前言¶
DeepSeek Harness（DSH）桌面版的主界面適合人手點選建會話、看側欄滾動。想在終端裏跑的 Claude Code、自建腳本或 CI 助手去「遙控」同一套宿主時，常見做法是 dsh headless 或碰宿主自帶的 Web 口。前者建的會話只落在 ~/.dsh/sessions/，不進 workspace.json，GUI 側欄看不到；後者對沒有 GUI 憑據的請求一律 401，外部進程接不上。
dsh-external-bridge 是社區維護的 DSH 客戶端側 Host 插件（維護者 Jason25417，MIT 許可）。它在 loopback 上單獨起一個 HTTP 服務，用 Bearer token 鑑權，調用宿主 sessionController.create 等能力，建出來的是和工作區側欄裏手動新建無區別的真會話。下文按定位、能力、安裝、調用順序說明。
這是什麼¶
插件全名 dsh-external-bridge（npm 包名同稱，當前版本 0.2.1）。運行時不改 DSH 本體、不改 @yunmiao/studymate，僅在 ~/.dsh/profiles/desktop/plugins/dsh-external-bridge/ 增加插件目錄。
監聽地址固定爲 127.0.0.1:39217。端口被佔用則啓動失敗並在日誌說明，不會靜默換端口。依賴 Node >= 22，宿主 DSH 0.2.x（package.json 要求 dsh >= 0.2.1-rc.0 < 0.3.0）。
與宿主自帶 HTTP 口的區別¶
桌面宿主另有 Web 口（例如 127.0.0.1:50186、*:3081），外部進程沒有 GUI 客戶端憑據時會一直收到 401 unauthorized。本插件不掛 connection.fetch，用 node:http 自建 loopback 監聽，啓動時生成 32 字節隨機 token（base64url），寫入 ~/.dsh/secrets/external-bridge.token（目錄 0700、文件 0600）。每個請求須帶 Authorization: Bearer <token>，否則 401。插件 dispose 時關閉監聽。
核心功能¶
會話與可見性¶
- POST /sessions：創建會話；可選
agentPreset、provider/model/reasoningEffort、firstPrompt。workspaceId與cwd二選一（推薦已註冊的workspaceId，保證側欄可見）。 - POST /sessions/:id/prompt：投遞用戶消息；
mode爲queue（默認）或steer。 - GET /sessions/:id：讀
state（running|idle|error）、lastAssistantText、turnCount、必要時error。 - **GET /sessions/:id/wait?timeoutMs=
：長輪詢等回覆；默認 30 秒，timeoutMs` 上限 240 秒。 - GET /sessions：按工作區列出會話 id。
- GET /health：返回
version、presets、models（拿不到則爲null）。
建會話走宿主 sessionController.create；指定模型時插件在 create 之後調用 selectModel，並在成功後恢復用戶原先的全局默認模型，避免悄悄改掉 GUI 裏的默認選項。
若 cwd 不屬於任何已註冊工作區，仍會建會話，但響應可能帶 warning：會話存在，側欄可能不顯示。模型不可用時可能返回錯誤，但仍可能攜帶 sessionId 供調用方接續處理。
所有成功/失敗響應均爲 JSON；失敗形如 { "ok": false, "error": { "code", "message" } }。請求體上限 1 MiB。
安裝與啓用¶
插件已打包爲 DSH bundle（package.json 的 dsh.bundle）。推薦用官方插件命令安裝，然後完全退出並重開 DSH Desktop（Host 插件只在啓動時掛載）：
dsh plugin --profile desktop add dsh-external-bridge
安裝來源可以是 npm 包、tarball 或本地路徑。源碼 checkout 場景可在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加 external-bridge 的 file:// Host 條目；回滾時刪除對應段落並重開桌面宿主。細節見倉庫 README「掛載」一節。
驗證服務是否起來¶
橋啓動後，可用 token 文件探活：
test -f ~/.dsh/secrets/external-bridge.token && ls -l ~/.dsh/secrets/external-bridge.token
TOKEN=$(cat ~/.dsh/secrets/external-bridge.token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:39217/health | jq
若返回 "ok": true 且帶有 version、presets、models 等字段，說明監聽正常。排錯可在宿主日誌中搜索 [dsh-external-bridge] 或 external bridge；端口衝突可用 lsof -nP -iTCP:39217 -sTCP:LISTEN 檢查。
典型調用流程¶
下面是一條可復現的最小鏈路：先健康檢查，再建會話並帶首條 prompt，最後長輪詢取助手正文。
1、確認 token 與 health（見上一節）。
2、創建會話（示例 JSON 字段以你環境 /health 返回的 preset、model 爲準）：
curl -s -X POST http://127.0.0.1:39217/sessions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workspaceId": "ws_xxx",
"agentPreset": "learning",
"provider": "opencode-go-4",
"model": "deepseek-v4-pro",
"reasoningEffort": "max",
"firstPrompt": "只回復兩個字：收到"
}' | jq
成功時得到 sessionId 等字段。
3、若需追加消息：
curl -s -X POST "http://127.0.0.1:39217/sessions/<sessionId>/prompt" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "繼續", "mode": "queue"}' | jq
4、等待或輪詢狀態：
curl -s -H "Authorization: Bearer $TOKEN" \
"http://127.0.0.1:39217/sessions/<sessionId>/wait?timeoutMs=30000" | jq
lastAssistantText 爲最後一條帶正文的助手回覆（工具調用行不計入）。空閒或出錯會立即返回；超時則 state 仍爲 running 且 timedOut: true。
適用場景與注意¶
適合誰：需要在同一臺機器上用腳本或外部 Agent 編排 DSH，又希望會話出現在桌面工作區側欄、消息與 GUI 手動操作一致可見的開發者。
安全與權限：服務只綁定 loopback，token 存於本機 ~/.dsh/secrets/。插件以當前 DSH 桌面進程權限運行；安裝前應自行審閱 GitHub 源碼 與 MIT 許可證。
生態說明：DSH 奉行「一切皆插件」；SkillHub 目錄頁 爲社區收錄，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-external-bridge 補上的是「外部自動化 + 桌面真會話」之間的缺口：本機 HTTP、獨立 token、標準 REST 式會話生命週期。需要細節、錯誤碼錶與模型/狀態讀取實現說明時，以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/Jason25417/dsh-external-bridge
- GitHub：https://github.com/Jason25417/dsh-external-bridge
