前言¶
如果你在 DSH 裏做過智能體落地，大概率會遇到同一個需求：模型在面板裏聊得很好，能不能接到 QQ 上，讓用戶直接發消息？常見的做法是自己拉一個 NapCat 或 go-cqhttp 客戶端，裝登錄態，再寫一套收發消息的服務——這一步的安裝和部署成本往往比寫業務邏輯還高。
下面介紹的插件 luchengfj/qq-bot（面板插件名 @local/qq-bot）就是針對這個痛點的。它屬於 DeepSeek Harness 生態裏「一切皆插件」思路下的一個通道插件，由 luchengfj 維護，目的是把 Harness 變成一個 QQ 機器人通道：接收文字、圖片消息，調用模型生成回答，再把回答發回去。它的設計取向與上面那類方案有明顯區別——插件本身純 Node 實現、零 npm 依賴、不下載、不安裝、不啓動任何 QQ 客戶端，也不再自動下載 NapCat；要對接真實 QQ，它複用你已經裝好並正在運行的 OneBot v11 實現端。
這是什麼¶
一句話定位：一個 DSH 面板插件，提供 QQ 機器人收發消息的通道，默認在面板裏即可直接聊天驗證，連真實 QQ 是可選能力。
倉庫爲 https://github.com/luchengfj/qq-bot，協議 MIT，package.json 中聲明 version 爲 1.0.0，engines.dsh 要求 >=0.1.7-rc.1。當前倉庫星標爲 0，說明還沒有形成規模化的用戶反饋，功能以 README 爲準。
插件基於 OneBot v11 協議，適配 NapCatQQ、Lagrange.Core、LLOneBot、go-cqhttp 等已經裝好的實現端。
核心功能¶
下面按 README 列出的已覈實能力逐條說明。
1. 面板直聊測試（默認路徑，零下載）
側邊欄「QQ 機器人」面板的「① 直聊測試」區塊，不裝任何東西就能發文字或圖片，走完整的 BotLogic 管線：收圖 → 記憶 / 上下文 → 模型作答 → 分段回覆。也就是說，不接入任何 QQ 端，也可以立刻驗證插件的完整鏈路是通的。
2. 默認跟隨 Harness 模型，免密鑰
默認 llm.mode='harness'，跟隨 Harness 裏當前選中的模型，不需要任何 API 密鑰。圖片消息走附件服務。也可以切到 external，走 OpenAI 兼容的 /chat/completions 端點，此時才需要 apiKey。external 端點可換成 OpenAI、DeepSeek、本地 Ollama / vLLM 等任何兼容服務。
3. 本機 OneBot 端口自動探測 + 自動連接
插件啓動時自動掃描本機常見端口（默認 3001, 3000, 5700, 8080, 6099, 3333），對每個端口嘗試 / 與 /onebot 路徑，發送 OneBot get_version 探測（收到 meta_event / lifecycle 推送也算命中），發現可用服務就自動連上。默認每 20 秒重掃一次。插件自身的 6700 端口始終被排除在探測之外。手工填的地址永遠不會被覆蓋——自動探測只在尚未配置 / 連接正向 WS 地址時啓用。
4. 與已有 OneBot 實現對接的四種方式
除了自動探測，其餘三種手工方式：
- 正向 WebSocket（插件主動連出）：填一個已運行的 OneBot v11 正向 WS 地址，或寫進
cordis.patch.yml的forward:塊。 - 反向 WebSocket（實現端連回插件）：把任意 OneBot 實現的反向 WS 客戶端地址指向
ws://127.0.0.1:6700/onebot。 - HTTP POST 上報：同一路徑
/onebot也接受 OneBot 的 HTTP POST 上報，可用secret做 HMAC-SHA1 簽名；這種單向連接發回復需要配合httpApiBase指向 OneBot 的 HTTP API，優先推薦前兩種方式。
5. 長期記憶與對話上下文
機器人自動記住用戶陳述的關鍵事實（例如「我叫小明」「我住在杭州」），私聊與羣聊完全隔離，同主題覆蓋不堆積；超過 memory.ttlDays（默認 30 天）沒說話自動遺忘。對話上下文是另一套機制：保留最近若干輪真實問答並注入模型，靜默超過 historyTtlMinutes 自動清空，/new 可立即清空且不影響長期記憶。
6. 內置指令與回覆清洗
聊天裏可用 /help、/status、/new、/memory、/forget，均有中文別名（/幫助、/狀態、/換話題、/我的記憶、/忘記我），指令只在消息開頭生效。模型返回後插件做本地清洗（lib/reply.js，不額外調用模型）：去開場白、摺疊空行；超過 llm.maxReplyChars（默認 600）時按段落 → 句子 → 空格拆成多條並標註 (1/4)，而不是直接截斷。
安裝與啓用¶
README 給出的安裝方式是掛目錄，沒有寫 dsh plugin add 這類命令，照原文執行即可：
- 把插件目錄掛到 Harness 的插件目錄；
- 或者用
cordis.patch.yml的insert行指向本目錄：
insert:
- { id: qq-bot, name: '@local/qq-bot' }
然後在 DSH「插件」裏啓用 @local/qq-bot。
需要注意的加載規則：改過配置或代碼後必須禁用 → 再啓用纔會重新加載，本地鏈接安裝的插件不會自動熱更新文件。
典型用法¶
先做零下載驗證，再做真實 QQ 接入。
第一步：面板直聊
1. 啓用 @local/qq-bot
2. 打開側邊欄「QQ 機器人」面板
3. 在「① 直聊測試」輸入框發一句話（或貼一張圖）
這一步不需要 QQ 客戶端、不需要 token、不需要 API key，默認走 Harness 原生模型。/help、/status 等指令在面板直聊裏同樣可用。
第二步：連真實 QQ
README 明確寫了前提：QQ 官方沒有「免客戶端」的 HTTP 機器人 API，所以要真實收發 QQ 消息，仍然需要一個已經裝好並正在運行的 OneBot v11 實現端，插件只是不再替你下載它。最省事的做法是什麼都不配，讓自動探測去找；也可以手工配置。修改配置的入口是 cordis.patch.yml：
host: 0.0.0.0
port: 6700
path: /onebot
插件默認監聽 0.0.0.0:6700，路徑 /onebot。只在本機使用的話，把 host 改成 127.0.0.1。
第三步：跑一次自檢
面板的「③ 運行自檢」逐項檢查 6 項：OneBot 監聽、模型後端、反向 WS 連接、正向 WS 連接、面板直聊可用、記憶功能，並附模型連通性測試、統計清零、實時日誌。自檢通過後再通過面板的 send 接口發測試消息，可以減少盲調時間。
面板與接口概覽¶
面板每幾秒自動刷新，按 5 個分組區塊組織（響應式兩欄，窄屏自動單欄）：
| 區塊 | 內容 |
|---|---|
| ① 直聊測試 | 不裝任何東西驗證收圖、答題、記憶與分段回覆；清空當前會話（chat-clear） |
| ② 連接真實 QQ（可選） | 自動探測卡片（「立即掃描」、開關、候選列表），正向 WS 地址配置 / 斷開，反向 WS 接入地址，測試消息發送 |
| ③ 運行自檢 | 6 項檢查、模型連通性測試、統計清零、實時日誌 |
| ④ 記憶與上下文 | 查看 / 刪除記憶，換話題清上下文，立即寫盤，查看最近對話 |
| ⑤ 配置與日誌 | 當前配置（只讀）、完整日誌環、日誌清空 |
面板共註冊 19 個 /api/qq-bot/* 路由，全部經 ctx.webServer 註冊，只允許本機同源訪問：sec-fetch-site: cross-site、Origin 與 Host 不一致、非 loopback 的 Host 或遠端地址都會被拒絕（403）。也就是說這個面板默認是本機調試界面，不要指望把它暴露到公網當運維後臺。面板裏的配置默認是隻讀的，正向 WS 例外，可在面板改並寫盤到 ~/.dsh/qq-bot-forward.json；其餘配置一律編輯 cordis.patch.yml 後禁用 → 啓用。
配置要點¶
完整配置項以倉庫裏的 cordis.patch.yml 爲準，這裏只列容易踩坑的幾項：
llm:
mode: harness # harness: 跟隨 Harness 當前模型，免密鑰（默認）
# external: OpenAI 兼容端點，需 apiKey
temperature: 0.4
maxReplyChars: 600
maxReplyParts: 4
allowPrivateImages: false # 默認拒絕下載內網 / 本機圖片，防 SSRF
memory:
enabled: true
maxFacts: 60
ttlDays: 30
file: # 留空 = 僅內存，重啓即失效；填路徑才寫盤
detect:
enabled: true
ports: [3001, 3000, 5700, 8080, 6099, 3333]
intervalMs: 20000
excludePorts: [] # 插件自身端口 6700 始終自動排除
trigger:
privateAlways: true # 私聊是否全部響應
groupRequiresAt: true # 羣消息是否需 @機器人 或前綴
prefix: ""
allow:
groups: [] # 白名單，空 = 不限制
users: []
denyUsers: []
幾個值得注意的默認值：llm.allowPrivateImages 默認 false，內網或本機圖片地址默認不會去下載；trigger.groupRequiresAt 默認 true，羣消息要 @ 機器人或帶命令前綴纔會觸發；單圖下載上限爲 maxImageBytes: 8388608（8MB）。
適用場景與注意¶
適合誰：
- 已經裝了 NapCatQQ、Lagrange.Core、LLOneBot、go-cqhttp 等 OneBot v11 實現端，想少寫膠水代碼就把 QQ 接到 Harness 模型上的人；
- 想先在面板裏把鏈路驗證通，再決定要不要接真實 QQ 的人；
- 希望默認不配任何 API key、直接複用 Harness 當前模型的人。
注意事項：
- 插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（MIT），不要在沒有讀完代碼的情況下把它暴露到非本機網絡。
- QQ 官方沒有免客戶端的機器人 API，所謂「零下載」指的是插件不下載任何東西，真實 QQ 收發仍然依賴一個已存在的 OneBot v11 端。
- 插件是純 Node 實現、零 npm 依賴，但
engines.dsh要求>=0.1.7-rc.1；該信息來自package.json，實際兼容性以安裝環境爲準。 - 改配置或改代碼後記得禁用 → 再啓用，否則不會生效。
- 本倉庫星標爲 0，社區驗證有限，遇到問題建議直接讀 README 與源碼，或向維護者 luchengfj 反饋。
結尾¶
這個插件的價值在於把「QQ 機器人接入」拆成了一條零下載的默認路徑和一條可選的真實接入路徑：前者讓聯調可以立刻開始，後者不替你承擔安裝 QQ 端的成本。如果你已經有一個跑着的 OneBot v11 實現端，並且想讓它在 Harness 裏直接對話、帶記憶、帶圖片，可以從自動探測那條路試起。
目錄頁：https://www.skillhub.cn/plugins/luchengfj/qq-bot
GitHub：https://github.com/luchengfj/qq-bot
