前言¶
DSH 的理念是「一切皆插件」，渠道類能力（飛書、Discord、Telegram 之類）本該由插件補齊，但 QQ 這條渠道一直比較特殊：QQ 機器人的出站消息有頻率限制、長消息要分塊、事件訂閱 intents 要在連接期聲明，官方 SDK 的默認行爲在這些邊界上未必符合預期。dsh-qqbot 就是在這條渠道上做工程化的插件，把流式輸出、發送鏈路重試、事件訂閱和可視化設置面板都處理了一遍，並提供了機器人 AppID/AppSecret 之後就能跑起來的完整鏈路。下面介紹這個插件的定位、安裝方式和典型用法。
這是什麼¶
一句話定位：給 DeepSeek Harness（dsh）接 QQ 機器人的 IM 渠道插件，支持羣聊與私聊、發圖發文件、定時任務、多人格與可視化設置面板。
維護者 RrOrange，分類爲客戶端，當前星標 0。它以 zaofan-make/dsh-qqbot 的 npm 發佈版 1.11.36 爲基礎手工維護，上游又 fork 自 tencent-connect/dsh-qqbot；包名沿用原有發佈名，因此 package.json 裏寫的是 @zaofan/dsh-qqbot，版本號 1.11.36，許可證 MIT。
它要解決的問題集中在兩處：一是出站鏈路，包括流式輸出、限流退避、長消息分塊、羣發降速；二是設置入口，把配置、賬號、定時任務、羣管理、審批等收斂到 dsh 的「設置」面板裏，而不是靠改 cordis.patch.yml。
核心功能¶
下面只列插件 README 中明確寫明的能力。
流式輸出。 修復後首幀自建緩衝，私聊可以邊生成邊刷新同一條消息；面板裏新增「流式輸出（默認開）」開關，私聊可關成非流式。羣聊受 QQ 平臺限制只能整條發送。
發送鏈路健壯性。 限流/5xx 退避重試；長消息分塊時單塊失敗不再影響後續塊；羣發降速到平臺配額以內；審批監聽重建後不再被舊實例搶走。
圖片消息。 修復純  消息被當純文本發出的問題；上傳失敗時不再把 [MEDIA:image|…] 字面標記發到羣裏。
事件訂閱補全。 機器人被移出羣、對方關閉主動消息，插件能感知並在面板給出提示。
設置面板。 搜索框合一（字面 + 語義）、保存條吸底、頂部標籤吸頂、「賬號與預設」頁重做，刪掉了冗餘的「怎麼用 / 定時喚醒 / 擴展示例」等頁籤。
渠道基礎能力。 羣裏發圖/文件、定時任務、多人格、多賬號（每個賬號實例一頁）、斜槓命令（發 /help 查看）。
擴展口。 提供用戶擴展樣板與契約文檔，工具/命令/自定義卡片都可以寫在賬號數據目錄的 .qqbot-extensions/ 下，不隨插件包下發。
安裝與啓用¶
前置：已裝好 dsh，並準備好 QQ 機器人的 AppID/AppSecret（在 https://q.qq.com 註冊獲取）。
README 給出的安裝方式是先打包再從本地 tgz 安裝，不要直接 git clone 後運行 npm run build——這份 fork 直接改編譯產物，dist/ 是隨包提交的，沒有 src/。
git clone https://github.com/RrOrange/dsh-qqbot.git
cd dsh-qqbot
pnpm pack --pack-destination .
$tgz = (Get-ChildItem *.tgz).FullName
npx @deepseek-ai/dsh plugin --profile desktop add $tgz # 桌面客戶端
# npx @deepseek-ai/dsh plugin --profile web add $tgz # dsh web（網頁版）
上面 --profile 要填你實際在用的 profile 名，也就是 %USERPROFILE%\.dsh\profiles\ 下的文件夾名：桌面客戶端一般叫 desktop，dsh web 一般叫 web。裝錯 profile 的表現是重啓後設置裏沒有 QQ 機器人面板。
打包出的 .tgz 文件名由 package.json 裏的 name + version 決定（本項目原名 @zaofan/dsh-qqbot，所以會是 zaofan-dsh-qqbot-1.11.36.tgz 這類），代碼裏用 (Get-ChildItem *.tgz).FullName 取即可，改名不影響安裝。裝完重啓 dsh：跑 dsh web 的重啓那個進程，桌面客戶端退出重開，dist/ 的改動必須重啓才生效。
README 也給出了一條備用路徑：dsh plugin --profile <你的profile> add github:RrOrange/dsh-qqbot。這是作者提供的簡寫形式，本質仍是拉取該倉庫的包，不是把倉庫當源碼構建。
夾帶在安裝命令裏的兩條注意點：
- Windows 上不要把帶空格的目錄直接
add（會報"- isn't supported"），必須先pnpm pack再add生成的 tgz。 - 這個倉庫沒有構建步驟，
npm run build/pnpm build都是無效的（會因缺少src/失敗），打包前不要執行。
典型用法¶
進入面板。 dsh 側打開「設置 → QQ 機器人」。多賬號時每個實例一頁；面板只在 web profile 下出現。
羣裏回覆範圍。 默認只有 @ 機器人 纔回復。想讓機器人讀取全部羣消息，需要去手機 QQ 裏改「機器人可獲取的羣聊消息範圍」，插件側不提供開關。
遠程審批。 Agent 的工具要訪問工作區之外的位置時，dsh 會觸發權限審批；開啓插件的「QQ 遠程審批」後，審批請求會發到發起者的 QQ 會話，直接用 /approve <碼> 放行、/deny <碼> 拒絕，120 秒後自動拒絕。開啓位置在「設置 → QQ 機器人 → ⑤ QQ 遠程審批」，保存即對新請求生效，不需要重啓。
羣管理（可選）。 機器人爲羣管理員時可在「⑥ QQ 羣管理」開啓能力：接收入羣申請、按申請審批、查詢與設置禁言。注意 watchJoinRequests 要在連接期註冊 intents，改動必須重啓宿主，不是 live 熱改。
斜槓命令。 直接在會話裏發 /help 看內置命令列表。
適用場景與注意¶
適合的場景：已經用 dsh 跑 agent，想多一個 QQ 渠道做羣助手或個人機器人的開發者；對流式顯示、羣發穩定性有要求、願意自己維護 fork 的用法。
需要注意的：
- 插件以當前 dsh 進程的權限運行，Agent 能訪問的文件、工具和命令集取決於你給 dsh 配的權限，本插件不會收緊也不會放寬這個邊界。
- 它依賴
@tencent-connect/qqbot-connector與@tencent-connect/qqbot-nodejs，並且聲明瞭對@deepseek-ai/cordis、dsh-agent、dsh-llm、dsh-session、dsh-tools的 peer 依賴；README 聲明要求 dsh>=0.1.5-rc.2。升級 dsh 前先確認這些版本約束。 - 倉庫不含任何機器人憑據、圖庫數據或日誌。AppID/AppSecret 請通過環境變量或 Web 面板注入，不要提交進 git。
- 這是個人修改版，上游是
zaofan-make/dsh-qqbot，再上游是tencent-connect/dsh-qqbot；許可證 MIT，上游版權歸各自作者。安裝前建議通讀dist/裏的實現、docs/中的用戶手冊與擴展契約，以及cordis.patch.yml。 - 倉庫
dist/就是源碼，改動後刷新網頁即可生效（設置面板的client/qqbot-settings.js是單文件手寫 bundle），因此不要用npm run build覆蓋。
結尾¶
這個插件的價值在於把 QQ 渠道里那些容易踩的坑——流式突發、限流退避、分塊重試、事件訂閱——在前面的 fork 裏補齊，並且把配置入口搬進了 dsh 的設置面板，日常使用不需要改配置文件。如果你已經在用 dsh 並覺得 QQ 渠道的缺點正好卡在這幾處，它是值得裝的一個選擇。
- 目錄頁：https://www.skillhub.cn/plugins/RrOrange/dsh-qqbot
- GitHub：https://github.com/RrOrange/dsh-qqbot
- 上游：https://github.com/zaofan-make/dsh-qqbot
