tiphareth0/dsh-hardssh#dsh-hardssh

已适配 DSH 0.1.5（实测内核 0.1.5-rc.1；本包版本 0.2.2）。在 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——判定命令、接口对照表、可照抄代码与自检清单。

架构

• 单一共享实例：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' 之前不建立基准，避免历史会话被误判为「新建会话」而逐台探测；本地会话不触发任何连接。
• 非交互失败可见：探测失败（网络不可达、认证失败、主机密钥异常、重试耗尽）会弹出「无法连接服务器」对话框并显示具体原因；用户主动取消密码/指纹弹窗不算失败。
• 状态徽章只读：左侧面板每 3 秒读取 /api/dsh-ssh/connections（连接池 live alias 列表）刷新「已连接 / 未连接」徽章，不会主动拨号。

安装

# 已发布 npm（当前 0.2.2）：profile 机制，热插拔，需重启 dsh
dsh plugin --profile <name> add @tiphareth/dsh-hardssh

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

开发

在仓库根目录执行：

pnpm --filter dsh-hardssh typecheck   # 类型检查
pnpm test                             # 默认测试套件（vault 加密用例已移出，约 12s）
pnpm test:vault                       # 只跑 vault 用例（约 21s，scrypt 派生故意慢）
pnpm --filter dsh-hardssh build       # 产出 lib/（构建前先清空，避免陈旧产物）

profile 通过 link: 指向本包源码目录，因此改码后只需重新 build（产出 lib/）并重启 dsh web 即生效；不要把依赖改成 file: 安装副本，那会让 profile 加载一份快照而不是源码。

安全模型

• /api/dsh-ssh/* 与 /api/dsh-hardssh/* 仅限 loopback（含同源校验）。
• 认证材料沿用 ~/.dsh/dsh-ssh.json（0600 / 0700），不新增存储。
• 路径 gate：远程操作 root 必须等于 resolved remoteRoot；相对路径禁止 ..；workspace.fs / workspace.process capability 在解析后的 canonical 路径上再做一次 root 收敛（symlink 逃逸 fail closed）。
• 远程操作消耗真实远程资源：工具描述与宣告段明确「先确认再执行」；remote_search 有深度与条数上限；glob / grep 在 SSH 会话里会被显式拒绝（本机 ripgrep 读不到服务器内容）并指向 remote_search。
• SSH 模式下本机沙箱不对远程执行生效（远程进程无法被本地内核沙箱约束）：门面的 sandboxMode 委托本地后端的真实模式（write / edit 的沙箱升级入口据此注册），而远端世界的升级策略在门面处显式丢弃。
• 凭据默认不落盘；secretStorage: vault 时以 AES-256-GCM + scrypt 加密存储于 ~/.dsh/ssh-secrets/dsh-ssh-vault.json（被 fs seam 拒绝访问），且 DSH_CREDENTIAL_PASSWORD 自动解锁默认关闭（需 vaultAutoUnlock: env）。会话密码按连接存活期复用，连接池回收即失效。