前言¶
在 DeepSeek Harness（DSH）裏接 QQ，常見做法是自行拼 NapCat、OneBot、Koishi 和模型網關：路徑、端口、反向 WebSocket、權限與 AI 觸發分散在多處配置裏，啓停和排查成本高。社區插件 dsh-qqbot（維護者 prophetcrab）把 DSH 端定位爲「控制中心」：由 DSH 負責安裝/啓停、配置控制面、AI 網關、人設/畫像與 Web 面板；NapCat 與 Koishi 作爲外部運行時仍由插件管理，但不承擔 DSH 側的權限策略與模型編排。當前實現 僅支持 macOS / Apple Silicon，與 Linux 或 Windows 上的自建方案不在同一支持範圍內。
這是什麼¶
dsh-qqbot 是 DSH 的 客戶端類插件（package.json 中 dsh.client.platform 爲 web，並注入側邊欄與設置 UI）。一句話鏈路如下：
QQ ↔ NapCat ↔ OneBot 11 ↔ Koishi ↔ DSH Host ↔ 面板 / LLM
插件版本 0.5.1，許可證 MIT，依賴 DSH >=0.2.1-rc.2 <0.3.0，Node ^22.19.0 || >=24.0.0。GitHub 倉庫 prophetcrab/dsh-qqbot 當前分支爲 dshbot-mac；社區目錄頁見 SkillHub 條目（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。
三端分工¶
理解插件前先對齊職責邊界（摘自 README 表格）：
| 端 | 負責 | 不負責 |
|---|---|---|
| NapCat | QQ 登錄、協議、收發消息、OneBot 實現、WebUI | 權限、AI、業務、面板 |
| Koishi | Session、權限、觸發、上下文、指令/插件、發送 | QQ 協議、QQ 注入、模型調用 |
| DSH（本插件） | 安裝/啓停、配置控制面、AI 網關、人設/畫像、面板 | QQ 協議、消息循環、權限執行 |
NapCat 只從內置離線包安裝（vendor/napcat/payload/NapCat.Shell-4.18.42.zip），校驗 size 與 SHA-256，不聯網下載。Koishi 使用模板項目 ~/project/qq-bot，版本 4.18.11，默認端口 5140，反向 WS 路徑 /onebot。
核心功能¶
下面介紹 README 中可覈對的能力，不展開未在資料中出現的「一鍵」細節以外的承諾。
Host 與 Client 插件化¶
Host 側每個能力是一個 host plugin，統一貢獻 registerRoute、registerTool、registerFeature、registerStatusProvider、registerClientTab、provide(service)；關閉某個插件時，其路由、工具、Feature 與 Tab 一併消失。Client 側每個 Tab 是獨立 Client 插件，源碼在 client/，構建產物爲 client.js（npm run build:client），避免單文件巨石。
面板側 Client 插件目錄包括：overview、ai、messages、access、plugins、features、logs——對應總覽、AI、消息、權限、插件、特性與日誌等 Tab。
NapCat 與 Koishi 管理¶
NapCat 側要點：
- QQ.app：
/Applications/QQ.app - WebUI：
127.0.0.1:6099 - 反向 WS：
ws://127.0.0.1:5140/onebot
可配置字段（空值表示走默認推導）：napcatPort、napcatToken、qqPath、napcatDir、offlineVendorDir、offlineNapcatVersion。
Koishi 側可配置：projectDir（默認 ~/project/qq-bot）、koishiPort、reversePath、napcatToken、autoRestartKoishi、autoInstallDeps、autoSyncSelfId、logLines。
AI、人設、權限與消息¶
- DSH 寫 配置 / 人設 / 畫像；Koishi 模板插件（如
access-control、ai/*）執行 權限、觸發與發送。 - Koishi 側 AI 子模塊包括
gateway.ts（DSH HTTP 契約）、trigger.ts（概率/@/回覆/跟進）、context.ts（背景/圖片）等，插件間通過ctx.qqbot.*服務通信。 - 運行時數據落在
~/project/qq-bot/data/：config/（access.json、ai-settings.json、persona.json）、state/（含koishi.db、napcat-login-qr.png等）、assets/、logs/。
舊版平鋪的 data/*.json 可用遷移腳本一次性遷入（遷移前需停止 Koishi）：
node scripts/migrate-data.mjs ~/project/qq-bot --database
安全與架構約束¶
- NapCat token 不落日誌、不返回明文；外部命令使用 argv 數組，不拼 shell。
- 離線包校驗失敗即拒絕安裝；權限策略由 Koishi
access-control執行。 - 倉庫內
npm run check覆蓋測試、client 構建、host/client 冒煙、架構與離線包校驗等（README 稱 host 冒煙約 41 routes / 6 tools / 5 features）。
安裝與啓用¶
資料中的安裝入口是項目內腳本，不是 dsh plugin add github:... 形式的目錄命令。使用前需已將插件源碼放到本地路徑（README 示例爲 ~/project/dsh-qqbot），並在該目錄執行：
cd ~/project/dsh-qqbot
node scripts/install-profile.mjs --profile desktop --install
首次加載會依次：
- 從
template/創建~/project/qq-bot - 解壓內置 Koishi
darwin-arm64依賴（template/runtime-bundles/node_modules-darwin-arm64.tar.gz） - 從
vendor/napcat離線安裝 NapCat - 寫入 OneBot 反向 WS 配置
- 啓動後掃碼登錄 QQ
安裝前請自行閱讀倉庫源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，會寫本地項目目錄與 QQ/NapCat 相關路徑，僅在可信環境中啓用。
典型用法與開發校驗¶
日常運維圍繞 DSH 面板與各 Tab 完成啓停、消息查看、權限與 AI 設置；具體按鈕與 API 以 Host 註冊的路由爲準。若你參與插件開發或二次打包，README 給出的校驗命令如下：
npm test # 198 tests
npm run build:client
npm run smoke:host
npm run smoke:client
npm run check:architecture
npm run offline:verify
npm run check # 全部
Client 源碼與生成物需保持同步：
npm run build:client
node scripts/build-client.mjs --check
更細的模塊與重構說明見倉庫 docs/archive/refactor-v2/ 與 docs/decisions/ 下的設計文檔（如人格/記憶、羣消息監聽閉環等）。
適用場景與注意¶
適合：已在 macOS（Apple Silicon）上使用 DSH，希望用統一面板管理 NapCat + Koishi + AI 網關與人設/畫像的 QQ 機器人方案，並接受離線內置 NapCat/Koishi 依賴的維護方式。
不適合或需注意：
- 非 macOS 環境：README 明確當前分支只支持 macOS / Apple Silicon。
- 需要自行從 GitHub 拉取或審查代碼後再安裝；不要使用資料未給出的安裝命令。
- NapCat 涉及 QQ 協議與第三方實現，合規與賬號風險需自行評估；權限策略雖在 Koishi 執行，策略內容仍由你在面板與配置中定義。
結尾¶
dsh-qqbot 把 QQ 機器人鏈路上 DSH 該管的一層（安裝啓停、控制面、AI 網關、人設/畫像、Web 客戶端）收攏爲插件化 Host/Client，並與 NapCat、Koishi 的職責劃分寫死在架構裏，便於在 DSH「一切皆插件」的生態中按需開關能力。
