前言¶

用 Herdr 管遠程開發會話時，常見做法是先開 PowerShell，再輸入別名（例如 workspace-us）才能連上服務器上的 herdr TUI。人還在 DSH 裏看上下文、插件和終端，就要在兩個界面之間來回切。下面介紹 dsh-herdr：把這條連接放進 DSH 左側主邊欄，點開即在內嵌終端裏跑真正的 herdr，並在頁面打開時按配置自動執行連接命令。

這是什麼¶

dsh-herdr 由維護者 kilbertert 發佈，歸類爲 DSH 客戶端插件（platform: web）。它在 DSH 左側邊欄註冊 Herdr 入口，頁面內用 xterm.js 渲染由宿主 PTY 服務拉起的 herdr 進程；不是嵌入 Herdr 官方 Electron GUI，也不是 iframe 嵌 Web 版——本機 herdr 是 Rust TUI，只能走「PTY + 終端模擬器」。

簡述（與倉庫一致）：在側欄嵌入 Herdr 終端，並通過宿主 PTY 自動連接你配置的遠程 Herdr 會話。當前 GitHub 星標爲 0；許可證 MIT；版本 0.1.0；要求 DSH >=0.2.2-rc.1。

核心能力¶

側欄入口與自動連接¶

安裝並重啓 DSH 後，左側主邊欄面板列表會出現 Herdr（與「插件 / 插件市場 / 上下文洞察」等並列）。進入頁面後默認自動執行插件配置中的連接，例如 README 中的示例：

herdr --remote dev-us --session work

這與 PowerShell profile 裏 workspace-us 一類別名指向的命令等價，但命令寫在插件配置裏，可改成任意 remote / session 或完整 command。

宿主與客戶端分工¶

插件自身不創建進程：PTY 由 DSH 終端服務（@deepseek-ai/dsh-api-terminal-controller 客戶端半）管理，與 DSH 內置終端共用 shell 解析、生命週期與斷線重連邏輯。

頁面內操作¶

• 配置了多條連接時，工具條左側下拉框可切換遠程 / 會話；切換會開新終端，舊 PTY 由插件關閉。
• 重連：讓宿主終端服務重試（進程仍在則複用，否則新建 PTY）。
• 重新執行：在終端仍存活時再次發送啓動命令。
• 新終端：換新 contentId 並顯式關掉舊 PTY（避免「視圖脫離 DOM 但進程仍在」的殘留）。
• 切換側欄面板再返回：複用共享視圖，不重複執行啓動命令。

側欄加載時會預熱 xterm 資源；首次連接顯示「正在連接…」而非黑屏。字體優先 --dsw-font-mono，回退等寬棧，避免 TUI 字符間距被拉寬。

安裝與啓用¶

插件已收錄社區目錄 awesome-dsh-plugin，可在 DSH 插件市場搜 Herdr 安裝。社區目錄站點（如 skillhub 上的條目）獨立於 DeepSeek / 幻方，並非官方應用商店。

本機（Windows）開發路徑示例，在 PowerShell 執行：

dsh plugin --profile desktop add D:\workspace\dsh-herdr

若命令不接受本地路徑，可手動：

1. 編輯 profile 的 package.json，在 dsh.profile.bundles 增加：

"dsh-herdr": "file:D:/workspace/dsh-herdr"

2. 在該 profile 目錄執行 pnpm install。

3. 確認 cordis.patch.yml 中 - insert: [{ id: herdr, name: 'dsh-herdr' }] 已合併進 profile 的 patch（dsh plugin add 通常會完成）。

然後完全重啓 DSH（不要只刷新頁面），再打開 Web GUI。

安裝前建議閱讀 GitHub 倉庫 源碼與 MIT 許可證；插件在當前 DSH 進程權限下運行，連接命令會在本機 PTY 中執行。

配置連接列表¶

宿主半將連接列表暴露爲 /herdr/config.json。在 profile 的 cordis.patch.yml 裏爲 dsh-herdr 增加 config:，例如：

- id: herdr
  name: 'dsh-herdr'
  config:
    connections:
      - label: US / work
        remote: dev-us
        session: work
      - label: 本地
        command: herdr
      - label: Dev
        command: herdr --remote dev --session work

規則摘要：

• connections 爲數組；每條可用完整 command，或用 remote / session（宿主拼成 herdr --remote <target> [--session <name>]）。
• label 爲下拉顯示名；缺省用 command。
• 僅一條連接時不顯示下拉框。
• 不配 connections 時可用扁平 remote / session / command / label 配一條；全缺省則默認執行 herdr。

若需指定 xterm 包路徑（找不到 @xterm/xterm 時），可在配置中設置 xtermDir / fitDir 絕對路徑，見 README「xterm 資源從哪來」一節。

典型用法¶

1. 完成安裝並重啓 DSH。
2. 左側點 Herdr，等待自動連上默認連接（如 herdr --remote dev-us --session work）。
3. 若配置了多條連接，用下拉框切換；需要時用 重連 / 重新執行 / 新終端。
4. 出現連接失敗時，在瀏覽器 localStorage 查看鍵 dsh-herdr:state 的診斷 JSON（含 phase、error、command 等），便於對照 README 故障排查表。

適用場景與注意¶

適合：已在 DSH Web profile 中使用 Herdr 遠程會話，希望在同一 GUI 側欄裏完成「打開 → 自動連遠程 herdr」，減少與外部 PowerShell 的切換。

注意：

• 依賴 ctx.webTerminals 與 ctx.slots；版本過舊或 profile 不含 Web 終端服務時側欄無入口或報「沒有提供宿主終端服務」。
• /herdr 僅暴露白名單靜態文件，並經 ctx.connection.requestRejection 校驗；不讀寫憑據，不保存 herdr 會話內容。
• 遇 missingTerminal 等綁定殘留，插件會嘗試 service.close() 後重新分配 PTY，詳見 README 故障排查。

結尾¶

經過上面的步驟，DSH 裏多了一頁專用的 Herdr 終端：配置即連接列表，側欄一點即可自動執行 herdr 遠程會話命令，並與 DSH 內置 PTY 棧保持一致。

• 目錄頁：skillhub — kilbertert/dsh-herdr
• 源碼與文檔：github.com/kilbertert/dsh-herdr