@fengye_nobug/dsh-qq-bot 0.2.7 → 0.2.8

package/README.md

@@ -1,655 +1,110 @@
 # dsh-qq-bot
 
-> **一句话简介。** 下面这句与 `package.json` 的 `description` 相同。GitHub 仓库 About 不能随 git 更新，需要在网站上手动粘贴同一句：
->
-> 把 DSH 会话接到 QQ（OneBot/NapCat）的插件。白名单默认全关；被 @、叫到昵称或被戳一定叫醒，其余消息按可调概率抽样。Fork 自 sj244/dsh-qq-bridge（MIT）。
+把已经在用的 DSH 会话接到 QQ 个人号。协议是 OneBot，常用实现是 NapCat。
 
-这是装在 `@deepseek-ai/dsh` 里的插件，把已经在用的 DSH 会话接到 QQ 个人号。协议是 OneBot，常用实现是 NapCat。
+Cordis 插件 id 是 `qq-bridge`。npm 包名是 `@fengye_nobug/dsh-qq-bot`。界面显示名是 dsh-qq-bot。
 
-本仓库 fork 自 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge)。上游许可证为 MIT，版权归 sj244；本 fork 的版权声明见 [`LICENSE`](./LICENSE)。安装和更新都走 `dsh plugin`，不要在服务器上打补丁脚本。
+唤醒、出站、图片、NapCat 和全部设置项见 [`DESIGN.md`](./DESIGN.md)。变更见 [`CHANGELOG.md`](./CHANGELOG.md)。
 
-**Cordis 插件 id 仍是 `qq-bridge`**（`cordis.patch.yml` 里的 `id`）。npm 包名是 **`@fengye_nobug/dsh-qq-bot`**。`cordis.patch.yml` 的 `name` 必须写成这个包名，Cordis 靠它加载模块。界面显示名仍是 **dsh-qq-bot**，消息来源仍是 `plugin:dsh-qq-bot`。无作用域的 `dsh-qq-bot` 发不出去：npm 认为它和已有的 `dsh-qqbot` 太像。已有 profile 里按 `id: qq-bridge` 写的覆盖继续生效；如果那一行还写着 `name: dsh-qq-bot`，要改成 `@fengye_nobug/dsh-qq-bot`，否则插件挂不上，设置接口是 HTTP 404。设置命名空间、状态文件和 `/api/qq-bridge/...` 也沿用这个 id，避免升级时对不上。
+## 简介
 
-**想装：** 优先用 npm 上已经发出的版本。连不上 npm，或 registry 里还没有这一版时，再用已经发布的 GitHub tag，不要盯着 main。
-
-```sh
-dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
-```
-
-```sh
-dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5
-```
-
-在 GitHub 上 Watch → Custom → **Releases**，比盯 main 稳。环境、第一次怎么开白名单、怎么升级、和官方插件为什么不能一起挂，写在[安装](#安装)。
-
-- 设计：[`DESIGN.md`](./DESIGN.md) ｜ 里程碑与真机实录：[`HANDOVER.md`](./HANDOVER.md) ｜ 变更：[`CHANGELOG.md`](./CHANGELOG.md)
-- 源码版本 **0.2.7**（一键更新装完会自己重启 dsh-web；Cordis 的包名会改成实际装上的 `@fengye_nobug/dsh-qq-bot`）。已经发布的是 **v0.2.5**，npm 上对应 `@fengye_nobug/dsh-qq-bot@0.2.5`。源码这一版还没打 tag，也还没 `npm publish`。v0.2.5 自带补丁里的 `name` 仍是无作用域的 `dsh-qq-bot`，装完若设置页是 HTTP 404，先把 `qq-bridge` 的 `name` 改成 `@fengye_nobug/dsh-qq-bot` 再重启。见 [`CHANGELOG.md`](./CHANGELOG.md)。
-- **M1–M8 全部完成**，已在**真实 NapCat + 真实 QQ** 上端到端跑通（Windows 真机）
-
-## 目录
-
-[功能](#功能) ｜ [安装](#安装) ｜ [npm](#用-npm-安装) ｜ [插件市场](#插件市场) ｜ [唤醒策略](#唤醒策略) ｜ [接入 QQ](#接入-qqonebot--napcat)
-｜ [NapCat 一键托管](#napcat-一键托管) ｜ [出站](#出站三种模式--来源闸门) ｜ [消息与图片](#消息占位符戳一戳图片)
-｜ [表情包](#表情包) ｜ [设置界面](#设置界面与全部设置项) ｜ [注入的系统提示](#注入给目标会话的系统提示) ｜ [无人值守边界](#无人值守的安全边界不提供审批桥接)
-｜ [上下文上限](#上下文上限) ｜ [工具一览](#工具一览) ｜ [已知限制](#已知限制与环境要求) ｜ [测试](#测试) ｜ [路线](#路线)
+消息进入你指定的会话，回答可以发回 QQ。白名单默认全关。被 @、叫到昵称或被戳时会叫醒；其余消息按概率抽样。群白名单可以由主人在 QQ 里用整句命令修改。
 
 ## 功能
 
-- **注入固定会话**：`sessionScope` 默认 `single`。`targetSessionId` 指向哪个会话，QQ 的消息就注入哪个会话，该会话原有的上下文继续使用。
-  目标会话由插件显式加载（`agents.get(id)`，取不到时用 `agents.resume({ resumeSessionId })`），不回退到别的会话。
-- **也可以按群分会话**：把 `sessionScope` 设成 `perGroup` 后，每个群、每个私聊各用一条 DSH 会话，对应关系写在状态文件的 `sessionByDest`（键是 `group:<群号>` / `private:<QQ号>`）。这种模式下 `targetSessionId` 可以留空，新建会话用宿主当前的默认模型；填了则沿用那个会话的模型。同时握着的会话句柄超过 48 个时，最久没用的会被放开，`sessionByDest` 里的对应关系还在，下次该群或该私聊再来消息会再恢复，不会另开一条。新建会话会带上工作目录：优先用宿主 `workingDirectory.defaultDirectory`，没有这项、或它不是绝对路径时，用进程当前工作目录。这样会话不会落到 `_no-cwd`，面板里可以打开，轨迹也读得到。标题写成「QQ群 <群名或群号>」或「QQ私聊 <昵称或 QQ 号>」：先调用宿主的会话改名；改名服务不可用或失败时，直接写入 `session/title`。升级前已经建好、当时没有工作目录的旧会话不会自动修好。把状态文件里对应的 `sessionByDest` 删掉，再在那个群或私聊里 @ 一次，才会按新规则新建。`maxRecentTurns` 默认 40，QQ 驱动的一轮结束后尽量把更早的轮次压到这个上限，`0` 表示不限制。有会话投影时按投影里的轮数判断；没有投影才数历史事件。压完一轮如果轮数没降下来，就停，不会连着再压。各记各的不只是上下文：这一轮算不算 QQ 唤醒、正在攒的回复、二次确认，都按会话分开。两个会话同时在跑，不会把甲群的回复发到乙群，也不会因为其中一路结束就把另一路的归属清掉。
-- **按概率唤醒，节省 token**：被 @、命中昵称、被戳时会话必须唤醒。其余消息按概率抽样（默认 5%）。
-  没有抽中的消息只记录，不调用模型。详见[唤醒策略](#唤醒策略)。
-- **出站受来源闸门限制**：出站有标记块和工具 2 种方式，由 `replyMode` 切换。2 种方式都只对“被 QQ 唤醒的那一轮”生效。
-  在 DSH 界面里与同一个会话聊天时，正文不会漏进群里。
-- **图片可见**：图片先落盘缓存。唤醒时由多模态模型写成文字。文字填回图片原来的位置。
-- **表情包**：群友发的图可以登记成表情包，之后按情绪或哈希再发出去。登记过的图不再调用多模态模型。
-  详见[表情包](#表情包)。
-- **系统表情**：模型写出的 `[笑哭]`、`[挥手]` 会变成 QQ 系统表情（笑哭是 182，挥手是 129）。
-  也认 `[表情182]` 和 `[CQ:face,id=182]`。详见[出站](#出站三种模式--来源闸门)。
-- **有设置卡片**：名称是白话（哪些群可以叫醒、群里发出去的是哪一段、忙的时候怎么插话等），
-  配置键仍是英文。在 `设置 → 插件 → 插件配置` 里修改，保存即生效。
-- **可以一键更新**：先点「检查更新」。有新正式版时再点「更新到 vX.Y.Z」，面板会装上并自己重启 dsh-web。优先从 npm 安装 `@fengye_nobug/dsh-qq-bot@版本`；这一版还没发到 npm 时，改从 GitHub 下载。装完把 Cordis 里 `qq-bridge` 的 `name` 改成实际装上的包名。超过三分钟没有结束就停掉卡住的安装进程；要装的版本已经在磁盘上时仍改包名，并自动重启。只有自动重启没有安排上，才提示自己重启。启动时检查不会自动安装。
-- **NapCat 自助托管**：插件可以按需下载、校验、解包、写配置、启停 NapCat。
-
-**不做的三件事**：
-
-1. 不接管审批（见[无人值守边界](#无人值守的安全边界不提供审批桥接)）。
-2. 不在插件加载时下载或执行任何内容。
-3. 不做 QQ 官方机器人，走 OneBot 个人号。
+- 接到一个已有会话，或按群、按私聊各记一条会话。
+- 白名单留空时，任何群和私聊都不会叫醒。
+- 被 @、命中昵称、被戳一定叫醒。其余按 `wakeProbability`（默认 `0.05`）抽样，没抽中只记录。
+- 发回 QQ 的内容由 `replyMode` 决定。在 DSH 界面里聊同一个会话时，正文不会进群。
+- 图片先落盘，叫醒时写成文字。表情包可以登记后再发。`[笑哭]` 这类写法会变成 QQ 系统表情。
+- 设置卡片在 **设置 → 插件 → 插件配置 → QQ 桥接**。可以检查更新；有新正式版时一键安装，并重启面板。
+- 可以按需下载、配置、启停 NapCat。加载插件时不会自己下载或执行。
+
+不做审批桥接，也不走 QQ 官方机器人。
 
 ## 安装
 
-日常安装用 npm 上已经发出的 **`@fengye_nobug/dsh-qq-bot@0.2.5`**。无作用域的 `dsh-qq-bot@版本` 装不上：npm 不接受这个名字，它和已有的 `dsh-qqbot` 太像。GitHub [Releases](https://github.com/yunfengnobug/dsh-qq-bot/releases) 上已经发出的是 **v0.2.5**。仓库源码如果已经是 0.2.7，那是还没打 tag、也还没发到 npm 的版本，日常不要装 main。某一版还没出现在 registry 里时，一键更新会改从 GitHub 下载。v0.2.5 的补丁仍把 Cordis 的 `name` 写成 `dsh-qq-bot`。装上这一版后，一键更新会在安装成功时把 profile、home（写了 `qq-bridge` 才改）和插件补丁里的 `name` 改成磁盘上的包名。
+日常安装用 npm 上已经发出的版本。仓库源码如果比已发布的版本新，不要直接装 main。
 
 ```sh
 dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
 ```
 
-GitHub 备用：
+registry 里还没有这一版时：
 
 ```sh
 dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5
 ```
 
-不写 tag 会装 main 上最新一次提交。主分支随时在改，日常别用这条：
-
-```sh
-dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot
-```
-
-装完要重启 `dsh web`（面板里就是重启 dsh-web），插件才会加载。
-
-### 环境
-
-和[已知限制](#已知限制与环境要求)同一套，没有另写一份要求：
-
-- **DSH**：0.1.5-rc.3 能用；0.2.0 及以后也能用。0.2.0 起宿主不给第三方插件可写设置域，本插件自己挂设置接口，卡片照常能改。
-- **NapCat**：OneBot v11 的正向 WebSocket。真机结论来自 **Windows 10 + NapCat Shell**（记录过 4.18.28）。仓库没有承诺更低的 NapCat 版本。NapCat 发行说明里的最低 QQ NT 构建号是 **40768**。主动戳人还要落在官方说的 **40768–44343**；真机上的 QQ 9.9.36-53644 发不出主动戳，别人戳我仍然会叫醒。
-- **Node ≥ 22**。插件用 Node 自带的 WebSocket，测试套件同样要求。
-
-### 第一次用
-
-白名单默认全关。私聊和群都是空的，这时候 @ 也不会醒。
-
-打开 **设置 → 插件 → 插件配置 → QQ 桥接**，先填「哪些群可以叫醒」或「哪些私聊可以叫醒」，保存，再去 @。例子里只用占位号，比如群 `123456789`。不要把真实群号、QQ 号写进仓库、Issue 或截图说明。
-
-### 升级
-
-四条路。装完都要让 dsh-web 重新加载插件：
-
-1. 设置卡片里先点「检查更新」。有新正式版时出现「更新到 vX.Y.Z」。点下去优先执行 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@X.Y.Z`，走这台机器上 pnpm 已经配置的 registry，然后重启面板。装完会把 profile、`$DSH_HOME/cordis.patch.yml`（写了 `qq-bridge` 才改）和插件补丁里 `qq-bridge` 的 `name` 改成磁盘上的包名，`config` 不动。设置还在，不改 NapCat。重启后刷新页面；登录口令可能会变。
-2. 自己执行同一条命令。npm 上已经发出的是 `@fengye_nobug/dsh-qq-bot@0.2.5`。自己装不会自动改 profile 里的旧 `name`。
-3. 指定 GitHub tag：`dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#vX.Y.Z`
-4. 卸掉再装，然后重启。
-
-无作用域名字发不出去。第 1 步如果发现 registry 里没有 `@fengye_nobug/dsh-qq-bot` 的这一版，会改从 GitHub 下载该标签的官方源码包：先 `github.com`，连不上再试同一标签的 `codeload.github.com`，然后交给 `dsh plugin add`。v0.2.4 及更早标签里的 `package.json` 仍是无作用域名，这种源码包仍然能装，Cordis 的 `name` 也保持 `dsh-qq-bot`。v0.2.5 的 `package.json` 已是作用域包，但补丁里的 `name` 还是旧的，所以会 404。插件不写死第三方镜像。registry 里已经有比当前新的正式版时，检查和安装不再访问 GitHub。
-
-从 0.2.5 点「更新」时，执行的还是那一版里的安装程序，不会改 profile，也不会自己重启。若设置页变成 HTTP 404，把 profile 和插件目录里 `qq-bridge` 的 `name` 改成 `@fengye_nobug/dsh-qq-bot`，再重启 dsh-web。这一版（0.2.7）自己跑一键更新时会改包名，并在装完后自动重启。
-
-「检查更新」和「启动时检查一次」只询问，不会安装。已经是最新正式版时不出现更新按钮。不会装比当前更旧的版本，也不装草稿和预发布。连不上、安装失败、面板没能重启，都用白话说明。安装已经成功但自动重启没有安排上时，新版本在磁盘上，需要自己重启 dsh-web。包名已经改好的话，重启后设置页会回来。
-
-安装超过三分钟没有结束时，会停掉卡住的 dsh 和它带起来的 pnpm，并用白话说明。profile 里的 `.plugin-manager/run.json` 只在记录的进程已经不在、或记录读不懂时删掉；进程还在就不会再开一次安装。超时后如果要装的版本已经在磁盘上，包名仍会改成实际安装的包，然后自动重启 dsh-web。没有确认装上时，可以再点一次「更新」，这时不会重启。
-
-在 Linux 上，进程由 systemd 拉起并且能认出具体服务时，大约 3 秒后只重启那个服务。服务挂在用户实例（`user@`）下面时，用 `systemctl --user`，不会重启整个登录。认不出单独服务，或 `systemd-run` 没有权限、执行失败时，改为按当前的 node 命令行再拉起一次。两条都做不到，才提示自己重启 dsh-web。没有被 systemd 拉起时，响应发出后按当前命令行再拉起一次。这次更新不改 NapCat 的配置，也不去停它。插件自己拉起的 NapCat 会随 dsh-web 退出而结束；已经在外面跑着的 NapCat 继续运行。
-
-想让 npm 走镜像，把 npm / pnpm 的 registry 配成你自己的镜像。插件只在没读到配置时用 `https://registry.npmjs.org/`。
-
-### 不要和官方插件一起挂
-
-官方仓库是 [sj244/dsh-qq-bridge](https://github.com/sj244/dsh-qq-bridge)。两边的 Cordis id 都是 `qq-bridge`，连的是同一个 OneBot。一起装会抢这条连接，消息对不上。只用其中一个。
-
-从官方换成这个 fork 时，包名一般是 `dsh-qq-bridge`。下面没有真实路径，profile 用你自己的：
-
-```sh
-dsh plugin --profile web remove dsh-qq-bridge
-dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
-```
-
-连不上 npm 时，把上面第二条换成 `dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5`。
-
-然后重启 dsh-web。profile 里原来按 `id: qq-bridge` 写的覆盖可以留着。若其中有 `name`，写成 `@fengye_nobug/dsh-qq-bot`，不要留着 `dsh-qq-bot` 或 `dsh-qq-bridge`。`list` 里如果包名不是 `dsh-qq-bridge`，卸你看到的那一个官方包，不要卸别的插件。
-
-### 开发期
-
-改本仓库代码时用本地目录：
-
-```powershell
-dsh plugin --profile web add "<REPO>"   # <REPO> = 本仓库在你机器上的绝对路径
-```
-
-`dsh plugin add <本地目录>` 装的是符号链接。Node 按真实路径找依赖，DSH 的包在 `~/.dsh/profiles/node_modules/@deepseek-ai`，从工作区向上找不到，插件 `import` 会失败。在插件目录挂一个 junction：
-
-```powershell
-New-Item -ItemType Junction `
-  -Path "<REPO>\node_modules\@deepseek-ai" `
-  -Target "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai"
-```
-
-每次改完插件代码，重启 `dsh web` 再刷新页面。
-
-### 以后怎么发版
-
-维护者按这个顺序，不要跳：
-
-1. 改 `package.json` 的 `version`。
-2. 在 [`CHANGELOG.md`](./CHANGELOG.md) 顶部写这一版做了什么。
-3. 提交并合进 main。
-4. 在含这个版本号的提交上打 annotated tag：`vX.Y.Z`。
-5. 用 CHANGELOG 里对应那一节的中文摘要发 GitHub Release。
-
-Release 不附带密钥、日志或本机文件。源码压缩包让 GitHub 自己生成即可，不必另外上传。用户侧安装优先用 npm 上的 `@fengye_nobug/dsh-qq-bot@版本`，不要把 main 当稳定版。见[用 npm 安装](#用-npm-安装)。
-
-## 用 npm 安装
-
-`dsh plugin` 是 pnpm 的包装。安装和一键更新都用作用域包名。npm 上已经发出的是 0.2.5：
-
-```sh
-dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
-```
-
-无作用域的 `dsh-qq-bot` 发不出去，npm 认为它和已有的 `dsh-qqbot` 太像。不要写成 `dsh plugin add dsh-qq-bot@版本`。
-
-registry 里还没有要装的那一版时（源码 0.2.7 尚未发布），改用 GitHub：
-
-```sh
-dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5
-```
+装完重启 dsh-web。
 
-一键更新的顺利路径是 npm，不再要求打开 github.com。某台机器上的 `dsh plugin --help` 如果只认 `github:`，就继续用 Release tag。想用镜像，配置这台机器的 npm / pnpm registry，不要等插件内置一个镜像地址。
+环境：DSH 0.1.5-rc.3，或 0.2.0 及以后；Node ≥ 22；NapCat 的 OneBot v11 正向 WebSocket。
 
-维护者发布下一版（仓库里没有 npm token，也不会在 CI 里代发）：
+`cordis.patch.yml` 里 `qq-bridge` 的 `name` 写成 `@fengye_nobug/dsh-qq-bot`。写成 `dsh-qq-bot` 或 `dsh-qq-bridge` 时插件挂不上，设置接口是 HTTP 404。
 
-1. `npm login`
-2. 确认 `package.json` 的 `name` 是 `@fengye_nobug/dsh-qq-bot`，`version` 和要发的 tag 一致。
-3. `npm pack --dry-run`，看清单里没有测试、密钥、本机路径。
-4. `npm publish`
+不要和另一个 Cordis id 也是 `qq-bridge` 的 QQ 插件一起挂，它们会抢同一条 OneBot。已经装着 `dsh-qq-bridge` 时，先卸掉再装上面的包，然后重启。profile 里按 `id: qq-bridge` 写的覆盖可以留着；其中的 `name` 同样写成 `@fengye_nobug/dsh-qq-bot`。
 
-`files` 是白名单。Node 要求 `>=22`（`engines`）。`@deepseek-ai/*` 仍是 `peerDependencies`，由 DSH 的 profile 提供，不要改成普通 dependencies。
+升级的几条路径、开发期怎么链到本地目录，见 [`DESIGN.md`](./DESIGN.md) 的「使用细节」。
 
-## 插件市场
+## 配置
 
-[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` 即可。
+白名单默认全关。先在设置卡片里填「哪些群可以叫醒」或「哪些私聊可以叫醒」，保存后再去 @。不要把真实群号、QQ 号写进仓库。
 
-要申请收录，按[贡献说明](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)做：
+群白名单仍按群号填写。连上之后，卡片里每个群号旁边会显示当前群名和头像。没连上，或暂时查不到，就只显示群号，保存不受影响。
 
-1. 在 GitHub 仓库页面加上 topic `dsh-plugin`。这个 topic 不会跟着 git 走，要在网页上加。
-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 认。
+DSH 0.2 的卡片把值写进 `$DSH_HOME/qq-bridge-settings.json`。这份文件比 `cordis.patch.yml` 优先，保存后马上生效，重启还在。只改 `cordis.patch.yml` 要重启。
 
-npm 上已经有 `@fengye_nobug/dsh-qq-bot`（目前是 0.2.5）。无作用域名发不出去。发到 npm 之后，市场才能显示下载量；不发也能收录。
+主人 QQ 在设置卡片里就叫「主人 QQ」（`ownerWhitelist`，默认 `[]`）。只有这些号能在 QQ 里改群白名单。**留空 = 这些命令不会生效。** 多个号用逗号分开。保存后下一条消息就生效。只改 `cordis.patch.yml` 要重启；设置文件里已有同名键时，以设置文件为准。
 
-用着有问题，到 [Issues](https://github.com/yunfengnobug/dsh-qq-bot/issues/new/choose) 选模板：**连不上**、**不回**、**发不出**。不要在 Issue 里贴真实 QQ 号、群号、token 或服务器地址。
+`accessTokenEnv` 填凭据引用名（一个环境变量名）。token 由 DSH 凭据服务解析，不要写进配置文件。每次建连重新解析。
 
-## 唤醒策略
-
-```
-QQ 消息 ─┬─ 不在白名单 ─────────────────→ 丢弃（白名单为空则全部拒绝）
-         ├─ 在会话跟随窗口内 ───────────→ 唤醒（reason: listening）
-         ├─ 群里 + atOnlyInGroup + 没 @ ─→ 丢弃
-         ├─ 被 @ / 命中昵称 / 被戳我 ───→ 唤醒
-         ├─ random() < wakeProbability ──→ 唤醒（默认 5%）
-         └─ 其余 ──────────────────────→ 只记录（零模型调用）
-```
-
-- **白名单默认全关**：`whitelist`（私聊）、`groupWhitelist`（群）为空数组时，任何来源都不能唤醒会话。
-- **必须唤醒**：被 @、正文命中 `nicknames`、被戳一戳（`[戳一戳]（戳的是我）`）。
-- **概率唤醒**：`wakeProbability`，默认 `0.05`。
-- **只记录**：未唤醒的消息进入“最近聊天缓冲”，不调用模型。缓冲按目的地分开，每个群、每个私聊各自最多 200 条。
-  下一次真正唤醒时，只取**这个目的地**最近 `recentChatLimit` 条（默认 8）拼成 `[QQ 未唤醒期间聊天记录] … [记录结束]`，
-  附在该条消息前。别的群或私聊的闲聊不会跟进来。摘要表头写明最近几条，并注明没进摘要的条数（“更早的 N 条已省略”）；
-  该条数按**真实丢失量**算，即这一目的地缓冲快照里的条目数减去摘要行数，窗口外的旧条目也计入。
-  该条数大于 99 时不写数字，改写成“更早的大量消息已省略”（不让巨大的数字进上下文）。
-  投递成功后，清掉的是**这个目的地**在唤醒那一刻缓冲里的条目，避免重复占用 token。
-  没进摘要的旧条目也一起删掉，不会留到下一次唤醒。别的目的地的缓冲不动。
-  只有投递期间新到的、同一个目的地的消息留在缓冲里，等下一次唤醒。
-- **投递方式**（`delivery`）：`auto`（默认）在目标会话正忙时插话（`steer`，下一个 step 边界塞入），空闲时排队；
-  `followup` 永远排成独立一轮；`steer` 总是插话。正忙时排进去的那一轮，到它真正开始时仍算 QQ 唤醒：
-  当前轮先结束、或中间夹进一条 DSH 里的消息，都不会把这次排队的归属清掉。
-- **群内二次闸门**：`atOnlyInGroup: true` 时，群消息没有被 @ 就完全不处理。
-
-### 会话跟随
-
-真人聊天不会每句话都 @。第一次被 @ 之后，是否继续收听由模型自己决定：
-
-| 调用 | 作用 |
-|---|---|
-| `qq_bridge_listen({ minutes: 5 })` | 开一个窗口（默认 5 分钟，上限 60） |
-| 窗口打开期间 | **同一目的地**（同一个群 / 同一个私聊）的普通消息也唤醒目标会话，不必再 @ |
-| `qq_bridge_listen({ off: true })` | 关掉当前目的地的窗口；到期也会自动失效 |
-
-- 每个目的地各有一个窗口，同时开着互不影响。给甲群开窗不会关掉乙群已经开着的窗口。
-- `qq_bridge_listen({ off: true })` 只关当前这一轮钉住的目的地，别的目的地的窗口还在。
-- 窗口只影响那个目的地，别的群 / 私聊照旧要 @ 或点名才会叫醒。
-- 警告：窗口打开时，每条消息都会唤醒，产生实际费用。默认 5 分钟、上限 60 分钟。
-  这条规则已经写进注入的系统提示（“别无脑常开”）。
-- 窗口检查排在 `atOnlyInGroup` 之前。否则群里开启跟随后，消息会被“没 @ 就丢弃”掐断。
-
-## 接入 QQ（OneBot / NapCat）
-
-插件作为 **WebSocket 客户端**主动连接 NapCat 的“正向 WebSocket”服务，收发都走这一条连接。
-
-```yaml
-# 在 profile cordis.patch.yml 里按 id 覆盖，或直接在设置界面改
-- id: qq-bridge
-  config:
-    onebotUrl: 'ws://127.0.0.1:3001'
-    accessTokenEnv: 'NAPCAT_ACCESS_TOKEN'
-```
-
-- `onebotUrl` **留空 = 完全不启用传输**（默认值，安全）。
-- NapCat 侧要开一个 **WebSocket 服务器**（不是 HTTP 服务器），并允许本机连接。
-- `selfId` 留空即可：连上后插件自动调用 `get_login_info` 取得自身的 QQ 号，用于过滤自身消息，
-  防止回复死循环，同时忽略 `message_sent` 事件。`get_login_info` 返回之前，事件里如果已经带了 `self_id`，
-  先用它过滤自身消息、识别 @ 和戳一戳。事件没带 `self_id` 的那一小段仍可能漏过；想完全避开就填上 `selfId`。
-- 两次建连叠在一起时只保留后一次。先发起、后拿到 token 的那次不会拆掉新连接，也不会留下多余的 socket。
-
-### 配置 access_token（不得明文写入配置）
-
-`accessTokenEnv` 填的是**凭据引用名**（一个环境变量名）。token 本身由 DSH 的凭据服务解析，
-不写入 `cordis.patch.yml`，也不进入日志或状态文件。token 按以下优先级逐层查找：
-
-1. 进程环境变量：`$env:NAPCAT_ACCESS_TOKEN = '…'`
-2. `~/.dsh/.credentials.yaml` 的 `refs:` 段
-3. 工作目录下的 `.env`
-
-> 解析在每次建连时重新执行，不缓存。轮换 token 不需要重启。
-
-## NapCat 一键托管
-
-插件可以按需从官方 GitHub Releases 下载、校验、解包、写配置、启停 NapCat，不预先打包 NapCat。
-
-**NapCat 已经自己部署好**（包括 Docker、另一台机器上的实例）时，下面的下载、解包和安装器可以整段跳过。仍要让 `onebotUrl` 和 `onebotPort` 跟那边的 OneBot 正向 WebSocket 一致，并在「NapCat 安装目录」里填实际路径。默认的 `$DSH_HOME/napcat` 在这种装法里往往不存在；目录不存在时「打开文件夹」不会去猜路径，只提示你改设置。
-
-在会话里调用 `qq_bridge_napcat` 工具，按以下顺序执行：
-
-| 步骤 | 调用 | 说明 |
+| 键 | 默认 | 效果 |
 |---|---|---|
-| 1 | `{ action: "status" }` | 查看 QQ 是否已安装、NapCat 是否存在、代理是否配置、端口是否正确 |
-| 2 | `{ action: "download" }` | 取最新发行包 → **sha256 校验** → 解包到 `napcatInstallDir` |
-| 3 | **手动运行一次安装器** | 见下文；这一步插件无法执行 |
-| 4 | `{ action: "configure" }` | 写 `config/onebot11.json`，把正向 WS 端口和 token 配好（**不用打开 WebUI**） |
-| 5 | `{ action: "launch" }` | 启动 NapCat（首次仍需扫码登录） |
-
-安装目录可以是 OneKey 根，也可以是 OneKey 根下的 `NapCat.Shell` 子目录；两种布局都能识别。
-
-**启动优先走官方 launcher**：目录里存在 `launcher-win10.bat`（或 `launcher.bat`）时，插件用
-`cmd /c` 调用这个 bat 脚本，工作目录设为 `NapCat.Shell`。脚本自己读注册表找 QQ 路径，非管理员时用
-UAC 自我提权，因此**可能弹出 UAC 窗口**，需要在系统弹窗里点“是”。
-没有 launcher 脚本时，插件直接调用 `NapCatWinBootMain.exe`，并按官方参数顺序传入
-QQ 路径与 `NapCatWinBootHook.dll`；此时 QQ 路径取不到会明确报错，先手动安装并登录一次 QQ NT 即可。
+| `targetSessionId` | 空 | `single` 时接到哪个会话。留空 = 不接到任何会话 |
+| `sessionScope` | `single` | `perGroup` 时每个群、每个私聊各一条会话 |
+| `nicknames` | `244`、`小助手` | 听到这些名字就叫醒 |
+| `wakeProbability` | `0.05` | 没点名时的叫醒概率 |
+| `whitelist` | `[]` | 哪些私聊可以叫醒。留空 = 都不叫醒 |
+| `groupWhitelist` | `[]` | 哪些群可以叫醒。留空 = 都不叫醒。卡片里查到群名时，群号旁边有名字和头像 |
+| `ownerWhitelist` | `[]` | 卡片里叫「主人 QQ」。留空 = 不能在 QQ 里改群白名单 |
+| `onebotUrl` | 空 | NapCat 正向 WebSocket。留空 = 不连接 |
+| `atOnlyInGroup` | `false` | 打开后，群里没被 @ 就不处理 |
+| `replyMode` | `marker` | 群里发出去的是哪一段：只发「发给群」里的那段 |
 
-**第 3 步必须手动执行的原因**：
+其余键见 [`DESIGN.md`](./DESIGN.md)。
 
-- `NapCatInstaller.exe` 是**交互式控制台程序**。DSH 的 `SubprocessStdio.stdin` 只支持
-  `'ignore' | 'pipe' | { data }`，没有 `inherit`，插件无法转发键盘输入。
-- **QQ 首次登录必须手动完成**（扫码或密码）。NapCat 官方要求登录过一次之后，才能用 QQ 号快速登录。
+## 使用
 
-**下载需要代理**：插件内的下载不读取 `HTTPS_PROXY`（Node 的 `fetch` 不识别代理），因此：
+在群里 @ 机器人，或叫出昵称。白名单没填时不会醒。
 
-- 有代理时，把 `downloadProxy` 设成代理地址，例如 `http://127.0.0.1:7890`；
-- `downloadProxy` 留空时，依次读取 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` 环境变量，都没有才直连；
-- 下载优先使用系统自带的 **`curl.exe`**（可以带 `-x` 代理）；没有 subprocess 服务时才退回内置 `fetch`。
+主人改群白名单时，整句必须就是命令，前面可以加一个 `/`。多出来的字不当命令。不是主人时按普通聊天处理：不改配置，也没有单独的拒绝回复。还没进白名单的群，主人仍能在群里直接加。调试工具模拟的消息不会改白名单。
 
-**安全边界**：
-
-- **插件从不自动下载或执行任何内容**。所有动作都由 `qq_bridge_napcat` 的显式调用触发。
-- 每次下载都按 GitHub Release 自带的 `asset.digest` 做 **sha256 校验**，校验不符时删除文件并报错。
-- ZIP 用**纯 Node 实现**解包，不依赖 7z / Expand-Archive，并拒绝 `..`、绝对路径等 zip-slip 条目。
-- 默认安装位是 `$DSH_HOME/napcat`，不污染项目目录。
-- 警告：**NapCat 是第三方 QQ 客户端**，存在账号风控风险，是否启用由用户决定。NapCat 由 DSH 的 subprocess
-  服务托管，**插件卸载或 DSH 退出时会一并结束**。
-
-## 出站：三种模式 + 来源闸门
-
-**出站方式由 `replyMode` 控制**：
-
-| 值 | 行为 | 代价 / 收益 |
+| 在哪 | 整句 | 作用 |
 |---|---|---|
-| `'marker'`（默认） | 只有 `[QQ]…[/QQ]` 里的内容会发出 | 零额外调用；没有反馈回路 |
-| `'tool'` | **关闭标记块**，改用 `qq_bridge_send` 工具 | 每轮多一次模型调用，换来反馈（工具结果会告诉模型是否已发出） |
-| `'always'` | 整轮回复都发出（旧行为，技术内容也会进群） | 适合“这个会话本来就是公开的”场景 |
-
-标记块的格式如下，块外的一切都不会进群：
-
-```
-这段技术说明、路径、思考过程都不会进群
-
-[QQ]在的，收到召唤了 👻[/QQ]
+| 群里 | `白名单 加`、`白名单 加本群` | 把当前群加进群白名单 |
+| 群里 | `白名单 删`、`白名单 删本群` | 把当前群移出 |
+| 群或私聊 | `白名单 加 群号`、`白名单 删 群号` | 按写明的群号加或删 |
+| 群或私聊 | `白名单`、`白名单 列表` | 回复现在有几个群 |
+| 私聊 | `白名单 加`（没写群号） | 不改配置，提示要写群号 |
 
-这段也不会
-```
-
-- **没有标记块时，一个字都不发**。DSH 会话里的技术说明、路径与思考过程不适合出现在 QQ 群，宁可不回复，也不刷屏。
-- **只有“被 QQ 唤醒的那一轮”才生效**：在 DSH 界面里直接与同一个会话聊天时，标记块一个字都不会发出；
-  QQ 唤醒的那一轮里，块外的正文同样不发出。
-- **来源判据**：优先识别插件注入的那条消息。① 消息 id 等于刚注入的那条；
-  ② 正文以 QQ 入站前缀开头（`[QQ · ` / `[QQ 未唤醒期间聊天记录`）。`source` 字段只作兜底：
-  真机上出现过 `source` 字段被上游重写，导致 QQ 侧 @ 了却发不出去（哑火）。
-- **工具调用同样经过来源闸门**。不是 QQ 唤醒的那一轮，`qq_bridge_send` 第一次调用只回一句
-  “确认要发吗”，不发送任何内容；同一轮里再调一次才真正发出。确认状态按轮清零，不跨轮保留。
-- **台账**：标记块发送记 `via: 'marker' | 'always'`，工具发送记 `via: 'tool'`，
-  非 QQ 轮的确认发送额外标 `nonQQTurn: true`。据此可以查到每条群消息的发送方式。
-- **字数上限**：出站文本超过 `replyMaxChars` 时**一条都不发**，调用方拿到 `reason: 'too-long'`，
-  应按提示缩短后重发；未超长时 `replyWithQuote: true` 让消息带上引用；
-  `stripMarkdown: true`（默认）时先去掉 Markdown 标记（QQ 不渲染）。字数按去掉 Markdown 之后、拆表情之前的正文计算。
-- **系统表情**：去掉 Markdown 之后，`sendToQQ` 把正文拆成 OneBot 消息段。`[笑哭]`、`[挥手]` 这类名字变成 `face` 段（笑哭是 182，挥手是 129），NapCat 显示系统表情。也认入站占位符 `[表情182]`，以及 `[CQ:face,id=182]`。对不上的方括号（例如 `[没这表情]`、`[图片]`）留在文字段里。标记块和 `qq_bridge_send` 都走这条路。名字表在 `faces.js`，常见的还有微笑、捂脸、吃瓜、比心。商城表情不走这条路，由 `qq_bridge_sticker` 按登记表发送，见[表情包](#表情包)。
-- **目的地钉在唤醒那一刻**。这一轮的标记块、`qq_bridge_send`、`qq_bridge_sticker` 和 `qq_bridge_listen` 都发回把这一轮叫醒的那个群或私聊，不会被同一时间另一条只记录下来的消息改掉。显式传入 `groupId` 或 `userId` 时发到那里，并且不引用别的会话里的原消息；这个群号必须在 `groupWhitelist` 里，这个 QQ 号必须在 `whitelist` 里，对不上就一条都不发（`reason: "not-allowlisted"`）。白名单留空等于不允许。钉住的目的地不再查一遍，它在入站时已经通过了白名单。同一会话后面没有新唤醒的轮次，仍回落到最后一次非丢弃的入站。
-- **连不上或还没有目的地时丢弃并记日志**，不静默排队堆积。
-- **标记块发出时传输失败**（`reason: 'send-failed'`）同样记进丢弃台账，并把原因回注到这一轮的会话里。模型能看到没发出去，而不是只在日志里留一行。
-- 入站消息会自动附一行提示，说明目标会话的回复方式。
-
-## 消息：占位符、戳一戳、图片
-
-### 非文本消息段
+删到一个群都不剩时，回复会说明现在任何群都不会叫醒。保存方式和设置卡片相同。
 
-QQ 的表情、表情包、图片、语音、视频、文件、卡片、合并转发等都会换成可读占位符
-（如 `[表情4]`、`[表情包:[动画表情]]`、`[图片]`、`[文件:a.zip]`），**不会让整条消息丢失**。
-系统表情的入站占位符带编号，例如 `[表情182]`。出站时模型写的 `[笑哭]`，或这种占位符，会再变回系统表情，见[出站](#出站三种模式--来源闸门)。
-商城表情若带了可下载的图，描述填回去之后写成 `[表情包#短哈希]`，和普通图片的 `[图片#短哈希]` 分开，见[表情包](#表情包)。
+`replyMode` 为 `marker` 时，模型把要发到群里的话放进 `[QQ]…[/QQ]`。会话跟随、表情包和戳一戳见 [`DESIGN.md`](./DESIGN.md)。
 
-### 戳一戳
+## 更新
 
-QQ 的“拍一拍”在 OneBot 里走的是 **notice 事件**，不是消息段。插件把该事件合成一条入站消息
-（正文 `[戳一戳]（戳的是我）`）：
+设置卡片里先点「检查更新」。有新正式版时点「更新到 vX.Y.Z」。优先从 npm 安装；这一版还没发到 npm 时，改从 GitHub 下载。装完会自己重启 dsh-web。设置还在，不改 NapCat。刷新页面后，登录口令可能会变。
 
-- **戳我时必唤醒**，与 @ 同级（`reason: poke`）；
-- 戳别人时只记录，不唤醒，与“叫了别人的名字”相同；
-- 其它没有适配的 notice 会留一条 `未适配的 notice：…` 日志，不静默丢弃。
+「检查更新」和「启动时检查一次」只询问，不会安装。
 
-> “主动戳人”暂不提供，原因是 NapCat 发包后端受限，见[已知限制](#已知限制与环境要求)。
+维护者发版：
 
-### 图片
-
-**图片会真正传给目标会话**，分 2 步：
-
-1. **收到即落盘缓存**（`$DSH_HOME/qq-bridge-images/`；超过 64MB 或 300 张时按时间淘汰最旧的）。
-   单张下载超过 8MB 不会落盘：先看 `content-length`，没有这个头就在读流时停掉。失败的那张仍是 `[图片]` 占位符。
-   这一步是纯 I/O，不调用模型，因此不影响缓冲“零模型调用”的性质，也不受 QQ 图片 URL 过期影响。
-   文件名就是**内容哈希**（`<hash>.<ext>`）：同一张图不重复落盘，命中已有文件时也拿得到哈希。
-2. **唤醒时先用多模态模型看图**，把描述填回图片原来的位置，并带上 6 位短哈希：
-
-```
-[QQ · “群名称”] “DSH 昵称”：看这个 [图片#a1b2c3]：“图片描述”
-```
-
-短哈希是这张图在插件里的编号。描述可能不准，而模型需要指着一张具体的图说话，
-所以占位符里带上短哈希 —— 模型把这个短哈希交给 `qq_bridge_sticker` 就能存下或再发出去。
-
-普通图片是 `[图片#a1b2c3]：<描述>`。入站段上带了商城表情的 `emoji_id`（NapCat 常把商城表情收成这种 `image` 段，也会直接给 `mface` 段）时，同一位置写成 `[表情包#a1b2c3]：<表情名> <描述>`。只有简介、没有表情 id 的图仍算普通图片。
-
-第 2 步是必需的：**目标会话的模型通常不支持图片输入**（如 `deepseek-v4-flash` 是纯文本），
-附件会被系统剥成 `image omitted`，只有描述能让模型知道图里的内容。
-
-- 选择模型：优先使用设置里的 `visionModel`（`provider/model`）；未设置时自动查找，
-  名字带 `vision` 的优先，其次是第一个支持图片输入的模型。
-- 发给视觉模型的那条消息，来源和注入 QQ 消息一样：DSH 0.2.0 用 `plugin:dsh-qq-bot`，
-  0.1.5 仍用原来的 `{ kind: 'plugin', plugin: 'qq-bridge' }`。0.2.0 不接受旧的 `kind: 'plugin'`。
-- 解析结果会缓存：成功的解析按 `visionModel` 的值缓存，值没变就不再枚举模型列表。
-  自动查找失败的结果也会缓存，但只用于同一次设置内的去重 —— 设置一改就丢掉并重试，
-  所以之后补上视觉模型不必改动 `visionModel`。
-- **单张图失败会重试 2 次**（共 3 次尝试，退避 300/600ms）；3 次都失败才记“描述失败 + 原因”。
-  普通图片写成 `[图片#a1b2c3]：（描述失败：原因）`。商城表情写成 `[表情包#a1b2c3]：<表情名> （描述失败：原因）`。
-- 一次唤醒最多描述 3 张（每张 = 一次多模态调用）；描述失败不影响文本处理与策略判定。
-- 图片已登记为表情包时，描述直接取登记表里的 `description`，不调用多模态模型。
-
-### 表情包
-
-群友发的图和商城表情可以登记下来，之后按情绪（mood）或哈希再发出去。带齐商城表情字段的登记项发成 QQ 原生表情包；普通图片发出去仍是图片。登记与发送都由 `qq_bridge_sticker` 工具完成。
-
-**存储位置**（与 statePath 同目录）：
-
-| 路径 | 内容 |
-|---|---|
-| `<statePath 目录>/qq-bridge-stickers.json` | 登记表 |
-| `<statePath 目录>/qq-bridge-stickers/<hash>.<ext>` | 图片本体 |
-
-`hash` 是图片字节 sha256 的**前 16 位十六进制**（小写）；正文占位符里的 6 位短哈希是 `hash` 的前 6 位。
-
-**条目字段**：
-
-| 字段 | 说明 |
-|---|---|
-| `hash` | 内容哈希，16 位十六进制 |
-| `mood` | 情绪分类，如 无语 / 开心 |
-| `description` | 这张图是什么；发送与识图都用这个字段 |
-| `file` | 图片本体路径，相对 statePath 目录 |
-| `ext` | 扩展名 |
-| `source` | 来源：`group:<群号>` / `private:<QQ号>` / `cache`（只从图片缓存捞到） |
-| `mface` | 可选。商城表情的 `emoji_id`（字符串）、`emoji_package_id`（非负整数）、`key`、`summary`。缺了这项的旧条目照常当图片 |
-| `addedAt` | 首次登记时间 |
-| `sentCount` / `lastSentAt` | 累计发送次数与上次发送时间 |
-
-**三个 action**：
-
-| action | 参数 | 作用 |
-|---|---|---|
-| `list` | `mood?` | 列出已登记的：短哈希、mood、描述（截断 40 字）、`kind`（`mface` 或 `image`）、表情名、图片大小、发送次数 |
-| `save` | `hash?`、`fromLast?`、`mood`、`description` | 登记一张图。`fromLast: true` 取缓冲区里最近一张。源图上若有商城表情字段，一并写入 |
-| `send` | `hash?`、`mood?`、`groupId?`、`userId?` | 发一张。给 `hash` 精确发；只给 `mood` 时在该情绪里随机挑一张。`mface` 四字段齐全时发原生表情包，否则发图片 |
-
-- `save` 先在**缓冲区**找源图（那里带着来源信息），再到**图片缓存目录**找。两处都没有时返回错误，
-  提示先让群友发一张图。
-- `send` 与 `qq_bridge_send` **共用同一道来源闸门**：不是 QQ 唤醒的那一轮，第一次调用只回一句确认，
-  同一轮里再调一次才真的发。
-- 发送成功记进 outbox（`via: 'tool'`、`action: 'sticker'`）。原生表情包的 `text` 是 `[表情包#<短哈希>]`，普通图片是 `[图片#<短哈希>]`。同时更新该条的 `sentCount` 与 `lastSentAt`，已记下的 `mface` 不会被这次计数清掉。
-- **四字段齐全就发 OneBot `mface`**：`emoji_package_id`（数字）、`emoji_id`、`key`、`summary`。QQ 里显示的是原生表情包，不是一张图。这种发送不读本地图片文件。
-- **缺任何一项就发图片**：本体用 `base64://`，不用本地路径。NapCat 的 `enableLocalFile2Url` 是 false，本地路径读不到。
-- 图片落盘时，商城表情字段写在同一目录的 `<hash>.mface.json`（`$DSH_HOME/qq-bridge-images/`）。唤醒成功后缓冲会清掉，`save` 靠这份旁路文件找回字段。图片被缓存淘汰时，旁边的文件一起删。
-- 该工具**不受 `debugTools` 限制**：表情包是产品的玩法，不是调试工具。没有新增设置项。
-
-**缓存命中省 token**：`describeImage()` 先查登记表。命中且有 `description` 时直接返回这条描述，
-不调用多模态模型 —— 反复出现的图只描述一次。日志只记短哈希，不记图片 URL。
-
-## 设置界面与全部设置项
-
-**设置 → 插件 → 插件配置** 里有一张 **QQ 桥接** 卡片（可折叠，默认展开）。卡片上的名称是白话
-（例如「哪些群可以叫醒」「群里发出去的是哪一段」），写进配置文件的键仍是英文。
-在这里修改后**保存即生效**（写入 `settings.yaml` 的用户层，不用重启）。
-
-> **DSH 0.2.0 上**：宿主不再给第三方插件可写的设置命名空间（DSH #677 的迁移未完成，生态里所有走这条路的
-> 插件都一样）。本插件因此**自己挂了一条设置接口**：`GET/POST /api/qq-bridge/settings`。
-> 值存 `$DSH_HOME/qq-bridge-settings.json`，优先级为 **设置文件 > `cordis.patch.yml` 里的安装配置**（composition config）。
-> 卡片照常可以使用；`cordis.patch.yml` 也仍然可以修改（改完重启生效，且会被上面的设置文件覆盖）。
-> 本机回环、且没有外来源（命令行、SSH 隧道）或来源也是本机时，可以直接改。经反向代理进来时，对端常常仍是 `127.0.0.1`，来源却是公网面板地址：这时必须是**已经登录**的面板会话，并且来源主机名和这次请求的 `Host` 一致，设置才能保存。卡片上的读取和保存会带上面板登录 cookie（`credentials: 'include'`）。**不必再配 `trustedHosts`**。
-> 宿主 `requestRejection()` 返回空、`undefined` 或 `0` **不算**已登录。已登录只认宿主明确给出的结果：`isAuthenticated`、浏览器会话，或 `admit()` 交回的身份。没有这个结果的外网请求是 403。来源是别的网站、和 `Host` 对不上的请求也是 403，就算带着 cookie 也不行。接口只写 schema 白名单里的键。
-> 判断面板监听器是不是 HTTPS 时，只通过 `ctx.get('webServer')` 读协议，不读 `ctx.webServer`。插件没有把 `webServer` 放进 inject。直接读这个属性会抛错，宿主会把这次请求收成**没有正文的 HTTP 400**，卡片诊断就显示本机接口不可用，即使浏览器里已经登录。读不到这项服务、或读取失败时，按 HTTP 继续做登录判定。
-
-卡片上方显示**当前版本**，并有 **检查更新**。按钮旁边只写「只检查，不安装。」接口是 `GET/POST /api/qq-bridge/update`，准入和设置接口相同。GET 只读当前版本，不去 npm，也不去 GitHub。POST 不带 `action` 才对比版本：先问 npm registry 里的 `@fengye_nobug/dsh-qq-bot` 正式版。有比当前新的版本时，卡片上写短句「有新版本 x.y.z（现在是 a.b.c），在 npm 上。这里只检查，还没安装。」并且不再访问 GitHub。npm 上还没有更新、但 GitHub Release 上有更新时，改问 GitHub，短句里写「在 GitHub 上」。安装命令和说明摘要仍在接口字段里，不铺在这句主提示上。没有新版、连不上、被限流，都用白话说明。检查本身不会下载或安装。
-
-有新版时出现 **更新到 vX.Y.Z**。旁边只加一句「装完会重启面板。请刷新；登录口令可能会变。不改 NapCat。」点下去才发送 `POST { "action": "apply", "version": "x.y.z" }`。优先 `dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@x.y.z`。registry 里没有这个版本时，改从 GitHub 的官方源码包装上。安装成功后，把 profile、`$DSH_HOME/cordis.patch.yml`（有 `qq-bridge` 这一行才改）和已安装插件补丁里的 `name` 改成磁盘上 `package.json` 的包名，然后重启面板。只改我们自己的旧包名（`dsh-qq-bot`、`dsh-qq-bridge`），不改 `config`，也不改别的插件。成功时主提示是「已经从 npm 装上 vX.Y.Z，面板即将重启。」或「已经从 GitHub 装上 vX.Y.Z，面板即将重启。」进行中显示「正在更新…」。已经是最新正式版时没有这个按钮。超过三分钟还没装完时停掉这次的 dsh 和 pnpm。`.plugin-manager/run.json` 里的进程还在就不删，也不再开第二个安装；进程已经不在或记录读不懂才删。超时后如果磁盘上已经是要装的版本，仍改包名，并自动重启 dsh-web。自动重启没有安排上时，才提示自己重启，并写明这次是从 npm 还是从 GitHub 装上的。
-
-「启动时检查一次」默认关。打开并保存后，下次启动 dsh-web 才问一次，结果只写在日志里，不会安装。
-
-卡片展开后还有 3 个操作按钮（0.1.5 与 0.2.0 上都有）：
-
-- **打开 WebUI**：用浏览器打开 NapCat 的 WebUI。填了 `napcatWebuiUrl` 就打开那个地址（地址本身没带 token 时，会补上 `webui.json` 里的 token）。没填则用 `<安装目录>/config/webui.json` 里的 host / port / token；文件不存在时仍按 `127.0.0.1:6099` 打开，按钮保持可点。地址是 `127.0.0.1` 或 `localhost` 时，旁边会写明只有跑着 NapCat 的那台机器能打开。
-- **启动 NapCat**：与工具 `qq_bridge_napcat` 的 `launch` 是同一个动作。目录里有官方
-  `launcher-win10.bat` 时优先调用该脚本，脚本会自我提权，**可能弹出 UAC 窗口**。
-  NapCat 运行中时，按钮显示“已在运行”并禁用；外部手动启动的 NapCat 也算运行中。
-  卡片展开期间每 5 秒轮询一次状态，所以外部启动后按钮会自己变化。
-- **打开文件夹**：用系统文件管理器打开 NapCat 安装目录（Windows 用 `explorer.exe`，macOS 用 `open`，
-  Linux 用 `xdg-open`）。目录不存在时不打开，卡片上会提示：自己部署或 Docker 里的路径通常不是默认值，请填写「NapCat 安装目录」。
-
-这 3 个按钮走 `GET /api/qq-bridge/napcat`、`POST /api/qq-bridge/napcat/launch`、
-`POST /api/qq-bridge/napcat/reveal`，准入与设置接口相同：本机可以直接用；反向代理要带已登录的面板会话，且来源主机名和 `Host` 一致。没有明确登录结果的外网请求 403。请求进行中按钮禁用，token 只拼进 URL 不写日志。
-
-修改**出站方式**会立刻重挂注入给目标会话的用法说明：提示词正文按模式分叉，
-不重挂时模型会按本部署里已经不生效的做法回话。
-
-**目标会话是下拉选择**（按会话标题或项目名选择，不用记 `session-…` 那串 id）；选好后会同时显示该会话的真实 id。
-**已归档的会话不会列出**，当前选中的那个例外，会标成“（已归档）”。
-配置里的会话不在列表里时（别的工作区、宿主还没有加载完），保留成“（不在会话列表里）”的兜底项。
+1. 改 `package.json` 的 `version`。
+2. 在 [`CHANGELOG.md`](./CHANGELOG.md) 顶部写这一版。
+3. 推到 `main`。
 
-卡片上的叫法和下面「说明」一致。第一列是配置键，不会出现在按钮上。
+推到 `main` 后，Actions 在 npm 上还没有 `@fengye_nobug/dsh-qq-bot` 的这一版时才发布，并补 tag `vX.Y.Z` 和 GitHub Release。`NPM_TOKEN` 放在仓库 Actions Secrets，不写进仓库。
 
-| 键 | 默认 | 说明 |
-|---|---|---|
-| `targetSessionId` | `''` | 接到哪个会话。`single` 时**空 = 不接到任何会话**。`perGroup` 时可以留空（新建会话用宿主当前默认模型）；填了则新建会话沿用该会话的模型 |
-| `sessionScope` | `single` | 会话怎么分。`single` = 所有群共用一个会话；`perGroup` = 每个群、每个私聊各记各的，映射写在状态文件的 `sessionByDest`（键为 `group:<群号>` / `private:<QQ号>`）。新建会话带工作目录和「QQ群 / QQ私聊」标题，见[功能](#功能) |
-| `maxRecentTurns` | `40` | 每个会话最多留几轮。超出后调用宿主 `compaction.compactNow` 尽量压缩。有投影时看投影轮数。压完没变短就停。`0` = 不限制 |
-| `nicknames` | `['244','小助手']` | 听到这些名字就回应 |
-| `wakeProbability` | `0.05` | 没点名时的回应概率 |
-| `whitelist` / `groupWhitelist` | `[]` | 哪些私聊可以叫醒 / 哪些群可以叫醒（**留空 = 谁都不能叫醒**） |
-| `attachRecentChat` / `recentChatLimit` | `true` / `8` | 把没叫醒时的聊天一并带上，以及附带最近几条 |
-| `atOnlyInGroup` | `false` | 群里必须 @ 才理 |
-| `replyMode` | `'marker'` | 群里发出去的是哪一段：`marker` 只发「发给群」里的那段｜`tool` 用发消息工具｜`always` 整段回答都进群（慎用） |
-| `delivery` | `'auto'` | 忙的时候怎么插话：`auto` 能插就插，不能就排队（推荐）｜`followup` 一律新开一轮｜`steer` 不管忙不忙都插 |
-| `replyMaxChars` | `1500` | 一条最多多少字（下限 100）；**超过就不发送** |
-| `replyWithQuote` | `false` | 回复时带上原消息 |
-| `stripMarkdown` | `true` | 去掉 Markdown 记号 |
-| `visionModel` | `''` | 用来看图的模型（`provider/model`）；空 = 自动查找 |
-| `agentPreset` | `''` | 人设预设；空 = 沿用会话自己记着的 |
-| `onebotUrl` | `''` | OneBot 连接地址；空 = 先不连接 |
-| `accessTokenEnv` | `''` | OneBot 令牌放在哪个环境变量（填变量名，不是令牌，也不是模型 API key） |
-| `selfId` | `''` | 机器人自己的 QQ 号。空 = 连上后自动读取；读取完成前，先用事件里的 `self_id`。想避开这段空窗就填上 |
-| `heartbeatTimeoutMs` | `90000` | 多久没收到连接数据就判定断线并重连 |
-| `napcatInstallDir` | `''` | NapCat 安装目录；空 = `$DSH_HOME/napcat`。自己装的或 Docker 里的请填实际目录 |
-| `napcatWebuiUrl` | `''` | NapCat 网页管理地址。空 = 读 `webui.json`（通常是 `127.0.0.1`，只有跑着 NapCat 的机器能打开）。远程使用时填外面打得开的地址 |
-| `napcatVersion` | `''` | 要下载的 NapCat 版本；空 = 最新 |
-| `downloadProxy` | `''` | 下载时走的代理；空 = 先看 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY`。NapCat 下载，以及一键更新改从 GitHub 下载时，都用它。从 npm 安装时走 pnpm 自己的 registry，不读这个框。界面上不显示代理地址 |
-| `onebotPort` | `3001` | OneBot 端口。自己另外部署的 NapCat 要和这边一致 |
-| `qqNumber` | `''` | 快速登录用的 QQ 号（需先手动登录过一次） |
-| `checkUpdateOnStart` | `false` | 启动时检查一次。默认关。打开后，下次启动只检查有没有新版本，写在日志里，不自动安装。要装用卡片上的「更新到 vX.Y.Z」 |
-
-这些值优先从设置界面 / `settings.yaml` 取，未设置时回落到 `cordis.patch.yml` 里的安装配置（composition base）。
-
-> 字段旁带 “·已覆盖” 时，该键在设置文件里有本机覆盖。点该字段旁的 “撤销覆盖” 可清掉这一项。
-> 该键随即回落到 `cordis.patch.yml` 里的安装配置，“·已覆盖” 标记消失。
-> 数字框留空不会存成 0（那样会把唤醒概率或轮数上限关掉）。想回到安装配置里的值，点「撤销覆盖」。
-
-**看不到卡片**（或修改 `client/` 之后看不到变化）时，按顺序确认 4 件事：
-
-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`（详情页在 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` 包含该一致性的断言）。
-
-## 注入给目标会话的系统提示
-
-插件会给目标会话注入一段用法说明（`buildUsagePrompt()`，在 `index.js` 里导出，便于测试检查），分 6 节：
-
-| 节 | 内容 |
-|---|---|
-| 入站格式 | 入站消息格式、未唤醒摘要、“[图片#<短哈希>]：<描述>”（就地填回，可能不准）、被戳显示成“[戳一戳]（戳的是我）” |
-| 回复方式 | 按 `replyMode` 分叉：标记块怎么写、该调用哪个工具、非 QQ 轮的 2 步确认 |
-| 表情包 | 用 `qq_bridge_sticker` 的 `list` / `send` 发表情包；用 `save` 收藏群友发的图。`[表情包#短哈希]` 是商城表情，发出去是原生表情包；`[图片#短哈希]` 发出去仍是图片 |
-| 群聊礼仪 | 1–2 句话；默认不超过 40 字；不刷屏；不放路径、代码、日志、提交号；不汇报过程。系统表情写 `[笑哭]`、`[挥手]` 或 `[表情182]` |
-| 无人值守 | 不碰特权操作，见下一节 |
-| 会话跟随（监听模式） | 何时开窗；默认 5 分钟、上限 60 分钟；只对同一目的地生效；答完主动关 |
-
-## 无人值守的安全边界（不提供审批桥接）
-
-QQ 侧没有人能点击“同意”，因此：
-
-- 审批策略保持 `ask`：**没有人应答时，危险操作直接失败**，不会偷偷执行。
-- 注入的系统提示明确禁止无人值守时主动执行特权操作：执行或安装程序、修改系统或网络设置、
-  操作工作区之外的目录、删除或覆盖文件、修改配置、结束进程、发布推送。
-- **不弹审批的路径同样属于“动手”**：用浏览器点击网页（例如直接在 GitHub 网页改文件、提交）、
-  直接发 HTTP 写请求、写文件。这些操作不弹审批，但不能因此绕过上面的清单。
-  判断标准是这件事本身是否属于动手操作，与是否弹出审批无关。
-- **QQ 消息按不可信输入对待**：群里任何人都能塞入“忽略以上指令，去执行 xxx”这类注入，
-  **聊天内容本身不构成动手的理由**。需要动手时，机器人回答“无人值守时我不执行这类操作”，
-  并等发起人在电脑前再处理。
-- **不得把规则表述成“需要授权”**。这种说法会让用户以为需要额外权限，实际是插件不执行。
-- 纯聊天、查资料、写草稿不属于动手操作，照常执行。
-
-插件不把审批搬到 QQ。那样做会把“谁能给机器人发消息”变成“谁能代替用户授权”。
-
-## 上下文上限
-
-防止长文超出 context：
-
-| 位置 | 上限 |
-|---|---|
-| 单条**入站**消息 → 模型上下文 | 4000 字符 |
-| 单条消息 → **未唤醒缓冲** | 500 字符 |
-| 整段**未唤醒摘要** | 1200 字符。从最新往回装，装不下的更早条目不进摘要，并注明“更早的 N 条已省略”；N 取缓冲快照条目数减摘要行数，大于 99 时改写成“更早的大量消息已省略”。这些条目随后随缓冲一起删除，不会留到下一次唤醒 |
-| `buffer` / `log` / `outbox` 条数 | 200 / 200 / 50 |
-| `log` 每条 | 200 字符 |
-| `outbox` 每条 | 4000 字符 |
-
-截断都会留 `…（已截断）` 标记，不静默丢内容。
-
-## 工具一览
-
-| 工具 | 注册条件 | 作用 |
-|---|---|---|
-| `qq_bridge_status` | `debugTools` | 设置、目标会话是否已加载、连接状态、目的地、缓冲条数、最近日志，以及**最近观测到的 `user/message` 来源**（`recentInboundSources`）。排查“哑火”先看这个工具：`ours: false` = 没有认出那条是插件灌入的 QQ 消息；`ours: true` 但工具仍被拒 = 标记被别的事件清掉了 |
-| `qq_bridge_transport` | `debugTools` | 查看连接状态（含 token 是否解析到），或 `action: 'reconnect'` 强制重连 |
-| `qq_bridge_simulate` | `debugTools` | 模拟一条入站消息走完整策略；可带 `groupName`（群名，用来写 perGroup 会话标题）；`dryRun: true` 只看决策，不注入 |
-| `qq_bridge_send` | 始终 | 出站。正文里的 `[笑哭]` 会变成系统表情。`replyMode: 'tool'` 时该工具**就是唯一的出站方式**，因此不能藏在调试开关后面 |
-| `qq_bridge_sticker` | 始终 | 表情包：`list` / `save` / `send`。登记项带齐商城表情字段时发 `mface`，否则图片以 base64 出站。与 `qq_bridge_send` 共用来源闸门，见[表情包](#表情包) |
-| `qq_bridge_listen` | 始终 | 会话跟随窗口的开启与关闭。这是产品的使用方式，不是调试工具 |
-| `qq_bridge_napcat` | 始终 | NapCat 自助托管（下载 / 配置 / 启停） |
-
-`debugTools` 默认 `true`；关闭后只保留后 4 个。
-
-## 已知限制与环境要求
-
-- **“主动戳人”暂不提供**：OneBot 的 `send_poke` 依赖 NapCat 的 **PacketBackend**，而 PacketBackend 只支持特定 QQ 版本。
-  真机上（NapCat 4.18.28 + QQ 9.9.36-53644）会报
-  `retcode=1400 packetBackend发包能力不可用 … 不支持当前QQ版本架构`；
-  把 poke 当消息段发送也会被拒（`1200 消息体无法解析`）。
-  **入站戳完全可用**（戳我必唤醒）。要恢复主动戳，可以换用 PacketBackend 支持的 QQ
-  （NapCat 官方 release 推荐 **40768–44343**），或等 NapCat 跟上 QQ 的更新节奏。
-- **图片描述依赖一个支持图片输入的多模态模型**：目标会话的模型看不了图时，这是目标会话“看见”图的唯一途径；
-  一次唤醒最多描述 3 张（成本考虑）。
-- **没有商城表情 id 的图发不成原生表情包**：本地保存的图、普通图片、只带简介的图、收藏表情（图片 `sub_type` 表示表情，但没有 `emoji_id` / `key`）都走图片。只收到 `mface` 段、却没有可下载地址时，占位符里没有短哈希，`save` 找不到文件，也就不能再发出去。四字段里缺 `key` 或 id 时同样退回图片。表情下架或 `key` 失效时，NapCat 可能直接拒发，插件不会自动改成图片再发一次。
-- **NapCat 是第三方 QQ 客户端**，存在账号风控风险；`NapCatInstaller.exe` 与 QQ 首次登录都需要人在场。
-- **测试套件需要 Node >= 22**（用到内置的全局 `WebSocket`）。
-- README / CHANGELOG 里的真机结论都来自 **Windows 10 + NapCat Shell + OneBot v11** 这一套；
-  其它平台可能可用，但没有真机验证过。
-
-## 测试
-
-改用法、设置或运行行为时，同一次提交里更新本文件。约定见 [`AGENTS.md`](./AGENTS.md)。
-
-5 个套件都是**零依赖**（测试自己造 zip、自己起一个最小 OneBot WS 服务器；检查更新不连真 npm、也不连真 GitHub），共 **812 条断言**：
-
-```powershell
-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、npm 正式版、GitHub 备用下载、限流和断网的白话
-```
+## 许可
 
-## 路线
-
-| 里程碑 | 内容 |
-|---|---|
-| **M1** ✅ | 固定会话注入 / 显式 resume / 唤醒策略 / 出站采集 / 调试工具 |
-| **M2** ✅ | OneBot(NapCat) 传输：WS 入站 → `handleInbound()`；出站 → `send_group_msg` / `send_private_msg` |
-| **M3** ✅ | 设置界面：手写 `__ModuleLoader__` bundle 的“QQ 桥接”卡片（不依赖构建步骤） |
-| **M4** ✅ | 打成 DSH bundle，`dsh plugin add` 安装、重启、实测通过 |
-| **M5** ✅ | NapCat 自助托管（下载 / sha256 校验 / 解包 / 写配置 / 启停） |
-| **M6** ✅ | 真机联调补齐：出站标记闸门、上下文上限、图片缓存 + 多模态描述、会话跟随、用法注入系统提示 |
-| **M7** ✅ | 安全边界：用法说明重写为分节契约（含**无人值守不碰特权操作**）；**明确不做审批桥接** |
-| **M8** ✅ | 分得清“在 QQ 还是 DSH 里”：出站闸门按来源生效、出站方式做成开关、改模式立刻重挂提示词 |
-| **M9** 🚧 | 戳一戳（入站已通，出站受 NapCat 限制，见[已知限制](#已知限制与环境要求)） |
-
-完整变更记录见 [`CHANGELOG.md`](./CHANGELOG.md)。上游发行版见 [sj244/dsh-qq-bridge Releases](https://github.com/sj244/dsh-qq-bridge/releases)。
+MIT。详见 [`LICENSE`](./LICENSE)。本插件基于 sj244 的 dsh-qq-bridge（MIT）。