前言¶
在 DSH 裏跑 agent，常見做法是隻在 Web 界面或 CLI 裏對話。若希望同一個會話在 QQ 羣裏也能被 @、被暱稱喚起，且仍沿用該會話已有的上下文，而不是爲 QQ 單獨開新會話、重新 priming，就需要在 OneBot/NapCat 與 DSH 之間做橋接，並控制「誰可以驅動模型、哪些消息只記錄不調用」。
下面介紹社區插件 dsh-qq-bridge（維護者 sj244）：它把一個已存在的固定 DSH 會話接到 QQ（OneBot / NapCat 個人號），白名單 fail-closed，@ / 暱稱 / 戳一戳必喚醒，其餘消息可按概率抽樣或只寫入緩衝，喚醒時再摘要注入。插件分類爲「聯網工具」，當前版本 v0.1.3（MIT），倉庫 sj244/dsh-qq-bridge。
這是什麼¶
dsh-qq-bridge 是 DeepSeek Harness（DSH）的 Web 側插件：通過配置 targetSessionId，QQ 入站消息注入指定會話；插件用 agents.get(id) 顯式加載目標，取不到時用 agents.resume({ resumeSessionId })，不回退到其他會話。出站受「來源閘門」約束，默認只有被 QQ 喚醒那一輪裏、[QQ]…[/QQ] 標記塊內的文字纔會發到羣裏，避免 DSH 界面裏的技術說明和思考過程漏進 QQ。
項目自述爲 vibecoding 產物；README 寫明 M1–M8 已在真實 NapCat + 真實 QQ 上端到端跑通（Windows 真機）。它不接管審批、不在加載時自動下載或執行任何內容、也不做 QQ 官方機器人。
核心功能¶
固定會話與上下文¶
targetSessionId指向哪個會話，QQ 消息就進哪個會話，原有上下文繼續可用。- 未喚醒期間的消息最多保留 200 條緩衝；真正喚醒時，取最近
recentChatLimit條（默認 8）拼成[QQ 未喚醒期間聊天記錄] … [記錄結束]附在當前消息前，投遞成功後緩衝清空。
喚醒策略（省 token）¶
白名單爲空數組時，任何來源都不能喚醒（fail-closed）。流程概覽：
QQ 消息 ─┬─ 不在白名單 ─────────────────→ 丟棄（fail-closed）
├─ 在會話跟隨窗口內 ───────────→ 喚醒（reason: listening）
├─ 羣裏 + atOnlyInGroup + 沒 @ ─→ 丟棄
├─ 被 @ / 命中暱稱 / 被戳我 ───→ 喚醒
├─ random() < wakeProbability ──→ 喚醒（默認 5%）
└─ 其餘 ──────────────────────→ 只記錄（零模型調用）
- 私聊白名單：
whitelist；羣白名單：groupWhitelist。 - 羣內若
atOnlyInGroup: true，未被 @ 的羣消息完全不處理（跟隨窗口檢查排在該規則之前）。 - 模型可通過工具
qq_bridge_listen({ minutes: 5 })在同一羣/同一私聊開跟隨窗口（默認 5 分鐘，上限 60）；窗口內普通消息也會喚醒，會產生實際調用費用。
出站與來源閘門¶
replyMode 控制出站方式：
| 值 | 行爲 |
|---|---|
marker（默認） |
僅 [QQ]…[/QQ] 塊內內容發出 |
tool |
用 qq_bridge_send 工具發送 |
always |
整輪迴復都發出（舊行爲） |
只有「被 QQ 喚醒的那一輪」生效；在 DSH 裏與同一會話聊天時，標記塊不會發到 QQ。超長（超過 replyMaxChars）則一條都不發。
圖片、表情包與 NapCat¶
- 圖片先緩存；喚醒時可用多模態模型轉成文字填回原位置；登記爲表情包後可按情緒或哈希複用，減少重複視覺調用。
- 非文本段（表情、語音、文件等）轉爲佔位符，避免整條消息丟失；戳自己合成
[戳一戳]（戳的是我）並必喚醒。 - 插件可作爲 WebSocket 客戶端連接 NapCat 正向 WebSocket；
onebotUrl留空則完全不啓用傳輸（默認，偏安全）。 - 會話內可調用
qq_bridge_napcat：查狀態、下載並 sha256 校驗發行包、寫onebot11.json、啓動 NapCat；不會在無人操作時自動下載或執行。
設置界面¶
暱稱、白名單、概率、目標會話、出站方式、OneBot 地址、視覺模型等可在 設置 → 插件 → 插件配置 修改，保存即生效。accessTokenEnv 填環境變量名，token 由 DSH 憑據服務解析，不寫入 cordis.patch.yml。
安裝與啓用¶
正式安裝（資料原文命令）：
dsh plugin --profile web add github:sj244/dsh-qq-bridge
裝完以及每次改插件代碼後，需重啓 dsh web 纔會加載。
接入 OneBot 時，可在 profile 的 cordis.patch.yml 按 id 覆蓋，或在設置界面修改，例如：
- id: qq-bridge
config:
onebotUrl: 'ws://127.0.0.1:3001'
accessTokenEnv: 'NAPCAT_ACCESS_TOKEN'
NapCat 側需開 WebSocket 服務器（非 HTTP）。token 解析優先級：進程環境變量 → ~/.dsh/.credentials.yaml 的 refs: → 工作目錄 .env；建連時重新解析，輪換 token 不必重啓。
典型用法¶
- 安裝插件並重啓
dsh web，在插件配置裏填寫targetSessionId、白名單、暱稱與wakeProbability（默認0.05）。 - 配置
onebotUrl與accessTokenEnv，確保 NapCat 正向 WS 可達；selfId可留空，連上後插件會get_login_info取得本號 QQ，過濾自消息防死循環。 - 若尚未部署 NapCat，在目標會話中按 README 順序調用
qq_bridge_napcat：status→download（需代理時可設downloadProxy）→ 手動運行一次安裝器 →configure→launch（首次仍須掃碼登錄 QQ）。 - 在羣裏 @ 機器人或命中暱稱測試喚醒；默認出站用
[QQ]回覆內容[/QQ]包裹要發到羣裏的句子。 - 需要連續聊幾句時，由模型在合適時機調用
qq_bridge_listen，並注意窗口內每條消息都會喚醒。
開發期可用本地路徑 dsh plugin --profile web add "<REPO>" 做 link 安裝；README 說明了 Windows 下 @deepseek-ai 依賴 junction 的注意事項。
適用場景與注意¶
適合：已有固定 DSH 會話（例如長期「大肥魚」人格或項目 agent），希望在小範圍 QQ 羣或私聊裏以羣友方式互動，且要嚴格限制誰可驅動、控制隨機插話比例的場景。
不建議：公共大羣長期無人值守；README 明確 NapCat 爲第三方客戶端，存在賬號風控風險，是否啓用由用戶自行決定。
安全與權限：插件以當前 dsh 進程權限運行；安裝前應閱讀 源碼與 LICENSE，理解白名單、出站閘門與「不提供審批橋接」等邊界。卸載插件或退出 DSH 時，由 subprocess 託管的 NapCat 會一併結束。
DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-qq-bridge 解決的是「一個會話、兩處入口」：QQ 側可控喚醒與只記錄，DSH 側保留完整上下文與默認不出羣的出站策略。進一步的設計與變更見倉庫內 DESIGN.md、HANDOVER.md、CHANGELOG.md。
- 目錄頁：https://www.skillhub.cn/plugins/sj244/dsh-qq-bridge
- GitHub：https://github.com/sj244/dsh-qq-bridge
