前言¶
DSH 開發者有時需要把 Agent 放到 QQ 裏使用：在私聊中追問，或在羣聊中觸發一次任務。若只希望接入消息，而不想引入個人 QQ 逆向協議、Hook、注入或模擬登錄，下面介紹 dsh-qqbot-bridge。
這是什麼¶
dsh-qqbot-bridge 是一個 DSH 插件，基於騰訊官方 QQ 機器人開放平臺，將 QQ 私聊或羣聊安全地接入 DeepSeek Harness（DSH）。
- 維護者：
dsh-qqbot-bridge contributors - 當前版本：
0.1.0 - 許可證：
MIT - 倉庫歸屬線索在資料中不一致，本文不據此斷言最終歸屬
給機器人發送消息，等同於向一個獨立的 DSH Agent 會話發送消息。
核心能力¶
- 只使用騰訊 QQ 機器人開放平臺和騰訊官方 SDK，不使用個人 QQ 逆向協議、Hook、注入或模擬登錄
- 首次啓動支持騰訊官方掃碼綁定，自動保存 AppID、Secret 和掃碼用戶 OpenID
- 私聊默認白名單，羣聊默認關閉；空白名單不會退化成開放訪問
- QQ 消息直接驅動 DSH Agent，支持流式回覆、發送失敗自動重試、會話持久化和模型切換
- 支持在 QQ 內處理 DSH 的一次性權限申請：
/approve CODE或/deny CODE - AppSecret、OpenID 和 API Key 僅保存在本機
$DSH_HOME/.env，不進入項目配置和日誌 - 內置隱私掃描、單元測試、打包檢查和 GitHub Actions CI
安裝與啓用¶
插件命令¶
下面是已覈實的 npm 發佈後安裝命令。
dsh plugin --profile qqbot add dsh-qqbot-bridge
dsh --profile qqbot
從源碼啓動¶
以下啓動命令來自已覈實示例；倉庫路徑在資料中存在不一致，使用前請覈對實際倉庫。
Windows¶
git clone https://github.com/JHf0912/dsh-qqbot-bridge.git
cd dsh-qqbot-bridge
powershell -ExecutionPolicy Bypass -File .\scripts\dev-start.ps1
Linux/macOS¶
git clone https://github.com/JHf0912/dsh-qqbot-bridge.git
cd dsh-qqbot-bridge
chmod +x scripts/dev-start.sh
./scripts/dev-start.sh
啓動腳本常用參數：
--profile 名稱--skip-install--build-only--setup-only
設置必填 API Key¶
必須設置 DEEPSEEK_API_KEY，否則機器人無法生成任何回覆。
建議將密鑰寫入本機 DSH 環境文件：
# Windows 默認位置：C:\Users\<你>\.dsh\.env
# macOS/Linux 默認位置：~/.dsh/.env
DEEPSEEK_API_KEY="你的 API Key"
在 Windows 下，也可以追加到默認位置：
$key = Read-Host -Prompt "粘貼你的 DeepSeek API Key"
Add-Content "$env:USERPROFILE\.dsh\.env" "DEEPSEEK_API_KEY=`"$key`""
首次掃碼與白名單¶
首次啓動時，使用騰訊官方掃碼綁定。綁定成功後，插件會保存 AppID、Secret 和掃碼用戶 OpenID。
注意：首次掃碼寫入的 QQBOT_C2C_ALLOW 白名單不會注入本次進程。首次掃碼後，需要停掉並重跑一次，之後 QQ 消息纔會按白名單策略被接受。
QQ 內審批¶
當 DSH 觸發一次性權限申請時，可在 QQ 內使用驗證碼處理。示例如下：
/approve A1B2C3
/deny A1B2C3
審批邊界如下：
- 僅任務發起者本人可以處理
- 驗證碼一次性使用
- 默認 120 秒超時自動拒絕
隱私與運行注意¶
- 插件以當前 dsh 進程權限運行；安裝前應檢查源碼與許可證
- 需要 Node.js
>= 22 - Windows 的
dev-start.ps1不包含 node 存在性檢查 - 當前版本爲
0.1.0，項目仍處於早期階段，建議先使用專用測試機器人、專用工作目錄和私聊白名單 - 必須設置
DEEPSEEK_API_KEY - 敏感配置應保存在
$DSH_HOME/.env，不要提交或粘貼到 Issue、PR、截圖和日誌中 - 使用前遵守騰訊 QQ 開放平臺規則、機器人運營規範和所在地法律法規
- 項目無法承諾賬號絕對不會受到限制，也不會提供繞過風控或協議限制的實現
結尾¶
dsh-qqbot-bridge 的價值在於：用騰訊官方機器人能力連接 QQ 與 DSH，並把訪問控制、密鑰存儲和一次性審批放在插件側處理。
社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；已覈實資料未提供目錄頁 URL。
GitHub 路徑在資料中不一致，請人工覈對後再使用：
- https://github.com/wang-22-code/dsh-qqbot-bridge
- https://github.com/JHf0912/dsh-qqbot-bridge
