Koishi

https://koishi.chat/zh-CN/
Admin
Koishi is a cross-platform, extensible, and high-performance chatbot framework with a rich plugin...
Tokens:113,096
Snippets:1,277
Trust Score:8.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### 配置 package.json 启动脚本

Source: https://koishi.chat/zh-CN/guide/develop/script

在 package.json 中定义 dev 和 start 脚本以简化应用启动流程。

```json
{
  "scripts": {
    "dev": "cross-env NODE_ENV=development koishi start -r esbuild-register -r yml-register",
    "start": "koishi start"
  }
}
```

--------------------------------

### bot.start()

Source: https://koishi.chat/zh-CN/api/core/bot

Starts the bot instance. This method is typically called automatically when the plugin is loaded.

```APIDOC
## bot.start()

### Description
Starts the bot instance. This method is typically called automatically when the plugin is loaded, so manual invocation is usually unnecessary.

### Returns
- **Promise<void>**
```

--------------------------------

### webhook.get(path, headers?)

Source: https://koishi.chat/zh-CN/plugins/develop/mock

Simulates a GET request to the Koishi server.

```APIDOC
## webhook.get(path, headers?)

### Description
Simulates an HTTP GET request to the specified path.

### Parameters
- **path** (string) - Required - The request path.
- **headers** (object) - Optional - The request headers.
```

--------------------------------

### 编写指令帮助信息

Source: https://koishi.chat/zh-CN/guide/basic/command

通过 desc 参数或 usage 和 example 方法为指令添加描述、用法说明和示例。

```typescript
ctx.command('echo <message:text> 输出收到的信息')
  .option('timeout', '-t <seconds> 设定延迟发送的时间')
```

```typescript
ctx.command('echo <message:text>', '输出收到的信息')
  .option('timeout', '-t <seconds> 设定延迟发送的时间')
  .usage('注意：参数请写在最前面，不然会被当成 message 的一部分！')
  .example('echo -t 300 Hello World  五分钟后发送 Hello World')
```

--------------------------------

### 使用 get 查询数据

Source: https://koishi.chat/zh-CN/guide/database

通过主键或对象条件获取表中的数据行，支持指定字段和查询表达式。

```typescript
// 获取 schedule 表中 id 为 1234 的数据行，返回一个数组
await ctx.database.get('schedule', 1234)

// 获取 schedule 表中 id 为 1234 或 5678 的数据行，返回一个数组
await ctx.database.get('schedule', [1234, 5678])
```

```typescript
// 返回的数组中每个元素只会包含 command, time 属性
await ctx.database.get('schedule', [1234], ['command', 'time'])
```

```typescript
// 获取名为 schedule 的表中 assignee 为 123456 或 456789 的数据行
await ctx.database.get('schedule', {
  assignee: ['123456', '456789'],
})
```

```typescript
// 获取名为 schedule 的表中 id 大于 2 但是小于等于 5 的数据行
await ctx.database.get('schedule', {
  id: { $gt: 2, $lte: 5 },
})
```

```typescript
import { $ } from 'koishi'

// 上述两个搜索条件的或运算
await ctx.database.get('schedule', (row) =>
  $.or(
    $.in(row.assignee, [
      '123456',
      '456789',
    ]),
    $.and(
      $.gt(row.id, 2),
      $.lte(row.id, 5),
    ),
  ),
)
```

--------------------------------

### bot.getMessageIter(channelId)

Source: https://koishi.chat/zh-CN/api/resources/message

Gets an asynchronous iterator for channel messages.

```APIDOC
## bot.getMessageIter(channelId)

### Description
Returns an asynchronous iterator to traverse messages in a channel.

### Parameters
- **channelId** (string) - Required - The ID of the channel.

### Returns
- **AsyncIterable<Message>**
```

--------------------------------

### 处理文件监听限制报错

Source: https://koishi.chat/zh-CN/guide/develop/script

当遇到文件监听数量限制错误时，通过修改系统配置增加监听上限。

```text
NOSPC: System limit for number of file watchers reached
```

```sh
echo fs.inotify.max_user_watches=524288 |
sudo tee -a /etc/sysctl.conf &&
sudo sysctl -p
```

--------------------------------

### ctx.http.head/get/delete(url, config)

Source: https://koishi.chat/zh-CN/plugins/develop/http

Sends HEAD, GET, or DELETE requests.

```APIDOC
## ctx.http.head(url, config)
## ctx.http.get(url, config)
## ctx.http.delete(url, config)

### Description
Sends a HEAD, GET, or DELETE request to the specified URL.

### Parameters
- **url** (string) - Required - The target URL.
- **config** (RequestConfig) - Optional - Configuration options for the request.

### Returns
- **Promise<any>** - A promise that resolves with the response data.
```

--------------------------------

### 配置安装时下载脚本

Source: https://koishi.chat/zh-CN/cookbook/design/storage

在 package.json 中添加 postinstall 脚本以在安装时下载依赖。

```json
{
  "scripts": {
    "postinstall": "node lib/download"
  }
}
```

--------------------------------

### 运行启动命令

Source: https://koishi.chat/zh-CN/guide/develop/script

在应用目录下执行 npm 命令以启动 Koishi 应用。

```bash
npm run start
```

```bash
npm run dev
```

--------------------------------

### Random.int(start?, end)

Source: https://koishi.chat/zh-CN/api/utils/random

Generates a random integer within a specified range.

```APIDOC
## Random.int(start?, end)

### Description
Generates a random integer in the range [start, end).

### Parameters
- **start** (number) - Optional - The lower bound, defaults to 0.
- **end** (number) - Required - The upper bound.

### Returns
- **number** - The generated random integer.
```

--------------------------------

### useConfig()

Source: https://koishi.chat/zh-CN/api/console/composition

获取用户设置。

```APIDOC
## useConfig()

### Description
获取用户设置。

### 返回值
- **Ref<any>** - 用户设置的响应式引用。
```

--------------------------------

### 克隆开发依赖

Source: https://koishi.chat/zh-CN/cookbook/practice/online

在本地测试前，需要克隆必要的 webui 和 ponyfills 仓库。

```bash
npm run clone koishijs/webui
npm run clone cordiverse/ponyfills
```

--------------------------------

### Random.real(start?, end)

Source: https://koishi.chat/zh-CN/api/utils/random

Generates a random real number within a specified range.

```APIDOC
## Random.real(start?, end)

### Description
Generates a random real number in the range [start, end).

### Parameters
- **start** (number) - Optional - The lower bound, defaults to 0.
- **end** (number) - Required - The upper bound.

### Returns
- **number** - The generated random real number.
```

--------------------------------

### 配置 npm 镜像源

Source: https://koishi.chat/zh-CN/guide/develop/publish

设置安装和发布插件时使用的 npm 镜像服务器地址。

```bash
yarn config set npmRegistryServer https://registry.npmmirror.com
yarn config set npmPublishRegistry https://registry.yarnpkg.com
```

--------------------------------

### ctx.settings(options)

Source: https://koishi.chat/zh-CN/api/console/context

Extends user settings in the console.

```APIDOC
## ctx.settings(options)

### Description
Extends user settings. If a component is provided, the schema is ignored.

### Parameters
- **options.type** (string) - Required - Category type.
- **options.title** (string) - Optional - Category name.
- **options.order** (number) - Optional - Sorting priority.
- **options.disabled** (() => boolean) - Optional - Function to determine if hidden.
- **options.schema** (Schema) - Optional - Configuration schema.
- **options.component** (Component) - Optional - Configuration component.
```

--------------------------------

### ctx.loader.fullReload()

Source: https://koishi.chat/zh-CN/api/service/loader

重启被守护的 Koishi 进程。

```APIDOC
## ctx.loader.fullReload()

### 描述
重启被守护的 Koishi 进程。
```

--------------------------------

### Schema.date and String roles

Source: https://koishi.chat/zh-CN/schema/basic/date

Examples of how to define date and time fields using Schema.date() and Schema.string() with specific roles.

```APIDOC
## Schema Definition

### Description
Defines date and time fields in a schema. `Schema.date()` returns a Date instance, while `Schema.string()` with roles returns formatted strings.

### Configuration Options
- **value** (Schema.date()) - Select date and time (returns Date object).
- **datetime** (Schema.string().role('datetime')) - Select date and time (returns string).
- **date** (Schema.string().role('date')) - Select date only (returns string).
- **time** (Schema.string().role('time')) - Select time only (returns string).

### Example
```typescript
export default Schema.object({
  value: Schema.date(),
  datetime: Schema.string().role('datetime'),
  date: Schema.string().role('date'),
  time: Schema.string().role('time'),
})
```
```

--------------------------------

### ctx.server[method](path, middleware)

Source: https://koishi.chat/zh-CN/plugins/develop/server

Registers a handler for specific HTTP methods on a given path. Supported methods include get, post, put, delete, patch, and all.

```APIDOC
## ctx.server[method](path, middleware)

### Description
Registers a Koa middleware to handle network requests on a specific path. Supported methods are get, post, put, delete, patch, and all.

### Parameters
- **method** (string) - Required - The HTTP method (must be lowercase).
- **path** (string | RegExp | (string | RegExp)[]) - Required - The path or paths to match.
- **middleware** (Function) - Required - The Koa middleware function to execute.
```

--------------------------------

### 使用环境变量隐藏配置项

Source: https://koishi.chat/zh-CN/cookbook/practice/online

利用 process.env.KOISHI_ENV 判断当前是否在浏览器环境中运行，从而隐藏不适用的配置项。

```typescript
export const Config = Schema.object({
  foo: Schema.string().default('bar')
    .hidden(process.env.KOISHI_ENV === 'browser'),
})
```

--------------------------------

### 发布插件命令

Source: https://koishi.chat/zh-CN/guide/develop/publish

用于发布插件的命令行工具，支持调试模式及指定镜像源。

```npm
npm run pub [...name]
```

```npm
npm run pub [...name] --debug
```

```yarn
yarn pub [...name] --debug
```

```text
No token found and can't prompt for login when running with --non-interactive.
```

```npm
npm run pub [...name] -- --registry https://registry.npmjs.org
```

--------------------------------

### 管理用户设置

Source: https://koishi.chat/zh-CN/guide/console/client

使用 ctx.settings 添加配置表单，并通过 useConfig 读取用户设置。

```typescript
ctx.settings({
  id: 'appearance',
  schema: Schema.object({
    wallpaper: Schema.object({
      image: Schema.string().description('要使用的背景图片。'),
      opacity: Schema.number().description('前景的不透明度。'),
    }).description('壁纸设置'),
  }),
})
```

```typescript
const config = useConfig()
config.value.wallpaper.image
```

--------------------------------

### 启动轻量版 Koishi 容器

Source: https://koishi.chat/zh-CN/manual/starter/docker

使用不包含 Chromium 的轻量版镜像启动 Koishi，适用于对镜像体积有要求的场景。

```bash
podman run -p 5140:5140 koishijs/koishi:latest-lite
```

--------------------------------

### ctx.before(event, listener, append?)

Source: https://koishi.chat/zh-CN/api/service/events

监听以 before- 开头的事件。

```APIDOC
## ctx.before(event, listener, append?)

### Description
监听一个以 before- 开头的事件。

### Parameters
- **event** (string) - Required - 事件名称
- **listener** (Function) - Required - 回调函数
- **append** (boolean) - Optional - 是否后置

### Returns
- **() => boolean** - 取消这个监听器
```

--------------------------------

### webhook.post(path, body, headers?)

Source: https://koishi.chat/zh-CN/plugins/develop/mock

Simulates a POST request to the Koishi server.

```APIDOC
## webhook.post(path, body, headers?)

### Description
Simulates an HTTP POST request to the specified path.

### Parameters
- **path** (string) - Required - The request path.
- **body** (string) - Required - The request body.
- **headers** (object) - Optional - The request headers.
```

--------------------------------

### ctx.middleware(middleware, prepend?)

Source: https://koishi.chat/zh-CN/api/service/events

在当前上下文中注册一个中间件。

```APIDOC
## ctx.middleware(middleware, prepend?)

### Description
当前上下文中注册一个中间件。

### Parameters
- **middleware** (Middleware) - Required - 要注册的中间件
- **prepend** (boolean) - Optional - 是否前置

### Returns
- **() => boolean** - 取消这个中间件
```

--------------------------------

### ctx.loader.keyFor(plugin)

Source: https://koishi.chat/zh-CN/api/service/loader

获取插件的短名称。

```APIDOC
## ctx.loader.keyFor(plugin)

### 描述
获取插件的短名称。

### 参数
- **plugin** (any) - 插件导出

### 返回值
- (string) - 插件的短名称
```

--------------------------------

### 在 package.json 中声明浏览器支持

Source: https://koishi.chat/zh-CN/cookbook/practice/online

在插件的 package.json 中添加 koishi.browser 字段以启用 k-on! 支持。

```json
{
  "koishi": {
    "browser": true
  }
}
```

--------------------------------

### 启动 k-on! 开发环境

Source: https://koishi.chat/zh-CN/cookbook/practice/online

进入 webui 目录并启动开发脚本以进行本地调试。

```bash
cd external/webui
npm run dev
```

--------------------------------

### ctx.on(event, listener, prepend?)

Source: https://koishi.chat/zh-CN/api/service/events

监听指定的事件。

```APIDOC
## ctx.on(event, listener, prepend?)

### Description
监听一个事件。

### Parameters
- **event** (string) - Required - 事件名称
- **listener** (Function) - Required - 回调函数
- **prepend** (boolean) - Optional - 是否前置

### Returns
- **() => boolean** - 取消这个监听器
```

--------------------------------

### Implementing Dynamic WhatsApp Adapter

Source: https://koishi.chat/zh-CN/guide/adapter/adapter

Adapter implementation that dynamically creates multiple bot instances upon startup.

```typescript
class WhatsAppAdapter<C extends Context> extends Adapter<C, WhatsAppBot<C>> {
  // 由适配器直接向外暴露配置项
  static schema = true
  // 这个适配器仍然是可重用的
  static reusable = true

  constructor(ctx: C, config: WhatsAppAdapter.Config) {
    super()

    // 初始化内部接口
    const http = ctx.http.extend({
      headers: { Authorization: `Bearer ${config.token}` },
    })
    const internal = new Internal(http)

    // 启动时创建机器人
    ctx.on('ready', async () => {
      const data = await internal.getPhoneNumbers()
      for (const item of data) {
        const bot = new WhatsAppBot(ctx, {
          phoneNumber: item.id,
        })
        bot.adapter = this
        bot.internal = internal
        this.bots.push(bot)
      }
    })
  }
}
```

--------------------------------

### ctx.permissions.provide(name, callback)

Source: https://koishi.chat/zh-CN/api/service/permissions

Provides a permission implementation via a callback.

```APIDOC
## ctx.permissions.provide(name, callback)

### Description
Registers a provider for the specified permission name.
```

--------------------------------

### 启动 Koishi 应用

Source: https://koishi.chat/zh-CN/manual/starter/boilerplate

在项目目录下启动已配置好的 Koishi 应用。

```npm
npm start
```

--------------------------------

### 注册控制台入口文件

Source: https://koishi.chat/zh-CN/guide/console/index.html

在插件的 apply 函数中通过 ctx.console.addEntry 注册前端资源路径。

```typescript
import { Context } from 'koishi'
// 此处需要导入 @koishijs/plugin-console 以获取类型
import {} from '@koishijs/plugin-console'
import { resolve } from 'path'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在已有插件逻辑的基础上，添加下面这段
  ctx.inject(['console'], (ctx) => {
    ctx.console.addEntry({
      dev: resolve(__dirname, '../client/index.ts'),
      prod: resolve(__dirname, '../dist'),
    })
  })
}
```

--------------------------------

### 配置插件依赖

Source: https://koishi.chat/zh-CN/guide/console/index.html

在 package.json 中添加控制台插件所需的 peerDependencies 和 devDependencies。

```json
{
  "peerDependencies": {
    "@koishijs/plugin-console": "^5.11.0"
  },
  "devDependencies": {
    "@koishijs/client": "^5.11.0"
  }
}
```

--------------------------------

### 配置插件市场与配置插件

Source: https://koishi.chat/zh-CN/about/upgrade

在 koishi.yml 配置文件中添加 config 插件以恢复插件配置页面功能。

```yaml
host: 127.0.0.1
port: 5140
maxPort: 5149
plugins:
  ...
    ...
    config: {}         # 加一行在这里，注意左侧缩进与 market 对齐
    market:
      ...
    ...
```

--------------------------------

### 配置环境变量与插件

Source: https://koishi.chat/zh-CN/cookbook/practice/bundle

在 koishi.yml 中引用环境变量，并在 .env.local 中定义隐私值以避免提交敏感信息。

```yaml
plugins:
  adapter-discord:
    $if: env.DISCORD_TOKEN
    token: ${{ env.DISCORD_TOKEN }}
```

```text
DISCORD_TOKEN = QwErTyUiOpAsDfGhJkLzXcVbNm
```

--------------------------------

### 创建新插件工作区

Source: https://koishi.chat/zh-CN/guide/develop/workspace

在应用目录下运行此命令以初始化一个新的插件工作区。

```npm
npm run setup [name] -- [-c] [-m] [-G]
```

--------------------------------

### 处理 Windows 脚本执行权限错误

Source: https://koishi.chat/zh-CN/guide/develop/setup

当遇到无法加载 yarn.ps1 的错误时，通过此命令修改执行策略以允许脚本运行。

```text
yarn：无法加载文件 yarn.ps1，因为在此系统上禁止运行脚本。
```

```sh
Set-ExecutionPolicy RemoteSigned
```

--------------------------------

### 更新插件版本号

Source: https://koishi.chat/zh-CN/guide/develop/publish

使用 npm 命令更新插件版本，支持自动递增或指定版本号。

```bash
npm run bump [...name] -- [-1|-2|-3|-p|-v <ver>] [-r]
```

--------------------------------

### Define Matrix registry configuration

Source: https://koishi.chat/zh-CN/plugins/adapter/matrix

Create a registry.yaml file to define the Application Service parameters for the Matrix homeserver.

```yaml
id: koishi                    # Application Service 的 ID
hs_token:                     # 填入任意内容，与配置文件相对应，请确保不会泄漏
as_token:                     # 填入任意内容，与配置文件相对应，请确保不会泄漏
url:                          # 你的机器人地址，通常是 {selfUrl}/matrix
sender_localpart: koishi      # 不能与机器人的 ID 相同
namespaces:
  users:
  - exclusive: true
    # 这里填入你的机器人的 userId
    # 如果需要同时接入多个 matrix 机器人，请使用正则表达式
    regex: '@koishi:matrix.example.com'
```

--------------------------------

### ctx.loader.replace(plugin1, plugin2)

Source: https://koishi.chat/zh-CN/api/service/loader

替换插件导出。

```APIDOC
## ctx.loader.replace(plugin1, plugin2)

### 描述
替换插件导出。

### 参数
- **plugin1** (any) - 原插件导出
- **plugin2** (any) - 新插件导出
```

--------------------------------

### <k-layout>

Source: https://koishi.chat/zh-CN/api/console/component

布局组件。

```APIDOC
## <k-layout>

### 属性 (Props)
- **menu** (string) - 可选，菜单标识符

### 插槽 (Slots)
- **header** - 标题栏
- **left** - 侧边栏
- **default** - 页面主体
```

--------------------------------

### 创建并运行入口文件

Source: https://koishi.chat/zh-CN/manual/starter/direct

配置 Koishi 应用实例并加载基础插件，使用 esbuild-register 运行 TypeScript 入口文件。

```typescript
import { Context } from 'koishi'
import server from '@koishijs/plugin-server'
import console from '@koishijs/plugin-console'
import * as sandbox from '@koishijs/plugin-sandbox'
import * as echo from '@koishijs/plugin-echo'

// 创建一个 Koishi 应用
const ctx = new Context()

// 启用上述插件
ctx.plugin(server, {
  port: 5140,
})                      // 提供后端服务
ctx.plugin(console)     // 提供控制台
ctx.plugin(sandbox)     // 提供调试沙盒
ctx.plugin(echo)        // 提供回声指令
```

```bash
node -r esbuild-register .
```

--------------------------------

### ctx.theme(options)

Source: https://koishi.chat/zh-CN/api/console/context

Defines a new console theme.

```APIDOC
## ctx.theme(options)

### Description
Defines a new theme for the console.

### Parameters
- **options.id** (string) - Required - Theme identifier (must end in -dark or -light).
- **options.name** (string) - Required - Theme name.
- **options.components** (Dict<Component>) - Optional - Layout components provided by the theme.
```

--------------------------------

### 实现 WebSocket 适配器

Source: https://koishi.chat/zh-CN/guide/adapter/adapter

通过继承 Adapter.WsClient 实现 WebSocket 通信，需实现 prepare 和 accept 方法。

```typescript
export class DiscordAdapter<C extends Context> extends Adapter.WsClient<C, DiscordBot<C>> {
  async prepare() {
    const { url } = await this.bot.internal.getGatewayBot()
    return this.bot.http.ws(url + '/?v=10&encoding=json')
  }

  accept() {
    this.socket.addEventListener('message', async ({ data }) => {
      const parsed = JSON.parse(data.toString())
      if (parsed.t === 'READY') {
        const user = decodeUser(parsed.d.user)
        Object.assign(this.bot, user)
        return this.bot.online()
      } else {
        const session = createSession(this.bot, parsed)
        if (session) this.dispatch(session)
      }
    })
  }
}
```

```typescript
const { url } = await this.bot.internal.getGatewayBot()
return this.bot.http.ws(url + '/?v=10&encoding=json')
```

```typescript
const user = decodeUser(parsed.d.user)
Object.assign(this.bot, user)
return this.bot.online()
```

```typescript
const session = createSession(this.bot, parsed)
if (session) this.dispatch(session)
```

--------------------------------

### 获取全局存储路径

Source: https://koishi.chat/zh-CN/cookbook/design/storage

使用 env-paths 库获取跨平台的全局路径，适用于存放可执行文件或下载的资源。

```typescript
import envPaths from 'env-paths'
import * as path from 'path'

const root = path.join(envPaths('some-binary').data, version)
```

--------------------------------

### .description()

Source: https://koishi.chat/zh-CN/schema/meta/description

The .description() method is used to set descriptive text for configuration items. When applied to properties, it appears below the name; when applied to objects, it acts as a sub-heading.

```APIDOC
## .description()

### Description
Sets the description text for a configuration item. Supports basic inline Markdown syntax.

### Usage
```typescript
export default Schema.object({
  foo: Schema.boolean().description('*斜体*的属性描述。'),
  bar: Schema.string().description('**粗体**的属性描述。'),
}).description('配置标题')
```
```

--------------------------------

### 控制台扩展的 package.json 配置

Source: https://koishi.chat/zh-CN/cookbook/practice/online

为控制台扩展插件配置必要的导出字段和公共资源目录。

```json
{
  "main": "lib/index.cjs",
  "typings": "lib/index.d.ts",
  "exports": {
    ".": {
      "import": "./lib/index.mjs",
      "require": "./lib/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "koishi": {
    "browser": true,
    "public": [
      "dist"
    ]
  }
}
```

--------------------------------

### ctx.plugin(plugin, options?)

Source: https://koishi.chat/zh-CN/api/service/registry

在当前上下文中安装一个插件。

```APIDOC
## ctx.plugin(plugin, options?)

### Description
在当前上下文中安装一个插件。

### Parameters
- **plugin** (Plugin) - Required - 要安装的插件
- **options** (any) - Optional - 要传入插件的参数

### Returns
- **Fork** - 返回一个 Fork 对象
```

--------------------------------

### 基于上下文的插件化实现

Source: https://koishi.chat/zh-CN/cookbook/design/disposable

通过 Context 对象管理插件生命周期，利用 ctx.on('restore') 自动处理资源回收。

```typescript
function serve(ctx: Context, config: Config) {
  const server = createServer().listen(config.port)
  ctx.on('restore', () => server.close())
}

ctx.plugin(serve, { port: 80 })
```

--------------------------------

### ctx.loader.reload(parent, key, config)

Source: https://koishi.chat/zh-CN/api/service/loader

启用或重载一个插件。

```APIDOC
## ctx.loader.reload(parent, key, config)

### 描述
启用一个插件。如果 key 已经存在于父级上下文中，则会重载该插件实例；如果 key 不存在，则会创建一个新的插件实例。

### 参数
- **parent** (Context) - 父级上下文
- **key** (string) - 插件的短名称
- **config** (object) - 插件配置

### 返回值
- (Promise<ForkScope>) - 插件的 ForkScope
```

--------------------------------

### ctx.once(event, listener, prepend?)

Source: https://koishi.chat/zh-CN/api/service/events

监听事件，且确保回调函数只执行一次。

```APIDOC
## ctx.once(event, listener, prepend?)

### Description
监听一个事件，且确保回调函数只会被执行一次。

### Parameters
- **event** (string) - Required - 事件名称
- **listener** (Function) - Required - 回调函数
- **prepend** (boolean) - Optional - 是否前置

### Returns
- **() => boolean** - 取消这个监听器
```

--------------------------------

### 配置延时参数

Source: https://koishi.chat/zh-CN/guide/basic/advanced

通过配置文件调整消息发送的延时行为。

```yaml
delay:
  # 消息里每有一个字符就等待 0.02s
  character: 20
  # 每条消息至少等待 0.5s
  message: 500
```

--------------------------------

### 复杂配置翻译文件

Source: https://koishi.chat/zh-CN/guide/i18n/translation

对应复杂类型的翻译文件内容。

```yaml
# 对应的翻译文件
foo:
  qux: 这是一个配置项。
bar: 这是另一个配置项。
baz: 是再一个配置项。
```

--------------------------------

### 克隆插件进行二次开发

Source: https://koishi.chat/zh-CN/guide/develop/workspace

将远程仓库的插件克隆到本地 external 目录进行调试。

```npm
npm run clone koishijs/koishi-plugin-forward
```

--------------------------------

### ctx.permissions.inherit(a, b)

Source: https://koishi.chat/zh-CN/api/service/permissions

Sets up permission inheritance between two permissions.

```APIDOC
## ctx.permissions.inherit(a, b)

### Description
Configures permission 'a' to inherit from permission 'b'.
```

--------------------------------

### Exporting WhatsApp Adapter

Source: https://koishi.chat/zh-CN/guide/adapter/adapter

Entry point file for the WhatsApp adapter.

```typescript
import WhatsAppAdapter from './adapter'
export default WhatsAppAdapter
```

--------------------------------

### 构建插件源代码

Source: https://koishi.chat/zh-CN/guide/develop/workspace

将插件源代码编译为生产环境可用的 lib 或 dist 文件。

```npm
npm run build [...name]
```

--------------------------------

### REPL 适配器 Adapter 实现

Source: https://koishi.chat/zh-CN/guide/adapter/index.html

实现 Adapter 类以处理消息接收逻辑，通过 readline 接口监听输入并分发会话。

```typescript
import { Adapter, Context } from 'koishi'
import { createInterface } from 'readline'
import ReplBot from './bot'

export default class ReplAdapter extends Adapter<ReplBot> {
  rl = createInterface({
    input: process.stdin,
  })

  async start(bot: ReplBot) {
    bot.online()
    this.rl.on('line', (line) => {
      const session = bot.session()
      session.type = 'message'
      session.userId = 'repl'
      session.channelId = 'repl'
      session.isDirect = true
      session.content = line
      bot.dispatch(session)
    })
  }

  async stop(bot: ReplBot) {
    this.rl.close()
  }
}
```

--------------------------------

### 初始化 Koishi 项目

Source: https://koishi.chat/zh-CN/guide/develop/setup

使用 npm 初始化工具创建新的 Koishi 项目。

```npm
npm init koishi@latest
```

--------------------------------

### 初始化整合包仓库

Source: https://koishi.chat/zh-CN/cookbook/practice/bundle

在模板项目根目录下执行此命令以将其初始化为 Git 仓库。

```sh
git init
```

--------------------------------

### 插件目录结构示例

Source: https://koishi.chat/zh-CN/guide/develop/publish

展示了插件在项目中的位置，强调应修改插件目录下的 package.json 而非应用根目录的。

```diff
root
├── plugins
│   └── example
│       ├── src
│       │   └── index.ts
│       └── package.json        # 你应该修改这里
├── koishi.yml
└── package.json                # 而不是这里
```

--------------------------------

### ctx.page(options)

Source: https://koishi.chat/zh-CN/api/console/context

Registers a new page in the console.

```APIDOC
## ctx.page(options)

### Description
Registers a page with routing and component configuration.

### Parameters
- **options.id** (string) - Optional - Page identifier.
- **options.path** (string) - Required - Page route.
- **options.name** (MaybeRefOrGetter<string>) - Required - Page name.
- **options.desc** (MaybeRefOrGetter<string>) - Optional - Page description.
- **options.icon** (MaybeRefOrGetter<string>) - Optional - Page icon.
- **options.position** ('top' | 'bottom') - Optional - Icon position in the activity bar.
- **options.order** (number) - Optional - Sorting priority.
- **options.disabled** (() => boolean) - Optional - Function to determine if the page is hidden.
- **options.component** (Component) - Required - The page component.
```

--------------------------------

### Telegram Adapter Directory Structure

Source: https://koishi.chat/zh-CN/guide/adapter/adapter

Recommended file structure for a multi-protocol adapter implementation.

```text
adapter-telegram
├── src
│   ├── bot.ts
│   ├── index.ts
│   ├── adapter.ts
│   ├── polling.ts
│   └── server.ts
└── package.json
```

--------------------------------

### mock.client(userId, channelId?)

Source: https://koishi.chat/zh-CN/plugins/develop/mock

Creates a client instance to simulate interactions within a specific context.

```APIDOC
## mock.client(userId, channelId?)

### Description
Creates a client instance for simulating messages sent to a specific context.

### Parameters
- **userId** (string) - Required - The user ID.
- **channelId** (string) - Optional - The channel ID.

### Returns
- **Client** - A client instance.
```

--------------------------------

### 实现上下文菜单

Source: https://koishi.chat/zh-CN/guide/console/client

定义上下文菜单并在组件中使用 useMenu 触发。

```typescript
ctx.menu('entry', [{
  id: '.rename',
  label: '重命名',
}, {
  id: '.remove',
  label: '删除',
}])
```

```vue
<template>
  <!-- 这里显示了文件列表 -->
  <div v-for="entry in entries">
    <!-- 右击任意文件名会呼出上述菜单 -->
    <div @contextmenu.stop="trigger($event, entry)">{{ entry.filename }}</div>
  </div>
</template>

<script lang="ts" setup>
import { useContext, useMenu } from '@koishijs/client'

const ctx = useContext()
const trigger = useMenu('entry')

// 实现菜单动作
ctx.action('entry.remove', {
  action: ({ entry }) => send('explorer/remove', entry.filename),
})
</script>
```

--------------------------------

### 创建测试目录结构

Source: https://koishi.chat/zh-CN/cookbook/practice/testing

在插件目录下创建 tests 文件夹及测试文件。

```text
└── example
    ├── src
    │   └── index.ts
+   ├── tests
+   │   └── index.spec.ts
    └── package.json
```

--------------------------------

### Implementing TelegramBot Entry Point

Source: https://koishi.chat/zh-CN/guide/adapter/adapter

Bot class that selects the appropriate adapter based on the provided configuration protocol.

```typescript
class TelegramBot<C extends Context> extends Bot<C, TelegramBot.Config> {
  constructor(ctx: C, config: TelegramBot.Config) {
    super(ctx, config)
    if (config.protocol === 'server') {
      ctx.plugin(HttpServer, this)
    } else if (config.protocol === 'polling') {
      ctx.plugin(HttpPolling, this)
    }
  }
}

namespace TelegramBot {
  export type Config = ServerAdapter.Options | PollingAdapter.Options

  export const Config: Schema<Config> = Schema.intersect([
    Schema.object({
      protocol: Schema.union(['server', 'polling']).required(),
    }),
    Schema.union([
      HttpServer.Options,
      HttpPolling.Options,
    ]),
  ])
}
```

--------------------------------

### 使用 create 插入数据

Source: https://koishi.chat/zh-CN/guide/database

向指定表中插入一行数据，并返回包含自动填充属性的完整数据行。

```typescript
// 向 schedule 表中添加一行数据，data 是要添加的数据行
// 返回值是添加的行的完整数据 (包括自动填充的 id 和默认属性等)
await ctx.database.create('schedule', data)
```

--------------------------------

### Configure package.json for Type-Only Dependencies

Source: https://koishi.chat/zh-CN/guide/plugin/service

When only importing types, declare the service in the koishi configuration and add the package to devDependencies.

```json
{
  "service": {
    "required": ["puppeteer"]
  },
  "devDependencies": {
    "koishi-plugin-puppeteer": "^2.0.0"
  }
}
```

--------------------------------

### 连接查询

Source: https://koishi.chat/zh-CN/guide/database/selection

使用 join() 连接多个表，支持指定别名。

```typescript
// 返回的数据包含 foo, bar 两个属性
ctx.database
  .join(['foo', 'bar'], (foo, bar) => $.eq(foo.id, bar.id))
  .orderBy('foo.id') // orderBy 可以使用 'a.b' 的形式
  .execute()
```

```typescript
// 返回的数据包含 t1, t2 两个属性
ctx.database
  .join({ t1: 'foo', t2: 'bar' }, row => $.eq(row.t1.id, row.t2.id))
  .orderBy('t1.id') // orderBy 可以使用 'a.b' 的形式
  .execute()
```

--------------------------------

### 登录 npm 账号

Source: https://koishi.chat/zh-CN/guide/develop/setup

在命令行中登录 npm 账号，以便后续发布插件。

```sh
npm login --registry=https://registry.npmjs.org
```

--------------------------------

### 字段映射

Source: https://koishi.chat/zh-CN/guide/database/selection

使用 project() 方法对查询结果进行字段映射和计算。

```typescript
// 返回的数组元素将只含有 a, b 属性
ctx.database
  .select('foo')
  .project({
    a: row => $.add(row.id, 1),         // a = id + 1
    b: row => $.multiply(row.id, 2),    // b = id * 2
  })
  .execute()
```

--------------------------------

### 配置聊天平台适配器

Source: https://koishi.chat/zh-CN/manual/starter/direct

安装并配置 Satori 和 Discord 适配器插件，实现与真实聊天平台的连接。

```bash
# 以 Satori 和 Discord 适配器为例
npm i @koishijs/plugin-adapter-satori \
      @koishijs/plugin-adapter-discord
```

```typescript
import satori from '@koishijs/plugin-adapter-satori'
import discord from '@koishijs/plugin-adapter-discord'

// 使用 Satori 适配器的机器人
ctx.plugin(satori, {
  endpoint: 'http://127.0.0.1:5500',
})

// 使用 Satori 适配器的另一个机器人，可以有不同的通信方式
ctx.plugin(satori, {
  endpoint: 'http://127.0.0.1:5501',
})

// 使用 Discord 适配器的机器人
// 别忘了在使用之前，先安装相应的插件和完成准备工作
ctx.plugin(discord, {
  token: 'QwErTyUiOpAsDfGhJkLzXcVbNm',
})
```

--------------------------------

### 整合包目录结构示例

Source: https://koishi.chat/zh-CN/cookbook/practice/bundle

展示了在 packages 目录下添加私有插件的目录结构。

```diff
root
├── external
│   └── foo                     # 公开插件
│       ├── src
│       │   └── index.ts
│       └── package.json
├── packages
│   └── bar                     # 私有插件
│       ├── src
│       │   └── index.ts
│       └── package.json
├── koishi.yml
└── package.json
```
Tokens:
Raw