前言¶
在 DeepSeek Harness（DSH）里跑 Agent，产出往往还在工作台里；要送到同事或客户常用的 QQ 群、私聊，常见做法仍是人工复制粘贴。QQ 开放平台有官方机器人，本机也可以跑 NapCat、Lagrange.OneBot 等 OneBot v11 框架，但和 DSH 之间缺少一条统一、可审计、能被工具调用的通道。
@deepwhale-cn/dsh-qq-bridge（社区仓库 feely0208/dsh-qq-bridge）是 DSH 的客户端类插件：从 v0.3 起可在 QQ 官方机器人 WebSocket 与 OneBot v11 HTTP 两条通道里二选一；侧栏收发、入站入队、全量审计 JSONL；官方通道还可选开关键词规则自动回复（默认关闭）。下面介绍它解决什么问题、怎么装、怎么用。
这是什么¶
插件 npm 包名为 @deepwhale-cn/dsh-qq-bridge，当前资料中的版本为 0.3.1，MIT 许可证，维护者 feely0208（仓库与 SkillHub 目录页 一致）。定位一句话：把 QQ 接进 DSH——发消息、收入站、留审计。
与「只在 IM 里挂一个独立 bot」相比，它把 QQ 侧事件和发送能力接到 DSH Web 侧栏与 qq_send 等工具链上，本地队列上限 1000 条，收发与失败原因（含官方 code / trace_id）写入本机审计文件。AppSecret、access_token 只存本机，请求 10s 超时，只连官方域名或你配置的 OneBot 端点。
核心功能¶
双通道二选一¶
通道一：QQ 官方机器人（v0.2 起，README 推荐先用）
- 只需在 q.qq.com 创建机器人，填写 AppID、AppSecret，无需本机跑 OneBot 框架。
- 走 QQ 开放平台 WebSocket；订阅群 @ 与私聊等事件，归一化入队。
- 沙箱勾选时走
sandbox.api.sgroup.qq.com，正式环境走api.sgroup.qq.com。
通道二：OneBot v11（v0.1 起）
- 依赖本机已有 OneBot v11 HTTP API（如 NapCat、LLOneBot、Lagrange.OneBot）。
- 面板配置端点（例如
http://127.0.0.1:3000）、access_token、可选上报共享密钥；OneBot 上报地址设为http://127.0.0.1:<DSH Web 端口>/dsh-qq-bridge/api/hook。
两条通道的入站都进入同一队列；配置集中在 ~/.dsh/qq-bridge.json（权限 0600），字段 mode 为 official 或 onebot（未配时默认 onebot，兼容老配置）。
发送、入站与审计¶
- 发得出去：面板或工具把纯文本（≤4000 字符）发到私聊 c2c、群 group、频道等；支持带
msg_id的被动回复。 - 收得进来：官方 dispatch 与 OneBot 上报写入本机 inbox；群消息需真正 @ 机器人才会收到（平台规则）。
- 留得下痕：
~/.dsh/qq-bridge-audit.jsonl记录动作、结果与错误；inbox 在~/.dsh/qq-bridge-inbox.json。富媒体、撤回、按钮交互当前未实现。
自动回复（v0.3，仅官方机器人通道）¶
默认关闭。开启后：入队后按面板规则行顺序匹配关键词（包含 / 精确: / 正则:），命中则用模板回复，占位符含 {昵称}、{内容}、{时间}；一律用原消息 msg_id 被动回复。内置防刷：同会话最小间隔默认 30s、全局每小时上限默认 60 条、连续 3 次失败自动暂停等。OneBot 通道仍只入队与审计，不做自动回复。
README 列举的典型用法方向：法律/客服接待归档、企业审批通知、多渠道统一后台的基础 IM 通道。
安装与启用¶
在终端执行（命令来自插件 README）：
dsh plugin --profile web add @deepwhale-cn/dsh-qq-bridge
装完后重启 DSH 桌面端或 Web 配置对应的 DSH 实例，侧栏会出现「QQ 桥接」。package.json 中声明的 DSH 引擎范围为 >=0.1.0-rc.6 <0.3.0，Node >=18；安装前请对照你本地的 DSH 版本与插件源码、许可证。
典型用法¶
官方机器人：从零到连通¶
- 执行上述安装命令并重启。
- 浏览器打开 q.qq.com，创建机器人，在「开发设置」复制 AppID、AppSecret。
- 侧栏「QQ 桥接」→「QQ 官方机器人」→ 粘贴并「保存配置」→ 点「连接」，状态为
已连接（机器人名）即成功。 - 将机器人拉进群或让用户私聊；群里须从成员列表 @ 机器人，手打「@名字」不算。
- 可选：「自动回复」卡片打开开关，配置默认模板与规则行，「保存并生效」。
手机端只需 QQ 客户端聊天；配置在电脑完成。电脑关机或 DSH 未运行时，机器人不会回复——逻辑跑在本机，不是云端托管服务。
OneBot：端点与上报¶
- 本机启动 OneBot v11 框架，记下 HTTP API 地址与 token。
- 面板「通道切换」选 OneBot v11，填写端点与
access_token，保存。 - 在框架里把 HTTP 上报指到 DSH 的 hook 路径，并与面板「上报共享密钥」或
access_token校验方式一致。
Agent 侧¶
插件作为 DSH 客户端注入 Web 平台（dsh.client.platform: web），并提供发送等能力；具体工具名与参数以面板和仓库文档为准（README 提到 qq_send）。入站消息可在面板「入站 / 审计」查看，并可用「回复」带入 msg_id 做被动回复，避免主动消息配额错误（如 40034105）。
适用场景与注意¶
适合谁：已在用 DSH 做 Agent 或自动化，又需要 QQ 作为触达或收集入口的团队；希望本地留存收发审计、而不是只在第三方 bot 控制台里翻记录的场景。
权限与安全：插件以当前 DSH 进程权限运行，会读写 ~/.dsh/ 下 qq-bridge 相关文件（明文、0600）。安装前应自行审查 GitHub 源码 与 MIT 许可证；勿把含 AppSecret 的配置或审计文件放进共享目录或云盘。须遵守 QQ 开放平台服务条款；插件不提供绕过审核、自动加群或群发能力。
常见报错（面板对照 README 报错表）：主动消息无权限 40034105、被动回复窗口过期 40034005、token 错误 401、OneBot fetch failed 需先启动框架或改走官方通道；沙箱与正式环境的密钥/地址不可混用。
结尾¶
@deepwhale-cn/dsh-qq-bridge 补的是 DSH 与 QQ 之间「可控、可审计、可工具化」的一段：官方机器人或 OneBot 二选一，侧栏收发与全量审计，官方通道还可选关键词自动回复。社区目录与 DeepSeek / 幻方无官方从属关系，属 DSH「一切皆插件」生态中的独立条目。
