dsh-ssh-workspace

@wilshi/dsh-ssh-workspace

DSH 的 SSH 远程工作区插件：模型、Agent、会话和记忆继续运行并保存在本机，服务器目录通过 SSH/SFTP 映射为受控的本地缓存工作区。

面向 DSH 0.2.1-rc.5（@deepseek-ai/cordis 4.0.5 / @deepseek-ai/* 0.2.1-rc.5）构建；Node ^22.19.0 || ^24.0.0。

安装

dsh plugin --profile web add @wilshi/dsh-ssh-workspace

安装后重启 dsh web。包内自带 cordis.patch.yml（bundle patch），加载器会把宿主侧挂成一条 loader 行，浏览器侧按 dsh.client 声明注入「设置 → 远程工作区」和新建远程工作区流程。

远程助手优先使用 Python 3；没有 Python 3 的 Linux x86_64/arm64 服务器会自动部署随包原生助手（Go 静态二进制），不要求管理员安装依赖。

使用

有两种入口：

• 工作区入口：点击侧边栏「工作区 → +」或会话空白页的「选择工作区」，「添加工作区」会直接打开本插件的创建对话框（插件占用 0.2.1 的 sidebar.workspaces.directoryFlow / conversation.hero.workspace.directoryFlow 两个目录流插槽，以优先级 -1 遮蔽内置文件夹选择器）。对话框左上角的「选择本机文件夹」会让你回到系统目录选择器，用来添加普通本地工作区。
• 设置页入口：打开“设置 → 远程工作区 → 添加远程工作区”。

创建步骤：

1. 填写名称、服务器地址、SSH 端口、用户名、服务器目录和认证方式。
2. 点击“测试连接”，核对并固定主机指纹。
3. 点击“保存并创建工作区”。新工作区会出现在左侧工作区列表中。

支持密码、OpenSSH 私钥（可带口令）、本机 SSH Agent，以及系统 OpenSSH 配置。系统模式会复用 ~/.ssh/config、Include、ProxyJump、ProxyCommand、Kerberos 和安全密钥等现有能力。密码、私钥和口令仅写入 DSH 凭据服务；普通配置、日志和安装包不保存这些内容。

行为

• 创建流直接接入工作区选择器：创建成功后把本地缓存目录交给 DSH 采用并打开；同时保留“选择本机文件夹”回退，避免遮蔽内置目录选择器后无法添加本地工作区。
• 文件在本地缓存和服务器之间双向同步；本地和服务器变更都会触发快速同步，监听不可用时自动退化为轮询。
• 同一个文件两侧同时变化时不会静默覆盖。设置页会保留冲突副本，并要求用户选择本地版本或服务器版本。
• 稳定文件使用本地快照快速确认，不会在每个轮询周期重新读取和哈希整个工作区；旧版本同步清单会在下一次安全同步时自动补齐该快照。
• 上传、下载和远端哈希会在传输前后复核文件快照；传输途中任一侧文件变化时会中止本次文件操作，而不会提交不完整内容。
• 同步发现大量已跟踪文件可能被删除时会先暂停，设置页必须由用户明确确认后才会继续。
• 服务器离线或网络异常时，后台同步会逐步延长重试间隔（最长 5 分钟），避免持续占用网络；“立即同步”不受该等待限制。
• 侧边卡片终端会自动连接远程 PTY；普通本地工作区仍使用本机终端。
• 远端存在 tmux 时，终端在网络中断或侧边卡片暂时关闭后会保留并续接输出；兼容 tmux 1.8 等企业老版本。
• 设置页可以发现服务器监听端口和进程名并一键转发到本机；转发意图会保存，客户端重启后自动恢复。连接中断会明确提示，并可一键重试或清理。
• 远端助手优先使用 Python 3；没有 Python 3 的 Linux x86_64/arm64 服务器会自动部署随包原生助手，不要求管理员安装依赖。原生助手也不可用时，内置 SSH 会继续使用纯 SFTP 同步。
• 标准 DSH Agent 可调用 ssh_workspace_run 和 ssh_workspace_sync。
• 内置 Codex / Claude Code 原生内核在 SSH 工作区中使用同名远程工具执行命令；文件编辑仍落在受控缓存并同步到服务器。
• 移除连接会删除公开连接配置、凭据记录和 DSH 工作区注册，但故意保留本地缓存，避免误删用户文件。

同步容量

• 单文件最大 6GB。
• 单个远程工作区同步数据总量最大 100GB。
• 单个远程工作区最多扫描 50,000 个条目。
• 上传、下载和哈希均采用流式处理，不会把整个大文件一次性读入内存。

这些是 DSH 客户端的保护性边界；SSH/SFTP 服务端本身还可能受到磁盘空间、用户配额、文件系统和管理员策略限制。

安全边界

• 首次连接必须确认服务器主机指纹，后续连接固定该指纹。
• Web 配置 API 仅接受本机同源渲染器请求。
• 默认排除 .git、node_modules 和 .dsh-conflicts。
• 符号链接不会被当作普通文件递归跟随。

构建与测试

npm install
npm run build     # tsc 编译宿主 lib/ + esbuild 打包 lib/client.js + 校验脚本 + 可选原生助手
npm test          # vitest（19 个测试文件 / 59 个用例）
npm run typecheck # tsc --noEmit（宿主、客户端、测试）

• npm run build:host：只编译宿主 ESM 到 lib/，声明文件在 lib/types/。
• npm run build:client：esbuild 打包 src-client/index.tsx 为浏览器 CJS，并用 window.__ModuleLoader__.load({ id, factory }) 闭包工厂包裹，产物 lib/client.js。
• npm run build:helper：用 Go 源码 remote-helper-go/main.go 交叉编译 lib/helpers/dsh-ssh-helper-linux-{amd64,arm64}。Go 工具链缺失时自动跳过（构建不失败，Python 助手仍是默认运行时；只有无 python3 的 Linux 服务器会因此失去原生助手回退）。设置 DSH_SSH_HELPER_REQUIRE_NATIVE=1 可改为强制失败，便于发布流水线确认产物完整。
• npm run smoke:host：在真实 @deepseek-ai/cordis Context 下加载 lib/index.js，用桩宿主服务验证路由/工具注册与 dispose 清理。

目录结构

路径	说明
src/	宿主侧：Cordis 插件入口、Manager、同步引擎、SSH/SFTP 客户端、HTTP API、模型工具、凭据与端口转发
src-client/	浏览器侧：设置页、远程工作区创建流程、slot 注册、CSS Modules
remote-helper-go/	可选远端原生助手源码（Go，无第三方依赖）
scripts/	构建 / 产物校验 / 真实服务器冒烟脚本
tests/	vitest 测试（SSH 相关用桩通道，无需真实服务器；live-smoke 才需要真实服务器）

作者：WilShi · License: MIT