@shiqyka/dsh-ssh-workspace

dsh plugin --profile web add @shiqyka/dsh-ssh-workspace

<div align="center">

<img src="https://raw.githubusercontent.com/siqyka/dsh-ssh-workspace/main/docs/assets/header.png" alt="dsh-ssh-workspace header" width="840" />

dsh-ssh-workspace

把一台 SSH 主机上的目录，当作 DSH 工作区使用。

read / write / edit 通过 SFTP 直接读写远端文件——

不需要手动同步、不需要挂载驱动、不需要装任何第三方文件系统。



简体中文 · English

</div>

---

<table>

<tr>

<td align="center" width="33%">

SFTP 直通

读写编辑全程走 SFTP，

完整错误语义 + 原子写入

</td>

<td align="center" width="33%">

远端执行

shell / ripgrep / git

都落在远端主机上跑

</td>

<td align="center" width="33%">

界面集成

文件树、@ 引用、拖拽进任务、

主机管理面板，开箱即用

</td>

</tr>

</table>

目录

• [概览](#概览)
• [快速开始](#快速开始)
• [主机管理](#主机管理)
• [配置](#配置)
• [Agent 工具](#agent-工具)
• [能力一览](#能力一览)
• [限制](#限制)
• [实现要点](#实现要点)
• [文档索引](#文档索引)
• [许可证](#许可证)

概览

工作区路径语法：

ssh://<主机别名>/<远端绝对路径>
例如  ssh://myserver/home/user/project

界面里这类路径显示为 ssh://<主机别名>@/<远端绝对路径>（别名后插入 @，

读起来像 SSH 地址）——侧栏工作区行的悬停卡片、右侧栏「文件」面板头部、

文档预览头部等处都是这种显示；复制与一切功能（挂载、文件操作、工具调用）

使用的仍是实际拼写 ssh://<主机别名>/<远端绝对路径>。

它解决什么问题

DSH 的所有文件操作都走 ctx.fs（@deepseek-ai/dsh-fs）这一个服务抽象。

本插件在这个抽象上增加了一个「远端半边」：

        DSH 工具层（read / write / edit / bash / glob / grep / 变更面板）
                                   │
                              ctx.fs 路由
                                   │
            ┌──────────────────────┴──────────────────────┐
            │                                             │
   ssh://<alias>/<path>                        其他任何路径（E:\…、/home/…）
            │                                             │
   本插件的 SFTP 后端 ──► SSH 主机              部署原有的本地（沙箱）后端

因此本地工作区的一切照旧，包括沙箱写入围栏、版本守卫、原子写入；

远端工作区则获得同一套工具和同一套错误语义。

快速开始

1. 安装：打开官方桌面客户端，进入「设置」中的「插件」页面（或左侧导航栏的插件入口）；

2. 输入来源：在插件管理界面的安装输入框中二选一，点击安装：

• npm 包（走 npm 分发，支持锁定版本）：

@shiqyka/dsh-ssh-workspace，或指定版本

@shiqyka/dsh-ssh-workspace@0.2.8

（npm 页面）；

• 仓库地址（从 Git 取最新代码）：

https://github.com/siqyka/dsh-ssh-workspace

（这种方式由插件管理器代为安装依赖；手动 clone 后 link 进 profile 才需要看下一节）

3. 重启：安装完成后重启客户端，即可开始使用。

之后的使用流程：

「远程工作区」面板确认主机（首次可添加）
        │
        ▼
「添加工作区 → 新建远程工作区」选主机、浏览远端目录并挂载
        │
        ▼
在该工作区里新建会话 —— 文件读写、shell、搜索、变更追踪自动落到远端

从源码仓库使用

git clone https://github.com/siqyka/dsh-ssh-workspace.git
cd dsh-ssh-workspace
npm ci          # ssh2 是直接依赖，不随 clone 到位

装完重启客户端即可。

主机管理

主机记录存放在 $DSH_HOME/dsh-ssh.json；没有该文件时，会退回到读取

~/.ssh/config 里具体的 Host 块。因此已经配好的主机无需重复配置。

「远程工作区」面板里可以直接添加 / 编辑 / 删除主机，写回

$DSH_HOME/dsh-ssh.json（原子写入，保留文件里本插件不认识的字段）。

~/.ssh/config 中的主机是只读回退，面板不会修改那个文件；

与存储同名的主机以存储为准。密码 / 私钥口令加密保存在 dsh-ssh.json 的

secrets 段（AES-256-GCM，密钥是 $DSH_HOME/dsh-ssh.key，仅本用户可读），

且不会回传到浏览器，编辑时留空表示保持原值。

删除主机不会自动卸载已挂载的工作区，但那些工作区会因主机不存在而无法访问。

存储格式、~/.ssh/config 解析规则与凭据策略细节见 docs/hosts.md。

配置

字段 · 默认 · 含义

enabled · true · 总开关

announceToAgent · false · 是否向每个 agent 注入能力说明（系统提示词段落）

allowLan · false · 局域网部署：浏览器的 HTTP 路由接受私网来源地址（IPv4 RFC1918、IPv6 ULA/链路本地）

allowedHosts · [] · 额外放行的 Host 值（配合 allowLan，如面板经局域网主机名访问时）

engine.idleTimeoutMs · 1800000 · 连接空闲超过该时长后回收（毫秒）

engine.connectTimeoutMs · 15000 · 单次 SSH 连接握手超时（毫秒）

engine.keepaliveIntervalMs · 15000 · keepalive 心跳间隔（毫秒）

engine.sweepIntervalMs · 60000 · 空闲连接的扫描周期（毫秒）

engine.reconnect · 见下 · 断线后的后台重连策略；传 false 退回「只在操作时重连一次」

engine.reconnect.baseDelayMs · 1000 · 首次重试的等待（毫秒），之后按 2 的幂增长

engine.reconnect.maxDelayMs · 60000 · 单次等待的上限（毫秒）

engine.reconnect.maxAttempts · 0 · 最多尝试次数；0 表示不限次数

engine.reconnect.jitter · 0.2 · 向下抖动的比例，用来避免多主机同时重连；不会超过上限

engine 下各项均为可选（非法值回落默认），通常无需配置。

局域网部署（allowLan）

默认只接受本机回环访问（127.0.0.1 / ::1 / localhost）。webserver 绑定

0.0.0.0、浏览器从局域网另一台机器访问时，请求会被 forbidden: loopback-only

拒绝——这是防 DNS-rebinding 的围栏，不是故障。设 allowLan: true 后：

• 来源地址放宽到私网地址（IPv4 10/8、172.16/12、192.168/16；IPv6 ULA

fc00::/7 与链路本地 fe80::/10），公网地址仍被拒绝；

• Host 头必须命名本机真实监听地址（由本机各网卡地址 + 端口拼出，回环拼写

始终有效），不匹配的 Host 仍以 forbidden: unexpected Host header … 拒绝——

防 rebinding 语义原样保留；

• 若面板经一个本机网卡不知道的名字访问（局域网主机名、反代拼写），把它加进

allowedHosts（大小写与首尾空白不敏感，可带端口也可不带）；

• POST 的 JSON content-type 校验、405/415 等其余防护不变。

安全语义的完整说明见 SECURITY.md。

Agent 工具

工具 · 用途

ssh_workspace_hosts · 列出可用主机（store + ~/.ssh/config 候选）

ssh_workspace_mount · 把一个远端目录登记为工作区，返回 ssh:// 路径

ssh_workspace_unmount · 停用远端工作区（默认保留记录与会话，可逆；勾选「同时删除记录」才归档会话并删除记录）

ssh_workspace_enable · 重新挂载被停用的工作区并取消归档其会话

ssh_workspace_status · 当前挂载 / 停用列表、连接、转发与持久会话状态

ssh_workspace_exec · 在远端执行 shell 命令（可 run_in_background）

ssh_workspace_shell · 在持久远端 shell 里执行命令，状态跨调用保留

ssh_workspace_transfer · 本机 ↔ 远端传文件（SFTP，不经对话内容）

ssh_workspace_forward · 把远端端口映射到本机，返回可打开的 URL

ssh_workspace_unforward · 关闭端口映射并释放本地端口

工具的参数、返回字段与错误语义详见 docs/tools.md。

能力一览

完整的按域清单（含依赖、降级与边界）见 docs/features.md。

远端文件

能力 · 说明

完整错误语义 · read / write / edit 全程走 SFTP，含 FS_STALE_VERSION、FS_NOT_OBSERVED、`FS_AMBIGUO

…(truncated)