一句话定位

把 DSH 的工作区从「本机目录」扩展到「任意 SSH 主机上的目录」：保存多台主机、一键镜像远端目录成 DSH 原生工作区，让 Agent 跨网操作远端文件、跑命令、开隧道。

核心能力

• 多主机 SSH 管理：在「设置 → 远程工作区」保存任意数量台主机（host/port/user + 私钥或密码），一键切换当前机；支持私钥口令、OpenSSH Agent、键盘交互（OTP/MFA）、跳板机（ProxyJump）。
• 远程工作区选择器：填充 DSH 原生「Add workspace」流程，弹窗分「本机」和「远程」两个 tab，默认落在本地；切远程后选机器、输入或浏览远端路径即可生成镜像工作区。
• 21 个 rw_* 模型工具：info / connect / pick_workspace / list_dir / stat / read_file / write_file / edit / append / mkdir / remove / move / exec / search / download / upload / sync / push / forward / disconnect；rw_exec 可分配 PTY、设环境变量，rw_edit 带 mtime 乐观锁。
• 双向 SFTP 同步：rw_sync（远端→镜像）和 rw_push（镜像→远端）走三路对比，识别冲突但不覆盖，可 dryRun 预演、async 后台运行、force 覆盖；默认有单文件大小上限、忽略规则（gitignore 语法）。
• SSH 端口转发：本地正向和远程反向隧道，在设置面板或 rw_forward 里增删启停；记入 forwards.json，可设自动重连，连接断开时一并停掉。
• 主机指纹 TOFU 校验：首次连接记录指纹到 known_hosts.json，之后指纹变更立即拒绝；提供 accept-new / verify / off 三档。
• 侧边栏远程文件：自带 dsh-better-sidebar，提供「远程文件」目录树 + 可视化编辑器（含「编辑 → 保存到远程」流程与 mtime 乐观锁保护、409 提示重读）。
• 命令审计日志：所有 rw_exec / 写 / 删 / 移 / 转发操作追加到 audit.log，设置面板里可看最近若干条。
• 可选系统钥匙串存密码：勾选「加密保存密码」时把单台机器密码交 macOS Keychain / Windows DPAPI / Linux secret-tool，失败自动回落明文。
• 自我更新：从 npm 拉版本，支持「manual / auto / off」三档，自动档按可配置间隔静默检查并升级。
• ~/.ssh/config 导入：设置页面列出你 SSH 配置里的 Host 记录，一键回填表单（仅导入配置路径，不读私钥内容）。

技术实现

• 语言: JavaScript (ESM, Node.js)
• 关键依赖: ssh2（SSH/SFTP 客户端，纯 JS 实现无原生绑定）、@deepseek-ai/schemastery（配置 schema 校验）、dsh-better-sidebar（侧边栏 UI，v0.7.2 起硬依赖内嵌挂载）、iconv-lite（GBK 等非 UTF-8 编码读写）
• 架构模式: 双半插件：宿主半（lib/index.js）通过 Cordis inject=['tools','systemPrompt','webServer'] 注册 21 个工具、system-prompt 段落、以及 /dsh-remote/* 16 个 JSON 端点；客户端半（lib/client.js）通过 window.__ModuleLoader__ 注册 React UI（设置页面、远程工作区选择器补全、侧边栏入口），优先级 -100 填充 directory-flow hooks。所有文件操作走 SFTP 协议层，POSIX 和 Windows 远程都支持。
• 入口文件: lib/index.js（宿主半）+ lib/client.js（客户半），搭配 cordis.patch.yml（自动插入本体与侧边栏两行）

适用场景

需要让 DSH Agent 操作远端开发机/部署机/内网服务器上的代码与命令：典型场景是本地编辑代码不方便或文件本身就只在远端；远程构建/部署、运维检查、跨网协作时把远端目录镜像成 DSH 真实工作区。适合需要双击切换多台机器、用私钥或密码登录、跳板进内网、临时开几条 SSH 隧道的用户。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:flymysql/dsh-remote

配置项

本插件无需在安装时手动配置；首次使用在「设置 → 远程工作区」里以图形界面添加主机。cordis.patch.yml 也可声明一台默认主机（详见 README §「可选：CLI 默认机」）。Schema 字段（lib/index.js:55）解释如下：

补充：用户机器清单里还有「privateKeyPath / passphrase / SSH Agent / 跳板机 / 加密保存密码」等表单字段（详见设置页），每条记录可独立覆盖上述字段。

常见问题

Q: 多机器怎么切换？

A: 在「设置 → 远程工作区」列表里点任意机器的「设为当前」即可；切换后该机器上的 workspace 与端口转发一并激活；用 rw_* 工具时也会作用到当前机器。也可用 Model 的 rw_connect 在工具调用里临时换机器（save=false 即不写入清单）。

Q: 远端工作区对应到我机器的哪个本地文件夹？能挪走吗？

A: 默认在 $DSH_HOME/remote-workspaces/<host>-<user>-<port>/<basename>； 重复时追加短哈希。删除该目录仅删本地镜像，不会动远端；要从迁移前的旧位置（~/.dsh/remote-workspaces）找到则自动覆盖。如想自定义镜像位置，可用 rw_download 显式 localPath= 把单文件下载到任意位置。

Q: 能中途改 SSH 私钥/密码吗？改了之后必须重启吗？

A: 不必重启。改完保存设置 → 触发 applyActiveMachine，底层 SshPool.setTarget 会 bump epoch、丢弃旧连接，下次工具调用用新凭据建立新连接；当前活跃 SSH 连接立即失效。

Q: 端口转发重启 harness 后还在吗？

A: 定义在 forwards.json 里，永久保存；勾选「自动启动」的转发在每次连接建立后会被自动拉起。

Q: 同步时两边都改了会怎样？

A: 标记为冲突并保留两侧不被覆盖，控制台报告冲突路径和原因；可在 UI 或工具调用里加 force=true 强行用本地覆盖远端（rw_push）或反之（rw_sync）。

Q: 错误「没有 host + workspace configured — call rw_connect with a host to get started」是什么意思？

A: 插件没拿到任何机器配置；在设置页加主机，或在工具调用里用 rw_connect 临时连一台。

Q: 能从 ~/.ssh/config 复用配置吗？

A: 可以。设置页面有「导入 SSH 配置」按钮，一键回填 Host/HostName/User/Port/IdentityFile/ProxyJump；只导入路径引用，不会读取任何私钥内容。

Q: 端到端的安全风险在哪？

A: 把机器凭据交给本插件，等于让 Agent 以你的身份在远端跑 shell 命令；只添加你信任的机器，并把 audit.log 当敏感数据对待；可在文件系统层收紧 ACL（audit.log / machines.json / .secrets/）。所有远端命令都经过 shell-转义、cd 工作目录也走 shq 引号包裹，单引号直传不展开。

上手难度

入门 — 添加主机、选工作区即用；常见配置（密码/私钥/Agent/跳板）有 UI 表单，模型工具调用也按 rw_list_dir / rw_read_file 这类自然语言动词命名。进阶点（自动同步、端口转发、TOFU 策略）保持默认即可工作。

已知问题与限制

• 本机目录选择器在某些发行版 Linux 上依赖桌面会话里的 zenity / kdialog；纯 CLI 环境（无 dbus）下会报 ENOENT，可直接在输入框手动填路径（lib/index.js:1797-1819）。
• SSH 通道空闲被服务端静默关闭时会偶发 Channel open failure: open failed；0.7.3 起会自动失效旧连接并重连一次。仍偶发时可调高 keepalive/connectTimeoutMs 或主动调 rw_disconnect（lib/index.js:516-523）。
• 同步/搜索有文件大小上限（默认 50 MB）和最大文件数（同步 2000、搜索 500/2000）以避免误拉大文件；可改 maxFileBytes=0 关闭文件大小上限，但不要把同步任务目标指向含数据库或大二进制仓库。
• audit.log 单进程追加、不分卷，长时间使用需要外部 logrotate。
• 0.8.6 修复了设置页底部版本号硬编码问题（之前任何版本都显示 v0.8.3）。
• 0.8.4 修复 dsh 0.1.0-rc.8 加载 0.8.3 时的启动崩溃；升级后请同步升级两者。
• 内嵌 dsh-better-sidebar 自 0.7.2 引入，要求 profile 的 pnpm-workspace.yaml 保持 nodeLinker: hoisted，否则内嵌行无法解析同名包（cordis.patch.yml:5-18 / README.zh.md:61）。

English · 中文

---

dsh-remote

Remote-work assistant for DeepSeek Harness (DSH).

Manage several SSH machines, then pick a remote workspace (or a local one) and let the agent operate right there without leaving the harness — listing files, reading code, running builds & commands over the remote host, and keeping that remote directory mirrored into a real local workspace object.

The harness Web UI intentionally binds 127.0.0.1 (the CLI rejects --host 0.0.0.0 for safety). This plugin goes the other way: you connect out to the machines you maintain, pick a workspace, and work in it through the normal DSH workspace + agent fs flows — no changes to dsh-workspace or the harness core.

Screen previews

Settings → 远程工作区 — a multi-machine SSH registry (add / edit / delete / set-current, password stored locally):

The native "Add workspace" / "Select workspace" flow — a centered modal, two tabs, opens on 本机 (local); switch to 远程 (remote):

• 远程 — a machine <select>, a path field that auto-prefills / and live-completes directories (picking one immediately reveals its next level, OS/VSCode-style), plus a 浏览… floating browser that fills the field without committing — you review, edit, then 设为远程工作区.

Real capture (host scrubbed to a placeholder):

---

Features

• Multi-machine SSH — save any number of hosts (host/port/user + private key or password). Passwords are stored locally and never shown back in the UI. Switch with one click in Settings. Per-machine passphrase / host-key mode / SSH agent / keyboard-interactive (OTP) / proxy jump (bastion) and an optional OS-keychain password (加密保存密码 — macOS Keychain / Windows DPAPI / Linux secret-tool).
• ~/.ssh/config import — the Settings page lists your Host aliases; one click fills the form (path reference only, the plugin never reads key material).
• Two-tab workspace picker (fills the native "Add workspace" flow):
  • 本机 / Local — opens the native OS folder chooser over the host (macOS osascript / Linux zenity→kdialog / Windows FolderBrowserDialog), or lets you type a local path → adopted directly as a normal DSH local workspace.
  • 远程 / Remote — the picker is a centered modal. Pick a machine → the path field is pre-filled with / and live autocompletes directories; selecting a directory immediately lists its next level. A 浏览… floating browser (shows size + mtime, dirs first, follows symlinks) fills the field without committing. 最近 workspaces quick-pick, ~ 主目录 shortcut and 新建目录 are one click away. On confirm it creates a real local mirror under $DSH_HOME/remote-workspaces/<host>-<user>-<port>/<base> that passes fs.realpath → the harness adopts it as a real workspace while dsh-remote keeps it synced over SFTP.
• Bidirectional SFTP sync, conflict-aware — rw_sync (remote → mirror) and rw_push (mirror → remote) are three-way (remote vs local vs last-synced snapshot): files changed on both sides are reported as conflicts and never silently overwritten (force=true overrides). Both support dry-run, background tasks, and honor gitignore-style ignore rules (.dsh-remote-ignore under remote-workspaces, defaults cover .git/node_modules/target/dist/build/…).
• Model tools — 20 tools, all Windows/POSIX portable via SFTP: rw_info, rw_connect (with save), rw_pick_workspace, rw_list_dir (size+mtime), rw_stat, rw_read_file (encoding-aware: utf-8/gbk), rw_write_file, rw_edit (literal replace + mtime optimistic lock), rw_append, rw_mkdir, rw_remove (recursive, bounded), rw_move, rw_exec (pty/env), rw_search (SFTP tree walk — works on Windows too, honors ignore rules, context lines), rw_download/rw_upload (streaming fastGet/fastPut + size caps), rw_forward (SSH tunnels), rw_sync, rw_push, rw_disconnect.
• Port forwarding panel — create/start/stop/remove local (127.0.0.1:port → remote) and reverse (remote → local) tunnels in the Settings page or via rw_forward; definitions persist, auto-restart on reconnect when enabled, all tunnels stop on disconnect.
• Sidebar remote editing — the better-sidebar remote file tab is now editable: click 编辑 → edit → 保存到远程 with an mtime optimistic lock (409 + "重新读取" on concurrent change). The explorer rows show file sizes and have a right-click menu (下载到本地镜像 / 重命名 / 删除 / 新建目录).
• Command audit log — every rw_exec/write/remove/move/forward is appended to $DSH_HOME/remote-workspaces/audit.log (time · user@host · op · exit code · command); the Settings page shows the last 30.
• Async long tasks — rw_sync/rw_push with async: true return a taskId; progress/result/cancel via /dsh-remote/task (single-flight queue).
• Connection health — a 「测试连接」 button validates host/user/key/password (with per-category error hints: auth / network / host key / timeout) before you save a machine; latency is cached on the machine record.
• The active user@host:/path is injected into every system prompt (plus active forwards).
• No official dsh-workspace core is modified — everything is delivered as a normal plugin (directory-flow holes filled by the client half at priority -100).
• Cross-platform remotes — all file access is SFTP-protocol-level (no shell dependency), so Linux/macOS/Windows remotes all work for listing, reading, writing, searching and syncing.
• Host-key verification (TOFU) — every SSH connect verifies the host key (hostKeyMode: accept-new): first connect records it, a later CHANGE is rejected as a possible man-in-the-middle. verify also refuses hosts never seen before; off disables it. Stored at $DSH_HOME/remote-workspaces/known_hosts.json; reset with /remote forget-key.
• Data lives under the harness home — machines + mirrors follow $DSH_HOME; pre-0.6 data under ~/.dsh/remote-workspaces is migrated automatically on first run.

Install

dsh plugin add dsh-remote            # add the bundle

One command installs everything: since v0.7.2 the sidebar (dsh-better-sidebar) is a hard dependency and is mounted automatically — the 🌐 remote-file explorer and remote file viewer show up in the sidebar with no extra step. If you already have the sidebar installed on its own, the embedded copy backs off (no double mount).

Requires the profile's pnpm linker to be hoisted (the DSH profile default, nodeLinker: hoisted in pnpm-workspace.yaml). The loader resolves plugin packages from the profile root, so the sidebar must be reachable in the top-level node_modules. If your pnpm-workspace.yaml was rewritten without nodeLinker: hoisted, add it back (nodeLinker: hoisted) and run pnpm install once — otherwise the embedded sidebar row fails with Cannot find package 'dsh-better-sidebar'.

(or npm install dsh-remote + add - id: dsh-remote / name: dsh-remote in cordis.patch.yml).

Quick start

1. Add a machine — Settings → 远程工作区 → add host/port/user + key or password → (optional) set it current.
2. Open a workspace — click Add workspace in the sidebar / conversation:
   • 本机 → system folder chooser (or type a local path) → local workspace.
   • 远程 → choose the machine → browse to a remote directory (or type /path) → "设为远程工作区" ⇒ a local mirror workspace is created and adopted.
3. Work with the agent — treat it like any workspace:
   • rw_list_dir(path?)/rw_read_file — inspect remote files
   • rw_write_file(path, content) / rw_edit(path, old, new) — create / patch a remote file directly
   • rw_stat(path) / rw_mkdir(path) / rw_remove(path, recursive?) / rw_move(path, dest) — manage remote paths
   • rw_search(pattern, path?) — grep remote files (SFTP walk, Windows OK)
   • rw_exec(command, cwd?, pty?) — run remote shell commands (defaults to the workspace dir)
   • rw_forward(listenPort, targetHost?, targetPort?) — open an SSH tunnel
   • rw_sync(dryRun?/force?/async?) / rw_push(dryRun?/force?/async?) — conflict-aware mirror pull/push

CLI defaults (optional)

Provide a default machine in cordis.patch.yml:

# Example only — use values for your own machine.
- id: dsh-remote
  name: dsh-remote
  config:
    host: 203.0.113.10   # or your real host / hostname
    port: 22
    username: dev
    privateKeyPath: ~/.ssh/id_rsa
    # or password: '…'
    workspace: ~/project

If host is empty the plugin starts disconnected and you configure machines in the UI.

CLI quick reference

Installing and driving DSH may live in different shells, so both the dsh binary and the npx form are shown. Always tell DSH which profile to use with --profile <name> (usually web).

# install the bundle into a profile (npm is pulled by pnpm; recommended)
dsh plugin --profile web add dsh-remote
# same but when `dsh` is not on PATH (e.g. Windows PowerShell inside a repo)
npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote

# confirm it is installed wire
dsh plugin --profile web list
npx --yes @deepseek-ai/dsh plugin --profile web list

# start the web surface (reload profile; the plugin activates on boot)
dsh --profile web
npx --yes @deepseek-ai/dsh --profile web   # http://127.0.0.1:3080

# use a local checkout instead of the npm version (dev iteration)
npx --yes @deepseek-ai/dsh plugin --profile web add /path/to/dsh-remote
npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # back to release

After a successful start, Settings → 远程工作区 appears and the "Add workspace" flow gains the 本机 / 远程 tabs (screenshots above).

Development (sandbox, not product)

Iterate in the sandbox, never by hand-editing a product profile — the product profile is re-managed by the plugin manager and reverts hand-deployed files on reinstall. Use the helper script:

scripts/dev-run.sh --restart   # start / restart the isolated sandbox
scripts/dev-run.sh --stop      # stop it
scripts/dev-run.sh --status    # is it running?

• Runs its own DSH instance (dev-harness/harness inside this repo) with the plugin copied in from lib/ — it boots through the same bin.js web --patch path as the desktop app, so the sandbox reproduces the product boot behavior.
• The sandbox web UI serves on http://127.0.0.1:50599 and the plugin routes are live immediately (e.g. GET /dsh-remote/machines).
• Host-half changes (lib/index.js) need a sandbox restart (--restart); client-half changes (lib/client.js) need a page refresh.
• Node ESM resolves dependencies from the importing file's real path, so the script copies lib/ (hardlink copy, cp -al) into the sandbox profile instead of symlinking — a symlink breaks @deepseek-ai/* resolution.
• Run scripts/check.mjs (static framework-constraint gate: command-name regex, …) before every commit; scripts/boot-smoke.sh boots an isolated instance to prove the plugin still starts.
• Full rules live in scripts/dev-standards.md (command names, cordis service access via ctx.get() only, optional framework services may never register, verify third-party callback contracts against the real runtime, …).

Deploying to a product profile is a separate, explicit action (./sync.sh) and should be done only when you intend to release.

Configuration

FAQ / troubleshooting

Host key 变了 / 提示可能中间人 — 主机重装过或密钥更换过：/remote-forget-key（或设置页 → 机器 → 重新信任），下次连接重新记录。

连接报"认证失败" — 检查用户名/密码/私钥路径；私钥加密了要填 Passphrase；公司机器要求 OTP/动态码时勾选 keyboard-interactive。

连不上内网机器 — 走跳板机：机器表单里填「跳板机」主机（也可以先把它本身配成一台机器）。主机不可达类错误会给出分类提示。

rw_sync/rw_push 报冲突 — 远端和本地都改过同一个文件时会跳过并列出冲突（绝不静默覆盖）。处理：手动合并后重新同步，或用 force=true 以一边为准。

Windows 远程 — 列表/读写/搜索/同步全部走 SFTP 协议，不依赖 POSIX shell；中文文件用 encoding=gbk 读。

镜像里没有某个目录 — 默认 ignore 规则（.git、node_modules、target 等）会跳过；在 $DSH_HOME/remote-workspaces/.dsh-remote-ignore 加 ! 之外的条目即可调整（gitignore 语法）。

侧边栏远程文件保存失败（409） — 远端文件在你打开后已被改动，重新读取后再编辑（mtime 乐观锁保护）。

密码怎么加密保存 — 机器表单勾选「加密保存密码」：macOS 用系统钥匙串（security），Windows 用 DPAPI，Linux 需要 secret-tool（libsecret）；后端不可用时自动回退明文。

Safety

Giving the plugin a machine's credentials lets the agent run shell commands as your user on that host. Only add machines you trust. Passwords are saved on the local machine file (or the OS keychain when enabled); treat it as sensitive (you may lock file ACLs). Every executed command is recorded in the audit log when auditLog is on — review it from the Settings page.

License

MIT

Changelog

See CHANGELOG.md.