前言¶
做 DeepSeek Harness（DSH）渠道插件时，常见的问题是：Web 侧会话已经可用，但 QQ 侧缺少一个可直接运行的 channel 插件；要自己接 Gateway、处理消息、文件、审批和会话持久化，成本不低。
下面介绍 sliverp/DeepSeek-harness-qqbot。它是一个 out-of-tree DeepSeek Harness channel plugin，用官方 @tencent-connect/qqbot-nodejs Gateway client 把 QQ Bot 接入 persistent Harness agents，覆盖 C2C 和群聊文本、图片、文件、审批与命令。
这是什么¶
- 插件名：
sliverp/DeepSeek-harness-qqbot - 维护者：
sliverp - 许可证：MIT
- 定位：DSH channel plugin，将 QQ Bot Gateway 接到 persistent Harness agents。
核心功能¶
会话与消息¶
- C2C 和群聊文本消息。
- 每个 C2C 或群聊会话对应一个 persistent Harness session。
/new和/reset会保留旧历史，并切换到新的 durable session。- 入站 PNG、JPEG、WebP、GIF 图片会作为 durable Harness attachments 处理。
- 如果所选模型不接受图片输入，会自动退化为纯文本。
- 入站语音转写文本和非图片附件元数据会携带临时 QQ 下载 URL。
- 出站支持助手文本、图片和本地 workspace 文件。
文件发送¶
- 提供 QQ-turn-scoped
qq_send_file工具，用于在当前 QQ 轮次发送文件。 - 工具限定在 workspace 内，并做文件大小检查。
- 只接受
cwd内的 regular files，解析符号链接，拒绝大于 104,857,600 字节（100 MiB）的文件。
QQ 能力¶
- QQ Markdown 回复默认开启；需要 QQ Markdown permission，否则 QQ API 会拒绝 Markdown 消息。
- 支持 typing indicators、长回复拆分、按会话排序、去重、发送重试和有界超时。
审批与访问控制¶
- 对需要 Harness approval 的操作，会发送 requester-bound QQ 审批消息，带 one-shot Allow 和 Reject 按钮。
- 只有发起当前轮次的 QQ 用户可以批准或拒绝。
- 审批超时默认 120,000 毫秒，未答复会被拒绝。
- 支持 fallback 到另一个 composed approval channel。
- C2C 和群聊流量可使用 open、allowlist 或 disabled access policy。
- 含非公开数据的 workspace 建议使用 allowlist；被允许的 QQ 用户也能访问所选 agent preset 提供的工具。
DSH 集成¶
- 密钥通过 Harness credential service 解析，而不是直接写在插件配置里。
- AppID 或 AppSecret 未配置时，插件以 dormant 方式启动，不阻塞 DSH。
- 无效 QQ credentials 只会让 QQ channel offline，不会导致 DSH 启动失败。
- 支持 Harness agent-preset composition，用于 tools、prompts、skills。
- 如果 Web 已经打开了同一个 live session，QQ 侧会安全复用，不会创建第二个 session writer。
环境要求¶
- Node.js 22.19 或更高版本
- pnpm 10.33.4
- DeepSeek Harness 0.1.0-rc.7 或更高版本
- QQ Bot AppID 和 AppSecret，且启用 C2C 和/或 group message events
- 如需 QQ 审批按钮，需要 Inline Keyboard permission
package.json声明版本为 0.1.5
安装与启用¶
从 GitHub 安装：
pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-qqbot
如果已有本地 checkout，也可以直接安装路径：
pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-qqbot
开发时可以在启动环境中设置凭据：
export QQBOT_APP_ID='your-app-id'
export QQBOT_APP_SECRET='your-app-secret'
pnpm dsh --profile web
如果要长期运行，可以把 QQBOT_APP_ID 放入 ~/.dsh/.env，并通过 Harness credential settings surface 保存 QQBOT_APP_SECRET。两个值都不要提交到代码仓库。
也可以通过覆盖 ~/.dsh/profiles/web/cordis.patch.yml 中的插件行，调整访问策略或限制。
典型用法¶
1、启动 DSH，等待日志出现 QQ Gateway connected。
2、给机器人发送：
/bot-ping
3、发送普通文本或图片。消息会追加到对应会话的 durable Harness session，模型回复会回到 QQ。
4、发送 /new，确认机器人报告新的会话。
5、发送已注册命令，例如：
/goal
/plan
/compact
其他可用命令包括：
/bot-ping
/bot-image-test
/bot-file-test
/bot-help
/bot-status
/bot-cancel
适用场景与注意¶
适合需要在 QQ C2C 或群聊中使用 DSH agents 的场景，尤其是希望复用持久会话、agent preset、文件发送和审批流程的团队。
注意：
- 插件以当前
dsh进程权限运行，安装前应检查源码与许可证。 - 如果 workspace 含非公开数据，使用 allowlist 策略。
- QQ Markdown 权限未开启时，关闭 Markdown 回复，避免 QQ API 拒绝消息。
qq_send_file只发送cwd内的常规文件，且受 100 MiB 限制。- 审批按钮依赖 Inline Keyboard permission；超时默认 120,000 毫秒。
结尾¶
sliverp/DeepSeek-harness-qqbot 把 QQ Bot 的收发、会话、文件和审批接到 DSH 的持久 agent 会话上，适合作为 QQ 渠道插件的起点。
GitHub：https://github.com/sliverp/DeepSeek-harness-qqbot
