QQ 机器人通道 23bear/dsh-plugin-qq-bot

dsh-plugin-qq-bot

把 QQ 官方机器人（q.qq.com 开放平台）接成 DeepSeek Harness 的一个输入通道：在 QQ 群里 @机器人 或在私聊里发消息 → DSH 用对应会话处理 → 回答回到 QQ。

一个 QQ 用户 / 一个 QQ 群固定对应一个 DSH Session（id 形如 session-qq-c2c-<openid>、 session-qq-group-<group_openid>），所以多轮上下文由 DSH 自己的会话持久化维护，插件不额外维护映射表；在 GUI 里能直接看到并归档这些会话。

一、先在 QQ 侧准备

1. 打开 <https://q.qq.com>，用 QQ 号登录「QQ 开放平台」，创建机器人应用（个人主体也能建）。
2. 在「开发设置」里拿到 AppID 和 AppSecret（客户端密钥）。
3. 在「功能配置」里开启 单聊（私聊）和 / 或 群聊 场景。群聊场景需要在「沙箱配置」里把你自己的测试群加进去（新版群/单聊机器人没有沙箱域名，管理员账号本身就是测试账号，直接用真实环境）。
4. 群聊场景下，机器人需要被拉进群；测试期建议只把小号/测试群加进去。

官方文档：<https://bot.q.qq.com/wiki/develop/api-v2/>

二、把凭据交给插件

三种方式，按优先级：插件配置 → 环境变量 → 凭据文件。

推荐第三种（不把密钥写进 profile 补丁）：

// ~/.dsh/qq-bot.json
{
"appId": "你的 AppID", "clientSecret": "你的 AppSecret" }

或设环境变量 DSH_QQ_APP_ID / DSH_QQ_CLIENT_SECRET。
也可以在 profile 的 cordis.patch.yml 里写：

- id: qq-bot
name: dsh-plugin-qq-bot
config:
appId: "..."
clientSecret: "..."

凭据文件会被轮询：补上或修改 ~/.dsh/qq-bot.json 后，插件在几秒内自动连上网关， 不需要重启 DeepSeek Harness（credentialsPollMs 控制轮询间隔）。
只有改动插件配置项（cordis.patch.yml 里的 config:）才需要重启。

三、配置项

| 配置 | 默认 | 说明 |
| enabled | true | 关掉后插件只写状态文件、不连网关 |
| appId / clientSecret | "" | 留空则走环境变量 / 凭据文件 |
| apiBase | https://api.bot.qq.com | 官方接口根地址（2026-08-10 起统一域名） |
| intents | 33554432 | 1<<25，同时覆盖群聊@与单聊 |
| agentPreset | standard | 这些会话使用的 Agent 预设（也是平台默认预设） |
| workspace | ~/.dsh/qq-bot-workspace | 会话工作目录；想让它操作某个项目就指过去 |
| allowOpenIds | [] | 只响应这些 openid / group_openid；留空不限制 |
| replyChunkChars | 1500 | 单条消息最大字符数，超出分片发送 |
| maxWaitMs | 900000 | 单轮最长等待；超时先把已有内容发出去 |
| ackAfterMs | 12000 | 超过这么久还没答就先回一句「正在处理」；0 关闭 |
| ackText | 收到，正在处理… | 上面那句的文案 |
| credentialsFile | ~/.dsh/qq-bot.json | 凭据文件路径 |
| credentialsPollMs | 5000 | 轮询凭据文件内容变化的间隔（毫秒） |

四、怎么确认它跑起来了

状态会写到 ~/.dsh/qq-bot-state.json：

{
"status": "ready", // starting / connecting / ready / closed / reconnecting / missing-credentials
"lastMessageAt": 1760000000000,
"lastSessionId": "session-qq-c2c-XXXXXXXX",
"lastSummary": "[正常完成，12.3s]",
"events": [ { "at": 1760000000000, "message": "info: access_token 已获取，有效期 7200s" } ]
}

- missing-credentials → 凭据没被读到；补上文件后插件会自动重试，不用重启。
- closed / reconnecting 反复出现 → 看 events 里的日志：
- 日志里带 （这通常是 AppID / AppSecret 不对…） 或 机器人不存在 → 凭据或平台配置问题。
- 服务端以 4013/4014 断开 → intents 没权限（群 + 单聊要 33554432）。
- 先出现 access_token 已获取 再断开 → 凭据没问题，检查平台上的场景/群配置。

已实测（2026-10-14）：api.bot.qq.com 同时提供 access_token 与 OpenAPI；用无效 AppID 请求 token 会返回 HTTP 200 + {"code":10004,"message":"机器人不存在"}，所以判定成败必须看 body 里的 code（插件已按此实现）。

五、行为细节

- 被动回复优先：群里 5 分钟内、单聊 60 分钟内，用收到的那条消息的 msg_id 回复（群里最多 5 条、单聊最多 4 条，msg_seq 递增）。超出窗口或次数后自动改走普通消息。
- 同一个会话串行：同一个 QQ 用户/群的多条消息排队处理，不会互相打断；不同会话并行。
- 超时保护：单轮超过 maxWaitMs 会把当前已有的文本先发出去，并在末尾标注超时。
- 回复末尾会附一行状态，例如 [正常完成，12.3s]，方便知道这轮是怎么结束的。
- 两条本地指令（不占用 DSH 轮次，用来快速确认链路通不通）：
- /ping → 回 pong ✅ 加网关状态、凭据来源、本会话 id
- /help → 回一段使用说明

六、开发与测试

单元测试（不需要 DSH、不需要网络）
node --test

测试覆盖：文本分片、事件归一化、桥接投递顺序与串行、以及用一个假 WebSocket + 假 fetch 跑完整的「Hello → Identify → READY → 收消息 → 被动回复 → 过期回退主动消息」链路。

七、写 DSH 插件时踩到的两个坑

这两条都是真实联调时才暴露的，跟 QQ 无关，任何 DSH 插件都可能遇到。

1. sessionController.prompt(request, signal) 的 signal 不能省。 它的 @Remote 门面第一行是 signal.throwIfAborted()，且没有 ?. 兜底：

prompt(request, signal) {
signal.throwIfAborted();
return this.commands.prompt(request);
}

少传第二个参数就报 TypeError: Cannot read properties of undefined (reading 'throwIfAborted')。
官方服务契约里只写 prompt(request, signal)，看不出哪个参数可省 —— 实测 create 和 resolveAgent 都不需要 signal，只有 prompt 需要。
本插件在测试里用一个「复刻真实契约」的假 sessionController 看住这一点。

2. 改完插件代码，重新挂载不等于加载新代码。 ESM 模块按 URL 缓存，dsh plugin add 重新装、或把 bundle 关掉再打开，插件会重新
apply()（状态文件里的挂载时间会变），但跑的还是缓存住的旧模块。只有重启
DSH 进程才会真正换代码。

插件为此在状态文件里写了 codeVersion；node tools/check.mjs 会直接告诉你当前进程跑的是哪一版，缺失就说明还是旧模块。

八、许可

MIT