前言¶

在 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 列出多組本地迴歸測試（適配器、插件端到端、客戶端設置頁、權限與羣管理等）已通過。

1. OneBot 11 雙模式：默認 正向 WebSocket（插件連 ws://127.0.0.1:3001）；可選 反向 WS（插件在 0.0.0.0:6199 監聽，由 NapCat 連入）。HTTP 默認 3000 用於發消息，與 NapCat 默認端口一致。
2. 一會話一 Agent：perChatSession: true 時，每個羣/每個私聊獨立 DSH 會話（id 形如 qqbot-group-33333），可落盤並在 Web UI 會話列表中繼續聊。
3. 羣聊與私聊策略：羣聊默認需 @機器人 才觸發（@ 會從正文去掉再交給 Agent）；私聊默認直接回復。長回覆按換行切分，默認單條不超過 1200 字。
4. Web 設置頁：DSH ≥ 0.1.7 下，配置寫入 profile 的 cordis.patch.yml；連接模式、地址、token、白名單、preset、權限與羣管理項等集中在一個選項卡。access_token 爲只寫字段，已設置時留空保存不會清空。
5. 權限與羣管理：靜態擁有者/超級管理員、本羣管理員身份、動態授權等多路並行；訪客默認不開放 DSH 內部工具，可通過白名單保留 qqbot、qqgroup 等。管理指令前綴、dry-run 等見 README「權限與羣管理」一節（正文資料截斷處仍可在倉庫完整閱讀）。
6. 工具與狀態：可在對話中讓 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 等。

典型用法¶

1. 完成 NapCat 登錄與 OneBot 端口、插件安裝與重啓。
2. 私聊機器人 QQ 號，默認應直接收到 Agent 回覆。
3. 羣聊中 @機器人 提問（默認 group.requireAt: true）。
4. 在 Web UI 打開對應 qqbot-* 會話，可像普通 DSH 會話一樣續聊；換人格可在配置中設置 agentPreset 爲專屬 preset id。
5. 排查連接時在對話中讓 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