前言¶

DeepSeek Harness（DSH）把智能體能力放在可擴展的插件體系裏；要在 QQ 裏和用戶對話，通常還要單獨搭 OneBot 協議端、自己寫消息轉發和會話隔離。社區維護者 Jiangsubei 的 dsh-napcat-bridge（npm 包名 dsh-napcat-bridge）把 DSH 與 NapCat 接在一起：基於 OneBot 11 反向 WebSocket，在羣聊和私聊裏開箱即用，並帶 QQ 專屬預設、記憶、權限與 WebUI 配置。下面介紹它是什麼、能做什麼，以及如何安裝與對接 NapCat。

這是什麼¶

dsh-napcat-bridge 是 DeepSeek Harness × NapCat QQ 接入插件，分類屬於 DSH 生態裏的客戶端方向插件。倉庫：https://github.com/Jiangsubei/dsh-napcat-bridge；社區目錄頁：https://www.skillhub.cn/plugins/Jiangsubei/dsh-napcat-bridge。許可證爲 MIT；當前資料中的 npm 版本爲 0.2.8，要求 DSH >= 0.2.0、Node.js >= 22.12.0（受 better-sqlite3 約束）。

SkillHub 等社區目錄與 DeepSeek / 幻方無官方從屬關係；安裝前建議自行查看源碼與許可證。插件在當前 DSH 進程權限下運行，羣聊默認只讀等工作區權限策略需結合自己的部署環境理解。

核心功能¶

接入與會話隔離¶

• QQ 羣聊 / 私聊經 NapCat 反向 WebSocket 接入 DSH。
• 專屬預設 qq-session：構建期與運行時 SSOT 同步，QQ 工具集只注入 QQ 會話，避免向 Web UI 常規會話泄露；並補齊工作區、跨平臺 Shell（Windows pwsh / Linux bash）、Web 搜索、交互提問與技能等能力。
• 用戶側靜默出站：純文本不再直接推流；文本統一由 send_qq_message 驅動，模型根據入站標頭 [消息ID: <id>] 決定是否 reply_to 或 at_user。
• 出站工具與回合解耦：調用出站工具不強行結束回合，同一輪可繼續用記憶、表情等工具。

記憶、表情與黑話¶

• 兩層記憶：羣聊會話記憶 + 用戶跨羣畫像，Markdown 存儲；工具 read_memory、create_memory、edit_memory；寫入側有用戶畫像、Session 規則、羣聊畫像總預算三套字符上限，超限硬拒絕落盤。
• 表情包（受 face_enabled 門控）：list_faces、send_face、collect_face、manage_faces，以及羣聊 react_message；庫容與 LRU 等策略可配。
• 黑話學習（SQLite + 工具 query_slang、record_slang、manage_slang）：動態注入 L1 索引，支持 LRU 淘汰；默認 slang_enabled 爲 true。

消息、權限與羣聊策略¶

• 單對端串行出站隊列；支持私聊文件入站落盤、羣文件索引 list_group_files、fetch_chat_resource、expand_forward_message 等。
• 羣成員與定時任務：get_group_member_info；schedule_task、manage_scheduled_tasks。
• 卡片消息通用提取（小程序、分享、音樂等標題與鏈接）。
• 羣聊主動回覆：窗口期聚合、潛水超時破冰、Agent 繁忙丟棄、夜間免打擾（默認 23:00–08:00）；new_message_behavior 可選 steer（插話）或 queue（入隊）。
• 斜槓命令（兩字中文）：/新建、/會話、/用量、/停止、/模型、/權限、/思考、/狀態、/幫助；管理員白名單 admins。
• 黑名單與權限：私聊/羣聊發言黑名單（命中不喚醒、不回覆，管理員不豁免）；新建會話默認權限（私聊默認 workspace-write、羣聊默認 read-only）及 QQ 號/羣號例外；Coding 工具組可按場景裁剪，只讀工具 read_image 與 working_directory 始終保留。

WebUI 配置¶

DSH Web UI 中提供 dsh-napcat-bridge 設置卡片，7 個 Tab、共 40 項參數，支持 volatile 熱更新（連接、人格與準則、回覆、權限與安全、記憶、表情包、黑話學習）。

安裝與啓用¶

前置條件¶

• 已安裝 DeepSeek Harness（例如 npm install -g @deepseek-ai/dsh），版本 >= 0.2.0。
• 已部署 NapCat 作爲 QQ 協議端。
• Node.js >= 22.12.0；從源碼開發時需 pnpm >= 9.0.0。

安裝插件（推薦 npm）¶

CLI 環境：

# 安裝到 DSH 的 web profile
dsh plugin --profile web add dsh-napcat-bridge

# 或安裝到全局默認環境
dsh plugin add dsh-napcat-bridge

DSH Desktop 無 dsh CLI 時，在「插件 → 添加插件」中輸入包名 dsh-napcat-bridge 安裝。npm 包內置編譯產物與 cordis.patch.yml，安裝後重啓 DSH 生效，常規安裝不觸發 better-sqlite3 本地編譯。

對接 NapCat 並啓動¶

1. 在 NapCat WebUI（默認 http://127.0.0.1:6099/webui）新增反向 WebSocket 客戶端：
   - URL：ws://127.0.0.1:8080/（插件綁定環回 127.0.0.1，端口與 ws_port 一致，默認 8080）
   - Token：必填，與插件 ws_token 完全一致（不一致或未配置時握手拒絕，401）
   - 心跳週期 30000 ms，重連間隔 3000 ms
2. 啓動 DSH：

dsh --profile web

3. 打開 DSH Web UI（默認 http://127.0.0.1:3080/），進入 dsh-napcat-bridge 設置，至少填寫：
   - ws_token：與 NapCat 一致（空值會被拒絕連接，WebUI 保存亦會校驗）
   - bot_qq：機器人 QQ 號（過濾自身消息、識別 @）
   - admins：可執行斜槓命令的管理員 QQ 號

其餘如 aliases 點名、proactive_* 主動回覆、記憶預算、face_enabled、slang_* 等按需保存，即時熱更新。

典型用法¶

在 QQ 裏對話¶

NapCat 與 DSH 連通且必填項保存後，用戶在羣聊 @ 機器人或使用配置的 aliases 點名，或在私聊發消息，即可觸發 QQ 專屬會話。模型通過 send_qq_message 回覆；是否引用、是否 @ 由工具參數決定，不再使用已下線的固定「羣聊強制引用/艾特」配置項。

管理員斜槓命令¶

管理員 QQ 號寫入 admins 後，可在 QQ 內使用 /幫助 等命令管理會話、用量、模型、權限、思考模式與狀態；具體行爲以實現爲準，權限嚴格依賴白名單。

記憶與羣文化維護¶

Agent 可在對話中調用記憶工具維護用戶畫像與羣 Session 規則；開啓 slang_enabled 後可通過黑話工具沉澱羣詞條；開啓 face_enabled 後可在新會話中裝載表情工具鏈（對已存在會話需按 README 說明理解「對新會話生效」的門控語義）。

適用場景與注意¶

適合：已有 NapCat + DSH 部署、希望在 QQ 羣/私聊統一跑 Agent，並需要會話與工具隔離、權限分級、可選主動回覆與羣文化（記憶/表情/黑話）能力的團隊或個人。

注意：

• 插件依賴本地 WebSocket 網關與 Token 鑑權，生產環境應使用強 ws_token，並理解默認只監聽 127.0.0.1。
• 羣聊默認 read-only 與羣聊默認關閉 Coding 工具組是安全向默認值；需要寫工作區或 bash 時應顯式調整默認或例外表，並評估 DSH 進程權限。
• 發言黑名單命中後永不回覆，包括管理員；誤配前請確認列表。
• 社區目錄頁星標等數據會變動；以 GitHub 與 npm 頁面爲準。

結尾¶

dsh-napcat-bridge 把 DSH Agent 接到 NapCat/OneBot 11 上，用 qq-session 預設和靜默出站模型把 QQ 場景與 Web 會話隔開，再用 WebUI 四十項參數覆蓋連接、人格、主動回覆、權限、記憶、表情與黑話。若要進一步瞭解參數表與開發構建，見倉庫 README：https://github.com/Jiangsubei/dsh-napcat-bridge；插件索引：https://www.skillhub.cn/plugins/Jiangsubei/dsh-napcat-bridge。