@zhangfengshun/dsh-remote-ssh 2.1.5 → 2.1.7

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [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

@@ -176,6 +176,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 +191,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 +206,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);
@@ -283,7 +292,7 @@ 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));
   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]);
@@ -388,7 +397,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 +662,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);
@@ -661,18 +671,40 @@ function apply(ctx, config) {
     if (!s) { s = new CommandSession(subprocess, p); sessions.set(key, s); }
     return s;
   }
-  /** 池化执行：复用持久会话，失败时回退到一次性 runRemote。 */
+  /** 把 SSH 常见失败翻译成带修复建议的中文提示。 */
+  function sshErrorHint(text) {
+    const t = String(text || "");
+    if (/remote port forwarding failed for listen port (\d+)/i.test(t)) {
+      const m = t.match(/remote port forwarding failed for listen port (\d+)/i);
+      return "SSH 端口转发失败（本地端口 " + m[1] + " 已被占用）。这通常由 ~/.ssh/config 里的 RemoteForward 造成：远端该端口被上次会话占用时，ExitOnForwardFailure yes 会让 ssh 直接退出。本插件已对该连接加 ClearAllForwardings，若仍出现请检查 ssh config。原始信息: " + t.trim().slice(0, 300);
+    }
+    if (/permission denied \(publickey/i.test(t)) return "公钥认证失败：请检查 keyPath 私钥路径是否正确、远端 ~/.ssh/authorized_keys 是否包含对应公钥。原始信息: " + t.trim().slice(0, 300);
+    if (/connection refused/i.test(t)) return "连接被拒绝：请确认远端 sshd 已启动且端口正确。原始信息: " + t.trim().slice(0, 300);
+    if (/connection timed out|timed out/i.test(t)) return "连接超时：请确认网络可达、端口开放，或检查 ProxyJump 配置。原始信息: " + t.trim().slice(0, 300);
+    if (/could not resolve hostname/i.test(t)) return "无法解析主机名：请检查连接配置中的 host 拼写。原始信息: " + t.trim().slice(0, 300);
+    return t.trim().slice(0, 500);
+  }
+
+  /** 池化执行：复用持久会话；连接层失败（exit 255）或会话异常时清理会话并经一次性连接重试。 */
   async function runPooled(p, cmd, stdinData, maxBytes) {
+    const dropSession = () => {
+      const key = profileKey(p);
+      const old = sessions.get(key);
+      if (old) { old.close(); sessions.delete(key); }
+    };
     try {
       const s = getSession(p);
       const r = await s.exec(cmd, stdinData);
-      return { ok: r.exitCode === 0, exitCode: r.exitCode, stdout: r.stdout, stderr: "", error: r.exitCode !== 0 ? String(r.stdout).trim().slice(0, 500) : "", truncated: false };
+      if (r.exitCode === 0) return { ok: true, exitCode: 0, stdout: r.stdout, 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 };
     } catch (e) {
-      // 会话挂了 —— 清理并回退到一次性连接
-      const key = profileKey(p);
-      const old = sessions.get(key);
-      if (old) { old.close(); sessions.delete(key); }
-      return runRemote(subprocess, p, cmd, stdinData, maxBytes);
+      // 会话挂了 —— 清理并回退到一次性连接（相当于自动重连一次）
+      dropSession();
+      const r2 = await runRemote(subprocess, p, cmd, stdinData, maxBytes);
+      if (!r2.ok && r2.exitCode === 255) r2.error = sshErrorHint(r2.stdout || r2.stderr || r2.error);
+      return r2;
     }
   }
   // 定期清理空闲会话
@@ -760,6 +792,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）。 */
@@ -794,9 +838,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) => {
@@ -869,15 +916,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) => {
@@ -1458,7 +1497,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;
@@ -1612,7 +1653,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 ----
@@ -1692,6 +1733,286 @@ function apply(ctx, config) {
     return null;
   }
 
+  // ---- P0: 远程工作区的 Git 面板重定向（git.* 走远端，本地照旧本机 git）----
+  const GIT_METHODS = ["status", "diff", "log", "branch", "commit-diff", "show", "stage", "unstage", "commit", "checkout", "discard", "revert", "cherry-pick"];
+
+  /** 本机 git 执行（better-sidebar 原行为）：失败抛 {code:'git-error',message}。 */
+  async function runGitLocal(cwd, args) {
+    let handle;
+    try {
+      handle = subprocess.spawn({
+        argv: ["git", "-C", cwd, "--no-pager", "-c", "color.ui=false", ...args],
+        cwd: process.cwd(),
+        stdio: {
+          stdin: "ignore",
+          stdout: { maxBytes: 8 * 1024 * 1024, spill: { maxBytes: 8 * 1024 * 1024 } },
+          stderr: { maxBytes: 512 * 1024, spill: { maxBytes: 512 * 1024 } }
+        },
+        graceMs: 30000
+      });
+    } catch (e) {
+      throw { code: "git-error", message: "cannot run git: " + String(e && e.message ? e.message : e) };
+    }
+    const outcome = await handle.done.catch((e) => { throw { code: "git-error", message: String(e && e.message ? e.message : e) }; });
+    const so = (handle.collected && handle.collected.stdout) ? handle.collected.stdout.readFrom(0) : { text: "", nextOffset: 0, lossy: false };
+    const se = (handle.collected && handle.collected.stderr) ? handle.collected.stderr.readFrom(0) : { text: "", nextOffset: 0, lossy: false };
+    if (outcome.exitCode !== 0) throw { code: "git-error", message: String(se.text || "").trim() || ("git exited with " + outcome.exitCode) };
+    return so.text;
+  }
+
+  /** 远端 git 执行（远程工作区）：在 remoteDir 里跑同一 git 语义。 */
+  async function runGitRemote(profile, remoteDir, args) {
+    const quoted = args.map((a) => shellQuote(a)).join(" ");
+    const r = await runPooled(profile, "git -C " + shellQuotePath(remoteDir) + " --no-pager -c color.ui=false " + quoted, undefined, 8 * 1024 * 1024);
+    if (!r.ok) throw { code: "git-error", message: String(r.stdout || r.error || "").trim() || "remote git exited with " + r.exitCode };
+    return r.stdout;
+  }
+
+  function parsePorcelainZ(output) {
+    const tokens = String(output).split("\0");
+    const entries = [];
+    let index = 0;
+    while (index < tokens.length) {
+      const token = tokens[index];
+      index += 1;
+      if (token === "") continue;
+      const xy = token.slice(0, 2);
+      const rest = token.slice(3);
+      entries.push({ path: rest, xy: xy });
+      if ((xy[0] === "R" || xy[0] === "C") && tokens[index] !== undefined && tokens[index] !== "") index += 1;
+    }
+    return entries;
+  }
+
+  function parseLogLines(output) {
+    const rows = [];
+    for (const line of String(output).split("\n")) {
+      if (line === "") continue;
+      const [hash, subject, author, date, hashFull, refs] = line.split("\x1f");
+      if (hash === undefined || subject === undefined) continue;
+      rows.push({ hash, subject, author: author ?? "", date: date ?? "", hashFull: hashFull ?? hash, refs: refs ?? "" });
+    }
+    return rows;
+  }
+
+  /** git.status 的完整实现（isRepo 检测 + 分支 + porcelain 解析），本地/远端共用。 */
+  async function gitStatusImpl(run, dir) {
+    let inside = "false";
+    try { inside = String((await run(dir, ["rev-parse", "--is-inside-work-tree"])).trim()); } catch (e) { inside = "false"; }
+    if (inside !== "true") return { isRepo: false, entries: [] };
+    let branch = "HEAD";
+    try { branch = String((await run(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim()) || "HEAD"; } catch (e) {}
+    let raw = "";
+    try {
+      raw = await run(dir, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
+    } catch (e) {
+      return { isRepo: true, branch: branch, entries: [] };
+    }
+    return { isRepo: true, branch: branch, entries: parsePorcelainZ(raw) };
+  }
+
+  /** 解析一次 /sidebar/api/git.* 请求的上下文：远程工作区 → {profile, remoteDir}，否则 null。 */
+  function gitContextOf(payload) {
+    const sessionId = payload && payload.sessionId;
+    const clientCwd = payload && payload.cwd;
+    let cwd = clientCwd;
+    if ((!cwd || cwd === "") && sessionId) {
+      const sessions = ctx.get("sessions");
+      const session = sessions ? sessions.get(sessionId) : null;
+      cwd = session && session.header && session.header.cwd;
+    }
+    if (!cwd) return null;
+    const ws = matchRemoteWorkspace(cwd, cwd);
+    if (!ws) return null;
+    const remoteInfo = readRemoteInfoSync(ws.mirrorPath);
+    const profile = remoteInfo && getProfile(remoteInfo.profileId);
+    if (!remoteInfo || !profile) return null;
+    const remoteDir = localToRemote(cwd, ws.mirrorPath, remoteInfo.remotePath);
+    return { profile: profile, remoteDir: remoteDir, cwd: cwd };
+  }
+
+  async function interceptGitHandler(req, res, method) {
+    if (!isTrusted(req)) { writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } }); return; }
+    if (req.method !== "POST") { writeJson(res, 405, { ok: false, error: { code: "method-error", message: "method not allowed" } }); return; }
+    let payload;
+    try { payload = await readJsonBody(req); }
+    catch (e) { writeJson(res, 400, { ok: false, error: { code: "bad-request", message: String(e && e.message ? e.message : e) } }); return; }
+    try {
+      const remote = gitContextOf(payload);
+      // 本地会话没有 session/cwd 时无法判定工作目录 → 按本机 git 于 process.cwd() 处理。
+      const cwd = remote ? remote.remoteDir : (payload && payload.cwd) || process.cwd();
+      const run = remote
+        ? (dir, args) => runGitRemote(remote.profile, remote.remoteDir, args)
+        : (dir, args) => runGitLocal(cwd, args);
+      let value;
+      switch (method) {
+        case "status":
+          value = await gitStatusImpl(run, cwd);
+          break;
+        case "diff": {
+          const p = payload;
+          const path = p.path !== undefined ? String(p.path) : undefined;
+          const staged = p.staged === true;
+          const args = ["diff", "--no-ext-diff", "--no-color", "-U3"];
+          if (staged) args.push("--cached");
+          if (path !== undefined && path !== "") args.push("--", path);
+          value = { diff: await run(cwd, args) };
+          break;
+        }
+        case "log": {
+          const p = payload;
+          const count = typeof p.count === "number" && Number.isInteger(p.count) && p.count > 0 ? p.count : 30;
+          const skip = typeof p.skip === "number" && Number.isInteger(p.skip) && p.skip >= 0 ? p.skip : 0;
+          value = parseLogLines(await run(cwd, ["log", "-n", String(count), "--skip", String(skip), "--decorate=short", "--pretty=format:%h%x1f%s%x1f%an%x1f%ai%x1f%H%x1f%D"]));
+          break;
+        }
+        case "branch": {
+          let current = "HEAD";
+          try { current = String((await run(cwd, ["rev-parse", "--abbrev-ref", "HEAD"])).trim()) || "HEAD"; } catch (e) {}
+          const raw = await run(cwd, ["for-each-ref", "--format=%(refname:short)", "refs/heads"]);
+          const names = String(raw).split("\n").filter((l) => l !== "");
+          value = { current: current, names: names.includes(current) ? names : [current, ...names] };
+          break;
+        }
+        case "commit-diff": {
+          const hash = String(payload && payload.hash || "").trim();
+          if (!hash) throw { code: "bad-request", message: "hash is required" };
+          value = { diff: await run(cwd, ["show", "--no-ext-diff", "--no-color", "--format=", "-m", "--first-parent", hash]) };
+          break;
+        }
+        case "show": {
+          const p = payload;
+          const rev = String(p && p.rev || "").trim();
+          const path = String(p && p.path || "").trim();
+          if (!rev || !path) throw { code: "bad-request", message: "rev and path are required" };
+          let content = null;
+          try { content = await run(cwd, ["show", rev + ":" + path]); } catch (e) { content = null; }
+          value = { content: content };
+          break;
+        }
+        case "stage": {
+          const path = payload && payload.path !== undefined ? String(payload.path) : undefined;
+          await run(cwd, ["add", "-A", ...(path !== undefined && path !== "" ? ["--", path] : [])]);
+          value = { ok: true };
+          break;
+        }
+        case "unstage": {
+          const path = payload && payload.path !== undefined ? String(payload.path) : undefined;
+          await run(cwd, ["reset", "-q", ...(path !== undefined && path !== "" ? ["--", path] : [])]);
+          value = { ok: true };
+          break;
+        }
+        case "commit": {
+          const message = String(payload && payload.message || "").trim();
+          if (!message) throw { code: "bad-request", message: "message is required" };
+          await run(cwd, ["commit", "-m", message]);
+          value = { ok: true };
+          break;
+        }
+        case "checkout": {
+          const branch = String(payload && payload.branch || "").trim();
+          if (!branch) throw { code: "bad-request", message: "branch is required" };
+          await run(cwd, ["checkout", branch]);
+          value = { ok: true };
+          break;
+        }
+        case "discard": {
+          const path = String(payload && payload.path || "").trim();
+          if (!path) throw { code: "bad-request", message: "path is required" };
+          await run(cwd, ["checkout", "--", path]);
+          value = { ok: true };
+          break;
+        }
+        case "revert": {
+          const hash = String(payload && payload.hash || "").trim();
+          if (!hash) throw { code: "bad-request", message: "hash is required" };
+          await run(cwd, ["revert", "--no-edit", hash]);
+          value = { ok: true };
+          break;
+        }
+        case "cherry-pick": {
+          const hash = String(payload && payload.hash || "").trim();
+          if (!hash) throw { code: "bad-request", message: "hash is required" };
+          await run(cwd, ["cherry-pick", hash]);
+          value = { ok: true };
+          break;
+        }
+        default:
+          writeJson(res, 404, { ok: false, error: { code: "not-found", message: "unknown git method " + method } }); return;
+      }
+      if (value === undefined) value = { ok: true };
+      writeOk(res, value);
+    } catch (e) {
+      const code = (e && e.code) || "git-error";
+      const message = (e && e.message) || String(e);
+      writeJson(res, code === "bad-request" ? 400 : 500, { ok: false, error: { code: code, message: message } });
+    }
+  }
+
+  GIT_METHODS.forEach(function (m) {
+    ctx.effect(() => ctx.webServer.register({
+      kind: "exact",
+      path: "/sidebar/api/git." + m,
+      handler: function (req, res) { return interceptGitHandler(req, res, m); }
+    }), "dsh-remote-ssh: intercept /sidebar/api/git." + m);
+  });
+
+  /** 等待可写流 drain（带回退:已销毁则即时返回）。 */
+  function awaitOnce(emitter, event) {
+    return new Promise((resolve, reject) => {
+      emitter.once(event, () => resolve());
+      emitter.once("error", reject);
+    });
+  }
+
+  /** 流式写入：把请求体直接管道到远端 `cat > target`（二进制安全、恒定内存）。 */
+  async function streamRemoteUpload(profile, target, req, limit) {
+    let handle;
+    try {
+      handle = subprocess.spawn({
+        argv: sshArgv(profile, "cat > " + shellQuotePath(target), false),
+        cwd: process.cwd(),
+        stdio: {
+          stdin: "pipe",
+          stdout: { maxBytes: 64 * 1024, spill: { maxBytes: 64 * 1024 } },
+          stderr: { maxBytes: 64 * 1024, spill: { maxBytes: 64 * 1024 } }
+        },
+        graceMs: 10000
+      });
+    } catch (e) {
+      return { ok: false, code: "spawn-failed", message: "spawn 失败: " + String(e && e.message ? e.message : e), size: 0 };
+    }
+    let size = 0;
+    let aborted = false;
+    const onAbort = () => { aborted = true; try { handle.terminate(); } catch (e) {} };
+    try {
+      req.on("aborted", onAbort);
+      req.on("close", () => { if (!req.complete) onAbort(); });
+      for await (const chunk of req) {
+        if (aborted) break;
+        const b = Buffer.from(chunk);
+        size += b.length;
+        if (size > limit) { handle.terminate(); return { ok: false, code: "too-large", message: "upload exceeds the remote upload limit (" + limit + " bytes)", size: size }; }
+        if (handle.stdin.destroyed) return { ok: false, code: "pipe-closed", message: "ssh stdin closed during upload", size: size };
+        if (!handle.stdin.write(b)) await awaitOnce(handle.stdin, "drain");
+      }
+      if (aborted) return { ok: false, code: "aborted", message: "upload aborted", size: size };
+      handle.stdin.end();
+      const outcome = await handle.done;
+      const so = (handle.collected && handle.collected.stdout) ? handle.collected.stdout.readFrom(0) : { text: "", nextOffset: 0, lossy: false };
+      const se = (handle.collected && handle.collected.stderr) ? handle.collected.stderr.readFrom(0) : { text: "", nextOffset: 0, lossy: false };
+      if (outcome.exitCode !== 0) {
+        return { ok: false, code: "fs-error", message: String(se.text || "").trim() || ("ssh 退出码 " + outcome.exitCode), size: size };
+      }
+      return { ok: true, size: size, stdout: so.text, stderr: se.text };
+    } catch (e) {
+      try { handle.terminate(); } catch (e2) {}
+      return { ok: false, code: "fs-error", message: String(e && e.message ? e.message : e), size: size };
+    } finally {
+      req.removeListener("aborted", onAbort);
+    }
+  }
+
   async function handleRemoteUpload(req, res) {
     if (!isTrusted(req)) { writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } }); return; }
     if (req.method !== "POST") { writeJson(res, 405, { ok: false, error: { code: "method-error", message: "method not allowed" } }); return; }
@@ -1712,25 +2033,19 @@ function apply(ctx, config) {
       const remoteDir = localToRemote(dir, ws.mirrorPath, remoteInfo.remotePath);
       const target = remoteDir.replace(/\/+$/, "") + (rel ? "/" + rel : "");
       const parent = target.slice(0, Math.max(target.lastIndexOf("/"), 0));
-      // 读取原始字节流（File/Blob 直传，二进制安全）
-      const chunks = [];
-      let size = 0;
-      for await (const chunk of req) {
-        const b = Buffer.from(chunk);
-        size += b.length;
-        if (size > REMOTE_UPLOAD_LIMIT) { writeJson(res, 413, { ok: false, error: { code: "too-large", message: "upload exceeds the remote upload limit (" + REMOTE_UPLOAD_LIMIT + " bytes)" } }); return; }
-        chunks.push(b);
-      }
-      const payloadBase64 = Buffer.concat(chunks).toString("base64");
       // 远端建父目录
       if (parent && parent !== remoteDir.replace(/\/+$/, "")) {
         const mk = await runPooled(profile, "mkdir -p " + shellQuotePath(parent), undefined, 65536);
         if (!mk.ok) { writeJson(res, 500, { ok: false, error: { code: "fs-error", message: String(mk.error || mk.stdout || "mkdir failed").trim() } }); return; }
       }
-      // 二进制安全落地：base64 -d 还原后写入目标文件
-      const w = await runPooled(profile, "base64 -d > " + shellQuotePath(target), payloadBase64, REMOTE_UPLOAD_LIMIT);
-      if (!w.ok) { writeJson(res, 500, { ok: false, error: { code: "fs-error", message: String(w.error || w.stdout || "remote write failed").trim() } }); return; }
-      writeOk(res, { path: dir.replace(/\\/g, "/").replace(/\/+$/, "") + "/" + rel, size: size });
+      // 流式上传（cat > target 直接吃 stdin，无 base64、无内存膨胀）
+      const r = await streamRemoteUpload(profile, target, req, REMOTE_UPLOAD_LIMIT);
+      if (!r.ok) {
+        const status = r.code === "too-large" ? 413 : (r.code === "bad-request" ? 400 : 500);
+        writeJson(res, status, { ok: false, error: { code: r.code, message: r.message } });
+        return;
+      }
+      writeOk(res, { path: dir.replace(/\\/g, "/").replace(/\/+$/, "") + "/" + rel, size: r.size });
     } catch (e) {
       writeJson(res, 400, { ok: false, error: { code: "fs-error", message: String(e && e.message ? e.message : e) } });
     }
@@ -1742,6 +2057,105 @@ function apply(ctx, config) {
     handler: function (req, res) { return handleRemoteUpload(req, res); }
   }), "dsh-remote-ssh: /remote-ssh/upload route");
 
+  // ---- P0: 远程文件下载 / 媒体预览（拦截 better-sidebar 的 /sidebar/file）----
+  // better-sidebar 注册的是 prefix 路由，这里注册同路径 exact 路由优先匹配。
+  const MEDIA_TYPES = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
+    ".webp": "image/webp", ".svg": "image/svg+xml", ".bmp": "image/bmp", ".ico": "image/x-icon",
+    ".avif": "image/avif", ".pdf": "application/pdf", ".html": "text/html; charset=utf-8", ".htm": "text/html; charset=utf-8"
+  };
+  const REMOTE_DOWNLOAD_LIMIT = 64 * 1024 * 1024; // 远端内容走 base64 传输，设一个合理上限
+
+  function mediaTypeForPath(path) {
+    const ext = String(path || "").toLowerCase();
+    const dot = ext.lastIndexOf(".");
+    const key = dot >= 0 ? ext.slice(dot) : "";
+    return MEDIA_TYPES[key] || "application/octet-stream";
+  }
+
+  /** 二进制安全地取回远端文件字节（base64 走 stdout，长度上限 maxBytes）。 */
+  async function remoteFetchBytes(profile, remotePath, maxBytes) {
+    // 先拿大小（stat），超限直接拒绝；base64 会膨胀 4/3，给 stdout 相应上限。
+    const st = await runPooled(profile, "stat -c%s " + shellQuotePath(remotePath), undefined, 65536);
+    if (!st.ok) return { ok: false, error: String(st.stdout || st.error || "stat failed").trim() };
+    const size = parseInt(String(st.stdout).trim(), 10);
+    if (isNaN(size)) return { ok: false, error: "cannot stat remote file size" };
+    if (size > maxBytes) return { ok: false, error: "file too large (" + size + " bytes; limit " + maxBytes + ")" };
+    const cap = Math.ceil(size * 1.5) + 4096;
+    const r = await runPooled(profile, "base64 -w0 " + shellQuotePath(remotePath), undefined, cap);
+    if (!r.ok) return { ok: false, error: String(r.stdout || r.error || "read failed").trim().slice(0, 500) };
+    try {
+      const buf = Buffer.from(String(r.stdout).replace(/\s+/g, ""), "base64");
+      return { ok: true, buffer: buf };
+    } catch (e) {
+      return { ok: false, error: "decode failed: " + String(e) };
+    }
+  }
+
+  async function handleSidebarFile(req, res) {
+    if (!isTrusted(req)) { res.writeHead(403); res.end("forbidden"); return; }
+    if (req.method !== "GET") { res.writeHead(405); res.end(); return; }
+    try {
+      const url = new URL(req.url || "/", "http://dsh.internal");
+      const sessionId = url.searchParams.get("sessionId");
+      const rawPath = url.searchParams.get("path");
+      const cwdParam = url.searchParams.get("cwd") || "";
+      const download = url.searchParams.get("download") === "1";
+      if (!sessionId || !rawPath) { res.writeHead(400); res.end("sessionId and path are required"); return; }
+      const ws = matchRemoteWorkspace(rawPath, cwdParam);
+      if (ws) {
+        // ---- 远程工作区：SSH 拉取远程文件 ----
+        const remoteInfo = readRemoteInfoSync(ws.mirrorPath);
+        const profile = remoteInfo && getProfile(remoteInfo.profileId);
+        if (!remoteInfo || !profile) {
+          writeJson(res, 500, { ok: false, error: { code: "internal", message: "remote workspace profile not found" } });
+          return;
+        }
+        const remotePath = localToRemote(rawPath, ws.mirrorPath, remoteInfo.remotePath);
+        const r = await remoteFetchBytes(profile, remotePath, REMOTE_DOWNLOAD_LIMIT);
+        if (!r.ok) {
+          writeJson(res, 400, { ok: false, error: { code: "fs-error", message: r.error || "read failed" } });
+          return;
+        }
+        const body = r.buffer;
+        const headers = {
+          "content-type": mediaTypeForPath(remotePath),
+          "cache-control": "no-cache"
+        };
+        if (download) headers["content-disposition"] = `attachment; filename*=UTF-8''${encodeURIComponent(String(remotePath).split("/").pop() || "download")}`;
+        res.writeHead(200, headers);
+        res.end(body);
+        return;
+      }
+      // ---- 本地工作区：沿用 better-sidebar 原行为（读本地文件）----
+      let cwd = cwdParam;
+      if (!cwd && sessionId) {
+        const sessions = ctx.get("sessions");
+        const session = sessions ? sessions.get(sessionId) : null;
+        cwd = session && session.header && session.header.cwd;
+      }
+      const info = await stat(rawPath).catch((e) => { throw new Error("cannot read: " + String(e && e.message ? e.message : e)); });
+      if (!info.isFile() || info.size > 20 * 1024 * 1024) { res.writeHead(400); res.end("not a file or too large"); return; }
+      const body = await readFile(rawPath);
+      const headers = {
+        "content-type": mediaTypeForPath(rawPath),
+        "cache-control": "no-cache"
+      };
+      if (download) headers["content-disposition"] = `attachment; filename*=UTF-8''${encodeURIComponent(rawPath.split(/[\\/]/).pop() || "download")}`;
+      res.writeHead(200, headers);
+      res.end(body);
+    } catch (e) {
+      res.writeHead(400);
+      res.end(String(e && e.message ? e.message : e));
+    }
+  }
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: "exact",
+    path: "/sidebar/file",
+    handler: function (req, res) { return handleSidebarFile(req, res); }
+  }), "dsh-remote-ssh: intercept /sidebar/file");
+
   // ---- 清理 ----
   ctx.effect(() => () => {
     clearInterval(idleTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "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"
   ],