dsh-qq-bot
把已经在用的 DSH 会话接到 QQ 个人号。协议是 OneBot，常用实现是 NapCat。
Cordis 插件 id 是 qq-bridge。npm 包名是 @fengye_nobug/dsh-qq-bot。界面显示名是 dsh-qq-bot。
唤醒、出站、图片、NapCat 和全部设置项见 DESIGN.md。变更见 CHANGELOG.md。
简介
消息进入你指定的会话，回答可以发回 QQ。白名单默认全关。被 @、叫到昵称或被戳时会叫醒；其余消息按概率抽样。群白名单可以由主人在 QQ 里用整句命令修改。
功能
- 接到一个已有会话，或按群、按私聊各记一条会话。
- 白名单留空时，任何群和私聊都不会叫醒。
- 被 @、命中昵称、被戳一定叫醒。其余按
wakeProbability（默认0.05）抽样，没抽中只记录。 - 发回 QQ 的内容由
replyMode决定。在 DSH 界面里聊同一个会话时，正文不会进群。 - 图片先落盘，叫醒时写成文字。表情包可以登记后再发。半角方括号里的
[表情名]会变成 QQ 系统表情。 - 设置卡片在 设置 → 插件 → 插件配置 → QQ 桥接。可以检查更新；有新正式版时一键安装，并重启面板。
- 可以按需下载、配置、启停 NapCat。加载插件时不会自己下载或执行。
不做审批桥接，也不走 QQ 官方机器人。
安装
日常安装用 npm 上已经发出的版本。仓库源码如果比已发布的版本新，不要直接装 main。
dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
registry 里还没有这一版时：
dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5
装完重启 dsh-web。
环境：DSH 0.1.5-rc.3，或 0.2.0 及以后；Node ≥ 22；NapCat 的 OneBot v11 正向 WebSocket。
cordis.patch.yml 里 qq-bridge 的 name 写成 @fengye_nobug/dsh-qq-bot。写成 dsh-qq-bot 或 dsh-qq-bridge 时插件挂不上，设置接口是 HTTP 404。
不要和另一个 Cordis id 也是 qq-bridge 的 QQ 插件一起挂，它们会抢同一条 OneBot。已经装着 dsh-qq-bridge 时，先卸掉再装上面的包，然后重启。profile 里按 id: qq-bridge 写的覆盖可以留着；其中的 name 同样写成 @fengye_nobug/dsh-qq-bot。
升级的几条路径、开发期怎么链到本地目录，见 DESIGN.md 的「使用细节」。
配置
白名单默认全关。先在设置卡片里填「哪些群可以叫醒」或「哪些私聊可以叫醒」，保存后再去 @。不要把真实群号、QQ 号写进仓库。
群白名单仍按群号填写。连上之后，卡片里每个群号旁边会显示当前群名和头像。没连上，或暂时查不到，就只显示群号，保存不受影响。
DSH 0.2 的卡片把值写进 $DSH_HOME/qq-bridge-settings.json。这份文件比 cordis.patch.yml 优先，保存后马上生效，重启还在。只改 cordis.patch.yml 要重启。
主人 QQ 在设置卡片里就叫「主人 QQ」（ownerWhitelist，默认 []）。只有这些号能在 QQ 里改群白名单。留空 = 这些命令不会生效。 多个号用逗号分开。保存后下一条消息就生效。只改 cordis.patch.yml 要重启；设置文件里已有同名键时，以设置文件为准。
accessTokenEnv 填凭据引用名（一个环境变量名）。token 由 DSH 凭据服务解析，不要写进配置文件。每次建连重新解析。
| 键 | 默认 | 效果 |
|---|---|---|
targetSessionId |
空 | single 时接到哪个会话。留空 = 不接到任何会话 |
sessionScope |
single |
perGroup 时每个群、每个私聊各一条会话 |
maxRecentTurns |
40 |
每个会话最多留几轮。QQ 一轮结束并空闲后，更早的内容会尽量压缩掉。用的是这条会话自己的压缩（标准人设里就有）。人设没有时再看会话作用域和宿主。已经超限却找不到压缩，或这次压缩没有改动会话时，记一条警告。0 = 不限制 |
nicknames |
244、小助手 |
听到这些名字就叫醒 |
wakeProbability |
0.05 |
没点名时的叫醒概率 |
whitelist |
[] |
哪些私聊可以叫醒。留空 = 都不叫醒 |
groupWhitelist |
[] |
哪些群可以叫醒。留空 = 都不叫醒。卡片里查到群名时，群号旁边有名字和头像 |
ownerWhitelist |
[] |
卡片里叫「主人 QQ」。留空 = 不能在 QQ 里改群白名单 |
onebotUrl |
空 | NapCat 正向 WebSocket。留空 = 不连接 |
atOnlyInGroup |
false |
打开后，群里没被 @ 就不处理 |
replyMode |
marker |
群里发出去的是哪一段：只发「发给群」里的那段 |
其余键见 DESIGN.md。
使用
在群里 @ 机器人，或叫出昵称。白名单没填时不会醒。
主人改群白名单时，整句必须就是命令，前面可以加一个 /。多出来的字不当命令。不是主人时按普通聊天处理：不改配置，也没有单独的拒绝回复。还没进白名单的群，主人仍能在群里直接加。调试工具模拟的消息不会改白名单。
| 在哪 | 整句 | 作用 |
|---|---|---|
| 群里 | 白名单 加、白名单 加本群 |
把当前群加进群白名单 |
| 群里 | 白名单 删、白名单 删本群 |
把当前群移出 |
| 群或私聊 | 白名单 加 群号、白名单 删 群号 |
按写明的群号加或删 |
| 群或私聊 | 白名单、白名单 列表 |
回复现在有几个群 |
| 私聊 | 白名单 加（没写群号） |
不改配置，提示要写群号 |
删到一个群都不剩时，回复会说明现在任何群都不会叫醒。保存方式和设置卡片相同。
replyMode 为 marker 时，模型把要发到群里的话放进 [QQ]…[/QQ]。会话跟随、表情包和戳一戳见 DESIGN.md。
更新
设置卡片里先点「检查更新」。有新正式版时点「更新到 vX.Y.Z」。优先从 npm 安装；这一版还没发到 npm 时，改从 GitHub 下载。装完会自己重启 dsh-web。设置还在，不改 NapCat。刷新页面后，登录口令可能会变。
0.2.12 起，重启后如果 $DSH_HOME/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/references/reply-style.md 里还有 “Emoji are welcome when they make the answer friendlier.”，会删掉这一句。「Avoid Markdown formatting. Use plain text.」还在，其它行不动，也不另写禁用表情的规矩。这份文件本来没有时不会新建。不用删掉整个人设目录。已经读进当前会话的旧规则，要等下次再读这份说明，或另开一条会话。
「检查更新」和「启动时检查一次」只询问，不会安装。
维护者发版：
- 改
package.json的version。 - 在
CHANGELOG.md顶部写这一版。 - 推到
main。
推到 main 后，Actions 在 npm 上还没有 @fengye_nobug/dsh-qq-bot 的这一版时才发布，并补 tag vX.Y.Z 和 GitHub Release。NPM_TOKEN 放在仓库 Actions Secrets，不写进仓库。
许可
MIT。详见 LICENSE。本插件基于 sj244 的 dsh-qq-bridge（MIT）。
