dsh-plugin-qq-bot
QQ 官方机器人通道：在 QQ 群或私聊里直接与 DSH 会话对话 —— 收到消息后唤醒/续接一个 DSH Session，把回答发回 QQ
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:23bear/dsh-plugin-qq-bot#ecacfccec901c8fb72c84e0e944f4bb22f8de935Plugin Qq Bot 以 dsh-plugin-qq-bot 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
把 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 里能直接看到并归档这些会话。
三种方式，按优先级：插件配置 → 环境变量 → 凭据文件。
推荐第三种（不把密钥写进 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 不对…） 或 机器人不存在 → 凭据或平台配置问题。intents 没权限（群 + 单聊要 33554432）。access_token 已获取 再断开 → 凭据没问题，检查平台上的场景/群配置。已实测（2026-10-14）：
api.bot.qq.com同时提供 access_token 与 OpenAPI；用无效 AppID 请求 token 会返回 HTTP 200 +{"code":10004,"message":"机器人不存在"}， 所以判定成败必须看 body 里的code（插件已按此实现）。
msg_id
回复（群里最多 5 条、单聊最多 4 条，msg_seq 递增）。超出窗口或次数后自动改走普通消息。maxWaitMs 会把当前已有的文本先发出去，并在末尾标注超时。[正常完成，12.3s]，方便知道这轮是怎么结束的。/ping → 回 pong ✅ 加网关状态、凭据来源、本会话 id/help → 回一段使用说明# 单元测试（不需要 DSH、不需要网络）
node --test
测试覆盖：文本分片、事件归一化、桥接投递顺序与串行、以及用一个假 WebSocket + 假 fetch 跑完整的「Hello → Identify → READY → 收消息 → 被动回复 → 过期回退主动消息」链路。
这两条都是真实联调时才暴露的，跟 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