@zhangfengshun/dsh-remote-ssh 2.4.2 → 2.4.4

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.4] — 文档结构补全（README 代码示例 / 兼容性矩阵 / 故障排查）
+### 文档
+- **新增「代码示例」章节**（中英双语）：6 组可直接照抄的示例——远程命令（含 `timeoutMs`）、文件读写、长时任务与挂起恢复（`timeoutMs: 0` / `remote_ssh_kill`）、远程工作区内的免参调用、`~/.ssh/config` 导入、镜像 sync/push，并给出真实返回值形状。
+- **新增「兼容性」矩阵**：逐行列出 DSH 0.1.5-rc.1 / 0.1.2 稳定线、dsh-better-sidebar 0.15–0.18（4 端点）与 0.19.x（6 端点，并标注上游主机半边加载问题）、远程 sshd 的实测状态。
+- **新增「故障排查」表**：公钥认证失败（口令密钥 / Administrators 授权文件 / 用户名写法）、git-bash 启动、文件页签「这类内容还没有可用的查看方式。」、终端仅密钥认证、`minimumReleaseAge`、命令挂起、大文件截断——每条给出原因与解法。
+- **新增「安装」前置要求表与卸载命令**、README 顶部目录导航、「更新日志」入口与 Star 引导。
+- 中文 README 与英文 README_EN 保持结构对齐。
+
+## [2.4.3] — 适配 better-sidebar 0.19 新增端点（fs.rename / fs.remove）+ 版本兼容性核查
+### 新增
+- **拦截 better-sidebar 0.19 新增的 `fs.rename` / `fs.remove` 端点**（exact 路由从 4 条增至 6 条）：远程工作区的「重命名 / 删除」此前会落到本地镜像目录（0.19 之前 better-sidebar 没有这两个端点，操作走客户端 API，不存在该问题）。现在：
+  - 远程工作区 → 走 SSH（`mv -f --` / `rm -rf --`），语义对齐 better-sidebar（单个路径段校验、目标已存在返回 409、禁止操作工作区根），并失效相关读/列举缓存；
+  - 本地工作区 → 本地实现（不覆盖、lstat 判定符号链接、目录递归删除），契约与 better-sidebar 完全一致；
+  - 旧版 better-sidebar（无此端点）不调用这两个路由，注册无副作用。
+
+### 兼容性核查（重要）
+- **dsh-better-sidebar 0.19.0 / 0.19.1（以及 0.18.1）在当前 DSH Desktop（v2.0.9，DSH 0.1.5-rc.1）上主机半边无法加载**：其 `lib/index.js` 以**值**方式导入 `SessionLogOffset`（`import { SessionLogOffset } from "@deepseek-ai/dsh-session"`），而 DSH 2.0.9 面向插件的模块面只提供该符号的**类型**声明，运行时导入抛 `does not provide an export named 'SessionLogOffset'` → better-sidebar 主机半边（fs/git/terminal/jobs 等全部 API）整体失效，侧边栏文件页签因此回落到「这类内容还没有可用的查看方式。」
+- **已验证的版本矩阵**：`0.19.1`（导入该符号）、`0.19.0`（导入）、`0.18.1`（导入）→ 在 DSH 2.0.9 上不可用；`0.18.0`、`0.17.1`（不导入）→ 可用。本插件在 `0.18.0` 上逐点验证：`fs.tree/read/write/search` 返回形状、`betterSidebar` 服务与 `registerTab`、`/sidebar/upload` 上传拦截全部咬合。
+- 建议：在 better-sidebar 修复该导入（或 DSH 恢复该运行时导出）之前，desktop profile 使用 **dsh-better-sidebar@0.18.0**；本插件对 0.18/0.19 两套契约均已适配。
+
 ## [2.4.2] — 修复设置导航显示器图标「先齿轮后显示器」闪现
 ### 修复
 - **图标替换从防抖路径改为同步执行**：此前设置面板挂载后，显示器图标替换走 500ms 防抖定时器，用户会先看到半秒壳层默认齿轮再变成显示器图标。现在在 MutationObserver 回调里**同步原位替换**——回调是微任务、在浏览器绘制前执行，齿轮刚插入 DOM 就被换掉，**第一帧即最终图标**，无闪现。

package/README.md

@@ -4,6 +4,8 @@
 
 类 **VSCode Remote-SSH** 的 **DSH** 插件：通过 SSH 连接远程超算 / 服务器，在 DSH 内置「文件」「终端」页签中直接操作远程文件和终端。
 
+**目录**：[功能](#功能) · [截图](#截图) · [安装](#安装) · [使用](#使用) · [代码示例](#代码示例) · [模型工具](#模型工具) · [命令超时与恢复](#命令超时与恢复) · [兼容性](#兼容性) · [故障排查](#故障排查) · [原理](#原理) · [缓存与一致性](#缓存与一致性) · [许可证](#许可证)
+
 ## 功能
 
 | 能力 | 说明 |
@@ -31,20 +33,107 @@
 
 ## 安装
 
+**前置要求**
+
+| 项 | 要求 |
+| --- | --- |
+| DSH | ≥ 0.1.5-rc.1（0.1.2 稳定线请用 v0.18.1 时代的插件版本） |
+| dsh-better-sidebar | ≥ 0.15（本插件依赖其 `/sidebar/api/fs.*` 文件 API） |
+| 本机 SSH 客户端 | Windows：系统自带 OpenSSH（`%SystemRoot%\System32\OpenSSH\ssh.exe`）；Linux/macOS：openssh-client |
+| 远程主机 | 任意标准 sshd（超算 / 服务器 / 跳板机均可） |
+
+**一条命令安装**（无需 token、API Key 或额外配置）：
+
+```bash
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.4
+```
+
+安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
+
+卸载：
+
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
+dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 ```
 
-> 安装后需**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
->
-> 内置「文件」页签的 SSH 直读依赖 **dsh-better-sidebar ≥ 0.15** 的文件 API（`/sidebar/api/fs.*` 端点），请勿使用更早版本；当前已逐点验证至 **dsh-better-sidebar 0.19.0** 与 **DSH 0.1.5-rc.1**（主机服务 / settings / tools / slot / 上传下载拦截全部咬合）。
+> ⚠️ **dsh-better-sidebar 版本兼容性（2026-09 实测）**：`0.18.1 / 0.19.0 / 0.19.1` 在 DSH Desktop v2.0.9（DSH 0.1.5-rc.1）上**主机半边无法加载**（它们以值方式导入 `SessionLogOffset`，桌面版模块面只提供该类型声明）→ 侧边栏文件页签显示「这类内容还没有可用的查看方式。」。请使用 **0.18.0**，或使用已修复该导入的构建；本插件对 0.18（4 端点）与 0.19（6 端点，含 `fs.rename`/`fs.remove`）两套契约均已适配。
 
 ## 使用
 
-1. **设置 → 远程连接** → 添加连接（主机/端口/用户/密钥）→ 点「测试连接」验证
-2. **添加工作区** → 选「选择远程目录…」→ 选连接 → 浏览并选择远程目录
-3. 打开内置「文件」页签 → 直接显示远程文件，编辑保存直接写回远程
-4. 打开内置「终端」页签 → 自动 SSH 到远程主机（仅密钥认证）
+**三步上手**
+
+1. **设置 → 远程连接** → 添加连接（主机 / 端口 / 用户 / 密钥）→ 点「测试连接」验证；已有 `~/.ssh/config` 可直接一键导入
+2. **添加工作区** → 选「选择远程目录…」→ 选连接 → 浏览并选择远程目录（该目录会成为原生 DSH 工作区）
+3. 进入该工作区会话：内置「文件」页签直接显示远程文件（编辑保存直写远程），「终端」页签自动 SSH 到远程主机（仅密钥认证）
+
+**会话内直接对模型说**（远程工作区会话中免填连接参数）：
+
+```text
+看看 /home/user/project 下有什么，然后把 train.py 的第 20 行改掉
+跑一下 squeue -u $USER，把排队情况整理成表格
+把这个目录的 *.log 里含 ERROR 的行抓出来
+```
+
+## 代码示例
+
+**示例 1 · 执行远程命令**（`remote_ssh_exec`，默认 120s 超时）：
+
+```json
+{
+  "command": "sinfo -h -o '%P %a %D %t %N' | head -20",
+  "timeoutMs": 30000
+}
+```
+
+返回 `{ ok, exitCode, stdout, stderr, error, truncated, isTimeout }`——例如：
+
+```json
+{ "ok": true, "exitCode": 0, "stdout": "cpu* up 12 idle 8 ...\n", "stderr": "", "error": "", "truncated": false, "isTimeout": false }
+```
+
+**示例 2 · 文件读写（无需同步）**：
+
+```json
+{ "path": "~/project/config.yaml", "content": "lr: 0.001\nepochs: 50\n" }
+```
+
+```json
+{ "path": "~/project/train.py" }
+```
+
+`remote_ssh_cat` 走 base64 传输（二进制安全），`remote_ssh_write` 为原子写入（写临时文件再 rename）。
+
+**示例 3 · 长时任务与挂起恢复**（构建 / 训练显式放宽，卡住可强杀会话）：
+
+```json
+{ "command": "cd ~/project && bash run_train.sh", "timeoutMs": 0 }
+```
+
+```json
+{ "all": true }
+```
+
+`timeoutMs: 0` 禁用本次超时；环境变量 `DSH_REMOTE_SSH_CMD_TIMEOUT_MS=600000` 可改全局默认。超时后池化会话自动丢弃重建，`remote_ssh_kill` 是随时可用的手动兜底。
+
+**示例 4 · 远程工作区内的工具调用**（免填 `profileId`，相对路径基于工作区远程目录）：
+
+```json
+{ "path": "configs/exp1.yaml" }
+```
+
+**示例 5 · 从 `~/.ssh/config` 导入连接**：设置 → 远程连接 → 「导入 SSH config」→ 勾选主机 → 自动填充 host / user / port / keyPath / ProxyJump。
+
+**示例 6 · 本地镜像同步与回推**（离线批改后再一次性上传）：
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+`remote_ssh_sync` 把远端拉进本地镜像目录，`remote_ssh_push` 把镜像改动推回远端（tar over ssh，批量高效）。
 
 ## 模型工具
 
@@ -75,9 +164,35 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
 - **手动兜底**：`remote_ssh_kill`（或 `all: true`）强制关闭某个/全部池化会话，挂起命令随时可清理；
 - 超时命令**不做自动重试**（重试一条挂起的命令只会再次挂起），由模型决定是否改用 `remote_ssh_kill` 或换命令重试。
 
+## 兼容性
+
+**实测矩阵**（2026-09-12，均为真机验证）：
+
+| 组件 | 版本 | 状态 |
+| --- | --- | --- |
+| DSH | 0.1.5-rc.1（DSH Desktop v2.0.9） | ✅ 主机服务 / settings / tools / slot / 上传下载拦截全部咬合 |
+| DSH | 0.1.2-rc.1 稳定线 | ✅（插件 2.3.x 时代基线） |
+| dsh-better-sidebar | 0.15.0 – 0.18.0 | ✅ `fs.tree/read/write/search`（4 端点契约） |
+| dsh-better-sidebar | 0.19.x | ⚠️ 插件侧已适配 6 端点（含 `fs.rename`/`fs.remove`）；但 0.19.0/0.19.1 自身在 DSH Desktop 上主机半边无法加载，需等上游修复（见[安装](#安装)的警告） |
+| 远程主机 sshd | 标准 OpenSSH（Linux / 超算 / Windows） | ✅ 密钥认证；密码认证需本机 `sshpass`（POSIX） |
+
+插件不修改 DSH 源码、不注入 profile 依赖树，全部能力经官方 `cordis.patch.yml` + profile 机制挂载。
+
+## 故障排查
+
+| 现象 | 原因与解法 |
+| --- | --- |
+| 「测试连接」报 `Permission denied (publickey)` | ① 私钥**带口令**：插件以批处理模式运行（`BatchMode=yes`），无法交互输口令——先用 `ssh-add` 加载，或去掉密钥口令；② Windows host 且用户在 Administrators 组时，公钥须写入 `C:\ProgramData\ssh\administrators_authorized_keys`；③ 用户名的写法（`user` / `.\user` / `user@domain`）要与手动连接一致 |
+| 从 git-bash 启动 `dsh web` 后密钥认证失败 | 2.3.9 起已修复：Windows 下 ssh 解析固定为系统 OpenSSH 绝对路径（此前会误用 Git 自带的 MSYS2 ssh） |
+| 侧边栏文件页签显示「这类内容还没有可用的查看方式。」 | `dsh-better-sidebar` 主机半边未加载：0.18.1 / 0.19.0 / 0.19.1 在 DSH Desktop 上会因 `SessionLogOffset` 运行时导入失败——降到 0.18.0 或使用修复版（上游 PR [#641](https://github.com/omdsh-dev/DSH-better-sidebar/pull/641)） |
+| 内置「终端」页签连不上 | 终端为 `ssh -tt` 交互式通道，**仅支持密钥认证**；密码认证请改用「文件」页签与模型工具 |
+| 安装时提示 `minimumReleaseAge` 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
+| 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 `timeoutMs: 0`，随时可用 `remote_ssh_kill` 强杀 |
+| 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 `remote_ssh_exec` + `head`/`tail` 分段处理 |
+
 ## 原理
 
-插件注册 4 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
+插件注册 6 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`，以及 better-sidebar 0.19 新增的 `fs.rename`、`fs.remove`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
 
 远程读取采用**单往返合并读**：一条池化命令同时返回 `size/mtime` 帧与文件内容（文本类扩展名优先 raw 直传，字节长 + U+FFFD 双校验失败自动回退 base64，结果逐字节一致）；配合主机侧结果缓存与变更失效（见下节）。
 
@@ -101,6 +216,14 @@ Shell wrapper（`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`）检测工作区 `.r
 
 —— 2026 年 8 月 18 日
 
+## 更新日志
+
+版本历史与每版修复细节见 [CHANGELOG.md](./CHANGELOG.md)（最近：2.4.3 适配 better-sidebar 0.19 端点、2.4.2 修复设置图标闪现、2.4.0 命令级超时与 `remote_ssh_kill`）。
+
 ## 许可证
 
 [MIT](./LICENSE)
+
+---
+
+如果这个插件帮到了你，欢迎在 GitHub 上点个 ⭐ [Star](https://github.com/ZhangFengshun/dsh-remote-ssh)，或到 [DSH Market](https://dshmarket.com) 收藏——这会帮助更多需要远程超算开发的人找到它。

package/README_EN.md

@@ -4,6 +4,8 @@ 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.
 
+**Contents**: [Features](#features) · [Screenshots](#screenshots) · [Installation](#installation) · [Usage](#usage) · [Examples](#examples) · [Model Tools](#model-tools) · [Command Timeout & Recovery](#command-timeout--recovery) · [Compatibility](#compatibility) · [Troubleshooting](#troubleshooting) · [How It Works](#how-it-works) · [Caching & Consistency](#caching--consistency) · [License](#license)
+
 ## Features
 
 | Feature | Description |
@@ -31,20 +33,107 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 
 ## Installation
 
+**Prerequisites**
+
+| Item | Requirement |
+| --- | --- |
+| DSH | ≥ 0.1.5-rc.1 (on the 0.1.2 stable line, use the v0.18.1-era plugin release) |
+| dsh-better-sidebar | ≥ 0.15 (this plugin uses its `/sidebar/api/fs.*` file API) |
+| Local SSH client | Windows: built-in OpenSSH (`%SystemRoot%\System32\OpenSSH\ssh.exe`); Linux/macOS: openssh-client |
+| Remote host | Any standard sshd (HPC / server / bastion) |
+
+**One command** (no token, API key or extra configuration needed):
+
+```bash
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.4
+```
+
+**Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
+
+Uninstall:
+
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
+dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 ```
 
-> **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.19.0** and **DSH 0.1.5-rc.1** (host services / settings / tools / slots / upload & download interception all compatible).
+> ⚠️ **dsh-better-sidebar compatibility (measured 2026-09)**: `0.18.1 / 0.19.0 / 0.19.1` cannot load their host half on DSH Desktop v2.0.9 (DSH 0.1.5-rc.1) — they value-import `SessionLogOffset`, which the desktop module surface exposes only as a type — so the sidebar Files tab falls back to "Nothing here can view this kind of content yet." Use **0.18.0** or a build carrying the fix; this plugin supports both contracts (4 endpoints on 0.18, 6 including `fs.rename`/`fs.remove` on 0.19).
 
 ## 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)
+**Three steps**
+
+1. **Settings → Remote SSH** → Add a connection (host / port / user / key) → Click "Test Connection"; an existing `~/.ssh/config` can be imported in one click
+2. **Add Workspace** → Choose "Select Remote Directory…" → Pick a connection → Browse and select a remote directory (it becomes a native DSH workspace)
+3. Inside that workspace session: the built-in **Files** tab shows remote files (edits save straight back to remote), and the **Terminal** tab auto-SSHes to the host (key auth only)
+
+**Just ask the model** (connection params are auto-filled inside a remote-workspace session):
+
+```text
+What's inside /home/user/project? Then fix line 20 of train.py
+Run squeue -u $USER and summarise the queue as a table
+Grep every ERROR line from the *.log files in this directory
+```
+
+## Examples
+
+**1 · Run a remote command** (`remote_ssh_exec`, 120s timeout by default):
+
+```json
+{
+  "command": "sinfo -h -o '%P %a %D %t %N' | head -20",
+  "timeoutMs": 30000
+}
+```
+
+Returns `{ ok, exitCode, stdout, stderr, error, truncated, isTimeout }` — e.g.
+
+```json
+{ "ok": true, "exitCode": 0, "stdout": "cpu* up 12 idle 8 ...\n", "stderr": "", "error": "", "truncated": false, "isTimeout": false }
+```
+
+**2 · Read / write files (no sync needed)**:
+
+```json
+{ "path": "~/project/config.yaml", "content": "lr: 0.001\nepochs: 50\n" }
+```
+
+```json
+{ "path": "~/project/train.py" }
+```
+
+`remote_ssh_cat` transfers base64 (binary-safe); `remote_ssh_write` is atomic (temp file + rename).
+
+**3 · Long jobs and hung-command recovery**:
+
+```json
+{ "command": "cd ~/project && bash run_train.sh", "timeoutMs": 0 }
+```
+
+```json
+{ "all": true }
+```
+
+`timeoutMs: 0` disables the timeout for that call; `DSH_REMOTE_SSH_CMD_TIMEOUT_MS=600000` changes the global default. Timed-out pooled sessions are discarded and rebuilt, and `remote_ssh_kill` is the manual hatch.
+
+**4 · Tool calls inside a remote workspace** (`profileId` omitted, relative paths resolve against the remote root):
+
+```json
+{ "path": "configs/exp1.yaml" }
+```
+
+**5 · Import connections from `~/.ssh/config`**: Settings → Remote SSH → "Import SSH config" → tick hosts → host / user / port / keyPath / ProxyJump are filled in.
+
+**6 · Mirror sync and push-back** (review offline, then upload in one shot):
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+```json
+{ "workspaceId": "w_xxx" }
+```
+
+`remote_ssh_sync` pulls the remote tree into the local mirror; `remote_ssh_push` sends mirror changes back (tar over ssh, batched).
 
 ## Model Tools
 
@@ -75,9 +164,35 @@ All SSH commands default to a **120-second** timeout (issue #5): a hung remote c
 - **Manual hatch**: `remote_ssh_kill` (or `all: true`) force-closes one or all pooled sessions at any time;
 - Timed-out commands are **never auto-retried** (retrying a hung command just hangs again) — the model decides whether to kill the session or retry differently.
 
+## Compatibility
+
+**Measured matrix** (2026-09-12, all verified on real machines):
+
+| Component | Version | Status |
+| --- | --- | --- |
+| DSH | 0.1.5-rc.1 (DSH Desktop v2.0.9) | ✅ host services / settings / tools / slots / upload & download interception all compatible |
+| DSH | 0.1.2-rc.1 stable line | ✅ (the 2.3.x-era baseline) |
+| dsh-better-sidebar | 0.15.0 – 0.18.0 | ✅ `fs.tree/read/write/search` (4-endpoint contract) |
+| dsh-better-sidebar | 0.19.x | ⚠️ this plugin already supports the 6-endpoint contract (incl. `fs.rename`/`fs.remove`); 0.19.0/0.19.1 themselves cannot load their host half on DSH Desktop until upstream fixes it (see the warning under [Installation](#installation)) |
+| Remote sshd | standard OpenSSH (Linux / HPC / Windows) | ✅ key auth; password auth needs `sshpass` on the host (POSIX) |
+
+The plugin never patches DSH sources or injects into the profile dependency tree — everything mounts through the official `cordis.patch.yml` + profile mechanism.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| "Test Connection" reports `Permission denied (publickey)` | ① key has a **passphrase**: the plugin runs in batch mode (`BatchMode=yes`) and cannot prompt — load it with `ssh-add` first, or strip the passphrase; ② on a Windows host where the user is in Administrators, the public key must go to `C:\ProgramData\ssh\administrators_authorized_keys`; ③ the username spelling (`user` / `.\user` / `user@domain`) must match a manual connection |
+| Key auth fails after launching `dsh web` from git-bash | Fixed in 2.3.9: on Windows the ssh binary is pinned to the system OpenSSH absolute path (previously Git's MSYS2 ssh was picked up) |
+| Sidebar Files tab says "Nothing here can view this kind of content yet." | `dsh-better-sidebar` host half failed to load: 0.18.1 / 0.19.0 / 0.19.1 hit the `SessionLogOffset` runtime import on DSH Desktop — downgrade to 0.18.0 or use a fixed build (upstream PR [#641](https://github.com/omdsh-dev/DSH-better-sidebar/pull/641)) |
+| Built-in Terminal tab cannot connect | The terminal is an `ssh -tt` interactive channel and supports **key auth only**; use the Files tab and the model tools for password auth |
+| Install fails with `minimumReleaseAge` or "No matching version" right after a release | npm supply-chain freshness policy — retry after 1–5 minutes |
+| A command hangs forever | The 120s timeout discards the pooled session automatically; use `timeoutMs: 0` for long jobs and `remote_ssh_kill` at any time |
+| Large files are truncated | 4MB per read, ≈6.29MB on the pooled download path (larger files fall back to a one-shot connection); use `remote_ssh_exec` with `head`/`tail` to page through |
+
 ## 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.
+The plugin registers 6 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.write`, `fs.search`, plus `fs.rename` and `fs.remove` added by better-sidebar 0.19) 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).
 
@@ -101,6 +216,14 @@ May it connect us as closely as it connects to distant supercomputers. Happy Qix
 
 —— August 18, 2026
 
+## Changelog
+
+Version history and per-release details live in [CHANGELOG.md](./CHANGELOG.md) (latest: 2.4.3 better-sidebar 0.19 endpoints, 2.4.2 settings icon flash, 2.4.0 command-level timeout + `remote_ssh_kill`).
+
 ## License
 
 [MIT](./LICENSE)
+
+---
+
+If this plugin helps you, a ⭐ [star on GitHub](https://github.com/ZhangFengshun/dsh-remote-ssh) or a favourite on [DSH Market](https://dshmarket.com) helps more people who work on remote supercomputers find it.

package/lib/index.js

@@ -10,10 +10,10 @@
  */
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { mkdir, rm, writeFile, readFile, opendir, stat, open, rename, readdir } from "node:fs/promises";
+import { mkdir, rm, writeFile, readFile, opendir, stat, open, rename, readdir, lstat } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { join, dirname, basename } from "node:path";
 
 /** Plugin identity for cordis.yml rows. */
 const name = "@zhangfengshun/dsh-remote-ssh";
@@ -2139,6 +2139,28 @@ function apply(ctx, config) {
     return { ok: true };
   }
 
+  // 本地 rename（对齐 better-sidebar 0.19 的 fs.rename 契约：单段名、不覆盖、返回新绝对路径）
+  async function localRenameEntry(path, name) {
+    if (!path) return { ok: false, error: "path 为必填项" };
+    if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+      return { ok: false, error: "name 必须是单个路径段" };
+    }
+    if (basename(path) === name) return { ok: true, path: path };
+    const dest = join(dirname(path), name);
+    if (existsSync(dest)) return { ok: false, error: "\"" + name + "\" 已存在" };
+    await rename(path, dest);
+    return { ok: true, path: dest };
+  }
+
+  // 本地 remove（文件 unlink / 目录递归；lstat 判定，符号链接只删链接本身）
+  async function localRemoveEntry(path) {
+    if (!path) return { ok: false, error: "path 为必填项" };
+    const st = await lstat(path);
+    if (st.isDirectory()) await rm(path, { recursive: true, force: true });
+    else await rm(path, { force: true });
+    return { ok: true, path: path };
+  }
+
   // 本地 searchFiles（简单递归文件名搜索）
   async function localSearchFiles(root, query) {
     if (!query) return { entries: [] };
@@ -2247,6 +2269,46 @@ function apply(ctx, config) {
           result = { entries: (r.files || []).map(function (f) {
             return { path: join(remoteBase, f), isDir: false };
           }), truncated: !!r.truncated };
+        } else if (method === "fs.rename") {
+          // better-sidebar 0.19 新增端点：重命名必须落在远端，绝不能让本地镜像目录被改。
+          const localPath = payload.path || "";
+          const name = String(payload.name || "");
+          if (!localPath) { writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "path is required" } }); return; }
+          if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+            writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "name must be a single path segment" } }); return;
+          }
+          const srcRemote = localToRemote(localPath, remoteBase, remoteInfo.remotePath);
+          if (srcRemote === remoteInfo.remotePath) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: "cannot rename the workspace root" } }); return;
+          }
+          const dstRemote = posixDirname(srcRemote) + "/" + name;
+          const exists = await runPooled(profile, "test -e " + shellQuotePath(dstRemote), undefined, 4096);
+          if (exists.ok) {
+            writeJson(res, 409, { ok: false, error: { code: "fs-error", message: "\"" + name + "\" already exists" } }); return;
+          }
+          const mv = await runPooled(profile, "mv -f -- " + shellQuotePath(srcRemote) + " " + shellQuotePath(dstRemote), undefined, 4096);
+          if (!mv.ok) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: String(mv.stderr || mv.error || "rename failed").trim().slice(0, 500) } }); return;
+          }
+          invalidateRemoteCaches(profile, srcRemote, { subtree: true });
+          invalidateRemoteCaches(profile, dstRemote, { subtree: true });
+          result = { path: join(dirname(localPath), name) };
+        } else if (method === "fs.remove") {
+          // better-sidebar 0.19 新增端点：删除同样必须在远端执行（本地镜像仅供注册工作区）。
+          const localPath = payload.path || "";
+          if (!localPath) { writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "path is required" } }); return; }
+          const srcRemote = localToRemote(localPath, remoteBase, remoteInfo.remotePath);
+          if (srcRemote === remoteInfo.remotePath) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: "cannot remove the workspace root" } }); return;
+          }
+          const rmv = await runPooled(profile, "rm -rf -- " + shellQuotePath(srcRemote), undefined, 4096);
+          if (!rmv.ok) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: String(rmv.stderr || rmv.error || "remove failed").trim().slice(0, 500) } }); return;
+          }
+          // 本地镜像若有同名副本一并清理（镜像不是事实来源，失败可忽略）。
+          try { await rm(localPath, { recursive: true, force: true }); } catch (e) {}
+          invalidateRemoteCaches(profile, srcRemote, { subtree: true });
+          result = { path: localPath };
         } else {
           writeJson(res, 404, { ok: false, error: { code: "not-found", message: "unknown method " + method } }); return;
         }
@@ -2261,6 +2323,10 @@ function apply(ctx, config) {
           result = await localWriteFile(payload.path, payload.content || "");
         } else if (method === "fs.search") {
           result = await localSearchFiles(sessionCwd, payload.query || "");
+        } else if (method === "fs.rename") {
+          result = await localRenameEntry(payload.path, String(payload.name || ""));
+        } else if (method === "fs.remove") {
+          result = await localRemoveEntry(payload.path);
         } else {
           writeJson(res, 404, { ok: false, error: { code: "not-found", message: "unknown method " + method } }); return;
         }
@@ -2275,7 +2341,9 @@ function apply(ctx, config) {
     }
   }
 
-  ["fs.tree", "fs.read", "fs.write", "fs.search"].forEach(function (m) {
+  // fs.rename / fs.remove 是 better-sidebar 0.19 新增端点：旧版客户端不会调用，
+  // 注册它们对旧版无副作用；新版下远程工作区的重命名/删除才不会落到本地镜像。
+  ["fs.tree", "fs.read", "fs.write", "fs.search", "fs.rename", "fs.remove"].forEach(function (m) {
     ctx.effect(() => ctx.webServer.register({
       kind: "exact",
       path: "/sidebar/api/" + m,

package/package.json

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