前言¶

DSH 的工作区默认是本机目录。做跨机器开发时，经常出现这样的需求：模型、Agent、会话和记忆希望留在本机运行和保存，而真正要读写的代码与产物在远程服务器上。手动用 scp/rsync 来回同步，既容易漏文件，也很难把远程终端、端口转发接到 Agent 的能力里。

wilshi/dsh-ssh-workspace 处理的是这件事：它把服务器目录通过 SSH/SFTP 映射为一个受控的本地缓存工作区，并在此基础上提供冲突安全的双向同步、远程终端和端口转发。插件由 WilShi 维护，许可证为 MIT。

这是什么¶

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

它针对两类问题：

1. 让远程目录能像本地工作区一样被 DSH 采用和打开；
2. 在本地缓存与服务器之间做安全的双向同步，冲突时不会静默覆盖。

插件面向 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。

核心功能¶

以下能力均来自插件 README。

远程工作区创建¶

有两个入口：

• 工作区入口：点击侧边栏「工作区 → +」，或在会话空白页点击「选择工作区」。「添加工作区」会直接打开本插件的创建对话框。对话框左上角的「选择本机文件夹」可以回到系统目录选择器，用来添加普通本地工作区。
• 设置页入口：打开「设置 → 远程工作区 → 添加远程工作区」。

插件占用 DSH 0.2.1 的 sidebar.workspaces.directoryFlow 和 conversation.hero.workspace.directoryFlow 两个目录流插槽，以优先级 -1 遮蔽内置文件夹选择器，因此上面的「选择本机文件夹」是保留的回退路径。

认证方式¶

支持密码、OpenSSH 私钥（可带口令）、本机 SSH Agent，以及系统 OpenSSH 配置。系统模式会复用 ~/.ssh/config、Include、ProxyJump、ProxyCommand、Kerberos 和安全密钥等现有能力。

密码、私钥和口令只会写入 DSH 凭据服务；普通配置、日志和安装包不保存这些内容。

双向同步与冲突处理¶

• 文件在本地缓存和服务器之间双向同步，两侧变更都会触发快速同步；监听不可用时自动退化为轮询。
• 同一文件两侧同时变化时不会静默覆盖。设置页会保留冲突副本，并要求用户选择本地版本或服务器版本。
• 稳定文件使用本地快照快速确认，不会在每个轮询周期重新读取和哈希整个工作区；旧版本同步清单会在下一次安全同步时自动补齐该快照。
• 上传、下载和远端哈希会在传输前后复核文件快照；传输途中任一侧文件变化时会中止本次文件操作，而不是提交不完整内容。
• 同步发现大量已跟踪文件可能被删除时会先暂停，设置页必须由用户明确确认后才会继续。
• 服务器离线或网络异常时，后台同步会逐步延长重试间隔，最长 5 分钟，避免持续占用网络；「立即同步」不受该等待限制。

远程终端与端口转发¶

• 侧边卡片终端会自动连接远程 PTY；普通本地工作区仍使用本机终端。
• 远端存在 tmux 时，终端在网络中断或侧边卡片暂时关闭后会保留并续接输出，兼容 tmux 1.8 等企业老版本。
• 设置页可以发现服务器监听端口和进程名，并一键转发到本机；转发意图会保存，客户端重启后自动恢复。连接中断会明确提示，并可一键重试或清理。

模型工具与内核¶

• 标准 DSH Agent 可调用 ssh_workspace_run 和 ssh_workspace_sync。
• 内置 Codex / Claude Code 原生内核在 SSH 工作区中使用同名远程工具执行命令；文件编辑仍落在受控缓存并同步到服务器。

远端助手¶

远程助手优先使用服务器上的 Python 3。没有 Python 3 的 Linux x86_64/arm64 服务器会自动部署随包原生助手（Go 静态二进制），不要求管理员安装依赖。原生助手也不可用时，内置 SSH 会继续使用纯 SFTP 同步。

同步容量与安全边界¶

同步容量：

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

安全边界：

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

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

安装与启用¶

官方安装命令如下，安装后需要重启 dsh web：

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

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

典型用法¶

以下是 README 给出的创建流程。

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

创建成功后，插件会把本地缓存目录交给 DSH 采用并打开。

移除连接会删除公开连接配置、凭据记录和 DSH 工作区注册，但故意保留本地缓存，避免误删用户文件。

适用场景与注意¶

适合需要把远程服务器目录当作 DSH 工作区使用、且希望在本地保留模型与 Agent 运行环境的开发者。插件对锁文件、冲突副本、端口转发和远程终端都做了处理，适合把 SSH 工作区纳入日常开发流。

几点需要注意：

• 插件以当前 dsh 进程的权限运行；请确认运行 dsh 的账户对目标目录和凭据有访问权限。
• 安装第三方插件前应先检查源码与许可证，本插件为 MIT 许可证。
• 插件面向 DSH 0.2.1-rc.5 构建，Node 要求 ^22.19.0 || ^24.0.0；版本不匹配时可能需要核对兼容性。

结语¶

wilshi/dsh-ssh-workspace 的价值在于把「本地缓存 + 冲突安全同步 + 远程终端」这三件事打包成一个 DSH 工作区入口，让远程服务器目录可以直接被 Agent 采用。

目录页：https://www.skillhub.cn/plugins/WilShi/dsh-ssh-workspace

GitHub：https://github.com/WilShi/dsh-ssh-workspace