@jsbot-tellus/core 2.6.0 → 2.7.0

package/docs/plugin-api.md

@@ -184,11 +184,11 @@ const installed = await ctx.core.installer.list()
 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()` 请求应用重建运行时并重新加载插件；第三方插件不应把这些方法暴露给普通用户。
+核心服务由内核注入，适合帮助、状态类插件。`ctx.core.commands.list(event)` 会按当前会话的 `enabled`、`groups`、`private` gating 以及命令的 `messageType` 过滤命令；不传 `event` 时返回全部命令。`ctx.core.installer` 额外提供 `install` / `remove` / `update` / `list`；它不会检查调用者角色，权限判断由调用方负责（`admin` 的 `/plugin` 命令要求 SuperAdmin）。安装器默认关闭，必须在配置中显式启用。`ctx.core.restart()` 请求应用重建运行时并重新加载插件；第三方插件不应把这些方法暴露给普通用户。
 
 安装的插件与内置插件运行在同一个宿主进程中，可访问文件系统、网络和 `process.env`，属于完全可信代码，不是安全沙箱。
 
-自动重启会在同一个 Node.js 进程内重建 Kernel，不会清空 Node 的 ESM 模块缓存。安装包的入口文件会附加查询参数来绕过缓存，但入口相对导入的辅助模块仍可能复用旧代码；通过 `plugins/` 加载的本地插件也不会被缓存刷新。更新多文件插件包后，请完整退出并重新启动进程。
+自动重启会在同一个 Node.js 进程内重建 Kernel，不会清空 Node 的 ESM 模块缓存。每次加载都会重新构建带 `build` 脚本的插件，并给入口文件附加基于修改时间的查询参数来绕过缓存；但入口相对导入的辅助模块仍可能复用旧代码。更新多文件插件包后，请完整退出并重新启动进程。
 
 ## 命令
 
@@ -215,11 +215,14 @@ ctx.commands.register(
 | `aliases`     | `[]`     | 别名                                         |
 | `prefixes`    | `['/']`  | 前缀；空字符串表示无前缀                     |
 | `permission`  | `'User'` | `User`、`Admin`、`SuperAdmin`                |
+| `messageType` | 无       | `'group'`、`'private'` 或数组，限定生效会话  |
 | `description` | 无       | `/help` 中展示                               |
 | `params`      | 无       | Koishi 风格参数声明；省略时 handler 行为不变 |
 
 `name` 和 `aliases` 的每一项只能是一个路径段；多级命令请使用 `commands.group()`。
 
+`messageType` 省略时群聊和私聊都可触发；`messageType: 'group'` 只匹配群消息，私聊中的同名文本会继续进入 `onMessage`。命令组会继承该设置，子命令可以覆盖。
+
 ### 参数
 
 `params` 用字符串声明位置参数，解析结果从 handler 的第四个参数开始按位置传入：
@@ -344,7 +347,7 @@ ctx.commands.group(
 
 - `group()` 的 `name` 和 `aliases` 同样是单个路径段；通过嵌套 `group()` 组成任意层级。
 - 子命令自动拼接组路径，例如上面的 `plugin` + `install` 对应 `/plugin install`。
-- 子命令默认继承组的 `prefixes`、`permission`，也可以在子命令上覆盖。
+- 子命令默认继承组的 `prefixes`、`permission`、`messageType`，也可以在子命令上覆盖。
 - 组别名和子命令别名会自动组合；组 `plugin` 别名 `p`、子命令 `install` 别名 `i` 时，`/p i` 也能命中。
 - 组根没有提供 `handler` 时，会自动注册根命令并生成用法提示，列出直接子命令、参数用法和描述。
 - 组根提供了 `handler` 时，未命中子命令的输入（例如 `/plugin`、`/plugin help`、`/plugin unknown`）会进入该 handler。
@@ -385,6 +388,16 @@ ctx.events.onMessage(async (event, context) => {
     }
 })
 
+ctx.events.onGroupMessage(async (event, context) => {
+    // 只处理群消息，event.message_type 收窄为 'group'
+    await context.send(`${event.group_id} 收到消息`)
+})
+
+ctx.events.onPrivateMessage(async (_event, context) => {
+    // 只处理私聊消息
+    await context.send('私聊收到')
+})
+
 ctx.events.onNotice(
     { noticeType: 'notify', subType: 'poke' },
     async (event, context) => {
@@ -402,6 +415,8 @@ ctx.events.onRequest({ requestType: 'friend' }, async (event) => {
 
 未匹配命令的消息才会进入 message handler。notice/request handler 会先按类型过滤，再检查插件 gating。
 
+`onGroupMessage` / `onPrivateMessage` 与 SDK 的同名方法对齐，在注册时按 `message_type` 过滤，事件类型分别收窄为群消息和私聊消息。
+
 ## 中间件
 
 ```ts
@@ -488,7 +503,7 @@ manifest: {
 
 完整的目录约定、创建步骤和本地调试流程见[插件开发指南](plugin-development.md)。
 
-本地插件固定放在 `plugins/<id>/dist`，应用启动时自动扫描，不需要路径参数：
+本地插件固定放在 `plugins/<id>/dist`，应用启动和运行时重启时自动扫描，不需要路径参数：
 
 ```bash
 npm run build
@@ -534,7 +549,7 @@ npm run build:plugin
 node dist/app.js
 ```
 
-应用会自动扫描 `plugins/<id>/dist`；没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，会先自动构建再加载，构建失败则记录警告并跳过。示例见 [`examples/plugins/hello`](../examples/plugins/hello)。
+应用每次加载都会扫描 `plugins/<id>/dist`；带有 `build` 脚本且依赖已安装的插件会先自动构建再加载，构建失败时回退已有 `dist`，没有可用产物才记录警告并跳过。示例见 [`examples/plugins/hello`](../examples/plugins/hello)。
 
 ## 通过 npm 发布与安装
 

package/docs/plugin-development.md

@@ -6,11 +6,11 @@ API 细节（`PluginContext`、命令、事件、中间件、KV、Session 等）
 
 ## 先选插件类型
 
-| 类型     | 推荐位置            | 是否进入本仓库 | 加载方式                                               | 适用场景                     |
-| -------- | ------------------- | -------------- | ------------------------------------------------------ | ---------------------------- |
-| 内置插件 | `src/plugins/<id>/` | 是             | 注册到 `src/plugins/index.ts`                          | 随内核发布的官方功能         |
-| 本地插件 | `plugins/<id>/`     | 否             | 启动时自动扫描 `plugins/<id>/dist`，缺失时尝试自动构建 | 个人使用、内部功能、开发调试 |
-| npm 插件 | 独立仓库或独立包    | 独立管理       | `/plugin install <包名>[@版本]`                        | 发布给其他用户安装           |
+| 类型     | 推荐位置            | 是否进入本仓库 | 加载方式                                           | 适用场景                     |
+| -------- | ------------------- | -------------- | -------------------------------------------------- | ---------------------------- |
+| 内置插件 | `src/plugins/<id>/` | 是             | 注册到 `src/plugins/index.ts`                      | 随内核发布的官方功能         |
+| 本地插件 | `plugins/<id>/`     | 否             | 启动和重启时扫描 `plugins/<id>/dist`，每次尝试重建 | 个人使用、内部功能、开发调试 |
+| npm 插件 | 独立仓库或独立包    | 独立管理       | `/plugin install <包名>[@版本]`                    | 发布给其他用户安装           |
 
 位置约定：
 
@@ -39,7 +39,7 @@ plugins/my-plugin/
 
 - `src/index.ts` 是开发入口。
 - `dist/index.js` 是运行时入口。
-- 构建产物固定放在 `plugins/<id>/dist`，启动时自动扫描；缺少 `dist` 且 `package.json` 中存在 `build` 脚本时会先自动构建，不要指向或加载 `src/`。
+- 构建产物固定放在 `plugins/<id>/dist`，每次加载时自动扫描；只要 `package.json` 中存在 `build` 脚本且依赖已安装，就会先自动重建，不要指向或加载 `src/`。
 - 每个本地插件都是独立包，有自己的 `package.json`、lockfile 和 `node_modules`。
 
 ### 内置插件
@@ -113,7 +113,7 @@ npm install --prefix plugins/my-plugin
 node dist/app.js
 ```
 
-启动时如果插件还没有 `dist`，应用会自动执行 `npm run build --prefix plugins/my-plugin`；前提是已经安装依赖。也可以手动提前构建：
+应用在启动和每次运行时重启时都会执行 `npm run build --prefix plugins/my-plugin`，前提是已经安装依赖；构建失败或缺少依赖时会回退加载已有 `dist`。也可以手动提前构建：
 
 ```bash
 npm run build --prefix plugins/my-plugin
@@ -221,7 +221,7 @@ export default definePlugin({
 - `setup()` 只注册命令、事件和中间件；定时器、连接等运行时资源放在 `start()`，并在 `stop()` 中清理。
 - 命令可以用 `params` 声明位置参数；解析结果从 handler 第四个参数开始传入，用法会自动出现在 `/help` 和指令组提示中。详见[插件 API 的参数章节](plugin-api.md#参数)。
 - 多级命令（例如 `/plugin install`）使用 `ctx.commands.group()`，不要直接注册带空格的命令名。详见[插件 API 的命令章节](plugin-api.md#命令)。
-- 修改命令、事件或配置后，完整重启进程最可靠；自动重启不会清空 ESM 模块缓存。
+- 修改命令、事件或配置后，自动重启会重新构建并刷新插件入口模块；入口相对导入的辅助模块仍可能命中 ESM 缓存，修改多文件插件时完整重启进程最可靠。
 
 ### 4. 安装依赖
 
@@ -230,7 +230,7 @@ npm install --prefix plugins/my-plugin
 npm run build
 ```
 
-根目录的 `npm run build` 构建内核。插件自身的构建在启动时缺少 `dist` 会自动执行；需要提前校验时也可以手动运行 `npm run build --prefix plugins/my-plugin`。
+根目录的 `npm run build` 构建内核。插件自身在每次加载时都会自动构建；需要提前校验时也可以手动运行 `npm run build --prefix plugins/my-plugin`。
 
 根目录的 `npm run build:plugin` / `npm run check:plugin` 会自动发现 `plugins/*` 中包含 `src/`、`tsconfig.json` 且声明了对应 npm script 的目录；没有安装 `node_modules` 的目录会跳过。新增插件不需要修改根 `package.json`，也可以单独运行 `npm run build --prefix plugins/<id>` 和 `npm run check --prefix plugins/<id>`。
 
@@ -242,7 +242,7 @@ npm run watch --prefix plugins/my-plugin
 
 ### 5. 启动并加载
 
-本地插件目录固定为 `plugins/`，相对当前工作目录解析。应用启动时会自动扫描：
+本地插件目录固定为 `plugins/`，相对当前工作目录解析。应用启动和运行时重启时都会自动扫描：
 
 ```text
 plugins/
@@ -264,7 +264,9 @@ node dist/app.js
 npm run dev
 ```
 
-不需要额外参数；多个本地插件按 `plugins/<id>/dist` 并存。没有 `dist` 的本地插件如果带有 `build` 脚本且 `node_modules` 存在，会先自动执行 `npm run build` 再加载；没有 `build` 脚本、缺少依赖或构建失败时会记录警告并跳过。
+`npm run dev` 会监听内核 `src/` 和本地插件 `plugins/*/src/`，并忽略插件构建产物 `plugins/*/dist/`。修改插件源码会自动重启并重建插件；修改 `dist` 不会触发重启，避免“构建 → 重启 → 再构建”的循环。
+
+不需要额外参数；多个本地插件按 `plugins/<id>/dist` 并存。只要带有 `build` 脚本且 `node_modules` 存在，每次加载都会先执行 `npm run build` 再加载；构建失败或缺少依赖时会回退加载已有 `dist`，没有可用 `dist` 时记录警告并跳过。没有 `build` 脚本的插件直接加载现有 `dist`。
 
 ### 6. 配置插件
 
@@ -295,28 +297,29 @@ npm run dev
     - `export const plugins = [...]`
 - 没有导出插件定义的 helper 模块会被跳过。
 - 生产环境应加载编译后的 JavaScript；TypeScript 源码必须先构建，或者在使用 `tsx` 的开发环境中运行。
-- `dist` 缺失时，如果插件目录中有 `package.json`、`package.json` 声明了 `scripts.build`，并且 `node_modules` 存在，加载器会执行 `npm run build` 后再加载；构建失败或构建后仍无 `dist` 时只跳过该插件。
-- 通过 `/plugin install` 安装的包由安装器管理，缺少 `dist` 时不会自动构建，而是直接告警跳过。
+- 每次加载时，如果插件目录中有 `package.json`、声明了 `scripts.build`，并且 `node_modules` 存在，加载器都会执行 `npm run build` 后再加载；构建失败或缺少依赖时，已有 `dist` 会回退加载，没有可用 `dist` 时只跳过该插件。
+- 通过 `/plugin install` 安装的包和手动放在 `plugins/` 的本地插件使用同一套重建规则；安装包通常自带 `dist`，缺少构建依赖时会回退使用自带产物。
 - 空目录不会报错；如果目录中存在无法导入或无法识别的文件，并且最终没有加载到任何有效插件，启动失败。只要至少有一个有效插件，其他无法识别的文件会记录警告并跳过。
 - 本地插件和在线安装的插件都从 `plugins/<目录>/dist` 自动加载，没有单独的安装目录。
 - 同一个 ID 同时来自内置插件和 `plugins/` 中的多个目录时，只有最先加载的那个生效。
 
 ## 调试与常见问题
 
-| 现象                                                 | 可能原因                                             | 处理                                                                                                             |
-| ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `skipping local plugin ... dist directory not found` | 没有 `build` 脚本、缺少 `node_modules`，或构建失败   | 执行 `npm install --prefix plugins/<id>`，检查 `scripts.build`，或手动执行 `npm run build --prefix plugins/<id>` |
-| `failed to build local plugin ...`                   | `build` 脚本执行失败或超时                           | 查看 npm 输出和插件源码，修复后重启                                                                              |
-| `build finished but dist directory not found`        | `build` 脚本没有把产物输出到插件的 `dist` 目录       | 检查 `tsconfig.json` 的 `outDir` 和 `scripts.build`                                                              |
-| `failed to import ...`                               | TypeScript 未编译、入口有运行时错误                  | 先构建；查看日志中的具体导入错误                                                                                 |
-| `dist` 目录没有有效插件                              | 没有导出 `default` / `plugin` / `plugins`            | 检查入口导出和 `dist` 中的构建输出                                                                               |
-| `skipping ... plugin id already loaded`              | 插件 ID 重复                                         | 修改 `manifest.id`，或移除重复的插件目录                                                                         |
-| `unknown plugin id`                                  | 配置里写了未加载的插件 ID                            | 启用插件、修正 ID，或删除 `plugins.<id>` 配置                                                                    |
-| 命令没有响应                                         | 插件未启用、权限不足、群组 gating、命令前缀不匹配    | 检查 `plugins.<id>.enabled`、角色、群组配置和命令前缀                                                            |
-| 修改代码后行为没变                                   | ESM 模块缓存、自动重启未刷新本地插件                 | 完整退出并重新启动进程                                                                                           |
-| `Cannot find module '@jsbot-tellus/core'`            | 没有安装 devDependency，或 `file:` 依赖尚未构建      | 在插件目录执行 `npm install`；使用 `file:` 时先构建根项目                                                        |
-| `/plugin install` 拒绝包                             | 使用了路径、`file:`、git/url、范围版本或未启用安装器 | 改用 npm 包名 + 精确版本或 dist-tag；确认 `installer.enabled` 和 allowlist                                       |
-| 安装完成但提示网络错误                               | 安装后的通知发送失败，不代表安装失败                 | 用 `/plugin list` 确认；必要时手动重启进程                                                                       |
+| 现象                                                 | 可能原因                                                           | 处理                                                                                                             |
+| ---------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `skipping local plugin ... dist directory not found` | 没有 `build` 脚本且缺少 `dist`，或构建失败/缺依赖且无可用旧 `dist` | 执行 `npm install --prefix plugins/<id>`，检查 `scripts.build`，或手动执行 `npm run build --prefix plugins/<id>` |
+| `failed to build local plugin ...`                   | `build` 脚本执行失败或超时                                         | 查看 npm 输出和插件源码，修复后重启                                                                              |
+| `using existing dist ... rebuild failed`             | 重建失败，但旧 `dist` 仍可用                                       | 检查构建错误；确认插件运行的是预期产物                                                                           |
+| `build finished but dist directory not found`        | `build` 脚本没有把产物输出到插件的 `dist` 目录                     | 检查 `tsconfig.json` 的 `outDir` 和 `scripts.build`                                                              |
+| `failed to import ...`                               | TypeScript 未编译、入口有运行时错误                                | 先构建；查看日志中的具体导入错误                                                                                 |
+| `dist` 目录没有有效插件                              | 没有导出 `default` / `plugin` / `plugins`                          | 检查入口导出和 `dist` 中的构建输出                                                                               |
+| `skipping ... plugin id already loaded`              | 插件 ID 重复                                                       | 修改 `manifest.id`，或移除重复的插件目录                                                                         |
+| `unknown plugin id`                                  | 配置里写了未加载的插件 ID                                          | 启用插件、修正 ID，或删除 `plugins.<id>` 配置                                                                    |
+| 命令没有响应                                         | 插件未启用、权限不足、群组 gating、命令前缀不匹配                  | 检查 `plugins.<id>.enabled`、角色、群组配置和命令前缀                                                            |
+| 修改代码后行为没变                                   | ESM 缓存命中辅助模块，或构建失败回退了旧 `dist`                    | 检查构建日志；完整退出并重新启动进程                                                                             |
+| `Cannot find module '@jsbot-tellus/core'`            | 没有安装 devDependency，或 `file:` 依赖尚未构建                    | 在插件目录执行 `npm install`；使用 `file:` 时先构建根项目                                                        |
+| `/plugin install` 拒绝包                             | 使用了路径、`file:`、git/url、范围版本或未启用安装器               | 改用 npm 包名 + 精确版本或 dist-tag；确认 `installer.enabled` 和 allowlist                                       |
+| 安装完成但提示网络错误                               | 安装后的通知发送失败，不代表安装失败                               | 用 `/plugin list` 确认；必要时手动重启进程                                                                       |
 
 注意：安装器在安装或更新成功后会请求重建运行时，但安装后的通知发送失败不会回滚安装。遇到“网络连接异常”时优先检查 `/plugin list` 和 `plugins/.jsbot-installed.json`。
 

package/docs/release.md

@@ -2,12 +2,13 @@
 
 `@jsbot-tellus/core` 通过 GitHub Actions 自动发布：
 
-- CI 工作流：[`.github/workflows/ci.yaml`](../.github/workflows/ci.yaml)，负责类型检查、格式检查、依赖审计、测试、构建和 smoke
-- CD 工作流：[`.github/workflows/cd.yaml`](../.github/workflows/cd.yaml)，在 `main` 的 CI 成功后发布到 npm
+- CI 工作流：[`.github/workflows/ci.yaml`](../.github/workflows/ci.yaml)，负责类型检查、格式检查、依赖审计、测试、构建、smoke 和 Docker 镜像构建校验
+- CD 工作流：[`.github/workflows/cd.yaml`](../.github/workflows/cd.yaml)，在 `main` 的 CI 成功后发布到 npm，并构建推送 Docker 镜像
 - 触发方式：推送到 `main`，或在 `main` 上手动运行 `CI`；不需要创建或推送版本标签
 - 发布方式：npm Trusted Publisher（GitHub OIDC），不需要长期 `NPM_TOKEN`
-- 幂等处理：如果 `package.json` 中的版本已经存在于 npm，发布步骤会跳过
-- 发布产物带 npm provenance
+- Docker 镜像：同时推送 GHCR 和 Docker Hub；使用 `GITHUB_TOKEN` 推送 GHCR，Docker Hub 使用仓库 Secret
+- 幂等处理：`package.json` 中的版本已经存在于 npm 时跳过 npm 发布；同版本镜像已存在于某个镜像仓库时只跳过该仓库
+- 发布产物带 npm provenance；Docker 镜像带 provenance 和 SBOM
 
 CD 只会在 CI 结论为成功、且 CI 运行来自 `main` 的 `push` 或 `workflow_dispatch` 时执行。`pull_request` 运行和其他分支不会触发发布。
 
@@ -25,15 +26,25 @@ CD 只会在 CI 结论为成功、且 CI 运行来自 `main` 的 `push` 或 `wor
 
 工作流文件名必须与实际文件一致。如果以后重命名 `cd.yaml`，需要同步修改 npm 的 Trusted Publisher 配置。
 
+Docker Hub 需要在仓库的 **Settings → Secrets and variables → Actions** 中配置：
+
+| Secret               | 值                                      |
+| -------------------- | --------------------------------------- |
+| `DOCKERHUB_USERNAME` | Docker Hub 用户名                       |
+| `DOCKERHUB_TOKEN`    | Docker Hub Access Token（Read & Write） |
+
+首次镜像推送后，如果希望匿名拉取，在 GitHub 仓库的 **Packages** 设置里把 `jsbot-tellus` 的可见性改为 public。GHCR 使用工作流自带的 `GITHUB_TOKEN`，不需要额外 Secret。
+
 CD 工作流已经声明：
 
 ```yaml
 permissions:
     contents: read
     id-token: write
+    packages: write
 ```
 
-`id-token: write` 用于 OIDC 和 provenance，不能删除。
+`id-token: write` 用于 npm OIDC 和 provenance，不能删除；`packages: write` 用于推送 GHCR。
 
 ## 发布新版本
 
@@ -46,15 +57,32 @@ git commit -m "Release v$(node -p "require('./package.json').version")"
 git push
 ```
 
-将 `patch` 换成 `minor` 或 `major` 可以发布对应版本。提交并通过 Pull Request 合并到 `main` 后，CI 会先运行；CI 成功后 CD 自动发布该版本。`main` 受分支保护，不能直接推送。
+将 `patch` 换成 `minor` 或 `major` 可以发布对应版本。提交并通过 Pull Request 合并到 `main` 后，CI 会先运行；CI 成功后 CD 自动发布该版本到 npm，并构建推送 Docker 镜像。`main` 受分支保护，不能直接推送。
+
+如果 `main` 上的版本已经在 npm 存在，CD 只会输出提示并跳过，不会失败。镜像按仓库独立判断：某个仓库已有该版本时跳过该仓库，缺失的仓库会补推。版本提交重复合并不影响已发布版本。
+
+## Docker 镜像
+
+CD 会推送以下标签：
+
+- `latest`
+- 完整版本号，例如 `1.2.3`
+- 主次版本，例如 `1.2`
+- 主版本，例如 `1`
+- `sha-<短哈希>`
 
-如果 `main` 上的版本已经在 npm 存在，CD 只会输出提示并跳过，不会失败。因此版本提交重复合并不影响已发布版本。
+镜像地址：
+
+- `ghcr.io/jsbot-dev/jsbot-tellus`
+- `docker.io/<DOCKERHUB_USERNAME>/jsbot-tellus`
+
+只构建 `linux/amd64`。CI 在每次推送时构建镜像并执行 smoke，但不会推送。使用方式见 [Docker 部署](docker.md)。
 
 ## 手动运行
 
 在 GitHub Actions 中打开 `CI`，选择 `Run workflow`，并选择 `main` 分支。CI 成功后，CD 会像普通推送一样自动发布。
 
-如果 CD 因临时故障失败，可以在 Actions 中打开对应的 `CD` 运行并选择 `Re-run failed jobs`，不需要重新推送代码。
+如果 CD 因临时故障失败，可以在 Actions 中打开对应的 `CD` 运行并选择 `Re-run failed jobs`，不需要重新推送代码。Docker job 会重新检查两个镜像仓库，只补推缺失的版本标签。
 
 ## 验证
 
@@ -72,10 +100,24 @@ npm install -g @jsbot-tellus/core@latest
 jsbot --help
 ```
 
+Docker 镜像验证：
+
+```bash
+docker pull ghcr.io/jsbot-dev/jsbot-tellus:latest
+docker run --rm ghcr.io/jsbot-dev/jsbot-tellus:latest --help
+
+docker pull <DOCKERHUB_USERNAME>/jsbot-tellus:latest
+docker run --rm <DOCKERHUB_USERNAME>/jsbot-tellus:latest --help
+```
+
 ## 常见失败
 
 - **`ENEEDAUTH` / `E403`**：检查 npm Trusted Publisher 的组织、仓库和工作流文件名是否完全匹配（文件名必须是 `cd.yaml`）。
 - **`npm publish` 提示版本已存在**：说明该版本此前已经发布；提升 `package.json` 版本后重新推送到 `main`。正常情况下 CD 会自动跳过已发布版本。
 - **provenance 失败**：确认 CD 工作流仍有 `id-token: write` 权限，并且仓库是公开的。
+- **Docker Hub 登录失败 / `unauthorized`**：确认 `DOCKERHUB_USERNAME`、`DOCKERHUB_TOKEN` 已配置，Token 有 Read & Write 权限。
+- **GHCR 推送 `denied`**：确认工作流仍有 `packages: write`，并且组织没有禁止 `GITHUB_TOKEN` 创建包。
+- **镜像已存在**：CD 会输出 notice 并跳过对应仓库，不会失败；如果两个仓库都有该版本，提升版本号后再发布。
+- **Docker job 被跳过**：它依赖 npm 发布 job；npm 发布失败或 CD 未在 `main` 触发时不会执行。
 - **CD 没有触发**：确认 `CI` 已在 `main` 上成功完成；`pull_request` 运行和其他分支不会触发发布。
 - **CD 找不到要发布的提交**：确认 `ci.yaml` 和 `cd.yaml` 都已经在默认分支上。

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jsbot-tellus/core",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "engines": {
         "node": "^24.22.1 || >=26.12.1"
     },
@@ -44,7 +44,7 @@
         "jsbot": "dist/app.js"
     },
     "scripts": {
-        "dev": "tsx watch src/app.ts",
+        "dev": "tsx watch --exclude \"plugins/**/dist/**\" --include \"plugins/*/src/**\" src/app.ts",
         "dev:webui": "vite --config webui/vite.config.ts",
         "start": "node dist/app.js",
         "start:build": "npm run build && npm start",

package/src/core/dispatch/command.ts

@@ -11,17 +11,42 @@ import type {
     CommandInfo,
     CommandMatch,
     CommandOptions,
+    MessageType,
+    MessageTypeFilter,
 } from '../plugin/types.js'
 import type { Permission } from '../security/permission.js'
 
 type AnyCommandHandler = CommandHandler<OneBotMessageEvent, any[]>
 
+const DEFAULT_MESSAGE_TYPES: MessageType[] = ['group', 'private']
+
+export function normalizeMessageTypes(
+    value: MessageTypeFilter | undefined
+): MessageType[] {
+    if (value === undefined) return [...DEFAULT_MESSAGE_TYPES]
+
+    const values = typeof value === 'string' ? [value] : value
+    const result: MessageType[] = []
+
+    for (const item of values) {
+        if (
+            (item === 'group' || item === 'private') &&
+            !result.includes(item)
+        ) {
+            result.push(item)
+        }
+    }
+
+    return result.length > 0 ? result : [...DEFAULT_MESSAGE_TYPES]
+}
+
 export interface CommandRegistration {
     pluginId: string
     name: string
     aliases: string[]
     prefixes: string[]
     permission: Permission
+    messageTypes: MessageType[]
     description?: string | undefined
     params?: string | undefined
     paramsParser?: CompiledCommandParams | undefined
@@ -35,6 +60,7 @@ export interface CommandGroupRegistration {
     aliases: string[]
     prefixes: string[]
     permission: Permission
+    messageTypes: MessageType[]
     description?: string | undefined
     params?: string | undefined
     handler?: AnyCommandHandler | undefined
@@ -188,6 +214,7 @@ export class CommandRegistry {
             bases,
             prefixes,
             registration.permission,
+            registration.messageTypes,
             children
         )
 
@@ -199,6 +226,7 @@ export class CommandRegistry {
                 bases,
                 prefixes,
                 registration.permission,
+                registration.messageTypes,
                 registration.description,
                 registration.params,
                 registration.handler,
@@ -253,6 +281,7 @@ export class CommandRegistry {
                 name: registration.name,
                 aliases: [...registration.aliases],
                 permission: registration.permission,
+                messageTypes: [...registration.messageTypes],
                 ...(registration.description !== undefined
                     ? { description: registration.description }
                     : {}),
@@ -263,7 +292,10 @@ export class CommandRegistry {
             }))
     }
 
-    match(rawMessage: string): RegisteredCommand | null {
+    match(
+        rawMessage: string,
+        messageType?: MessageType
+    ): RegisteredCommand | null {
         const raw = stripLeadingReply(rawMessage.trim()).trim()
 
         if (!raw) return null
@@ -298,6 +330,13 @@ export class CommandRegistry {
 
                 if (!registration) continue
 
+                if (
+                    messageType !== undefined &&
+                    !registration.messageTypes.includes(messageType)
+                ) {
+                    continue
+                }
+
                 const start = first.index ?? 0
                 const end = (last.index ?? 0) + last[0].length
 
@@ -404,6 +443,7 @@ export class CommandRegistry {
         bases: string[],
         prefixes: string[],
         permission: Permission,
+        messageTypes: MessageType[],
         children: GroupChild[]
     ): GroupScope {
         const disposers: Array<() => void> = []
@@ -464,6 +504,10 @@ export class CommandRegistry {
                     aliases: childBases.slice(1),
                     prefixes: options.prefixes ?? prefixes,
                     permission: options.permission ?? permission,
+                    messageTypes:
+                        options.messageType !== undefined
+                            ? normalizeMessageTypes(options.messageType)
+                            : [...messageTypes],
                     ...(options.description !== undefined
                         ? { description: options.description }
                         : {}),
@@ -506,12 +550,17 @@ export class CommandRegistry {
                 )
                 const nestedPrefixes = options.prefixes ?? prefixes
                 const nestedPermission = options.permission ?? permission
+                const nestedMessageTypes =
+                    options.messageType !== undefined
+                        ? normalizeMessageTypes(options.messageType)
+                        : [...messageTypes]
                 const nestedChildren: GroupChild[] = []
                 const nestedScope = this.createGroupScope(
                     pluginId,
                     nestedBases,
                     nestedPrefixes,
                     nestedPermission,
+                    nestedMessageTypes,
                     nestedChildren
                 )
 
@@ -523,6 +572,7 @@ export class CommandRegistry {
                         nestedBases,
                         nestedPrefixes,
                         nestedPermission,
+                        nestedMessageTypes,
                         options.description,
                         options.params,
                         options.handler,
@@ -567,6 +617,7 @@ export class CommandRegistry {
         bases: string[],
         prefixes: string[],
         permission: Permission,
+        messageTypes: MessageType[],
         description: string | undefined,
         params: string | undefined,
         handler: AnyCommandHandler | undefined,
@@ -584,6 +635,7 @@ export class CommandRegistry {
             aliases: bases.slice(1),
             prefixes,
             permission,
+            messageTypes: [...messageTypes],
             ...(description !== undefined ? { description } : {}),
             ...(params !== undefined ? { params } : {}),
             handler: handler ?? createGroupUsageHandler(children),

package/src/core/dispatch/handler.ts

@@ -1,4 +1,5 @@
 import type {
+    OneBotMessageEvent,
     OneBotNoticeEvent,
     OneBotRequestEvent,
     SnowLumaEvent,
@@ -9,6 +10,7 @@ import type {
     EventContext,
     EventType,
     MessageHandler,
+    MessageType,
     NoticeHandler,
     RequestHandler,
 } from '../plugin/types.js'
@@ -16,6 +18,7 @@ import type { MessageSender } from '../messaging/sender.js'
 
 export interface MessageRegistration {
     pluginId: string
+    messageType?: MessageType | undefined
     handler: MessageHandler
 }
 
@@ -96,9 +99,14 @@ export class HandlerRegistry {
     private noticeRegistrations: NoticeRegistration[] = []
     private requestRegistrations: RequestRegistration[] = []
 
-    registerMessage(pluginId: string, handler: MessageHandler): () => void {
+    registerMessage(
+        pluginId: string,
+        handler: MessageHandler,
+        messageType?: MessageType
+    ): () => void {
         const registration: MessageRegistration = {
             pluginId,
+            ...(messageType !== undefined ? { messageType } : {}),
             handler,
         }
 
@@ -156,6 +164,16 @@ export class HandlerRegistry {
     }
 }
 
+export function isMessageOf(
+    event: OneBotMessageEvent,
+    registration: MessageRegistration
+): boolean {
+    return (
+        registration.messageType === undefined ||
+        registration.messageType === event.message_type
+    )
+}
+
 export function isNoticeOf(
     event: OneBotNoticeEvent,
     registration: NoticeRegistration

package/src/core/dispatch/router.ts

@@ -15,6 +15,8 @@ import type {
     CommandInfo,
     EventType,
     MessageHandler,
+    MessageType,
+    MessageTypeFilter,
     MiddlewareOptions,
     NoticeHandler,
     NoticeOptions,
@@ -27,6 +29,7 @@ import { PermissionRefuser } from '../security/refuse.js'
 import type { Permission } from '../security/permission.js'
 import {
     CommandRegistry,
+    normalizeMessageTypes,
     type CommandGroupRegistration,
     type CommandRegistration,
 } from './command.js'
@@ -34,6 +37,7 @@ import {
     createEventContext,
     eventTypeOf,
     HandlerRegistry,
+    isMessageOf,
     isNoticeOf,
     isRequestOf,
 } from './handler.js'
@@ -64,6 +68,7 @@ export interface RegisterCommandOptions {
     aliases?: string[] | undefined
     prefixes?: string[] | undefined
     permission?: Permission | undefined
+    messageType?: MessageTypeFilter | undefined
     description?: string | undefined
     params?: string | undefined
     handler: AnyCommandHandler
@@ -75,6 +80,7 @@ export interface RegisterCommandGroupOptions {
     aliases?: string[] | undefined
     prefixes?: string[] | undefined
     permission?: Permission | undefined
+    messageType?: MessageTypeFilter | undefined
     description?: string | undefined
     params?: string | undefined
     handler?: AnyCommandHandler | undefined
@@ -160,7 +166,10 @@ export class Router {
             if (context.stopped) return
 
             if (isMessageEvent(event)) {
-                const found = this.commands.match(event.raw_message)
+                const found = this.commands.match(
+                    event.raw_message,
+                    event.message_type
+                )
 
                 if (found) {
                     sdkContext.stopPropagation()
@@ -257,6 +266,7 @@ export class Router {
             aliases: options.aliases ?? [],
             prefixes: options.prefixes ?? ['/'],
             permission: options.permission ?? 'User',
+            messageTypes: normalizeMessageTypes(options.messageType),
             ...(options.description !== undefined
                 ? { description: options.description }
                 : {}),
@@ -277,6 +287,7 @@ export class Router {
             aliases: options.aliases ?? [],
             prefixes: options.prefixes ?? ['/'],
             permission: options.permission ?? 'User',
+            messageTypes: normalizeMessageTypes(options.messageType),
             ...(options.description !== undefined
                 ? { description: options.description }
                 : {}),
@@ -289,8 +300,12 @@ export class Router {
         return this.commands.group(registration, setup)
     }
 
-    registerMessage(pluginId: string, handler: MessageHandler): () => void {
-        return this.handlers.registerMessage(pluginId, handler)
+    registerMessage(
+        pluginId: string,
+        handler: MessageHandler,
+        messageType?: MessageType
+    ): () => void {
+        return this.handlers.registerMessage(pluginId, handler, messageType)
     }
 
     registerNotice(options: RegisterNoticeOptions): () => void {
@@ -431,6 +446,8 @@ export class Router {
             for (const registration of this.handlers.messages()) {
                 if (messageContext.stopped) return
 
+                if (!isMessageOf(event, registration)) continue
+
                 if (!this.gate.isEnabled(registration.pluginId, event)) {
                     continue
                 }

package/src/core/index.ts

@@ -30,8 +30,11 @@ export type {
     EventContext,
     EventRegistrar,
     EventType,
+    GroupMessageHandler,
     InstalledPackageInfo,
     MessageHandler,
+    MessageType,
+    MessageTypeFilter,
     MiddlewareOptions,
     MiddlewareRegistrar,
     NoticeHandler,
@@ -46,6 +49,7 @@ export type {
     PluginStatus,
     PluginStatusEntry,
     PluginUpdateResult,
+    PrivateMessageHandler,
     RequestHandler,
     RequestOptions,
 } from './plugin/types.js'