前言¶

在 DeepSeek Harness（DSH）裏跑多 Bot 團隊時，每個角色通常有獨立的長會話：歷史、記憶文件、工具權限和工作區都綁在這條 session 上。若要從 QQ 私聊觸達它們，常見做法是再寫一個 QQ 機器人，用同樣的 system prompt 調模型——這樣會丟掉真實會話裏的上下文，Web 端和 QQ 端也變成兩套互不相干的對話。

下面介紹社區插件 dsh-qqbot-bridge（維護者 WuChangqing1），它把 QQ 官方 Bot 的私聊消息投遞到 DSH 裏該 Bot 已在運行的 session，並把回覆回傳到 QQ；不另開第二套 QQ 網關，也不復制 system prompt。

這是什麼¶

dsh-qqbot-bridge 是 DSH 工作流類插件，當前版本 0.1.0（MIT 許可證，Node >=22.19.0）。定位一句話：Bridge QQ official-bot private chats into DeepSeek Harness agent sessions — same session, same memory, same permissions.

與「典型 QQ ⇄ LLM 橋接」的差異在於：通過 sessionController.resolveAgent(sessionId) 與 agent.followup(createUserMessage({ source })) 複用真實 session；Web UI 與 QQ 共用同一 session id；複用官方 @tencent-connect/dsh-qqbot 已建立的 websocket，本插件只消費 Cordis 服務、不自己連 socket；白名單 allowOpenIds: [] 表示拒絕所有人（fail-closed），被拒用戶的 OpenID 僅被記錄、不會自動放行；羣聊默認關閉，羣消息交回官方插件原鏈路處理。

工作原理概覽¶

消息路徑可概括爲：

QQ 私聊 → @tencent-connect/dsh-qqbot（含本地 fork patch）→ dsh-qqbot-bridge
  → 白名單 / 命令路由 / 隊列與去重 → 只讀 state.json 取當前 session id
  → resolveAgent → followup → 同一 DSH session（msg.source.kind = 'qqbot-bridge'）
  → session/event 收集回覆 → 分片回 QQ

官方 QQ 插件原先未暴露 Cordis 服務，外部插件無法共用連接或插入中間件；同一 AppID 再起網關會搶事件流。因此項目要求對 stock 包做最小本地 fork（patch 0001：在 middleware 鏈前插入可選 preHandlers，並 ctx.provide('qqbot', …)）。未使用該擴展點的宿主行爲與原版一致。

核心功能¶

1. 會話級橋接：QQ 私聊進入對應 Bot 的真實 DSH session，保留歷史、記憶、工具與工作區；會話滾動到新 part 時，每次發送前重讀 state.json。
2. 多 Bot 路由：通過 QQ 內命令切換當前對話對象（見下文「典型用法」），路由持久化到 routing.json，按 OpenID 區分。
3. 安全默認：空白名單拒絕所有私聊；僅 v1 私聊，allowGroups: false。
4. 可觀測：控制台日誌與 bridge-status.json；插件註冊 qqbotBridge Cordis 服務供運維查詢；官方 /bot-ping、/bot-status 等命令仍可走原鏈路。
5. 配套腳本：自檢、生成 fork、寫入 Web profile、展示被拒 OpenID 等（見安裝步驟）。

安裝與啓用¶

前置條件：已安裝 DSH Web profile、官方 QQ 插件且已綁定 AppID，以及已在 DSH 中創建的團隊 Bot。安裝流程以倉庫 README 爲準，不是 dsh plugin add github:… 一行命令；需在克隆或下載項目目錄後執行腳本（資料中禁止在此文重複 git clone，請從 GitHub 倉庫 獲取源碼）。

先在項目根目錄做自檢（無額外運行時依賴）：

node scripts/run-tests.mjs
node scripts/audit-constraints.mjs
node scripts/verify-host-resolution.mjs

生成本地 fork 的 QQ 插件包（自動定位已安裝的 stock 包，也可用 --from <dir>）：

node scripts/make-bridged-qqbot.mjs --out ../dsh-bridged-qqbot
(cd ../dsh-bridged-qqbot && pnpm install --prefer-offline)

將 Web profile 指向 fork 並掛載本橋接插件（建議先看 dry-run diff）：

node scripts/install-profile.mjs --fork ../dsh-bridged-qqbot --project . --dry-run
node scripts/install-profile.mjs --fork ../dsh-bridged-qqbot --project .

停止 DSH 後，在 profile 內安裝依賴並重啓：

cd ~/.dsh/profiles/web && pnpm install

啓動後日志中應出現類似：

[qqbot-bridge] apply() entered (plugin v0.1.0)
[qqbot-bridge] allowOpenIds: 0 configured -- FAIL CLOSED, every QQ peer is refused
[qqbot-bridge] provided the "qqbotBridge" service
[qqbot-bridge] STARTED: transport=dsh-qqbot-bridge/qq | snapshot=...

白名單配置：先在 QQ 給 Bot 發一條私聊（會被拒絕），再查 OpenID 並寫入 profile patch：

node scripts/show-openids.mjs

在 ~/.dsh/profiles/web/cordis.patch.yml 中爲插件 qqbot-bridge 設置 allowOpenIds: ["YOUR_OPENID"]。DSH 支持配置熱重載，一般無需重啓。

配置項均在你的 profile patch 中，不在插件倉庫內。資料中明確出現的字段示例：

- id: qqbot-bridge
  config:
    allowOpenIds: []        # 空數組表示拒絕所有人，僅添加可信 OpenID
    defaultBot: 管家         # 尚未切換過 Bot 的私聊用戶默認對話對象
    allowGroups: false      # v1 僅私聊
    replyTimeoutMs: 600000  # 等待回覆超時（毫秒）

典型用法（QQ 端）¶

在 QQ 發起的問題，可在 DSH Web UI 同一 session 中繼續；反之亦然。

適用場景與注意¶

適合：已在 DSH 內維護多 Agent / 多 session 團隊，希望用手機 QQ 私聊觸達同一套記憶與權限，且願意按文檔對官方 QQ 插件做最小 fork 並改 Web profile 的開發者。

務必注意：

• 插件與 DSH 進程同權限運行；安裝前請閱讀源碼與 MIT 許可證，確認 fork 與 profile 變更可接受。
• 默認 fail-closed，未配置 OpenID 時所有私聊會被拒，這是預期行爲。
• peer 依賴包括 @deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-session 等（版本範圍見倉庫 package.json）。
• 社區目錄 SkillHub 插件頁 與 GitHub 爲獨立信息源，與 DeepSeek / 幻方無官方從屬關係；星標與版本以倉庫爲準。

結尾¶

dsh-qqbot-bridge 解決的是「QQ 觸達」與「DSH 真實 session」之間的斷層：不復制 prompt、不雙開網關，把私聊納入已有 Agent 工作流。詳情與測試說明見 GitHub：WuChangqing1/dsh-qqbot-bridge，目錄頁：SkillHub - dsh-qqbot-bridge。