@zhangfengshun/dsh-remote-ssh 2.4.3 → 2.4.5

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.5] — 集成终端落在工作区远程目录（issue #7）+ 密码认证回退提示
+### 修复
+- **「终端」页签现在落在工作区对应的远程目录**（感谢 @Linhaojing 的完整定位与验证矩阵）：此前生成的 `dsh-remote-shell.js` 只拼 host/user/port/keyPath/proxyJump，`ssh -tt` 不带远程命令，交互式 shell 落在远程 `$HOME`；同一会话里出现「文件树在工作区目录、终端在 $HOME」的割裂。现在 wrapper 读取标记文件里**已有的** `remotePath` 并追加远程命令：
+  - `~`/`~/x` 的展开交给**远端** shell（`$HOME/...`）——本地 homedir 与远程不同，本地展开必错；
+  - `cd … 2>/dev/null || cd "$HOME"`：目标目录被删/改名时回退，终端仍可打开；
+  - `exec "${SHELL:-/bin/bash}" -l`：尊重远端登录 shell（zsh/fish 等），保持单进程与退出码语义；
+  - 无 `remotePath` 的旧标记文件不追加命令，行为与 2.4.5 之前完全一致（向后兼容）。
+- **密码认证的远程工作区现在会明确提示**：集成终端仅支持密钥认证，此前静默回退为本地 shell，用户会误以为已连上远程；现在向 stderr 打印中英双语提示（本地工作区与密钥认证路径不受影响）。
+
+### 测试
+- 新增 `tests/wrapper-terminal.test.mjs`：从 `lib/index.js` 提取**真实**的 wrapper 生成文本，用 CJS runner 桩掉 `child_process` 后捕获实际 spawn argv，覆盖 5 组场景（`~/子路径`、`~`、绝对路径、无 remotePath、非密钥认证）共 16 条断言。
+
+## [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，不存在该问题）。现在：

package/README.md

@@ -4,13 +4,15 @@
 
 类 **VSCode Remote-SSH** 的 **DSH** 插件：通过 SSH 连接远程超算 / 服务器，在 DSH 内置「文件」「终端」页签中直接操作远程文件和终端。
 
+**目录**：[功能](#功能) · [截图](#截图) · [安装](#安装) · [使用](#使用) · [代码示例](#代码示例) · [模型工具](#模型工具) · [命令超时与恢复](#命令超时与恢复) · [兼容性](#兼容性) · [故障排查](#故障排查) · [原理](#原理) · [缓存与一致性](#缓存与一致性) · [许可证](#许可证)
+
 ## 功能
 
 | 能力 | 说明 |
 | --- | --- |
 | 🔌 SSH 连接 | 密钥 / 密码认证，ProxyJump 跳板机，`~/.ssh/config` 一键导入 |
 | 📂 远程文件 | 内置「文件」页签直接 SSH 读写远程文件，无需同步 |
-| 💻 远程终端 | 内置「终端」页签自动检测远程工作区，SSH 交互式终端 |
+| 💻 远程终端 | 内置「终端」页签自动检测远程工作区，SSH 交互式终端，**落在工作区对应的远程目录**（与 VSCode Remote-SSH 一致） |
 | 🌐 远程工作区 | 选择远程目录创建原生工作区，一键进入远程环境 |
 | 🤖 模型工具 | 13 个 `remote_ssh_*` 工具，会话感知免填连接参数；命令级超时 + `remote_ssh_kill` 兜底恢复 |
 | ⚡ 打开提速 | 单往返合并读 + raw 文本快路径 + 结果缓存（LRU + 5s TTL）：首开 ≈**1.31×**，TTL 内重复打开 **0 往返**，过期复验 **≈5×**（真实超算实测）；`remote_ssh_exec` 连接复用 **≈15×** |
@@ -31,22 +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.5
+```
+
+安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
+
+卸载：
+
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.3
+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.*` 端点），请勿使用更早版本。
->
-> ⚠️ **版本兼容性（2026-09 实测）**：`dsh-better-sidebar` **0.18.1 / 0.19.0 / 0.19.1** 在 DSH Desktop v2.0.9（DSH 0.1.5-rc.1）上**主机半边无法加载**——它们以值方式导入 `SessionLogOffset`，而当前 DSH 面向插件的模块面只提供该类型声明，导入直接抛错，导致侧边栏文件页签显示「这类内容还没有可用的查看方式。」。请使用 **0.18.0**（本插件已逐点验证）直到上游修复；本插件对 0.18（4 端点）与 0.19（6 端点，含 `fs.rename`/`fs.remove`）两套契约均已适配。
+> ⚠️ **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，批量高效）。
 
 ## 模型工具
 
@@ -77,6 +164,33 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.3
 - **手动兜底**：`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` 交互式通道，**仅支持密钥认证**；密码认证的连接会回退为本地 shell 并打印一行提示（避免把本地 shell 误认为已连上远程），密码认证请改用「文件」页签与模型工具 |
+| 终端落在远程 `$HOME` 而不是工作区目录 | 2.4.5 起已修复（wrapper 会 `cd` 到工作区 `remotePath`，目录不存在时回退 `$HOME`）；若仍停在 `$HOME`，确认 2.4.5 已装入并重启 DSH |
+| 安装时提示 `minimumReleaseAge` 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
+| 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 `timeoutMs: 0`，随时可用 `remote_ssh_kill` 强杀 |
+| 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 `remote_ssh_exec` + `head`/`tail` 分段处理 |
+
 ## 原理
 
 插件注册 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 自动转换为远程路径——对客户端完全透明。
@@ -103,6 +217,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,13 +4,15 @@ 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 |
 | --- | --- |
 | 🔌 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 Terminal | Built-in **Terminal** tab auto-detects remote workspaces, opens an SSH interactive shell **in the workspace's remote directory** (like VSCode Remote-SSH) |
 | 🌐 Remote Workspace | Select a remote directory to create a native workspace, one-click enter |
 | 🤖 Model Tools | 13 `remote_ssh_*` tools, session-aware with auto-filled connection params; command-level timeout + `remote_ssh_kill` recovery |
 | ⚡ 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×** |
@@ -31,22 +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.5
+```
+
+**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.3
+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.
->
-> ⚠️ **Version compatibility (measured 2026-09)**: `dsh-better-sidebar` **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 current DSH plugin-facing module surface exposes only as a type, so the import throws and the sidebar Files tab falls back to "Nothing here can view this kind of content yet." Use **0.18.0** (verified point-by-point) until upstream fixes it; this plugin supports both contracts (4 endpoints on 0.18, 6 including `fs.rename`/`fs.remove` on 0.19).
+> ⚠️ **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 **into the workspace's remote directory** (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
 
@@ -77,6 +164,33 @@ 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**; password-auth profiles fall back to a local shell and now print a one-line notice (so a local shell is not mistaken for a remote one) — use the Files tab and the model tools for password auth |
+| Terminal opens in the remote `$HOME` instead of the workspace directory | Fixed in 2.4.5 (the wrapper `cd`s into the workspace `remotePath`, falling back to `$HOME` when it no longer exists); if it still starts in `$HOME`, make sure 2.4.5 is installed and DSH restarted |
+| 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 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.
@@ -103,6 +217,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

@@ -1947,8 +1947,9 @@ function apply(ctx, config) {
   });
 
   // ---- 创建 shell wrapper（供 better-sidebar 的 shell 配置指向它，实现远程终端透明接入）----
-  // wrapper 逻辑：读取当前工作目录下的 .remote-ssh.json，若存在且含 keyPath → exec ssh -tt；
-  // 否则降级到平台默认 shell（bash -l / powershell）。
+  // wrapper 逻辑：读取当前工作目录下的 .remote-ssh.json，若存在且含 keyPath → exec ssh -tt
+  // （并把终端 cd 到该工作区的 remotePath，与 VSCode Remote-SSH 行为一致）；
+  // 否则降级到平台默认 shell（bash -l / powershell）——远程工作区但非密钥认证时打一行提示。
   // 实现方式：跨平台 Node.js 脚本 + 平台特定的薄壳调用它。
   const wrapperDir = join(homedir(), ".dsh", "remote-ssh");
   const isWin = process.platform === "win32";
@@ -1971,10 +1972,23 @@ function apply(ctx, config) {
     "      // ExitOnForwardFailure=no：ssh config 里的 RemoteForward 端口被占时终端仍能打开",
     "      const args = ['-tt', '-o', 'StrictHostKeyChecking=no', '-o', 'ExitOnForwardFailure=no', '-p', String(port), '-i', j.keyPath, j.user + '@' + j.host];",
     "      if (j.proxyJump) { args.splice(2, 0, '-J', j.proxyJump); }",
+    "      // 终端落在工作区对应的远程目录（issue #7：此前不带远程命令，落点是远程 $HOME）。",
+    "      // remotePath 的 ~ 必须交给【远端】shell 展开——本地 homedir 与远程不同，本地展开必错；",
+    "      // cd 失败（目录被删/改名）回退 $HOME，保证终端仍能打开；",
+    "      // exec 让远端只留一个交互式登录 shell，退出码语义与之前一致。",
+    "      const remotePath = typeof j.remotePath === 'string' ? j.remotePath.trim() : '';",
+    "      if (remotePath !== '') {",
+    "        const expanded = remotePath === '~' ? '$HOME' : (remotePath.indexOf('~/') === 0 ? '$HOME/' + remotePath.slice(2) : remotePath);",
+    "        args.push('cd \"' + expanded + '\" 2>/dev/null || cd \"$HOME\"; exec \"${SHELL:-/bin/bash}\" -l');",
+    "      }",
     "      const ssh = spawn(sshBin, args, { stdio: 'inherit' });",
     "      ssh.on('exit', function(c) { process.exit(c == null ? 0 : c); });",
     "      return;",
     "    }",
+    "    // 远程工作区但该连接不是密钥认证（如密码认证，keyPath 为空）：集成终端仅支持",
+    "    // 密钥认证，这里显式提示一行，避免用户把本地 shell 误认为已连上远程。",
+    "    process.stderr.write('[dsh-remote-ssh] 检测到远程工作区，但该连接不是密钥认证：集成终端仅支持密钥认证，已回退为本地 shell。\\n');",
+    "    process.stderr.write('[dsh-remote-ssh] remote workspace detected, but this profile is not key-authenticated; the integrated terminal only supports key auth and fell back to a local shell.\\n');",
     "  }",
     "} catch (e) {}",
     "// 默认本地 shell",

package/package.json

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