前言¶
DeepSeek Harness (DSH) 是一個基於 Cordis 框架的智能體運行環境。dsh-adapter-qq 是其官方 QQ 機器人適配器插件，旨在解決開發者需要在移動端或桌面端 QQ 與 DSH Agent 進行深度交互（如全量編碼、Shell 執行、子代理規劃）的需求。
不同於常見的逆向協議實現，該插件基於 QQ 官方 OpenAPI v2 構建。它將 DSH 的 Web UI 能力與 QQ 單聊窗口打通，實現對話、執行與審批的實時同步。
核心功能¶
該插件主要提供以下能力：
- 基於 QQ OpenAPI v2 的 C2C 單聊適配：使用 WebSocket Gateway 長連接接收消息，HTTP API 發送消息，無需第三方逆向協議，連接穩定合規。
- 實時雙向同屏同步：在 QQ 中提問，Web UI 實時展現；在 Web UI 中操作，QQ 端實時推送進展。
- 雙向審批聯動：遇到超權限操作（如文件修改）時，審批卡片同時推送到 QQ 與 Web UI。支持在 QQ 端一鍵點擊“允許”或“拒絕”，兩端立即結算。
- 交互式操作板：在聊天中生成按鈕面板，支持一鍵切換會話、選擇預設、切換權限，無需繁瑣輸入。
- 全局自定義快捷菜單：啓動後自動通過官方 API 註冊底部快捷菜單，提供會話列表、狀態與快捷管理入口。
- 動態預設與權限管理：預設列表從 DSH 運行時動態獲取，支持在會話中即時切換權限級別（只讀、工作區寫入、全系統）。
- 原生 Web UI 配置：配置項嵌入 DSH Web UI 原生設置頁，安全字段自動脫敏。
安裝與前置要求¶
安裝前請確保環境滿足以下條件：
- Node.js: 版本 >= 18
- 依賴庫:
@deepseek-ai/cordis(^4.0.0) 和@deepseek-ai/schemastery(^3.18.0) - QQ 憑證: 需準備 QQ 開放平臺的
AppID和AppSecret
安裝命令如下：
dsh plugin --profile web add dsh-adapter-qq
配置項¶
安裝後，進入 DSH Web UI 的 設置 (Settings) 頁面，展開 【QQ 機器人 (QQ Bot)】 卡片進行配置。主要配置項包括：
appId: 填寫 QQ 開放平臺的 Bot AppID。clientSecret: 填寫 AppSecret（密文遮罩）。sandbox: 是否連接沙箱環境（測試期間建議勾選）。userOpenid: 綁定的專屬用戶 OpenID（留空將在收到首條消息時自動綁定）。defaultPreset: 新建會話默認 Agent 預設（如standard）。defaultCwd: 新建會話默認工作目錄。autoRegisterMenu: 啓動後自動註冊底部快捷菜單。markdown: 消息回覆優先使用 Markdown 渲染。syncToolCalls: 是否同步推送工具調用執行進度。toolCallAggregateWindowMs: 工具調用聚合推送窗口時間（毫秒）。
交互指令¶
在 QQ 單聊窗口中，可直接發送以下指令或在底部菜單/操作板中點擊按鈕：
| 指令 | 功能說明 |
|---|---|
/sessions |
查看工作區層級樹形會話列表，支持按鍵切換 |
/new |
啓動新建會話嚮導，選擇工作區或目錄 |
/switch <序號或ID> |
切換當前活躍會話 |
/current |
查看當前會話詳細信息 |
/model |
查看模型列表，支持一鍵切換 |
/effort |
查看或切換思考等級（off/low/medium/high/xhigh/max） |
/stats |
查看會話統計（輪次、步數、LLM耗時、緩存命中率等） |
/preset |
查看或切換 Agent 預設 |
/permission |
查看或切換權限模式（只讀、工作區寫入、全系統） |
/cancel / /stop |
中止當前 Agent 運行 |
/approve / /reject |
批准或拒絕待審批請求 |
/menu |
手動同步底部快捷菜單 |
/help |
顯示幫助菜單與操作板 |
注意事項¶
- 權限運行：插件以當前 DSH 進程的權限運行，涉及系統操作或文件修改時需注意權限配置。
- 許可證：遵循 MIT 許可證。
- 網絡環境：若使用代理軟件（如 Clash），需確保
bots.qq.com與*.qq.com直連，避免 DNS 解析失敗。
總結¶
dsh-adapter-qq 是 DeepSeek Harness 生態中連接 QQ 生態的關鍵插件。它通過官方 API 提供了穩定、合規的 C2C 交互方式，並實現了與 Web UI 的深度雙向綁定，適合需要在移動端或即時通訊場景下使用 DSH 編碼與執行能力的開發者。
文檔與源碼：
* 技能目錄：https://www.skillhub.cn/plugins/jixishi/dsh-adapter-qq
* GitHub 倉庫：https://github.com/jixishi/dsh-adapter-qq
