前言¶
在 DeepSeek Harness（DSH）裏接 QQ，常見做法是掛官方通道或 OneBot 客戶端，再疊若干認知、記憶類插件。問題是：羣裏的 @、命令、推送和真正聊天往往混在同一條鏈路裏，token 和權限邊界不好控；人設、記憶若分散在多個插件，運維和隱私也偏散。
dsh-qqbot-refine（維護者 Anarrogantcat，倉庫由鯨魚娘與染喵長期維護）把 QQ/NapCat 增強做成單一 DSH 插件：命令、推送、禁言/撤回、圖庫同步、診斷等閘門在模型之前生效，多數操作 0 token；人設、半衰期記憶、本地心情引擎、關係親近度等收在本機存儲。倉庫 README 還描述了向 DSH「身份系統」演進的設計（P0 已在倉庫內測通，尚未部署到 DSH 宿主）。下文按當前已發佈能力說明定位、功能與上手步驟。
這是什麼¶
一句話：給 DSH 加一層可治理的 QQ 通道——NapCat（OneBot 11）或官方 Tencent 通道二選一，不依賴其他 DSH 插件（onebot 模式下整條鏈路在本插件內）。
- 目錄頁：https://www.skillhub.cn/plugins/Anarrogantcat/dsh-qqbot-refine
- GitHub：https://github.com/Anarrogantcat/dsh-qqbot-refine
- 分類：工作流（社區目錄 SkillHub）
- 當前 package 版本：0.11.2（MIT，Node ≥20，DSH ≥0.2.0）
核心功能¶
閘門與成本¶
頻率（僅 @ / 自然接話、冷卻、owner 優先等）、隱私（白名單、出站脫敏、不可信內容隔離）、羣秩序類命令均在模型前處理，README 功能表標明這些模塊 token 爲 0。每輪注入控制羣上下文條數、記憶召回條數；心情默認本地引擎，不依賴第三方認知插件（可選與 dsh-feiyu-mood 聯動）。
像個人：人設、心情、記憶、關係¶
- 人設：人設庫 + 全局/按羣/按私聊三級作用域；內置多套預設，面板與
#人設命令管理。 - 心情：七維 + 生氣/得意，半衰期與慣性，影響語氣等；本地計算。
- 記憶：半衰期淡忘、
#記得手動寫、第一人稱陳述自動記。 - 關係：對羣成員的親近度/信任度隨情緒信號更新。
- 認知四張卡（S7）：在場的人、自述/承諾、待辦、羣摘要——數據落在本機
<store>/relations/等路徑，注入時 0 token。
能幹活的擴展（按需啓用）¶
本地 ComfyUI 生圖（#畫 流程：搜 → 問 → 確認）、WSL+CUDA TTS（#說話）、B 站動態與鏈接、LPL/LCK 等賽程、知識庫從本機路徑導入（md/txt/csv/json/html/pdf/docx/sqlite 等）、自帶只讀 MCP 沙箱橋（工具名 mcp__<server>__<tool>）。可選配合 dsh-computer-use-win 做電腦操控，面板「隱私 / 工具」可設羣成員 off / read / full。
通道：onebot 與 tencent¶
transport.mode 單活、不共存：
| 模式 | 說明 |
|---|---|
onebot |
本插件直連 NapCat websocketServers（OneBot 11），15 項能力全開，無需其他 DSH 插件 |
tencent |
掛官方 @tencent-connect/dsh-qqbot 鉤子，受官方 SDK 能力限制（7 項） |
onebot 鏈路：NapCat → OneBotClient → 閘門 → 宿主 agent → 出站閘門 → OneBot 發送。每羣/每私聊一個 DSH 會話，sessionId 爲固定前綴的 sha256，重啓可 resume。
NapCat 專屬（僅 onebot）：撤回不答、戳一戳反應、合併轉發展開、引用原文、語音轉寫（可選 STT 配置）、引用回覆、定時撤回、羣管命令等——詳見 README 表格。
錢與安全（羣場景）¶
#餘額 / #飯、#充值、#飯賬、#充值碼；峯谷價折算用量；可選花費硬閘、發送失敗熔斷、被踢摘白名單、被禁言閉麥。配置與記憶均在 $DSH_HOME/storages/dsh-qqbot-refine/，README 強調不上傳雲端。
安裝與啓用¶
Web 版 profile 一條命令安裝（桌面端可將 web 換爲 desktop 或用應用內「設置 → 插件」）：
dsh plugin --profile web add github:Anarrogantcat/dsh-qqbot-refine
手動協議（與 README 一致）：插件進 profile 的 node_modules 或 package.json 依賴 → 在 dsh.profile.bundles 增加 "dsh-qqbot-refine" → 重啓 DSH；cordis.patch.yml 會插入 id: qqbot-refine。
NapCat（onebot 模式，一次性）
- WebUI
http://127.0.0.1:6099→ 網絡配置 → Websocket 服務器 → 新增：host=127.0.0.1、port=3001、token=<隨機 32 位>、messagePostFormat=array、reportSelfMessage=否 - 保存並重啓 NapCat
- 面板「通道」：
mode=onebot、地址ws://127.0.0.1:3001、填入 token → 重啓 DSH
配置面板：http://127.0.0.1:<DSH端口>/qqbot-refine（僅 loopback）；也可通過瀏覽器半邊右下角懸浮按鈕打開。設置落盤 <DSH_HOME>/storages/dsh-qqbot-refine/settings.json，保存熱生效。更新可在面板「檢查更新」或再執行 add 命令；更新前會備份到 ~/.dsh/storages/dsh-qqbot-refine/backups/update-<時間>/。
典型用法¶
經過上面的步驟，在羣裏 @ 機器人即可對話。常用 # 命令（均 0 token，管理類限 Owner/Admin）：綁定 / 綁定本羣、羣狀態、閉嘴 / 說話、撤回、禁言 / 解禁、記得 / 忘掉 / 記憶、人設、表情、B站、賽程、用量、餘額 / 飯 / 充值、幫助 等；#羣列表、#羣成員、#踢人、#名片、#贊 僅 onebot 模式。
維護通道：#診斷（只讀）→ 貼 diff → #合併（git apply –check）→ #測試。
示例認知卡片段（README 說明注入人設段，每次只取有用句）：
# 在場的人（按最近活躍）
· 染喵（羣主）：今天說過 12 句
# 我剛纔說過/答應過
說過：押 HLE；答應過：明天幫你查賽程
適用場景與注意¶
適合：需要在 QQ 羣/私聊裏跑 DSH agent，且希望頻率、隱私、羣管、用量在本機可控；已有 NapCat 或願意走 OneBot 11；接受人設/記憶/心情 bundled 在同一插件、數據本地落盤。
注意：
- 插件以當前 DSH 進程權限運行，安裝前應閱讀倉庫源碼與 MIT 許可證，確認通道 token、白名單、電腦操控檔位等配置符合你的安全要求。
- 羣聊與資料內容一律按不可信素材處理，不當指令執行；出站會脫敏密鑰與路徑。
- 身份系統路線圖在 README 中標註爲設計已定稿、宿主側尚未部署，勿與當前面板功能混爲一談。
- SkillHub 爲社區插件目錄，與 DeepSeek / 幻方無官方從屬關係；星標等以 GitHub 頁面爲準（線索抓取時爲 0）。
結尾¶
dsh-qqbot-refine 把 QQ 機器人做成「閘門在前、聊天在後」的 DSH 工作流插件：NapCat 或官方通道二選一，人設/記憶/心情/關係與羣工具收在一處，並預留向統一身份底座演進的方向。進一步瞭解可打開 SkillHub 目錄頁 與 GitHub 倉庫（安裝細節見 docs/INSTALL.md）。
