@jsbot-tellus/core 2.0.3 → 2.2.0

package/docs/configuration.md

@@ -2,14 +2,13 @@
 
 ## 路径和优先级
 
-| 项目     | CLI            | 环境变量         | 默认值              |
-| -------- | -------------- | ---------------- | ------------------- |
-| 配置文件 | `--config`     | `BOT_CONFIG`     | `./bot.config.json` |
-| 数据目录 | `--data-dir`   | `BOT_DATA_DIR`   | `./data`            |
-| 日志级别 | `--log-level`  | `BOT_LOG_LEVEL`  | `info`              |
-| 插件目录 | `--plugin-dir` | `BOT_PLUGIN_DIR` | 无                  |
+| 项目     | CLI           | 环境变量        | 默认值              |
+| -------- | ------------- | --------------- | ------------------- |
+| 配置文件 | `--config`    | `BOT_CONFIG`    | `./bot.config.json` |
+| 数据目录 | `--data-dir`  | `BOT_DATA_DIR`  | `./data`            |
+| 日志级别 | `--log-level` | `BOT_LOG_LEVEL` | `info`              |
 
-`--plugin-dir` 可以重复；`BOT_PLUGIN_DIR` 使用逗号分隔多个目录。空字符串会被视为未设置。路径最终按 `process.cwd()` 解析。
+本地插件目录固定为 `./plugins`，不提供 CLI 或环境变量覆盖；每个插件从 `./plugins/<id>/dist` 加载，缺失时会在启动阶段尝试自动构建，相对路径按 `process.cwd()` 解析。
 
 ## 完整示例
 
@@ -68,7 +67,6 @@ npm 包会在宿主进程中执行，拥有与内核相同的文件系统、环
 {
     "installer": {
         "enabled": true,
-        "dir": "data/plugins",
         "registry": "https://registry.npmjs.org/",
         "allowedPackages": ["@scope/*", "another-plugin"],
         "allowScripts": false,
@@ -80,19 +78,20 @@ npm 包会在宿主进程中执行，拥有与内核相同的文件系统、环
 | 字段              | 默认值                        | 说明                                                               |
 | ----------------- | ----------------------------- | ------------------------------------------------------------------ |
 | `enabled`         | `false`                       | 为 `false` 时禁用安装、卸载和更新；列表仍可用（仍要求 SuperAdmin） |
-| `dir`             | `<data-dir>/plugins`          | 安装目录，相对路径按 `process.cwd()` 解析                          |
 | `registry`        | `https://registry.npmjs.org/` | npm registry，可换成镜像（如 npmmirror）                           |
 | `allowedPackages` | `[]`                          | 允许安装的包；空表示不限制，支持精确名和 `@scope/*`                |
 | `allowScripts`    | `false`                       | 为 `false` 时 npm 操作带 `--ignore-scripts`                        |
 | `timeoutMs`       | `120000`                      | 单次 npm/校验操作的超时，最大 600000                               |
 
-安装目录由内核维护，包含 `package.json`、`package-lock.json` 和 `.jsbot-installed.json`。不要手动修改；安装失败时内核会恢复安装前的 manifest、lock 和安装状态并重装依赖。安装状态损坏会明确报错，不会静默清空。
+插件根目录固定为 `plugins/`，不能通过配置修改；旧配置中的 `installer.dir` 已被移除，继续保留会导致配置校验失败。安装器把包直接放到 `plugins/<插件id>/`，和本地插件使用同一个加载器；首次安装时，一个包导出多个插件会使用包名作为目录（例如 `@scope/bundle` 对应 `plugins/@scope__bundle/`）。插件自身在 `plugins/<目录>/dist`，运行时依赖在 `plugins/<目录>/node_modules`，不会放进共享的 `node_modules`。
 
-安装器会在安装目录创建 `node_modules/@jsbot-tellus/core` 链接，指向当前内核包。`@jsbot-tellus/core` 的入口是 `dist/core/index.js`，所以在线安装和加载已安装插件都需要先执行 `npm run build`；直接从 TypeScript 源码运行（`tsx`）时不要依赖安装器。
+`plugins/.jsbot-installed.json` 保存安装状态和包名到目录的映射，由内核维护，不要手动修改。安装、更新会先在临时目录完成下载和校验，再原子替换目标目录；失败时保留原目录。状态文件损坏会明确报错，不会静默清空。如果目标目录已存在但没有安装记录，安装会被拒绝，避免覆盖手动放在 `plugins/` 的本地插件。
+
+安装器会在每个已安装插件目录创建 `node_modules/@jsbot-tellus/core` 链接，指向当前内核包。`@jsbot-tellus/core` 的入口是 `dist/core/index.js`，所以在线安装和加载已安装插件都需要先执行 `npm run build`；直接从 TypeScript 源码运行（`tsx`）时不要依赖安装器。
 
 安装只接受 npm registry 包。以下来源会被拒绝：git/github 地址、`file:`、`http(s):`、`workspace:`、`link:`、本地路径和 semver 范围（`^`、`~`、`1.x`）。版本部分只接受精确版本或 dist-tag。
 
-安装、更新、卸载成功后会重建运行时并重新加载已安装插件，不需要手动重启，进程本身不会退出。卸载时如果配置里仍有对应插件 ID，会给出警告并跳过自动重启；如果其它已安装包依赖被卸载的插件 ID，默认拒绝卸载，需要确认后使用 `/plugin remove <目标> --force`。安装和更新会检查完整依赖图，拒绝自依赖、循环依赖和缺失依赖。启动时加载顺序是：内置插件 → `--plugin-dir` 外部插件 → 已安装插件；出现重复插件 ID 时保留先加载的插件并记录警告。
+安装、更新、卸载成功后会自动重建运行时并重新加载插件，不需要手动重启，进程本身不会退出。卸载时如果配置里仍有对应插件 ID，会给出警告并跳过自动重启；如果其它已安装包依赖被卸载的插件 ID，默认拒绝卸载，需要确认后使用 `/plugin remove <目标> --force`。安装和更新会检查完整依赖图，拒绝自依赖、循环依赖和缺失依赖。启动时把内置插件和 `plugins/` 中的全部目录一起加载；出现重复插件 ID 时保留先加载的插件并记录警告。
 
 ## 插件公共信封
 
@@ -141,19 +140,18 @@ npm 包会在宿主进程中执行，拥有与内核相同的文件系统、环
 ```
 
 - `/utter <文本>`：Admin 权限，发送自动转义的纯文本（CQ 码不会被解析）。
-- `/utter.raw <CQ 消息>`：SuperAdmin 权限，发送原始 CQ 字符串。
+- `/utter raw <CQ 消息>`：SuperAdmin 权限，发送原始 CQ 字符串。
 
-## 外部与本地插件配置
+## 插件目录配置
 
-`plugins` 中出现的插件 ID 必须对应已加载的插件，否则启动失败。外部插件通过 `--plugin-dir` 或 `BOT_PLUGIN_DIR` 加载：
+`plugins` 中出现的插件 ID 必须对应已加载的插件，否则启动失败。本地插件和在线安装的插件都固定从 `plugins/<目录>/dist` 自动加载：
 
 ```bash
-node dist/app.js \
-    --plugin-dir plugins/poke/dist \
-    --plugin-dir plugins/llm/dist
+npm run build
+node dist/app.js
 ```
 
-通过 `/plugin install` 安装的包会自动从 `<data-dir>/plugins` 加载，不需要 `--plugin-dir`。安装目录、registry 和允许列表见[插件安装器](#插件安装器)。
+没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，启动时会先自动执行 `npm run build` 再加载；没有 `build` 脚本、缺少 `node_modules` 或构建失败时会记录警告并跳过。通过 `/plugin install` 安装的包会直接出现在 `plugins/<插件id>/`，与手动放在 `plugins/` 的本地插件没有区别；安装器管理的包应自带 `dist`，加载器不会为它们自动构建。安装状态、registry 和允许列表见[插件安装器](#插件安装器)。
 
 插件自己的配置字段由 `manifest.configSchema` 校验。例如一个 `demo` 插件：
 
@@ -178,12 +176,10 @@ npm install --prefix plugins/poke
 npm install --prefix plugins/llm
 npm run build:local
 
-npm run dev -- \
-    --plugin-dir plugins/poke/dist \
-    --plugin-dir plugins/llm/dist
+npm run dev
 ```
 
-应用会跳过与内置插件同 ID 的外部插件。
+本地插件从 `plugins/<id>/dist` 自动加载；缺少 `dist` 时会先尝试构建。应用会跳过与内置插件同 ID 的本地插件。
 
 ## 错误处理
 

package/docs/feature-parity.md

@@ -11,14 +11,14 @@
 | 群开关        | `PluginGate`               | `enabled/private/groups`                       |
 | 消息发送      | `core/messaging/sender.ts` | reply、长消息 forward                          |
 | 插件 KV       | `core/plugin/kv.ts`        | 按插件 ID 隔离的 SQLite KV                     |
-| 管理发送      | `src/plugins/admin`        | `/utter`、`/utter.raw`                         |
+| 管理发送      | `src/plugins/admin`        | `/utter`、`/utter raw`                         |
 | 角色查询/帮助 | `src/plugins/core`         | `/role`、`/help`、`/status`                    |
 | 内置插件      | `src/plugins/*`            | 普通源码，随内核编译                           |
 | 在线安装      | `core/plugin/installer.ts` | `/plugin install/list/remove/update`，重启生效 |
 
 ## 本地插件
 
-以下插件保留在本地，但不进入仓库，通过 `--plugin-dir` 加载：
+以下插件保留在本地，但不进入仓库，从 `plugins/<id>/dist` 自动加载（缺少 `dist` 时会先尝试自动构建）：
 
 | 能力 | 位置           | 说明                                         |
 | ---- | -------------- | -------------------------------------------- |
@@ -42,6 +42,7 @@
 ## 验收场景
 
 - 只注册一个 SDK middleware。
+- 命令支持多级路径，按最长路径匹配；组根未提供 handler 时自动生成用法提示。
 - 命令命中后不会进入普通消息 handler。
 - 禁用命令不会穿透到普通消息 handler。
 - 权限不足不执行 handler，并返回通用提示。
@@ -49,8 +50,7 @@
 - 插件 setup/start 失败可以回滚。
 - 长消息转 forward，短消息默认引用回复。
 - 配置错误包含路径，未知插件 ID 启动失败。
-- 外部插件目录可以加载并执行。
-- 本地插件可以通过 `--plugin-dir` 加载。
+- 本地插件可以从 `plugins/<id>/dist` 自动加载并执行；缺少 `dist` 且带有 `build` 脚本时会先自动构建。
 - 已安装的 npm 插件包可以在自动重启后加载，安装失败会回滚。
 - 非 SuperAdmin 不能使用 `/plugin` 的任何子命令，包括 `help` 和 `list`。
 - `npm run build` 后 `node dist/app.js` 可用。

package/docs/migration.md

@@ -8,9 +8,11 @@
 
 - 安装本地依赖：`npm install --prefix plugins/poke`、`npm install --prefix plugins/llm`
 - 构建本地插件：`npm run build:local`
-- 启动时加载：`--plugin-dir plugins/poke/dist --plugin-dir plugins/llm/dist`
+- 启动时加载：应用会自动扫描 `plugins/<id>/dist`，不需要路径参数
 
-`--plugin-dir` 可以重复，应用会跳过与内置插件同 ID 的外部插件。没有加载的插件不能出现在 `plugins` 配置中，否则会因未知插件 ID 启动失败。
+应用会跳过与内置插件同 ID 的本地插件。没有加载的插件不能出现在 `plugins` 配置中，否则会因未知插件 ID 启动失败。
+
+管理命令方面，`/utter.raw` 已迁移为 `/utter raw` 指令组子命令。
 
 发布到 npm registry 的插件也可以由 SuperAdmin 在聊天中安装：
 
@@ -21,7 +23,7 @@
 /plugin remove @scope/plugin
 ```
 
-安装目录默认是 `<data-dir>/plugins`，安装、更新、卸载成功后会自动重启运行时。它不会修改 `plugins` 配置，因此卸载后需要手动删除对应的 `plugins.<id>`；存在残留配置时会跳过自动重启并提示手动处理。详见[插件 API](plugin-api.md#通过-npm-发布与安装)和[配置](configuration.md#插件安装器)。
+包会直接安装到 `plugins/<插件id>/`，和本地插件使用同一个目录、同一个加载器；安装、更新、卸载成功后会自动重启运行时。它不会修改 `plugins` 配置，因此卸载后需要手动删除对应的 `plugins.<id>`；存在残留配置时会跳过自动重启并提示手动处理。旧版本的 `<data-dir>/plugins` 安装目录不再读取，升级后需要用 `/plugin install` 重新安装在线插件；旧配置中的 `installer.dir` 也已移除，继续保留会导致配置校验失败，需要删除该字段。详见[插件 API](plugin-api.md#通过-npm-发布与安装)和[配置](configuration.md#插件安装器)。
 
 ## 迁移步骤
 
@@ -63,21 +65,19 @@
     npm install --prefix plugins/poke
     npm install --prefix plugins/llm
     npm run build:local
-    node dist/app.js \
-        --plugin-dir plugins/poke/dist \
-        --plugin-dir plugins/llm/dist
+    node dist/app.js
     ```
 
 6. 验证 `core`、`admin` 和已加载的本地插件。确认后再切换生产进程和反向代理配置。
 
 ## 目录对照
 
-| 项目            | 迁移前                                       | 迁移后                               |
-| --------------- | -------------------------------------------- | ------------------------------------ |
-| 配置文件        | `bot.config.json` → `bot.config.legacy.json` | 新建 `bot.config.json`               |
-| 数据目录        | `data/` → `data.legacy/`                     | 新建 `data/`                         |
-| 旧插件目录      | 保留原样                                     | 内置 `core`/`admin` + `--plugin-dir` |
-| 旧 KV / Session | 保留在 `data.legacy/bot.db`                  | `data/bot.db`                        |
+| 项目            | 迁移前                                       | 迁移后                           |
+| --------------- | -------------------------------------------- | -------------------------------- |
+| 配置文件        | `bot.config.json` → `bot.config.legacy.json` | 新建 `bot.config.json`           |
+| 数据目录        | `data/` → `data.legacy/`                     | 新建 `data/`                     |
+| 旧插件目录      | 保留原样                                     | 内置 `core`/`admin` + `plugins/` |
+| 旧 KV / Session | 保留在 `data.legacy/bot.db`                  | `data/bot.db`                    |
 
 新版不会读取 `bot.config.legacy.json` 或 `data.legacy/`。备份文件可以保留，方便回退。
 
@@ -89,7 +89,7 @@
 - 本地 `llm` 插件按 session 存储上下文，不再整份 KV 重写。
 - 旧 `auth`、`echo`、`like-me` 不重建；权限由 `core` + `roles` 负责，发送文本由 `admin` 负责。
 - 不支持热加载、插件市场界面和旧装饰器；npm 插件安装成功后会重建运行时。
-- 仓库只跟踪 `core`、`admin`；其它插件通过本地目录或外部目录加载。
+- 仓库只跟踪 `core`、`admin`；其它插件从 `plugins/` 加载，在线安装的插件也在这里。
 
 ## 回滚
 

package/docs/plugin-api.md

@@ -176,6 +176,7 @@ const result = await ctx.api.call('get_group_list')
 const role = ctx.core.roles.roleOf(userId)
 const allowed = ctx.core.roles.can(role, 'Admin')
 const commands = ctx.core.commands.list()
+const visibleCommands = ctx.core.commands.list(event)
 const plugins = ctx.core.plugins.list()
 const uptime = ctx.core.uptime()
 
@@ -183,14 +184,16 @@ const installed = await ctx.core.installer.list()
 ctx.core.restart()
 ```
 
-核心服务由内核注入，适合帮助、状态类插件。`ctx.core.installer` 额外提供 `install` / `remove` / `update` / `list`；它不会检查调用者角色，权限判断由调用方负责（`admin` 的 `/plugin` 命令要求 SuperAdmin）。安装器默认关闭，必须在配置中显式启用。`ctx.core.restart()` 请求应用重建运行时并重新加载插件；第三方插件不应把这些方法暴露给普通用户。
+核心服务由内核注入，适合帮助、状态类插件。`ctx.core.commands.list(event)` 会按当前会话的 `enabled`、`groups`、`private` gating 过滤命令；不传 `event` 时返回全部命令。`ctx.core.installer` 额外提供 `install` / `remove` / `update` / `list`；它不会检查调用者角色，权限判断由调用方负责（`admin` 的 `/plugin` 命令要求 SuperAdmin）。安装器默认关闭，必须在配置中显式启用。`ctx.core.restart()` 请求应用重建运行时并重新加载插件；第三方插件不应把这些方法暴露给普通用户。
 
 安装的插件与内置插件运行在同一个宿主进程中，可访问文件系统、网络和 `process.env`，属于完全可信代码，不是安全沙箱。
 
-自动重启会在同一个 Node.js 进程内重建 Kernel，不会清空 Node 的 ESM 模块缓存。安装包的入口文件会附加查询参数来绕过缓存，但入口相对导入的辅助模块仍可能复用旧代码；通过 `--plugin-dir` 加载的本地插件也不会被缓存刷新。更新多文件插件包后，请完整退出并重新启动进程。
+自动重启会在同一个 Node.js 进程内重建 Kernel，不会清空 Node 的 ESM 模块缓存。安装包的入口文件会附加查询参数来绕过缓存，但入口相对导入的辅助模块仍可能复用旧代码；通过 `plugins/` 加载的本地插件也不会被缓存刷新。更新多文件插件包后，请完整退出并重新启动进程。
 
 ## 命令
 
+### 普通命令
+
 ```ts
 ctx.commands.register(
     {
@@ -206,21 +209,151 @@ ctx.commands.register(
 )
 ```
 
-| 字段          | 默认值   | 说明                          |
-| ------------- | -------- | ----------------------------- |
-| `name`        | 必填     | 主命令名，匹配时大小写不敏感  |
-| `aliases`     | `[]`     | 别名                          |
-| `prefixes`    | `['/']`  | 前缀；空字符串表示无前缀      |
-| `permission`  | `'User'` | `User`、`Admin`、`SuperAdmin` |
-| `description` | 无       | `/help` 中展示                |
+| 字段          | 默认值   | 说明                                         |
+| ------------- | -------- | -------------------------------------------- |
+| `name`        | 必填     | 主命令名，匹配时大小写不敏感                 |
+| `aliases`     | `[]`     | 别名                                         |
+| `prefixes`    | `['/']`  | 前缀；空字符串表示无前缀                     |
+| `permission`  | `'User'` | `User`、`Admin`、`SuperAdmin`                |
+| `description` | 无       | `/help` 中展示                               |
+| `params`      | 无       | Koishi 风格参数声明；省略时 handler 行为不变 |
+
+`name` 和 `aliases` 的每一项只能是一个路径段；多级命令请使用 `commands.group()`。
+
+### 参数
+
+`params` 用字符串声明位置参数，解析结果从 handler 的第四个参数开始按位置传入：
+
+```ts
+ctx.commands.register(
+    {
+        name: 'ask',
+        description: '向模型提问',
+        params: '<question:string> [count:integer=1]',
+    },
+    async (_event, context, _match, question, count) => {
+        // question: string, count: number
+        await context.send(`问题：${question}（${count} 次）`)
+    }
+)
+```
+
+声明语法：
+
+| 写法                 | 说明                                     |
+| -------------------- | ---------------------------------------- |
+| `<arg>`              | 必填字符串参数                           |
+| `[arg]`              | 可选字符串参数                           |
+| `<arg:type>`         | 指定类型的必填参数                       |
+| `[arg:type=default]` | 可选参数及默认值                         |
+| `<arg:text>`         | 文本参数，消费全部剩余输入，必须放在最后 |
+| `[...rest]`          | 变长参数，每个剩余 token 作为一个字符串  |
 
-命令命中后会立即 `stopPropagation()`。同一前缀下的命令或别名冲突会在注册时抛错。
+内置类型：
+
+- `string`：默认类型，单个 token。
+- `text`：消费全部剩余输入，保留空格；usage 显示为 `<arg...>`。
+- `number`：有限数字，包括小数。
+- `integer`：整数。
+- `boolean`：`true/false`、`1/0`、`yes/no`、`y/n`、`on/off`，大小写不敏感。
+- `[...rest]`：把剩余 token 依次收集为字符串；只能放在最后，且没有必填形式。
+
+固定参数可以用双引号或单引号包裹，例如 `/ask "hello world" 2` 会把 `hello world` 作为一个 token；引号内的反斜杠用于转义。
+
+解析规则：
+
+- `match.args` 和 `match.rest` 保持原始内容，不会被参数解析结果替换。
+- 声明槽位填完后，多余 token 会被忽略并记录 debug 日志，不会报错。`text` 和 `rest` 会消费全部剩余输入，因此不存在多余 token。
+- 必填参数缺失、已声明槽位类型错误或引号未闭合时，Router 会自动回复错误和用法，handler 不会执行。
+- usage 会自动生成，并显示在 `/help` 和指令组根命令的用法提示中。
+- 必填参数不能出现在可选参数之后；参数名不能重复；`text` 和变长参数必须放在最后；必填参数不能声明默认值。
+- 当 `params` 是字符串字面量时，handler 从第四个参数开始的位置参数类型会自动推导。例如 `<question:string> [count:integer=1]` 会推导为 `(question: string, count: number)`，`[name:string]` 会推导为 `string | undefined`，`[...rest]` 会推导为 `...string[]`。
+- 需要在类型位置复用推导结果时，可以使用导出的 `CommandParamArgs<'<question:string>'>`。
+- 也可以继续手写 handler 参数注解；注解与声明不一致时会在编译期报错。
+- 自动推导只对字面量生效：运行时拼接的字符串，或显式声明为 `string` 的变量会回退为 `any[]`。需要保留字面量类型时，使用 `const` 变量或 `as const`。
+- 类型层解析覆盖上面的声明语法；如果默认值包含 `]` 等会干扰声明边界的字符，可能回退为 `any[]`，但不影响运行时解析。非法声明仍然在注册时抛错，而不是变成类型错误。
+
+参数错误示例：
+
+```text
+/ask hello abc
+-> 参数 count 需要是整数
+-> 用法：/ask <question> [count]
+```
+
+### 指令组
+
+```ts
+ctx.commands.group(
+    {
+        name: 'plugin',
+        aliases: ['p'],
+        permission: 'SuperAdmin',
+        description: '管理已安装的插件包',
+        // 可选；省略时自动生成用法提示
+        handler: async (_event, context) => {
+            await context.send('用法：/plugin <list|install>')
+        },
+    },
+    (plugin) => {
+        plugin.register(
+            {
+                name: 'list',
+                description: '列出插件包',
+            },
+            async (_event, context) => {
+                await context.send('...')
+            }
+        )
+
+        plugin.register(
+            {
+                name: 'install',
+                description: '安装插件包',
+                params: '<spec:string>',
+            },
+            async (_event, context, _match, spec: string) => {
+                await context.send(`安装：${spec}`)
+            }
+        )
+
+        plugin.group({ name: 'cache' }, (cache) => {
+            cache.register({ name: 'clear' }, async () => {})
+        })
+    }
+)
+```
+
+指令组规则：
+
+- `group()` 的 `name` 和 `aliases` 同样是单个路径段；通过嵌套 `group()` 组成任意层级。
+- 子命令自动拼接组路径，例如上面的 `plugin` + `install` 对应 `/plugin install`。
+- 子命令默认继承组的 `prefixes`、`permission`，也可以在子命令上覆盖。
+- 组别名和子命令别名会自动组合；组 `plugin` 别名 `p`、子命令 `install` 别名 `i` 时，`/p i` 也能命中。
+- 组根没有提供 `handler` 时，会自动注册根命令并生成用法提示，列出直接子命令、参数用法和描述。
+- 组根提供了 `handler` 时，未命中子命令的输入（例如 `/plugin`、`/plugin help`、`/plugin unknown`）会进入该 handler。
+- 组根和子命令都可以声明 `params`；子命令的用法会显示在组根提示和 `/help` 中。例如组根声明 `params: '<target:string>'` 时，`/demo alice` 会把 `alice` 传给组根 handler。
+- `group()` 返回 disposer，会注销组根和所有子命令；组 setup 抛错或注册冲突时会自动回滚整组。
+- `/help` 中会显示完整路径，例如 `/plugin install`。
+
+同一前缀下按完整路径进行冲突检测。命令命中后会立即 `stopPropagation()`。
+
+匹配时前缀最长优先，同一前缀下完整路径最长优先：
+
+```text
+/plugin install demo
+-> command: "plugin install"
+-> args: ["demo"]
+-> rest: "demo"
+```
+
+`/plugin unknown` 在 `plugin` 组根存在时会回退到组根，`args` 为 `["unknown"]`。
 
 `CommandMatch`：
 
 ```ts
 interface CommandMatch {
-    command: string
+    command: string // 命中的完整路径，例如 "plugin install"
     prefix: string
     args: string[]
     rest: string
@@ -304,6 +437,7 @@ await context.send('自动转义 CQ 码', { autoEscape: true })
 - `plugins.<id>.enabled` 控制整体启用。
 - `plugins.<id>.groups.allow` / `deny` 只作用于群事件，二者不能同时非空。
 - `plugins.<id>.private` 控制私聊，默认 `true`。
+- `/help` 只列出当前会话中启用的插件命令；群 gating 或 `private: false` 会隐藏对应命令。
 
 ## 配置校验
 
@@ -334,22 +468,26 @@ manifest: {
 
 `enabled` 等信封字段会被剥离；`limit` 会传给 `configSchema`。未知字段会报错，错误信息包含 `plugins.demo.limit` 这样的路径。
 
-## 外部插件
+## 本地插件
+
+完整的目录约定、创建步骤和本地调试流程见[插件开发指南](plugin-development.md)。
+
+本地插件固定放在 `plugins/<id>/dist`，应用启动时自动扫描，不需要路径参数：
 
 ```bash
 npm run build
-node dist/app.js --plugin-dir examples/plugins
+node dist/app.js
 ```
 
-`--plugin-dir` 可以重复，`BOT_PLUGIN_DIR` 使用逗号分隔多个目录。应用会跳过与内置插件同 ID 的外部插件。加载器会扫描目录下所有 `.js`、`.mjs`、`.cjs`、`.ts`、`.mts`、`.cts` 文件，识别：
+应用会跳过与内置插件同 ID 的本地插件。加载器会扫描每个插件 `dist` 目录下所有 `.js`、`.mjs`、`.cjs`、`.ts`、`.mts`、`.cts` 文件，识别：
 
 - `export default plugin`
 - `export const plugin = ...`
 - `export const plugins = [...]`
 
-没有导出插件定义的 helper 模块会被跳过；目录中没有任何有效插件时加载失败。插件定义必须包含可调用的 `configSchema.safeParse`，非法的 `dependencies` 类型也会被拒绝。
+没有导出插件定义的 helper 模块会被跳过；空目录不会报错，但目录中存在无法导入或无法识别的文件、且最终没有加载到任何有效插件时，启动失败。插件定义必须包含可调用的 `configSchema.safeParse`，非法的 `dependencies` 类型也会被拒绝。
 
-TypeScript 插件必须在生产运行前编译为 JavaScript。外部插件和内置插件共用同一个 `PluginContext` API。
+TypeScript 插件必须在生产运行前编译为 JavaScript。本地插件和内置插件共用同一个 `PluginContext` API。
 
 推荐把插件做成独立包，至少包含 `package.json`、`tsconfig.json` 和 `src/index.ts`。`package.json` 的入口指向构建后的 `dist/index.js`：
 
@@ -368,7 +506,7 @@ TypeScript 插件必须在生产运行前编译为 JavaScript。外部插件和
 }
 ```
 
-`@jsbot-tellus/core` 只用于类型和 `definePlugin`，运行时由宿主提供。外部插件开发时通过 `npm install --save-dev @jsbot-tellus/core` 安装；在本仓库内联调也可以改用 `file:` 或 workspace 链接。发布到 npm 时不要把 `@jsbot-tellus/core` 写进 `dependencies` 或 `peerDependencies`。仅在本机使用的包可以加 `"private": true`。插件自己的第三方依赖放在 `dependencies`，npm 安装插件时会一并安装。
+`@jsbot-tellus/core` 只用于类型和 `definePlugin`。通过 `/plugin install` 安装时由宿主提供；从 `plugins/` 加载的本地插件需要在插件自己的 `node_modules` 中安装 core（`npm install` 会安装 `devDependencies`）。在本仓库内联调也可以改用 `file:` 或 workspace 链接。发布到 npm 时不要把 `@jsbot-tellus/core` 写进 `dependencies` 或 `peerDependencies`。仅在本机使用的包可以加 `"private": true`。插件自己的第三方依赖放在 `dependencies`，npm 安装插件时会一并安装。
 
 内置插件 `core`、`admin` 是 `src/plugins/` 下的普通源码。其他插件放在 `plugins/`，该目录整体被 `.gitignore` 排除。每个本地插件都是独立包，独立安装依赖：
 
@@ -377,24 +515,23 @@ npm install --prefix plugins/poke
 npm install --prefix plugins/llm
 npm run build:local
 
-node dist/app.js \
-    --plugin-dir plugins/poke/dist \
-    --plugin-dir plugins/llm/dist
+node dist/app.js
 ```
 
-示例见 [`examples/plugins/hello`](../examples/plugins/hello)。
+应用会自动扫描 `plugins/<id>/dist`；没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，会先自动构建再加载，构建失败则记录警告并跳过。示例见 [`examples/plugins/hello`](../examples/plugins/hello)。
 
 ## 通过 npm 发布与安装
 
+打包结构、发布清单和本地开发流程见[插件开发指南](plugin-development.md)。
+
 发布到 npm registry 的插件包必须是可直接运行的构建产物，安装后不再执行编译。要求：
 
-- ESM 包（`"type": "module"`），发布 `dist/` 中的 JavaScript 和 `.d.ts`。
-- 通过 `exports["."]` 或 `main` 提供包根入口；安装器只解析根入口。
-- 根入口导出插件定义：`export default plugin`、`export const plugin = ...` 或 `export const plugins = [...]`。
-- `manifest.id` 必须匹配 `[a-z0-9][a-z0-9._-]*`，且不能与内置插件、`--plugin-dir` 插件或其它已安装插件重复。
+- ESM 包（`"type": "module"`），发布 `dist/` 中的 JavaScript 和 `.d.ts`；安装后从 `plugins/<目录>/dist` 加载，不再执行编译。
+- `dist/` 中导出的插件定义会被加载：`export default plugin`、`export const plugin = ...` 或 `export const plugins = [...]`。
+- `manifest.id` 必须匹配 `[a-z0-9][a-z0-9._-]*`，且不能与内置插件、`plugins/` 本地插件或其它已安装插件重复。
 - 插件之间的依赖写在 `manifest.dependencies`，依赖必须由同一个包导出，或已由其它已安装包提供。
 - 不要依赖源码仓库或相对的 `file:` 依赖；第三方运行时依赖写入 `dependencies`。
-- 不要把 `@jsbot-tellus/core` 写进 `dependencies` 或 `peerDependencies`。宿主会在安装目录创建 `node_modules/@jsbot-tellus/core` 链接，运行时直接解析到当前内核。
+- 不要把 `@jsbot-tellus/core` 写进 `dependencies` 或 `peerDependencies`。宿主会在 `plugins/<目录>/node_modules/@jsbot-tellus/core` 创建链接，运行时直接解析到当前内核。
 - 不要依赖 `postinstall` 构建。安装器默认使用 `--ignore-scripts`，只有 `installer.allowScripts=true` 才会执行 npm 脚本。
 
 发布后在聊天中安装：
@@ -407,7 +544,7 @@ node dist/app.js \
 /plugin remove @yourscope/plugin-demo
 ```
 
-安装、更新和卸载成功后会自动重启运行时并重新加载插件，进程不会退出。`/plugin` 的所有子命令（包括 `help` 和 `list`）都要求 SuperAdmin。安装器默认关闭；启用后只接受 npm registry 包，拒绝 git、file、URL、workspace、link 和版本范围。安装目录默认是 `<data-dir>/plugins`，配置见[插件安装器](configuration.md#插件安装器)。
+安装、更新和卸载成功后会自动重启运行时并重新加载插件，进程不会退出。`/plugin` 的所有子命令（包括 `help` 和 `list`）都要求 SuperAdmin。安装器默认关闭；启用后只接受 npm registry 包，拒绝 git、file、URL、workspace、link 和版本范围。包会直接安装到 `plugins/<插件id>/` 并从 `dist` 加载，配置见[插件安装器](configuration.md#插件安装器)。
 
 安装和更新会检查完整依赖图；自依赖、循环依赖和缺失依赖会被拒绝。卸载被其它包依赖的插件时默认失败，确认后可使用 `/plugin remove <目标> --force`。