前言¶
DeepSeek Harness（DSH）把智能體開發收進本地 WebUI：工作區、會話、模型與權限都在同一進程裏管理。實際開發時，人往往不在瀏覽器前——例如在通勤、臨時用手機回一條消息，或希望把「審批一次 shell 操作」從桌面挪到即時通訊裏完成。自建 Webhook 或第三方 IM 橋接通常還要處理鑑權、消息格式和與 DSH 會話狀態的同步，維護成本不低。
下面介紹社區插件 dsh-qqbot-bridge（維護者 Jiangsubei，分類：客戶端）。它走 QQ 開放平臺官方 Bot API v2，用 QQ 單聊（C2C） 遠程驅動 DSH 裏已有的工作區與會話，不做羣聊與頻道。插件與 WebUI 同進程運行，列表與新建會話與側邊欄實時對齊。
這是什麼¶
dsh-qqbot-bridge 是 DSH 的 QQ 官方機器人橋接插件：身份依賴 openid 與好友關係，不自研鑑權層。你在 QQ 裏選工作區、選會話或直接發消息，等價於在 WebUI 裏操作對應會話；Agent 的流式正文、Markdown、文件收發，以及審批與提問卡片，按 README 描述轉發到 QQ 側處理。
生態上，DSH 強調「一切皆插件」；插件目錄站 skillhub.cn 爲社區收錄，與 DeepSeek / 幻方無官方從屬關係。源碼與說明見 GitHub：Jiangsubei/dsh-qqbot-bridge，npm 包名 dsh-qqbot-bridge（資料中版本 0.1.3），許可證 MIT。
核心功能¶
會話與工作區¶
- 遠程控制已有會話：
/切換選工作區、/會話選會話，驅動 DSH 裏已存在的會話；WebUI 可見的工作區與會話，QQ 側可列出並接管。 - 全工作區覆蓋：與 WebUI 側邊欄同一套可見性規則（例如隱藏已歸檔、隱藏 subagent 子會話等，以 README 爲準）。
- 首次直髮引導：安裝後不做任何選擇、直接發一條消息 → 在默認工作區
$DSH_HOME/workspace/default自動建會話並處理該消息（不會落到用戶主目錄）。 - 與 WebUI 同進程、狀態實時同步：插件建的會話會出現在 WebUI 對應工作區分組裏。
- 接管策略：優先複用 live agent；遇排他鎖衝突立即如實回執，不搶鎖、不降級。
消息與媒體¶
- 整回合正文流式輸出：每個 step 的正文單獨一條，不拼接、不丟步；可通過配置關閉流式、改用普通 Markdown 消息。
- Markdown 渲染：標題、表格、代碼塊、行內代碼、圖片等按 QQ 原生 Markdown 渲染。
- 文件與圖片：Agent 可調用
send_file/send_image發回；入站附件自動落盤並注入會話（默認目錄與大小上限見配置表）。
審批、提問與命令¶
- 審批與提問可遠程作答：
approval/request、user-questions/request轉發到 QQ，回覆即可決策；超時 300 秒 fail-closed（按拒絕或未作答處理）。 - 命令系統：9 箇中文命令加翻頁子命令，回執純文本；列表 10 條/頁、跨頁連續編號。
- WebUI 設置卡片：連接 / 行爲 / 文件 / 命令四個分區；AppID/Secret 支持從 DSH 憑據庫讀取。
明確不做（README 原文）：羣聊 / 頻道 / 頻道私信、記憶與人格、主動回覆、表情回應、會話歸檔與刪除、自研鑑權。機器人是被動回覆模型：須由用戶側先發起單聊。
安裝與啓用¶
前置條件¶
- 已安裝 DeepSeek Harness：
npm install -g @deepseek-ai/dsh。 - Node.js ≥ 20 與 pnpm。
- QQ 開放平臺機器人（AppID / AppSecret），以及能與該機器人單聊的 QQ 號。
插件聲明依賴：dsh ≥ 0.2.0（見 package.json）。
安裝插件¶
推薦安裝到 DSH 的 web profile（無需編譯，秒級安裝）：
dsh plugin --profile web add dsh-qqbot-bridge
或安裝到全局默認環境：
dsh plugin add dsh-qqbot-bridge
本地開發若從源碼 link，需先 pnpm install 與 pnpm build，再 dsh plugin --profile web add link:.；改 src/ 後必須重新 build，DSH 加載的是 dist/。
配置憑據¶
推薦寫入 DSH 憑據庫（與 DSH 其他密鑰同一處，不落 settings.yaml）：
# ~/.dsh/.credentials.yaml
refs:
QQ_BOT_APP_ID: "<你的 AppID>"
QQ_BOT_SECRET: "<你的 AppSecret>"
也可在 WebUI 設置卡片填寫 app_id / app_secret。解析優先級：環境變量 QQ_BOT_APP_ID / QQ_BOT_SECRET → .credentials.yaml 的 refs → 插件配置（前者優先）。
啓動¶
dsh --profile web
WebUI 默認在 127.0.0.1:3080。啓動後從 QQ 給機器人發一條消息即可建立使用鏈路。
典型用法¶
第一次發消息¶
- 直接發消息：不選工作區與會話，插件自動新建會話（回執只報工作區名），該條消息即會話的第一個 prompt。
- 選工作區：
/切換列出工作區 →/切換 <序號或名字>選中（會清空當前控制目標）。 - 選會話：
/會話列出當前工作區會話 →/會話 <序號>接管；之後普通消息在該會話中發送。
一個 openid 同時只有一個控制目標；換會話用 /會話，換工作區用 /切換。
常用命令（節選）¶
| 命令 | 說明 |
|---|---|
/狀態 |
目標標題、工作區、模型、思考強度、權限檔位、忙閒、上下文用量等 |
/新建 [路徑] |
在當前選中工作區新建會話；受 allow_create_session 約束 |
/模型 [名稱]、/思考 [強度]、/權限 [檔位] |
查看或切換 |
/壓縮 |
壓縮當前會話歷史（等價 DSH /compact） |
/停止 |
中斷當前正在生成的回覆 |
/幫助 |
命令清單 |
列表超過一頁時，頁腳會提示 /下一頁、/上一頁（跨頁連續編號）。
審批：回覆 y（或 README 列出的同義詞）允許本次；n 拒絕；/取消 取消；超時 300 秒按拒絕。
提問：選擇題回覆序號（多選用逗號）；可回覆自定義文本；/跳過、/取消；超時 300 秒視爲未作答。
審批與提問只接管當前正被遠程受控的會話；非受控會話仍由 WebUI 處理。
主要配置項¶
可在 WebUI 設置卡片調整，字段以 README 爲準：
| 參數 | 說明 | 默認值 |
|---|---|---|
default_workspace |
默認工作區；留空則 $DSH_HOME/workspace/default |
'' |
stream_enabled |
是否走 QQ 流式消息 | true |
stream_throttle_ms |
流式分片節流（毫秒） | 1000 |
allow_create_session |
是否允許 QQ 側新建會話（含直髮自動建會話） | true |
media_dir |
入站附件目錄（相對 $DSH_HOME 或絕對路徑） |
qqbot/media |
media_max_bytes |
單文件落盤上限 | 209715200（200 MB） |
reply_max_chars |
命令回執最大字符數 | 1500 |
list_page_size |
列表分頁大小 | 10 |
適用場景與注意¶
適合誰：已在用 DSH WebUI 管理多工作區、多會話，且希望用手機 QQ 單聊做輕量遠程操控、看流式回覆、收文件、回審批/提問的開發者。不適合需要羣聊、頻道或插件主動推送的場景。
安全與權限：插件與當前 dsh 進程同權，可觸達該進程能訪問的工作區與會話；安裝前請閱讀源碼與 MIT 許可證，自行評估 AppSecret 與憑據存放方式。QQ 側僅能控制你賬號綁定的 openid 會話，但仍等同「遠程桌面級」操作 DSH，勿把機器人開放給不可信聯繫人。
範圍邊界：僅單聊 C2C；不支持羣聊/頻道；不做會話歸檔與刪除等 WebUI 部分能力在 QQ 側的復刻。
結尾¶
dsh-qqbot-bridge 把 DSH 已有工作區與會話接到 QQ 官方 Bot API v2 單聊通道上：選工作區、選會話、流式 Markdown、文件與審批/提問遠程作答，並與 WebUI 同進程同步。若你需要在 QQ 裏管 DSH 而不是另搭一套 IM 橋，可按上文命令安裝並配置憑據後，用 dsh --profile web 啓動驗證。
