DSH Desktop Agent Bridge：讓外部智能體在 DeepSeek Harness 桌面中協作

前言¶

DeepSeek Harness（DSH）桌面端以“一切皆插件”爲理念，允許開發者擴展交互、工作區與能力。對於多智能體場景，常見做法是啓動多個 headless/web 實例，或通過 HTTP/隧道遠程控制。這會帶來資源開銷、狀態割裂與 UI 聚合難度。

DSH Desktop Agent Bridge 插件提供另一種路徑：將 Codex、Hermes、Grok Bot 等外部 MCP 客戶端與已運行的 DSH 桌面應用綁定。外部 agent 通過本地 stdio 或 HTTPS 與宿主通信，在 DSH 左側工作區下方顯示“Agent 協作”面板，按客戶端身份分組會話，複用 DSH 原生聊天、工具與審批流程，無需啓動新實例。

是什麼¶

• 名稱：DSH Desktop Agent Bridge
• 倉庫：WaldInsel/dsh-desktop-agent-bridge
• 版本：0.1.1（預覽版）
• 宿主：DSH 桌面端 0.2.1-rc.2（已驗證爲 Windows，其他系統未確認兼容）
• 維護者：WaldInsel
• 分類：工作流

插件通過本地 stdio（默認）或 HTTPS 遠程入口，讓外部智能體調用 DSH 會話模型、工具與審批流程。用戶在 DSH 原生界面中查看、插話、接管或停止任務，普通會話需用戶明確交接纔可被外部 agent 使用。每個客戶端擁有獨立令牌與服務端校驗。

能做什麼¶

• 在左側工作區下方顯示「Agent 協作」面板，按外部客戶端身份分組會話。
• 外部 agent 創建任務、讀取結果、繼續會話，並從用戶授權的工作區、能力包與模型中選擇資源。
• 複用 DSH 原生聊天、工具與審批，不另外啓動 headless/web 實例。
• 每個客戶端使用獨立令牌；服務端檢查會話歸屬與資源授權。
• 用戶可在 DSH 直接補充消息、接管、交還或停止任務；普通會話需明確交接。
• 可選將審批與問題轉交到父 Agent 聊天（默認關閉，需在客戶端設置中勾選）。
• 每個客戶端可使用已有能力包，不提供任意安裝 Skill/MCP 或提權接口。

安裝與啓用¶

已驗證的宿主版本爲 DSH 桌面端 0.2.1-rc.2。先完成或停止正在運行的協作任務，在 DSH 左側打開「插件 → 添加插件」，輸入：

https://github.com/WaldInsel/dsh-desktop-agent-bridge

點擊「安裝」，按插件頁提示啓用 dsh-agent-collaboration，然後完全退出並重新打開 DSH。這是 DSH 自帶的插件安裝流程，不需要先運行倉庫的構建或離線安裝腳本。若要固定已審查的代碼，可改用 github:WaldInsel/dsh-desktop-agent-bridge#<完整提交 SHA>；先覈對該提交已推送。

也可在相同輸入框填寫本地源碼目錄的絕對路徑（目錄內須有 package.json、cordis.patch.yml 和 dist/），例如 C:\Projects\dsh-desktop-agent-bridge。本地目錄用於開發或離線安裝；普通使用建議選擇 GitHub 地址。安裝時會執行來自該來源的插件代碼，請先確認來源可信。

首次連接外部 Agent¶

1. 重啓後確認左側出現「Agent 協作」，打開「Agent 協作 → 設置」。
2. 爲 Codex、Hermes 等外部客戶端分別創建身份，選擇可用工作區、已有能力包和模型，保存授權。新身份默認沒有資源權限。
3. 記下各自 client-<id>.json 連接文件的路徑；文件內有令牌，只在本機配置中引用其路徑，不要粘貼到聊天或提交到倉庫。
4. 爲本機 MCP 客戶端配置 stdio 啓動命令。這一外部命令需要系統可用的 Node.js 22+；DSH 插件頁安裝本身由 DSH 管理。

示例 MCP 配置（本機 stdio）：

{
  "mcpServers": {
    "dsh_collaboration": {
      "command": "node",
      "args": [
        "<DSH desktop profile>/node_modules/dsh-agent-collaboration/dist/mcp.mjs",
        "--connection",
        "<協作數據目錄>/client-codex.json"
      ]
    }
  }
}

默認 desktop profile 爲 ~/.dsh/profiles/desktop，協作數據目錄爲 ~/.dsh/agent-collaboration。將佔位符換成絕對路徑，並覈對實際安裝後的包入口是否存在；不要假定每個平臺的物理 pnpm 存儲路徑相同。客戶端配置格式可能不同（例如 Hermes 使用 mcp_servers）。每個客戶端只使用自己的連接文件。

重載 MCP 或新建客戶端會話後，實際調用 dsh_health 和 dsh_catalog。Grok Bot 等雲端客戶端需要獨立認證的 HTTP 適配器和可達 HTTPS 通道，見倉庫文檔中的遠程連接說明；本機連接無需部署公網服務。

分派任務¶

正常流程是 dsh_health → dsh_catalog → dsh_start_task → dsh_wait_task。先讀取授權目錄，再使用目錄中的精確資源標識。

示例請求：

{
  "requestId": "example-task-001",
  "task": "檢查工作區中的 README，給出需要修正的內容。",
  "title": "檢查 README",
  "workspaceId": "<dsh_catalog 返回的 workspaceId>",
  "preset": "<dsh_catalog 返回的 preset id>",
  "selection": {
    "provider": "<目錄中的 provider>",
    "model": "<目錄中的 model>"
  }
}

selection.reasoningEffort 可選，只接受所選模型支持的值。省略 sessionId 創建會話；帶上自己已有的 sessionId 則開始下一輪，沿用該會話的工作區和能力包。同一請求重試應保留 requestId 和全部參數，避免重複執行；新一輪使用新編號。同一規範化項目目錄下的協作任務串行執行。這個隊列不覆蓋 DSH 普通會話或其他程序。

常用工具：

queued、running、waiting_approval、waiting_input 都不是完成。completed 表示 DSH 結束了該輪，調用方仍應讀取結果並覈驗交付物；failed、cancelled、blocked、unknown 不能當作成功。提交結果不確定時先覈查原會話，不自動重發。MCP 返回的文本最多爲本輪結果的末尾 60,000 字符，truncated 表明是否截斷；完整原生會話仍在 DSH 中。

用戶如何介入¶

點擊協作區中的會話即可打開原生聊天，用戶可以直接輸入消息。

撤銷資源授權會阻止後續提交，並在排隊任務執行前重新檢查；它不等同於停止當前執行。需要馬上停止時使用「停止」。

在父 Agent 聊天中審批與回答¶

默認由用戶在 DSH 中處理。只有用戶在對應客戶端設置中勾選「在父 Agent 處審批與回答」並保存後，才允許轉交。

父 Agent 必須先通過 dsh_list_interactions 讀取請求，向用戶展示操作、路徑、原因或完整問題，等待用戶答覆，再調用 dsh_respond_interaction。dsh_send_message 不能批准操作。審批只支持 allowed-once 或 rejected，不支持永久授權。

這是需要信任父 Agent 的聊天轉發功能，不是對真人點擊的密碼學證明。 服務端驗證身份、歸屬、請求有效性和答覆格式，但不能證明 userReply 確實由真人輸入。不要爲會自行代批或編造用戶答覆的客戶端開啓此功能。DSH 原生界面仍可直接處理；兩處同時答覆時，以原生流程先收到的有效答覆爲準。接管、停止、關閉開關或修改授權會使舊請求編號失效。submitted 僅表示提交，隨後仍需讀取任務狀態。網絡中斷不會自動批准，也不會自動重放結果不確定的批准。

驗證範圍與限制¶

此前 0.1.0 優化版已安裝到現有 DSH 桌面端，並完成同會話兩輪對話、接管、交還、停止、父 Agent 問答及一次允許/拒絕審批的真實驗收。GitHub 插件頁安裝路徑需要與功能驗收分別覈對；安裝成功後仍應實際調用 dsh_health、dsh_catalog 並檢查原生會話。

本插件依賴 DSH 0.2.1-rc.2 的會話模型選擇、原生交互和 UI 插槽接口，升級宿主後需要重新驗收。外部客戶端斷開時，DSH 已開始的任務可以繼續；桌面退出或崩潰不保證繼續執行，插件不自動恢復或重發中斷任務。

身份隔離是插件接口的訪問控制，不是同一操作系統用戶下的進程隔離。能讀取連接文件的程序可以取得對應憑據。狀態文件還包含任務文本、會話歸屬及審批迴復記錄，詳見倉庫 SECURITY.md。

更新與卸載¶

從 DSH「插件」頁安裝的版本：先完成或停止協作任務，再從該插件的詳情頁執行「更新」；按頁面提示啓用並重啓 DSH，重新調用 dsh_health、dsh_catalog 覈驗。卸載也在同一插件頁完成。DSH 移除插件包不會刪除獨立的 ~/.dsh/agent-collaboration 狀態目錄、DSH 原生會話和已執行的文件修改；外部客戶端的 MCP 註冊與遠程適配器/隧道須分別清理。

scripts/update-local.mjs 和 scripts/uninstall-local.mjs 只用於先前由 scripts/install-local.mjs 手工維護的安裝，不要拿它們操作插件頁安裝的 bundle。反過來，也不要在手工託管塊仍存在時通過插件頁疊加安裝。

舊安裝遷移¶

1. 完成或停止全部協作任務，完全退出 DSH。把 ~/.dsh/agent-collaboration 複製到只有自己能讀取的備份位置；其中包含明文令牌和任務記錄，不要提交到倉庫。
2. 在本倉庫源碼目錄運行 node scripts/uninstall-local.mjs。腳本會另備份原 profile 配置與舊插件包，移除帶 BEGIN/END dsh-agent-collaboration 標記的舊配置及舊包，保留協作狀態、連接憑據和 DSH 原生會話。記下返回的 backup 路徑；報錯時不要強行刪除配置。
3. 啓動 DSH，按上文從「插件 → 添加插件」安裝；啓用後完全退出並重開。檢查原有客戶端授權及連接文件，再實際調用 dsh_health 和 dsh_catalog。舊 MCP 配置若指向已刪除的文件路徑，改爲新安裝的包入口後重載客戶端。

極早期手工配置若缺少 stateDirectory，卸載腳本會拒絕。確認原數據目錄後，在原 BEGIN/END dsh-agent-collaboration 標記塊的 config 下按原縮進補入真實絕對路徑：

stateDirectory: '<原有協作數據目錄的真實絕對路徑>'

舊默認目錄爲 ~/.dsh/agent-collaboration，寫入 YAML 時須展開爲絕對路徑。保留原狀態和憑據，不要創建空狀態目錄、移動數據或改 --home 繞過檢查，再重新運行卸載。

遷移或舊式離線維護遇到宿主佔用鎖、併發維護鎖或未完成任務時會拒絕操作；確認真實狀態後再處理。舊腳本的 --home、--profile、--state-dir 和 --backup 只用於明確指定舊安裝的位置，不能用來遷移狀態或繞過檢查。出現額外插件行或未知配置時也會保守拒絕，避免誤刪無關配置。

開發與來源¶

項目沿用內部包名 dsh-agent-collaboration、插件 ID agent-collaboration 和現有 MCP 工具名，避免破壞已安裝連接；對外名稱爲 DSH Desktop Agent Bridge，倉庫爲 dsh-desktop-agent-bridge。

參見倉庫文檔中的架構、貢獻指南、更新記錄和發佈流程。本項目並非首個 DSH 控制橋；已有項目與取捨見倉庫中的類似項目說明。感謝 Harness Relay MCP 提供的公開設計參考，許可及複用範圍見 THIRD_PARTY_NOTICES.md。

本項目採用 MIT License。

適用場景與注意¶

適合需要在 DSH 桌面內聚合多個外部智能體、複用原生會話與審批流程的場景。插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。舊安裝遷移需按文檔步驟操作，避免重複加載插件 ID 或誤刪配置。