@zhangfengshun/dsh-remote-ssh 2.1.6 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.2.0] — 远程命令连接复用（实测 ≈15× 提速）+ 协议/安全加固
+### 性能
+- **`remote_ssh_exec` 走持久会话池**：不再每次调用做完整 SSH 握手。真实 HPC（ssh.cn-zhongwei-1.paracloud.com，2222 端口）实测：一次性连接单命令平均 **1292ms**，连接复用后单命令平均 **84.3ms**，**约 15.3× 提速**；`stdin` 参数经 heredoc 走同一条复用通道。
+- **stderr/stdout 分离语义保留**：stderr 重定向到远端临时文件、退出码哨兵后 cat 回传并以第二个哨兵收尾（双哨兵协议）。
+- **读路径保持轻量**：`ls`/`cat`/`grep`/`glob` 继续走 `2>&1` 合并协议，热路径避开子 shell 与临时文件开销。
+- **大文件读取先 stat**：超过 4MB 只读前 4MB（`head -c` 截断并标记 truncated），不再让持久会话缓冲无限增长。
+### 安全 / 健壮性
+- **会话输出硬上限 8MB**：单条命令哨兵到达前缓冲超限即重置会话并给出明确报错，防止远端海量输出撑爆内存。
+- **密钥认证非交互连接加 `-o BatchMode=yes -o PreferredAuthentications=publickey`**：带口令的私钥/意外交互立即失败并返回可读提示（不再挂到超时），同时缩短建连时间；交互式终端（`ssh -tt`）不受影响。
+- **分离协议用双层子 shell**：用户命令中的 `exit`/`cd` 不再弄挂共享会话（内层子 shell 隔离，实测远端 `exit 7` 后会话存活且退出码正确传回）。
+- **写入上限 4MB**：超限直接拒绝并给出清晰报错；写入失败现在能拿回远端 stderr（此前错误信息丢失）。
+- 配合 2.1.7 纳入的修复（`--include` 转义、stderr 排空、删除配置级联清理、keyPath `~` 展开、会话池 key 含认证信息），完成一轮兼容性/安全性全面检查。
+
+## [2.1.7] — 兼容 DSH Desktop ≥ 2.0.4：polyfill __DSH_MODULES__ + 可靠性/安全修复
+### 修复
+- **__DSH_MODULES__ polyfill**：better-sidebar 0.15+ 的懒加载 chunk（编辑器等）依赖 `globalThis.__DSH_MODULES__`，而 DSH Desktop ≥ 2.0.4 的 shell 不再挂载该全局，导致侧边栏面板打不开（"chunk ... client module system unavailable"）。Client 半边启动时用内核 `modules` 服务补挂该全局（better-sidebar 已注入则保持原值），并带定期兜底重试。
+- **持久会话 stderr 排空**：SSH 会话的 stderr 管道此前无人消费，写满后远端 ssh 进程阻塞、会话假死；现在持续排空并保留最近 64KB，会话意外关闭时报错会附带最近 stderr 尾部，便于排查断连原因。
+- **修复 `remote_ssh_grep` 命令注入**：`--include` 参数此前未做 shell 转义，可通过构造参数在远端执行任意命令；现已与其它参数一样经 `shellQuote` 引用。
+- **删除连接配置时级联清理**：删除 profile 时同步删除其远程工作区的原生注册与本地镜像目录（复用统一的 `cleanupWorkspace`），不再留下指向已删配置的孤儿工作区。
+- **密钥路径支持 `~` 展开**：`keyPath` 按 `~`、`~/` 前缀展开为绝对路径，与设置界面占位符（`~/.ssh/id_rsa`）行为一致。
+- **会话池 key 纳入认证信息**：修改连接配置的 keyPath/authMethod 后立即重建 SSH 会话，不再复用旧连接。
+- 清理每次文件请求的 `console.log` 调试输出（改走 `ctx.logger.debug`）；`localToRemote` 对镜像目录之外的路径不再静默拼出错误远程路径。
+- 文档：补全 2.1.0 以来缺失的 CHANGELOG 条目；README 安装命令版本号同步为 2.1.7。
+
+## [2.1.6] — P0 打磨：远程下载 / 流式上传完善 / 远程 Git / 重连
+### 修复 / 改进
+- **远程文件下载与媒体预览**：拦截 better-sidebar 的 `/sidebar/file`（同路径 exact 路由优先），远程工作区中的文件直接从远端 base64 拉回（上限 64MB），本地照旧。
+- **流式上传**：`/remote-ssh/upload` 把请求体直接管道到远端 `cat > target`（二进制安全、恒定内存），请求中断时终止远端进程。
+- **远程 Git 面板**：拦截 `/sidebar/api/git.*`（status/diff/log/branch/commit-diff/show/stage/unstage/commit/checkout/discard/revert/cherry-pick），远程工作区中在远端目录执行同语义 git 命令。
+- **SSH 失败修复建议**：端口转发占用 / 公钥认证失败 / 连接拒绝 / 超时 / 域名解析失败翻译为带修复建议的中文提示。
+
+## [2.1.5] — 同步 better-sidebar 0.15+ 上传到远程工作区
+### 修复
+- better-sidebar 0.15+ 的上传 UI 直连 `/sidebar/upload`，远程工作区镜像目录会导致文件只落在本地镜像。Client 半边包装 `fetch`：目标目录位于远程工作区镜像内时把上传重定向到 `/remote-ssh/upload`，经 SSH 直接写远端。
+
+## [2.1.4] — 修复远程工作区标题卡在镜像目录名
+### 修复
+- `workspaceRegistry.create` 只对新建记录应用 title，旧工作区（早期版本未传 title）标题卡在镜像目录名（如 `wmt3tev5cdfge`）。创建时显式 `setTitle`，并新增启动自愈 `healWorkspaceTitles`（仅在标题等于镜像目录 basename 时修复，不覆盖用户自定义标题）。
+
+## [2.1.3] — 远程工作区标题默认取远程路径最后一段
+### 改进
+- 创建远程工作区时的默认标题改为远程路径最后一段目录名（如 `~/run/zfs/codex/DSH_Test → DSH_Test`），取不到有效段时回退为 `连接名:远程路径`；原生工作区标题带 🌐 前缀。
+
+## [2.1.2] — 修复 ssh config RemoteForward 端口占用导致连接失败
+### 修复
+- 插件内部连接（文件读写 / 工具 / 同步）追加 `ClearAllForwardings=yes`；shell wrapper 追加 `ExitOnForwardFailure=no`。`~/.ssh/config` 里的 `RemoteForward` 端口被上次会话占用且 `ExitOnForwardFailure yes` 时不再导致连接直接失败。
+- 把 SSH 常见失败（端口转发占用 / 公钥认证失败 / 连接拒绝 / 超时 / 域名解析失败）翻译成带修复建议的中文提示。
+
+## [2.1.1] — 新增英文 README
+### 文档
+- 新增 README_EN.md，中英文版本互链。
+
+## [2.1.0] — README 拆分语言版本
+### 文档
+- 移除 README 内联双语，拆分为 README.md（中文）与 README_EN.md（英文）。
+
 ## [2.0.1] — 修复远程检测：从 payload.path 也查找 .remote-ssh.json
 ### 修复
 - **sessionCwd 为空时无法检测远程工作区**：客户端请求有时只带 `payload.path` 不带 `cwd`，而 `ctx.sessions.get(sessionId)` 可能返回 undefined（session 未创建或 ID 不匹配）。现改为：先尝试 `sessionCwd`，再尝试 `payload.path`，两者都会检查 `.remote-ssh.json`。

package/README.md

@@ -17,7 +17,7 @@
 ## 安装
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.0
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.7
 ```
 
 > 安装后需**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。

package/README_EN.md

@@ -0,0 +1,67 @@
+# @zhangfengshun/dsh-remote-ssh
+
+English | [中文](./README.md)
+
+A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via SSH, and directly operate remote files and terminals within DSH's built-in **Files** and **Terminal** sidebar tabs.
+
+## Features
+
+| Feature | Description |
+| --- | --- |
+| 🔌 SSH Connection | Key / password auth, ProxyJump bastion, one-click import from `~/.ssh/config` |
+| 📂 Remote Files | Built-in **Files** tab reads/writes remote files directly via SSH — no sync needed |
+| 💻 Remote Terminal | Built-in **Terminal** tab auto-detects remote workspaces, opens SSH interactive shell |
+| 🌐 Remote Workspace | Select a remote directory to create a native workspace, one-click enter |
+| 🤖 Model Tools | 12 `remote_ssh_*` tools, session-aware with auto-filled connection params |
+
+## Installation
+
+```bash
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.7
+```
+
+> **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
+
+## Usage
+
+1. **Settings → 🖥️ Remote SSH** → Add a connection (host/port/user/key) → Click "Test Connection"
+2. **Add Workspace** → Choose "Select Remote Directory…" → Pick a connection → Browse and select
+3. Open the built-in **Files** tab → Remote files shown directly, edits save back to remote
+4. Open the built-in **Terminal** tab → Auto SSH to remote host (key auth only)
+
+## Model Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `remote_ssh_profiles` | List saved connections + current session's remote workspace context |
+| `remote_ssh_exec` | Execute remote command |
+| `remote_ssh_ls` | List remote directory |
+| `remote_ssh_cat` | Read remote file |
+| `remote_ssh_write` | Write remote file |
+| `remote_ssh_grep` | Search remote file contents |
+| `remote_ssh_glob` | Find remote files by glob |
+| `remote_ssh_mkdir` | Create remote directory |
+| `remote_ssh_delete` | Delete remote file/directory |
+| `remote_ssh_move` | Move/rename |
+| `remote_ssh_sync` | Sync remote to local mirror |
+| `remote_ssh_push` | Push local mirror back to remote |
+
+In a remote-workspace session, `profileId` and other connection params can be omitted.
+
+## How It Works
+
+The plugin registers 4 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.write`, `fs.search`) that intercept better-sidebar's prefix route. When the session cwd contains `.remote-ssh.json`, requests go through SSH; otherwise local fs. The client sees local mirror paths — the Host transparently translates them to remote paths.
+
+A shell wrapper (`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`) detects the workspace's `.remote-ssh.json` and auto-launches `ssh -tt`, making the built-in **Terminal** tab transparently connect to remote.
+
+## ❤️ Happy Qixi
+
+This project is a Qixi Festival gift for **zhangyi**.
+
+May it connect us as closely as it connects to distant supercomputers. Happy Qixi ❤️
+
+—— August 18, 2026
+
+## License
+
+[MIT](./LICENSE)

package/lib/client.js

@@ -1063,6 +1063,39 @@ window.__ModuleLoader__.load({
       var slots = ctx.slots;
       var locale = ctx.locale;
 
+      // 兼容 DSH Desktop ≥2.0.4：shell 不再把客户端模块系统挂到
+      // globalThis.__DSH_MODULES__，而 dsh-better-sidebar 0.15+ 的懒加载
+      // chunk（editor 等）会回退到该全局——缺失时侧边栏面板打不开、报
+      // "chunk ... client module system unavailable"。这里用内核提供的
+      // modules 服务补挂该全局；better-sidebar 已注入则保持原值。
+      try {
+        if (typeof globalThis !== "undefined") {
+          var fallbackModules = null;
+          try { if (ctx.modules && typeof ctx.modules.import === "function") fallbackModules = ctx.modules; } catch (e) {}
+          if (!fallbackModules && ctx.get && typeof ctx.get === "function") {
+            try { fallbackModules = ctx.get("modules"); } catch (e) { fallbackModules = null; }
+          }
+          // 定期兜底：better-sidebar 若把本插件应用时间之后的模块系统清掉，也补回。
+          if (globalThis.__DSH_MODULES__ === undefined && fallbackModules === null) {
+            var waitModules = 0;
+            var waitTimer = setInterval(function () {
+              waitModules += 1;
+              try {
+                var ms = (ctx.get && typeof ctx.get === "function") ? ctx.get("modules") : null;
+                if (ms && typeof ms.import === "function") {
+                  globalThis.__DSH_MODULES__ = ms;
+                  clearInterval(waitTimer);
+                }
+              } catch (e) {}
+              if (globalThis.__DSH_MODULES__ !== undefined || waitModules > 40) clearInterval(waitTimer);
+            }, 250);
+          }
+          if (!globalThis.__DSH_MODULES__ && fallbackModules && typeof fallbackModules.import === "function") {
+            globalThis.__DSH_MODULES__ = fallbackModules;
+          }
+        }
+      } catch (e) {}
+
       // 注册中英文词典并绑定当前语言；locale 切换时 i18n.subscribe 触发组件重渲染。
       if (locale) {
         ctx.effect(function () { return locale.register(NS, { zh: zh, en: en }); }, "dsh-remote-ssh: dictionaries");

package/lib/index.js

@@ -25,6 +25,8 @@ const Config = z.object({});
 
 const NS = "dsh-remote-ssh";
 const MAX_BYTES = 4 * 1024 * 1024;
+/** 持久会话单条命令的 stdout 缓冲硬上限（防止大文件/海量输出撑爆内存）。 */
+const SESSION_MAX_STDOUT = 8 * 1024 * 1024;
 const API_BASE = "/remote-ssh/api/";
 
 /** 连接配置 schema（存于 settings）。 */
@@ -161,8 +163,10 @@ async function listSshConfigHosts() {
  * 避免每次操作都做完整 TCP 握手 + SSH 密钥交换 + 认证（超算/跳板机单次 2-10 秒）。
  *
  * 工作原理：向 bash 的 stdin 写入命令 + 哨兵标记 printf，从 stdout 读取直到哨兵出现，
- * 哨兵后的数字即退出码。每条命令用 2>&1 合并 stderr（成功时 stderr 为空，不影响解析；
- * 失败时错误信息在 stdout 中，退出码非 0）。带 stdin 的写操作用 heredoc。
+ * 哨兵后的数字即退出码。split（分离 stderr）模式下，stderr 重定向到远端临时文件，
+ * 退出码哨兵之后 cat 出来并用第二个哨兵收尾：保住 stdout/stderr 分离的同时，
+ * 让 remote_ssh_exec 这类调用也走连接复用（首调用建连后毫秒级返回）。
+ * 输出侧有硬上限 SESSION_MAX_STDOUT：哨兵出现前缓冲超限即重置会话，下次调用自动重建。
  */
 class CommandSession {
   constructor(subprocess, profile) {
@@ -176,6 +180,8 @@ class CommandSession {
     this.sentinel = "DSHEOF" + Math.random().toString(36).slice(2, 14) + Math.random().toString(36).slice(2, 10) + "DSHEOF";
     this.lastUsed = Date.now();
     this.connectPromise = null;
+    /** 最近一段 stderr（防背压消费 + 会话关闭诊断）。 */
+    this.errBuf = "";
   }
 
   async connect() {
@@ -189,6 +195,7 @@ class CommandSession {
     if (this.handle) { try { this.handle.terminate(); } catch (e) {} this.handle = null; }
     this.alive = false;
     this.buf = "";
+    this.errBuf = "";
     this.current = null;
     this.queue = [];
     const argv = sshArgv(this.profile, "bash", false);
@@ -203,10 +210,16 @@ class CommandSession {
       this.buf += chunk.toString("utf8");
       this._check();
     });
+    // stderr 必须消费：不挂监听会让管道缓冲填满、远端 ssh 写 stderr 阻塞（会话假死）。
+    // 保留最近 64KB 用于会话关闭时的诊断。
+    h.stderr.on("data", (chunk) => {
+      this.errBuf = (this.errBuf + chunk.toString("utf8")).slice(-65536);
+    });
     const onEnd = () => {
       this.alive = false;
-      if (this.current) { this.current.reject(new Error("ssh 会话已关闭")); this.current = null; }
-      while (this.queue.length) this.queue.shift().reject(new Error("ssh 会话已关闭"));
+      const errMsg = "ssh 会话已关闭" + (this.errBuf.trim() ? ": " + this.errBuf.trim().slice(-300) : "");
+      if (this.current) { this.current.reject(new Error(errMsg)); this.current = null; }
+      while (this.queue.length) this.queue.shift().reject(new Error(errMsg));
     };
     h.stdout.on("end", onEnd);
     h.stdout.on("error", onEnd);
@@ -217,34 +230,87 @@ class CommandSession {
 
   _check() {
     if (!this.current) return;
-    const idx = this.buf.indexOf(this.sentinel);
-    if (idx < 0) return;
-    const before = this.buf.slice(0, idx);
-    const after = this.buf.slice(idx + this.sentinel.length);
-    const nl = after.indexOf("\n");
-    const codeStr = nl >= 0 ? after.slice(0, nl) : after;
-    const rest = nl >= 0 ? after.slice(nl + 1) : "";
-    this.buf = rest;
-    const exitCode = parseInt(codeStr, 10);
-    const cur = this.current;
+    const item = this.current;
+    if (!item.exitParsed) {
+      // 找到主哨兵：解析退出码；split 模式还要等第二个哨兵（stderr 内容）
+      const idx = this.buf.indexOf(this.sentinel);
+      if (idx < 0) { this._enforceCap(); return; }
+      const before = this.buf.slice(0, idx);
+      const after = this.buf.slice(idx + this.sentinel.length);
+      const nl = after.indexOf("\n");
+      const codeStr = nl >= 0 ? after.slice(0, nl) : after;
+      this.buf = nl >= 0 ? after.slice(nl + 1) : "";
+      const exitCode = parseInt(codeStr, 10);
+      item.exitCode = isNaN(exitCode) ? -1 : exitCode;
+      item.stdout = before;
+      item.exitParsed = true;
+      if (!item.errSentinel) {
+        this.current = null;
+        item.resolve({ stdout: item.stdout, stderr: item.stderr, exitCode: item.exitCode });
+        this._next();
+        return;
+      }
+    }
+    if (item.errSentinel) {
+      // split 模式第二段：等 stderr 哨兵（可能已在缓冲里）
+      const idx = this.buf.indexOf(item.errSentinel);
+      if (idx < 0) { this._enforceCap(); return; }
+      const errText = this.buf.slice(0, idx);
+      const after = this.buf.slice(idx + item.errSentinel.length);
+      const nl = after.indexOf("\n");
+      this.buf = nl >= 0 ? after.slice(nl + 1) : "";
+      item.stderr = errText.replace(/\n$/, "");
+      this.current = null;
+      item.resolve({ stdout: item.stdout, stderr: item.stderr, exitCode: item.exitCode });
+      this._next();
+    }
+  }
+
+  /** 单条命令输出超过硬上限：立即重置会话（下次调用自动重建），拒绝挂起/撑爆内存。 */
+  _enforceCap() {
+    if (!this.current || this.buf.length < SESSION_MAX_STDOUT) return;
+    const item = this.current;
     this.current = null;
-    cur.resolve({ stdout: before, exitCode: isNaN(exitCode) ? -1 : exitCode });
-    this._next();
+    item.reject(new Error("单条命令输出超过 " + SESSION_MAX_STDOUT + " 字节上限，会话已重置（若确实需要更大输出请拆分命令）"));
+    this.alive = false;
+    if (this.handle) { try { this.handle.terminate(); } catch (e) {} this.handle = null; }
+    while (this.queue.length) this.queue.shift().reject(new Error("ssh 会话已重置"));
   }
 
   _next() {
     if (this.current || !this.alive || this.queue.length === 0) return;
     const item = this.queue.shift();
-    this.current = { resolve: item.resolve, reject: item.reject };
+    item.exitParsed = false;
+    item.stdout = "";
+    item.stderr = "";
+    item.exitCode = -1;
+    item.errSentinel = item.split
+      ? "DSHERR" + Math.random().toString(36).slice(2, 14) + Math.random().toString(36).slice(2, 8)
+      : null;
+    this.current = item;
     try {
+      const errFile = "${TMPDIR:-/tmp}/.dsh-err-" + Math.random().toString(36).slice(2, 10);
+      const exitMark = "printf '\\n" + this.sentinel + "%s\\n' $?";
+      const errTail = "cat " + errFile + " 2>/dev/null; rm -f " + errFile + "; printf '\\n" + item.errSentinel + "ok\\n'";
       let toWrite;
-      if (item.stdinData !== undefined && item.stdinData !== null) {
-        // 写操作：heredoc 传内容，不用 2>&1（cat > file 不产生 stdout）
+      if (item.split) {
+        // 分离 stderr 用双层子 shell：
+        //   外层 ( ... ) 保证 printf 链自身不会受用户命令返回值影响；
+        //   内层 ( { cmd ; } ) 隔离用户命令里的 exit/cd，绝不弄挂共享 bash 会话
+        //   （exit 只会退出内层子 shell，后面照常打印哨兵与退出码）。
+        if (item.stdinData !== undefined && item.stdinData !== null) {
+          const delim = "DSHW" + Math.random().toString(36).slice(2, 14);
+          toWrite = "( ( " + item.cmd + " <<'" + delim + "'\n" + String(item.stdinData) + "\n" + delim + "\n) 2>" + errFile + "; " + exitMark + "; " + errTail + " )\n";
+        } else {
+          toWrite = "( ( " + item.cmd + " ; ) 2>" + errFile + "; " + exitMark + "; " + errTail + " )\n";
+        }
+      } else if (item.stdinData !== undefined && item.stdinData !== null) {
+        // 快速路径写操作：heredoc 传内容，2>&1 合并（成功时 stderr 为空，不影响解析）
         const delim = "DSHW" + Math.random().toString(36).slice(2, 14);
-        toWrite = item.cmd + " <<'" + delim + "'\n" + String(item.stdinData) + "\n" + delim + "\nprintf '\\n" + this.sentinel + "%s\\n' $?\n";
+        toWrite = item.cmd + " <<'" + delim + "'\n" + String(item.stdinData) + "\n" + delim + "\n" + exitMark + "\n";
       } else {
-        // 读/列举/搜索：2>&1 合并 stderr（成功时 stderr 为空）
-        toWrite = "{ " + item.cmd + " ; } 2>&1\nprintf '\\n" + this.sentinel + "%s\\n' $?\n";
+        // 读/列举/搜索快速路径：2>&1 合并 stderr（成功时 stderr 为空）
+        toWrite = "{ " + item.cmd + " ; } 2>&1\n" + exitMark + "\n";
       }
       this.handle.stdin.write(toWrite);
     } catch (e) {
@@ -254,11 +320,11 @@ class CommandSession {
     }
   }
 
-  async exec(cmd, stdinData) {
+  async exec(cmd, stdinData, split) {
     await this.connect();
     this.lastUsed = Date.now();
     return new Promise((resolve, reject) => {
-      this.queue.push({ cmd, stdinData, resolve, reject });
+      this.queue.push({ cmd, stdinData, split: !!split, resolve, reject });
       this._next();
     });
   }
@@ -283,7 +349,14 @@ function sshArgv(p, remoteCmd, tty) {
   // 清除 ssh config 里的 RemoteForward/LocalForward，避免端口被占时连接直接失败。
   opts.push("-o", "ClearAllForwardings=yes");
   if (p.proxyJump) opts.push("-o", "ProxyJump=" + String(p.proxyJump));
-  if (p.authMethod === "key" && p.keyPath) opts.push("-i", p.keyPath);
+  if (p.authMethod === "key" && p.keyPath) opts.push("-i", expandSshPath(p.keyPath));
+  // 密钥认证的非交互连接（会话池 / 工具 / 同步）要求一次性无提示完成：
+  // BatchMode 禁用 passphrase/确认交互（有口令的密钥立即报错而不是挂到超时），
+  // PreferredAuthentications=publickey 跳过无谓的认证方法协商，缩短建连时间。
+  if (!tty && p.authMethod === "key") {
+    opts.push("-o", "BatchMode=yes");
+    opts.push("-o", "PreferredAuthentications=publickey");
+  }
   const target = String(p.user || "") + "@" + String(p.host || "");
   const head = (p.authMethod === "password" && p.password) ? ["sshpass", "-p", String(p.password)] : [];
   const argv = head.concat(opts, [target]);
@@ -357,8 +430,23 @@ async function remoteListDir(runner, p, path) {
 
 async function remoteReadFile(runner, p, path) {
   if (!path) return { ok: false, error: "path 为必填项" };
-  const r = await runner(p, "base64 -w0 " + shellQuotePath(path), undefined, MAX_BYTES);
-  if (!r.ok) return r;
+  // 先 stat 拿大小：超过 MAX_BYTES 的大文件只读前 4MB（head -c 截断），
+  // 避免把持久会话的 stdout 缓冲撑爆（会话层另有 8MB 硬上限兜底）。
+  // 读路径走 2>&1 合并协议（热路径，省掉一次子 shell 与 stderr 重定向）。
+  const st = await runner(p, "stat -c%s " + shellQuotePath(path));
+  let size = null;
+  if (st.ok) {
+    const n = parseInt(String(st.stdout || "").trim(), 10);
+    if (!isNaN(n)) size = n;
+  }
+  let cmd = "base64 -w0 " + shellQuotePath(path);
+  let truncated = false;
+  if (size !== null && size > MAX_BYTES) {
+    cmd = "head -c " + MAX_BYTES + " " + shellQuotePath(path) + " | base64 -w0";
+    truncated = true;
+  }
+  const r = await runner(p, cmd, undefined, MAX_BYTES);
+  if (!r.ok) return { ok: false, error: String(r.error || r.stderr || "").trim() || "读取失败" };
   let text = "";
   let binary = false;
   try {
@@ -369,13 +457,16 @@ async function remoteReadFile(runner, p, path) {
   } catch (e) {
     return { ok: false, error: "解码失败: " + String(e) };
   }
-  return { ok: true, path: path, content: text, binary: binary, truncated: r.truncated };
+  return { ok: true, path: path, content: text, binary: binary, truncated: truncated || r.truncated };
 }
 
 async function remoteWriteFile(runner, p, path, content) {
   if (!path) return { ok: false, error: "path 为必填项" };
   const c = content !== undefined ? String(content) : "";
-  return await runner(p, "cat > " + shellQuotePath(path), c, MAX_BYTES);
+  if (c.length > MAX_BYTES) {
+    return { ok: false, exitCode: -1, stdout: "", stderr: "", error: "写入内容超过 " + MAX_BYTES + " 字节上限", truncated: false };
+  }
+  return await runner(p, "cat > " + shellQuotePath(path), c, MAX_BYTES, true);
 }
 
 /**
@@ -388,7 +479,7 @@ async function remoteGrep(runner, p, pattern, path, opts) {
   const target = path || p.remoteRoot || "~";
   const parts = ["grep", "-rnIE"];
   if (opts.ignoreCase) parts.push("-i");
-  if (opts.include) parts.push("--include=" + String(opts.include));
+  if (opts.include) parts.push("--include=" + shellQuote(String(opts.include)));
   parts.push("--", shellQuote(pattern), shellQuotePath(target));
   const cmd = parts.join(" ");
   const r = await runner(p, cmd, undefined, MAX_BYTES);
@@ -653,7 +744,8 @@ function apply(ctx, config) {
   const sessions = new Map(); // profileKey -> CommandSession
   const SESSION_IDLE_MS = 10 * 60 * 1000;
   function profileKey(p) {
-    return String(p.id) + "|" + String(p.host) + ":" + String(p.port || 22) + "|" + String(p.user || "");
+    // 认证信息变化时应重建会话：修改 keyPath/authMethod 后旧连接不能继续复用。
+    return String(p.id) + "|" + String(p.host) + ":" + String(p.port || 22) + "|" + String(p.user || "") + "|" + String(p.authMethod || "key") + "|" + String(p.keyPath || "");
   }
   function getSession(p) {
     const key = profileKey(p);
@@ -675,8 +767,9 @@ function apply(ctx, config) {
     return t.trim().slice(0, 500);
   }
 
-  /** 池化执行：复用持久会话；连接层失败（exit 255）或会话异常时清理会话并经一次性连接重试。 */
-  async function runPooled(p, cmd, stdinData, maxBytes) {
+  /** 池化执行：复用持久会话；连接层失败（exit 255）或会话异常时清理会话并经一次性连接重试。
+   *  split=true 时 stderr 与 stdout 分离返回（命令走双哨兵协议）。 */
+  async function runPooled(p, cmd, stdinData, maxBytes, split) {
     const dropSession = () => {
       const key = profileKey(p);
       const old = sessions.get(key);
@@ -684,11 +777,16 @@ function apply(ctx, config) {
     };
     try {
       const s = getSession(p);
-      const r = await s.exec(cmd, stdinData);
-      if (r.exitCode === 0) return { ok: true, exitCode: 0, stdout: r.stdout, stderr: "", error: "", truncated: false };
+      const r = await s.exec(cmd, stdinData, split);
+      const stderr = split ? String(r.stderr || "") : "";
+      if (r.exitCode === 0) return { ok: true, exitCode: 0, stdout: r.stdout, stderr: stderr, error: "", truncated: false };
       // exit 255 = ssh 连接层失败（非远程命令失败）：会话作废，下次调用重建。
       if (r.exitCode === 255) dropSession();
-      return { ok: false, exitCode: r.exitCode, stdout: r.stdout, stderr: "", error: sshErrorHint(r.exitCode === 255 ? r.stdout : String(r.stdout).trim().slice(0, 500)), truncated: false };
+      const errSource = String(stderr || r.stdout || "");
+      const error = r.exitCode === 255
+        ? sshErrorHint(errSource)
+        : (errSource.trim().slice(0, 500) || ("ssh 退出码 " + r.exitCode));
+      return { ok: false, exitCode: r.exitCode, stdout: r.stdout, stderr: stderr, error: error, truncated: false };
     } catch (e) {
       // 会话挂了 —— 清理并回退到一次性连接（相当于自动重连一次）
       dropSession();
@@ -782,6 +880,18 @@ function apply(ctx, config) {
     return base.replace(/\/+$/, "") + "/" + String(path);
   }
 
+  /** 清理远程工作区的原生注册与本地镜像目录（删除工作区或级联删除 profile 时调用）。 */
+  async function cleanupWorkspace(ws) {
+    if (!ws || !ws.mirrorPath) return;
+    if (workspaceRegistry) {
+      try {
+        const entity = await workspaceRegistry.resolveByPath(ws.mirrorPath);
+        if (entity) await workspaceRegistry.delete(entity.id);
+      } catch (e) {}
+    }
+    try { await rm(ws.mirrorPath, { recursive: true, force: true }); } catch (e) {}
+  }
+
   const api = {
     listProfiles: async () => ({ ok: true, profiles: settingsFace.read().profiles }),
     /** 读取本机 ~/.ssh/config 发现的主机（借鉴 Yan-Zero dsh-remote-ssh）。 */
@@ -816,9 +926,12 @@ function apply(ctx, config) {
     deleteProfile: async (args) => {
       const id = args && args.id;
       const profiles = settingsFace.read().profiles.filter((p) => p.id !== id);
+      const orphaned = settingsFace.read().workspaces.filter((w) => w.profileId === id);
       const workspaces = settingsFace.read().workspaces.filter((w) => w.profileId !== id);
       await settingsFace.updateProfiles(profiles);
       await settingsFace.updateWorkspaces(workspaces);
+      // 级联清理：相关远程工作区的原生注册与本地镜像目录一并删除，不留孤儿。
+      for (const ws of orphaned) await cleanupWorkspace(ws);
       return { ok: true, profiles: profiles, workspaces: workspaces };
     },
     testConnection: async (args) => {
@@ -891,15 +1004,7 @@ function apply(ctx, config) {
       const ws = all.find((w) => w.id === id);
       const workspaces = all.filter((w) => w.id !== id);
       await settingsFace.updateWorkspaces(workspaces);
-      if (ws && ws.mirrorPath) {
-        if (workspaceRegistry) {
-          try {
-            const entity = await workspaceRegistry.resolveByPath(ws.mirrorPath);
-            if (entity) await workspaceRegistry.delete(entity.id);
-          } catch (e) {}
-        }
-        try { await rm(ws.mirrorPath, { recursive: true, force: true }); } catch (e) {}
-      }
+      await cleanupWorkspace(ws);
       return { ok: true, workspaces: workspaces };
     },
     updateWorkspace: async (args) => {
@@ -917,7 +1022,8 @@ function apply(ctx, config) {
       const p = resolveProfile(args);
       if (!p) return { ok: false, error: "需要 profileId 或 host+user" };
       if (!args || !args.command) return { ok: false, error: "command 为必填项" };
-      return await runRemote(subprocess, p, args.command, args.stdin, undefined);
+      // 走持久会话池（stderr 分离）：首调用建立连接后，后续调用毫秒级返回。
+      return await runPooled(p, args.command, args.stdin, undefined, true);
     },
     listDir: async (args) => {
       const p = resolveProfile(args);
@@ -1113,7 +1219,10 @@ function apply(ctx, config) {
       if (!args.command) return normExec({ ok: false, error: "command 为必填项" });
       let cmd = String(args.command);
       if (tc.remotePath) cmd = "cd " + shellQuotePath(tc.remotePath) + " 2>/dev/null; " + cmd;
-      return normExec(await runRemote(subprocess, tc.profile, cmd, args.stdin, undefined));
+      // 走持久会话池（stderr 分离，双哨兵协议）：首次调用完成建连后，
+      // 后续调用不再重复 TCP 握手 + 认证，单次耗时从秒级降到毫秒级；
+      // 会话异常时 runPooled 自动重建并降级一次性连接。
+      return normExec(await runPooled(tc.profile, cmd, args.stdin, undefined, true));
     }
   });
 
@@ -1480,7 +1589,9 @@ function apply(ctx, config) {
     if (rel.toLowerCase().startsWith(mc.toLowerCase())) {
       rel = rel.slice(mc.length);
     } else {
-      // 可能是相对于 cwd 的路径
+      // 不在镜像目录下：剥掉可能的前导斜杠与盘符，按相对路径处理（此前会静默拼出错误路径）。
+      rel = rel.replace(/^[A-Za-z]:/, "").replace(/^\/+/, "");
+      try { ctx.logger?.debug("[dsh-remote-ssh] localToRemote: path outside mirror, treated as relative: " + localPath); } catch (e) {}
     }
     if (rel.startsWith("/")) rel = rel.slice(1);
     if (!rel) return remoteBase;
@@ -1634,7 +1745,7 @@ function apply(ctx, config) {
         remoteInfo = readRemoteInfoSync(payload.path);
         remoteBase = payload.path;
       }
-      console.log("[dsh-remote-ssh] intercept " + method + ": sessionId=" + sessionId + " cwd=" + sessionCwd + " path=" + (payload && payload.path) + " remote=" + (remoteInfo ? "YES" : "NO"));
+      try { ctx.logger?.debug("[dsh-remote-ssh] intercept " + method + ": sessionId=" + sessionId + " cwd=" + sessionCwd + " path=" + (payload && payload.path) + " remote=" + (remoteInfo ? "YES" : "NO")); } catch (e) {}
       let result;
       if (remoteInfo && remoteInfo.keyPath && remoteInfo.host && remoteInfo.user) {
         // ---- 远程工作区：走 SSH ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.1.6",
+  "version": "2.2.0",
   "description": "DSH web plugin: VSCode Remote-SSH-like remote development (SSH to supercomputers/servers, remote workspace, file explorer, integrated terminal), integrated with dsh-better-sidebar and DSH settings.",
   "keywords": [
     "dsh",
@@ -40,6 +40,7 @@
     },
     "client": {
       "inject": [
+        "@deepseek-ai/dsh-client-modules",
         "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-slots",
@@ -66,6 +67,7 @@
     "lib/client.js",
     "cordis.patch.yml",
     "README.md",
+    "README_EN.md",
     "LICENSE",
     "CHANGELOG.md"
   ],