# 内置 SSH 与远程文件夹实施方案(审阅稿) 日期:2026-11-03 仓库:`dsh-workspace-groups`(`workspace-groups-local@1.3.0`) 目标:不再把 `@zhangfengshun/dsh-remote-ssh` 作为运行依赖,由本插件自己提供 SSH 连接、远程目录、远程文件夹工作区和文件/终端能力。 --- ## 0. 结论先行 1. **传输层用系统 OpenSSH,不自写 SSH 协议。** 继续用 `ssh` / `sftp` 这套已验证的客户端,保留 `~/.ssh/config`、ProxyJump、known_hosts、密钥代理、老 HPC 算法和 2FA 兼容性;插件自己负责连接管理、文件操作、镜像工作区和 UI。这样“内置”指**不依赖 Remote-SSH 插件**,不是“不依赖系统 ssh”。 2. **远程文件夹仍然使用 mirror-backed 原生 Workspace。** 浏览器只看到本地镜像路径,Host 用 `.workspace-groups-remote.json` 把它映射到远端;原生 Workspace 身份和已有会话不重建。 3. **先做可替换的最小闭环,再补完整工具面。** 先完成“连接配置 → 远程选目录 → 建远程文件夹 → 重启后仍可用 → 删除/迁移”,再接文件写回、终端、exec、glob/grep、同步。不要一开始就重写 13 个工具。 > 关键限制先说清楚:DSH 的通用 bash/终端执行仍以本地 Workspace 的 `cwd` 为准。内置 SSH 能做到“远程文件夹 + 显式远程工具 + 远程终端”,**不能仅靠插件让 Agent 的所有 bash 命令在 HPC 上执行**;后者需要 DSH 平台提供远程执行层。若你的预期是后者,这份方案的边界需要先扩大。 --- ## 1. 目标与非目标 ### 1.1 目标 - 卸载 `@zhangfengshun/dsh-remote-ssh` 后,分组、文件夹、远程目录选择、远程工作区创建仍可用。 - Host 端持有 SSH 配置、密钥路径、连接池、超时/重连、SFTP/命令执行;浏览器端不接触私钥内容和密码。 - 远程目录选择、远程文件夹创建、删除、重新打开、离线提示完整。 - 远程写入失败**硬失败**,绝不静默写本地镜像;读缓存明确标记“离线副本”。 - 兼容现有 `~/.dsh/remote-workspaces` 镜像和旧 Remote-SSH 记录,可回滚。 - Windows 本地 + Linux/macOS 远程;Unicode、空格、单引号路径可用。 ### 1.2 非目标(v1 不做) - 不做远程 Windows 主机(Remote-SSH 当前也主要按 POSIX 远程设计)。 - 不把 SSH 私钥、密码、passphrase 写入浏览器 bundle、URL、日志、marker 或普通配置文件。 - 不做跨设备云同步;镜像仍是本机缓存。 - 不在本方案里顺手修“本地/云端会话拆分”和“图标分类”,它们独立跟踪;但会预留 project identity 接口,避免再次写死。 --- ## 2. 现状与约束 ### 2.1 当前调用链 ```text GroupsBrowser / FoldersDialog -> src/client/folder-directory.ts POST /remote-ssh/api/{listProfiles,listDir,remoteExec,createRemoteWorkspace,listWorkspaces,mkdir} -> @zhangfengshun/dsh-remote-ssh (Host) OpenSSH CLI + 连接池 + 镜像 + workspaceRegistry -> ctx.workspaceRegistry.create(mirrorDir, title) ``` 唯一远程 seam 是 `src/client/folder-directory.ts:30-53`;`remoteExec("cd ... && pwd -P")` 在 `:141`。当前 Host 只 `inject = ['webServer']`(`src/index.ts:57-61`),路由在 `:122-348`。 ### 2.2 关键事实 - Remote-SSH 2.4.41 已安装,MIT,只发布 `lib/index.js` / `lib/client.js`,**没有源码**;不能可靠地 fork/vendor 维护。 - 它用 `ctx.subprocess`、`ctx.workspaceRegistry`,底层是系统 `ssh`,不是 ssh2。 - 远程工作区本质是 `workspaceRegistry.create(mirrorDir, title)` 注册的本地镜像目录;会话 `cwd` 指向镜像。 - 现有镜像 marker 是 `.remote-ssh.json`,里面含 `keyPath`;新方案不能继续把密钥路径写进工作区可见文件。 - 现有测试:`tests/folders.test.ts`、`tests/tree.test.ts`、`tests/core.test.ts`、`tools/verify-folders.mjs`、`tools/verify-folder-directory.mjs`(mock)、`tools/verify-directory-flow.mjs`、`scripts/verify-groups.mjs`(CDP 真机)。 - 构建:Host ESM + client CJS(`tsdown.config.ts:82-136`),浏览器包不能 import Node builtins。 --- ## 3. 传输层选型 | 维度 | 系统 OpenSSH(推荐) | ssh2 / node-ssh | |---|---|---| | 配置兼容 | 原生读 `~/.ssh/config`、ProxyJump、Match、Include | 要自己解析,容易漏 | | 认证 | key、agent、password、keyboard-interactive/2FA 都由 ssh 处理 | 要自己实现 askpass/2FA 流程 | | 老 HPC 算法 | 跟随系统 ssh,兼容性最好 | 受库的算法列表限制 | | 文件操作 | 需要 shell/SFTP 组合,需严格转义 | SFTP 原生、结构化、最稳 | | 依赖 | 系统需有 `ssh`(Windows 可选功能) | 纯 JS,但 ssh2 有可选原生依赖 | | 安全边界 | 复用成熟客户端;参数数组调用,不拼 shell | 自己处理 host key、超时、通道,代码面更大 | | 迁移风险 | 与现有 Remote-SSH 行为最接近 | 需重新验证跳板、密码、算法、终端 | **决定:v1 用系统 OpenSSH。** 理由:当前插件的行为基线就是 OpenSSH;用户环境已能连 HPC;换成 ssh2 会把“替换插件”变成“重写 SSH 客户端”,风险和工作量都更高。 本机已确认 `C:\Windows\System32\OpenSSH\ssh.exe` 与 `sftp.exe` 存在(PATH 中另有 OpenSSH_10.5p1),v1 不需要额外安装依赖。 保留后路:`SshTransport` 做成接口;如果未来要求“零系统依赖”,再加 `ssh2` 实现,不动上层。 --- ## 4. 目标架构 ```text Browser (React) ├─ SSH 设置 / 连接测试 / 远程目录选择器 ├─ 只知道 profileId、displayName、目录项;不知道 keyPath/password └─ fetch /workspace-groups/ssh/* │ Host (Node ESM) ├─ SshProfileStore ~/.dsh/workspace-groups/ssh-profiles.json (0600) ├─ SecretVault 仅内存;密码/passphrase,重启即清 ├─ SshTransport ctx.subprocess + ssh/sftp;超时、取消、重连、并发上限 ├─ RemoteFs stat/list/read/write/mkdir/rename/delete/glob/grep ├─ RemoteWorkspaceService 镜像目录 + marker + workspaceRegistry.create/delete ├─ Migrator 旧 Remote-SSH 记录/镜像一次性导入 └─ RemoteTools 远程 exec/read/write/...(Host 工具,不经浏览器) │ ctx.workspaceRegistry.create(mirrorDir, title) │ ~/.dsh/remote-workspaces// ← 原生 Workspace 的 cwd ``` ### 4.1 新增/修改文件 | 文件 | 作用 | |---|---| | `src/host-ssh/profiles.ts` | profile CRUD、校验、0600 原子写、导入 `~/.ssh/config` | | `src/host-ssh/transport.ts` | 连接测试、命令执行、超时/取消、并发池、host key 策略 | | `src/host-ssh/files.ts` | 远程文件操作、路径规范化、原子写、大小上限 | | `src/host-ssh/workspaces.ts` | 镜像、marker、workspaceRegistry 注册/清理、幂等 | | `src/host-ssh/migrate.ts` | 旧记录/旧镜像导入、双读、回滚 | | `src/host-ssh/tools.ts` | Host 侧 `remote_*` 工具注册(M2 起) | | `src/client/ssh-settings.tsx` | 连接管理 UI;密码只提交到 Host,不回显 | | `src/client/remote-picker.tsx` | 远程目录浏览;复用现有目录选择器样式 | | `src/client/folder-directory.ts` | 把 `/remote-ssh/api/*` 换成 `/workspace-groups/ssh/*`;保留六种操作 DTO,删掉 generic `remoteExec` | | `src/index.ts` | 注入 `workspaceRegistry`;注册 SSH 路由;统一错误 envelope | | `src/host-folders.ts` | remote marker 只做 fail-closed;新增我们自己的 marker 校验 | | `src/client/folders-persist.ts` | 创建失败回滚,保证 members round-trip | | `cordis.patch.yml` | 如接终端 wrapper,补 terminal-controller 补丁;M2 再做 | ### 4.2 Host 路由(示意) ```text GET /workspace-groups/ssh/profiles POST /workspace-groups/ssh/profiles PATCH /workspace-groups/ssh/profiles/:id DELETE /workspace-groups/ssh/profiles/:id POST /workspace-groups/ssh/profiles/:id/test POST /workspace-groups/ssh/profiles/:id/list POST /workspace-groups/ssh/profiles/:id/mkdir POST /workspace-groups/ssh/workspaces GET /workspace-groups/ssh/workspaces DELETE /workspace-groups/ssh/workspaces/:recordId POST /workspace-groups/ssh/workspaces/:recordId/sync ``` 响应统一 `{ ok: true, value }` / `{ ok: false, error: { code, message } }`;沿用当前 `HttpError` 和请求体上限,不引入新的网络暴露面。 --- ## 5. 数据模型 ### 5.1 Profile ```ts type SshAuth = | { kind: 'key'; keyPath: string } // 仅 Host 可读;浏览器只看到 basename | { kind: 'agent' } | { kind: 'password' } // 密码不落盘,仅 SecretVault interface SshProfile { id: string // crypto.randomUUID() name: string host: string port: number // 默认 22 user: string auth: SshAuth proxyJump?: string remoteRoot: string // 默认 '~';文件操作必须落在此根下 connectTimeoutMs: number // 默认 15000 keepaliveSeconds: number // 默认 30 } ``` - 存储:`~/.dsh/workspace-groups/ssh-profiles.json`,权限 `0600`,原子 rename。 - 不存密码/passphrase;`SecretVault` 以 `profileId` 为键存在 Host 内存,重启清空。 - 导入 `~/.ssh/config` 只复制 host/user/port/keyPath/proxyJump,不复制密码。 ### 5.2 远程工作区记录 ```ts interface RemoteWorkspaceRecord { id: string // 稳定 recordId,不用时间戳拼 profileId: string title: string remotePath: string // 用户看到的绝对路径 mirrorPath: string // 本地绝对路径 workspaceId: string // 原生 workspaceRegistry id createdAt: string schemaVersion: 1 } ``` Marker:`/.workspace-groups-remote.json` ```json {"schemaVersion":1,"recordId":"...","profileId":"...","remotePath":"/home/u/proj"} ``` **不写** host/user/keyPath/proxyJump;这些只在 Host profile store。旧 `.remote-ssh.json` 只读,不修改。 ### 5.3 FolderMember 沿用 `src/core/folders.ts:20-68` 的 `FolderMember`,不新增必填字段;可选加: ```ts remoteRecordId?: string // 只做诊断/迁移,不参与归属 ``` `workspaceId` 仍是唯一权威;`path` 仍是镜像路径。不要用标题或 host 反推归属。 --- ## 6. 安全不变量 | # | 不变量 | 验证 | |---|---|---| | S1 | 私钥内容永不进入 Host 响应、浏览器 bundle、日志、marker | 构建产物 grep `BEGIN OPENSSH PRIVATE KEY`;路由快照断言无 keyPath | | S2 | keyPath 只在 Host profile store;浏览器只拿 basename | API 单测 | | S3 | password/passphrase 只存内存,响应不回显,日志脱敏 | 重启后连接需重输;日志 grep | | S4 | host key 默认 `StrictHostKeyChecking=yes`,使用应用私有 known_hosts;首次连接显示指纹并要求确认 | 中间人测试:换 key 必须失败 | | S5 | 远程路径必须落在 profile `remoteRoot` 内,`realpath -m` 后校验;拒绝 `..`、NUL、换行 | 路径穿越测试 | | S6 | 所有进程用 argv 数组调用,禁止 `shell: true`;远程命令参数用 POSIX 单引号 + base64 | 注入测试(`'`, `$(...)`, 空格, 中文) | | S7 | 写文件先写同目录临时文件,再 `mv` 原子替换;失败保留原文件 | 断连/磁盘满测试 | | S8 | 远程写失败绝不回落本地镜像;读缓存只读并标 `offline` | 断网测试:镜像 mtime 不变,UI 明确报错 | | S9 | 单命令/单文件有超时与大小上限;可取消;输出截断 | 大文件、`sleep 999`、`kill` | | S10 | 删除远程文件夹只删本地记录/镜像,**不删远端目录**;删除远端目录需单独确认 | UI 文案 + 测试 | 补充: - 使用应用私有 known_hosts:`~/.dsh/workspace-groups/known_hosts`,提供“从 `~/.ssh/known_hosts` 导入”按钮;不静默接受新主机。 - 密码认证只在回环/受信 Host 上可用;若 GUI 通过局域网访问,提示改用密钥。 - 命令输出做 secret redaction;`ssh -v` 诊断只保留认证相关行,其他丢弃。 --- ## 7. 远程工作区生命周期 ### 7.1 创建 1. 校验 profile + `remotePath`,`cd && pwd -P` 解析绝对路径;不存在则按用户选择 `mkdir -p`。 2. 按 `profileId + remotePath` 查重;已存在则复用 record,不新建。 3. 生成稳定 `recordId`;镜像目录沿用 `~/.dsh/remote-workspaces/`。 4. 创建镜像目录,写 marker(不含密钥信息),写一份只读 `README.md` 说明“这是远程镜像,写操作请走远程工具”。 5. `ctx.workspaceRegistry.create(mirrorPath, title)`;若已有同路径原生 Workspace,复用其 id 并 `setTitle`。 6. 保存 record;返回 `{mirrorPath, workspaceId, recordId, remotePath, profileId, reused}`。 7. 任一步失败:回滚已创建的原生 Workspace / 镜像;**不写 folders overlay**。客户端只有在拿到完整返回后才 PUT members。 ### 7.2 删除 - 从 folders overlay 移除 member; - 若无其他 member 引用同一 `workspaceId`,删除原生 Workspace 记录和镜像; - **不执行远端 `rm -rf`**;UI 明确写“只移除本地映射,不会删除服务器文件”。 ### 7.3 重开/离线 - 启动时只读 marker + record,不自动连 SSH;目录行显示“远程(离线)”状态。 - 用户点开或执行操作时才连接;失败显示具体阶段(DNS/TCP/认证/host key/权限),不把本地镜像伪装成远端成功。 --- ## 8. 从 Remote-SSH 迁移 原则:**先双读,后切换,可回滚;不重建原生 Workspace,不丢已有会话。** 1. 一次性读取旧插件 `listWorkspaces`(若仍安装)或扫描 `~/.dsh/remote-workspaces/*/.remote-ssh.json`。 2. 按 `host + user + port + keyPath basename` 匹配/创建新 profile;密码不迁移,要求重输。 3. 复用旧 `mirrorPath` 和 `shellWorkspaceId`(旧记录里有);生成我们的 record + marker。 4. 迁移 `FolderMember` 时保留 `workspaceId`,只补 `remoteRecordId`;不按标题合并。 5. 旧插件仍保留安装但禁用;新插件通过 feature flag 接管。验收通过后再卸载旧插件。 6. 回滚:保留旧 `.remote-ssh.json` 和旧设置不动;关闭新 backend 即可回到旧插件。 --- ## 9. 会话拆分问题(独立小任务) 用户看到的“同一项目在本地文件夹和云端文件夹分成两个会话列表”,根因大概率不是 SSH 传输,而是**每个远程文件夹注册了不同的原生 Workspace,Session 的 `workspaceId` 不同**。本方案只做两件事,避免加重问题: - 创建远程文件夹时优先复用同一逻辑项目的 owner/member 归属,不产生新的顶层项目行。 - 预留 `projectKey` 投影接口;后续用“canonical project”聚合会话,不直接改写 Session 归属。 需要一次平台能力验证(Phase 0): > 能否在 owner Workspace 下创建 `cwd = 远程镜像` 的 Session? > - 能:远程文件夹不新建 Workspace,会话天然统一,这是最优解。 > - 不能:保留 mirror-backed Workspace,另做 UI 投影聚合。 在验证前不承诺“合并历史会话”。 --- ## 10. 分阶段实施 | 阶段 | 内容 | 交付/验收 | 预估 | |---|---|---|---| | P0 决策与探针 | 确认传输选型;验证 owner Workspace + mirror cwd 是否可行;冻结六种 DTO 和错误码 | 一页探针结论;不写生产代码 | 0.5–1 天 | | P1 连接与目录 | profiles、连接测试、known_hosts、远程 list/mkdir、SSH 设置页 | 不装 Remote-SSH 也能连 HPC、浏览目录 | 3–5 天 | | P2 远程文件夹闭环 | 镜像、marker、workspaceRegistry、创建/删除/重开、folders 回滚、迁移 | 建远程文件夹,重启后仍在;删记录不删远端 | 3–5 天 | | P3 文件与终端 | read/write/stat/rename/delete/glob/grep、原子写、离线态、终端 wrapper | 远程改文件失败不落本地;终端进 HPC | 4–7 天 | | P4 工具面/同步 | exec 超时/取消、sync/push、上传、13 工具对齐、并发池 | 与旧插件功能对照表全绿 | 4–8 天 | | P5 加固发布 | 安全测试、Unicode/空格/引号、大文件、断网、CDP 真机、文档与迁移说明 | 验收清单全过;可卸载旧插件 | 3–5 天 | **总计约 15–30 个工作日**(单人;不含会话合并和图标分类)。如果只做 P1–P2,约 7–11 天,就能先摆脱“建远程文件夹必须装 Remote-SSH”。 --- ## 11. 验收清单 ### 功能 - [ ] 全新 profile:密钥、agent、密码(内存)三种认证都能连。 - [ ] ProxyJump / `~/.ssh/config` 的 Host 别名可用。 - [ ] 远程目录浏览支持 `~`、绝对路径、空格/中文/单引号目录。 - [ ] 创建远程文件夹后,原生 Workspace 的 `cwd` 是镜像路径,标题正确。 - [ ] 重启 DSH 后,远程文件夹仍在,能重新打开。 - [ ] 删除远程文件夹只删本地映射,远端目录和文件不变。 - [ ] 旧 Remote-SSH 记录迁移后,已有会话仍挂在原 Workspace 下。 ### 安全/失败 - [ ] 构建产物和 API 响应中搜不到私钥内容、密码、完整 keyPath。 - [ ] host key 变化时连接失败,不自动接受。 - [ ] 远程路径 `../../etc`、symlink 逃逸被拒绝。 - [ ] `$(touch /tmp/pwned)`、反引号、换行注入不执行。 - [ ] 断网写文件:报错,镜像文件字节不变。 - [ ] 命令超时/取消后子进程被 kill,无孤儿 ssh。 - [ ] 日志不含 Authorization、密码、passphrase。 ### 兼容 - [ ] Windows 本地 + Linux 远程;macOS 本地 smoke。 - [ ] 远程 Unicode 文件名 round-trip。 - [ ] 大文件超过上限时明确拒绝,不截断后写回。 - [ ] 卸载 Remote-SSH 后,P1–P4 功能不回退。 --- ## 12. 风险与待确认 1. **“完整内置”的边界**:如果要求 Agent 的普通 bash 也在 HPC 执行,这不是本插件能单独完成的,需要 DSH 平台远程执行层;本方案只能做到显式远程工具 + 远程终端。 2. **系统 OpenSSH 依赖**:Windows 需启用 OpenSSH Client;安装页要检测 `ssh -V` 并给出一键说明。若你要求零系统依赖,需改 ssh2,工期和兼容风险上升。 3. **密码/2FA**:v1 密码只存内存,重启要重输;keyboard-interactive 先走终端,Host 工具面后补。若必须持久化,需要接 OS 凭据库(DPAPI/Keychain/libsecret),单独评估。 4. **远程 Windows 主机**:v1 不做;POSIX shell 假设(`sh`、`base64`、`find`、`grep`)。 5. **终端 wrapper**:需要 `nodePath` 逃生舱(旧插件已有同类问题);Desktop 的 Host node 不一定在 PATH。 6. **会话拆分**:见第 9 节,先探针后承诺。 7. **图标分类**:与 SSH 无关,独立处理;当前通用 50 个图标未分节,材料 28 个已分 4 节。 --- ## 13. 需要你拍板的三件事 1. **传输层**:系统 OpenSSH(推荐,兼容最好)还是纯 JS `ssh2`(零系统依赖,但重写配置/跳板/2FA)? 2. **首期范围**:只做 P1–P2(远程文件夹闭环,最快摆脱 Remote-SSH),还是一次做到 P4(完整工具面)? 3. **密码策略**:只存内存、重启重输(推荐,安全)还是接 OS 凭据库持久化? 确认后我再动代码;当前仓库工作树干净,未改任何实现文件。