@zhangfengshun/dsh-remote-ssh 2.2.1 → 2.3.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.3.1] — 修复 2.3.0 上线后的界面卡顿（GC 压力 + 客户端全页扫描）
+### 修复
+- **读缓存字节预算（review m1）**：单条结果 >1MiB 不再缓存（结果照常返回），缓存总量上限 32MB 超限逐出最旧条目——消除大文件驻留字符串造成的 GC 压力（最坏 ~270MB → ≤32MB）。
+- **设置导航齿轮观察器改为增量扫描**：此前任何 DOM 变动都会触发全文档 `querySelectorAll("button")` 扫描（流式聊天期间持续打断主线程）；现改为只扫描新增子树、节流 500ms、后台页签零开销，稳态成本≈0。
+- **exec 失败不再 bump epoch（review m3）**：失败的命令通常无副作用，不再无谓打断整代缓存（部分副作用由 ≤5s TTL 兜底）。
+- **git 只读命令不再整代失效（review m4）**：仅 add/reset/commit/checkout/revert/cherry-pick 变更类子命令 bump，status/diff/log/branch/show 不再打断缓存。
+
+## [2.3.0] — 远程文件打开提速：单往返合并读 + 结果缓存（实测 ≈1.3×~5×）
+### 性能
+- **fs.read 单往返合并读**：size/mtime 与文件内容合并为一条池化命令（`__DSH_ST__` 帧，`_` 不在 base64 字母表故标记天然抗噪），去掉每文件一次的 stat 往返。真实 HPC 实测（100KB 文件，各 10 次 p50）：raw 直传 396.6→301.8ms、base64 443.8→337.9ms，约 **1.31×**；1MB 大文件同步受益。>4MB 仍 `head -c 4MiB` 截断，二进制探测与解码语义不变。
+- **raw 文本快路径**：文本扩展名白名单（.py/.js/.md/… 等）免 base64 直传（传输段再省 ≈24-27%）；字节长度 + U+FFFD 双校验，不符自动回退 base64 重读——结果与旧实现逐字节一致，仅多 1 RTT。
+- **主机侧结果缓存**：读结果与目录列举各 LRU（32/64 条）+ TTL 5s。TTL 内重复打开/切回页签 **0 RTT**（实测 ≈0.02ms）；过期后 1 次轻量 mtime+size 复验，未变免重传（实测 84.9ms，约 **5×**）；目录列举 TTL 内 0ms。写/删/移/建目录/上传/推送/远端 exec/git 自动失效，并引入每 profile 缓存代（epoch）兜底「同秒同 size 写」与 `~/x` vs `/home/u/x` 路径字符串空间差。
+- **目录列举 `cd` 包进子 shell**：修复列举后 `cd` 残留污染共享会话 cwd 的既有问题（旧实现会使会话内后续相对路径命令落空）。
+### 修复
+- **写路径字节精确**：`remote_ssh_write` / 文件页签保存改走 `base64 -d` 管道写入，修复旧 `cat > file` heredoc 帧每次保存尾随多 1 字节的问题（实测 3/3/4B，旧实现 4/4/5B），且对 NUL/二进制内容安全。
+### 已知限制
+- 集成终端（`ssh -tt`）与远端外部进程改动的文件，插件缓存最多 **5s** 陈旧；外部进程「同秒内同 size 写」且此后不再变化时，mtime 复验无法察觉（极窄窗口；插件自身写/exec/git 路径经失效与 epoch 兜底，不受此限）。
+- `/sidebar/file` 下载池化路径有效上限 ≈**6.29MB**（会话 8MB 输出熔断 ÷ base64 4/3 膨胀）；更大文件自动退回一次性连接下载（可成功，但多付一次废传输与重连），2.4.0 候选修复。
+- 二进制内容伪装文本扩展名时，raw 校验拒绝后自动回退 base64 重读（多 1 RTT，结果正确）。
+
 ## [2.2.1] — 去掉设置导航「远程连接」左侧的齿轮图标
 ### 修复
 - DSH 壳层对未知 `settings.section` 渲染默认齿轮图标，且导航类名是构建期哈希（每版都会变），旧版硬编码的 CSS 选择器（`VOzbGW_*`）已随 DSH 更新失效。改为按栏目标题文本定位设置导航按钮并隐藏其图标 svg（MutationObserver + 语言切换自动重跑），跨 DSH 构建版本稳定。

package/README.md

@@ -17,7 +17,7 @@
 ## 安装
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.7
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
 ```
 
 > 安装后需**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
@@ -54,6 +54,16 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.7
 
 Shell wrapper（`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`）检测工作区 `.remote-ssh.json`，自动 `ssh -tt` 连接远程，使内置「终端」页签透明接入。
 
+## 缓存与一致性
+
+远程读取与目录列举结果在主机侧缓存（LRU 32/64 条，TTL 5 秒）：TTL 内重复打开或切回页签 0 网络往返；过期后先做一次轻量 mtime+size 复验，未变化则免重传。写、删除、移动、建目录、上传、推送（push）、远端 exec 与 git 面板操作会自动失效相关缓存。
+
+已知限制：
+
+- 集成终端（`ssh -tt`）与远端其它进程改动的文件依赖 TTL + 复验兜底，最多 **5 秒**陈旧；
+- `/sidebar/file` 下载池化路径有效上限约 **6.29MB**，更大文件自动退回一次性连接下载（可成功，多一次重连开销）；
+- 二进制内容伪装成文本扩展名时会多一次 base64 回退往返（结果正确）。
+
 ## ❤️ 七夕快乐
 
 本项目是送给 **zhangyi** 的七夕礼物。

package/README_EN.md

@@ -17,7 +17,7 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 ## Installation
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.1.7
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
 ```
 
 > **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
@@ -54,6 +54,16 @@ The plugin registers 4 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.writ
 
 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.
 
+## Caching & Consistency
+
+Remote reads and directory listings are cached host-side (LRU 32/64 entries, TTL 5s): re-opening or switching back to a tab within the TTL costs 0 network round-trips; after expiry a lightweight mtime+size revalidation runs first, and unchanged files are served without re-transfer. Write, delete, move, mkdir, upload, push (syncUp), remote exec and git-panel operations automatically invalidate the affected cache entries.
+
+Known limitations:
+
+- Files changed from the integrated terminal (`ssh -tt`) or by other remote processes rely on TTL + revalidation and may be stale for up to **5 seconds**;
+- The pooled `/sidebar/file` download path has an effective limit of ≈**6.29MB**; larger files automatically fall back to a one-shot connection download (succeeds, with one extra reconnect);
+- Binary content masquerading with a text extension costs one extra base64 fallback round-trip (results are still correct).
+
 ## ❤️ Happy Qixi
 
 This project is a Qixi Festival gift for **zhangyi**.

package/lib/client.js

@@ -1115,32 +1115,58 @@ window.__ModuleLoader__.load({
       // 不可靠。这里改为按条目文本（settings.nav）定位设置导航按钮，隐藏其 svg 图标；
       // 设置面板按需挂载、语言会切换，用 MutationObserver + 语言订阅自动重跑。
       if (slots) {
+        function checkCell(btn) {
+          var label = i18n.t("settings.nav");
+          var text = (btn.textContent || "").trim();
+          if (text !== label.trim() || text === "") return false;
+          var icon = btn.querySelector("svg");
+          if (icon) { icon.style.display = "none"; return true; }
+          return false;
+        }
+        function checkCellIn(root) {
+          try {
+            if (root.tagName && String(root.tagName).toLowerCase() === "button") checkCell(root);
+            var cells = root.querySelectorAll("button");
+            for (var i = 0; i < cells.length; i++) checkCell(cells[i]);
+          } catch (e) {}
+        }
         function hideRemoteGearIcon() {
           try {
-            var label = i18n.t("settings.nav");
             var buttons = document.querySelectorAll("button");
-            for (var i = 0; i < buttons.length; i++) {
-              var btn = buttons[i];
-              var text = (btn.textContent || "").trim();
-              if (text === label.trim() && text !== "") {
-                var icon = btn.querySelector("svg");
-                if (icon) { icon.style.display = "none"; return true; }
-              }
-            }
+            for (var i = 0; i < buttons.length; i++) checkCell(buttons[i]);
           } catch (e) {}
-          return false;
         }
         ctx.effect(function () {
           if (typeof document === "undefined") return;
           hideRemoteGearIcon();
           var timer = null;
-          var schedule = function () {
+          var pendingRoots = null;
+          var schedule = function (root) {
+            if (root && root.nodeType === 1) (pendingRoots || (pendingRoots = [])).push(root);
             if (timer) return;
-            timer = setTimeout(function () { timer = null; hideRemoteGearIcon(); }, 120);
+            timer = setTimeout(function () {
+              timer = null;
+              var roots = pendingRoots;
+              pendingRoots = null;
+              if (document.hidden) return; // 后台页签零开销
+              if (roots && roots.length) {
+                // 只扫新增子树：流式聊天期间不做全文档扫描（稳态成本≈0）
+                for (var i = 0; i < roots.length; i++) {
+                  if (roots[i].isConnected) checkCellIn(roots[i]);
+                }
+              } else {
+                hideRemoteGearIcon(); // 语言切换等无根场景全量扫一次
+              }
+            }, 500);
           };
-          var mo = new MutationObserver(schedule);
+          var mo = new MutationObserver(function (muts) {
+            for (var i = 0; i < muts.length; i++) {
+              var added = muts[i].addedNodes;
+              for (var j = 0; j < added.length; j++) schedule(added[j]);
+            }
+          });
           mo.observe(document.body, { childList: true, subtree: true });
-          var off = i18n.subscribe(schedule);
+          var off = i18n.subscribe(function () { schedule(null); });
           return function () {
             mo.disconnect();
             if (off) off();

package/lib/index.js

@@ -408,7 +408,17 @@ async function runRemote(subprocess, p, remoteCmd, stdinData, maxBytes) {
 
 async function remoteListDir(runner, p, path) {
   const target = path || p.remoteRoot || "~";
-  const script = "cd " + shellQuotePath(target) + " 2>/dev/null || { echo '__DSH_ERR__ cannot cd'; exit 1; }; find . -maxdepth 1 -mindepth 1 -printf '%Y\\t%f\\t%s\\n' 2>/dev/null | sort";
+  const pk = profileKey(p);
+  const key = pk + "|" + String(target);
+  const epoch = cacheEpoch(pk);
+  const hit = lruGet(treeCache, key);
+  if (hit && hit.epoch === epoch && Date.now() - hit.at <= TREE_CACHE_TTL_MS) {
+    return { ok: true, path: target, entries: hit.entries.slice() }; // TTL 内 0 RTT
+  }
+  if (hit && hit.epoch !== epoch) treeCache.delete(key);
+  // cd 包进子 shell：列举完成后不污染共享会话 cwd（findings §4.4 —— 旧实现 cd 持久生效，
+  // 会话内后续相对路径命令全部落空）。exit 只退出子 shell，哨兵协议不受影响。
+  const script = "( cd " + shellQuotePath(target) + " 2>/dev/null || { echo '__DSH_ERR__ cannot cd'; exit 1; }; find . -maxdepth 1 -mindepth 1 -printf '%Y\\t%f\\t%s\\n' 2>/dev/null | sort )";
   const r = await runner(p, script, undefined, MAX_BYTES);
   if (!r.ok) return { ok: false, error: (r.error || r.stderr || "").trim() || "读取目录失败" };
   const entries = [];
@@ -425,39 +435,322 @@ async function remoteListDir(runner, p, path) {
   entries.sort(function (a, b) {
     return a.type === b.type ? (a.name < b.name ? -1 : a.name > b.name ? 1 : 0) : (a.type === "directory" ? -1 : 1);
   });
+  lruPut(treeCache, key, { entries: entries, epoch: epoch, at: Date.now() }, TREE_CACHE_MAX);
   return { ok: true, path: target, entries: entries };
 }
 
+// ---------------------------------------------------------------------------
+// 远程读取提速（t2）：单往返合并读 + raw 文本快路径 + mtime/size LRU 结果缓存
+//
+// 帧协议（沿用既有非 split 快速路径 "{ cmd ; } 2>&1" + 退出码哨兵；路径一律先
+// f=<shellQuotePath> 再以 "$f" 引用，无任何 cwd 依赖）：
+//   stdout 首行固定为  __DSH_ST__<size>:<mtime>   （stat 成功，均为十进制）
+//   或               __DSH_ST__ERR:<单行摘要>     （stat 失败：摘要压成单行 ≤200 字符，
+//                                                 整条命令以内建 false 收尾保证非零
+//                                                 退出码 —— 绝不空内容假成功/挂起；
+//                                                 不用 exit，因非 split 帧无子 shell 隔离）
+//   载荷 = 首行 \n 之后：base64 模式 `base64 -w0`（size>4MB 先 `head -c 4MB` 截断），
+//         raw 模式为文件原始字节（仅限文本扩展名白名单）。
+//   `_` 不在 base64 字母表内 → base64 载荷不可能出现 `__DSH_ST__`，标记定位天然抗噪；
+//   协议层固定在哨兵前补一个 \n（exitMark），raw 解析按“恰好去掉末尾一个 \n”还原。
+// ---------------------------------------------------------------------------
+
+const DSH_ST_MARK = "__DSH_ST__";
+/** raw 快路径扩展名白名单（findings §3②）：只对按 UTF-8 文本处理的文件免 base64。
+ *  字节长度或 \uFFFD 校验失败时自动回退 base64 重读，不劣于现状。 */
+const RAW_TEXT_EXTS = new Set([
+  ".txt", ".md", ".markdown", ".rst", ".log", ".csv", ".tsv",
+  ".py", ".pyw", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".vue", ".svelte",
+  ".json", ".jsonc", ".json5", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", ".env",
+  ".sh", ".bash", ".zsh", ".fish", ".ps1", ".psm1", ".bat", ".cmd", ".sql",
+  ".c", ".h", ".cpp", ".hpp", ".cc", ".hh", ".cxx", ".hxx", ".f", ".for", ".f90", ".f95",
+  ".java", ".go", ".rs", ".rb", ".pl", ".pm", ".php", ".lua", ".r", ".jl", ".dart", ".kt",
+  ".html", ".htm", ".css", ".scss", ".sass", ".less", ".xml", ".svg", ".xsl", ".proto",
+  ".tex", ".bib", ".properties", ".gradle", ".cmake", ".mk", ".diff", ".patch", ".ipynb"
+]);
+/** 无扩展名 / 点开头的常读文本文件（按整名匹配，小写）。 */
+const RAW_TEXT_NAMES = new Set([
+  "makefile", "dockerfile", "license", "readme", "changelog", "authors", "contributors",
+  ".gitignore", ".gitattributes", ".gitmodules", ".gitconfig", ".gitkeep", ".editorconfig",
+  ".dockerignore", ".npmrc", ".nvmrc", ".bashrc", ".bash_profile", ".profile", ".vimrc", ".tmux.conf"
+]);
+/** 读结果 LRU：key = profileKey|path，TTL ≤5s；过期后 1 裸 RTT stat 复验 mtime+size。 */
+const READ_CACHE_MAX = 32;
+const READ_CACHE_TTL_MS = 5000;
+/** 目录列举 LRU：key = profileKey|dir，TTL 5s。 */
+const TREE_CACHE_MAX = 64;
+const TREE_CACHE_TTL_MS = 5000;
+/** 每个 profile 的缓存代（epoch）：插件侧任何变更（写/删/移/建目录/上传/syncUp/
+ *  远程 exec/git）都 +1，条目按填充时代号校验 —— 兜底 mtime 秒级粒度的“同秒同 size”
+ *  写、~/x 与 /home/u/x 路径字符串空间不一致、以及漏钩子场景（findings §4.3）。 */
+const cacheEpochs = new Map();
+const readCache = new Map();
+const treeCache = new Map();
+
+function profileKey(p) {
+  // 认证信息变化时应重建会话/缓存：修改 keyPath/authMethod 后旧身份不能继续复用。
+  return String(p.id) + "|" + String(p.host) + ":" + String(p.port || 22) + "|" + String(p.user || "") + "|" + String(p.authMethod || "key") + "|" + String(p.keyPath || "");
+}
+
+function cacheEpoch(pk) {
+  let e = cacheEpochs.get(pk);
+  if (!e) { e = 1; cacheEpochs.set(pk, e); }
+  return e;
+}
+
+/** 只递增 epoch 不删条目：远程 exec / git 这类“可能改了任意文件”的入口调用。 */
+function bumpCacheEpoch(p) {
+  const pk = profileKey(p);
+  cacheEpochs.set(pk, cacheEpoch(pk) + 1);
+}
+
+function lruGet(map, key) {
+  const v = map.get(key);
+  if (v === undefined) return undefined;
+  map.delete(key);
+  map.set(key, v); // LRU touch
+  return v;
+}
+
+function lruPut(map, key, val, max) {
+  map.delete(key);
+  map.set(key, val);
+  while (map.size > max) map.delete(map.keys().next().value);
+}
+
+/** 读缓存字节预算（review m1）：单条 >1MiB 不缓存、总量 ≤32MB，防止大文件驻留
+ *  造成 GC 压力拖慢整个宿主进程。超预算时从最旧条目开始逐出。 */
+const READ_CACHE_MAX_ENTRY_BYTES = 1024 * 1024;
+const READ_CACHE_TOTAL_BYTES = 32 * 1024 * 1024;
+function readCachePut(key, entry, max) {
+  entry.bytes = Buffer.byteLength(entry.content, "utf8");
+  if (entry.bytes > READ_CACHE_MAX_ENTRY_BYTES) return; // 大文件不缓存（结果照常返回）
+  lruPut(readCache, key, entry, max);
+  let total = 0;
+  for (const v of readCache.values()) total += v.bytes || 0;
+  while (total > READ_CACHE_TOTAL_BYTES && readCache.size > 1) {
+    const oldest = readCache.keys().next().value;
+    total -= readCache.get(oldest).bytes || 0;
+    readCache.delete(oldest);
+  }
+}
+
+function normalizeCachePath(path) {
+  let s = String(path || "");
+  while (s.length > 1 && s.charCodeAt(s.length - 1) === 47) s = s.slice(0, -1);
+  return s;
+}
+
+function posixDirname(path) {
+  const s = normalizeCachePath(path);
+  const i = s.lastIndexOf("/");
+  if (i < 0) return ".";
+  if (i === 0) return "/";
+  return s.slice(0, i);
+}
+
+/** 文件读取缓存失效（统一入口之一；pk 为 profileKey 字符串）。
+ *  subtree=true 同时失效 path 子树（rm -rf / mv 目录场景）。 */
+function invalidateReadCache(pk, path, opts) {
+  const sub = !!(opts && opts.subtree);
+  const target = pk + "|" + normalizeCachePath(path);
+  for (const k of Array.from(readCache.keys())) {
+    if (k === target || (sub && k.startsWith(target + "/"))) readCache.delete(k);
+  }
+}
+
+/** 目录列举缓存失效（同语义，作用于目录键）。 */
+function invalidateTreeCache(pk, dir, opts) {
+  const sub = !!(opts && opts.subtree);
+  const target = pk + "|" + normalizeCachePath(dir);
+  for (const k of Array.from(treeCache.keys())) {
+    if (k === target || (sub && k.startsWith(target + "/"))) treeCache.delete(k);
+  }
+}
+
+/** 收敛失效入口：所有可能改变远端文件/目录的插件入口都调用它 ——
+ *  文件缓存（exact + 可选子树）+ 列举缓存（被改目录本身 + 其父目录）+ 整代 epoch+1。 */
+function invalidateRemoteCaches(p, path, opts) {
+  bumpCacheEpoch(p);
+  const pk = profileKey(p);
+  const target = normalizeCachePath(path);
+  if (!target) return;
+  invalidateReadCache(pk, target, opts);
+  invalidateTreeCache(pk, target, opts);
+  invalidateTreeCache(pk, posixDirname(target), { subtree: false });
+}
+
+/** 整个 profile 的缓存清空（syncUp 批量覆盖远端后调用）。 */
+function clearCachesForProfile(p) {
+  const pk = profileKey(p);
+  cacheEpochs.set(pk, cacheEpoch(pk) + 1);
+  for (const k of Array.from(readCache.keys())) { if (k.startsWith(pk + "|")) readCache.delete(k); }
+  for (const k of Array.from(treeCache.keys())) { if (k.startsWith(pk + "|")) treeCache.delete(k); }
+}
+
+function isRawTextPath(path) {
+  const base = String(path || "").split(/[\\/]/).pop() || "";
+  const lower = base.toLowerCase();
+  const dot = lower.lastIndexOf(".");
+  if (dot > 0 && RAW_TEXT_EXTS.has(lower.slice(dot))) return true;
+  if (RAW_TEXT_NAMES.has(lower)) return true;
+  if (dot === 0 && RAW_TEXT_EXTS.has(lower)) return true; // .gitignore 这类整名即后缀
+  return false;
+}
+
+/** 远端错误摘要：压成单行、去重空白、≤300 字符（远端侧已 cut -c1-200，这里再兜底）。 */
+function sanitizeErrLine(s) {
+  const t = String(s || "").replace(/[\r\n\t]+/g, " ").replace(/ {2,}/g, " ").trim();
+  return t.slice(0, 300);
+}
+
+/**
+ * 解析 __DSH_ST__ 帧。stdout 首行必须严格以标记开头（登录噪声场景按旧行为降级，
+ * framed=false → 整段按旧协议处理，绝不误切）。stat 值异常（非数字/缺冒号）一律走
+ * err 分支，禁止 NaN 继续传播。首行之后即载荷（文件内容不会出现在标记行之前：
+ * 命令先 printf 标记，head/base64/cat 在其后输出）。
+ */
+function parseStatFrame(stdout) {
+  const out = String(stdout || "");
+  const nl = out.indexOf("\n");
+  const first = nl >= 0 ? out.slice(0, nl) : out;
+  const rest = nl >= 0 ? out.slice(nl + 1) : "";
+  if (!first.startsWith(DSH_ST_MARK)) {
+    return { framed: false, err: null, size: null, mtime: null, rest: out };
+  }
+  const body = first.slice(DSH_ST_MARK.length);
+  if (body.startsWith("ERR:")) {
+    return { framed: true, err: sanitizeErrLine(body.slice(4)) || "远端读取失败", size: null, mtime: null, rest: rest };
+  }
+  const ci = body.indexOf(":");
+  if (ci < 0) return { framed: true, err: "stat 标记解析异常", size: null, mtime: null, rest: rest };
+  const sizeStr = body.slice(0, ci);
+  const mtimeStr = body.slice(ci + 1);
+  if (!/^\d*$/.test(sizeStr) || !/^\d*$/.test(mtimeStr) || (sizeStr === "" && mtimeStr === "")) {
+    return { framed: true, err: "stat 标记数值异常", size: null, mtime: null, rest: rest };
+  }
+  return {
+    framed: true,
+    err: null,
+    size: sizeStr === "" ? null : parseInt(sizeStr, 10),
+    mtime: mtimeStr === "" ? null : parseInt(mtimeStr, 10),
+    rest: rest
+  };
+}
+
+/** 帧命令共享段：stat(size mtime) + 标记行。stat 失败 → ERR 标记 + false（非零收尾）。 */
+function statFrameSnippet() {
+  return "if st=$(stat -c'%s %Y' -- \"$f\" 2>&1); then printf '" + DSH_ST_MARK + "%s:%s\\n' \"${st%% *}\" \"${st#* }\"; ";
+}
+
+function errSnippet() {
+  return "else printf '" + DSH_ST_MARK + "ERR:%s\\n' \"$(printf '%s' \"$st\" | tr '\\r\\n' '  ' | cut -c1-200)\"; false; fi";
+}
+
+/** 复验命令（过期缓存条目的 mtime+size 校验）：1 裸 RTT，无内容传输。 */
+function buildStatCommand(path) {
+  return "f=" + shellQuotePath(path) + "; " + statFrameSnippet() + errSnippet();
+}
+
+/** 合并读命令：一次往返同时拿 size/mtime 与内容；>4MB 保留 head -c 截断语义。
+ *  raw=true 载荷为原始字节（仅白名单文本），否则 base64 -w0。 */
+function buildReadCommand(path, raw) {
+  const readPart = raw
+    ? "if [ \"${st%% *}\" -gt " + MAX_BYTES + " ] 2>/dev/null; then head -c " + MAX_BYTES + " -- \"$f\"; else cat -- \"$f\"; fi"
+    : "if [ \"${st%% *}\" -gt " + MAX_BYTES + " ] 2>/dev/null; then head -c " + MAX_BYTES + " -- \"$f\" | base64 -w0; else base64 -w0 -- \"$f\"; fi";
+  return "f=" + shellQuotePath(path) + "; " + statFrameSnippet() + readPart + "; " + errSnippet();
+}
+
+function decodeBase64Text(b64) {
+  const bytes = new Uint8Array(Buffer.from(String(b64).trim(), "base64"));
+  let binary = false;
+  const first = bytes.subarray(0, 8000);
+  for (let i = 0; i < first.length; i++) { if (first[i] === 0) { binary = true; break; } }
+  return { text: new TextDecoder().decode(bytes), binary: binary };
+}
+
+/** raw 载荷字节级校验：去掉协议层补的末尾 \n 后，字节数必须等于 size，且不含
+ *  \uFFFD（会话层 chunk.toString("utf8") 有损解码的痕迹）。任一不符 → 返回 null，
+ *  由调用方回退 base64 重读。二进制探测语义与旧实现一致（前 8000 含 NUL → binary）。 */
+function decodeRawText(rest, size) {
+  if (size === null || size === undefined) return null;
+  if (!rest.endsWith("\n")) return null; // 协议保证哨兵前有一个分隔 \n
+  const rawText = rest.slice(0, -1);
+  const expected = Math.min(size, MAX_BYTES);
+  if (Buffer.byteLength(rawText, "utf8") !== expected) return null;
+  if (rawText.indexOf("\uFFFD") >= 0) return null;
+  return { text: rawText, binary: rawText.slice(0, 8000).indexOf("\u0000") >= 0 };
+}
+
+function readResultOk(path, text, binary, truncated) {
+  return { ok: true, path: path, content: text, binary: binary, truncated: truncated };
+}
+
 async function remoteReadFile(runner, p, path) {
   if (!path) return { ok: false, error: "path 为必填项" };
-  // 先 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 pk = profileKey(p);
+  const key = pk + "|" + String(path);
+  const epoch = cacheEpoch(pk);
+  const hit = lruGet(readCache, key);
+  if (hit && hit.epoch === epoch) {
+    if (Date.now() - hit.at <= READ_CACHE_TTL_MS) {
+      return readResultOk(path, hit.content, hit.binary, hit.truncated); // TTL 内 0 RTT
+    }
+    // TTL 过期：1 裸 RTT 复验 mtime+size，未变则免内容重传（findings §3③）
+    const rv = await runner(p, buildStatCommand(path), undefined, MAX_BYTES);
+    if (rv.ok) {
+      const rst = parseStatFrame(rv.stdout);
+      if (rst.framed && rst.err !== null) {
+        readCache.delete(key); // 文件已消失/不可 stat：全量读也只会得到同样错误
+        return { ok: false, error: rst.err };
+      }
+      if (rst.framed && rst.size === hit.size && rst.mtime === hit.mtime) {
+        hit.at = Date.now();
+        readCachePut(key, hit, READ_CACHE_MAX);
+        return readResultOk(path, hit.content, hit.binary, hit.truncated);
+      }
+    }
+    // 复验失败/文件已变更 → 落到全量合并读
+  } else if (hit) {
+    readCache.delete(key); // 旧代条目（epoch 已推进）直接丢弃
   }
-  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;
+  const isRaw = isRawTextPath(path);
+  let r = await runner(p, buildReadCommand(path, isRaw), undefined, MAX_BYTES);
+  let st = parseStatFrame(r.stdout);
+  if (isRaw && r.ok && st.framed && st.err === null) {
+    const rawOk = decodeRawText(st.rest, st.size);
+    if (rawOk) {
+      const truncated = st.size !== null && st.size > MAX_BYTES;
+      if (!r.truncated) {
+        readCachePut(key, { content: rawOk.text, binary: rawOk.binary, truncated: truncated, size: st.size, mtime: st.mtime, epoch: epoch, at: Date.now() }, READ_CACHE_MAX);
+      }
+      return readResultOk(path, rawOk.text, rawOk.binary, truncated || !!r.truncated);
+    }
+    // raw 校验失败（二进制冒充文本/截断断字/异常）→ base64 重读，不劣于现状
+    r = await runner(p, buildReadCommand(path, false), undefined, MAX_BYTES);
+    st = parseStatFrame(r.stdout);
+  }
+  if (!r.ok) {
+    readCache.delete(key);
+    let msg = String(r.error || r.stderr || "").trim();
+    if (st.framed) msg = st.err !== null ? st.err : sanitizeErrLine(st.rest);
+    return { ok: false, error: msg || "读取失败" };
+  }
+  if (st.framed && st.err !== null) {
+    // 帧内错误但退出码 0（异常远端）：按错误处理，绝不返回空内容假成功
+    return { ok: false, error: st.err };
+  }
+  let decoded;
   try {
-    const bytes = new Uint8Array(Buffer.from(String(r.stdout).trim(), "base64"));
-    const first = bytes.subarray(0, 8000);
-    for (let i = 0; i < first.length; i++) { if (first[i] === 0) { binary = true; break; } }
-    text = new TextDecoder().decode(bytes);
+    decoded = decodeBase64Text(st.framed ? st.rest : r.stdout);
   } catch (e) {
     return { ok: false, error: "解码失败: " + String(e) };
   }
-  return { ok: true, path: path, content: text, binary: binary, truncated: truncated || r.truncated };
+  const truncated = st.framed && st.size !== null && st.size > MAX_BYTES;
+  if (st.framed && !r.truncated) {
+    readCachePut(key, { content: decoded.text, binary: decoded.binary, truncated: truncated, size: st.size, mtime: st.mtime, epoch: epoch, at: Date.now() }, READ_CACHE_MAX);
+  }
+  return readResultOk(path, decoded.text, decoded.binary, truncated || !!r.truncated);
 }
 
 async function remoteWriteFile(runner, p, path, content) {
@@ -466,7 +759,13 @@ async function remoteWriteFile(runner, p, path, content) {
   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);
+  // base64 -d 写入（heredoc stdin）：heredoc 帧固定补一个尾随 \n，base64 解码会忽略它，
+  // 从而字节级精确 —— 修复旧 `cat > file` 写法“每次保存尾随 +1 字节”的 quirk
+  // （findings §3⑦），且对 NUL/二进制安全。内容 ≤4MB → base64 ≤5.6MB，内存可控。
+  const r = await runner(p, "base64 -d > " + shellQuotePath(path), Buffer.from(c, "utf8").toString("base64"), MAX_BYTES, true);
+  // 写后失效：成功与否都失效（失败的写也可能已截断旧文件）。
+  invalidateRemoteCaches(p, path, { subtree: false });
+  return r;
 }
 
 /**
@@ -607,7 +906,11 @@ async function remoteSyncUp(subprocess, p, remotePath, mirrorPath) {
   try { sshOut = await sshH.done; } catch (e) { sshOut = { exitCode: -1 }; }
   const tarErr = readCollected(tarH, "stderr");
   const sshErr = readCollected(sshH, "stderr");
-  if (tarOut.exitCode === 0 && sshOut.exitCode === 0) return { ok: true, remotePath: remotePath };
+  if (tarOut.exitCode === 0 && sshOut.exitCode === 0) {
+    // 批量覆盖远端文件：清空该 profile 的读/列举缓存（findings §4.3a）
+    clearCachesForProfile(p);
+    return { ok: true, remotePath: remotePath };
+  }
   const parts = [];
   if (pipeErr) parts.push("管道: " + pipeErr);
   if (tarOut.exitCode !== 0) parts.push("tar 退出码 " + tarOut.exitCode + (tarErr ? ": " + tarErr.slice(0, 500) : ""));
@@ -743,10 +1046,7 @@ function apply(ctx, config) {
   // ---- 持久 SSH 会话池（连接复用，避免每次操作都做完整 SSH 握手）----
   const sessions = new Map(); // profileKey -> CommandSession
   const SESSION_IDLE_MS = 10 * 60 * 1000;
-  function profileKey(p) {
-    // 认证信息变化时应重建会话：修改 keyPath/authMethod 后旧连接不能继续复用。
-    return String(p.id) + "|" + String(p.host) + ":" + String(p.port || 22) + "|" + String(p.user || "") + "|" + String(p.authMethod || "key") + "|" + String(p.keyPath || "");
-  }
+  // profileKey 已上移模块层（读缓存/列举缓存与失效逻辑共用同一身份键，定义见 remoteReadFile 上方）。
   function getSession(p) {
     const key = profileKey(p);
     let s = sessions.get(key);
@@ -1023,7 +1323,11 @@ function apply(ctx, config) {
       if (!p) return { ok: false, error: "需要 profileId 或 host+user" };
       if (!args || !args.command) return { ok: false, error: "command 为必填项" };
       // 走持久会话池（stderr 分离）：首调用建立连接后，后续调用毫秒级返回。
-      return await runPooled(p, args.command, args.stdin, undefined, true);
+      // 远程命令可能改任意文件（插件不可见）→ 成功后整代失效读/列举缓存（findings §4.3a）；
+      // 失败的命令通常无副作用，不 bump 以免无谓打断缓存（部分副作用由 ≤5s TTL 兜底）。
+      const r = await runPooled(p, args.command, args.stdin, undefined, true);
+      if (r.ok) bumpCacheEpoch(p);
+      return r;
     },
     listDir: async (args) => {
       const p = resolveProfile(args);
@@ -1054,19 +1358,26 @@ function apply(ctx, config) {
       const p = resolveProfile(args);
       if (!p) return { ok: false, error: "需要 profileId 或 host+user" };
       if (!args || !args.path) return { ok: false, error: "path 为必填项" };
-      return await runPooled(p, "mkdir -p " + shellQuotePath(args.path), undefined, undefined);
+      const r = await runPooled(p, "mkdir -p " + shellQuotePath(args.path), undefined, undefined);
+      invalidateRemoteCaches(p, args.path, { subtree: false }); // 父目录列举变化
+      return r;
     },
     deleteFile: async (args) => {
       const p = resolveProfile(args);
       if (!p) return { ok: false, error: "需要 profileId 或 host+user" };
       if (!args || !args.path) return { ok: false, error: "path 为必填项" };
-      return await runPooled(p, "rm -rf " + shellQuotePath(args.path), undefined, undefined);
+      const r = await runPooled(p, "rm -rf " + shellQuotePath(args.path), undefined, undefined);
+      invalidateRemoteCaches(p, args.path, { subtree: true });
+      return r;
     },
     move: async (args) => {
       const p = resolveProfile(args);
       if (!p) return { ok: false, error: "需要 profileId 或 host+user" };
       if (!args || !args.src || !args.dst) return { ok: false, error: "src 和 dst 为必填项" };
-      return await runPooled(p, "mv " + shellQuotePath(args.src) + " " + shellQuotePath(args.dst), undefined, undefined);
+      const r = await runPooled(p, "mv " + shellQuotePath(args.src) + " " + shellQuotePath(args.dst), undefined, undefined);
+      invalidateRemoteCaches(p, args.src, { subtree: true });
+      invalidateRemoteCaches(p, args.dst, { subtree: true });
+      return r;
     },
     /** 远端 → 本地镜像（按工作区）。 */
     syncDown: async (args) => {
@@ -1222,7 +1533,10 @@ function apply(ctx, config) {
       // 走持久会话池（stderr 分离，双哨兵协议）：首次调用完成建连后，
       // 后续调用不再重复 TCP 握手 + 认证，单次耗时从秒级降到毫秒级；
       // 会话异常时 runPooled 自动重建并降级一次性连接。
-      return normExec(await runPooled(tc.profile, cmd, args.stdin, undefined, true));
+      // 远程命令可能改任意文件（插件不可见）→ 整代失效读/列举缓存（findings §4.3a）。
+      const r = await runPooled(tc.profile, cmd, args.stdin, undefined, true);
+      bumpCacheEpoch(tc.profile);
+      return normExec(r);
     }
   });
 
@@ -1435,8 +1749,10 @@ function apply(ctx, config) {
       const tc = toolContext(args, exec);
       if (!tc.profile) return normExec({ ok: false, error: "需要 profileId 或 host+user（当前会话非远程工作区时必填）" });
       if (!args.path) return normExec({ ok: false, error: "path 为必填项" });
-      let cmd = "mkdir -p " + shellQuotePath(resolveRemotePath(args.path, tc.remotePath));
-      return normExec(await runPooled(tc.profile, cmd, undefined, undefined));
+      const rp = resolveRemotePath(args.path, tc.remotePath);
+      const r = await runPooled(tc.profile, "mkdir -p " + shellQuotePath(rp), undefined, undefined);
+      invalidateRemoteCaches(tc.profile, rp, { subtree: false }); // 父目录列举变化
+      return normExec(r);
     }
   });
 
@@ -1450,8 +1766,10 @@ function apply(ctx, config) {
       const tc = toolContext(args, exec);
       if (!tc.profile) return normExec({ ok: false, error: "需要 profileId 或 host+user（当前会话非远程工作区时必填）" });
       if (!args.path) return normExec({ ok: false, error: "path 为必填项" });
-      let cmd = "rm -rf " + shellQuotePath(resolveRemotePath(args.path, tc.remotePath));
-      return normExec(await runPooled(tc.profile, cmd, undefined, undefined));
+      const rp = resolveRemotePath(args.path, tc.remotePath);
+      const r = await runPooled(tc.profile, "rm -rf " + shellQuotePath(rp), undefined, undefined);
+      invalidateRemoteCaches(tc.profile, rp, { subtree: true });
+      return normExec(r);
     }
   });
 
@@ -1468,8 +1786,12 @@ function apply(ctx, config) {
       const tc = toolContext(args, exec);
       if (!tc.profile) return normExec({ ok: false, error: "需要 profileId 或 host+user（当前会话非远程工作区时必填）" });
       if (!args.src || !args.dst) return normExec({ ok: false, error: "src 和 dst 为必填项" });
-      let cmd = "mv " + shellQuotePath(resolveRemotePath(args.src, tc.remotePath)) + " " + shellQuotePath(resolveRemotePath(args.dst, tc.remotePath));
-      return normExec(await runPooled(tc.profile, cmd, undefined, undefined));
+      const src = resolveRemotePath(args.src, tc.remotePath);
+      const dst = resolveRemotePath(args.dst, tc.remotePath);
+      const r = await runPooled(tc.profile, "mv " + shellQuotePath(src) + " " + shellQuotePath(dst), undefined, undefined);
+      invalidateRemoteCaches(tc.profile, src, { subtree: true });
+      invalidateRemoteCaches(tc.profile, dst, { subtree: true }); // dst 子树：mv file dir/ 会落入既有目录
+      return normExec(r);
     }
   });
 
@@ -1853,10 +2175,15 @@ function apply(ctx, config) {
   }
 
   /** 远端 git 执行（远程工作区）：在 remoteDir 里跑同一 git 语义。 */
+  const GIT_MUTATING_FIRST_TOKENS = new Set(["add", "reset", "commit", "checkout", "revert", "cherry-pick"]);
   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 };
+    // 仅变更类子命令（stage→add / unstage→reset / commit / checkout / discard→checkout /
+    // revert / cherry-pick）会改工作区文件 → 整代失效读/列举缓存；
+    // status/diff/log/branch/show 等只读命令不再打断缓存（review m4）。
+    if (GIT_MUTATING_FIRST_TOKENS.has(String(args[0] || ""))) bumpCacheEpoch(profile);
     return r.stdout;
   }
 
@@ -2137,6 +2464,8 @@ function apply(ctx, config) {
         writeJson(res, status, { ok: false, error: { code: r.code, message: r.message } });
         return;
       }
+      // 上传落盘：目标文件 + 父目录列举失效
+      invalidateRemoteCaches(profile, target, { subtree: false });
       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) } });

package/package.json

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