前言¶
在 DSH 里跑 Agent，常见入口是 Web UI 或桌面客户端。若希望同事、群友在 QQ 里直接对话，而不另写一套机器人网关，需要把 QQ 的收发协议接到 DSH 的会话与工具链上。社区里已有 NapCat、Lagrange 等 OneBot 11 实现负责登录 QQ 与风控；缺的是一层「OneBot 事件 → DSH Agent → 回发 QQ」的 profile 插件。
下面介绍维护者 arrow1031 的 dsh-qq-bot：装进 DSH profile 后，每个 QQ 私聊或群会话对应一个 DSH Agent 会话，复用 NapCat（或其它 OneBot 11 实现），不自造 QQ 协议。插件要求 DSH ≥ 0.1.7（0.6.1 起）；仓库 README 写明 已封版、不承诺持续维护，MIT 许可，遇到问题需自行 fork 修改。
这是什么¶
dsh-qq-bot 是 DeepSeek Harness（DSH）的 客户端类 插件：QQ 消息经 OneBot 11 进入插件自带的适配器，再交给 Cordis 侧逻辑，由 sessionController → agent.followup 驱动 DSH Agent，回复经 HTTP 或 WS action 发回 QQ。
数据流可概括为：
QQ 客户端 → NapCat 等（OneBot 11）→ lib/onebot-adapter.mjs → lib/index.js（Cordis）
→ DSH Agent；设置面板由 lib/client.js 提供「设置 → QQ 机器人」选项卡。
维护者：arrow1031。源码与说明：GitHub - arrow1031/dsh-qq-bot；社区目录页：SkillHub 插件页。当前 package 版本 0.6.1，Node ≥ 22.6，许可 MIT。
核心功能¶
以下能力均来自仓库 README 与 package 声明，且 README 列出多组本地回归测试（适配器、插件端到端、客户端设置页、权限与群管理等）已通过。
- OneBot 11 双模式：默认 正向 WebSocket（插件连
ws://127.0.0.1:3001）；可选 反向 WS（插件在0.0.0.0:6199监听，由 NapCat 连入）。HTTP 默认3000用于发消息，与 NapCat 默认端口一致。 - 一会话一 Agent：
perChatSession: true时，每个群/每个私聊独立 DSH 会话（id 形如qqbot-group-33333），可落盘并在 Web UI 会话列表中继续聊。 - 群聊与私聊策略：群聊默认需 @机器人 才触发（@ 会从正文去掉再交给 Agent）；私聊默认直接回复。长回复按换行切分，默认单条不超过 1200 字。
- Web 设置页：DSH ≥ 0.1.7 下，配置写入 profile 的 cordis.patch.yml；连接模式、地址、token、白名单、preset、权限与群管理项等集中在一个选项卡。access_token 为只写字段，已设置时留空保存不会清空。
- 权限与群管理：静态拥有者/超级管理员、本群管理员身份、动态授权等多路并行；访客默认不开放 DSH 内部工具，可通过白名单保留
qqbot、qqgroup等。管理指令前缀、dry-run 等见 README「权限与群管理」一节（正文资料截断处仍可在仓库完整阅读）。 - 工具与状态：可在对话中让 Agent 调用
qqbot工具（action=status）查看连接状态，而非在设置页展示。
适配器 lib/onebot-adapter.mjs 为零 npm 依赖；运行时依赖 @deepseek-ai/schemastery，peer 可选 @deepseek-ai/dsh-tools。
安装与启用¶
安装前请确认 DSH 版本：0.6.1 及以后需要 DSH ≥ 0.1.7；DSH 0.1.6 及更早应使用插件 0.6.0。插件不在 npm 上，通过 dsh plugin 从 GitHub 或 Release tarball 安装。
1. 准备 OneBot 11（推荐 NapCat）¶
在同一台机器上可先起 NapCat 官方 Docker 镜像（支持 amd64 / arm64）：
docker run -d --name napcat --restart=always \
-e NAPCAT_GID=$(id -g) -e NAPCAT_UID=$(id -u) \
-p 3000:3000 -p 3001:3001 -p 6099:6099 \
mlikiowa/napcat-docker:latest
WebUI 为 http://<主机IP>:6099/webui，用手机 QQ 扫码登录；在「网络配置」中确认 OneBot 11 的 HTTP 3000、正向 WS 3001。若配置了 access_token，需填入插件配置。
2. 安装插件¶
--profile 按实际环境替换（桌面版常用 --profile desktop，dsh web 常用 --profile web）：
# 方式一：直接从 GitHub 仓库装（默认跟 main 分支）
dsh plugin --profile web add github:arrow1031/dsh-qq-bot
# 想锁版本就用 tag（推荐生产环境）
dsh plugin --profile web add github:arrow1031/dsh-qq-bot#v0.6.1
# 方式二：用 Release 里打好的 tarball（固定版本）
dsh plugin --profile web add \
https://github.com/arrow1031/dsh-qq-bot/releases/download/v0.6.1/dsh-qq-bot-0.6.1.tgz
# 方式三：本地 tarball（自己改了代码之后）
npm pack
dsh plugin --profile web add ./dsh-qq-bot-0.6.1.tgz
装完后 重启 DSH（桌面重启应用，CLI 重启 dsh web）。若修改了 lib/client.js，还需 刷新浏览器 才能加载新客户端 bundle。自行改代码再安装时，须 bump 版本号再打 tarball，否则 pnpm 可能因哈希缓存跳过更新。
3. 配置连接¶
推荐在 设置 → QQ 机器人 中保存；连接相关项保存后会自动重启适配器。
NapCat 与 DSH 同机时用默认 forward 即可。若 NapCat 在其它主机或只能 outward 连接，改为 reverse，在 NapCat 中填写 ws://<DSH主机IP>:6199/，并按 README 配置 token（Bearer 头或 URL access_token）。
也可在 $DSH_HOME/profiles/web/cordis.patch.yml 中按 id dsh-qq-bot 覆盖 config（不要改包内 cordis.patch.yml，升级会被覆盖）。README 提供了完整 YAML 示例字段：mode、onebot.wsUrl / listen / httpUrl、group / private、reply、auth、admin 等。
典型用法¶
- 完成 NapCat 登录与 OneBot 端口、插件安装与重启。
- 私聊机器人 QQ 号，默认应直接收到 Agent 回复。
- 群聊中 @机器人 提问（默认
group.requireAt: true）。 - 在 Web UI 打开对应
qqbot-*会话，可像普通 DSH 会话一样续聊；换人格可在配置中设置agentPreset为专属 preset id。 - 排查连接时在对话中让 Agent 执行
qqbot工具 的status；需要逐帧协议日志时可开logAdapterFrames。
反向 WS 场景：插件 mode: reverse、onebot.listen: '0.0.0.0:6199'，NapCat 侧填 DSH 可达的 WS 地址与 token。
适用场景与注意¶
适合：已在用 DSH Agent、preset 与工具链，希望 QQ 作为又一个聊天入口；已有或愿意部署 NapCat 等 OneBot 11 实现，且接受「每个 QQ 会话一个 Agent 会话」的模型。
不适合或需知：
- 作者声明 已封版：不修 bug、不适配上游变更、不接受功能请求；生产环境请评估自行维护成本，架构说明见仓库 ARCHITECTURE.md。
- 插件在 当前 DSH 进程权限 下运行，Agent 工作目录、工具能力由配置与 preset 决定；安装前应阅读源码与 MIT 许可，并理解 auth / admin 配置，避免访客误开
guestDshTools。 - DSH 社区目录（SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；本介绍事实以 GitHub README 为准。
结尾¶
dsh-qq-bot 把 OneBot 11 与 DSH Agent 会话对齐：NapCat 管 QQ 侧，插件管协议翻译与会话路由，设置页与 cordis.patch.yml 管策略。若你要在 QQ 里复用同一套 DSH 能力，可按 README 起 NapCat、用上述 dsh plugin add 命令装入 profile 并重启验证。
- 目录页：https://www.skillhub.cn/plugins/arrow1031/dsh-qq-bot
- 源码：https://github.com/arrow1031/dsh-qq-bot
