@zhangfengshun/dsh-remote-ssh 2.3.5 → 2.3.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.3.7] — Windows host 连接诊断增强：过滤 PQ 警告、ssh -v 诊断、跨平台测试探测
+### 修复
+- **过滤 OpenSSH「后量子 KEX」警告横幅**：新版本客户端对非 PQ 加密的 stderr 警告（三行 `** WARNING…`）与认证成败无关，此前混入错误信息会误导用户以为是不支持加密算法；现在统一过滤（错误提示、一次性连接 stderr、持久会话关闭诊断）。
+- **测试连接探测命令改为跨平台 `echo __DSH_OK__`**：旧命令尾部 `uname -a`/`pwd` 在 Windows host（cmd/PowerShell）上必然报错，导致**认证成功的 Windows host 也误报失败**。
+- **认证失败自动带 ssh -v 诊断**：测试连接认证失败时重跑一次 `ssh -v` 握手，抽取关键诊断行（私钥加载 / 公钥提供 / 服务器拒绝方法 / 口令要求）附在错误信息里，用户一眼定位失败环节。
+- **公钥失败提示覆盖 Windows 三大圈套**：① 私钥带口令 + 批处理模式无法交互输入（先 ssh-add 或去口令）；② Windows host 且用户在 Administrators 组时公钥须写入 `C:\ProgramData\ssh\administrators_authorized_keys`；③ 用户名写法（`user` / `.\user` / `user@domain`）须与手动连接一致。
+
+## [2.3.6] — settings 注册迁移至字符串命名空间，移除 legacy 导出依赖
+### 变更
+- **不再从 `@deepseek-ai/dsh-settings` 导入 `settingsNamespace`**：该导出在 dsh-settings 中被标注为 legacy（仅为 alpha.2 之前的插件保留，未来版本可能移除）。`parseSettingsNamespace` 实为恒等函数（校验 `/^[a-z][a-z0-9-]*$/` 后原样返回），故 `register(NS, schema)` 与原 `register(settingsNamespace(NS), schema)` 存储键完全一致——零数据迁移，老用户配置无缝保留。
+- **peerDependencies 移除 `@deepseek-ai/dsh-settings`**（已无导入；`ctx.settings` 能力由 DSH 内核的 settings 服务提供，与该 npm 包导入无关），安装时少一条未解析 peer 警告。
+
 ## [2.3.5] — 地球角标样式重制：右下角、默认文件夹形状、透明底白经纬线
 ### 变更
 - **文件夹形状与默认完全一致**：不再自绘/改写文件夹几何，壳层 IconFolderOpen16/Close16 的原始路径与几何零改写，仅向工作区行首槽位 svg **追加**一个透明地球经纬线组（appendChild 不触碰 React 管理的子节点，零对账风险）。

package/README.md

@@ -13,14 +13,31 @@
 | 💻 远程终端 | 内置「终端」页签自动检测远程工作区，SSH 交互式终端 |
 | 🌐 远程工作区 | 选择远程目录创建原生工作区，一键进入远程环境 |
 | 🤖 模型工具 | 12 个 `remote_ssh_*` 工具，会话感知免填连接参数 |
+| ⚡ 打开提速 | 单往返合并读 + raw 文本快路径 + 结果缓存（LRU + 5s TTL）：首开 ≈**1.31×**，TTL 内重复打开 **0 往返**，过期复验 **≈5×**（真实超算实测）；`remote_ssh_exec` 连接复用 **≈15×** |
+
+## 截图
+
+**设置 → 🖥️ 远程连接**：连接配置（密钥 / 密码 / ProxyJump 跳板机）· 连接测试 · 从 `~/.ssh/config` 一键导入
+
+<p align="center"><img src="assets/settings-remote-connections.png" width="420" alt="设置：远程连接"></p>
+
+**内置「文件」页签**：直接浏览远程主机文件（右侧文件树即远程目录，编辑保存直写远程）
+
+<p align="center"><img src="assets/remote-files-tab.webp" width="820" alt="内置文件页签直接浏览远程文件"></p>
+
+**内置「终端」页签**：自动 SSH 到远程超算（图为 SLURM 作业调度环境）；左侧会话即模型免填调用 `remote_ssh_*` 工具
+
+<p align="center"><img src="assets/remote-terminal.webp" width="820" alt="内置终端页签自动 SSH 远程超算"></p>
 
 ## 安装
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.5
 ```
 
 > 安装后需**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
+>
+> 内置「文件」页签的 SSH 直读依赖 **dsh-better-sidebar ≥ 0.15** 的文件 API（`/sidebar/api/fs.*` 端点），请勿使用更早版本；当前已逐点验证至 **dsh-better-sidebar 0.18.0**。
 
 ## 使用
 
@@ -46,17 +63,19 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
 | `remote_ssh_sync` | 远端同步到本地镜像 |
 | `remote_ssh_push` | 本地镜像推送回远端 |
 
-远程工作区会话中调用工具可免填 `profileId` 等连接参数。
+远程工作区会话中调用工具可免填 `profileId` 等连接参数；全部文件/命令类工具走持久 SSH 会话池 + 结果缓存，`remote_ssh_exec` 单命令实测 ≈15× 提速。
 
 ## 原理
 
 插件注册 4 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
 
+远程读取采用**单往返合并读**：一条池化命令同时返回 `size/mtime` 帧与文件内容（文本类扩展名优先 raw 直传，字节长 + U+FFFD 双校验失败自动回退 base64，结果逐字节一致）；配合主机侧结果缓存与变更失效（见下节）。
+
 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 面板操作会自动失效相关缓存。
+远程读取与目录列举结果在主机侧缓存（读 LRU 32 条 + 列举 LRU 64 条，TTL 5 秒；单条 >1MiB 不缓存、总量 32MB 字节预算，防止大文件驻留拖慢宿主）：TTL 内重复打开或切回页签 **0 网络往返**；过期后先做一次轻量 mtime+size 复验，未变化则免重传。写、删除、移动、建目录、上传、推送（push）、成功的远端 exec 与变更类 git 子命令（add/reset/commit/checkout/revert/cherry-pick）会自动失效相关缓存，并以每 profile 缓存代（epoch）兜底「同秒同 size 写」等粒度盲区。
 
 已知限制：
 

package/README_EN.md

@@ -13,14 +13,31 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 | 💻 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 |
+| ⚡ Faster Opens | Single-roundtrip merged reads + raw text fast path + result cache (LRU + 5s TTL): first open ≈**1.31×**, repeat opens within TTL **0 round-trips**, expired revalidation **≈5×** (measured on a real HPC); `remote_ssh_exec` connection reuse **≈15×** |
+
+## Screenshots
+
+**Settings → 🖥️ Remote SSH**: connection profiles (key / password / ProxyJump bastion) · connection test · one-click import from `~/.ssh/config`
+
+<p align="center"><img src="assets/settings-remote-connections.png" width="420" alt="Settings: Remote Connections"></p>
+
+**Built-in Files tab**: browse the remote host directly (the right-hand tree IS the remote directory, edits save back to remote)
+
+<p align="center"><img src="assets/remote-files-tab.webp" width="820" alt="Built-in Files tab browsing remote files"></p>
+
+**Built-in Terminal tab**: auto-SSH to the HPC (SLURM environment shown); the left panel shows the model calling `remote_ssh_*` tools without connection params
+
+<p align="center"><img src="assets/remote-terminal.webp" width="820" alt="Built-in Terminal tab auto-SSH to remote HPC"></p>
 
 ## Installation
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.5
 ```
 
 > **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
+>
+> The built-in **Files** tab SSH interception relies on the file API of **dsh-better-sidebar ≥ 0.15** (`/sidebar/api/fs.*` endpoints) — do not use older versions; verified point-by-point against **dsh-better-sidebar 0.18.0**.
 
 ## Usage
 
@@ -46,17 +63,19 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.3.0
 | `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.
+In a remote-workspace session, `profileId` and other connection params can be omitted. All file/command tools run over the persistent SSH session pool + result cache; `remote_ssh_exec` measures ≈15× faster per command.
 
 ## 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.
 
+Remote reads use a **single-roundtrip merged read**: one pooled command returns the `size/mtime` frame plus the file content (text extensions prefer raw transfer with byte-length + U+FFFD validation and automatic base64 fallback — results are byte-identical), combined with host-side result caching and change invalidation (see below).
+
 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.
+Remote reads and directory listings are cached host-side (read LRU 32 + listing LRU 64 entries, TTL 5s; entries >1MiB are not cached, total budget 32MB so large files never weigh down the host): 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. Writes, deletes, moves, mkdir, uploads, push (syncUp), successful remote exec and mutating git subcommands automatically invalidate the affected cache entries, with a per-profile cache epoch guarding same-second same-size writes and path-space mismatches.
 
 Known limitations:
 

package/lib/index.js

@@ -10,7 +10,6 @@
  */
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { mkdir, rm, writeFile, readFile, opendir, stat, open, rename, readdir } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -217,7 +216,7 @@ class CommandSession {
     });
     const onEnd = () => {
       this.alive = false;
-      const errMsg = "ssh 会话已关闭" + (this.errBuf.trim() ? ": " + this.errBuf.trim().slice(-300) : "");
+      const errMsg = "ssh 会话已关闭" + (this.errBuf.trim() ? ": " + stripPqBanner(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));
     };
@@ -337,7 +336,7 @@ class CommandSession {
   }
 }
 
-function sshArgv(p, remoteCmd, tty) {
+function sshArgv(p, remoteCmd, tty, extraOpts) {
   const opts = ["ssh"];
   if (tty) opts.push("-tt");
   opts.push("-p", String(p.port || 22));
@@ -357,6 +356,7 @@ function sshArgv(p, remoteCmd, tty) {
     opts.push("-o", "BatchMode=yes");
     opts.push("-o", "PreferredAuthentications=publickey");
   }
+  if (Array.isArray(extraOpts) && extraOpts.length) opts.push(...extraOpts);
   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]);
@@ -364,12 +364,23 @@ function sshArgv(p, remoteCmd, tty) {
   return argv;
 }
 
-async function runRemote(subprocess, p, remoteCmd, stdinData, maxBytes) {
+/** 过滤 OpenSSH 客户端的“后量子 KEX”警告横幅（stderr 噪音，与认证成败无关，
+ *  混进错误信息会误导用户以为是不支持加密算法）。 */
+function stripPqBanner(text) {
+  return String(text || "")
+    .split("\n")
+    .filter(function (line) {
+      return !/^\s*\*\*\s*(WARNING: connection is not using a post-quantum|This session may be vulnerable to .?store now|The server may need to be upgraded)/i.test(line);
+    })
+    .join("\n");
+}
+
+async function runRemote(subprocess, p, remoteCmd, stdinData, maxBytes, extraOpts) {
   const max = maxBytes || MAX_BYTES;
   let handle;
   try {
     handle = subprocess.spawn({
-      argv: sshArgv(p, remoteCmd, false),
+      argv: sshArgv(p, remoteCmd, false, extraOpts),
       cwd: process.cwd(),
       stdio: {
         stdin: stdinData !== undefined ? { data: String(stdinData) } : "ignore",
@@ -390,7 +401,7 @@ async function runRemote(subprocess, p, remoteCmd, stdinData, maxBytes) {
   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 };
   const outText = so.text;
-  const errText = se.text;
+  const errText = stripPqBanner(se.text);
   let error = "";
   if (outcome.exitCode !== 0 && !outText && !errText) {
     error = "ssh 退出码 " + outcome.exitCode + (outcome.signal ? " (signal " + outcome.signal + ")" : "");
@@ -1055,12 +1066,12 @@ function apply(ctx, config) {
   }
   /** 把 SSH 常见失败翻译成带修复建议的中文提示。 */
   function sshErrorHint(text) {
-    const t = String(text || "");
+    const t = stripPqBanner(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 (/permission denied \(publickey/i.test(t)) return "公钥认证失败（服务器拒绝了公钥）。请依次检查：① keyPath 指向的私钥是否正确、是否带口令——测试连接以批处理模式运行无法交互输口令，可先 ssh-add 加载或改用无口令密钥；② 远端是否收录对应公钥——Windows 主机且目标用户在 Administrators 组时需写入 C:\\ProgramData\\ssh\\administrators_authorized_keys；③ profile 的用户名写法与手动连接是否一致（user / .\\user / user@domain 在 Windows sshd 中解析不同）。原始信息: " + 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);
@@ -1110,7 +1121,10 @@ function apply(ctx, config) {
     updateWorkspaces: async () => {}
   };
   ctx.inject(["settings"], (sctx) => {
-    const scope = sctx.settings.register(settingsNamespace(NS), PrefsSchema);
+    // settings 命名空间直接传插件 id（匹配 /^[a-z][a-z0-9-]*$/）。不再依赖
+    // @deepseek-ai/dsh-settings 的 legacy `settingsNamespace` 构造器（该导出仅为
+    // alpha.2 之前的插件保留，未来可能移除）；恒等语义下两种写法存储键完全一致。
+    const scope = sctx.settings.register(NS, PrefsSchema);
     settingsFace = {
       read: () => {
         const v = scope.get();
@@ -1237,7 +1251,26 @@ function apply(ctx, config) {
     testConnection: async (args) => {
       const p = getProfile(args && args.id);
       if (!p) return { ok: false, error: "未找到连接配置" };
-      return await runRemote(subprocess, p, "echo __DSH_OK__; hostname; whoami; pwd; uname -a", undefined, 256 * 1024);
+      // 认证探测只用跨平台 echo：Windows host 无 uname/pwd，且默认 shell 语义各异
+      // （旧命令尾部 uname -a 会让认证成功的 Windows host 也误报失败）。
+      const r = await runRemote(subprocess, p, "echo __DSH_OK__", undefined, 16 * 1024);
+      if (r.ok) return r;
+      const baseErr = sshErrorHint([r.error, stripPqBanner(r.stderr).trim()].filter(Boolean).join(" ") || ("ssh 退出码 " + r.exitCode));
+      // 认证类失败：带 ssh -v 重跑一次握手 + 认证，抽取关键诊断行
+      // （私钥加载 / 公钥提供 / 服务器拒绝方法），定位 Windows 常见坑。
+      let error = baseErr;
+      if (/permission denied|publickey/i.test(baseErr + " " + stripPqBanner(r.stderr))) {
+        const diag = await runRemote(subprocess, p, "exit 0", undefined, 16 * 1024, ["-v"]);
+        const diagText = String(diag.stderr || "")
+          .split("\n")
+          .filter(function (l) {
+            return /debug1: (Offering public key|Authentications that can continue|Server accepts key|Trying private key|no such identity)|Load key|Permission denied|passphrase/i.test(l);
+          })
+          .join("\n")
+          .slice(0, 1200);
+        if (diagText) error = baseErr + "\n\nssh -v 诊断:\n" + diagText;
+      }
+      return { ok: false, exitCode: r.exitCode, signal: r.signal, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, error: error };
     },
     listWorkspaces: async () => ({ ok: true, workspaces: settingsFace.read().workspaces }),
     createRemoteWorkspace: async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.3.5",
+  "version": "2.3.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",
@@ -59,7 +59,6 @@
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
   },
   "files": [