@fengye_nobug/dsh-qq-bot 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,11 +1,17 @@
 # 更新日志
 
+## v0.2.5 — 2026-10-30
+
+- **设置卡片可以一键更新**：有新正式版时出现「更新到 vX.Y.Z」。点下去才安装，并重启面板。优先执行 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@版本`，走本机 npm / pnpm 已经配置的 registry。插件不写死镜像地址。registry 里找不到这个版本时，改从 GitHub 下载官方源码包（先 github.com，连不上再试同一标签的 codeload.github.com），不走第三方镜像。v0.2.3 及更早标签里的 `package.json` 仍是无作用域名，这种源码包仍然能装。装完提示刷新页面，登录口令可能会变。现有设置还在，不改 NapCat。已经是最新时没有这个按钮。不会安装更旧的版本，也不装草稿和预发布。连不上、安装失败、没能重启，都用白话说明。
+- **「检查更新」和「启动时检查一次」仍然只询问**：不下载、不安装。先问 npm 上的 `@fengye_nobug/dsh-qq-bot`。有比当前新的正式版时不再访问 GitHub。npm 上没有更新，或包还连不上时，才看 GitHub Releases。
+- **npm 包名改为 `@fengye_nobug/dsh-qq-bot`**：无作用域的 `dsh-qq-bot` 发不出去，npm 认为它和已有的 `dsh-qqbot` 太像。npm 上已经发出的是 `@fengye_nobug/dsh-qq-bot@0.2.4`。源码 0.2.5 还没发到 npm，GitHub Release 仍是 v0.2.3。界面显示名和消息来源 `plugin:dsh-qq-bot` 不变，Cordis id 仍是 `qq-bridge`。不要再用 `dsh plugin add dsh-qq-bot@版本`。
+
 ## v0.2.4 — 2026-10-30
 
 - **设置页可以检查 GitHub 上有没有新版本**：卡片显示当前版本。点「检查更新」才请求 `yunfengnobug/dsh-qq-bot` 的 Releases，按 semver 对比。有新版时写出最新版本号、说明摘要，以及 `github:yunfengnobug/dsh-qq-bot#vX.Y.Z` 的安装命令。没有新版、连不上、被限流，都用白话说明，不把英文报错摆到界面上。不会自动下载或安装。
 - **新设置「启动时检查一次」**（`checkUpdateOnStart`，默认 `false`）：打开并保存后，下次启动 dsh-web 向 GitHub 问一次，只写日志。默认关。
 - **安装说明**：README 写清推荐用 Release tag（已发布的是 `v0.2.3`）、Watch Releases、最低环境、白名单先填再 @、三条升级路径（面板升级 / `#vX.Y.Z` / 重装后重启 dsh-web）、与官方 `sj244/dsh-qq-bridge` 不能同时挂同一个 OneBot，以及以后的发版流程（改版本号 → CHANGELOG → tag `vX.Y.Z` → GitHub Release）。
-- **npm 与插件市场**：`package.json` 补了 `publishConfig.access`（`public`）和 `engines.node`（`>=22`），`files` 白名单含更新检查模块和 CHANGELOG。维护者用 `npm login` 后自己 `npm publish`，本仓库不代发。包发布之后，用户可以 `dsh plugin --profile web add dsh-qq-bot@<版本>`；没发布时仍用 GitHub Release。本 fork 还没进 awesome-dsh-plugin，申请步骤和 Issue 模板（连不上 / 不回 / 发不出）写在 README。
+- **npm 与插件市场**：`package.json` 补了 `publishConfig.access`（`public`）和 `engines.node`（`>=22`），`files` 白名单含更新检查模块和 CHANGELOG。维护者用 `npm login` 后自己 `npm publish`，本仓库不代发。当时写的安装命令是无作用域的 `dsh-qq-bot@<版本>`。这个名字发不出去，实际包名和命令见 v0.2.5。本 fork 还没进 awesome-dsh-plugin，申请步骤和 Issue 模板（连不上 / 不回 / 发不出）写在 README。
 
 ## v0.2.3 — 2026-10-30
 

package/DESIGN.md

@@ -1,6 +1,6 @@
 # dsh-qq-bot 设计草案
 
-> 本文记录上游 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge) 的设计。本 fork 的包名是 dsh-qq-bot，Cordis 插件 id 仍是 `qq-bridge`。文中的 `qq-bridge` 是插件 id，不是包名。上游许可证为 MIT，版权归 sj244。
+> 本文记录上游 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge) 的设计。本 fork 的 npm 包名是 `@fengye_nobug/dsh-qq-bot`（无作用域的 `dsh-qq-bot` 发不出去，它和已有的 `dsh-qqbot` 太像）。界面显示名仍是 dsh-qq-bot。Cordis 插件 id 仍是 `qq-bridge`。文中的 `qq-bridge` 是插件 id，不是包名。上游许可证为 MIT，版权归 sj244。
 
 > 目标：把 **一个指定的、已存在的 DSH 会话**（当前目标：
 > `<TARGET_SESSION_ID>`，<TARGET_WORKSPACE> 工作区）

package/README.md

@@ -8,9 +8,13 @@
 
 本仓库 fork 自 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge)。上游许可证为 MIT，版权归 sj244；本 fork 的版权声明见 [`LICENSE`](./LICENSE)。安装和更新都走 `dsh plugin`，不要在服务器上打补丁脚本。
 
-**Cordis 插件 id 仍是 `qq-bridge`**（`cordis.patch.yml` 里的 `id`）。包名和界面显示名是 **dsh-qq-bot**。已有 profile 里按 `id: qq-bridge` 写的覆盖继续生效。设置命名空间、状态文件和 `/api/qq-bridge/...` 也沿用这个 id，避免升级时对不上。
+**Cordis 插件 id 仍是 `qq-bridge`**（`cordis.patch.yml` 里的 `id`）。npm 包名是 **`@fengye_nobug/dsh-qq-bot`**。界面显示名仍是 **dsh-qq-bot**，消息来源仍是 `plugin:dsh-qq-bot`。无作用域的 `dsh-qq-bot` 发不出去：npm 认为它和已有的 `dsh-qqbot` 太像。已有 profile 里按 `id: qq-bridge` 写的覆盖继续生效。设置命名空间、状态文件和 `/api/qq-bridge/...` 也沿用这个 id，避免升级时对不上。
 
-**想装：** 用已经发布的 tag，不要盯着 main。
+**想装：** 优先用 npm 上已经发出的版本。连不上 npm，或 registry 里还没有这一版时，再用已经发布的 GitHub tag，不要盯着 main。
+
+```sh
+dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.4
+```
 
 ```sh
 dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
@@ -19,7 +23,7 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
 在 GitHub 上 Watch → Custom → **Releases**，比盯 main 稳。环境、第一次怎么开白名单、怎么升级、和官方插件为什么不能一起挂，写在[安装](#安装)。
 
 - 设计：[`DESIGN.md`](./DESIGN.md) ｜ 里程碑与真机实录：[`HANDOVER.md`](./HANDOVER.md) ｜ 变更：[`CHANGELOG.md`](./CHANGELOG.md)
-- 源码版本 **0.2.4**（设置页可以检查更新）。GitHub 上已发布的稳定版仍是 **v0.2.3**，日常安装用上面的 `#v0.2.3`。打出新的 Release 之后，把命令里的 tag 换成那一版；卡片上的「检查更新」也会给出当时的安装命令。见 [`CHANGELOG.md`](./CHANGELOG.md)。
+- 源码版本 **0.2.5**（设置页可以一键更新）。npm 上已经发出的是 **`@fengye_nobug/dsh-qq-bot@0.2.4`**。GitHub 上已发布的稳定版仍是 **v0.2.3**。源码这一版还没打 tag，也还没 `npm publish`。卡片上的「更新到 vX.Y.Z」安装 `@fengye_nobug/dsh-qq-bot@版本`。见 [`CHANGELOG.md`](./CHANGELOG.md)。
 - **M1–M8 全部完成**，已在**真实 NapCat + 真实 QQ** 上端到端跑通（Windows 真机）
 
 ## 目录
@@ -45,6 +49,7 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
   也认 `[表情182]` 和 `[CQ:face,id=182]`。详见[出站](#出站三种模式--来源闸门)。
 - **有设置卡片**：名称是白话（哪些群可以叫醒、群里发出去的是哪一段、忙的时候怎么插话等），
   配置键仍是英文。在 `设置 → 插件 → 插件配置` 里修改，保存即生效。
+- **可以一键更新**：先点「检查更新」。有新正式版时再点「更新到 vX.Y.Z」，面板会装上并重启。优先从 npm 安装 `@fengye_nobug/dsh-qq-bot@版本`；这一版还没发到 npm 时，改从 GitHub 下载。启动时检查不会自动安装。
 - **NapCat 自助托管**：插件可以按需下载、校验、解包、写配置、启停 NapCat。
 
 **不做的三件事**：
@@ -55,7 +60,13 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
 
 ## 安装
 
-稳定版看 [Releases](https://github.com/yunfengnobug/dsh-qq-bot/releases)。已经发出的是 **v0.2.3**。仓库源码如果已经是 0.2.4，那是 main 上还没打 tag 的版本，日常不要装 main。
+日常安装用 npm 上已经发出的 **`@fengye_nobug/dsh-qq-bot@0.2.4`**。无作用域的 `dsh-qq-bot@版本` 装不上：npm 不接受这个名字，它和已有的 `dsh-qqbot` 太像。GitHub [Releases](https://github.com/yunfengnobug/dsh-qq-bot/releases) 上已经发出的是 **v0.2.3**。仓库源码如果已经是 0.2.5，那是还没打 tag、也还没发到 npm 的版本，日常不要装 main。某一版还没出现在 registry 里时，一键更新会改从 GitHub 下载。
+
+```sh
+dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.4
+```
+
+GitHub 备用：
 
 ```sh
 dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
@@ -85,11 +96,20 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot
 
 ### 升级
 
-三条路。装完都要重启 dsh-web：
+四条路。装完都要让 dsh-web 重新加载插件：
+
+1. 设置卡片里先点「检查更新」。有新正式版时出现「更新到 vX.Y.Z」。点下去优先执行 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@X.Y.Z`，走这台机器上 pnpm 已经配置的 registry，然后重启面板。设置还在，不改 NapCat。重启后刷新页面；登录口令可能会变。
+2. 自己执行同一条命令。npm 上已经发出的是 `@fengye_nobug/dsh-qq-bot@0.2.4`。
+3. 指定 GitHub tag：`dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#vX.Y.Z`
+4. 卸掉再装，然后重启。
 
-1. 面板的插件管理里升级（有这个入口再用）。
-2. 指定新 tag：`dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#vX.Y.Z`
-3. 卸掉再装同一条命令，然后重启。
+无作用域名字发不出去。第 1 步如果发现 registry 里没有 `@fengye_nobug/dsh-qq-bot` 的这一版，会改从 GitHub 下载该标签的官方源码包：先 `github.com`，连不上再试同一标签的 `codeload.github.com`，然后交给 `dsh plugin add`。v0.2.3 及更早标签里的 `package.json` 仍是无作用域名，这种源码包仍然能装。插件不写死第三方镜像。registry 里已经有比当前新的正式版时，检查和安装不再访问 GitHub。
+
+「检查更新」和「启动时检查一次」只询问，不会安装。已经是最新正式版时不出现更新按钮。不会装比当前更旧的版本，也不装草稿和预发布。连不上、安装失败、面板没能重启，都用白话说明。安装已经成功但没能安排重启时，新版本在磁盘上，需要自己重启 dsh-web。
+
+在 Linux 上，进程由 systemd 拉起并且能认出具体服务时，大约 3 秒后只重启那个服务。只看到用户会话、认不出单独服务时，请自己重启 dsh-web。没有被 systemd 拉起时，响应发出后按当前的 node 命令行再拉起一次。这次更新不改 NapCat 的配置，也不去停它。插件自己拉起的 NapCat 会随 dsh-web 退出而结束；已经在外面跑着的 NapCat 继续运行。
+
+想让 npm 走镜像，把 npm / pnpm 的 registry 配成你自己的镜像。插件只在没读到配置时用 `https://registry.npmjs.org/`。
 
 ### 不要和官方插件一起挂
 
@@ -99,9 +119,11 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot
 
 ```sh
 dsh plugin --profile web remove dsh-qq-bridge
-dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
+dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.4
 ```
 
+连不上 npm 时，把上面第二条换成 `dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3`。
+
 然后重启 dsh-web。profile 里原来按 `id: qq-bridge` 写的覆盖可以留着。`list` 里如果包名不是 `dsh-qq-bridge`，卸你看到的那一个官方包，不要卸别的插件。
 
 ### 开发期
@@ -132,28 +154,30 @@ New-Item -ItemType Junction `
 4. 在含这个版本号的提交上打 annotated tag：`vX.Y.Z`。
 5. 用 CHANGELOG 里对应那一节的中文摘要发 GitHub Release。
 
-Release 不附带密钥、日志或本机文件。源码压缩包让 GitHub 自己生成即可，不必另外上传。用户侧安装始终用 `#vX.Y.Z`，不要把 main 当稳定版。npm 不是这条流程的必经步骤，见[用 npm 安装](#用-npm-安装)。
+Release 不附带密钥、日志或本机文件。源码压缩包让 GitHub 自己生成即可，不必另外上传。用户侧安装优先用 npm 上的 `@fengye_nobug/dsh-qq-bot@版本`，不要把 main 当稳定版。见[用 npm 安装](#用-npm-安装)。
 
 ## 用 npm 安装
 
-日常请用上面的 GitHub Release。`dsh plugin` 是 pnpm 的包装；维护者把包发到 npm 之后，也可以按包名装：
+`dsh plugin` 是 pnpm 的包装。安装和一键更新都用作用域包名。npm 上已经发出的是 0.2.4：
 
 ```sh
-dsh plugin --profile web add dsh-qq-bot@0.2.4
+dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.4
 ```
 
-包还没发布时这条会失败，改回 GitHub：
+无作用域的 `dsh-qq-bot` 发不出去，npm 认为它和已有的 `dsh-qqbot` 太像。不要写成 `dsh plugin add dsh-qq-bot@版本`。
+
+registry 里还没有要装的那一版时（源码 0.2.5 尚未发布），改用 GitHub：
 
 ```sh
 dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
 ```
 
-某台机器上的 `dsh plugin --help` 如果只认 `github:`，就继续用 Release tag。GitHub 是主路径，npm 是辅路径。
+一键更新的顺利路径是 npm，不再要求打开 github.com。某台机器上的 `dsh plugin --help` 如果只认 `github:`，就继续用 Release tag。想用镜像，配置这台机器的 npm / pnpm registry，不要等插件内置一个镜像地址。
 
-维护者自己发布（仓库里没有 npm token，也不会在 CI 里代发）：
+维护者发布下一版（仓库里没有 npm token，也不会在 CI 里代发）：
 
 1. `npm login`
-2. 确认 `package.json` 的 `version` 和要发的 tag 一致。
+2. 确认 `package.json` 的 `name` 是 `@fengye_nobug/dsh-qq-bot`，`version` 和要发的 tag 一致。
 3. `npm pack --dry-run`，看清单里没有测试、密钥、本机路径。
 4. `npm publish`
 
@@ -161,7 +185,7 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
 
 ## 插件市场
 
-[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 里已经有上游 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge)。本 fork 还没进索引，所以现在用 GitHub Release 安装。
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 里已经有上游 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge)。本 fork 还没进索引。安装不必等收录，用上面的 `@fengye_nobug/dsh-qq-bot` 即可。
 
 要申请收录，按[贡献说明](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)做：
 
@@ -169,7 +193,7 @@ dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.3
 2. 把本仓库的 [`docs/awesome-dsh-plugin-entry.yml`](./docs/awesome-dsh-plugin-entry.yml) 复制成对方仓库的 `data/plugins/yunfengnobug__dsh-qq-bot.yml`，提一个 PR。不要改上游那条。一个 PR 最多 3 条。对方的 README 由脚本生成，不要手改。
 3. 描述只写插件实际做的事。`repository` 必须指回本仓库（`package.json` 里已经是了）。yml 里不要手写 `npm:`，市场自己从 registry 认。
 
-npm 发布是可选的。发了，市场才能显示下载量；不发也能收录，安装仍走 GitHub。
+npm 上已经有 `@fengye_nobug/dsh-qq-bot`（目前是 0.2.4）。无作用域名发不出去。发到 npm 之后，市场才能显示下载量；不发也能收录。
 
 用着有问题，到 [Issues](https://github.com/yunfengnobug/dsh-qq-bot/issues/new/choose) 选模板：**连不上**、**不回**、**发不出**。不要在 Issue 里贴真实 QQ 号、群号、token 或服务器地址。
 
@@ -447,9 +471,11 @@ QQ 的“拍一拍”在 OneBot 里走的是 **notice 事件**，不是消息段
 > 宿主 `requestRejection()` 返回空、`undefined` 或 `0` **不算**已登录。已登录只认宿主明确给出的结果：`isAuthenticated`、浏览器会话，或 `admit()` 交回的身份。没有这个结果的外网请求是 403。来源是别的网站、和 `Host` 对不上的请求也是 403，就算带着 cookie 也不行。接口只写 schema 白名单里的键。
 > 判断面板监听器是不是 HTTPS 时，只通过 `ctx.get('webServer')` 读协议，不读 `ctx.webServer`。插件没有把 `webServer` 放进 inject。直接读这个属性会抛错，宿主会把这次请求收成**没有正文的 HTTP 400**，卡片诊断就显示本机接口不可用，即使浏览器里已经登录。读不到这项服务、或读取失败时，按 HTTP 继续做登录判定。
 
-卡片上方显示**当前版本**，并有一个 **检查更新** 按钮。它向本仓库的 GitHub Releases 问一次（`GET/POST /api/qq-bridge/update`，准入和设置接口相同）。GET 只读当前版本，不去 GitHub；只有点按钮的 POST 才去对比。有新版时写出最新版本号、Release 说明摘要，以及 `github:yunfengnobug/dsh-qq-bot#vX.Y.Z` 的安装命令。没有新版、连不上、被 GitHub 限流，都用白话说明。不会自动下载或安装。
+卡片上方显示**当前版本**，并有 **检查更新**。接口是 `GET/POST /api/qq-bridge/update`，准入和设置接口相同。GET 只读当前版本，不去 npm，也不去 GitHub。POST 不带 `action` 才对比版本：先问 npm registry 里的 `@fengye_nobug/dsh-qq-bot` 正式版。有比当前新的版本时，写出版本号和 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@x.y.z`，并且不再访问 GitHub。npm 上还没有更新、但 GitHub Release 上有更新时，才改问 GitHub，并说明一键更新会从 GitHub 下载。没有新版、连不上、被限流，都用白话说明。检查本身不会下载或安装。
+
+有新版时出现 **更新到 vX.Y.Z**。点下去才发送 `POST { "action": "apply", "version": "x.y.z" }`。优先 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@x.y.z`。registry 里没有这个版本时，改从 GitHub 的官方源码包装上，再重启面板。按钮下面写着：设置还在，不改 NapCat；重启后请刷新，登录口令可能会变。进行中显示「正在更新…」。已经是最新正式版时没有这个按钮。
 
-「启动时检查一次」默认关。打开并保存后，下次启动 dsh-web 才问一次，结果只写在日志里。
+「启动时检查一次」默认关。打开并保存后，下次启动 dsh-web 才问一次，结果只写在日志里，不会安装。
 
 卡片展开后还有 3 个操作按钮（0.1.5 与 0.2.0 上都有）：
 
@@ -497,10 +523,10 @@ QQ 的“拍一拍”在 OneBot 里走的是 **notice 事件**，不是消息段
 | `napcatInstallDir` | `''` | NapCat 安装目录；空 = `$DSH_HOME/napcat`。自己装的或 Docker 里的请填实际目录 |
 | `napcatWebuiUrl` | `''` | NapCat 网页管理地址。空 = 读 `webui.json`（通常是 `127.0.0.1`，只有跑着 NapCat 的机器能打开）。远程使用时填外面打得开的地址 |
 | `napcatVersion` | `''` | 要下载的 NapCat 版本；空 = 最新 |
-| `downloadProxy` | `''` | 下载时走的代理；空 = 读环境变量 |
+| `downloadProxy` | `''` | 下载时走的代理；空 = 先看 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY`。NapCat 下载，以及一键更新改从 GitHub 下载时，都用它。从 npm 安装时走 pnpm 自己的 registry，不读这个框。界面上不显示代理地址 |
 | `onebotPort` | `3001` | OneBot 端口。自己另外部署的 NapCat 要和这边一致 |
 | `qqNumber` | `''` | 快速登录用的 QQ 号（需先手动登录过一次） |
-| `checkUpdateOnStart` | `false` | 启动时检查一次。默认关。打开后，下次启动 dsh-web 向 GitHub 问一次有没有新版本，只写日志，不自动安装。平时用卡片上的「检查更新」 |
+| `checkUpdateOnStart` | `false` | 启动时检查一次。默认关。打开后，下次启动先问 npm 上的 `@fengye_nobug/dsh-qq-bot`；npm 上还没有更新时再问 GitHub。只写日志，不自动安装。要装用卡片上的「更新到 vX.Y.Z」 |
 
 这些值优先从设置界面 / `settings.yaml` 取，未设置时回落到 `cordis.patch.yml` 里的安装配置（composition base）。
 
@@ -513,7 +539,7 @@ QQ 的“拍一拍”在 OneBot 里走的是 **notice 事件**，不是消息段
 1. `package.json` 里的 `dsh.client` 还在；
 2. **重启过 `dsh web`**。浏览器端的内容是启动时读盘并计算指纹的，修改后必须重启；
 3. **重启之后刷新过页面（F5）**。清单是页面加载时注入的，只重启服务器时，已经打开的页面手里还是旧清单；
-4. DSH 版本：0.2.0 把客户端设置服务从 `settingsScope` 改名为 `webUiSettings`，插件配置页的挂载点从 `settings.plugin.item` 改成 `settings.plugins.tab`。有的 0.2.x 上这两个服务都不存在，`ctx.inject` 会一直等。本插件**不等它们**：`apply` 时就挂上卡片。宿主设置域还在就用它；否则读写 `/api/qq-bridge/settings`。挂载点有四个：`settings.plugins.tab`、`settings.plugin.item`、`plugins.tab`、`plugins.detail.section`（详情页只在本包 `dsh-qq-bot`、旧包名 `dsh-qq-bridge`，或 id `qq-bridge` 上显示）。卡片默认展开。
+4. DSH 版本：0.2.0 把客户端设置服务从 `settingsScope` 改名为 `webUiSettings`，插件配置页的挂载点从 `settings.plugin.item` 改成 `settings.plugins.tab`。有的 0.2.x 上这两个服务都不存在，`ctx.inject` 会一直等。本插件**不等它们**：`apply` 时就挂上卡片。宿主设置域还在就用它；否则读写 `/api/qq-bridge/settings`。挂载点有四个：`settings.plugins.tab`、`settings.plugin.item`、`plugins.tab`、`plugins.detail.section`（详情页在 npm 包 `@fengye_nobug/dsh-qq-bot`、旧包名 `dsh-qq-bot` 和 `dsh-qq-bridge`，或 id `qq-bridge` 上显示）。卡片默认展开。
 
 > 卡片按 settings 命名空间派发，`client/client.js` 里的 key 必须逐字等于 `qq-bridge`。
 > 对不上不会报错，只是静默不显示（`test-smoke.mjs` 包含该一致性的断言）。
@@ -598,14 +624,14 @@ QQ 侧没有人能点击“同意”，因此：
 
 改用法、设置或运行行为时，同一次提交里更新本文件。约定见 [`AGENTS.md`](./AGENTS.md)。
 
-5 个套件都是**零依赖**（测试自己造 zip、自己起一个最小 OneBot WS 服务器；检查更新不连真 GitHub），共 **718 条断言**：
+5 个套件都是**零依赖**（测试自己造 zip、自己起一个最小 OneBot WS 服务器；检查更新不连真 npm、也不连真 GitHub），共 **778 条断言**：
 
 ```powershell
-node test-smoke.mjs     # 策略分支 + 出站闸门 + 描述缓存命中 + 表情包工具（含 mface）+ 系统表情分段 + 设置卡片字段 + 检查更新接口（假 ctx，纯离线）
+node test-smoke.mjs     # 策略分支 + 出站闸门 + 描述缓存命中 + 表情包工具（含 mface）+ 系统表情分段 + 设置卡片字段 + 检查更新和一键安装接口（假 ctx，纯离线）
 node test-onebot.mjs    # M2 端到端：内置最小 OneBot WS 服务器，验证收发全链路
 node test-napcat.mjs    # M5：ZIP 解包 / sha256 校验 / 发行包选择 / 配置写入
 node test-stickers.mjs  # 表情包登记表：哈希 / 读写 / 查找 / 原子写 / importSticker / mface 字段
-node test-updates.mjs   # 检查更新：semver 比较、Release 摘要、限流和断网的白话
+node test-updates.mjs   # 检查更新和一键安装：semver、npm 正式版、GitHub 备用下载、限流和断网的白话
 ```
 
 ## 路线

package/client/client.js

@@ -13,12 +13,12 @@
  *   参考实现：第三方插件 `dshmarket` 的 `client/client.js`（同样是手写/预构建产物）。
  *
  * 与宿主半的约定：
- *   - `id` 必须等于包名 `dsh-qq-bot`；
+ *   - `id` 必须等于 npm 包名 `@fengye_nobug/dsh-qq-bot`；
  *   - 卡片注册进 `settings.plugin.item`，**key 必须等于宿主注册的 settings 命名空间** `qq-bridge`，
  *     否则配置页那一栏里什么都不会出现（它按命名空间派发）。
  */
 window.__ModuleLoader__.load({
-  id: 'dsh-qq-bot',
+  id: '@fengye_nobug/dsh-qq-bot',
   factory: (require) => {
     var module = { exports: {} }
     var exports = module.exports
@@ -38,7 +38,7 @@ window.__ModuleLoader__.load({
         key: 'checkUpdateOnStart',
         label: '启动时检查一次',
         kind: 'boolean',
-        hint: '默认关。打开并保存后，下次启动 dsh-web 会向 GitHub 问一次有没有新版本，只写在日志里，不会自动安装。平时用上面的「检查更新」就够了。',
+        hint: '默认关。打开并保存后，下次启动 dsh-web 会先问 npm 上的 @fengye_nobug/dsh-qq-bot 有没有新版本；npm 上还没有更新时再看 GitHub。只写在日志里，不会自动安装。要装新版本，用检查之后出现的更新按钮。',
       },
       {
         key: 'sessionScope',
@@ -358,6 +358,8 @@ window.__ModuleLoader__.load({
       const [pluginVersion, setPluginVersion] = react.useState('')
       const [versionState, setVersionState] = react.useState('loading')
       const [updateBusy, setUpdateBusy] = react.useState(false)
+      const [updateKind, setUpdateKind] = react.useState('')
+      const [updateOffer, setUpdateOffer] = react.useState(null)
       const [updateNote, setUpdateNote] = react.useState('')
       const [updateIsError, setUpdateIsError] = react.useState(false)
 
@@ -449,9 +451,11 @@ window.__ModuleLoader__.load({
       }
 
       async function checkForUpdate() {
+        setUpdateKind('check')
         setUpdateBusy(true)
         setUpdateNote('')
         setUpdateIsError(false)
+        setUpdateOffer(null)
         try {
           if (typeof fetch !== 'function') {
             setUpdateIsError(true)
@@ -474,11 +478,56 @@ window.__ModuleLoader__.load({
           const ok = body.ok === true
           setUpdateIsError(!ok)
           setUpdateNote(plainUpdateText(ok ? body.message : body.error, ok))
+          const tag = typeof body.tag === 'string' ? body.tag : ''
+          const version = typeof body.latest === 'string' ? body.latest : ''
+          if (ok && body.updateAvailable === true && tag !== '' && version !== '') {
+            setUpdateOffer({ tag, version })
+          }
         } catch {
           setUpdateIsError(true)
           setUpdateNote('连不上本机的检查更新接口。确认 dsh-web 在跑，稍后再试。')
         } finally {
           setUpdateBusy(false)
+          setUpdateKind('')
+        }
+      }
+
+      async function applyUpdate() {
+        if (!updateOffer) return
+        const version = updateOffer.version
+        const tag = updateOffer.tag
+        setUpdateKind('apply')
+        setUpdateBusy(true)
+        setUpdateNote('')
+        setUpdateIsError(false)
+        try {
+          if (typeof fetch !== 'function') {
+            setUpdateIsError(true)
+            setUpdateNote('这个页面没有网络接口，装不了更新。')
+            return
+          }
+          const res = await fetch(UPDATE_API, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { accept: 'application/json', 'content-type': 'application/json' },
+            body: JSON.stringify({ action: 'apply', version }),
+          })
+          const body = await res.json().catch(() => null)
+          if (!body || typeof body !== 'object') {
+            setUpdateIsError(true)
+            setUpdateNote('更新没有返回能看懂的结果。稍后再试。')
+            return
+          }
+          const ok = body.ok === true
+          setUpdateIsError(!ok)
+          setUpdateNote(plainUpdateText(ok ? body.message : body.error, ok))
+          if (ok) setUpdateOffer(null)
+        } catch {
+          setUpdateIsError(true)
+          setUpdateNote(`更新到 ${tag} 的请求没返回。如果面板马上断开，多半是正在重启，请稍后刷新；登录口令可能会变。如果还是旧版本，再点一次。`)
+        } finally {
+          setUpdateBusy(false)
+          setUpdateKind('')
         }
       }
 
@@ -794,10 +843,27 @@ window.__ModuleLoader__.load({
                 checkForUpdate()
               },
             },
-            updateBusy ? '检查中…' : '检查更新',
+            updateBusy && updateKind === 'check' ? '检查中…' : '检查更新',
           ),
+          updateOffer
+            ? h(
+                'button',
+                {
+                  type: 'button',
+                  style: disabled({ ...S.btn, ...S.primary }, updateBusy),
+                  disabled: updateBusy,
+                  onClick: () => {
+                    applyUpdate()
+                  },
+                },
+                updateBusy && updateKind === 'apply' ? '正在更新…' : `更新到 ${updateOffer.tag}`,
+              )
+            : null,
         ),
-        h('div', { style: S.hint }, '向 GitHub 问一次有没有新版本。不会自动下载，也不会自动安装。'),
+        h('div', { style: S.hint }, '先问 npm 上有没有新版本。这里只检查，不会安装。'),
+        updateOffer
+          ? h('div', { style: S.hint }, '优先从 npm 安装 @fengye_nobug/dsh-qq-bot 的这一版并重启面板。这一版还没发到 npm 时，会改从 GitHub 下载。设置还在，不改 NapCat。重启后请刷新，登录口令可能会变。')
+          : null,
         updateNote
           ? h('div', { style: { ...(updateIsError ? S.err : S.note), whiteSpace: 'pre-wrap' } }, updateNote)
           : null,
@@ -866,7 +932,7 @@ window.__ModuleLoader__.load({
     const API_PATH = '/api/qq-bridge/settings'
     /** NapCat 操作接口（宿主半不受 legacy 门控，两代宿主都挂）。 */
     const NAPCAT_API = '/api/qq-bridge/napcat'
-    /** 检查更新。GET 只读当前版本，POST 才访问 GitHub。 */
+    /** 检查更新。GET 只读当前版本；POST 不带 action 只检查。安装要另发 action 为 apply。浏览器不直接访问 npm 或 GitHub。 */
     const UPDATE_API = '/api/qq-bridge/update'
     /** 稳定引用：useSyncExternalStore 的 getSnapshot 每次返回新对象会死循环。 */
     const LOADING_SNAPSHOT = { status: 'loading' }
@@ -975,7 +1041,7 @@ window.__ModuleLoader__.load({
       const candidates = []
       // 0.2.0 的表单 key 到底叫什么，源码里能看到的写法**全试一遍**（谁 ready 用谁）：
       // settings 命名空间 / profile entry id / 包名，以及带 include: 前缀的两种。
-      for (const namespace of [NS, `include:${NS}`, 'dsh-qq-bot', 'include:dsh-qq-bot', 'dsh-qq-bridge', 'include:dsh-qq-bridge']) {
+      for (const namespace of [NS, `include:${NS}`, '@fengye_nobug/dsh-qq-bot', 'include:@fengye_nobug/dsh-qq-bot', 'dsh-qq-bot', 'include:dsh-qq-bot', 'dsh-qq-bridge', 'include:dsh-qq-bridge']) {
         try {
           const scope = service.bind({ namespace })
           if (scope && typeof scope === 'object') candidates.push({ namespace, scope })
@@ -1064,12 +1130,12 @@ window.__ModuleLoader__.load({
     function subjectIsOurs(subject) {
       if (!subject || typeof subject !== 'object') return false
       const pkgName = subject.pkg && typeof subject.pkg === 'object' ? String(subject.pkg.name ?? '') : ''
-      if (pkgName === 'dsh-qq-bot' || pkgName === 'dsh-qq-bridge') return true
+      if (pkgName === '@fengye_nobug/dsh-qq-bot' || pkgName === 'dsh-qq-bot' || pkgName === 'dsh-qq-bridge') return true
       const id = String(subject.id ?? '')
-      if (id === NS || id === 'dsh-qq-bot' || id === 'dsh-qq-bridge') return true
+      if (id === NS || id === '@fengye_nobug/dsh-qq-bot' || id === 'dsh-qq-bot' || id === 'dsh-qq-bridge') return true
       if (subject.kind === 'item' && id.includes('qq-bridge')) return true
       const pkg = String(subject.package ?? subject.packageName ?? '')
-      return pkg === 'dsh-qq-bot' || pkg === 'dsh-qq-bridge'
+      return pkg === '@fengye_nobug/dsh-qq-bot' || pkg === 'dsh-qq-bot' || pkg === 'dsh-qq-bridge'
     }
 
     /**
@@ -1194,7 +1260,7 @@ window.__ModuleLoader__.load({
     exports.inject = inject
     // 导出 name：Cordis 用它做插件标识，Slots inspect 里的 registrant 会显示成它
     // （不导的话那边显示的是产物里的 fallback 短名，排障时认不出是谁注册的卡片）。
-    exports.name = 'dsh-qq-bot'
+    exports.name = '@fengye_nobug/dsh-qq-bot'
     // 纯函数给离线测试用（test-smoke.mjs 会在假 ctx 里真跑这个 bundle）。
     // Cordis 只认 apply / inject / name / Config，多余的导出它不管。
     exports.__test = { sessionOptions, draftFrom, parse, fields: FIELDS, bindSettings }

package/index.js

@@ -41,7 +41,7 @@ import {
   upsertSticker,
 } from './stickers.js'
 import { FACE_NAME_TO_ID, textToOneBotSegments } from './faces.js'
-import { checkPluginUpdate } from './updates.js'
+import { applyPluginUpdate, checkPluginUpdate } from './updates.js'
 
 const require = createRequire(import.meta.url)
 /** 当前安装的包版本。设置页和检查更新都读这一处，避免卡片里手写一份。 */
@@ -100,8 +100,8 @@ const PACKAGE_LEGACY = 'dsh-qq-bridge'
 export function injectedMessageSource(legacy) {
   return legacy ? { kind: 'plugin', plugin: PLUGIN_TAG } : { kind: `plugin:${PACKAGE}` }
 }
-/** 包名：与 `client/client.js` 里 `__ModuleLoader__.load({id})` 的值必须一致。 */
-const PACKAGE_NAME = 'dsh-qq-bot'
+/** npm 包名：与 `client/client.js` 里 `__ModuleLoader__.load({id})` 的值必须一致。 */
+const PACKAGE_NAME = '@fengye_nobug/dsh-qq-bot'
 const MAX_BUFFER = 200
 const MAX_LOG = 200
 const MAX_OUTBOX = 50
@@ -3886,9 +3886,37 @@ export function apply(ctx, config) {
   }
 
   /**
-   * 检查更新。GET 只报当前版本，不去 GitHub。POST 才问 Releases。
-   * 有新版只返回说明和安装命令，不下载、不安装。
-   * 两代宿主都挂：按钮跟“设置存在哪”无关。
+   * 把检查或安装的结果收成卡片用的字段。不把临时路径、堆栈或代理地址带出去。
+   * @param {Record<string, unknown>} result
+   */
+  function presentUpdate(result) {
+    const body = {
+      ok: result.ok === true,
+      current: result.current || PLUGIN_VERSION,
+      latest: result.latest || result.version || '',
+      updateAvailable: result.updateAvailable === true,
+      summary: result.summary || '',
+      install: result.install || '',
+      command: result.command || '',
+      url: result.url || '',
+      tag: result.tag || '',
+      message: result.message || '',
+    }
+    if (result.applied === true) body.applied = true
+    if (result.restarting === true) body.restarting = true
+    if (result.installed === true) body.installed = true
+    if (result.stage) body.stage = result.stage
+    if (result.ok !== true) body.error = String(result.error || result.message || '更新没有完成。稍后再试。')
+    return body
+  }
+
+  /**
+   * 检查更新，以及在用户点了安装之后才装。
+   * GET 只报当前版本，不去 GitHub。
+   * POST 不带 action（或 action 为 check）只问 Releases，不下载、不安装。
+   * POST `{ action: 'apply', version }` 才安装这次检查允许的更新版本，并安排重启面板。
+   * 安装先走 npm（`dsh plugin add @fengye_nobug/dsh-qq-bot@版本`）。registry 里没有这一版时才改从 GitHub 下载。
+   * 启动时检查不会走到 apply。两代宿主都挂：按钮跟“设置存在哪”无关。
    */
   async function handleUpdateRequest(req, res) {
     if (rejectLocalRequest(req, res)) return
@@ -3907,25 +3935,49 @@ export function apply(ctx, config) {
         error: '这个接口只接受 GET 与 POST。GET 看当前版本，POST 才去 GitHub 检查更新。',
       })
     }
-    const result = await checkPluginUpdate({ current })
-    if (result.ok === false) {
-      return sendJson(res, 200, {
+    let payload = {}
+    try {
+      const raw = (await readRequestBody(req)).trim()
+      payload = raw === '' ? {} : JSON.parse(raw)
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('not-object')
+    } catch {
+      return sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON。' })
+    }
+    const action = payload.action == null || payload.action === '' ? 'check' : String(payload.action)
+    if (action === 'check') {
+      const result = await checkPluginUpdate({ current })
+      if (result.ok === false) {
+        return sendJson(res, 200, {
+          ok: false,
+          current,
+          error: String(result.error || result.message || '检查更新失败，稍后再试。'),
+        })
+      }
+      return sendJson(res, 200, presentUpdate(result))
+    }
+    if (action !== 'apply') {
+      return sendJson(res, 400, {
         ok: false,
+        error: '不认识这个操作。检查更新不用带 action；安装请把 action 设为 apply。',
+      })
+    }
+    if (payload.version != null && payload.version !== '' && typeof payload.version !== 'string') {
+      return sendJson(res, 400, { ok: false, error: '版本号格式不对，没有安装。' })
+    }
+    let result
+    try {
+      result = await applyPluginUpdate({
         current,
-        error: String(result.error || result.message || '检查更新失败，稍后再试。'),
+        version: typeof payload.version === 'string' ? payload.version : '',
+        force: payload.force === true,
+        proxy: proxyFor(readSettings()),
       })
+    } catch {
+      return sendJson(res, 200, { ok: false, stage: 'install', error: '更新没有完成。稍后再试。' })
     }
-    return sendJson(res, 200, {
-      ok: true,
-      current: result.current || current,
-      latest: result.latest || '',
-      updateAvailable: result.updateAvailable === true,
-      summary: result.summary || '',
-      install: result.install || '',
-      command: result.command || '',
-      url: result.url || '',
-      message: result.message,
-    })
+    if (result.ok === true) logger.info(`一键更新：${result.message}`)
+    else logger.warn(`一键更新：${result.error || result.message}`)
+    return sendJson(res, 200, presentUpdate(result))
   }
 
   // TODO: accessTokenEnv 留空时，可回退读 NapCat 的 onebot11*.json 里的 token（用户说可做可不做）。
@@ -4068,7 +4120,7 @@ export function apply(ctx, config) {
     },
   }))
 
-  // 默认关。打开后每次进程启动问一次，只写日志，不下载、不安装、不挡住 ready。
+  // 默认关。打开后每次进程启动只问一次并写日志。这里不能调用 applyPluginUpdate。
   if (readSettings().checkUpdateOnStart === true) {
     const current = PLUGIN_VERSION
     Promise.resolve()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fengye_nobug/dsh-qq-bot",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "main": "index.js",
   "description": "把 DSH 会话接到 QQ（OneBot/NapCat）的插件。白名单默认全关；被 @、叫到昵称或被戳一定叫醒，其余消息按可调概率抽样。Fork 自 sj244/dsh-qq-bridge（MIT）。",