前言¶
在 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
