前言¶
在 DSH 里做智能体开发，文件读写、shell、搜索和变更追踪通常都落在本机工作区。若代码和构建环境在远程 Linux 服务器或云主机上，常见做法是 rsync/scp 同步、网络盘挂载，或 SSH 进机器另开一套编辑器。这些路径要么多一步同步，要么依赖第三方文件系统，DSH 的 read / write / edit 与沙箱语义也难以直接延伸到远端目录。
下面介绍社区插件 dsh-ssh-workspace（维护者 siqyka，GitHub：siqyka/dsh-ssh-workspace）。它在 DSH 的 ctx.fs（@deepseek-ai/dsh-fs）抽象上增加「远端半边」：通过 SFTP 读写远端文件，shell、ripgrep、git 等落在远端主机执行，无需手动同步、挂载驱动或安装第三方文件系统。插件归类为 SkillHub 目录下的「联网工具」。
这是什么¶
dsh-ssh-workspace 把一台 SSH 主机上的目录登记为 DSH 工作区。工作区路径语法为：
ssh://<主机别名>/<远端绝对路径>
例如 ssh://myserver/home/user/project
界面里同类路径会显示为 ssh://<主机别名>@/<远端绝对路径>（别名后插入 @），便于阅读；复制与挂载、文件操作、工具调用仍使用实际拼写 ssh://<主机别名>/<远端绝对路径>。
DSH 工具层（read / write / edit / bash / glob / grep、变更面板等）经 ctx.fs 路由：ssh:// 前缀走本插件的 SFTP 后端，其余路径仍走部署原有的本地（沙箱）后端。本地工作区的沙箱写入围栏、版本守卫、原子写入等行为保持不变；远端工作区使用同一套工具与错误语义。
核心功能¶
SFTP 直通与文件语义¶
read/write/edit全程走 SFTP，支持完整错误语义（如FS_STALE_VERSION、FS_NOT_OBSERVED、FS_AMBIGUOUS_EDIT、FS_NOT_FOUND等）。- 原子写入：先在同目录写暂存文件再替换；优先
posix-rename@openssh.com，不支持时退化为先删后改名。 - 远端写入仅允许落在已挂载的远端工作区内，越界返回
FS_OUTSIDE_WORKSPACE；「仅可查看」模式会阻止远端写入（FS_SANDBOX_DENIED）。读取不受此限。 - 大文件按 256 KiB 块流式读取；远端目录变更优先用
inotifywait推送，未安装时回退轮询。
远端执行¶
- 会话工作区为
ssh://时，pwsh/bash在远端以 POSIX shell 语义执行；glob/grep调用远端主机上的rg（未安装时明确失败，退出码 127）。 - 「变更」面板用远端
git做快照与 diff；远端未装 git 时自动降级关闭，其余功能不受影响。
界面与 Agent 工具¶
侧栏提供文件树、@ 远端文件引用、拖拽进任务、主机管理面板、浏览目录对话框，以及上传/下载等。重启客户端后会从持久化 registry 自动重新挂载已登记的远程工作区。
插件向 Agent 暴露的工具包括（完整参数见仓库 docs/tools.md）：
| 工具 | 用途 |
|---|---|
ssh_workspace_hosts |
列出可用主机 |
ssh_workspace_mount / unmount / enable |
挂载、停用、重新启用远端工作区 |
ssh_workspace_status |
挂载列表与连接状态 |
ssh_workspace_exec / shell |
远端执行命令（shell 可跨调用保留状态） |
ssh_workspace_transfer |
本机与远端 SFTP 传文件 |
ssh_workspace_forward / unforward |
端口映射 |
安装与启用¶
环境要求（见仓库 README 与 package.json）：Node >= 20，DSH >= 0.2.0-rc.1，依赖 ssh2 ^1.17.0；许可证 MIT。
- 打开 DSH 官方桌面客户端，进入「设置」中的「插件」页面（或左侧导航栏的插件入口）。
- 在插件管理界面的安装输入框中二选一，点击安装：
- npm 包（支持锁定版本）：
@shiqyka/dsh-ssh-workspace
或指定版本，例如：
@shiqyka/dsh-ssh-workspace@0.2.6
- 仓库地址：
https://github.com/siqyka/dsh-ssh-workspace
- 安装完成后重启客户端。
插件配置项（通常使用默认即可）：
| 字段 | 默认 | 含义 |
|---|---|---|
enabled |
true |
总开关 |
announceToAgent |
false |
是否向 agent 注入能力说明 |
engine.idleTimeoutMs |
1800000 |
连接空闲回收时间（毫秒） |
engine.connectTimeoutMs |
15000 |
SSH 握手超时 |
engine.keepaliveIntervalMs |
15000 |
keepalive 间隔 |
engine.sweepIntervalMs |
60000 |
空闲连接扫描周期 |
典型用法¶
经过上面的安装与重启，可按以下流程使用：
- 在「远程工作区」面板确认或添加主机（首次使用可在此添加）。
- 选择「添加工作区 → 新建远程工作区」，选定主机、浏览远端目录并挂载。
- 在该工作区新建会话；文件读写、shell、搜索与变更追踪会自动落到远端。
主机记录默认存放在 $DSH_HOME/dsh-ssh.json；若无该文件，会只读回退读取 ~/.ssh/config 里具体的 Host 块，已配好的 SSH 主机通常无需重复填写。密码与私钥口令加密保存在 dsh-ssh.json 的 secrets 段，不会回传到浏览器。
每个主机别名维持一条长连接（常开 SFTP 通道）；空闲约 30 分钟回收。首次连接采用 TOFU 记录主机密钥指纹，指纹变更会拒绝连接，可在面板「忘记主机密钥」后重新信任。
适用场景与注意¶
适合：开发机与运行环境分离、需要在 DSH 里直接改远端项目、在远端跑构建/测试/git diff，又不想维护同步脚本或 FUSE 挂载的用户。
明确限制（见 README「限制」）：
- 不支持跳板机 / ProxyCommand：引擎仅直连目标主机；带
proxyJump/ProxyCommand的主机会在解析时被拒绝并说明原因。 - 会话工作区为
ssh://时，shell 在远端以登录用户权限运行，不受本机文件沙箱约束；本地workdir的命令仍在本机沙箱内。
DSH 社区插件由维护者独立发布；SkillHub 目录页（dsh-ssh-workspace）与 GitHub 仓库并非 DeepSeek / 幻方官方应用商店。安装前建议查看源码与 MIT 许可证，确认插件以当前 DSH 进程权限运行，主机凭据存储策略是否符合你的安全要求。
链接¶
- 目录页：https://www.skillhub.cn/plugins/siqyka/dsh-ssh-workspace
- 仓库：https://github.com/siqyka/dsh-ssh-workspace
- npm：https://www.npmjs.com/package/@shiqyka/dsh-ssh-workspace
