前言¶

用 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