前言¶
DeepSeek Harness（DSH）的会话、预设和工作区都在本机进程里跑。想在手机上随手问一句、或在群里 @ 一下就能续接同一轮上下文，通常得再搭一层 IM 桥接：自己维护 WebSocket、消息格式和「QQ 用户 ↔ Session」映射，成本和联调面都不小。
dsh-plugin-qq-bot（维护者 23bear，分类：客户端）走 QQ 开放平台官方机器人通道：在 QQ 群或私聊里发消息，由 DSH 用固定 Session 处理，回答回到 QQ。一个 QQ 用户或一个群对应一个 DSH Session（如 session-qq-c2c-<openid>、session-qq-group-<group_openid>），多轮上下文交给 DSH 自己的会话持久化，插件不另建映射表，GUI 里也能直接看到并归档这些会话。
社区目录页：skillhub.cn/plugins/23bear/dsh-plugin-qq-bot（当前标注版本 v0.1.0，可安装客户端类插件）。源码与说明：github.com/23bear/dsh-plugin-qq-bot。许可：MIT；运行环境要求 Node >=22.15.0。
这是什么¶
插件把 q.qq.com 开放平台的官方机器人接成 DSH 的一个输入通道：收到 QQ 消息 → 唤醒或续接对应 Session → 把模型输出发回 QQ。简介原文：QQ 官方机器人通道插件 for DeepSeek Harness — talk to your DSH sessions from QQ groups and private chats.
核心功能¶
- 群聊与单聊：在群里 @ 机器人或私聊发消息，均可触发 DSH 处理（需在 QQ 开放平台开启对应场景）。
- Session 一一对应：按 openid / group_openid 生成稳定 Session id，多轮对话不依赖插件侧映射表。
- 凭据热更新：推荐
~/.dsh/qq-bot.json；补上或修改后数秒内自动连网关，一般无需重启 DSH（改cordis.patch.yml里的config:仍需重启进程）。 - 可观测状态：
~/.dsh/qq-bot-state.json记录ready/missing-credentials等状态与events日志。 - 消息与并发策略：同一会话内消息串行；不同会话并行；超长回复按
replyChunkChars分片；超时与「正在处理」提示可配置。 - 本地探活：
/ping、/help不占用 DSH 轮次，用于确认链路与会话 id。
先在 QQ 侧准备¶
下面按 README 顺序在开放平台侧做完，再配置 DSH。
- 打开 https://q.qq.com，用 QQ 号登录「QQ 开放平台」，创建机器人应用（个人主体也可）。
- 在「开发设置」获取 AppID 与 AppSecret（客户端密钥）。
- 在「功能配置」开启 单聊 和/或 群聊。群聊需在「沙箱配置」加入测试群（新版群/单聊机器人无沙箱域名时，管理员账号即测试账号，可直接用真实环境）。
- 群聊场景下将机器人拉进群；测试期建议只用小号或测试群。
官方 API 文档：bot.q.qq.com/wiki/develop/api-v2/。接口根地址自 2026-08-10 起统一为 https://api.bot.qq.com（插件配置项 apiBase 默认值即此）。
安装与启用¶
已抓取资料与目录页均未给出固定的 dsh plugin add … 安装命令，请勿凭仓库名自行拼接。将插件作为客户端类条目安装到当前 DSH 环境后，按下面方式交凭据并（可选）改配置。
凭据：三种方式（优先级：插件配置 → 环境变量 → 凭据文件）¶
推荐凭据文件，避免把密钥写进 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: "..."
凭据文件会被轮询（间隔由 credentialsPollMs 控制，默认 5000 ms）；仅当修改 config: 下其它配置项时需要重启 DSH。
常用配置项¶
| 配置 | 默认 | 说明 |
|---|---|---|
enabled |
true |
为 false 时只写状态文件、不连网关 |
appId / clientSecret |
"" |
留空则走环境变量或凭据文件 |
apiBase |
https://api.bot.qq.com |
官方接口根地址 |
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 |
凭据文件轮询间隔（毫秒） |
典型用法：确认跑起来并在 QQ 里对话¶
1. 看状态文件¶
插件将运行状态写入 ~/.dsh/qq-bot-state.json，例如：
{
"status": "ready",
"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）。README 注明：对api.bot.qq.com用无效 AppID 请求 token 可能仍返回 HTTP 200，需看 body 里code（如10004机器人不存在）。
2. 在 QQ 里发消息¶
群聊 @ 机器人或私聊发送内容，等待 DSH 处理。回复末尾会附一行状态（如 [正常完成，12.3s]）。可先发 /ping 或 /help 做链路自检。
行为摘要（来自 README）：
- 被动回复优先：群 5 分钟内、单聊 60 分钟内可用
msg_id被动回复（条数有上限）；超出后改普通消息。 - 单轮超过
maxWaitMs会先发出已有文本并标注超时。
适用场景与注意¶
适合谁：已在用 DSH、希望用 QQ 官方机器人（而非第三方协议）做群/私聊入口的开发者；需要把固定 QQ 身份绑定到可归档 Session 的场景。
权限与安全：插件随当前 DSH 进程运行，具备该进程能访问的本机资源与网络能力。安装前请阅读仓库源码与 MIT 许可证，自行评估 AppSecret 存放方式（凭据文件权限、是否写入 patch 等）。allowOpenIds 可在联调期收窄可响应的群或用户。
改插件代码后：README 强调 ESM 模块缓存——重新挂载或 dsh plugin add 不等于加载新代码，需重启 DSH 进程；可用状态文件中的 codeVersion 或 node tools/check.mjs 核对当前进程版本（属开发联调说明）。
生态说明：DSH 社区插件目录（SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；安装与命令以你环境中的 DSH 与目录页说明为准。
结尾¶
dsh-plugin-qq-bot 把 QQ 开放平台官方机器人收成 DSH 的一条客户端通道：凭据与配置按文档落地后，在群或私聊里即可对接本地 Session 与预设。目录：https://www.skillhub.cn/plugins/23bear/dsh-plugin-qq-bot；仓库：https://github.com/23bear/dsh-plugin-qq-bot。
