前言¶
做 DeepSeek Harness（DSH）渠道插件時，常見的問題是：Web 側會話已經可用，但 QQ 側缺少一個可直接運行的 channel 插件；要自己接 Gateway、處理消息、文件、審批和會話持久化，成本不低。
下面介紹 sliverp/DeepSeek-harness-qqbot。它是一個 out-of-tree DeepSeek Harness channel plugin，用官方 @tencent-connect/qqbot-nodejs Gateway client 把 QQ Bot 接入 persistent Harness agents，覆蓋 C2C 和羣聊文本、圖片、文件、審批與命令。
這是什麼¶
- 插件名：
sliverp/DeepSeek-harness-qqbot - 維護者：
sliverp - 許可證：MIT
- 定位：DSH channel plugin，將 QQ Bot Gateway 接到 persistent Harness agents。
核心功能¶
會話與消息¶
- C2C 和羣聊文本消息。
- 每個 C2C 或羣聊會話對應一個 persistent Harness session。
/new和/reset會保留舊歷史，並切換到新的 durable session。- 入站 PNG、JPEG、WebP、GIF 圖片會作爲 durable Harness attachments 處理。
- 如果所選模型不接受圖片輸入，會自動退化爲純文本。
- 入站語音轉寫文本和非圖片附件元數據會攜帶臨時 QQ 下載 URL。
- 出站支持助手文本、圖片和本地 workspace 文件。
文件發送¶
- 提供 QQ-turn-scoped
qq_send_file工具，用於在當前 QQ 輪次發送文件。 - 工具限定在 workspace 內，並做文件大小檢查。
- 只接受
cwd內的 regular files，解析符號鏈接，拒絕大於 104,857,600 字節（100 MiB）的文件。
QQ 能力¶
- QQ Markdown 回覆默認開啓；需要 QQ Markdown permission，否則 QQ API 會拒絕 Markdown 消息。
- 支持 typing indicators、長回覆拆分、按會話排序、去重、發送重試和有界超時。
審批與訪問控制¶
- 對需要 Harness approval 的操作，會發送 requester-bound QQ 審批消息，帶 one-shot Allow 和 Reject 按鈕。
- 只有發起當前輪次的 QQ 用戶可以批准或拒絕。
- 審批超時默認 120,000 毫秒，未答覆會被拒絕。
- 支持 fallback 到另一個 composed approval channel。
- C2C 和羣聊流量可使用 open、allowlist 或 disabled access policy。
- 含非公開數據的 workspace 建議使用 allowlist；被允許的 QQ 用戶也能訪問所選 agent preset 提供的工具。
DSH 集成¶
- 密鑰通過 Harness credential service 解析，而不是直接寫在插件配置裏。
- AppID 或 AppSecret 未配置時，插件以 dormant 方式啓動，不阻塞 DSH。
- 無效 QQ credentials 只會讓 QQ channel offline，不會導致 DSH 啓動失敗。
- 支持 Harness agent-preset composition，用於 tools、prompts、skills。
- 如果 Web 已經打開了同一個 live session，QQ 側會安全複用，不會創建第二個 session writer。
環境要求¶
- Node.js 22.19 或更高版本
- pnpm 10.33.4
- DeepSeek Harness 0.1.0-rc.7 或更高版本
- QQ Bot AppID 和 AppSecret，且啓用 C2C 和/或 group message events
- 如需 QQ 審批按鈕，需要 Inline Keyboard permission
package.json聲明版本爲 0.1.5
安裝與啓用¶
從 GitHub 安裝：
pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-qqbot
如果已有本地 checkout，也可以直接安裝路徑：
pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-qqbot
開發時可以在啓動環境中設置憑據：
export QQBOT_APP_ID='your-app-id'
export QQBOT_APP_SECRET='your-app-secret'
pnpm dsh --profile web
如果要長期運行，可以把 QQBOT_APP_ID 放入 ~/.dsh/.env，並通過 Harness credential settings surface 保存 QQBOT_APP_SECRET。兩個值都不要提交到代碼倉庫。
也可以通過覆蓋 ~/.dsh/profiles/web/cordis.patch.yml 中的插件行，調整訪問策略或限制。
典型用法¶
1、啓動 DSH，等待日誌出現 QQ Gateway connected。
2、給機器人發送：
/bot-ping
3、發送普通文本或圖片。消息會追加到對應會話的 durable Harness session，模型回覆會回到 QQ。
4、發送 /new，確認機器人報告新的會話。
5、發送已註冊命令，例如：
/goal
/plan
/compact
其他可用命令包括：
/bot-ping
/bot-image-test
/bot-file-test
/bot-help
/bot-status
/bot-cancel
適用場景與注意¶
適合需要在 QQ C2C 或羣聊中使用 DSH agents 的場景，尤其是希望複用持久會話、agent preset、文件發送和審批流程的團隊。
注意：
- 插件以當前
dsh進程權限運行，安裝前應檢查源碼與許可證。 - 如果 workspace 含非公開數據，使用 allowlist 策略。
- QQ Markdown 權限未開啓時，關閉 Markdown 回覆，避免 QQ API 拒絕消息。
qq_send_file只發送cwd內的常規文件，且受 100 MiB 限制。- 審批按鈕依賴 Inline Keyboard permission；超時默認 120,000 毫秒。
結尾¶
sliverp/DeepSeek-harness-qqbot 把 QQ Bot 的收發、會話、文件和審批接到 DSH 的持久 agent 會話上，適合作爲 QQ 渠道插件的起點。
GitHub：https://github.com/sliverp/DeepSeek-harness-qqbot
