远程工作区 MingTXin/dsh-remote-workstation

dsh-remote-workstation

把远程服务器目录挂进 DeepSeek Harness 侧栏工作区（阶段 2：可读写 + 远端命令/搜索工具）。

插件做三件事：

1. 替换文件系统提供方：ctx.fs 由本插件提供，落在「锚点目录」下的路径全部转成 SFTP 访问远端；其余路径仍走本地磁盘（继承 SandboxedFileSystem，沙箱围栏不变）。
2. 提供 Remote Explorer 侧栏面板：浏览器侧注册 sidebar.panellist 图标 + main 页面，用 JSON API（/api/remote-workspace/）浏览远端目录。
3. 锚点工作区：DSH 的工作区必须是宿主真实目录，插件在 ~/.dsh/remote-workspaces/<host>/<远端路径> 建本地空锚点目录，并把「锚点 → 远端」的映射写进 ~/.dsh/remote-workspaces.json。把锚点加为工作区后，右侧 Files 标签与文件预览就会显示远端内容。

安装

装进 DSH 的某个 profile（通常 web）：

1) 从 npm（需要先发布，见 PUBLISHING.md）
dsh plugin --profile web add @<你的npm账号>/dsh-remote-workstation

2) 直接从 GitHub 装（不用发 npm）
dsh plugin --profile web add github:<你的GitHub账号>/dsh-remote-workstation

3) 本地开发：link 掉本仓库
dsh plugin --profile web add link:<本仓库的绝对路径>

github: 与 npm 方式都会跑一次 pnpm 安装并把本包追加到该 profile 的 dsh.profile.bundles；link: 只建符号链接，改代码后重启宿主即生效。

⚠️ 影响范围：本插件的 bundle patch 会禁用 fs-sandbox 行，并在同一服务名上挂自己的 ctx.fs（继承 SandboxedFileSystem，沙箱围栏不变）。因此装进哪个 profile，哪个 profile 的所有会话都变成「本地 + 锚点」联合文件系统；不装的 profile 不受影响。

重启 DSH Desktop（或 dsh web）后，左侧栏出现「远程」按钮。

想先在不影响主 GUI 的情况下试：复制一个 profile，指向同一份 node_modules，单独起一个宿主：

Copy-Item ~\.dsh\profiles\web\package.json,~\.dsh\profiles\web\cordis.patch.yml,~\.dsh\profiles\web\pnpm-workspace.yaml ~\.dsh\profiles\rwtest\
cmd /c mklink /J "$env:USERPROFILE\.dsh\profiles\rwtest\node_modules" "$env:USERPROFILE\.dsh\profiles\web\node_modules"
dsh --profile rwtest --port 43199 --no-open # 打开它打印的 http://127.0.0.1:43199/?token=...

使用

从「远程」面板挂载

1. 左侧栏点「远程」。
2. 顶部下拉选主机（主机来自两处：本插件自己的 ~/.dsh/remote-workspaces-hosts.json 优先，其次 @linxin666/dsh-ssh 的 ~/.dsh/dsh-ssh.json；带 jump host 的配置不参与本插件的直连）。
3. 浏览目录：单击文件夹进入，「上一级」返回，路径框可直接输入后回车。
4. 目标目录上点 挂载为工作区：插件在 ~/.dsh/remote-workspaces/<host>/<远端路径> 创建锚点、写入映射，并调用 workspaces.create 注册成工作区（已存在则提示）。
5. 在左侧工作区列表里打开这个工作区（标题形如 my-server:/srv/project），右侧 Files 标签即可看到远端文件、点开预览。

主机管理（插件自带，不需要 dsh-ssh）

「远程」面板底部有 主机（N） 区：

- 每行显示 别名、host:port、用户，以及来源徽章：插件（本插件自己的存储）/ dsh-ssh（从 ~/.dsh/dsh-ssh.json 现读）。
- 测试 连一次远端并 realpath('.')，返回 home 目录与耗时；失败会显示原始错误（超时/鉴权/主机名）。
- 添加主机：别名、主机、端口、用户、认证方式（密码 / 私钥 / 无凭据走 SSH_AUTH_SOCK agent）、密码或私钥路径（+ 可选 passphrase）。保存后无需重启，下一次浏览/挂载即用新主机。
- 编辑 / 删除 只对来源为 插件 的主机开放；dsh-ssh 的主机请去那边的配置改（本插件不越权写别人的文件）。
- 别名同时存在于两处时，插件里的定义胜出（可用来给同一台机器换端口/换账号/换私钥）。

凭据存在 ~/.dsh/remote-workspaces-hosts.json，明文，写盘时按 0600 处理（Windows 上 NTFS ACL 不受 mode 影响，请自行保证用户目录权限）：

{
"version": 1,
"hosts": [
{
"alias": "build-box",
"host": "10.20.0.5",
"port": 22,
"user": "dev",
"auth": { "kind": "password", "password": "..." }
}
]
}

想把主机写进 profile 的 patch 行也可以，但密码会进 cordis.patch.yml，不推荐；sshHostsPath 可指向任意 ssh 主机文件（同 dsh-ssh.json 格式），因此插件既能自给自足，也能复用 dsh-ssh 的主机表。

为什么「工作区」标题行的 ＋ 里没有「远程」这一项

＋ 走的是上游 single 槽 sidebar.workspaces.directoryFlow，只有一个占位者。
本插件最初接管过它（＋ 卡片里多出「🖥 远程服务器目录…」），但 Windows 桌面的启动层（C:\Program Files\DSH Desktop\resources\app\lib\profile-.js 的 launcher 层，在插件 patch 之后才执行）会固定插入 @deepseek-ai/dsh-client-ui-directory-picker-browse 作为该槽的占位者：

- 插件抢到槽 ⇒ 内置目录选择器注册时抛 single slot "..." already has a registration ⇒ 整个客户端 boot 失败（界面报 Renderer boot failed for 1 plugin(s)，日志点名 browse 选择器）
- 插件让出槽 ⇒ ＋ 只能浏览本机目录

所以 v0.1 不接管该槽，只提供「远程」面板。真要把远端目录塞进 ＋ 卡片，可行但侵入性更大：在 ~/.dsh/profiles/web/node_modules/@deepseek-ai/ 下放一个同名的 dsh-client-ui-directory-picker-browse（影子包），替换它的 UI 并加上「远程」标签页；代价是每次升级 DSH 都要重新对齐上游实现。

注意：

- 远端可写（0.3.0 起，remoteReadOnly 默认 false）：write/edit 工具经同一个 ctx.fs 契约落到远端——createIfAbsent、按版本令牌的 replaceIfVersion（版本过期报 FS_STALE_VERSION）、字面量 editText（多处命中未 replaceAll 报 FS_AMBIGUOUS_EDIT）；沙箱围栏照旧（read-only 拒、workspace-write 限锚点子树 + /tmp、danger-full-access 放行）。想维持只读就把 remoteReadOnly 设回 true。
- Files 标签的自动刷新不可用（watch 在远程不可用，会返回 workspace-file/watch-unsupported）。手动刷新方式：收起再展开该目录，或重新打开文件。
- @ 文件提及、回合 diff（git）仍走宿主本地路径，不会看到远端内容；这是上游按设计保留的边界（docs/subsystems/ssh.md："Web workspace views that assume host filesystem access need separate integration"）。
- 远端连接超时默认 15s，可在 loader 行 config 里调 connectTimeoutMs。
- 锚点工作区里的会话，cwd 是本地空锚点目录：读文件/读写/列目录/Files 标签走 ctx.fs（到远端），但 bash/terminal 工具与内置 glob/grep 仍在本地执行（ripgrep 跑在宿主、锚点目录是空的）。0.3.0 起插件自带两个工具：remote_exec（在远端跑命令，返回 exitCode/stdout/stderr/durationMs，可带 cwd）与 remote_search（远端递归 grep -rInE，返回 path:line: text），无需再依赖 dsh-ssh。
- 凭据存储：~/.dsh/remote-workspaces.json（挂载表）只存 alias/host/port/user；凭据来源有两处——本插件自己的 ~/.dsh/remote-workspaces-hosts.json（面板里添加的主机，明文、0600），以及 ~/.dsh/dsh-ssh.json（dsh-ssh 的主机表，现读）。两者都没有该主机时不会静默退化成 agent 鉴权，而是直接报 remote workspace: no credentials for host "<alias>" — add a password or a private key for it in the DSH SSH host store (~/.dsh/dsh-ssh.json, 侧栏「远程」→ 主机列表来自该文件) （旧版会报 All configured authentication methods failed）。
- 改了插件代码之后：客户端 bundle 变化 → 刷新页面（Ctrl+R）即可；宿主侧（ctx.fs 提供方）变化 → 必须重启 DSH Desktop / dsh web 宿主进程。桌面版有 patchReload: live，但只对配置行生效，不会因插件源码变化重载宿主侧。
- v0.1.1 已知回归修复：0.1.0 曾接管 sidebar.workspaces.directoryFlow，在 Windows 桌面会导致内置 browse 目录选择器注册失败、整页 Renderer boot failed for 1 plugin(s)。0.1.1 移除了该注册，仅保留「远程」面板；如仍看到该报错，请确认 lib/client.js 里不再含 directoryFlow，并彻底退出重开 DSH Desktop。
- 主机凭据改动后：不用重启，插件在下一次连接时现读 ~/.dsh/dsh-ssh.json；挂载表文件被外部改动也会自动重载。

验收记录（2026-10-24，真实 DSH 宿主）

隔离宿主：复制 web profile 到 ~/.dsh/profiles/rwtest（node_modules 用 junction 指向 web），dsh --profile rwtest --port 43199 --no-open 启动。

| 检查 | 结果 |
| 插件 host 半边加载 | 无报错（/api/remote-workspace/ping 返回 {service:'remote-workspace'}） |
| 客户端半边进 boot roster | 首页 preload 清单里含 dsh-remote-workstation/client.js |
| 经 ctx.fs 读远端（read 动作） | targetKey = rw://my-server/tmp/dsh-remote-workspace-fixture/hello.txt，39 字节 |
| typert workspace/create 用锚点建工作区 | 成功，workspaceId=f10562b9-…，path = 锚点目录 |
| session/create（cwd=锚点）→ workspaceFiles/list | 返回远端条目：big.txt 200000、binary.bin 64、hello.txt 39、sub/ |
| workspaceFiles/read（Files 标签预览） | 返回远端文本，version 令牌 0:0:39:1792810431000:1792810431000（远端派生，本地文件不会有这种形状） |
| 子目录 sub 列表 | notes.md 31 字节（锚点子路径映射正确） |
| 同宿主 cwd=D:\WorkStation 的会话 | 仍正常列出本地目录（无回归） |
| 凭据 | 存储文件无 password/passphrase/keyPath |
| 凭据现读（把 pool 内存记录故意剥掉 auth 后再连） | 连接成功，entries: big.txt,binary.bin,hello.txt,sub；未知主机报 no credentials for host ... |
| 主机凭据改动后自动重载 | 改 dsh-ssh.json 密码 → refresh() 后池内记录变为新密码 |
| 自有主机存储（0.2.0） | hostSave → {alias:'verify-box',host:'192.0.2.9',port:2200,user:'dev',source:'plugin'}；hosts 同时列出插件主机与 dsh-ssh 主机（带 source 字段），hostRemove 删除插件主机 |
| 自有主机优先 | 同名 alias 在插件存储里覆盖 dsh-ssh.json 的连接参数与凭据 |
| hostTest 错误面 | 不可达主机 → 400 cannot connect to "verify-box" (dev@192.0.2.9:2200): connection timed out after 15000 ms |
| 单元测试 | node --test 21 例（离线默认 18 通过 + 3 例 SSH 集成用例自动跳过；设 DSH_RW_REMOTE_HOST 可全跑） |
| 客户端 bundle 服务端可解析 | plugins/??dsh-remote-workstation/client.js&rev=… → 200、20 KB、new vm.Script() 通过 |

配置（cordis.patch.yml 的 loader 行）

- id: fs-sandbox
disabled: true
- insert:
- id: remote-workspace
name: dsh-remote-workstation
config:
storePath: ~/.dsh/remote-workspaces.json # 挂载表 sshHostsPath: ~/.dsh/dsh-ssh.json # 主机来源之一（dsh-ssh 的配置） hostsPath: ~/.dsh/remote-workspaces-hosts.json # 插件自有主机表（面板「主机」区维护，含明文凭据、0600） anchorRoot: ~/.dsh/remote-workspaces # 锚点目录根 remoteReadOnly: false # true = 拒绝一切远端写入 enableTools: true # 注册 remote_exec / remote_search connectTimeoutMs: 15000 maxReadTextBytes: 33554432 # 单次 readText 上限 32 MiB 也可以静态声明挂载（不落盘）： mounts:
- host: my-server
remote: /srv/project

必须把 fs-sandbox 这一行禁用：ctx.fs 服务一个组合只能有一个提供方（dsh-base/README.zh.md），本插件的提供方已经继承了它的沙箱围栏。

限制与后续阶段

- 阶段 2（0.3.0 已实现）：writeText / editText（SFTP 写入 + mtime/size 版本令牌 + 原子替换语义）、remote_exec 与 remote_search 工具（内置 glob/grep 走宿主 ripgrep 二进制，不经过 ctx.fs，因此远端目录要用插件工具）。
- 阶段 3：watch 轮询、git 集成、图片/二进制预览。
- 已知边界：远端无 watch；SFTP 的 mtime 精度为秒；processPath() 返回锚点宿主路径（因此「在文件管理器中打开」可用）。