dsh-napcat：給 DeepSeek Harness 加一個 QQ 通道

前言¶

DeepSeek Harness 的理念是「一切皆插件」。如果你正在用 NapCat 或 OneBot 11 協議跑 QQ 機器人，想直接把消息接入 DSH 的 agent，而不是自己寫轉發邏輯，dsh-napcat 是一個現成的實現。

這個插件通過 NapCat（OneBot 11 協議）把羣聊/私聊消息送進 DSH 的 agent，再把回覆發回 QQ。每個羣或私聊對應一個獨立的 dsh 會話，同時提供了會話記憶、主動發言、性格設定、文件/圖片收發等實用能力。

是什麼¶

插件名：dsh-napcat
維護者：wzwei1990
分類：客戶端
解決的問題：把 NapCat / OneBot 11 事件轉換成 DSH 的會話，讓同一個 agent 同時服務多個 QQ 聊天
當前版本：v0.3.20（參考 dsh-onebot / dsh-im / dsh-qqbot 的形態）

核心功能¶

連接與觸發¶

連接方式：支持 forward（插件主動連 NapCat 的 WebSocket）和 reverse（NapCat 撥進插件）
token 校驗：兩邊需配置相同的 accessToken
斷線重連：指數退避
觸發方式：@機器人 / 回覆機器人 / 關鍵字（triggerKeywords，如「小燈」）；羣聊可要求必須 @

會話與分組¶

一個羣 / 一個私聊 = 一個 dsh 會話，id 格式爲 napcat-group-<羣號> 或 napcat-private-<QQ>
會話 id 裏編入 cwd 哈希，重啓後不換會話
每個聊天自動建一個工作區（側邊欄顯示「羣 1103089802」/「私聊 1000001」）並掛載會話
首條消息時把會話標題寫成 MM-DD HH:mm

准入策略¶

私聊 / 羣聊各自有策略：open（開放）、allowlist（白名單）、disabled（禁用）
可配置白名單，只允許特定用戶進入

羣記憶¶

每羣（或私聊）一份長期記憶，與其它羣互不干擾，包含兩層結構：

層	內容	用途
熱上下文	最近 N 條消息（默認 200 條）	每次觸發自動注入最近 20 條
長期記憶	羣設定 / 黑話 / 人物關係 / 事實結論（mnemon 記憶空間）	顯式召回（固定層 + 按需層兩次）

模型自動維護分層標籤：

【設定】→ tags 加 setting
【黑話】→ tags 加 glossary
【人物】→ tags 加 person
【事實】→ 無額外標籤

自動捕獲：只要對話中出現上述新信息，模型自己寫入（memoryAutoCapture，默認開啓）。信息變化時先 mnemon_forget 舊條目再寫新版本（帶「更新於 MM-DD」）。

手動入口（可選）：

@機器人記住：週五發週報：寫一條事實
@機器人記住設定：羣裏管老張叫張哥：寫設定（也支持 記住黑話： / 記住人物：）
@機器人記憶：檢索本羣長期記憶並回答
@機器人忘掉 XXX：召回後軟刪對應條目

歷史預熱：緩衝不足或最新一條已過期時，用 NapCat 的歷史接口補齊（羣用 get_group_msg_history，私聊用 get_friend_msg_history）。預熱是合併（按時間+暱稱+內容去重），不會覆蓋已攢下的歷史。

圖片與表情包¶

默認只存叫到機器人時的圖片。開啓緩存後，羣裏的圖片/表情包也會落盤：

imageCache: all                 # off=只存叫到機器人時的圖；all=羣裏的圖也存
imageCacheMaxBytes: 2097152     # 單張 ≤ 2MB
imageCacheDailyCap: 100         # 每個聊天每天最多 100 張
imageCacheRetentionDays: 7      # 超期目錄自動清理

落盤位置：<會話cwd>/napcat-inbox/imgs/<YYYYMMDD>/<hash>-<原名>
聊天記錄裏寫成 [圖片:<文件名>]，之後可用 read_image 回看
去重：按圖片 URL 的 hash
歷史圖片也會緩存：預熱時逐張嘗試用 get_image 解析，成功則落盤並寫成 [圖片:<文件名>]，解析失敗標 [圖片(已過期)]
記錄裏帶可讀路徑：[圖片:napcat-inbox/imgs/<日期>/<文件>]（相對會話工作目錄）
注意：@ 它那一輪圖片會隨消息直接送進模型；歷史/主動發言輪默認只給記錄，按需讀圖

主動發言（僞人模式）¶

默認關閉。開啓後，羣裏有人聊天時，會按泊松概率決定要不要自然插一句。

判定鏈（全部通過才考慮插話）：

總開關：proactiveEnabled
靜默時段：proactiveQuietHours（如 00:00-08:00,12:00-13:00）
冷卻：proactiveCooldownMinutes（默認 30）
每小時上限：proactiveMaxPerHour（默認 3）
有人聊：近窗口內至少 K 條他人消息（proactiveMinMessages / proactiveWindowMinutes，默認 3 條 / 5 分鐘）
概率：泊松過程，proactiveRatePerHour（λ，默認 1.5 次/小時；設 0 用 proactiveChance 固定概率）

主動發言的提示裏會拎出最後 2 條消息作爲錨點，要求模型：

≤ 2 句口語化
不重複別人剛說的話
不總結、不列點、不點人名
沒話說只回 __SKIP__

模型決定有話可說 → 正常回復（≤ 2 句、口語化、不總結不列點）→ 發出並記一次發言；沒話說 → 回 __SKIP__ → 插件丟棄這條，並累計 skipStreak（連續跳過會按 1/2、1/4…退避降低下次概率）。

被禁言時自動停發：探測 get_group_member_info.shut_up_timestamp 和 get_group_info.group_all_shut，禁言期間不再發消息、也跳過主動發言。

主動發言也會寫記憶：第一次主動發言時若還沒有記憶空間，會先建空間，再從近期羣聊裏提煉 1~3 條寫進去；已有空間時只在聽到值得長期記的新信息時順手記 1 條。

推薦起步值：

proactiveEnabled: true
proactiveRatePerHour: 3
proactiveCooldownMinutes: 15
proactiveMaxPerHour: 3
proactiveQuietHours: "00:00-08:00"
proactiveMinMessages: 2
proactiveWindowMinutes: 5

性格設定¶

通過 personaOverrides 配置：

group:<羣號>=<人設>
private:<QQ>=<人設>

按會話精確匹配注入到 systemPrompt.context
隻影響語氣 / 稱呼 / 風格，不會把設定原文念給用戶，也不會拿它當自我介紹
留空 = 不注入任何性格，純工具人

文件與圖片收發¶

圖片（收）：原生送達。下載到 <會話cwd>/napcat-inbox/ → attachments.admitPromptContent → ImageBlock 進模型請求；同時保留 [圖片: <路徑>] 文本兜底
文件（收）：私聊三級兜底（get_private_file_url → base64 → http url）；遠端 NapCat 只給本機路徑時會給出明確原因
羣文件（收）：按需拉取，支持模糊文件名
引用消息：引用一條帶圖/文件的消息 @機器人，會通過 get_msg 取回被引用消息裏的媒體
圖片 / 文件（發）：napcat_send_image（本地路徑或 URL，自動 base64，NapCat 在遠端也能發）、napcat_send_file（file 段，失敗退回 upload_*_file）

穩定性與其他¶

複用宿主已存在的 agent；同一會話裝配串行化
會話文件丟失（ENOENT）自愈並重投；歸檔過的會話改用 -rN 新會話（不擅自解除歸檔）
QQ 側無人可點「同意」，自動把該 agent 審批策略設爲 never（GUI 裏顯示 Custom 屬預期）
診斷：<會話cwd>/napcat-inbox/_image-debug.log 逐步記錄收圖

安裝與啓用¶

NapCat 側¶

選擇一種連接方式：

forward（推薦）：插件主動連 NapCat 的 WebSocket
NapCat 開 WebSocket 服務器，記下 ws://<host>:<port> + token
reverse：NapCat 連插件的 WebSocket 服務
NapCat 填 ws://<插件所在機器>:<port>；插件這邊填 host / port / accessToken
accessToken 兩邊必須一致

安裝插件¶

# 從 GitHub
dsh plugin --profile web add github:wzwei1990/dsh-napcat

# 或本地目錄
dsh plugin --profile web add /path/to/dsh-napcat

典型用法¶

在 NapCat 中配置 WebSocket 連接，確保 token 一致
使用上述命令安裝插件
在 DSH 的設置頁裏，爲每個羣/私聊配置准入策略、白名單、關鍵詞等
開啓羣記憶（默認開），模型會自動捕獲設定、黑話、人物、事實
如需主動發言，啓用 proactiveEnabled 並調整相關參數
需要時配置 personaOverrides，爲不同羣或私聊注入性格
開啓圖片緩存（imageCache: all）後，羣裏的圖片會按日期和 hash 落盤，聊天記錄裏會顯示 [圖片:<文件名>]

適用場景與注意¶

適合：已經在用 NapCat / OneBot 11，希望把 DSH agent 直接接入 QQ 聊天，並需要會話記憶、性格設定、主動發言等能力的開發者
注意：插件以當前 DSH 進程的權限運行；安裝前應檢查源碼與許可證

結尾¶

dsh-napcat 把 NapCat 的 OneBot 11 事件轉換成 DSH 的會話，讓同一個 agent 同時服務多個 QQ 聊天。它提供了會話記憶、主動發言、性格設定、文件/圖片收發等能力，適合想在 DSH 生態中快速接入 QQ 通道的開發者。

目錄頁：https://www.skillhub.cn/plugins/wzwei1990/dsh-napcat
GitHub：https://github.com/wzwei1990/dsh-napcat