前言¶
在 DSH 里跑 agent，常见入口是 Web 或桌面端会话。若要在 QQ 群或私聊里收消息、让 agent 生成回复并自动发回 QQ，需要自己接协议层、维护会话映射，再把入站事件转成 ctx.agents.create / followup。社区插件 qq-integration（npm 包名 dsh-qq-onebot-bridge，GitHub：mkiea/qq-integration）做的是集成：复用 OneBot v11 与现有 DSH agent API，加上独立控制台与可观测旁路，把「QQ ↔ Harness」收成一条可维护的链路。
这是什么¶
qq-integration 由维护者 mkiea 自研维护，定位为 QQ ↔ DeepSeek Harness 双向桥（独立 bundle）。它不实现 QQ 协议本身，而是把三端接起来：
| 角色 | 本插件提供 | 本插件不包含 |
|---|---|---|
| OneBot v11（协议层） | 反向 WebSocket 服务端、事件分发、action 调用、@ 解析、合并转发等（延续上游 dsh-qq-onebot-bridge 代码并维护） |
QQ 登录与底层编解码（在 OneBot 实现里） |
| OneBot 实现 | 凡声明 v11 即可：Waylay / NapCat / LLOneBot / OpenShamrock / Lagrange / go-cqhttp 等 | 任何实现的二进制 |
| Waylay（当前默认接入端） | 内置拉起/停止/状态（lib/waylay-launch.js、控制台与 /api/waylay*） |
Waylay 运行时与注入 DLL（另发 Apache-2.0 发行件，见仓库 NOTICE.md） |
数据主路径：QQ 客户端 ↔ OneBot 实现 ↔（反向 WS，默认端口 6700）↔ 本插件 ↔ DSH agent 会话（按群/私聊用户拆分）。控制台 control/ 为独立进程，默认 http://127.0.0.1:8880/，不依赖 DSH 桌面端；前台可用 node control/bin/qq-control.mjs 启动。
旁路录制与调试（不参与回复决策，故障也不挡发消息）：qq-inbox.jsonl（入站录制）、qq-trace.jsonl（决策链）、qq-runtime.json（约 2s 快照）、qq-inject.jsonl（控制台写、桥轮询读，默认 dry-run 拦截出站）。
核心功能¶
下面按已公开 README 与 package.json 可核对的能力归纳。
与 DSH 的会话桥接¶
入站 QQ 事件驱动 DSH agent；agent 产出经桥发回 QQ。插件通过 Cordis bundle 挂载，声明支持 DSH 运行时 0.1 与 0.2 线（peerDependencies 覆盖 CLI 与官方桌面端常用版本区间）。
OneBot v11 与多实现兼容¶
对 OneBot 实现无厂商绑定：只要对接 v11，可选用 Waylay、NapCat 等。当前默认路径内置 Waylay 生命周期管理；Waylay 本体需自行准备 rin-inject\ 等运行时（Windows + 官方 NTQQ 场景在文档中有完整从零说明）。
独立控制台与可观测性¶
控制台可读端口/进程、事件流、决策链、体检、录制列表、运行快照；可写启停宿主/Waylay/TTS、释放端口、离线回放（沙箱 + dry-run）、事件注入。鉴权限定 127.0.0.1 + token + 同源 Origin。
客户端扩展¶
package.json 中 dsh.client 向 Web 设置 UI 注入 @deepseek-ai/dsh-client-ui-settings（如「设置 → QQ 助手」类入口），与 profile 内 cordis.patch.yml 配置联动。
安全默认¶
allowUsers / allowGroups 白名单为空即全部拒绝（刻意设计）：未列入的会话不会创建，trace 记录为白名单拒绝，而不是在 QQ 里回一句「拒绝」。
安装与启用¶
本地目录安装走 pnpm link:（与 dsh-forge 同类）：profile 里 node_modules/dsh-qq-onebot-bridge 指向插件目录，改仓库即改运行时（重启宿主后生效）。README 强调三步缺一启动表现不同，且不要用 git+https://… 装插件以免 pnpm install 把运行时钉回远端 commit。
1. 插件目录依赖¶
在插件绝对路径下只装运行时依赖（主要为 ws）：
cd <插件的绝对路径>
npm install --omit=dev --legacy-peer-deps
--legacy-peer-deps 用于避开多个 @deepseek-ai/dsh-* peer 区间在 npm 下的 ERESOLVE（README 有说明；--omit=peer 不足以解决）。
2. 让插件目录能看见官方 peer¶
link: 安装后 Node 按真实路径解析 import，插件目录内须能解析 @deepseek-ai/*（Windows 目录联接示例）：
cmd /c mklink /J "<插件目录>\node_modules\@deepseek-ai" "%USERPROFILE%\.dsh\profiles\<profile>\node_modules\@deepseek-ai"
漏此步常见症状：宿主启动报 Cannot find package '@deepseek-ai/schemastery'。
3. 注册到 profile¶
dsh plugin --profile web add <本目录>
CLI / Web 版 profile 填 web；官方 DSH Desktop 用 desktop（联接必须指向对应 profile 的 node_modules\@deepseek-ai，指错 profile 可能 mklink 成功却挂错 peer）。装/卸后重启 dsh web 或桌面端生效。
卸载：
dsh plugin --profile web remove dsh-qq-onebot-bridge
手动本地安装时，除依赖外还须确认 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles 含 dsh-qq-onebot-bridge，否则依赖在列表里但 bundle 不加载（市场安装会自动处理）。
官方桌面端¶
桌面端独占 ~/.dsh/profiles/desktop；安装步骤与 web 相同，仅 <profile> 换为 desktop，配置写在 ~/.dsh/profiles/desktop/cordis.patch.yml，通过设置 → 插件 → 本地目录或仓库地址安装。
环境与单机约束（摘自文档）¶
从零文档面向 Windows 10/11 x64、Node.js ≥ 24.9.0（与 DSH 0.2.2-rc.1 的 engines.node 一致）、pnpm、NTQQ、Waylay 运行时、VC++ 运行库等。自查可用：
node launcher/preflight.mjs
一台机器只应一个 profile 实例托管 QQ 桥：web 与 desktop 可同时装插件，但默认共用 OneBot 端口（6700）与同一份 cwd 下会话/记忆文件；双实例并发写会互相覆盖，injectDryRun:false 时注入动作可能重复发送。正确做法是只在一个 profile 启用 bundle，或拆分 cwd 到不同目录（不推荐仅改端口让两边同时跑）。
典型用法¶
最小配置¶
配置写在 profile 的 cordis.patch.yml，不要写进仓库根目录示例：
- id: dsh-qq-onebot-bridge
config:
cwd: 'C:\Users\你\qq_chat'
dataDir: 'C:\Users\你\qq_chat'
botQq: 1000000000
allowUsers: [2000000001]
allowGroups: [3000000001]
cwd 为 agent 工作区；dataDir 为记忆、聊天记录、金丝雀等根目录。白名单外的 QQ 号/群不会建会话。
首次启动与数据目录¶
插件 deliberately 不设默认 dataDir。首次启动后控制台可向导选择目录并写回 cordis.patch.yml，也可在设置 → QQ 助手 → 数据与备份 填写（同一配置源）。未配置前可用 cwd 兜底，运行快照与 trace 会提示当前临时目录。换目录不会自动迁移数据；迁移需拷贝全部 qq-* 及 qq-canary.json。
控制台与可选配置¶
默认无需 qq-control.json；探测不对时可复制 qq-control.example.json 为 qq-control.json 并改本机路径。启动顺序、Waylay 与 DSH 宿主先后等细节见仓库 README 与 docs/CLEAN-INSTALL.md（含 2026-11-06 Win11 虚拟机打通记录）。
包版本当前为 0.1.0；提供 qq-control 二进制入口与 npm run control 脚本。
适用场景与注意¶
适合谁：已在 DSH 上跑 agent，希望用 QQ 作为触达渠道，并愿意在 Windows 上维护 OneBot 实现（尤其 Waylay + NTQQ）的开发者或小团队。
权限与信任：插件以当前 DSH 进程权限执行 agent 与工具调用；cwd / dataDir 即模型可访问的工作区。安装前应阅读源码、LICENSE / NOTICE.md（含上游 MIT 保留与复用边界），勿用主 QQ 号做机器人账号。
平台：文档明确当前路径围绕 Windows + 官方 NTQQ；其它平台需自备 OneBot 实现并自行验证。
生态说明：DSH 主张「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
qq-integration 把 OneBot v11、可选 Waylay 与 DSH agent 会话收成一条可调试的双向桥，并用独立控制台与 jsonl 旁路降低排障成本。进一步了解与 issue：
- 目录页：https://www.skillhub.cn/plugins/mkiea/qq-integration
- 仓库：https://github.com/mkiea/qq-integration
