前言¶
DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”，通過協議驅動將各類消息平臺接入 Agent 生態。dsh-qqbot 是基於 deepseek-harness (dsh) 的 QQ Bot IM 插件增強 fork。它將 QQ 消息平臺作爲 dsh agent 的前端協議驅動，並提供了一套基於官方 Bot API 的接入方案，解決了第三方協議端可能存在的封號風險與穩定性問題，同時補全了富媒體交互、羣管理及擴展開發能力。
功能概覽¶
該插件具備以下核心能力：
- 協議驅動：基於 deepseek-harness (dsh) 的 QQ Bot IM 插件增強 fork，將 QQ 消息平臺作爲 dsh agent 的前端協議驅動。
- 官方 Bot API：使用官方 Bot API（非模擬協議），無封號風險。
- 表情包圖庫：支持自動去重、分類、檢索與挑圖。
- 富媒體收發：支持圖片、語音、視頻、文件等多種媒體形式的收發。
- 定時任務：支持預設定時任務，讓 AI 按時在羣內發言。
- 多實例人格：支持多賬號獨立運行，每個實例擁有獨立的 AppID、人格設定與圖庫。
- 好感度系統：具備熟識度與好感度雙維度計算，影響 AI 的主動發言意願。
- 可視化設置面板：提供懸浮球 dock 進行設置，支持聊天記錄回放與富媒體查看。
- 羣管理：支持入羣審批、禁言、查成員。
- 擴展系統：提供 5 套擴展點，支持自定義工具、命令、交互邏輯與消息處理。
- 踢人功能：通過自有 QQ 號配合羣官網接口實現（功能受限，需依賴自有號）。
安裝與啓用¶
安裝前需確認已安裝 DeepSeek Harness 並處於 web profile 環境中，因爲可視化設置面板（懸浮球 dock）僅在 web profile 下生效。
- 執行以下命令安裝插件：
npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot
- 安裝完成後，在
dsh web的設置中會出現「QQ 機器人」面板，點擊即可進行配置。 - 若從 GitHub 源碼直接安裝，需確保倉庫根目錄存在編譯產物
dist/（推薦直接使用 npm 發佈版）。
核心能力¶
協議接入與安全性¶
插件不走模擬協議端（如 NapCat），而是直接使用騰訊官方 QQ 機器人開放平臺接口。這種方式不依賴你的個人 QQ 號登錄，賬號安全風險極低，且資源佔用極小（僅需 HTTP + WebSocket）。由於功能受限於官方接口，部分高級功能（如踢人）需通過插件提供的特殊方式補充。
可視化設置與羣管理¶
安裝到 web profile 後，界面右下角會出現懸浮球 dock。通過該面板可以進行以下操作：
* 羣管理：處理入羣審批、禁言、查看成員列表。踢人功能需使用你自己的 QQ 號通過羣官網接口實現，掃碼一次後可長期免掃。
* 聊天回放：像普通 QQ 一樣查看羣聊與私聊記錄，支持放大圖片、播放本地視頻、將 SILK 語音轉爲 MP3。
* 發送消息：在面板聊天框中直接發送文字、插圖或文件。
擴展系統¶
插件內置了擴展系統，允許在不修改插件源碼的情況下添加自定義功能。系統提供 5 套擴展點：
1. tools：供 AI 在思考過程中主動調用的工具。
2. commands：用戶觸發特定命令時執行的邏輯。
3. botplay：處理卡片互動按鈕點擊事件。
4. hooks：插件啓動時執行的任務或監聽器。
5. inbound：接管每一條消息的命運（如過濾、改寫、靜默處理）。
表情包與智能互動¶
- 圖庫管理：機器人會自動將羣內接收到的圖片存入圖庫，支持去重與分類。
- 自動回覆：用戶發送“發個開心點的圖”等指令，AI 會自動檢索圖庫並挑選合適的表情包回覆。
- 好感度機制：系統通過小模型分析 AI 的內心想法與實際發言，計算熟識度與好感度。好感度僅影響 AI 主動發言的頻率，負好感也不會導致機器人冷落或攻擊羣成員。
部署注意¶
- Profile 限制：必須安裝到
webprofile 才能使用可視化設置面板。若安裝到其他 profile，將無法看到懸浮球和設置頁。 - 踢人功能：QQ 官方未開放踢人接口，插件通過“自有 QQ 號 + 羣官網”實現此功能。這意味着你需要用自己的號去管理羣，且需確保該賬號擁有管理權限。
- 安卓部署：在安卓 Termux 等環境中，若系統不支持 ONNX 運行時，建議在設置中勾選“程序兜底（不依賴小模型）”。
- 隱私安全：插件不包含任何機器人憑據（AppID/Secret）與隱私數據，所有敏感信息由用戶自行管理。
總結¶
dsh-qqbot 爲 DeepSeek Harness 提供了安全、低成本的 QQ 機器人接入方案。它通過官方 API 保證了穩定性，通過擴展系統提供了靈活的開發空間，通過可視化面板降低了使用門檻。適合需要在 QQ 羣組中部署 AI 助手、進行羣管理或開發自定義互動功能的開發者。
