@jsbot-tellus/core 2.6.0 → 2.8.0

package/dist/webui/index.html

@@ -100,9 +100,9 @@
                 }
             })()
         </script>
-      <script type="module" crossorigin src="/assets/index-CUvpnClx.js"></script>
-      <link rel="modulepreload" crossorigin href="/assets/api-CNzxhTWe.js">
-      <link rel="stylesheet" crossorigin href="/assets/index-CePlRZX6.css">
+      <script type="module" crossorigin src="/assets/index-CFz4VL67.js"></script>
+      <link rel="modulepreload" crossorigin href="/assets/api-Bm2KUKXH.js">
+      <link rel="stylesheet" crossorigin href="/assets/index-Cs8jafCm.css">
     </head>
     <body>
         <div id="app"></div>

package/docs/architecture.md

@@ -16,7 +16,7 @@ src/core/*     -X-> src/plugins/*
 - 插件只能通过 `PluginContext`、`EventContext` 和 `BotApi` 使用能力。
 - `core` 不 import 任何插件；`core`、`admin` 在 `src/plugins/index.ts` 显式注册。
 - 内置插件是普通源码，随内核一起编译；没有独立依赖，不单独建包。
-- 本地插件由 `src/app/runtime.ts` 在启动前扫描 `plugins/<id>/dist` 并追加到内置插件之后；缺少 `dist` 时加载器会尝试执行插件的 `build` 脚本。
+- 本地插件由 `src/app/runtime.ts` 在启动和运行时重启前扫描 `plugins/<id>/dist` 并追加到内置插件之后；带 `build` 脚本的插件每次都会先重新构建，失败时回退已有 `dist`。
 - 本地插件放在不跟踪的 `plugins/`，每个插件是独立包，构建后自动加载。
 
 ## 运行时主链路
@@ -56,7 +56,7 @@ src/
       host.ts             插件排序、配置校验、setup/start/stop
       gating.ts           enabled/private/groups
       kv.ts               SQLite KV
-      loader.ts           本地插件目录加载（缺 dist 时自动构建）
+      loader.ts           本地插件目录加载（每次加载自动重建，失败回退 dist）
       command-params.ts   命令参数解析入口（barrel）
       params/             声明、默认值/at/time、输入解析、类型级解析
       install-dir.ts      安装状态/路径入口（barrel）
@@ -148,7 +148,7 @@ npm run build:plugin
 node dist/app.js
 ```
 
-应用会固定扫描 `plugins/<id>/dist`，并跳过与内置插件同 ID 的本地插件，避免重复注册。没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，会先自动构建再加载；没有 `build` 脚本、缺少 `node_modules` 或构建失败时会记录警告并跳过。`npm run build:plugin` / `npm run check:plugin` 会自动发现 `plugins/*` 下的本地源码插件，新增插件不需要改根 `package.json`。
+应用会固定扫描 `plugins/<id>/dist`，并跳过与内置插件同 ID 的本地插件，避免重复注册。每次加载时，带 `build` 脚本且依赖已安装的插件都会先自动构建，无论 `dist` 是否已经存在；构建失败或缺少 `node_modules` 时会回退加载已有 `dist`，没有可用 `dist` 时记录警告并跳过。没有 `build` 脚本的插件直接加载现有 `dist`。`npm run build:plugin` / `npm run check:plugin` 会自动发现 `plugins/*` 下的本地源码插件，新增插件不需要改根 `package.json`。
 
 ## 在线安装插件
 

package/docs/configuration.md

@@ -8,7 +8,7 @@
 | 数据目录 | `--data-dir`  | `BOT_DATA_DIR`  | `./data`            |
 | 日志级别 | `--log-level` | `BOT_LOG_LEVEL` | `info`              |
 
-本地插件目录固定为 `./plugins`，不提供 CLI 或环境变量覆盖；每个插件从 `./plugins/<id>/dist` 加载，缺失时会在启动阶段尝试自动构建，相对路径按 `process.cwd()` 解析。
+本地插件目录固定为 `./plugins`，不提供 CLI 或环境变量覆盖；每个插件从 `./plugins/<id>/dist` 加载，每次启动或重启加载时都会尝试自动重建，失败时回退已有产物，相对路径按 `process.cwd()` 解析。
 
 ## 完整示例
 
@@ -151,7 +151,7 @@ npm run build
 node dist/app.js
 ```
 
-没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，启动时会先自动执行 `npm run build` 再加载；没有 `build` 脚本、缺少 `node_modules` 或构建失败时会记录警告并跳过。通过 `/plugin install` 安装的包会直接出现在 `plugins/<插件id>/`，与手动放在 `plugins/` 的本地插件没有区别；安装器管理的包应自带 `dist`，加载器不会为它们自动构建。安装状态、registry 和允许列表见[插件安装器](#插件安装器)。
+带有 `build` 脚本且依赖已安装的插件，无论 `dist` 是否已经存在，每次加载都会先自动执行 `npm run build`；构建失败或缺少 `node_modules` 时会回退加载已有 `dist`，没有可用 `dist` 时记录警告并跳过。没有 `build` 脚本的插件直接加载现有 `dist`。通过 `/plugin install` 安装的包会直接出现在 `plugins/<插件id>/`，与手动放在 `plugins/` 的本地插件使用同一套重建规则；安装包通常自带 `dist`，缺少构建依赖时会回退使用自带产物。安装状态、registry 和允许列表见[插件安装器](#插件安装器)。
 
 插件自己的配置字段由 `manifest.configSchema` 校验。例如一个 `demo` 插件：
 
@@ -179,7 +179,7 @@ npm run build:plugin
 npm run dev
 ```
 
-本地插件从 `plugins/<id>/dist` 自动加载；缺少 `dist` 时会先尝试构建。应用会跳过与内置插件同 ID 的本地插件。
+本地插件从 `plugins/<id>/dist` 自动加载；每次加载前都会尝试重建。应用会跳过与内置插件同 ID 的本地插件。
 
 ## 错误处理
 

package/docs/docker.md

@@ -0,0 +1,166 @@
+# Docker 部署
+
+Docker 镜像包含内核、内置插件、WebUI 静态资源和生产依赖，不包含配置、数据库和本地插件。这几项通过卷挂载持久化。
+
+## 镜像
+
+| 仓库       | 镜像                                          |
+| ---------- | --------------------------------------------- |
+| GHCR       | `ghcr.io/jsbot-dev/jsbot-tellus`              |
+| Docker Hub | `docker.io/<DOCKERHUB_USERNAME>/jsbot-tellus` |
+
+当前只提供 `linux/amd64`。标签规则：
+
+| 标签          | 说明                            |
+| ------------- | ------------------------------- |
+| `latest`      | 最近一次成功发布的新版本        |
+| `1.2.3`       | 完整版本号，对应 `package.json` |
+| `1.2`、`1`    | 主/次版本                       |
+| `sha-xxxxxxx` | 对应提交的短哈希                |
+
+同一个版本已经存在于某个镜像仓库时，CD 会跳过该仓库，不覆盖已有版本标签。`latest` 只会在发布新版本时移动。
+
+## 快速开始
+
+先准备配置目录。配置文件必须放在一个目录里挂载，不要单独挂载 `bot.config.json` 文件：WebUI 保存配置时会先写临时文件再原子重命名，单文件挂载会导致重命名失败。
+
+```bash
+mkdir -p config
+cp bot.config.example.json config/bot.config.json
+```
+
+本地没有源码时，可以直接从镜像取出示例配置：
+
+```bash
+docker run --rm --entrypoint cat \
+  ghcr.io/jsbot-dev/jsbot-tellus:latest \
+  /app/bot.config.example.json > config/bot.config.json
+```
+
+编辑 `config/bot.config.json`，至少填写 OneBot 的 `url`、`accessToken` 和 `roles`。然后使用仓库里的示例：
+
+```bash
+docker compose -f compose.example.yaml up -d
+```
+
+或者直接运行：
+
+```bash
+docker run -d --name jsbot \
+  --restart unless-stopped \
+  --init \
+  -p 127.0.0.1:8787:8787 \
+  -v "$PWD/config:/app/config" \
+  -v jsbot-data:/app/data \
+  -v jsbot-plugins:/app/plugins \
+  ghcr.io/jsbot-dev/jsbot-tellus:latest
+```
+
+查看日志：
+
+```bash
+docker compose -f compose.example.yaml logs -f
+# 或
+docker logs -f jsbot
+```
+
+## 路径和卷
+
+镜像内固定使用以下路径：
+
+| 容器路径          | 内容               | 说明                                              |
+| ----------------- | ------------------ | ------------------------------------------------- |
+| `/app/config`     | 配置文件目录       | 环境变量 `BOT_CONFIG=/app/config/bot.config.json` |
+| `/app/data`       | SQLite 数据库      | 环境变量 `BOT_DATA_DIR=/app/data`                 |
+| `/app/plugins`    | 本地和在线安装插件 | 固定目录，不可通过环境变量修改                    |
+| `/app/dist/webui` | WebUI 静态资源     | 随镜像构建                                        |
+
+`data` 和 `plugins` 建议使用命名卷；如果改成宿主目录，需要保证容器内用户可写。
+
+容器以非 root 的 `node` 用户运行，UID/GID 为 `1000:1000`。绑定宿主机目录时先授权：
+
+```bash
+mkdir -p data plugins
+sudo chown -R 1000:1000 data plugins config
+```
+
+## WebUI
+
+WebUI 默认关闭。容器内要让端口可达，配置需要监听 `0.0.0.0`：
+
+```json
+{
+    "webui": {
+        "enabled": true,
+        "host": "0.0.0.0",
+        "port": 8787,
+        "username": "admin",
+        "password": "至少 8 位"
+    }
+}
+```
+
+示例 compose 只把端口发布到宿主机 `127.0.0.1`。WebUI 是完全特权接口，远程访问请放在 HTTPS 反向代理后面，不要直接暴露到公网。反向代理时按需设置 `trustProxy`，详见 [WebUI 文档](webui.md)。
+
+不启用 WebUI 时可以删掉 compose 里的 `ports`，或者不传 `-p`。
+
+## 插件
+
+`plugins` 卷必须可写。在线安装器默认关闭；启用后 `/plugin install` 会在容器内调用 npm，把包安装到 `/app/plugins/<id>/`，因此容器需要能访问 npm registry：
+
+```json
+{
+    "installer": {
+        "enabled": true,
+        "registry": "https://registry.npmjs.org/"
+    }
+}
+```
+
+手动放入的本地插件也从 `/app/plugins/<id>/dist` 加载，并在每次启动或重启时尝试重建。镜像已经包含 npm；插件自己的依赖安装在各自的 `node_modules` 中，不需要把宿主机的 `node_modules` 挂进来。
+
+## 升级
+
+```bash
+docker compose -f compose.example.yaml pull
+docker compose -f compose.example.yaml up -d
+```
+
+需要固定版本时把镜像标签改成完整版本号，例如 `ghcr.io/jsbot-dev/jsbot-tellus:1.2.3`。升级前建议备份 `/app/data` 和 `/app/config`。
+
+## 本地构建
+
+```bash
+docker build -t jsbot-tellus .
+docker run --rm jsbot-tellus --help
+```
+
+本地开发时也可以直接挂载配置启动：
+
+```bash
+docker run --rm -it \
+  -v "$PWD/config:/app/config" \
+  -v "$PWD/data:/app/data" \
+  -v "$PWD/plugins:/app/plugins" \
+  jsbot-tellus
+```
+
+## 发布机制
+
+Docker 镜像由 [`.github/workflows/cd.yaml`](../.github/workflows/cd.yaml) 发布：
+
+- `main` 的 CI 成功、并且 npm 发布步骤成功或幂等跳过之后执行；
+- 同时推送 GHCR 和 Docker Hub；
+- 每个仓库独立检查版本标签，已存在则跳过，缺失的一侧会补推；
+- 构建带 GHA 缓存、provenance 和 SBOM，仅 `linux/amd64`。
+
+GHCR 使用 `GITHUB_TOKEN` 和 `packages: write`，不需要额外 Secret。Docker Hub 需要在仓库 Actions secrets 中配置 `DOCKERHUB_USERNAME` 和 `DOCKERHUB_TOKEN`（Read & Write Token）。CI 会在每次推送时构建镜像并做 smoke，但不会推送。完整发布流程见[发布流程](release.md)。
+
+## 故障排查
+
+- **启动提示找不到配置**：确认 `./config/bot.config.json` 存在，并且挂载到 `/app/config`。
+- **`EACCES` / `permission denied`**：确认宿主机上的 `config`、`data`、`plugins` 目录属于 UID 1000，或改用命名卷。
+- **WebUI 打不开**：确认配置里 `webui.enabled=true`、`host=0.0.0.0`，并且容器端口已发布到宿主机。
+- **在线安装插件失败**：确认 `installer.enabled=true`、容器能访问 registry，并且 `/app/plugins` 可写。
+- **GHCR 拉取 403/404**：首次发布后到仓库的 Packages 设置里把 `jsbot-tellus` 设为 public，或先 `docker login ghcr.io`。
+- **镜像架构不匹配**：当前镜像只有 `linux/amd64`，ARM 设备需要使用 amd64 模拟或自行构建。

package/docs/feature-parity.md

@@ -18,7 +18,7 @@
 
 ## 本地插件
 
-以下插件保留在本地，但不进入仓库，从 `plugins/<id>/dist` 自动加载（缺少 `dist` 时会先尝试自动构建）：
+以下插件保留在本地，但不进入仓库，从 `plugins/<id>/dist` 自动加载（每次加载前都会尝试自动重建）：
 
 | 能力 | 位置           | 说明                                         |
 | ---- | -------------- | -------------------------------------------- |
@@ -50,7 +50,7 @@
 - 插件 setup/start 失败可以回滚。
 - 长消息转 forward，短消息默认引用回复。
 - 配置错误包含路径，未知插件 ID 启动失败。
-- 本地插件可以从 `plugins/<id>/dist` 自动加载并执行；缺少 `dist` 且带有 `build` 脚本时会先自动构建。
+- 本地插件可以从 `plugins/<id>/dist` 自动加载并执行；带有 `build` 脚本时每次加载都会先自动重建，失败时回退已有 `dist`。
 - 已安装的 npm 插件包可以在自动重启后加载，安装失败会回滚。
 - 非 SuperAdmin 不能使用 `/plugin` 的任何子命令，包括 `help` 和 `list`。
 - `npm run build` 后 `node dist/app.js` 可用。

package/docs/migration.md

@@ -8,7 +8,7 @@
 
 - 安装本地依赖：`npm install --prefix plugins/poke`、`npm install --prefix plugins/llm`
 - 构建本地插件：`npm run build:plugin`
-- 启动时加载：应用会自动扫描 `plugins/<id>/dist`，不需要路径参数
+- 启动和重启时加载：应用会自动扫描 `plugins/<id>/dist`，不需要路径参数
 
 应用会跳过与内置插件同 ID 的本地插件。没有加载的插件不能出现在 `plugins` 配置中，否则会因未知插件 ID 启动失败。
 

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,12 +1,12 @@
 {
     "name": "@jsbot-tellus/core",
-    "version": "2.6.0",
+    "version": "2.8.0",
     "engines": {
         "node": "^24.22.1 || >=26.12.1"
     },
     "description": "a new version of JsBot",
     "keywords": [
-        "Cordis",
+        "SnowLuma",
         "Bot",
         "Typescript"
     ],
@@ -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",