Skip to content

dsh-over-ssh

Verified

dsh-over-ssh · v0.3.2 · MIT · Web UI

SSH remote development for DeepSeek Harness: connections (key/password/ProxyJump/ssh config), remote files without sync, remote terminal, remote workspaces, remote @-completion, upload/download.

Install

dsh plugin add dsh-over-ssh

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Creators

Readme

dsh-over-ssh

DSH(DeepSeek Harness)第三方插件:把 VSCode Remote-SSH 式的远程开发做进 DSH —— 连接管理(密钥 / 密码 / ProxyJump / ~/.ssh/config 导入)、远程文件(无同步直读直写)、远程终端、远程工作区、远端 @ 补全、上传/下载,并支持"本地根 + 远端根"同处一个工作区。

设计依据:doc/01-product/02-技术设计-SSH远程开发插件.md(v0.2)。需求依据:doc/01-product/01-需求分析-多根工作区-远程根-会话管理.md(v0.4)。文档知识库入口:doc/README.md。

安装

从 npm(发布后):

dsh plugin --profile web add dsh-over-ssh     # 等价于在该 profile 目录里 pnpm add

从源码(本仓库开发时):

npm i && npm run build
dsh plugin --profile web add /绝对路径/dsh-over-ssh

GUI 安装提示:pnpm 会问是否允许安装脚本,列表里是 ssh2 与 cpu-features:允许后重试即可。 它们是 ssh2 传输的可选原生加速,拒绝会让 pnpm 中止本次安装(插件源码本身没有安装脚本)。

0.2.2 及更早在运行中的页面上启用插件时出现过 2 entries did not activate(workingDirectory / fileReferences 链);0.2.3 删掉了那条私有域克隆链(审计 0134),不再需要为它重启。

远端终端要额外配一次 terminalController.Config.shell——Config.shell 是静态单值,连哪台只能由 wrapper 运行时决定:

装法 指向
npm node_modules/dsh-over-ssh/lib/terminal-wrapper.js(单文件,内部模块已内联)
源码 tools/over-ssh-terminal.ts(Node 24 直接跑 TS)
shell:
  path: node
  name: SSH / Local
  args: ['<上面那个路径>', '--name', 'gpu01']

不配也能用,只是 Web 终端永远开在本地(远程文件、远端执行、@ 补全不受影响)。

工具选择速查(0.3.2)

想做的事 用哪个工具 说明
看清"本会话能干什么" remote_status 连接、root 是否可见、写闸、scratch 路径、超时、能力/版本、时钟偏移;任何不可用项都给原因 + 下一步
读/改文件 remote_file op:read / read_many / read_glob / write / write_many / edit / patch / apply_patch / stat / ls / move / mkdir / chmod;带版本守卫、原子写、无需转义
搜内容 / 找文件 remote_grep / remote_glob 支持 include/exclude、contextLines、分页、mode: files/count;比 remote_exec rg 更安全(有结构化结果与上限)
跑命令 remote_exec command(单条)、script(安全落盘执行,无引号事故)、steps(分步,一次往返);maxLines、redact、failureKind
长时间跑 remote_exec + waitMs,之后用 remote_job waitMs: 0 启动即返回;waitMs: 30000 最多等 30 s,没跑完给 jobId;需要一个工具就够。后台作业需要 Tier 2 代理;Tier 1 前台超时由远端 timeout -s KILL 收尸
传文件 remote_transfer 单文件/批量,下载校验 expectedSha256;目录用 remote_copy(远端→远端)
访问远端服务 remote_forward 远端端口 → 本机 127.0.0.1;远端 HTTP 服务用这个范式,不需要新工具
看 agent 做过什么 remote_log 进程内审计环(最近 500 次变更类调用,命令行摘要已脱敏)
多会话协作同一 root remote_lock 进程内租约;只保护同一 DSH 进程内的会话,跨进程/跨用户无效

remote_exec 与版本守卫的边界(必读)

remote_exec 里的 shell 不受 remote_file 的版本守卫约束:sed -i / python3 写文件不会触发 expectedVersion,也不会先读版本。要保留守卫就用 remote_file 的 edit/patch/apply_patch/write(它们按 version 拒绝覆盖别人刚做的改动)。用 remote_exec 改完关键文件后,建议用 remote_file op:"stat" 复核版本,或在提交前 git diff。部署若需要更硬的边界,可开 limits.execWriteFence(Landlock,Tier 2):默认关闭,因为它会挡掉构建工具写 $HOME/.cache / /tmp。

审批被禁用 / 没有可写根时怎么办

三种都可走:① 会话里「添加目录」;② 会话工作目录设为远端根;③ 部署在插件配置里声明 roots(推荐用于 headless / 审批禁用环境):

- id: 远程工作区
  name: dsh-over-ssh
  config:
    connections:
      - { id: build01, host: 10.0.0.5, user: ci, transport: agent }
    roots:
      - { location: remote, connectionId: build01, path: /srv/work, writable: true }

另外,本会话的 scratch 目录(/tmp/dsh-over-ssh-scratch/<session-id>/)在 0.3.1 起不依赖"根已注册":只依赖连接,可用于临时脚本/草稿。remote_status 会告诉你它当前是否可达。

0.3.2 更新

  • 持久 PTY 终端(协议 v4):新增 remote_terminal_open/send/read/close —— 长驻 bash/sh,cd/export/ source envsetup.sh 跨调用保留;会话上限 8、空闲 10min 回收,session.end 清理。协议版本 3→4, 旧代理需随包重装。

以路径为重点的收尾修复(详见审计 0181),全部来自真机回归:

  • read_glob 接受根内绝对拼写:修前绝对模式(如 /srv/work/ab/*.txt)被再拼一次根,静默"匹配 0 个 路径";现在与相对模式得到同一批文件。

  • 拒绝 URL 拼写而不是静默当相对路径:file:///D:/x、http://…、大写的 SSH:// 过去会被拼成 <root>/file:/D:/x(写到另一个文件);现在明确拒绝并提示正确拼写。

  • 不再静默 trim 路径首尾空白:"/srv/work/a " 过去等于 "/srv/work/a";现在明确报"首尾有空白",避免 写到另一个文件。

  • 0.3.1 真机 bug 修复(见审计 0180):remote_exec {waitMs} 作业现在能被 remote_job 读取; dryRun 不再进审计;steps 不再有多余空行;批量 connectionIds 认可会话「添加目录」的根; scratch 路径对 move/apply_patch 同样可用;read_glob 对 scratch 明确拒绝;cwd 误判(用户命令 自己 cd 失败被算到 cwd 上)与 cwd 是文件时的漏解释已修。

  • 0.3.2 复核修复(审计 0201):Tier 2 search.grep 的 exclude 现在真的下发;能力位探测不再清空 Tier 2 能力 (index/watch/cancel/git 在 5 分钟重探测后仍可用);remote_file{op:"read_glob"} 的二进制文件也受 maxBytes 与整批 2 MiB 预算约束;remote_file_restore 默认不再被快照 version 挡住(显式 expectedVersion 才校验); remote_terminal_send 单次上限 1 MiB、remote_terminal_read 描述与实际 20s 上限一致;旧代理没有 fs.readMany 时批量读自动退回逐文件;传输面板在 React 开发期 replay 后不再停摆。 代理二进制随包更新为 0.3.2-0f16923(远端主机需重装代理才生效)。

0.3.1 更新

按一线使用反馈落地的一轮(详见审计 0172):

  • remote_status(新):一次调用看清连接/root 是否可见/写闸/scratch 路径与可达性/超时/远端能力与版本/时钟差, 任何不可用项都给原因与下一步。

  • Tier 1 超时不再留孤儿:远端有 timeout 时命令被 timeout -s KILL 包装,本地预算留 3s 宽限,超时返回 timedOut + killConfirmed("已确认终止"),修掉"放弃等待后远端进程继续占用设备"的事故根因。

  • scratch 与 root 解耦:会话 cwd 不在任何远端根下时,/tmp/dsh-over-ssh-scratch/<session-id>/ 仍可写; 无根报错给出四条可走的路(添加目录 / 会话 cwd / 部署 config.roots / scratch)。

  • remote_exec 新形状:script(安全落盘执行,无引号事故)、steps(一次往返、逐步退出码)、 maxLines(头尾行窗口)、failureKind(ok/command/timeout/killed/transport)、redact(默认脱敏)、 posixOnly(拒绝 bash-only 语法)。

  • remote_exec 合并后台执行(waitMs):原来独立的 remote_exec_background 并入 remote_exec—— waitMs: 0 启动后台作业立即返回 jobId,waitMs: N 最多等 N ms:期间结束就返回和前台同形的结果 (含 failureKind、maxLines、redact),没结束就返回 job 句柄,继续用 remote_job 读/查/杀。

  • 搜索/枚举:remote_grep 支持 exclude 与 mode: files/count;remote_glob 支持 kind: file/dir/both 与 exclude;remote_file 新增 read_glob(按 glob 一次读一批文件)。

  • 传输/环境/LSP/作业:remote_transfer 支持批量与下载 expectedSha256 校验;remote_env 增加工具链版本; remote_lsp list 报告已安装/在跑的 server;remote_job 支持 connectionId。

  • 协作:remote_log(进程内审计环,命令行摘要已脱敏)、remote_lock(进程内软租约,明确只协调同进程会话)。

  • 实测摩擦轮(0.3.1 内):DSH_SCRATCH / DSH_SESSION_ID 注入每条命令;remote_exec 结果回显 cwd(command 形状另回显命令);Tier 2 超时明确报告 killConfirmed: true;会话 cwd 已落在远端根锚点内时 该根可写(此前"读可以、写被拒");写冲突/盲写拒绝直接给出当前 version,可原地重试。逐条核对见审计 0173。

常用配方(改码 → 构建 → 下载 → 板端 → 回传)

下面每个配方都是可以直接照抄的工具调用形状;路径按你的实际工程替换。Windows 客户端的本地路径要写绝对 路径(D:\work\...),插件按调用方给的拼写原样使用。

  1. 在编译服务器上改一个文件

    remote_file { op:"read", path:"src/a.c" }                  → 记住 version
    remote_file { op:"edit", path:"src/a.c", old:"x = 0", new:"x = 1", expectedVersion:"<version>" }
    

    多处替换先 remote_file { op:"edit", …, all:true, dryRun:true } 看预览,再真改。

  2. 交叉构建(长任务,别卡死会话)

    remote_exec { command:"./build.sh -j16", cwd:"build", waitMs:60000 }
    → state:"completed" 就直接拿 exitCode/failureKind;state:"running" 用
    remote_job { action:"output", jobId:"<id>", wait:true }
    

    waitMs:0 = 启动即返回;需要更长就设调用方自己的预算,不必把 timeoutMs 拉满。

  3. 从服务器下载产物到本机

    remote_transfer { direction:"download", remotePath:"out/app.bin", localPath:"D:\\work\\out\\app.bin" }
    

    想校验内容:加 expectedSha256:"<hex>"(不符会报错并保留本地文件)。

  4. 本机 → adb 设备(Windows 客户端)

    shell? 不需要:本机用平台 bash/pwsh 跑 `adb push D:\\work\\out\\app.bin /data/local/tmp/app`
    

    服务器 → 设备的两跳是两次远端操作:先 remote_transfer 下载,再本机 adb push;或者用 shell/bash 在客户端执行 adb(adb 在本机,不在远端)。

  5. 板端跑起来并回传结果

    remote_exec {
      command:"export LD_LIBRARY_PATH=/system/lib:/vendor/lib; cd /data/local/tmp/app && ./run 2>&1 | tail -n 50",
      waitMs:30000
    }
    

    临时文件写到 $DSH_SCRATCH(每条命令自动注入,例如 "$DSH_SCRATCH/out.log"),会话结束会清理。

  6. 对比多台编译服务器的同一份配置

    remote_grep { pattern:"^ENABLE_", path:"conf", connectionIds:["build01","build02","build03"] }
    

    路径按每台机器的覆盖根解析;一台失败只影响它自己那一行。

0.3.0 更新

相对 npm 上的 0.2.4。本版是工具可用性版本:不改变任何既有工具的行为,只让"读/改文件"不必再绕 remote_exec,并补上唯一缺失的批量写入口。

为什么改这个

真实使用中,模型几乎把所有操作(读文件、改文件、跑命令)都塞进一次 remote_exec。原因不是文件工具不可用, 而是三件结构性事实:remote_exec 是唯一不受「添加目录」限制的工具(/tmp 里的临时脚本只能走它);文件工具 是"一次一个文件一个操作",而模型的常见任务是"改 3 个文件 + 跑构建";remote_exec 的描述里从未反向提示还有 专用工具。这一版把这三条各自补上。

第二轮:还有 4 处让调用方退回 exec 的缺口(同版本)

缺口 修法
没有目录列举——平台 bash/glob/grep 都跑在本地机器上,远端"看看这个目录里有什么"只能 remote_exec ls 新工具 remote_ls:列一层(depth 1..3),目录在前、kind/size/mtime、all:false 隐藏点开头项;上限 2000 条/200 目录并如实报告截断
remote_grep 没有上下文行——代理侧 search.exec 的 contextLines 早已实现(连 before/after 都回传),但 TS 层从未发送,于是"看命中附近几行"只能 rg -C 走 exec 打通 contextLines(0..10):代理原生返回 before/after,Tier 1 明确拒绝而不是假装有上下文;命中的上下文也出现在渲染文本里
remote_read 不能读文件尾部——日志/长文件想 tail -n 100 必须先知道总行数 offset 支持负数:offset: -100 直接返回最后 100 行(offset: 0 仍是第 1 行)
~ 路径被静默当成根内目录——remote_read("~/x") 变成 <root>/~/x,报"文件不存在",看起来像工具坏了 明确拒绝并说明:本工具不做 ~ 展开,请用根内/绝对路径,或 remote_exec(shell 会展开)

同时把 remote_exec 的描述讲清楚:平台的 bash/glob/grep 跑在本地机器上,只有 remote_* 家族能到远端 —— 这解释了为什么"用 exec"在远端场景里是必然选择,也告诉模型该换哪些工具。

第三轮:把文件操作收敛成一个 remote_file(op 选择操作)

模型可见工具数 27 → 18:原来 10 个各自独立的文件工具(remote_read / remote_write / remote_edit / remote_patch / remote_apply_patch / remote_read_many / remote_write_many / remote_stat / remote_ls / remote_move)加上本轮新增的两个操作(mkdir / chmod),现在统一为一个 remote_file:

op 做什么
read 读一个文件(行号窗口;offset 负数 = 尾部;raw: true = 无行号原文)
read_many 一次读多个文件(原文 + version)
write / write_many 写一个 / 多个文件(expectedVersion、force、mode,write_many 支持 atomic 回滚)
edit / patch / apply_patch 字面量替换 / unified diff / 批量编辑
stat / ls 元信息 / 列目录(depth 1..3)
move / mkdir / chmod 移动改名 / 建目录 / 改权限位

为什么合并:这 12 个工具都只吃一个 path、只差一个动词;模型的实际失败模式不是"参数用错",而是根本没注意到 其中大部分工具存在(于是 ls/mkdir/chmod/cat 都走 exec)。一个带 op 表和参数说明的工具比 12 个各自 一段长描述的条目更容易被读到。行为零变化:每个 op 仍复用原来的实现(同样的校验、渲染与版本守卫), 并用测试钉住"合并后的参数表必须覆盖每个单操作工具的参数",防止以后加 op 时漏声明。

另补两端:remote_file 的 mkdir/chmod 覆盖"建空目录"和"给已有文件 chmod +x";read 的 raw: true 给出无行号原文(maxBytes 默认 256 KiB 并有截断标注,二进制文件明确拒绝),免得模型为了整段回写而回去用 cat。

重启后又核对了一遍线上工具目录:71 个工具、remote_* 18 个、remote_file 在列且旧名已消失;并修掉 6 处边界 (原型链 op、raw 对二进制/offset 的静默行为、raw 无上限、ls 对无 list() 后端的 TypeError、write_many 回滚不带版本守卫、重复路径),详见审计 0168 §6。

第六轮(四路独立审计)修 27 项,含一个 Go P0:fs.rename 的两条路径落在同一条带(1/64 概率)时会 对同一把互斥锁二次加锁而永久自死锁,把该条带上的写/编辑/复制/删除全部卡住;另修截断索引快照被当增量 基准(永久漏文件)、Tier 1 grep 假阴性、冷启动首次工具调用误报"不在任何远端根内"、失败操作污染版本记忆 (盲写拒绝可被重试绕过)、editText 大文件/二进制静默改写、preflight 缓存 key 失配每次重建连接、exec 客户端 deadline 无宽限导致拆会话等。详见审计 0171。

第五轮(真实远端 A/B 实验 + 路径语义)又修 4 处:新建文件/目录的权限与 shell 不一致(工具建 0644、shell 建 0664,组写构建机上会"别人建的能改、工具建的不行"——改为 0666/0777 由 umask 收敛,且 mkdir 显式 mode 不再被二次掩码)、remote_move/remote_copy/remote_delete 失败时点名"源不存在/目标是目录/父路径是文件"、 反斜杠与 Windows 盘符拼写显式拒绝(POSIX 边界写清)、统计脚本认识 remote_file(op) 并在 exec=0 时显示 N/A。 详见审计 0170。

第四次检查(替换式边界 / grep 双路 / renderer 空值)再修 5 处,并让打包可复现(同一份产物重复 npm pack 得到同一个 sha256,发布记录里的哈希因此可被复核):目录的版本不再进入"文件版本记忆"(否则一次 失败写目录会让下一次写入跳过守卫)、write/edit 拒绝尾随 / 的路径(不再静默建出同名文件)、父路径是文件 / 目标是目录时点名具体路径、超长路径(>4096 字节或单段 >255 字节)在解析阶段就拒绝、renderer 空值措辞; remote_grep 的 include+contextLines+offset 组合与 Tier 1 的可区分拒绝补了固定用例。统计脚本新增 --save/--compare,可在同一台远端机取 0.3.0 前后对比。详见审计 0168 §8 与 0169。

第三次检查再修 5 处:读空文件不再报错(offset 1 超出文件范围:共 0 行 是错的)、raw 读空文件不再渲染成空串、 remote_ls 的 path: "" 等价于根、ls/read 撞到"目录/文件/不存在"时给出人话而不是 ENOENT, 以及合并后共享参数的描述(path 曾只写"File to read."、mode/all/expectedVersion 同样只按单个 op 措辞) 改为中性描述。详见审计 0168 §7。

新能力(同版本)

  • remote_write_many(现为 remote_file 的 write_many op):一次调用写 1..16 个文件(全量内容), 每文件独立 expectedVersion 守卫、服务端原子替换;atomic: true(默认)在后面的文件失败时回滚已写文件, atomic: false 停在第一个失败并把其余标为 skipped。上限:16 文件、单文件 1 MiB、总内容 4 MiB。
  • 会话 scratch 目录:remote_file 的所有路径参数也接受 <limits.agentScratchRoot>/<session-id>/ 下的路径 (默认 /tmp/dsh-over-ssh-scratch/<session-id>/,首次使用时以 0700 创建)。写临时脚本不必再走 remote_exec。这是唯一的根外可写位置,其它根外路径照旧拒绝;scratch 不属于任何 workspace,因此不套 workspace 写围栏(它比 remote_exec 严格得多:remote_exec 本来就用 SSH 用户的全部权限),但沙箱模式仍然 生效——只读会话不能借 scratch 绕过只读。设 agentScratchRoot: "" 可关闭。
  • 工具家族索引:remote_exec 与 remote_file 的描述里带一行家族索引,并明确"读写文件优先 remote_file"。

同一版的修复

  • transport 释放代际按连接计数(不再取消无关连接的重连)。
  • 代理侧 fs.edit/fs.patch/fs.remove/fs.rename 的版本守卫与读-改-写整体串行;fs.copy/fs.copyTree 的目标侧检查与落地整体串行(overwrite=false 与"目标必须为空"的契约现在真的原子)。
  • 取消排队请求现在生效(sessionTable.Cancel);子进程启动失败不再泄漏 fd;JSON 编码尺寸估算补齐 HTML 转义。

相对 npm 上的 0.2.4 的补丁版本,只有一处修复。

  • 修复:释放一条连接/删除一个会话,不再取消无关连接正在进行的重连。 transport 的"已释放代际" 原来是全局计数器:release(连接 A) 或删除任意会话都会让它自增,于是连接 B 正在 discard 旧 传输、准备重建的 acquire() 会拿到一次 CANCELLED,调用方无法把它与真实故障区分。现在按连接计数, 只有真正被释放的那条连接会取消自己的重建。同时补齐"重建窗口内删除本会话仍然取消"的判断: 该窗口里 slot 与 entry 都已删除、pending 尚未登记,新增 #rebuilding 记录在飞的 lane key, releaseSession 依据 slots/entries/pending/rebuilding 四张表判断归属。
  • 修复:代理侧的编辑/补丁/删除/改名把版本守卫与读-改-写放进同一段临界区。 之前只有 fs.write 内部的"校验 + rename"持路径条带锁:并发的 fs.edit/fs.patch 都能读到同一份旧内容,在 mtime 粒度粗的 文件系统上(size:mtime 版本串两次写之间不变)两边都会通过守卫、后者静默覆盖前者;在 ns 粒度上则表现 为并发编辑偶发 E_VERSION_CONFLICT。现在 Edit/Patch 的整段读-改-写、Remove 的校验+删除、 Rename 的源/目标(按字典序取锁,避免 A→B 与 B→A 互等)都在同一把路径锁里。
  • 修复:fs.copy / fs.copyTree 的目标侧判定与落地现在真的原子。 旧实现先 os.Stat(to) 判断目标是否存在、 再拷临时文件、再 rename,三段之间没有按目标路径串行化:两个并发 fs.copy(overwrite=false) 能同时 看到"目标不存在",于是两边都报成功、后者覆盖前者(实测 2 并发 = 2 次成功)。现在目标侧的检查与落地 在同一把路径锁里,实测并发下恰好 1 次成功、另一次 E_VERSION_CONFLICT。fs.copyTree 同样: 目标"不存在/为空"的判定与整棵拷贝同持目标锁,避免两棵交错的树同时落盘(旧行为下失败方还会报 E_IO: mkdir ... file exists 而不是契约里的 E_VERSION_CONFLICT)。

0.2.4 更新

下面这些内容相对 npm 上的 0.2.3 一起生效。

传输与内存

  • transport lanes(审计 0164):interactive/bulk/compute 分 lane(limits.transportLanes,失败回退 interactive);job/LSP 按会话、watch 按会话(agentless 时连接级)使用 stateful lane(limits.statefulLanes 默认 8);transfer stat 走 bulk;Go 在飞窗口从 8 提到 16;proc/LSP/index 按会话公平配额(含后来者预留名额)。
  • P6 读/解析分离:读协程只读原始帧,zstd 解压、JSON 解析与 blob 解压移出读协程;原始帧队列有界,慢盘/大 blob 不再阻塞同连接其它会话。
  • 修复 P6 读错误被 readBlob 消费后主循环永久阻塞;大帧解析后把 parser 缓冲降回 64 KiB;#pollListings 快照表加 64 条上限;并发上传的 stdin drain 监听器合并。
  • 修复重连 discard 期间 releaseSession 被忽略导致已删除会话 lane 复活;selector 抛错泄漏 lane 槽;watch 按会话分 lane 后会话删除会回收 watch:<session>。
  • 修复浏览后端 dispose 拒绝产生未处理拒绝;#sendCancel 写失败遗留 pending 槽。

会话作用域与「添加目录」

  • 会话根按 sessions + workspaces 双重作用域过滤;带 scopedForSession 时,客户端仍按当前 workspace 过滤未限定行,dev 热修。
  • 工作区路径比较容忍尾斜杠与 Windows 大小写差异;真正切换会话/工作区时清空旧 roots,并复位卡片的 open/browsing。
  • 会话作用域修复覆盖:切会话/工作区不再显示上一条会话的目录;同 workspace 的两个会话按 session 隔离;fork 继承仍可见。

Agent / 子进程

  • 修复取消排队请求不生效:sessionTable.Cancel 摘除等待队列与 blob 队列,dispatchMu 覆盖出队+launch 与取消。
  • 修复子进程启动失败泄漏 fd:interactive proc.start 的 stdin,rg/git status/git ls-files 的 stdout,LSP stdout。
  • 修复 JSON 编码尺寸估算漏算 HTML 转义(</>/&/U+2028/U+2029),避免含 < 的大输出被误判装得下而超帧。

数据正确性与工具

  • remote_read_many:一次往返读多个文件(1..16,默认每文件 256 KiB),非 UTF-8 给 binary/dataBase64 与渲染警告;修复批量读总量上限与二进制截断一致。
  • remote_project_summary:一次往返给 git 状态、顶层结构、包清单、README 头与 test/build/lint 建议。
  • remote_apply_patch:一次往返多文件补丁,先全量校验,默认失败回滚。
  • remote_exec / remote_job:非 UTF-8 输出附带 base64 精确字节与渲染警告;remote_job 不再丢 exactBytes。
  • 协议 v3 zstd 跨帧压缩;remote_grep 支持 offset/total/nextOffset 分页;Tier 2 批量读走代理 fs.readMany。
  • LSP:server 支持带空格路径的引号切分、lsp.read 每轮 256 KiB、跨块多字节字符按 exactBytes 解析;卡片的初始焦点与 Tab 集合跳过不可见控件。
  • 文件引用补全:单来源失败只降级该来源;Windows 反斜杠路径参与排序;符号链接按目录处理,根内展开、根外只列链接;同根并发走查共享。
  • 端口转发:net.probe 远端预检,关闭端口在 start 阶段稳定失败;IPv6 [::1] 归一;旧代理没有 net.probe 时跳过预检继续。
  • 回收站与锁:父子还原、锁心跳、缺 entryId 行可见不可操作、已删连接编辑不再提交。
  • 会话管理页:修正短 id、工作区目录内联、行内回收站按钮、已选计数。

其它修复

  • remote_read_many、remote_exec、remote_job 的二进制/截断/渲染一致性问题(审计 0160–0162)。
  • writeFile 非 Uint8Array 参数本地立即拒绝;repo.summary 只读普通文件;patchMany 超大文件先判大小;fs.readMany 先校验再起协程。
  • 主菜单/渲染修复:项目概览补顶层/清单/README、分页提示按 Tier 分档、remote_grep 真正分页、zstd 小帧只压缩一次。

其它

  • 组合层仍为 6 个条目;本地写入围栏由平台沙箱执行。
  • 其余行为不变。

0.2.3 更新

下面这些内容相对 npm 上的 0.2.2 一起生效。

  • 热启用不再失败:移除私有域里对平台 @deepseek-ai/dsh-file-reference-local 的克隆与 localFileReferences 桥: 根作用域的 file-references 本来就自己实现本地有界走查,那份克隆没有消费者。效果是启用插件时 不再出现 2 entries did not activate(workingDirectory / fileReferences 等待链),热启用可以直接 完成,不必为它完整重启。
  • 组合层因此只剩 6 个条目(原 8 个):私有域只保留 fs-sandbox 克隆 + localFs 桥,本地写入围栏仍由 平台沙箱执行。
  • 文件引用补全复查(审计 0135):单个远端来源失败只降级该来源,不再让整个 @ 补全失败;缓存命中后 的取消仍按取消处理;Windows 本地根的反斜杠路径参与文件名/深度排序;符号链接目录按目录处理,只有 指向根内的链接会被展开(根外链接只列链接本身,不把工作区外的文件带进 @),并带环检测与 Windows 忽略目录大小写处理;打字快于一次走查时,同根并发调用共享一次树枚举、不再重复扫树(探针:6 次击键 = 1 次走查)。
  • LSP 复查(审计 0136):remote_lsp 的 server 支持带空格的路径(引号切分,"/opt/my tools/server" --stdio, 未闭合引号明确报错);宿主 lsp.read 每轮只取 256 KiB,不再吃满代理 2 MiB 默认块;客户端卡片的初始 焦点与 Tab 集合跳过不可见控件。
  • 回收站与锁(审计 0137):索引记录父子关系,还原父会话会连带还原子会话(失败留在垃圾并回报); 会话/回收站锁加心跳,跨设备大目录 copy 超过 60 s 也不会被当成陈旧锁抢走;缺 entryId 的回收站条目 现在可见但不可操作并说明原因;连接被删除后编辑对话框不再提交请求。
  • 构建:删掉的宿主入口产物会被清理,不再随包发出(0.2.3 首次打包曾多带一个 local-bridge-refs.js)。
  • 其余行为不变;远端 @、本地 @、文件工具、会话面板均未改动。

0.2.2 更新

  • 「添加目录」按会话作用域显示与删除,fork 子会话继承父会话的目录且立即可见。
  • 会话面板:删除/还原/清理都有确认与部分失败说明;运行中的会话拒绝删除;回收站条目显示标题与删除时间。
  • SSH 传输:连接闪断后自动重建(不再永久超时);版本守卫会校验摘要来源,损坏/缺失的摘要不再当守卫。
  • 宿主 HTTP:请求体超限、路径含 NUL、根外访问返回 400 而不是 500;?workspace= 单独给出时也生效。
  • 性能:会话面板刷新的日志头读取加签名缓存(31 会话冷 17 ms → 热 1.3–3.7 ms);GET /roots 与 user-roots.json 读取走 stat 短路;?session= 过滤先过滤后投影。

发布说明

包里带了两个平台的 Tier 2 代理二进制(纯静态,远端零依赖)。源码在配套的 Go 仓库 dsh-over-ssh-agent(暂未公开发布,按下面的 sourceCommit 可核对)。这一段由 npm run release:note 从 agents/agent-manifest.json 生成,prepack 会核对它与清单一致,不要手改:

平台 字节 sha256
linux-amd64 5,660,832 43df9c32933bb657ea08aea3926b617ae34082160cae4be2d3ba9a68b9fff241
linux-arm64 5,308,576 2ac25229c645bf5a9ea27a4fe2e321994706ad4bb887796a5889c182e56a842a
  • 代理版本:0.3.2-0f16923
  • 源码提交:0f16923(Go 仓 dsh-over-ssh-agent 的这个提交)
  • 清单原文:包内 agents/agent-manifest.json
  • 核对:sha256sum agents/<平台>/dsh-over-ssh-agent 与上表比对;按上面的提交检出 Go 仓后 scripts/check.sh 可重建同样的产物。

关键设计取舍(摘要)

  • 传输层自研,不使用核心 packages/ssh/* 家族。原因见设计文档 §3.1:官方实现的 BatchMode=yes 让密码认证不可能、远端必须预装 Node + helper、ctx.ssh 单例、且其 Web 集成需单独实现(preset 的 isolate 子树覆盖不到 agent.ctx)。
  • 文件按路径路由,进程不路由:核心 provider 的公开方法收不到 agent/session 身份,因此 fs 用自研路由 provider 支持"本地 + 远端多根",而 bash/终端保持单一执行世界,远端命令走显式入口。
  • 远端零安装(Tier 1,地板):只依赖远端已有的 POSIX 工具(sh/base64/stat/find/可选 git/rg),连上后做一次能力探测并按能力降级。
  • 可选 Go 代理(Tier 2,增强):独立仓库 ../dsh-over-ssh-agent,纯静态单文件(随包产物的体积与摘要以 agents/agent-manifest.json 的 bytes/sha256 为准,交叉编译矩阵见 ../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md;第三方依赖 4 个,全部经 ADR-0008 授权),经 ssh 通信(stdio 或常驻 daemon 的 unix socket,不监听 TCP 端口),补齐原生监听/索引/长任务/远端 LSP/Landlock 围栏。决策见 doc/03-decisions/0005-optional-go-remote-agent.md;代理不可用时一律回退 Tier 1。
    • 默认尝试部署(2026-10-13 起,审计 0040):连接的默认传输是 agent,首次连接会把代理装到远端 $HOME/.cache/dsh-over-ssh/dsh-over-ssh-agent(约 4.7 MiB / 4,907,168 B,以 agents/agent-manifest.json 为准,0700),失败自动回退 Tier 1。想避开远端写入就显式写 transport: alias。
    • 密码认证同样可用:代理经系统 ssh 启动,而系统 ssh 靠 SSH_ASKPASS 助手取密码(秘密只经环境变量传递,不落盘)。此前"密码认证无法用代理"的说法是把本插件硬写 BatchMode=yes 误当成了 SSH 的限制。
    • 随包只带 linux-amd64 与 linux-arm64 两个产物;其它平台的远端会正常降级到 Tier 1。
  • 秘密进 ctx.credentials:role('secret') 只保证不上 wire,落盘仍是 profile patch 明文,因此密码/口令绝不进 Config。

目录结构

src/
  index.ts fs.ts file-references.ts   # 三个 DSH 入口(组合根)
  host/
    domain/        # 纯 TS、零框架依赖、100% 单测覆盖
    app/           # 应用层用例(根路由、传输服务、状态)
    infra/         # 传输/后端/缓存/持久化实现
    integration/   # 与核心对接:fs provider、fileReferences、tools、Remote API、终端 wrapper
  client/          # web client 半(React + TS + CSS Modules)——与 host/ 是兄弟目录
  shared/          # 两半共用的纯工具(路由常量、根键等)
tests/             # 镜像 src/ 的测试树(每模块一个 *.test.ts;根级只留 architecture/config 两个横切用例)

测试

零依赖:使用 Node 内置 test runner + 原生 TypeScript 类型剥离(Node ≥ 22.19 / ≥ 24)。

npm test          # node --test "tests/**/*.test.ts"
npm run typecheck # 需要先安装 devDependencies(typescript)

约定:一个源文件对应一个 tests/<同名>.test.ts;领域层与基础设施层不依赖核心包,因此测试无需安装 @deepseek-ai/*。

当前数字只在 doc/05-benchmarks/baseline.md 维护,本文不重复抄录。抄录的副本会与基准不一致,这类不一致在本仓库已经出现过。要现在的数字就跑命令:

node --test --test-concurrency=4 "tests/**/*.test.ts"        # 正确性:用例数与失败数
tsc -b && tsc -p tsconfig.client.json                        # 类型:宿主半与客户端半
npm run build:host && node tools/build-client.mjs --check     # 产物体积
npm run agents                                               # 随包代理清单与体积

注意:本机跑套件必须限并发。npm test 的默认并发会一次拉起 71 个 Node 进程,而本机可用物理内存常年 只有 1–2 GB,会大量假失败(spawn ENOMEM / Fatal process out of memory,用例总数在 841–1235 之间跳)。 用 node --test --test-concurrency=4 "tests/**/*.test.ts"。这是环境容量问题,不是代码缺陷。

里程碑

见设计文档 §13:M0 spike(三个未验证假设)→ M1 传输与连接管理 → M2 路由 fs → M3 远端搜索与 @ → M4 文件树与传输 → M5 远程终端 → M6 会话管理 → M7 性能与内存回归。

当前进度(本仓库内):只列最近三条,更早的里程碑见 doc/06-audits/README.md 的历史记录表。

  • 改名 dsh-over-ssh:仓库目录、Go module、二进制、状态目录、两个回收站、HTTP 路由共 11 处名字统一, 已有数据走 4 条一次性迁移(远端旧代理目录不删)。见 0110(doc/06-audits/0110-rename-to-dsh-over-ssh.md)。
  • 阶段 2 的「添加目录」按会话隔离。同一工作区开两个会话时,A 加的目录 B 既看不到也用不了;fork 出来的会话继承父会话的目录,老数据(无 sessions 字段)保持工作区级不打断。会话身份由 AsyncLocalStorage 从工具派发带到 ctx.fs(平台只给 fs 传 cwd)。GUI 文件面板、glob/grep 与隐式会话根三处残余面已写明。见 0108(doc/06-audits/0108-per-session-root-isolation.md)。
  • 阶段 2 的「一键接管」开关尚不可用。审计 0095 的实现有宿主异步清单、行标识与回滚缺陷,不安全的逐行写入路径已移除,面板只显示状态与手动配置提示。平台的单行管理 API 不能保证四行批量原子切换或精确恢复原有 profile 覆盖,要等可靠的批量事务与还原机制可用并通过真实组合验证后才能启用。见 0096(doc/06-audits/0096-takeover-safety-correction.md)。
  • 阶段 2 的会话工作目录根。活会话 cwd 自动成为会话作用域、隐藏、纯内存的本地根;resolve/lstat 失败时同步一次再重试。真机端到端未跑。见 0094(doc/06-audits/0094-session-workspace-root.md)。
  • 卸载不等于关闭。用时间区分重注册与真关闭:surfaceDetached() 推迟一个任务、surfaceAttached() 取消,调度可注入,策略离线可测。见 0091(doc/06-audits/0091-unmount-is-not-close.md)。

并行轨道(独立仓库 ../dsh-over-ssh-agent):协议、文件原语、索引与搜索、watch、proc、LSP、Landlock 围栏均已实现,多会话与常驻 daemon 分四阶段完成。当前状态、未做项与实测数字见该仓库的 README.md(../dsh-over-ssh-agent/README.md) 与 benchmark(../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md)。