MDR-EX1000/dsh-rw

dsh-rw

CI
Release
License: MIT

面向 DeepSeek Harness（DSH）的 Remote-SSH 风格工作区。

版本 0.4.3 支持 DSH 0.1.2-rc.1 及兼容的后续 0.1.x 版本。

选择一个 SSH 主机和一个远程目录——该目录即成为原生 DSH 工作区，agent 通过 rw_ 工具（基于持久化 ssh2 连接池的 SFTP/exec）直接在远程文件系统上工作。无镜像、无同步：远程即唯一事实来源。

自 0.4.0 起零配置——一旦远程工作区激活，agent 的原生 read/write/edit/bash 工具会自动在远程主机上运行；你无需再教它使用新工具。

可以把它看作 SSH 运维工具箱在工作区层面的对应物：不再是“在那边跑一条命令”，而是让 agent 获得一个持久的远程项目根目录，可在其中读取、编辑、构建和测试——就像 VS Code Remote-SSH，但面向你的 agent。

功能特性

- 远程目录作为原生工作区——一个居中的选择器模态框填充 DSH 的“添加工作区”流程：紧凑的双卡片选择器（英文为 LOCAL / REMOTE）分别导向本地页面（操作系统文件夹选择器）或 Codex 风格的远程页面（仅别名的 host 下拉框、预填 ~/ 的远程主目录路径、带实时输入过滤的内联目录浏览器、可选的工作区名称）。
- 跟随 DSH 语言设置——每个选择器标签、提示、校验消息、加载状态、确认信息和回退消息均提供中英文版本。当前文案跟随 DSH 全局的 Settings → Language 偏好设置，并在选择器打开时即时更新；无需插件专属语言设置，也无需重启。
- 主机来自 ~/.ssh/config——零配置：你现有的别名会自动出现（文件变更时重新读取，无需重启）。密码认证的主机可在选择器中添加（本地存储，文件权限 0600）。
- 真正的工作区限制——每个 rw_ 文件路径都被限制在所选工作区根目录内：../、根目录之外的绝对路径以及符号链接逃逸（通过远程 realpath 检测为 SYMLINK_ESCAPE）都会被拒绝，并返回结构化错误。
- SSH 主机密钥验证——默认对照 ~/.ssh/known_hosts 进行验证（accept-new：首次出现的密钥会被记录），并支持 strict 和显式 off 策略。主机密钥发生变化时会被拒绝，绝不会被静默接受。
- 结构化错误——连接被拒绝 / 认证失败 / 超时 / 路径不存在 / 权限不足 / 超出工作区 / 主机密钥问题均为不同的错误码，因此 agent 可以正确应对。
- 自愈连接 — ssh2 连接池的 keepalive（15 秒 × 3）会检测断开的连接，通道/子系统打开操作有超时限制（channelOpenTimeoutMs，默认 10 秒），因此静默失效的连接（半开 TCP）不会挂起操作。落在失效连接上的操作会在重新拨号的新连接上透明地重试一次——瞬时的网络抖动永远不会以错误的形式到达 agent。
- 占位符，而非副本 — DSH 注册的本地目录是一个空占位符（.dsh-rw-meta.json 记录 user@host:path 来源）。它从不保存远程文件内容，因此无需同步，也不会有冲突。它采用一个干净的名称——远程 basename 或你在选择器中给出的名称；只有在命名冲突时才会出现哈希后缀（旧版带哈希后缀的占位符仍可正常工作）。
- Shim 模式（默认开启） — DSH 原生的 read/write/edit/str_replace_editor/glob/grep/bash 工具在工具管道上被拦截并转换为远程执行，因此 agent 可以像工作区在本地一样工作，而无需学习 rw_。路径在占位符↔远程之间双向映射，编辑在写回前会重新 stat（并发更改时返回 RW_EDIT_CONFLICT），被 shim 的 bash 会升级到审批对话框并指明远程主机。默认开启——设置 shim: false（cordis 配置或 ~/.dsh/settings.yaml 中的 dsh-rw:）可退出，仅使用显式的 rw_ 工具。shim 锚定在 agent 会话的 cwd 占位符上——而非可变的 rw_ 会话——因此 rw_disconnect 或将 rw_ 重新连接到另一台主机不会静默重定向原生工具；根路径位于占位符之外的调用始终原样传递给本地工具。
- 大声失败，绝不静默本地化 — 如果某个占位符的主机已从配置中移除，会触及该占位符的调用将失败并返回可操作的 NOT_CONNECTED 错误，而不是静默地针对空的本地目录运行。该阻止是路径感知的：只有触及损坏占位符的调用会失败；其他一切仍然照常通过。

安装

使用 DSH Market 显示的紧凑仓库 basename，从 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。

对于每个发布版本，在推送版本提交和标签之前，先构建并提交 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 进行密码认证）→ 浏览或输入远程路径（从远程主目录 ~/ 开始；可选地为它指定一个工作区名称）→ Use as remote workspace。当全局 DSH 语言为中文时，这些标签会以中文显示。
2. 像往常一样与 agent 协作 — 在 shim 模式开启（默认）的情况下，agent 在工作区内原生的 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.yml / loader patch 中的插件条目）——以下每个键的基础层。
hostKeyPolicy、knownHostsPath、commandTimeoutMs、connectTimeoutMs 和
maxOutputChars 仅在此处配置。
- ~/.dsh/settings.yaml — dsh-rw: 部分仅覆盖三个 shim 开关。
通过 settings 服务所做的更改会实时生效；手动编辑文件后，
重启 dsh web 以确保它们被读取。解析顺序：schema 默认值 →
cordis 条目配置（基础）→ 此用户层。

~/.dsh/settings.yaml — 所有三个键都默认为所示值；你只需要
此部分来退出 shim 模式。
dsh-rw:yaml
shim: false             # 默认 true：原生工具在远程工作区上运行。
设为 false 则仅使用显式的 rw_ 工具。
shimBash: true        # 同时拦截 bash（会话 cwd 必须为占位符）
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（仅当 agent 会话 cwd 为占位符工作区时） |
| shimBashApproval | 'ask' | cordis + 设置 | 经 shim 处理的 bash 审批：'ask' 升级到 DSH 审批对话框（原因中指明远程主机），但在诸如 danger-full-access 这类从不询问的预设下会让步——在那里询问会自动拒绝且不显示对话框，因此命令直接运行；'native' 始终交由原生 bash 策略处理 |

语言

dsh-rw 将其 zh 和 en 字典注册到官方
@deepseek-ai/dsh-client-locale 服务。它读取与
DSH 其余部分相同的由 Host 支持的全局偏好（~/.dsh/settings.yaml 中的 locale.preference），并订阅语言环境修订，因此
更改 设置 → 语言 会立即重新渲染已打开的选取器。对于其他语言包，英语是
回退语言，直到它们提供 dsh-rw 命名空间字典。

安全模型

- 工作区隔离 — 文件工具针对工作区根解析每个路径，并验证真实路径（跟随符号链接）保持在其中。写入会验证最近的存在祖先。
- 主机密钥验证如上所述；主机密钥变更会以 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 文件树显示的是空的占位目录，而非远程文件——远程浏览通过选择器或智能体进行。

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

真实主机验收（需主动启用，会在目标主机上创建并清理一个临时目录）：
bash
ssh  'mktemp -d /tmp/dsh-rw-acceptance.XXXXXX'   # then seed test data
node scripts/acceptance.mjs  /tmp/dsh-rw-acceptance.XXXXXX
node scripts/live-shim.mjs     # end-to-end shim acceptance (native tools → remote)

许可证

MIT