januory/dsh-remote-workspaces

English | 中文

通过 SSH 把远程主机上的目录，像打开本地文件夹一样，作为DeepSeek Harness 的工作区打开工作。

它做了什么

远程目录一旦被打开为工作区，agent 的文件工具（read / write / edit /grep / glob）和 shell 命令都会直接落到远主机上执行，而不是本地镜像。这里没有镜像、没有同步：每个操作都在远端实时执行，而本地工作区仍保留 harness 自身的完整沙箱行为。

功能特性

• 把远程目录当作工作区打开 —— 浏览远程文件系统、选中目录，harness 会像对待本地目录一样接纳它；所有 I/O 都路由到远端。
• 多主机注册表 —— 增删改 SSH 主机（别名 / 主机 / 端口 / 用户 / 密钥或密码）。凭据在本地用 AES-256-GCM 加密落盘，绝不会回传到浏览器。
• ~/.ssh/config 导入 —— 列出已配置的别名并自动填充连接表单。
• 连接测试 —— 使用前先验证主机连通性。
• 透明的工具路由 —— read/write/edit 走 SFTP，grep/glob 在远端跑ripgrep，bash/pwsh 命令通过 ssh2 exec 执行。路由由会话决定，而不是由路径写法决定：远程工作区内每条命令都在那台主机上执行，指向该主机上不存在路径的 workdir 会被拒绝，而不是落到本地执行。本地会话沿用 harness 自身的沙箱。
• 感知权限策略的远端写操作 —— harness 的文件策略同样作用于远程工作区：read-only 会拒绝 write/edit 和远程 shell 命令，workspace-write 把 write/edit 限制在远程工作区根目录（以及 /tmp）内、而远程 shell 命令需经 danger-full-access 审批后放行，danger-full-access 则交由 SSH 账号自身权限决定。

工作原理

bundle 分为宿主机侧（host）和浏览器侧（browser）两半：

• Host（src/index.js）—— 基于 ssh2 的 SSH/SFTP 传输、加密主机存储、分流文件系统（ctx.fs）与 shell（ctx.shell）provider、远程感知的grep/glob 工具，以及通过 Typert 暴露的 remoteWorkspaces Remote 命名空间。
• Browser（src/client.js）—— “远程工作区”设置页（按主机分组）以及一个“添加工作区”的选择器。

打开远程目录会创建一个锚点（anchor）：一个被 harness 接纳为工作区身份的真实但为空的本地目录，外加一个记录其远程来源的元数据文件。注册表（anchors.json）把该锚点映射到远程主机与路径，所有文件/命令操作都据此查表路由到远端：

$DSH_HOME/remote-workspaces/
├── machines.json              # 主机注册表（凭据加密落盘）
├── anchors.json               # 锚点 → 远程来源 路由注册表
└── <host>-<user>-<port>/      # 每台主机的锚点
    └── <encoded-path>/        # 每个远程路径对应一个空锚点
    │   └── .dsh-remote-meta.json

远程完整路径会被编码进锚点目录名（路径分隔符和 Windows 非法字符变成 --），因此 /home/test 和 /data/test 会落到不同的目录（home--test vs data--test）。

环境要求

• 一个 DeepSeek Harness 安装（插件在运行时解析其宿主服务）。
• Node.js ≥ 18（harness 本身运行在 Node 22+）。
• ssh2 是唯一的传输依赖；不需要外部 ssh 命令。
• 远端主机需要 rg（ripgrep）以支持 grep/glob，以及 sha256sum（或shasum）用于写入后校验——二者缺失时都会优雅降级。

安装

从本仓库在线安装：

dsh plugin --profile web add github:januory/dsh-remote-workspaces

发布到 npm 后，也可以直接安装已发布的包：

dsh plugin --profile web add dsh-remote-workspaces

从源码安装：

git clone https://github.com/januory/dsh-remote-workspaces.git

cd dsh-remote-workspaces

pnpm install  # 安装 ssh2 传输依赖

dsh plugin --profile web add .

卸载：

dsh plugin --profile web remove dsh-remote-workspaces

维护者注：npm 包名现为 dsh-remote-workspaces（早期 git 安装时的包名是 remote-workspaces）；旧安装请先 dsh plugin --profile <name> remove remote-workspaces，再按新名安装。

使用

1. 打开 设置 → 远程工作区。
2. 添加一台 SSH 主机（或从 ~/.ssh/config 导入），然后点 测试连接。
3. 在“添加工作区”流程里选择远程主机、浏览到某个目录并打开。harness 会把空锚点接纳为工作区，之后的读取、写入、搜索和 shell 命令都在远端执行。

Remote API

宿主通过 Typert 暴露 remoteWorkspaces Remote 命名空间，包含这些调用： listMachines、saveMachine、deleteMachine、listSshAliases、sshAliasDetail、testConnection、listRemoteDir、openRemoteWorkspace。

目录结构

src/                          # DSH bundle 源码
  index.js                    # 宿主入口（分流 fs/shell、搜索工具、Remote 命名空间）
  client.js                   # 浏览器入口（设置页 UI + 选择器）
  transport.js                # ssh2 传输（SshClient、exec、sha256）
  routing-fs.js               # 分流文件系统（远端 SFTP / 本地围栏）
  fs-sftp.js                  # SFTP 文件系统后端
  local-backend.js            # 本地文件系统后端
  containment.js              # 本地沙箱围栏
  shell-exec.js               # SshShellExecutor（远端 ssh2 exec / 本地 subprocess）
  search.js                   # 远程感知的 grep/glob 工具
  anchor.js                   # 本地锚点布局（空目录 + 元数据）
  registry.js                 # anchors.json 路由注册表
  machine-store.js            # 主机注册表（加密落盘）
  ssh-config.js               # ~/.ssh/config 解析
  ssh-uri.js                  # ssh:// URI 解析与识别
  errors.js                   # 错误码
cordis.patch.yml              # DSH bundle patch（换入分流 provider）
package.json                  # 包 + dsh 清单
test/                         # 单元 + 集成测试

测试

纯单元测试（无需任何主机）可在任意环境运行：

pnpm test

集成测试需要访问真实 SSH 主机，且需先配置好主机注册表（默认使用注册表里的第一台主机，或别名为 test 的那台）：

pnpm test:integration

发布（维护者）

发布完全手动触发、零输入：版本号直接取自 package.json，发布前先在 main 上提交改好的 version，然后 GitHub Actions → release → Run workflow 即可。工作流会自动执行：跑单元测试（npm test）→ 校验 v<version> tag 尚未存在（防止重复发布）→ npm publish（带 provenance）→ 打 v<version> tag 并推送 → 用 --generate-notes 创建 GitHub Release。

前提：在仓库 Settings → Secrets and variables → Actions 中配置名为 NPM_TOKEN 的 secret（npm automation token，或对该包有 publish 权限的 granular token）；发布账号须是持有该包名的 npm 用户。

等价的手工流程：

npm login

npm publish --provenance

git tag "v$(node -p \"require('./package.json').version\")"

git push origin --tags

开源协议

MIT