@tiphareth/dsh-hardssh

dsh plugin --profile web add @tiphareth/dsh-hardssh

dsh-hardssh — SSH 远程工作区 + SSH 运维插件

已适配 DSH 0.1.5 ~ 0.2.1，含官方桌面版（Electron）（0.1.x 兼容矩阵四条线全绿：0.1.5-rc.1、0.1.5-rc.2、0.1.6-alpha.1、0.1.6-alpha.2；0.2.x 线已在桌面版 0.2.1-rc.5 / 0.2.0-rc.2 上实测宿主侧与工作区注册；peer 范围 >=0.1.5-rc.1 <0.1.7 || >=0.1.6-alpha.1，对 0.2.x 不设上限；本包版本 0.2.8）。客户端 Windows / Linux / macOS 均可用（CI 在 Linux runner 上跑 Node 22.19 与 24 的完整套件；客户端路径、锚点与远端根之间的映射有专门的跨平台回归用例）。~/.ssh/config 会被实时读取（无需导入，插件从不改写该文件）；认证顺序固定为 key → agent → password。在 DSH Web GUI 中提供两块能力（单包单引擎）：

1. SSH 运维：右侧栏「SSH」Tab（从右侧栏标签条的「+」或右侧栏引导页入口打开）→ Web 终端（xterm + WebSocket PTY）、文件上传下载、本地端口转发隧道、当前服务器的远端命令；ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster 六个 Agent 工具；主机配置存 ~/.dsh/dsh-ssh.json。

2. SSH 工作区：左侧侧栏的全局入口行 → 中央面板管理服务器与工作区（增删改查 / ~/.ssh/config 导入）；绑定后本地 harness 的 fs/subprocess 经接缝门面透明路由到远程主机执行（read/write/edit/bash 在绑定会话中即远程操作）；remote_* 三个 Agent 工具（remote_ls / remote_search / remote_status）用于显式操作远端工作区。

核心优势

• 对插件零改动：cordis.patch.yml 禁用部署自带的 fs-sandbox / subprocess 行，由本包提供路由门面。任何走标准 ctx.fs / ctx.subprocess 的插件与标准工具，在 SSH 工作区会话里自动运行在远端。
• 通用工作区底座：WorkspaceRecord / Provider / Connection / 能力契约 + Registry / Ledger / Router，与 SSH 解耦。SSH 只是一个 provider（如 ssh、local），可继续接 docker / wsl / 云 devbox，上层插件与 UI 不改；单一运行时，全链路读同一个台账。
• 少数插件只需改几处接口：给 agent 的执行手册见 [SKILLS.md](./SKILLS.md)——判定命令、接口对照表、可照抄代码与自检清单。

架构

• 单一共享实例：HostStore + SshEngine（ssh2 连接池）在 src/index.ts 创建一次，SSH 运维与 SSH 工作区共用同一引擎 —— 配置变更（PATCH/DELETE）同时失效所有连接，无双池问题。
• 接缝切换：cordis.patch.yml 禁用部署自带的 fs-sandbox / subprocess 行，由 dsh-hardssh/fs、dsh-hardssh/subprocess 提供 provider 路由门面（本地 = 沙箱化原实现；远端 = 该 workspace 连接上的 workspace.fs / workspace.process capability）。
• REST：/api/dsh-ssh（运维路由，loopback-only）+ /api/dsh-hardssh（工作区路由，loopback-only）。
• 工作区核心服务：ctx.workspaceCore（通用 WorkspaceCore：台账 + provider 路由 + capability 连接）是唯一的工作区运行时；ctx.hardsshCore 只保留 hosts + engine 供 SSH 专用集成消费（如四列 IDE 形态的 dsh-workbench-tiphareth）。
• 公开入口：@tiphareth/dsh-hardssh/base（通用底座实现）、@tiphareth/dsh-hardssh/workspace（平台无关类型面）。

界面入口（全部走标准插件扩展点）

插件不使用任何 DOM 注入；两个界面都是内核公开的槽位注册：

界面 · 入口 · 槽位

SSH 工作区管理（服务器 + 工作区增删改查，服务器行带已连接/未连接徽章） · 左侧侧栏「新会话」与「工作区」之间的全局入口行 → 中央面板 · sidebar.panellist（行）+ main（面板，key 同为 dsh-hardssh-workspaces）

SSH 运维（终端 / 传输 / 隧道 / 当前服务器命令） · 右侧栏标签条的「+」或右侧栏引导页入口 · ctx.sidebarRightTabs.register（类型）+ sidebar.right.pane.tab（正文）+ sidebar.right.pane.tab.title（标签文字）

右侧栏 Tab 是 page 类型（不声明 patterns），只按 kind 打开，由用户从右侧栏自己的入口打开；插件不会强制展开右侧栏。右侧栏 Tab 实例是每会话独立的（内核的会话作用域语义），因此切换会话后需要重新打开该 Tab。

会话绑定语义（操作台不选服务器）

• 操作台的 SSH 目标由当前会话的 cwd 决定：最长匹配的 SSH 工作区锚点胜出，取该工作区的 alias 与 remoteRoot。终端 / 传输 / 隧道 / 命令四个子页都强制使用它，不提供服务器下拉框。
• 会话在本地工作区（或未绑定任何 SSH 工作区）时，操作台不挂载任何操作组件，改为渲染模糊蒙版并提示「SSH 操作台仅适用于 SSH 工作区会话」。
• 切换会话时操作台随 Session → alias 自动切换，并重置子页状态。
• 数据源是公开的 ctx.sessions.list（current + byId[id].cwd）+ WorkspaceManager 快照，两者都可订阅，不存在第二份工作区句柄。

连接行为

• 启动/刷新只连接当前会话的服务器：连接闸门在 ctx.sessions.list 的 phase === 'ready' 之前不建立基准，避免历史会话被误判为「新建会话」而逐台探测；本地会话不触发任何连接。
• 非交互失败可见：探测失败（网络不可达、认证失败、主机密钥异常、重试耗尽）会弹出「无法连接服务器」对话框并显示具体原因；用户主动取消密码/指纹弹窗不算失败。
• 认证被拒立刻重弹并给出原因：凭据已输入后服务器仍拒绝时，重新打开密码对话框并携带具体 SSH 错误，而不是落到非交互失败对话框。
• 连接中可见：连接期间左侧工作区徽章显示旋转指示器，状态翻转原地替换。
• 工作区文件面板显示远端地址：面板根锚在本机（会话 cwd），内容已经是远端、地址与面包屑也重写为远端根，避免「地址是本机、内容是服务器」的错觉。
• 终端 shell 解析已从根上兜底（0.2.8）：DSH 终端控制器先 resolveExecutable() 再 spawn；Windows Store 版 PowerShell 的 App Execution Alias 会让这一步直接抛 is not an executable file。插件的解析层会把 WindowsApps 别名换成真实可执行文件，解析失败且命令是 shell 名时回退 Program Files\PowerShell\7\pwsh.exe → System32\WindowsPowerShell\v1.0\powershell.exe → ComSpec；非 shell 命令不受影响。
• 终端诊断日志：~/.dsh/dsh-hardssh-terminal.log 记录每次侧边栏终端 spawn 的 cwd、清洗前后 argv 与 local/remote 路由，便于定位终端问题（只记这些，不记环境变量与凭据）。
• 状态徽章只读：左侧面板每 3 秒读取 /api/dsh-ssh/connections（连接池 live alias 列表）刷新「已连接 / 未连接」徽章，不会主动拨号。

主机命令守卫（可选，默认不拦截）

面向「登录节点禁止直接计算」这类主机策略：默认什么都不拦，只有给某台主机配了 commandPolicy 才生效。配置写在 ~/.dsh/dsh-ssh.json 的单台主机条目里，也可以在「新建/编辑服务器」对话框里填：

{
  "alias": "login-node",
  "host": "192.0.2.10",
  "user": "alice",
  "commandPolicy": {
    "deny": ["(^|[;&|(])\\s*(?:/?[^ /]+/){0,3}(python[0-9.]*|Rscript|R|make|gcc|g\\+\\+)(\\s|$)"],
    "denyCommands": ["python", "python3", "Rscript", "R", "matlab", "julia", "make", "cmake", "gcc", "g++"],
    "allowCommands": [],
    "hint": "登录节点不可直接计算，请用 srun/sbatch 提交到计算节点。"
  }
}

• deny：每行一个正则，匹配整条命令文本（命令位置锚定，srun -p gpu python x.py 这类提交命令不会误伤）；
• denyCommands：命令名清单，匹配前先「解包」——跳过 FOO=bar、剥掉 sudo/env/time/nohup/bash -c "…" 等包装、去路径取 basename，因此 bash -c 'python x.py'、sudo python3 …、/usr/bin/python3 … 都能抓到；
• allowCommands：上述名字的例外（豁免优先）；
• hint：命中时附在报错里的可操作提示；
• 拦截发生在两层：工具层 ctx.tools.guard()（ssh_exec / ssh_cluster / bash）与 seam 层（任何经 ctx.subprocess 的远端 spawn，含第三方插件直连）；
• 这是护栏而非沙箱：$(…)、base64、脚本内部再调用计算命令都能绕过；真正的硬约束要在服务器侧（Slurm 限额、pam_slurm_adopt、PATH shim）。另外 bash 本身不要列进 denyCommands——它被当作包装词剥壳，列为禁止名会连 bash 工具自身的 spawn 一起拦掉。

原生工具在绑定会话里的行为

工具 · 行为

read / write / edit / bash / pwsh(本机) · 经 ctx.fs / ctx.subprocess 路由：SSH 会话里就是远端操作

glob / grep · 走搜索桥：宿主机有 ripgrep 就发同一条 argv，否则由搜索阶梯（rg → POSIX 工具 → SFTP 遍历）代答并投影成 rg 的输出形状；不再「显式拒绝」

remote_ls / remote_search / remote_status · 显式远程运维工具（列目录、正则/字面量检索、绑定状态）

安装

# 已发布 npm（latest = 0.2.7；0.2.8 为本轮修复版本，发布后即为 latest）
dsh plugin --profile web add @tiphareth/dsh-hardssh

# 需要固定版本时
dsh plugin --profile web add @tiphareth/dsh-hardssh@0.2.8

# 开发/迭代：源码链接（改码重建 lib/ 后重启即生效）
dsh plugin --profile web add link:<repo>/packages/dsh-hardssh

桌面版（Electron）dsh：可以正常加载本插件，但它的 desktop profile 由应用独占管理——

普通 CLI 执行 dsh plugin --profile desktop … 会被拒绝

（error: profile "desktop" is managed exclusively by the Electron application）。

请改用桌面版自带的 CLI（菜单栏「Manage dsh command」，或直接调用

`<安装目录>\resources\runtime\c

…(truncated)