diff --git a/vendor/dsh-remote-ssh/README.md b/vendor/dsh-remote-ssh/README.md
new file mode 100644
index 0000000..be7fbf7
--- /dev/null
+++ b/vendor/dsh-remote-ssh/README.md
@@ -0,0 +1,330 @@
+# @zhangfengshun/dsh-remote-ssh
+
+[English](./README_EN.md) | 中文
+
+类 **VSCode Remote-SSH** 的 **DSH** 插件:通过 SSH 连接远程超算 / 服务器,在 DSH 内置「文件」「终端」页签中直接操作远程文件和终端。
+
+**目录**:[功能](#功能) · [截图](#截图) · [安装](#安装) · [使用](#使用) · [代码示例](#代码示例) · [模型工具](#模型工具) · [命令超时与恢复](#命令超时与恢复) · [兼容性](#兼容性) · [故障排查](#故障排查) · [原理](#原理) · [缓存与一致性](#缓存与一致性) · [许可证](#许可证)
+
+## 功能
+
+| 能力 | 说明 |
+| --- | --- |
+| 🔌 SSH 连接 | 密钥 / 密码认证,ProxyJump 跳板机,`~/.ssh/config` 一键导入 |
+| 📂 远程文件 | 内置「文件」页签直接 SSH 读写远程文件,无需同步 |
+| 💻 远程终端 | 内置「终端」页签自动检测远程工作区,SSH 交互式终端,**落在工作区对应的远程目录**(与 VSCode Remote-SSH 一致) |
+| 🌐 远程工作区 | 选择远程目录创建原生工作区,一键进入远程环境 |
+| 🤖 模型工具 | 13 个 `remote_ssh_*` 工具,会话感知免填连接参数;命令级超时 + `remote_ssh_kill` 兜底恢复 |
+| 🗂️ `@` 引用补全 | 远程工作区会话里 `@` 补全列**远端**文件(git 仓库走 `git ls-files`,实测 0.1s;非 git 用有界 `find`;索引缓存 + 900ms 查询预算,超时降级不卡输入框) |
+| ⚡ 打开提速 | 单往返合并读 + raw 文本快路径 + 结果缓存(LRU + 5s TTL):首开 ≈**1.31×**,TTL 内重复打开 **0 往返**,过期复验 **≈5×**(真实超算实测);`remote_ssh_exec` 连接复用 **≈15×** |
+
+## 截图
+
+**设置 → 远程连接**:连接配置(密钥 / 密码 / ProxyJump 跳板机)· 连接测试 · 从 `~/.ssh/config` 一键导入
+
+

+
+**内置「文件」页签**:直接浏览远程主机文件(右侧文件树即远程目录,编辑保存直写远程)
+
+
+
+**内置「终端」页签**:自动 SSH 到远程超算(图为 SLURM 作业调度环境);左侧会话即模型免填调用 `remote_ssh_*` 工具
+
+
+
+## 安装
+
+**前置要求**
+
+| 项 | 要求 |
+| --- | --- |
+| DSH | ≥ 0.1.5-rc.1,**含 0.2.0-rc.1**(最新官方线;0.1.2 稳定线请用 v0.18.1 时代的插件版本)。插件声明的 peer 范围显式列出每条已验证版本线,因此新版 harness 的兼容性门(见[安装](#安装))不会拦住它 |
+| dsh-better-sidebar | ≥ 0.15(本插件依赖其 `/sidebar/api/` 文件 API 与 0.24 的 `open.external`「打开方式」端点;0.23 起文件树改为批量 `fs.trees` 并新增 `fs.mkdir`,**2.4.18 起已适配**)。**可以只装本插件**:2.4.18 起未安装它时不再卡住 web boot(见下方说明),但「文件」页签的远程读写与编辑器页签也随之不可用 |
+| 本机 SSH 客户端 | Windows:系统自带 OpenSSH(`%SystemRoot%\System32\OpenSSH\ssh.exe`);Linux/macOS:openssh-client |
+| 远程主机 | 任意标准 sshd(超算 / 服务器 / 跳板机均可) |
+
+**一条命令安装**(无需 token、API Key 或额外配置):
+
+```bash
+dsh plugin --profile add @zhangfengshun/dsh-remote-ssh@2.4.45
+```
+
+安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
+
+> **只装本插件、不装 `dsh-better-sidebar`(或它加载失败)会怎样?** 2.4.18 起可以正常启动:客户端只把内核服务(`slots`/`locale`)声明为硬依赖,better-sidebar 改走**子 fiber 软注入** —— 装了才注册远程文件编辑器页签,没装就静默降级。此时**能用**:设置页「远程连接」(SSH 连接与远程工作区)、模型工具(`remote_ssh_*`)、远程终端集成、`@` 远程文件补全;**不能用**:「文件」页签的远程读写与编辑器页签 —— 那套 `/sidebar/api/fs.*` 通道属于 better-sidebar(内核原生侧边栏走的是它自己的 `/api/*`,本插件不接管)。1.0.0 之前的旧版插件在这里会**永久 pending**,前端直接报 `web boot: 1 entry did not activate` / `pending (waiting for service: betterSidebar)`(issue [#18](https://github.com/ZhangFengshun/dsh-remote-ssh/issues/18))。另外 better-sidebar 缺席时宿主会打一条 `patch: entry "better-sidebar" not found` 的 warn —— `dsh-app-boot` 对缺席的 patch 目标无条件告警,**属正常,可忽略**。
+
+> **DSH 0.2.0-rc.1 起:装不上 / 插件列表里不出现?** 新版 harness 会按插件自己声明的 **DSH peer 版本范围**判定兼容性,范围覆盖不到当前运行时版本时会**拒绝安装/激活**(提示 `Plugin … is incompatible with dsh <版本>`),并在插件管理器里给你一个「接受风险」的逐版本豁免。2.4.16 起本插件的 peer 范围已显式列出所有已验证版本线(`^0.1.0-rc.6 || ^0.1.5-rc.1 || ^0.1.7-rc.2 || ^0.2.0-rc.1`),**不需要**任何豁免即可安装。若你用的是更早的插件版本,请升级而不是点"接受风险"。(判定是严格 semver:预发布运行时只被"版本线显式列出"的范围覆盖 —— 这也是为什么范围里要逐条列 `0.1.5-rc.1` 这类版本。)
+
+卸载:
+
+```bash
+dsh plugin --profile remove @zhangfengshun/dsh-remote-ssh
+```
+
+> ⚠️ **dsh-better-sidebar 版本兼容性(2026-09 实测)**:`0.18.1 / 0.19.0 / 0.19.1` 在 DSH Desktop v2.0.9(DSH 0.1.5-rc.1)上**主机半边无法加载**(它们以值方式导入 `SessionLogOffset`,桌面版模块面只提供该类型声明)→ 侧边栏文件页签显示「这类内容还没有可用的查看方式。」。请使用 **0.18.0**,或使用已修复该导入的构建;本插件对 0.18(4 端点)与 0.19(6 端点,含 `fs.rename`/`fs.remove`)两套契约均已适配。
+
+## 使用
+
+**三步上手**
+
+1. **设置 → 远程连接** → 添加连接(主机 / 端口 / 用户 / 密钥)→ 点「测试连接」验证;已有 `~/.ssh/config` 可直接一键导入
+2. **添加工作区** → 选「选择远程目录…」→ 选连接 → 浏览并选择远程目录(该目录会成为原生 DSH 工作区);目录还不存在时点「📁 新建目录」就地创建(本地 / 远程 tab 均支持),创建后自动进入新目录
+3. 进入该工作区会话:内置「文件」页签直接显示远程文件(编辑保存直写远程),「终端」页签自动 SSH 到该工作区的**远程目录**(仅密钥认证)
+
+**会话内直接对模型说**(远程工作区会话中免填连接参数):
+
+```text
+看看 /home/user/project 下有什么,然后把 train.py 的第 20 行改掉
+跑一下 squeue -u $USER,把排队情况整理成表格
+把这个目录的 *.log 里含 ERROR 的行抓出来
+```
+
+## 代码示例
+
+**示例 1 · 执行远程命令**(`remote_ssh_exec`,默认 120s 超时):
+
+```json
+{
+ "command": "sinfo -h -o '%P %a %D %t %N' | head -20",
+ "timeoutMs": 30000
+}
+```
+
+返回 `{ ok, exitCode, stdout, stderr, error, truncated, isTimeout }`——例如:
+
+```json
+{ "ok": true, "exitCode": 0, "stdout": "cpu* up 12 idle 8 ...\n", "stderr": "", "error": "", "truncated": false, "isTimeout": false }
+```
+
+**示例 2 · 文件读写(无需同步)**:
+
+```json
+{ "path": "~/project/config.yaml", "content": "lr: 0.001\nepochs: 50\n" }
+```
+
+```json
+{ "path": "~/project/train.py" }
+```
+
+`remote_ssh_cat` 走 base64 传输(二进制安全),`remote_ssh_write` 为原子写入(写临时文件再 rename)。
+
+**示例 3 · 长时任务与挂起恢复**(构建 / 训练显式放宽,卡住可强杀会话):
+
+```json
+{ "command": "cd ~/project && bash run_train.sh", "timeoutMs": 0 }
+```
+
+```json
+{ "all": true }
+```
+
+`timeoutMs: 0` 禁用本次超时;环境变量 `DSH_REMOTE_SSH_CMD_TIMEOUT_MS=600000` 可改全局默认。超时后池化会话自动丢弃重建,`remote_ssh_kill` 是随时可用的手动兜底。
+
+**远端语义(2.4.44 起写清)**:`timeoutMs` 只是**本地等待预算** —— 到点只放弃等待并丢弃会话,**不会终止远端命令**(远端进程可能继续运行,输出不再回传;断开连接 / 退出 DSH 同理)。需要远端硬时限请用远端自己的 `timeout <秒> <命令>`。**按停止键取消**与 `remote_ssh_kill` 才代表「终止」:插件会给远端 shell 所在的进程组发 SIGHUP(最多等 4s;与关终端同义,`nohup` / `setsid` 起的任务不受影响)。
+
+**示例 4 · 远程工作区内的工具调用**(免填 `profileId`,相对路径基于工作区远程目录):
+
+```json
+{ "path": "configs/exp1.yaml" }
+```
+
+**示例 5 · 从 `~/.ssh/config` 导入连接**:设置 → 远程连接 → 「导入 SSH config」→ 勾选主机 → 自动填充 host / user / port / keyPath / ProxyJump。
+
+**示例 6 · 本地镜像同步与回推**(离线批改后再一次性上传):
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+`remote_ssh_sync` 把远端拉进本地镜像目录,`remote_ssh_push` 把镜像改动推回远端(tar over ssh,批量高效)。
+
+**2.4.20 起同步是「有门槛的整树操作」**,顺序固定为 *体积哨兵 → 解包到临时目录 →(整树时)比对「只存在于镜像的文件」→ 原子替换*,任何一步失败都**不碰旧镜像**:
+
+| 参数 | 作用 |
+| --- | --- |
+| `paths` | 只同步这些子路径(相对远端根),例如 `["src","docs"]`。**局部同步只覆盖对应子路径,不删除镜像里任何其它文件。** |
+| `exclude` | 排除规则(相对远端根,支持 `*`),下推为 `tar --exclude=./x`,例如 `["data","*.log"]` |
+| `force` | 显式确认:跳过体积哨兵与「仅存在于镜像的文件」保护(确认要整树全量复制时才用) |
+| `maxBytes` | 本次同步的体积上限,覆盖工作区设置与默认 **2 GiB** |
+| `timeoutMs` | 本次同步的墙钟预算,默认 **10 分钟**(0 = 不限) |
+
+```json
+{ "workspaceId": "w_xxx", "paths": ["src"], "exclude": ["data", "*.log"] }
+```
+
+- **体积哨兵**:删除任何东西之前先 `du -sb -c -- <本次范围>`(15 秒预算,只测要同步的范围)。超过上限、探测超时、远端无 `du`、输出不可解析 —— **一律拒绝**,要求显式 `force: true`。默认上限 2 GiB(`syncMaxBytes` / 环境变量 `DSH_REMOTE_SSH_SYNC_MAX_BYTES` 可调)。
+- **镜像独有文件默认不删**:整树同步前比对旧镜像与拉取结果,发现「远端没有、镜像里有」的文件就拒绝并列出清单(最多 20 条),提示先 `remote_ssh_push` 补推,或确认放弃后加 `force: true`。插件自己写的 `.remote-ssh.json` 与占位 `README.md` 不算(按内容指纹识别)。
+- **`push` 不污染远端根**:始终排除 `.remote-ssh.json`(连接信息绝不推到远端),并排除插件写的占位 `README.md`(你自己写的同名文件不受影响)。
+- ⚠️ **`exclude` 不抑制被显式列进 `paths` 的路径**(tar 对命令行点名的成员不做 `--exclude` 过滤):要排除大目录,请把 `paths` 提到它的父目录,让大目录成为「成员」而不是「目标」。另外,不匹配任何内容的 exclude 模式**不会报错也不会提示**(tar 的语义),别把"传了没反应"当成参数被丢弃的证据。
+- **镜像目录是"出站缓冲区",不是远端快照**:agent 的 `write` 会同时写镜像与远端对应文件;`remote_ssh_push` 是这些改动的**回推通道**。要在会话里读远端最新内容请用「文件」页签或 `remote_ssh_cat` —— 镜像里的内容可能已经过期。
+- **写回桥(issue #24)**:`write`/`edit` 落本地镜像后会把同一份内容推到远端。2.4.24 起:
+ - **超过 4 MiB 的内容也照推**(分块 base64 追加 + 远端字节数校验)—— 旧版这里是确定性失败,"写日志、模型看不见",于是模型以为远端已有该文件;
+ - **推送失败会明确报错**,消息里写清"本地镜像已写入成功、只是没同步到远端",并给出 `remote_ssh_push` 这条补救路径。想恢复"只写日志、不影响工具返回"的旧行为:设置 `writeBackFailure: "log"`(或环境变量 `DSH_REMOTE_SSH_WRITEBACK_FAILURE=log`)——**2.4.26 起**这种模式下被护栏 B 拦下时,那份带补救步骤的完整报告也会写进日志(此前只记一行短提示,等于"只报告、不推送"却没有报告)。
+ - **不想让草稿跟着进远端**:工作区可设 `writeBack: false` 整体关闭,或用 `writeBackExclude` 排除路径(镜像相对路径,支持 `*` / `**` / `?`,结尾带 `/` 视为目录前缀),例如 `["_patch/**", "*.log"]`。
+ - **护栏 B(2.4.25 起,默认开):推之前先看远端有没有被别人改过**。推送成功后插件记下远端的 `size:mtime`(`~/.dsh/remote-ssh/writeback-mtimes.json`),下次推同一路径前复查:**不一致或远端那份已消失 → 不推送**,并报错说明"本地镜像已写入成功、只是没推到远端",给出 `remote_ssh_sync`(拉下来比对)/ `remote_ssh_push`(确认以本地为准)两条出路。共享集群上最常见的"另一个写入者"就是**你自己刚跑完的作业**,这条护栏挡的正是"作业改了远端、镜像还是旧版、agent 再写一次把改动覆盖掉"。
+ - 只在**远端自己的时间轴**上自比(不与本地 mtime 比:跨机时钟偏移、tar/base64 重写都会让两边不可比);**读不到 ≠ 被改过** —— `stat` 失败、ssh 抖动都归为"状态未知"照常推送,只留一行日志。
+ - 显式写远端(`remote_ssh_write`、文件面板保存)或 `remote_ssh_push` / `remote_ssh_sync` 成功之后,相关记录会被清掉(那之后镜像与远端又是一致的)—— 这也是被拦下后的官方出路。
+ - **关掉它**:设置 `writeBackFreshness: false`,或环境变量 `DSH_REMOTE_SSH_WRITEBACK_FRESHNESS=off`(回到"每次都无条件覆盖")。
+ - **这些开关都能在设置面板里改**(2.4.25 起):设置 → 本插件 → 「写回与终端(进阶)」有 `nodePath` / `writeBackFailure` / `writeBackFreshness`;每个远程工作区下面多一组「启用写回 + 写回排除」。
+
+## 模型工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `remote_ssh_profiles` | 列出连接配置 + 当前会话远程工作区上下文 |
+| `remote_ssh_exec` | 执行远程命令(默认 120s **本地等待预算**,`timeoutMs` 可放宽/禁用;按停止键取消会 SIGHUP 远端进程组) |
+| `remote_ssh_kill` | 强制关闭池化 SSH 会话,并尽力给远端进程组发 SIGHUP(挂起命令的兜底恢复) |
+| `remote_ssh_ls` | 列举远程目录 |
+| `remote_ssh_cat` | 读取远程文件 |
+| `remote_ssh_write` | 写入远程文件 |
+| `remote_ssh_grep` | 搜索远程文件内容 |
+| `remote_ssh_glob` | 查找远程文件 |
+| `remote_ssh_mkdir` | 创建远程目录 |
+| `remote_ssh_delete` | 删除远程文件/目录 |
+| `remote_ssh_move` | 移动/重命名 |
+| `remote_ssh_sync` | 远端同步到本地镜像(**整树**:可用 `paths`/`exclude` 收窄,体积超限会被拒,镜像独有文件默认不删) |
+| `remote_ssh_push` | 本地镜像推送回远端(自动排除插件自有的 `.remote-ssh.json` 与占位 `README.md`) |
+
+远程工作区会话中调用工具可免填 `profileId` 等连接参数;全部文件/命令类工具走持久 SSH 会话池 + 结果缓存,`remote_ssh_exec` 单命令实测 ≈15× 提速。
+
+## `@` 文件引用补全
+
+远程工作区会话里输入 `@`,候选来自**远端**(与「文件」页签的树一致),而不是本地镜像目录:
+
+- **索引来源**:git 仓库用 `git ls-files --cached --others --exclude-standard`(尊重 `.gitignore`、含未跟踪文件;真实超算实测 0.117s / 137 条),非 git 目录回退有界 `find`(`maxdepth 5` + 剪枝,实测 1.57s / 3121 条);
+- **排除在远端、截断之前**(2.4.8 修复):`git ls-files --cached --others` 的输出**不是全局字典序**(未跟踪文件按 readdir 顺序先输出),`node_modules/` 这类目录可能占满前两万行把配额吃光——因此排除目录由远端 `grep -vE` 在 `head` 之前完成(与 `-prune` 同源,正则由同一份排除表生成),客户端过滤仅作双保险;索引达到上限时会打一条 warn 提示可能漏文件;
+- **查询语义与官方 provider 逐条对齐**:`@` 与 `@src/` 走远端目录列举;`@read` 走索引模糊匹配(同名 > 前缀 > 名称子串 > 路径子串 > 子序列,目录加权 +25);
+- **不卡输入框**:索引按工作区缓存 60 秒(写文件/执行命令后自动失效),单次补全只等 900ms——超时先用旧索引作答、重建在后台进行;连接异常时自动回退到本地行为;
+- **本地工作区不受影响**:非远程会话直接委托宿主原实现,索引与排序完全没有改动。
+
+## 命令超时与恢复
+
+所有 SSH 命令默认 **120 秒**超时(issue #5):一条挂起的远端命令(网络卡顿、远端进程僵死、等待 stdin 的 `cat`)不会再永久占用会话、拖死后续命令。
+
+- **超时后自动恢复**:池化会话超时即被丢弃并自动重建,后续命令照常执行;一次性连接超时即终止 SSH 进程;
+- **显式放宽**:`remote_ssh_exec` 传 `timeoutMs`(毫秒)覆盖单次预算,`0` 禁用超时(长时构建/训练);环境变量 `DSH_REMOTE_SSH_CMD_TIMEOUT_MS` 覆盖全局默认;
+- **手动兜底**:`remote_ssh_kill`(或 `all: true`)强制关闭某个/全部池化会话,挂起命令随时可清理;
+- **取消 / 超时 / kill 的远端语义**:按停止键取消与 `remote_ssh_kill` 会尽力**终止远端进程组**(SIGHUP,最多等 4s);`timeoutMs` 超时、断连只**放弃等待**,远端命令可能继续运行(需要硬时限请用远端 `timeout`);
+- 超时命令**不做自动重试**(重试一条挂起的命令只会再次挂起),由模型决定是否改用 `remote_ssh_kill` 或换命令重试。
+
+## 兼容性
+
+**实测矩阵**(2026-09-12,均为真机验证):
+
+| 组件 | 版本 | 状态 |
+| --- | --- | --- |
+| DSH | 0.1.5-rc.1(DSH Desktop v2.0.9) | ✅ 主机服务 / settings / tools / slot / 上传下载拦截全部咬合 |
+| DSH | **0.2.1-rc.1**(DeepSeek Harness 桌面端 nightly,2026-10-17 实测) | ✅ 2.4.32 起适配:信任源从已被移除的 `ctx.webRuntime.trustedHosts` 迁到 **`ctx.webStartup.trustedHosts`**(两个都软注入,老宿主自动退回旧源、都没有则 loopback-only),`--trusted-host` 的远程访问路径因此真正生效;三个 DSH peer 显式补上 `^0.2.1-rc.1`,**不再依赖宿主是否传 `includePrerelease`**;逐 API 复核 `webServer`/`subprocess`/`settings`/`slots`/`locale`/`defineTool`/cordis 生命周期全部未变(13 个工具注册通过,`testConnection` 实测 200),本插件零 warn/零 error。⚠️ 宿主新增的"监听绑定 IP 即受信"例外本插件**不跟随**(有意更严:本插件路由在宿主浏览器令牌认证之外,需要远程访问请显式 `--trusted-host`) |
+| DSH | **0.2.0-rc.1**(DeepSeek Harness 桌面端 nightly,2026-09-28) | ✅ 2.4.16 起适配并真机验证:peer 范围显式列出该版本线(否则 harness 会**拒绝安装/激活**);`settings` 新 API 与旧数据迁移继续有效(实测升级后首次启动即恢复全部连接与工作区);终端 patch 仍命中 `terminal-controller`。客户端注入清单同步移除运行时已不提供的 `dsh-client-runtime`;2.4.17 修好浅色主题下"工作区地球角标不可见"(颜色改为取图标自身计算色) |
+| DSH | **0.1.7-rc.2**(DSH Desktop v2.0.15) | ✅ 2.4.15 起适配:`settings` 新 API(`configure`/`describe`/`update`,数据存于本插件 entry 的 Config,字段标 `.volatile()`)+ **旧 `settings.yaml` 一次性迁移**(连接/工作区 ID 与 mirrorPath 全保留,无需重建);侧边栏终端改由宿主原生 `terminal-controller` 管理,patch 已同时覆盖它与 `better-sidebar` |
+| DSH | 0.1.5-rc.1 / 0.1.6 线 / 0.1.0-rc.6 线 | ✅ 主机服务 / settings / tools / slot / 上传下载拦截全部咬合(peer 范围继续覆盖);⚠️ **2.4.40 及更早**在这一代上会误判 settings 代际(两套接口都在 → 走 0.1.7+ 新分支 → 读恒空、写抛 `namespace not registered`,表现为「连接列表永远为空、导入与保存都没反应」,issue #34),**2.4.41 起修复** |
+| DSH | 0.1.2-rc.1 稳定线 | ✅(插件 2.3.x 时代基线) |
+| dsh-better-sidebar | 0.15.0 – 0.18.0 | ✅ `fs.tree`/`fs.read`/`fs.write` + `fs.search`(`{ matches: cwd 相对 '/'-分隔路径, truncated }` 契约,2.4.11 起;此前只回 `entries` 会让「按文件名搜索」崩掉整块页签) |
+| dsh-better-sidebar | 0.19.x | ⚠️ 插件侧已适配 6 端点(含 `fs.rename`/`fs.remove`);但 0.19.0/0.19.1 自身在 DSH Desktop 上主机半边无法加载,需等上游修复(见[安装](#安装)的警告) |
+| dsh-better-sidebar | **0.20 – 0.24.x**(实测 0.24.1) | ✅ **2.4.18 起适配 9 端点**:0.23+ 的文件树改为**批量 `fs.trees`**(一次请求列举「可见集」,≤64 条)+ 新增 `fs.mkdir`,0.24 的「打开方式」走 `open.external`。此前只注册 `fs.tree` → 新版的列举**绕过拦截**落到 better-sidebar 自己的本地实现,远程项目里看到的就成了**本地镜像目录**;「打开方式」也只会打开本地镜像(见[故障排查](#故障排查)) |
+| dsh-better-sidebar | **0.25.0 – 0.26.1** | ✅ **2.4.28 – 2.4.31 起适配**:git 面板的全部端点(`git.*` 18 项:status / diff / log / stage / commit / checkout / blame / worktrees / pull / push …)改由 exact 路由接管并**在远端执行**(此前未接管 → 远程项目里 git 面板显示的是**本地镜像**那份仓库);0.25.0 的 `fs.createFile`、0.26.1 的 `fs.readPage`(大文件分页预览)逐个对齐上游语义 |
+| dsh-better-sidebar | **0.28.0 – 0.28.2**(实测 0.28.2) | ✅ **2.4.32 / 2.4.42 起适配**:0.28.0 的派发表从 42 → 43 个方法,唯一新增的 **`git.graph`(提交图分页)** 已接管(含 sha256 快照游标、`graph-stale` 409 / `graph-limit` 400);**0.28.2 又新增 `git.history`**(提交图分支数超上限时的分页历史兜底)→ **2.4.42 起接管**(前后各取一次「全量 refs + HEAD + shallow」快照算指纹,远端仍是每页 2 次 SSH 往返)。不接管它时,远程工作区里客户端翻历史会读**本地镜像**那份仓库(upstream-drift 2026-11-02 报红的原因)。已接管的 **`git.status`** 补齐 0.28.0 的新形状(`upstream`/`ahead`/`behind`/`detached`/`operation` + 条目级 `staged`/`unstaged` 行数 + 2000 条截断),远端一条脚本一次 SSH 往返取齐。`fs.*` 10 项、`/sidebar/file`、`open.external` 与 0.26.1 **逐字节相同**,无需改动 |
+| dsh-better-sidebar | **未安装 / 加载失败** | ✅ **2.4.18 起可正常启动**(不再阻塞 `web boot`,见[安装](#安装)):设置页「远程连接」、模型工具、远程终端、`@` 补全照常;⚠️ 「文件」页签的远程读写与编辑器页签不可用(`/sidebar/api/fs.*` 属于 better-sidebar;内核原生侧边栏走自己的 `/api/*`)。宿主会打一条 `patch: entry "better-sidebar" not found` 的 warn,属正常 |
+| 远程主机 sshd | 标准 OpenSSH(Linux / 超算 / Windows) | ✅ 密钥认证;✅ 密码认证(Windows 用系统 OpenSSH 原生 `SSH_ASKPASS`,零依赖、助手自动落在纯 ASCII 目录;POSIX 需本机 `sshpass`) |
+
+插件不修改 DSH 源码、不注入 profile 依赖树,全部能力经官方 `cordis.patch.yml` + profile 机制挂载。
+
+## 故障排查
+
+| 现象 | 原因与解法 |
+| --- | --- |
+| 「测试连接」报 `Permission denied (publickey)` | ① 私钥**带口令**:插件以批处理模式运行(`BatchMode=yes`),无法交互输口令——先用 `ssh-add` 加载,或去掉密钥口令;② Windows host 且用户在 Administrators 组时,公钥须写入 `C:\ProgramData\ssh\administrators_authorized_keys`;③ 用户名的写法(`user` / `.\user` / `user@domain`)要与手动连接一致 |
+| 从 git-bash 启动 `dsh web` 后密钥认证失败 | 2.3.9 起已修复:Windows 下 ssh 解析固定为系统 OpenSSH 绝对路径(此前会误用 Git 自带的 MSYS2 ssh) |
+| 侧边栏文件页签显示「这类内容还没有可用的查看方式。」 | `dsh-better-sidebar` 主机半边未加载:0.18.1 / 0.19.0 / 0.19.1 在 DSH Desktop 上会因 `SessionLogOffset` 运行时导入失败——降到 0.18.0 或使用修复版(上游 PR [#641](https://github.com/omdsh-dev/DSH-better-sidebar/pull/641)) |
+| 前端整屏报 `Failed to load plugins` / `web boot: 1 entry did not activate` / `@zhangfengshun/dsh-remote-ssh: pending (waiting for service: betterSidebar)`,Desktop 还提示「插件恢复」 | ≤ 2.4.17 已知问题(issue [#18](https://github.com/ZhangFengshun/dsh-remote-ssh/issues/18)):本插件当时把 better-sidebar 的客户端服务声明为**硬依赖**,未安装它的用户前端会停在 pending(cordis 的 fiber 只要一个 inject 键缺失就整体不激活)。**升级到 2.4.18** 即可;或临时装上 `dsh-better-sidebar`(注意版本线要与内核匹配)并重启 |
+| **远程项目的侧边栏「文件」页签显示的是本地目录(不是远程目录)** | 2.4.18 起已修复:`dsh-better-sidebar` 0.23+ 把文件树从「逐层 `fs.tree`」改成「一次 `fs.trees` 批量列举可见集」,而插件当时只注册了 `fs.tree` 的 exact 路由 → 列举请求**绕过拦截**、落到 better-sidebar 自己的宿主实现(读本地 fs)。升级插件到 **2.4.18** 并重启 DSH 即可;本地工作区不受影响(两条分支都实现了 `fs.trees`)。0.24 新增的 `fs.mkdir`(新建目录)同理,此前只会建在本地镜像里 |
+| **右键「打开方式 / 在文件管理器中显示」打开的是本地镜像目录(不是远端)** | 2.4.18 起已修复:该菜单把**客户端已知的绝对路径**直接交给本机打开器(`explorer.exe /select,<路径>` / `rundll32 url.dll,FileProtocolHandler `),远程工作区里客户端只有镜像路径。现在拦截 `open.external`:远程工作区改开 `vscode://vscode-remote/ssh-remote+<别名><远端路径>`(别名取自 `~/.ssh/config`;`reveal` 打开的是该文件**所在的远端目录**),本地工作区行为不变 |
+| 远程工作区里「用 VS Code 打开」没反应 / 提示连不上 | 需要 `~/.ssh/config` 里有与连接**一致的别名**(Host 同名或 HostName 相同、且端口与用户名一致)——插件据此生成 `ssh-remote+<别名>`,VS Code 会复用该条目的 `Port`/`User`/`IdentityFile`/`ProxyJump`。没有别名且端口不是 22 时插件**回退本机行为**并在 DSH 日志里打一条 warn(避免静默失败)。另外:**不要**在 better-sidebar 的 `openWith.sshHost` 里手填主机——那条分支由客户端自行打开、路径仍是本地镜像路径,交给本插件处理才对 |
+| **`~/.ssh/config` 里的 `Host` 块会被继承吗**(issue [#21](https://github.com/ZhangFengshun/dsh-remote-ssh/issues/21)) | 分三层:① **导入 ≠ 运行时继承** —— 设置页「从 `~/.ssh/config` 导入」是把该 Host 块的 HostName / User / Port / IdentityFile / ProxyJump **抄进连接配置**,之后再改 `~/.ssh/config` 不会自动同步(重新导入即可)。② **连接时以连接配置为准** —— 插件固定以 `user@host` 为目标、并**总是**传 `-p <端口>`(没填就是 22),而命令行参数**优先于** config,所以**端口与用户名必须填对**(导入会帮你填好);只有 `keyPath` 与 `proxyJump` **留空**时,才会用 config 里的 `IdentityFile` / `ProxyJump`。③ **别名与其余选项** —— 把「主机」填成 Host 别名时,config 里插件**没有**显式指定的选项(`ProxyCommand`、`Compression`、`Ciphers`、`SetEnv` 等)照常由 ssh 应用,但插件自己传的 `-o`(`StrictHostKeyChecking=accept-new`、`ConnectTimeout=15`、`ServerAliveInterval=30`、`ServerAliveCountMax=3`、`ClearAllForwardings=yes`,非交互会话还有 `BatchMode=yes` / `PreferredAuthentications=publickey`)会覆盖同名项。导入侧只解析 `Host` 块(`Include` 递归跟进)、**含 `*`/`?` 的名字跳过**(所以全局 `Host *` 不会被导入 —— 但连接时 ssh 仍会应用它),`Match` 块不解析(块内指令会被算进上一个 `Host`) |
+| **「测试连接」/ 工具对密码认证报 `Permission denied`**,且诊断里出现 `ssh_askpass: posix_spawnp: No such file or directory` 或 `CreateProcessW failed error:2` | ≤ 2.4.42 的已知问题(issue [#36](https://github.com/ZhangFengshun/dsh-remote-ssh/issues/36)):Windows 用户名含中文等非 ASCII 字符时 `%USERPROFILE%`(以及它下面的 `%TEMP%`)都不是 ASCII,而 Windows OpenSSH 用**窄字符路径**启动 askpass 助手 → 助手根本没执行,ssh 把**空口令**发给服务端(提示还会误报成「公钥认证失败 / 检查 keyPath」)。**2.4.43 起**助手改落 `C:\ProgramData\dsh-remote-ssh` → `C:\Users\Public\dsh-remote-ssh` → 用户目录,自动挑纯 ASCII 且可写的落点;也可用环境变量 `DSH_REMOTE_SSH_ASKPASS` 显式指定纯 ASCII 目录下的 `.cmd` 助手(两行内容:`@`(或经配对设备访问);未配置时行为与之前一致(仅本机 loopback) |
+| 「文件」页签的「按文件名搜索」一输入就报 `Cannot read properties of undefined (reading 'length')` | 2.4.11 起已修复:`fs.search` 拦截此前只返回 `entries`,而 better-sidebar 客户端契约是 `{ matches, truncated }`;现在补上 `matches`(cwd 相对、`/` 分隔,与上游自带实现一致)并保留 `entries` |
+| 远程工作区里「按文件名搜索」一直转圈(大工作区) | 2.4.11 起已修复:改为浅层优先(`-maxdepth 3`,实测冷 0.68s / 热 0.11s)且**有命中就立即返回**(深挖转后台预热缓存,浅层零命中才同步等深挖 `-maxdepth 8`),遍历前剪噪声目录、去掉会阻塞短路的 `sort`,并加远端墙钟预算——到点返回**已收集的部分结果**并标记不完整。实测某大型远程项目工作区:旧实现 5 分钟零输出 → 现在 **0.96s 返回 43 条** |
+| 远程会话里 `@文件名` 没有候选,但单独输入 `@` 有 | 2.4.11 起已修复:模糊查询依赖索引,而索引首选 `git ls-files --cached --others`(`--others` 要遍历整棵工作树,巨型项目上跑不完 → 索引为空)。现在三级降级(完整 git 6s → 仅索引 git 3s → 有界 `find` `maxdepth 3` + 5s),并在索引未就绪时用有界 find 即时兜底(实测 0.65s),不再出现「全空」 |
+| 刚发布就安装:`minimumReleaseAge` / `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` / 「No matching version」 | 供应链新鲜度策略,分两层:① **npm 元数据传播**通常 1–5 分钟(`npm view` 看不到新版本就属于这层);② **DSH Desktop 插件管理器走 pnpm**,其 `minimumReleaseAge` 窗口**实测为 24 小时** —— 新版本发布后约一天内,管理器安装会被策略拦下(日志在 `/.plugin-manager/logs/*/pnpm.log`,里面会打印 cutoff 时间)。等到窗口过去重试即可。**想立刻装**:把包**名**加进 `/pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` —— pnpm 11.7 实测,*解析新版本*这条路径只认**纯包名**形式;`名@版本` 形式只对 *lockfile 校验* 生效,所以钉住版本仍会在卸载旧版、装新版时撞上 `ERR_PNPM_NO_MATURE_MATCHING_VERSION` |
+| **换一台电脑后,远程工作区的文件夹图标上没有本机看到的地球角标** | 该角标是客户端半边的 DOM 装饰(壳层工作区行只有固定文件夹原语,没有 per-workspace 图标 API),成立前提是:客户端半边已加载 → 宿主能返回远程工作区 → 行文本/属性与工作区标题匹配 → 壳层 DOM 结构一致 → **角标颜色在该主题下可见**。2.4.17 起:颜色改为取文件夹图标自身的计算色(浅色/深色都可见,此前硬编码白色在**浅色主题**下不可见)、匹配做空白归一化并兼容 `title`/`aria-label`、并加了自检。**排查**:在开发者工具 Console 执行 `window.__dshRemoteSshGlobeStats(true)` —— 返回 `undefined` 说明客户端半边没加载(升级插件后硬刷新页面);`remoteWorkspaces: 0` 说明宿主没返回工作区(查插件版本与 harness 兼容性);`remoteWorkspaces > 0` 而 `globesInDom: 0` 说明标题或 DOM 没匹配上(对照输出里的 `titleSamples` 与侧边栏实际显示文字)。 |
+| `remote_ssh_push` / `remote_ssh_sync` 明明推送成功却报 `returned invalid output` | 2.4.13 起已修复:这两个工具共用的 output schema 把 `error` 标成必填、成功路径又返回未声明的 `remotePath`/`mirrorPath`,于是**只有成功会报错**(失败路径反而合法)。现在 schema 声明两个路径字段、`error` 改为可选,成功路径也带 `error: ""`;全文件所有 output schema 的 `error` 一并改为可选 |
+| 同步被拒:「超过同步上限」/「无法在 15 秒内确认远端体积」 | 2.4.20 起的**体积哨兵**:删除任何东西之前先量体积,默认上限 **2 GiB**。远端根是「代码 + 数据集」的混合目录时这是常态。三条路:① 用 `paths: ["src"]` 只同步需要的子路径(推荐);② 用 `exclude: ["data"]` 排掉大目录;③ 确实要整树复制就带 `force: true`。上限本身可用工作区字段 `syncMaxBytes` 或环境变量 `DSH_REMOTE_SSH_SYNC_MAX_BYTES` 调整 |
+| 同步被拒:「将删除 N 个只存在于镜像、远端没有的文件」 | 这是**数据丢失防线**:镜像里那批文件(常见于 >4 MiB 的写入没能推回远端、或某次 push 失败)在整树替换时会消失。先 `remote_ssh_push` 把它们补推到远端,或确认放弃后带 `force: true` 重试。插件自己的 `.remote-ssh.json` 与占位 `README.md` 不计入这个清单 |
+| 同步很久不返回怎么办 | 2.4.20 起同步/推送有墙钟预算(默认 10 分钟,`timeoutMs` 可调,0 = 不限),到点自动终止两端进程且**不动旧镜像**。旧版本(≤2.4.19)没有超时,只能杀进程 |
+| **填了 ProxyJump 的连接,内置「终端」页签一开就退出(255,`no argument after keyword "-j"`)** | 2.4.21 起已修复:终端 wrapper 拼 ssh argv 时把 `-J` **插进了 `-o` 与其取值之间**,ssh 于是把 `-J` 当成 `-o` 的关键字(关键字小写化后就是报文里的 `-j`)并报「no argument」。升级到 **2.4.21** 并重启 DSH 即可(wrapper 每次加载都会重写,无需手动删 `~/.dsh/remote-ssh/` 下的文件)。旧版本的临时绕过:清空该连接的 ProxyJump(仅当目标机可直达时可行) |
+| **push 之后远端根多出 `.remote-ssh.json` / `README.md`,或者 `exclude` 好像没生效** | **2.4.20 的回归,2.4.22 已修复**:`sync` 方向的排除规则要带 shell 引号(拼进远端命令字符串),但同一条 helper 也被用在了 `push` 方向(字符串作为 **argv** 交给本地 tar,不经 shell)—— 引号于是成了模式的字面字符,所有 `--exclude` 静默失效,连代码写死的两条也没生效。升级到 **2.4.22** 并重启 DSH;**已经 push 过的话**请到远端根删掉多出来的 `.remote-ssh.json` 与 `README.md`(size 与本地镜像里那两个文件一致) |
+| **Windows 上拉取后,中文/日文等非 ASCII 文件名变成乱码(`报告_2026Q1.csv` → `鎶ュ憡_2026Q1.csv`),内容却完好** | **2.4.23 起已修复(issue #22)**。原因是一条三方各自的默认假设:远端 GNU tar 对较短的非 ASCII 名写的是**纯 ustar 头**(名字字段直接放裸 UTF-8 字节,无 PAX、无字符集声明),而 Windows 自带的 `tar.exe`(bsdtar 3.8.8)按**本地 ANSI 代码页**(中文机器 = CP936)解码它 —— **退出码 0、stderr 为空**,只有名字被改写;该构建又不支持 `--hdrcharset`。修法是让远端改用 `--format=pax`(`path=` 记录携带正确的 UTF-8 名),并用能力探针逐 profile 缓存结果,实测**体积零代价**。升级到 **2.4.23** 并重启 DSH 即可。**已经乱码的镜像**:不要直接 `force: true`(那会删掉你在这些副本上做过的修改)——首次整树同步会列出 `乱码名 → 正确名` 的对应关系,按提示要么带 `repairNames: true` 让插件清理(内容以远端为准),要么先在本地改回正确名再 `remote_ssh_push` |
+| **同步被提示「N 个疑似旧版本乱码文件名」** | 这不是"本地独有文件",而是 ≤2.4.22 在 Windows 上拉取非 ASCII 名留下的改写副本(issue #22)。带 `repairNames: true` 重试即可清理(整树同步随原子替换移除;局部同步会删掉这些副本并顺手清空目录)。插件**只**删除已证明是某个远端正确名被 GBK 改写的那一份 —— 清单里混有真正的本地独有文件时依旧拒绝,绝不借"修复"之名删真文件 |
+| **DSH Desktop 上一打开「终端」页签就一闪而过(`'node' is not recognized…`)** | **2.4.24 起已修复(issue #23)**。生成出来的 wrapper 此前裸调 `node`,而桌面端**按设计**不把自带 node 放进子进程 PATH(`packageManager` 只覆盖包操作;内嵌 node 只以"被宿主用绝对路径调用"的形式存在),于是 PATH 上没有 node 的机器 100% 打不开终端 —— 与 SSH、密钥、跳板机全都无关。2.4.24 起:wrapper 里写死**绝对路径**的 node(优先取设置项 `nodePath` → 环境变量 `DSH_REMOTE_SSH_NODE` → **正在运行本插件的那个解释器** `process.execPath`),失败才回退 PATH,再失败就打一条可操作的错误(说明是本插件的终端、桌面端为何没有 node、怎么配)并以 127 退出。**注意 2.4.24 的解析对官方发布形态是过强的**:打包版上 `execPath` 是 `DeepSeek Harness.exe`、`DSH_DESKTOP_NODE_EXECUTABLE` 不在子进程环境里、同目录也没有 node —— 五条候选**全部落空**(举报人对着打包产物逐条核对过,issue #23 第二轮验收)。**2.4.25 起**再补两条兜底:`%DSH_HOME%\dsh-runtimes\*\dependencies\node\bin\node.exe`(`DSH_HOME` 是宿主导出的通用根)与 `<应用安装目录>\resources\runtime\*\dependencies\node\bin\node.exe`(取自 `process.execPath`,另有 `process.resourcesPath` 那条)—— 实例名**不写死**(`primary` 优先、其余按名排序),逐个 `existsSync` 验证通过才用,用哪条都写进日志。升级到 **2.4.25** 并重启 DSH 即可(wrapper 每次加载重写)。若仍失败,最直接的办法是**在设置面板里把 `nodePath` 填成 node 可执行文件的绝对路径**(2.4.25 起该字段在「写回与终端(进阶)」区块里,不再只存在于配置文件中) |
+| **`write` / `edit` 返回成功,远端却没有这个文件(例如内容超过 4 MiB)** | **2.4.24 起已修复(issue #24)**。写回桥此前在推送失败时只写一行宿主日志:① 超过 4 MiB 的内容被 `MAX_BYTES` 拦下(一个日志、CSV、notebook 就够),② 其余失败(ssh 断开、权限、配额)同样静默 —— 模型以为远端已有该文件。2.4.24 起:>4 MiB 改**分块上传**(并校验远端字节数),不再失败;仍失败时**明确报错**,消息写清"本地镜像已写入成功、只是没同步到远端"并给出 `remote_ssh_push` 补推路径。想恢复旧行为(只写日志):设置 `writeBackFailure: "log"`(2.4.25 起可直接在设置面板的下拉里选) |
+| **`write` / `edit` 报错说「本地镜像已写入成功,但**没有推送到远端**」** | 这是 **2.4.25 起的护栏 B**(issue #24 第二轮,默认开):推之前插件发现远端这一份**自上次推送后已被改动**(共享集群上最常见的就是你自己刚跑完的作业写了它),于是选择**只报告、不覆盖** —— 直接推上去会把那些改动静默抹掉。处理:先 `remote_ssh_sync`(或 `remote_ssh_cat`)把远端拉下来比对;确认要以本地为准,用 `remote_ssh_push` 覆盖(push/sync 成功后该记录会被清掉,不会一直拦着)。想彻底关掉:设置里的 `writeBackFreshness`,或环境变量 `DSH_REMOTE_SSH_WRITEBACK_FRESHNESS=off`。若日志里写的是"无法确认远端状态",那是连接问题 —— 这种情况插件**照常推送**,只留一行日志(读不到 ≠ 被改过)。设了 `writeBackFailure: "log"` 时工具不会报错,但**同一份完整报告会写进日志**(2.4.26 起),别只看工具返回值 |
+| **本地会话里"部分文件打不开":`cannot read: ENOENT …\tools\x.py`** | **2.4.27 起已修复(issue #25)**。为了远程工作区,本插件以 `exact` 路由接管了 better-sidebar 的 `/sidebar/file` 与 `/sidebar/api/fs.*` —— 而 **exact 连本地会话一起抢**:本地分支此前把相对路径原样交给 `fs`,Node 按**插件宿主进程的 `process.cwd()`**(pnpm profile 目录)解析,于是相对路径报 ENOENT、绝对路径正常,用户看到的就是"部分文件打不开"。写操作更危险:`fs.write` / `fs.remove` 拿到相对路径会打到**插件宿主目录**里。2.4.27 起所有落点(`/sidebar/file`、`fs.read/tree/trees/write/rename/remove/mkdir/search` 的本地与远程分支、`git.*`、`open.external`)都先按**会话 cwd** 归一(与上游 `ensureWorkspacePath` 同语义);取不到会话 cwd 时**明确报错**,不再猜 `process.cwd()` |
+| **远程工作区里文件树「新建文件」看着成功了,远端却没有这个文件;git 面板的 blame / 工作树 / 拉取 / 推送结果不对,或报 `not a git repository`** | **2.4.28 起已修复**。better-sidebar **0.25.0** 新增了 9 个端点,其中 6 个与仓库/路径相关,而本插件此前没有注册它们 —— 本插件用 `exact` 路由接管 `/sidebar/api/fs.*` 与 `git.*`,**没注册的端点会回落到上游实现**,而远程工作区里上游拿到的 cwd 是**本地镜像目录**:`fs.createFile` 于是只在镜像里建了个空文件(远端永远没有,与 2.4.18 那次 `fs.trees` 绕过拦截同一类);`git.blame` / `git.diff-head` / `git.worktrees` 按镜像的 git 状态计算(镜像通常没有 `.git`,于是空结果或报错);`git.pull` / `git.push` 动的更是镜像那个与远端无关的仓库。2.4.28 起这 6 个端点全部接管并在**远端**执行;纯模型端点(`git.models` / `git.suggest-message` / `git.commit-model`)不碰仓库路径,仍交给上游。升级到 **2.4.28** 并重启 DSH 即可 |
+| **在会话目录里写的草稿/临时文件被无声推到远端(共享集群的项目目录)** | 写回桥对 agent 的 `write`/`edit` 是"落镜像 + 推远端"(issue #24 的护栏建议)。工作区可设 `writeBack: false` 整体关掉写回,或用 `writeBackExclude` 排除路径:镜像相对路径、支持 `*` / `**` / `?`,结尾带 `/` 视为目录前缀,例如 `["_patch/**", "*.log", "scratch/"]`。两者都**只影响写回**,`remote_ssh_push` 仍可手工把需要的东西推上去 |
+| **远程工作区里写/删的文件没落到远端,或报 `400 ENOENT … lstat '<镜像路径>'`;在**子目录**里开的会话尤其容易遇到** | **2.4.29 起已修复**。远程工作区的判定此前只认"正好放着 `.remote-ssh.json` 的那一级目录"(`readRemoteInfoSync` **不向上遍历**):真实客户端总带有效 `sessionId`(会话 cwd = 镜像根)所以一直没暴露,但**会话在工作区子目录里启动**、或客户端带了**过期/未知 sessionId**(判定回退到请求里的 `path`)时会漏判 —— 漏判的后果是写/删**静默作用在本地镜像**上。2.4.29 起判定改为按**工作区根前缀**匹配(同时修掉"拿更深的路径当基准、远端路径少一段"的映射问题;`@` 文件引用补全同样受益)。另外,**镜像目录下但不属于任何已注册工作区**的路径现在**明确报错**(读写都报),不再当成本地路径去操作。升级到 **2.4.29** 并重启 DSH 即可 |
+| 命令卡住不返回 | 默认 120s 超时后自动丢弃会话(**超时不杀远端命令**);长时任务用 `timeoutMs: 0`,随时可用 `remote_ssh_kill` 或按停止键取消 —— 两者都会 SIGHUP 远端进程组 |
+| 远程工作区里在侧栏编辑器改完文件、点 √ 或 Ctrl+S 保存不上 | **2.4.45 起已修复(issue #37)**:保存以前只写进本地镜像,远端文件没变。现在直接写远端,并保留原文件的 BOM 与行尾;基线过期会回 `fs-conflict` 让编辑器提示重载。GBK / UTF-16 等非 UTF-8 文件目前**明确拒绝**保存(避免用 UTF-8 覆盖老编码),请在远端改或让模型用工具写 |
+| 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB(更大自动回落一次性连接);用 `remote_ssh_exec` + `head`/`tail` 分段处理 |
+| **远程工作区会话里,本机绝对路径读不到、写/删落在远端;或者远端绝对路径(`/mnt/...`、`/tmp/x.log`)一律打不开** | **2.4.30 起已修复(issue #26)**。判定"这次请求走不走远端"此前只看**会话 cwd**:会话在远程工作区 → 整条请求都进远端分支。于是 ① 本机绝对路径被推到远端(`<远端根>/Users/...`),读报 `No such file`,**远端恰好有同路径文件时会静默返回另一份文件**,`fs.write` 本机不落盘、`fs.remove`/`fs.rename` 把删除/重命名打到远端;② 远端绝对路径被当成相对路径再拼一次远端根(`/...`)。现在按**每条请求路径**的归属决定:镜像成员 → 远端映射;盘符/UNC(含 `C:foo`)→ **本地**,即使会话在远程工作区;`/...` 远端绝对路径 → **原样下发**;相对路径 → 按会话 cwd;同一次请求混用本机与远端/镜像路径 → 明确 `400`(不再猜一侧)。同一版把 `localToRemote()` 那句"镜像之外按相对路径处理"的兜底从 `debug` 提到 `warn`(真被触发说明又出现同类误判) |
+| **「添加工作区」→「📁 本地目录」tab 一打开就报「path 为必填项」,目录树空、无法添加本地工作区** | **2.4.31 起已修复(issue #27)**:这是 2.4.27 为修 issue #25 引入 `localPathOf()` 时误伤的 —— 弹窗首次打开会**按设计**发空路径(语义是「打开主目录」,`lib/client.js` 有注释、`localListDir()` 也有 `homedir()` 兜底),而空路径被一律判 400。现在只放行「无会话 cwd + 空路径 + `fs.tree` 这个只读方法」;**写操作、相对路径、其它方法一律照旧报错**。临时绕过:在路径栏手填完整本地绝对路径再点「打开」 |
+| **远程工作区里点「预览」报「文件不存在,可能已被移动或删除」,同一路径右键下载却正常** | **2.4.35 起已修复(issue #29)**。内置预览取内容不走本插件的 HTTP 路由,而是进程内的 workspace-file RPC → `ctx.fs`,而 `ctx.fs` 的根是**本地镜像** —— 镜像里没有的文件必然 not-found(这就是 #15「read 仍读镜像」的另一面)。现在 `ctx.fs` 的读方法有一层影子:**本地有就照旧读本地,本地没有才回远端取**;远端也没有时仍按原样报不存在。仍未覆盖:远端被改动而镜像里也有旧版本时,读到的仍是镜像那份;远端文件变更不触发实时刷新 |
+| **升级到 2.4.35 后所有技能消失(`skill` 报 unknown / 系统提示里没有技能目录)** | **2.4.36 起已修复(issue #30,2.4.35 的回归)**。2.4.35 的读影子层在"本地不存在"时会回远端取,而路径**不在任何远程镜像里**时把本地原本的 not-found 换成了中文 `FS_IO_ERROR`;`dsh-skill-filesystem` 只认 `FS_NOT_FOUND / ENOENT / FS_NOT_DIRECTORY` 为"根不存在",于是项目级技能根(`/.dsh/skills`,绝大多数项目没有)一列就崩,整份技能目录一条都不注入。现在"远端也拿不到"一律退回本地原始错误(新内部码 `NO_MIRROR`),语义与 2.4.34 一致;远端确有内容才出现的二进制/过大/取消错误照旧透出。临时绕过:回退到 2.4.34 |
+| **与远程工作区同名的本地项目被打上地球角标(🌐)** | **2.4.37 起已修复(issue #31)**。角标是客户端按「工作区行」贴的 DOM 装饰,旧实现只按**标题文本**认行 —— 本地项目与远程工作区同名时文本一样,于是本地那个也被标上。现在改用壳层自带的行键 `data-row-key="workspace:<原生工作区 id>"` 精确对齐(宿主侧把该 id 存进工作区记录 `shellWorkspaceId`,老记录按镜像路径自动回填);标题匹配只作为旧壳层回退,且同名行不止一行时都不标;升级前误标的行会被自动摘掉 |
+
+## 原理
+
+插件注册 9 个 exact 路由(`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`,better-sidebar 0.19 新增的 `fs.rename`、`fs.remove`,0.23+ 新增的 `fs.trees`、`fs.mkdir`,以及 0.24 的 `open.external`),在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH,否则走本地 fs。客户端看到的是本地镜像路径,Host 自动转换为远程路径——对客户端完全透明。
+
+> `fs.trees` 是 0.23+ 的**批量**列举端点(一次请求带上「工作区根 + 所有已展开目录」,≤64 条;旧版是逐层 `fs.tree`)。远程分支用 `remoteListDirsBatch()` **一次 SSH 往返**列举全部目录(逐目录标记行 + `find -printf`,单层失败只影响该层),命中目录缓存(TTL 5s)的层 0 RTT。少注册这一个路由,新版客户端的整棵文件树就会静默回落到宿主的本地实现 —— 这正是 2.4.18 修的问题。
+
+> `open.external` 是 0.24 的「打开方式 / 在文件管理器中显示」端点,宿主侧用本机打开器执行(Windows:`explorer.exe /select,<路径>`、`rundll32 url.dll,FileProtocolHandler `)。远程工作区里客户端只有镜像路径,本插件因此把路径翻译成远端路径并改开 `vscode://vscode-remote/ssh-remote+<`~/.ssh/config` 别名><远端路径>`:`url` 保留客户端选中的 scheme(vscode / cursor / zed),`reveal` 打开该文件**所在的远端目录**。别名按「Host 同名或 HostName 相同 + 端口一致 + 用户兼容」匹配(纯函数 `remoteEditorAuthority`),让 VS Code 复用该条目的端口/用户/密钥/跳板机;**`~` 由插件自己展开**(URL 不过 shell,`~/run/...` 必须先换成远端 home 的绝对路径 —— 用 `printf %s "$HOME"` 查一次并按 profile 缓存 10 分钟),无可用别名或拿不到 home 时回退本机行为并打 warn。**不要**在 better-sidebar 里填 `openWith.sshHost`——那条分支由客户端自行打开、路径仍是镜像路径。
+
+**模型侧的文件工具(agent 的 `write`/`edit`)**走的是**进程内** `ctx.fs`(宿主 base bundle 挂的是本地 `fs-sandbox`),不经过任何 HTTP 路由,因此 2.4.13 及以前只落**本地镜像**——用户在远端机器上找不到文件,只能人工 `remote_ssh_push`。2.4.14 起插件包装 `ctx.fs` 的 `writeText`/`editText`:**原写入照旧**(镜像内容、沙箱围栏、写意图语义全不变),成功后把同一份内容**定向推回远端对应的那个文件**(不是整镜像 tar,避免用旧镜像覆盖远端其它文件),写前自动 `mkdir -p` 远端父目录。推送失败只记一条 warn——本地写入已成功,桥接层不会让写操作变成失败;包装不可用时(服务缺失/被替换)退回旧行为并在日志提示。
+
+远程读取采用**单往返合并读**:一条池化命令同时返回 `size/mtime` 帧与文件内容(文本类扩展名优先 raw 直传,字节长 + U+FFFD 双校验失败自动回退 base64,结果逐字节一致);配合主机侧结果缓存与变更失效(见下节)。
+
+Shell wrapper(`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`)检测工作区 `.remote-ssh.json`,自动 `ssh -tt` 连接远程,使内置「终端」页签透明接入。
+
+## 缓存与一致性
+
+远程读取与目录列举结果在主机侧缓存(读 LRU 32 条 + 列举 LRU 64 条,TTL 5 秒;单条 >1MiB 不缓存、总量 32MB 字节预算,防止大文件驻留拖慢宿主):TTL 内重复打开或切回页签 **0 网络往返**;过期后先做一次轻量 mtime+size 复验,未变化则免重传。写、删除、移动、建目录、上传、推送(push)、成功的远端 exec 与变更类 git 子命令(add/reset/commit/checkout/revert/cherry-pick)会自动失效相关缓存,并以每 profile 缓存代(epoch)兜底「同秒同 size 写」等粒度盲区。
+
+已知限制:
+
+- 集成终端(`ssh -tt`)与远端其它进程改动的文件依赖 TTL + 复验兜底,最多 **5 秒**陈旧;
+- **镜像是"本地优先"的读影子(2.4.35 起,issue #29)**:`ctx.fs` 的读方法(`stat` / `lstat` / `resolve` / `readText` / `streamText` / `readBytes` / `readByteRange` / `listDir`)现在**本地有就照旧读镜像,镜像里没有才回远端取**(内置预览、agent 的 `read` 都因此能读到只在远端存在的文件)。两点仍未覆盖:① 文件在远端被其它人改动、而镜像里也有旧版本时,读到的仍是**镜像那份**(本地优先;用 `remote_ssh_sync` 重拉镜像即最新);② 远端文件的变更**不会**触发实时刷新(`ctx.fs.watch` 对远端影子是空实现),预览不会自动跟新;另外远端整文件读受 4 MiB 单次上限约束;
+- `/sidebar/file` 下载池化路径有效上限约 **6.29MB**,更大文件自动退回一次性连接下载(可成功,多一次重连开销);
+- 二进制内容伪装成文本扩展名时会多一次 base64 回退往返(结果正确)。
+
+## ❤️ 七夕快乐
+
+本项目是送给 **zhangyi** 的七夕礼物。
+
+愿它像连接起一台台远方的超算一样,也把我们紧紧连在一起。七夕快乐 ❤️
+
+—— 2026 年 8 月 18 日
+
+## 更新日志
+
+版本历史与每版修复细节见 [CHANGELOG.md](./CHANGELOG.md)(最近:2.4.3 适配 better-sidebar 0.19 端点、2.4.2 修复设置图标闪现、2.4.0 命令级超时与 `remote_ssh_kill`)。
+
+## 许可证
+
+[MIT](./LICENSE)
+
+---
+
+如果这个插件帮到了你,欢迎在 GitHub 上点个 ⭐ [Star](https://github.com/ZhangFengshun/dsh-remote-ssh),或到 [DSH Market](https://dshmarket.com) 收藏——这会帮助更多需要远程超算开发的人找到它。