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