远程工作区 MDR-EX1000/dsh-rw

dsh-rw

给 DeepSeek Harness（DSH）用的 Remote-SSH 风格工作区。

0.4.6 版支持 DSH 0.1.2-rc.1 和 0.2.0-rc.2，也兼容后续的 0.1.x / 0.2.x 版本。

选一台 SSH 主机，再选一个远程目录——这个目录就成了 DSH 原生工作区，智能体通过 rw_ 工具直接在远程文件系统上干活（走持久 ssh2 连接池，用 SFTP/exec）。不做镜像，不做同步：远程就是唯一事实来源。

0.4.0 起零配置——远程工作区一激活，智能体原生的 read/write/edit/bash 工具就自动跑在远程主机上，你不用再教它一套新工具。

可以把它看成 SSH 运维工具箱的工作区版本：不再是「去那边跑一条命令」，而是给智能体一个持久的远程项目根目录，让它能在里面读、改、构建、测试——像 VS Code Remote-SSH，只不过服务对象是你的智能体。

功能

- 远程目录就是原生工作区——一个居中的选择弹窗接进 DSH 的「添加工作区」流程：先是一个紧凑的双卡片选择器（英文显示 LOCAL / REMOTE），然后进入本地页（系统文件夹选择器）或 Codex 风格的远程页（主机下拉框只列别名，远程家目录路径预填 ~/，内嵌目录浏览器支持边输入边过滤，工作区名称可选填）。
- 跟随 DSH 语言设置——选择器里的每个标签、提示、校验消息、加载状态、确认信息和兜底文案都提供中英双语。当前文案跟随 DSH 全局的 Settings → Language 偏好，选择器开着的时候也会立即切换；不需要插件单独的语言设置，也不用重启。
- 主机来自 ~/.ssh/config——零配置：你已有的别名会自动出现（文件一变就重新读取，不用重启）。密码认证的主机可以在选择器里添加（存在本地，文件权限 0600）。
- 真正的工作区隔离——每个 rw_ 文件路径都被限制在选定的工作区根目录内：../、根目录之外的绝对路径、符号链接逃逸（远程 realpath 判定为 SYMLINK_ESCAPE）都会被拒绝，并返回结构化错误。
- SSH 主机密钥校验——默认对照 ~/.ssh/known_hosts 校验（accept-new：首次见到的密钥会被记录），也支持 strict 和显式 off 策略。主机密钥变了就拒绝连接，绝不悄悄放行。
- 结构化错误——连接被拒 / 认证失败 / 超时 / 路径不存在 / 权限不足 / 超出工作区 / 主机密钥问题各有独立错误码，智能体能据此正确应对。
- 连接自愈 — ssh2 连接池的 keepalive（15s × 3）能发现断开的连接，channel/subsystem 打开设有超时上限（channelOpenTimeoutMs，默认 10s），因此静默死亡的连接（半开 TCP）不会把操作挂死。落在死连接上的操作会透明地在新拨号上重试一次——被拒绝的 channel 也算死连接（代理前端保持 TCP 健康，但后端已过期），所以池里的陈旧连接会自愈，而不是污染后续每一次调用。
- 占位符，不是副本 — DSH 注册的本地目录是空占位符（.dsh-rw-meta.json 记录 user@host:path 来源）。它从不保存远程文件内容，因此没有东西需要同步，也不会冲突。它取一个干净的名字——远程 basename，或你在选择器里给的名字；只有命名冲突时才出现哈希后缀（旧的带哈希后缀占位符继续可用）。
- Shim 模式（默认开启） — DSH 原生的 read/write/edit/str_replace_editor/glob/grep/bash 工具在工具流水线上被拦截，转译为远程执行，智能体就像工作区在本地一样工作，无需学习 rw_。路径在占位符↔远程之间双向映射，编辑写回前重新 stat（并发修改时报 RW_EDIT_CONFLICT），shim 的 bash 会升级到审批对话框，并标明远程主机。默认开启——设 shim: false（插件的 cordis 入口配置，或 DSH 插件配置表单里对应那一行）即可退出，只用显式的 rw_ 工具。shim 有两个锚点：调用自身的路径参数位于占位符内时，从任意工作目录都能转译（锚点随调用走）；没有路径可锚定的调用（bash、无路径的 glob/grep）在智能体会话的 cwd 是占位符时转译。两个锚点都不查可变的 rw_ 会话，所以 rw_disconnect 或重连到另一台主机不会悄悄重定向原生工具；根路径在所有占位符之外的调用始终原样透传给本地工具。
- 大声失败，绝不静默落到本地 — 如果占位符的主机已从配置中移除，会触及该占位符的调用以可操作的 NOT_CONNECTED 错误失败，而不是静默地对着空的本地目录运行。拦截是路径感知的：只有触及损坏占位符的调用失败，其余照常透传。
- 版本自报 — rw_info 打印主机实际加载的模块版本（不是磁盘上的 manifest），所以从会话内部就能看出进程是否陈旧。
- 不编辑 ssh 配置也能隐藏主机 — ssh-config 行上的 ✕ 把它从列表移除，并在本地记住别名（插件存储里的 hidden）；~/.ssh/config 不受影响。列表下方一行显示隐藏了什么，一键全部恢复。
- 哪些 ssh-config 条目会成为主机，由你决定 — sshConfigInclude / sshConfigExclude 接受 shell 风格的 glob，所以即使某台机器的 ~/.ssh/config 里塞满了构建和测试别名，也不会把主机列表刷爆。手动添加的主机不受这个过滤器影响。
- 主机列表，不是下拉框 — 远程页面为每台主机渲染一行，显示 user@host:port、来源（ssh-config / 手动）和凭据标签；主机不可用时行内给出原因；每行有 test 操作，报告实测延迟；手动主机还能编辑和删除。下次打开时恢复上次使用的主机。
- 用 rw_exec_many 扇出 — 在几台主机上跑同一条命令，或为每台主机各跑一条独立命令，并行执行（并发有上限，默认 4，上限 16），按输入顺序每次调用返回一个结果段。一台主机连不上，不会让其余结果作废；所有别名都会在开跑前解析完。
- 持久 shell — persistent-bash 变体为每个（主机, 工作区）保留一个长期存活的远程 bash，所以 cd 和 export 能跨调用保留。每条命令用随机哨兵包裹，哨兵携带退出码；stdout 和 stderr 合并，因为 shell 只有一条有序流（结果里会说明）。命令卡住时重置 shell，而不是留下未读输出；空闲 shell 在 persistentShellIdleMs 后关闭。
- 基于轮询的变更监视（rw_watch） — 对一个目录做 start / poll / stop / list（一个 include glob，maxEntries 上限）。两次轮询之间远程不跑任何东西：快照存在插件进程里，所以一次轮询只花一次递归 SFTP 列目录。
- Diff、补丁和乐观写入 — rw_diff 把远程文件与提供的文本或另一个远程文件做统一 diff（按原始字节比较，所以末尾换行永远不会变成幽灵变更）；rw_apply_patch 在运行之前先拿每个涉及的路径对照工作区根目录校验，然后在 --dry-run 之后用 patch -pN 应用；rw_write_file 接受 ifHash（sha256，或 "absent" 表示仅创建），冲突时以 RW_WRITE_CONFLICT 失败，而不是覆盖并发编辑。
- 远程搜索对齐原生工具 — glob 用 --sort=modified --no-ignore --hidden 加上 VCS 排除项，grep 解析 rg --json（所以含冒号的路径不会被错误切分），两者都在搜索根目录前放 --。主机上缺 ripgrep 时，结果里会标注走的是 find / grep -rnE 回退，而不是悄悄返回不同的 ignore/hidden 语义。
- 绝不在本地运行时声称走远程 —— 翻译锚定在会话的工作目录上，所以插件报告的是它实际观察到的情况，而不是记录中的会话所暗示的情况。rw_info 会说明原生工具实际去了哪里（remote / LOCAL / not observed yet）；本地工作目录导致的直通（pass-through）会恰好打印一行控制台日志，同时写明该 cwd 和它本应所在的占位符；提示词部分会一直陈述这条规则，直到一次派发将其确定下来 —— 一旦观察到本地直通，就切换为明确的 WARNING … running on the LOCAL machine；只有看到过一次已翻译的调用之后，才切换为「translated automatically」。

安装

GitHub 源（当前渠道）

发布包只发布到 GitHub；该包已为 npm 做好准备（prepublishOnly 会运行 typecheck + test + build，publishConfig 固定了 npmjs registry），但尚未发布到那里，所以 dsh plugin add dsh-rw 无法解析。

使用 DSH Market 显示的紧凑仓库基名，从 GitHub 源安装：

dsh plugin --profile web add github:MDR-EX1000/dsh-rw

仓库跟踪编译后的 lib/ 输出，没有 prepare、prepack、install 或 postinstall 生命周期钩子。因此安装这个源既不需要本地 TypeScript 工具链，也不需要构建插件的权限。DSH Market 在更新插件时会保留 github: 源，并解析仓库当前默认分支的提交。

需要精确的发布归档时，仍可使用对应的不可变发布包：

dsh plugin --profile web add https://github.com/MDR-EX1000/dsh-rw/releases/latest/download/dsh-rw.tgz

发布包包含相同的编译后 lib/ 输出。稳定的 dsh-rw.tgz 文件名让 releases/latest/download URL 在各版本间保持有效。

源码安装维护说明

按基名安装会跟随仓库的默认分支，安装过程中不会运行本插件的 build 脚本。运行时入口是已提交的 lib/index.js，所以要把生成的 lib/ 文件保留在 Git 中，并在 src/ 变化时重新构建：

pnpm build
git add lib

插件本身目前没有 prepare、prepack 或 postinstall 构建钩子。它的 ssh2 依赖仍可能为可选原生模块（ssh2 和 cpu-features）请求 pnpm 权限；使用 pnpm 构建脚本允许列表的配置档必须允许这些依赖。这属于依赖安装，不是重新构建 dsh-rw。

prepublishOnly 会在任何 npm publish 之前运行 typecheck、test 和 build，所以 npm 产物始终是经过测试的那一份。

每次发布时，先构建并提交 lib/，再推送版本提交和标签。这样现有的基名安装就能在后续 Market 更新中继续停留在同一个简洁的 GitHub 源上。只有需要精确的已测试归档时，才使用 Release tarball。

从本地检出安装（开发）：

dsh plugin --profile web add /path/to/dsh-rw

之后重启 dsh web。插件在启动时激活；「Add workspace」流程会多出卡片式选择器。

快速开始

1. 选择工作区 — 侧边栏 / 会话的 Add workspace → REMOTE 卡片 → 选一台主机（来自 ~/.ssh/config，或在其子页面点 + Add host 用密码认证）→ 浏览或输入远程路径（从远程 home ~/ 开始；可选填工作区名称）→ Use as remote workspace。全局 DSH 语言为中文时，这些标签显示为中文。
2. 照常和智能体协作 — 开启 shim 模式（默认开启）后，智能体在工作区内调用的原生 read/write/edit/glob/grep/bash 会自动转发到远程主机。直接让它修 bug、跑测试或重构即可，无需学习新东西。
3. 需要时显式操作远程 — rw_ 工具始终可用：
- rw_list_dir / rw_read_file / rw_write_file / rw_mkdir / rw_move / rw_delete — 文件操作（限定在工作区内）
- rw_exec — 以工作区根目录为 cwd 运行 shell 命令（构建、测试、grep……）
- rw_hosts / rw_connect / rw_pick_workspace / rw_info / rw_disconnect — 主机与会话管理

配置

下面每个键，dsh-rw 都只读一层配置：插件的 cordis 条目配置，也就是你配置档的 cordis.patch.yml / loader 补丁里的 dsh-rw 条目。hostKeyPolicy、knownHostsPath、commandTimeoutMs、connectTimeoutMs、maxOutputChars 只在这里配置。

三个 shim 开关属于设置层，而 DSH 在插件之下改动了这一层：

- DSH 0.2.x 从插件自己的 Config schema 推导插件设置，并通过配置档组合来编辑——插件配置表单，或条目的 config: 块。dsh-rw 暴露的开关就在 Config 里，所以会自动出现在该表单中；编辑后会以新值重新应用插件。
- DSH 0.1.2 注册 dsh-rw 设置命名空间，在条目配置之上再加一层，从 ~/.dsh/settings.yaml 的 dsh-rw: 段读取并实时生效。解析顺序：schema 默认值 → cordis 条目配置（基础）→ 用户层。

dsh-rw 根据找到的服务（是否存在 register 方法）选择模型，从不做版本检查，所以两种版本配置的是同样三个键： yaml

Profile cordis.patch.yml — the dsh-rw entry config. All three keys default to the

values shown; you only need this block to opt OUT of shim mode. On DSH 0.1.2 the

same keys also resolve from dsh-rw: in ~/.dsh/settings.yaml, which wins over this.

- id: dsh-rw
config:
shim: false # default true: native tools run on the remote workspace.

Set false to use only the explicit rw_* tools.

shimBash: true # also intercept bash (session cwd must be the placeholder)

shimBashApproval：ask # ask = 弹出审批对话框，并写明远程主机名（在 danger-full-access 这类从不询问的预设下会跳过，直接运行）；# native = 交给原生 bash 策略处理

插件配置项（默认值如下）：

| 配置项 | 默认值 | 生效层 | 含义 |
| hostKeyPolicy | 'accept-new' | 仅 cordis | 'accept-new' 会把首次见到的主机密钥记入 known_hosts；'strict' 拒绝未知主机；'off' 关闭校验（需显式设置） |
| knownHostsPath | ~/.ssh/known_hosts | 仅 cordis | 用于校验的 known_hosts 文件 |
| commandTimeoutMs | 30000 | 仅 cordis | 每条远程命令的超时 |
| connectTimeoutMs | 15000 | 仅 cordis | SSH 握手超时 |
| channelOpenTimeoutMs | 10000 | 仅 cordis | 通道/子系统打开超时：限制等待静默断连的时间，超时后丢弃连接，并在新连接上重试一次 |
| maxOutputChars | 200000 | 仅 cordis | 单次调用收集的 stdout/stderr 上限 |
| shim | true | cordis + 设置层 | shim 模式：拦截原生 read/write/edit/str_replace_editor/glob/grep/bash 工具，让它们对当前远程工作区执行（设为 false 可退出该模式，只用 rw_） |
| shimBash | true | cordis + 设置层 | 开启 shim 后，同时拦截 bash（仅当智能体会话的 cwd 是占位工作区时） |
| shimBashApproval | 'ask' | cordis + 设置层 | 经 shim 的 bash 审批方式：'ask' 会升级到 DSH 审批对话框（原因中写明远程主机名），但在 danger-full-access 这类从不询问的预设下不生效——在那里询问会自动拒绝且不弹框，命令直接运行；'native' 始终交给原生 bash 策略处理 |
| persistentShell | true | 仅 cordis | 按（主机，工作区）组合运行持久 bash 版本，每个组合一条长驻远程 shell，让 cd/export 在多次调用间保留（设为 false 回到 1.0 之前的一次性行为） |
| persistentShellIdleMs | 600000 | 仅 cordis | 持久 shell 空闲超过这么多毫秒后关闭（0 表示不按空闲关闭） |
| backgroundJobs | true | 仅 cordis | 把原生 bash(run_in_background) 调用作为 ctx.jobs 任务在 HOST 上运行，用常规的 job_output/job_kill 收集；关闭（或没有任务注册表）时拒绝该调用，而不是在本地运行 |
| jobPollMs | 500 | 仅 cordis | 叙述远程后台任务时轮询日志的间隔 |
| jobDir | '/tmp' | 仅 cordis | 存放后台任务日志的远程目录 |
| sshConfigInclude | [] | 仅 cordis | 只有这些 ~/.ssh/config 别名会成为主机；支持 shell 风格通配符（、?），不区分大小写。留空表示所有别名 |
| sshConfigExclude | [] | 仅 cordis | 永不导入这些别名；排除匹配优先于包含匹配 |

语言

dsh-rw 把 zh 和 en 词典注册到官方 @deepseek-ai/dsh-client-locale 服务。它读取的全局偏好与 DSH 其余部分一致，都由 Host 托管（即 locale.preference 设置，在 Settings → Language 下修改），并订阅 locale 修订，所以修改 Settings → Language 会立即重新渲染已经打开的选择器。其他语言包在提供 dsh-rw 命名空间字典之前，回退到英文。

安全模型

- 工作区限制 —— 文件工具对每个路径都基于工作区根目录解析，并校验真实路径（跟随符号链接后）仍位于工作区内。写入时校验最近的已存在祖先目录。
- Host key 校验 如上文所述；host key 变化会中止连接，并返回 HOSTKEY_CHANGED。
- 仅限回环的 HTTP 路由 —— /api/dsh-rw/ 拒绝非回环调用方。
- 密钥 —— 密码/口令以明文存储在 ~/.dsh/dsh-rw.json（权限 0600，信任模型与 dsh-ssh 相同）；它们不会出现在工具输出、API 响应或错误消息中。私钥只在连接时由 ssh2 读取。
- 影响范围 —— 把某台主机的凭据交给插件，就等于允许智能体以该用户身份在那台主机上运行 shell 命令。只连接你信任的主机。rw_delete 会执行真正的远程删除。

与 @linxin666/dsh-ssh 的关系

两者互补，不是替代关系。dsh-ssh 是运维工具箱（Web 终端、端口转发隧道、SFTP 传输 GUI、集群执行、ProxyJump）。dsh-rw 是工作区层（为智能体提供持久的远程项目根目录）。两者共存：工具名不同（ssh_ 与 rw_*），路由不同，连接池各自独立。

已知限制

- 不支持 ProxyJump / 跳板机链（仅单跳）。
- rw_exec 是一次性执行，没有交互式 PTY。
- 文件读取面向文本（按行分页），上限 2 MB；大文件二进制传输不在支持范围内。
- DSH 文件树显示的是空的占位目录，不是远程文件 —— 远程浏览通过选择器或智能体进行。

开发

pnpm install
pnpm build # tsc (host) + esbuild wrapper (client)
pnpm test # vitest — all SSH/SFTP mocked
pnpm typecheck

真实主机验收（需手动开启，会在目标机上创建并清理临时目录）：

ssh <alias> 'mktemp -d /tmp/dsh-rw-acceptance.XXXXXX' # then seed test data
node scripts/acceptance.mjs <alias> /tmp/dsh-rw-acceptance.XXXXXX
node scripts/live-shim.mjs <alias> <remote-dir> # end-to-end shim acceptance (native tools → remote)

License

MIT