dsh-ssh-tunnel 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -10,6 +10,64 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-10-09
+
+### 变更
+
+- **客户端面板改挂 DSH 官方右侧栏。** 标签页类型经 `sidebarRightTabs.register` 注册，正文与标题分别占用官方槽位 `sidebar.right.pane.tab` 与 `sidebar.right.pane.tab.title`；引导页入口框由 `guide` 条目渲染（order 44）。注册不再经由第三方侧栏宿主插件：`dsh-better-sidebar` 的 peer、`dsh.client.inject` 条目与 keywords 一并移除。
+- **客户端不再传项目 cwd 提示。** `getProjectContext` 只带 `sessionId`，项目路径由宿主从会话头（`ctx.sessions.get(sessionId).header.cwd`）解析；随之删除宿主注入的 `scope.sessionId` / `scope.cwd` 等字段，会话 id 改取官方席位平铺注入的 `sessionId`。
+- **DSH 兼容下限抬到 0.2.0-rc.2。** `engines.dsh` 与 `@deepseek-ai/dsh-client-locale` peer 收敛为单段 `>=0.2.0-rc.2 <0.3.0-0`，并新增同区间的 `@deepseek-ai/dsh-client-ui-sidebar-right` peer。
+- **官方右侧栏的标签页不自动常驻。** 用户从标签条「+」的引导页入口打开面板；布局按会话持久化，新会话第一次需各开一次。
+
+### Changed
+
+- **The client panel is mounted on the official DSH right sidebar.** The tab type registers through `sidebarRightTabs.register`, and the body and title take the official seats `sidebar.right.pane.tab` and `sidebar.right.pane.tab.title`; the guide-page entry box renders from the `guide` entry (order 44). Registration no longer goes through a third-party sidebar host plugin: the `dsh-better-sidebar` peer, its `dsh.client.inject` entry and its keywords are removed.
+- **The client no longer sends a project cwd hint.** `getProjectContext` carries only `sessionId`, and the host resolves the project path from the session header (`ctx.sessions.get(sessionId).header.cwd`); the host-injected `scope.sessionId` / `scope.cwd` fields go away, and the session id now comes from the flat `sessionId` prop the official seat injects.
+- **The DSH compatibility floor moves to 0.2.0-rc.2.** `engines.dsh` and the `@deepseek-ai/dsh-client-locale` peer collapse into the single segment `>=0.2.0-rc.2 <0.3.0-0`, and a new `@deepseek-ai/dsh-client-ui-sidebar-right` peer declares the same range.
+- **The official right-sidebar tab is not resident by default.** Users open the panel from the "+" guide page in the tab strip; layout persists per session, so each new session needs one open.
+
+## [1.0.2] - 2026-10-08
+
+### 新增
+
+- **交互式输出读取采用 seq 游标协议。** 侧栏轮询接口 `shellRead` 的响应带 `chunk` / `since` / `seq` / `baseSeq` / `dropped` / `chunkTruncated`：客户端携带上次读到的 `since`，宿主返回其后的新增输出；环形缓冲（512 KiB）淘汰后 `baseSeq` 前移且 `dropped: true`，客户端据此全量重取，避免缓冲滚动造成输出缺口。单次响应的 `chunk` 上限 256 KiB。
+- **API 错误返回结构化错误码。** 错误响应体带 `code` 字段，并按语义映射 HTTP 状态：`bad_request` 400、`forbidden` 403、`not_found` 404、`conflict` 409、`gone` 410、`payload_too_large` 413；未映射的错误保持 500。
+- **主机密钥确认提示有时效与上限。** 待确认提示 5 分钟过期，至多保留 50 条（超出时淘汰最旧），按项目隔离。
+
+### 变更
+
+- **安装脚本以 `--profile` 为必填参数。** `scripts/install.sh` 与 `scripts/install.ps1`：目标 profile 必填且无默认值，缺失或不存在的 profile 报错并列出实存 profile（退出码 2）。`--fix-profile` / `-FixProfile` 为可选开关：仅在该开关下补写 profile `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`（幂等）并清理 profile `cordis.patch.yml` 里旧版写入的手动挂载，写入后回读断言，失败回滚并以非零码退出。bash 试运行为 `--dry-run`，PowerShell 为 `-DryRun`。`PATH` 缺少 `dsh` 命令时的 `npx` 兜底先打印将执行的命令并要求确认（`DSH_INSTALL_YES=1` 跳过）。安装后读取 profile 的 `ignoredBuilds`，发现条目时打印 `allowBuilds` 豁免指引。`scripts/sync-to-dsh.sh` 支持 `--dry-run`。
+- **兼容区间按预发布线拆段。** `engines.dsh` 与 `@deepseek-ai/dsh-client-locale` peer 声明为 `>=0.1.7-rc.2 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0`，0.1.7 线与 0.2 线各占一段。
+- **exec 结果如实结算。** 返回值带 `exitKnown` / `code` / `signal` / `connectionDropped`：正常退出 `exitKnown: true` 且 `code` 为退出码；按信号终止时 `signal` 为信号名；连接被切断时 `code` 为 `null` 且 `connectionDropped: true`。
+- **`max_bytes` 按字节钳制。** exec 与 `sftp_read_text` 的输出上限钳制在 1024–1048576 字节（默认 exec 262144、`sftp_read_text` 524288），输出按字节截断并在结果中置 `truncated: true`。
+- **客户端注入清单补齐到达顺序边。** `dsh.client.inject` 增加 `dsh-better-sidebar`；`exports` 放行 `./cordis.patch.yml`；`files` 放行 `scripts/lib/*.cjs`（安装脚本共享逻辑）。
+- **键盘交互式认证不支持。** 该类主机在连接、重连与 `SSHManager` 中被拒绝（`credential=unsupported`），提示改用密码或私钥。
+- **文档更新。** 安全章节改为客观口径（本机回环、无鉴权 token、本机进程视为已授权用户）、补 seq 游标协议与超时/上限声明、0700/0600 加 POSIX 平台限定。
+
+### 安全
+
+- **授权检查全程 fail-closed。** 建立连接前必须已有该项目授权；写类操作在发起前与结果回报前各复检一次；授权撤销即时生效——受影响的存活会话被关闭、在飞输出被丢弃并以 `not authorized` 失败、下载中的本地文件被删除。本地工作区根取不到时拒绝操作，可用环境变量 `DSH_SSH_TUNNEL_WORKSPACE_ROOT` 显式指定。
+
+### Added
+
+- **Interactive output is read through a seq cursor protocol.** The sidebar polling API `shellRead` returns `chunk` / `since` / `seq` / `baseSeq` / `dropped` / `chunkTruncated`: the client sends the last `since` it has seen and the host returns the newer output; ring-buffer eviction (512 KiB) moves `baseSeq` forward and sets `dropped: true`, telling the client to refetch in full, which prevents output gaps from buffer rollover. A single response caps `chunk` at 256 KiB.
+- **API errors carry structured codes.** Error response bodies include a `code` field mapped to HTTP statuses by meaning: `bad_request` 400, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413; unmapped errors stay 500.
+- **Host key confirmation prompts have a lifetime and a cap.** Pending prompts expire after 5 minutes, at most 50 are kept (oldest evicted beyond that), and they are isolated per project.
+
+### Changed
+
+- **The install scripts require `--profile`.** `scripts/install.sh` and `scripts/install.ps1`: the target profile is required with no default; a missing or nonexistent profile fails with a list of the profiles that do exist (exit code 2). `--fix-profile` / `-FixProfile` is an optional switch: only with it does the script add the plugin to the profile's `pnpm-workspace.yaml` (`minimumReleaseAgeExclude`, idempotent) and remove the hand-written mount older versions put into the profile's `cordis.patch.yml`; writes are read back and asserted, and a failure rolls the change back and exits non-zero. The bash dry-run flag is `--dry-run`, the PowerShell one is `-DryRun`. When `dsh` is missing from `PATH`, the `npx` fallback prints the command it is about to execute and asks for confirmation (`DSH_INSTALL_YES=1` skips it). After installing, the script reads the profile's `ignoredBuilds` and prints an `allowBuilds` exemption recipe when entries are found. `scripts/sync-to-dsh.sh` supports `--dry-run`.
+- **The compatibility range is split per prerelease line.** `engines.dsh` and the `@deepseek-ai/dsh-client-locale` peer declare `>=0.1.7-rc.2 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0` — the 0.1.7 line and the 0.2 line each get their own segment.
+- **exec results are settled faithfully.** Results carry `exitKnown` / `code` / `signal` / `connectionDropped`: a normal exit sets `exitKnown: true` with the exit code in `code`; a signal death returns the signal name in `signal`; a cut connection returns `code: null` with `connectionDropped: true`.
+- **`max_bytes` is clamped in bytes.** The output cap for exec and `sftp_read_text` is clamped to 1024–1048576 bytes (defaults: 262144 for exec, 524288 for `sftp_read_text`); output is truncated on byte boundaries and the result sets `truncated: true`.
+- **The client inject list completes the arrival-order edge.** `dsh.client.inject` adds `dsh-better-sidebar`; `exports` admits `./cordis.patch.yml`; `files` admits `scripts/lib/*.cjs` (installer shared logic).
+- **keyboard-interactive auth is not supported.** Such hosts are refused on connect, reconnect and in `SSHManager` (`credential=unsupported`) with a message to switch to password or private key.
+- **Documentation updates.** The security section states the trust boundary objectively (local loopback, no authentication token, local processes treated as authorized users), the seq cursor protocol and timeout/limit declarations are added, and the 0700/0600 statements carry a POSIX platform qualifier.
+
+### Security
+
+- **Authorization checks fail closed end to end.** Connecting requires an existing project grant; write operations re-check the grant once before being issued and once before the result is delivered; a revocation takes effect immediately — affected live sessions are closed, in-flight output is discarded and the call fails with `not authorized`, and a local file mid-download is deleted. Operations are refused when no local workspace root can be resolved; the environment variable `DSH_SSH_TUNNEL_WORKSPACE_ROOT` can set one explicitly.
+
 ## [1.0.1] - 2026-10-04
 
 ### 新增
@@ -317,3 +375,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Initial permanent plugin scaffold
+
+[1.0.2]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.6...v1.0.0
+[0.4.6]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.5...v0.4.6
+[0.4.5]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.3...v0.4.5
+[0.4.3]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.3.11...v0.4.0
+[0.3.11]: https://github.com/OMSociety/dsh-ssh-tunnel/compare/v0.3.7...v0.3.11
+[0.3.7]: https://github.com/OMSociety/dsh-ssh-tunnel/tree/v0.3.7

package/README.md

@@ -7,19 +7,19 @@
   <p>模型用 <strong>SSHManager</strong> 工具执行命令、传文件；你在侧栏管主机与授权。<strong>密钥不进模型上下文</strong>。</p>
 
   <p>
-    <a href="https://github.com/OMSociety/dsh-ssh-tunnel/releases"><img src="https://img.shields.io/github/v/tag/OMSociety/dsh-ssh-tunnel?label=version&color=4f6ef7" alt="Version"></a>
-    <a href="https://github.com/deepseek-ai/dsh"><img src="https://img.shields.io/badge/DSH-%3E%3D0.1.7--rc.2_%3C0.3.0--0-4f6ef7" alt="DSH"></a>
+    <a href="https://www.npmjs.com/package/dsh-ssh-tunnel"><img src="https://img.shields.io/npm/v/dsh-ssh-tunnel?label=version&color=4f6ef7" alt="Version"></a>
+    <img src="https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.2%20%3C0.3.0--0-4f6ef7" alt="DSH">
     <a href="LICENSE"><img src="https://img.shields.io/github/license/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="License"></a>
     <a href="https://github.com/OMSociety/dsh-ssh-tunnel/stargazers"><img src="https://img.shields.io/github/stars/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="Stars"></a>
     <a href="https://github.com/OMSociety/dsh-ssh-tunnel/issues"><img src="https://img.shields.io/github/issues/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="Issues"></a>
   </p>
 
-<a href="#这是什么">这是什么</a> • <a href="#核心特性">核心特性</a> • <a href="#快速开始">快速开始</a> • <a href="#侧栏">侧栏</a> • <a href="#模型工具">模型工具</a> • <a href="#安全">安全</a> • <a href="#开发">开发</a> • <a href="#许可证与作者">许可证与作者</a>
+<a href="#这是什么">这是什么</a> • <a href="#核心特性">核心特性</a> • <a href="#安装方式">安装方式</a> • <a href="#侧栏">侧栏</a> • <a href="#模型工具">模型工具</a> • <a href="#安全">安全</a> • <a href="#开发">开发</a> • <a href="#许可证与作者">许可证与作者</a>
 </div>
 
 ## 这是什么
 
-**dsh-ssh-tunnel** 是 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 的社区插件，挂在右侧栏宿主 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 上：把多台 SSH 主机收进一个**主机库**，按项目授权，然后在中央面板里开**交互式终端**（xterm）或**双栏 SFTP**。
+**DSH SSH Tunnel** 是 DeepSeek Harness 的社区插件，挂在 **DSH 官方右侧栏**的标签页上：把多台 SSH 主机收进一个**主机库**，按项目授权，然后在中央面板里开**交互式终端**（xterm）或**双栏 SFTP**。
 
 它**不会**把全局 `fs` / `subprocess` 换成一个远程盘：远端操作只发生在你显式调用的 `SSHManager` 工具与面板里，本地文件与远端文件始终是两侧分明的东西。
 
@@ -29,8 +29,6 @@
 
 **产品形态与部分 UX 参考开源项目 [LiveAgent](https://github.com/thirsty5034/LiveAgent)**（多机 SSH 主机库、按项目授权、侧栏隧道管理、中央终端 / SFTP 等）。
 
-本仓库是 **DSH 原生实现**（Cordis host/client、`dsh-better-sidebar` Tab、`SSHManager` 工具、DSH 本地密钥布局），**不是** LiveAgent 的 git fork，也**不**内嵌 LiveAgent 源码。对照设计时请遵守 LiveAgent 自身许可证。
-
 ## 核心特性
 
 | 特性 | 说明 |
@@ -44,39 +42,16 @@
 | **本地路径守卫** | 上传 / 下载 / 列举 / 删除的本机路径限制在**项目工作区根**内，词法 **与** realpath 双重校验 |
 | **界面双语** | 侧栏与面板随 DSH 界面语言在中文 / 英文间即时切换 |
 
-## 快速开始
-
-**方式一：从 npm 安装（推荐）**
-
-```powershell
-# 1) 先停掉 dsh web（运行中的服务会锁住依赖，装完再起）
-dsh plugin --profile web add "dsh-ssh-tunnel@1.0.1"
-# 2) 重新启动 dsh web
-```
-
-包已发布到 npm，随包提供预构建产物，本地不需要构建步骤；换版本就把 `@1.0.1` 换成目标版本。
-
-**方式二：从 GitHub 源安装**
-
-```powershell
-dsh plugin --profile web add "github:OMSociety/dsh-ssh-tunnel"
-```
-
-想复现某次安装就钉住 ref：在仓库地址后加 `#<tag 或提交 sha>`。
+## 安装方式
 
-**方式三：一键脚本**
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/OMSociety/dsh-ssh-tunnel/main/scripts/install.sh | bash
-```
+**从 npm 安装**
 
 ```powershell
-irm https://raw.githubusercontent.com/OMSociety/dsh-ssh-tunnel/main/scripts/install.ps1 | iex
+# 先停掉正在运行的 DSH（运行中的服务会锁住依赖，装完再起）
+dsh plugin --profile <profile> add "dsh-ssh-tunnel"
 ```
 
-脚本默认走 GitHub 源（`bash scripts/install.sh --from npm 1.0.1` 可切到 npm），除安装外还会把 profile 的 `minimumReleaseAgeExclude` 补上本插件、校验 `dsh.profile.bundles` 确实写入、清掉旧版手写在 profile `cordis.patch.yml` 里的挂载（先加 `--dry-run` 可只看计划不动手）。
-
-> **提示**：装好后**刷新一下浏览器页面**，右侧栏才会出现「SSH 隧道」入口——只重启宿主不够，客户端产物是页面加载时取的。
+> **提示**：装好后**刷新一下浏览器页面**，「SSH 隧道」入口才会出现在右侧栏——只重启宿主不够，客户端产物是页面加载时取的。
 
 **装完怎么用**
 
@@ -111,54 +86,57 @@ irm https://raw.githubusercontent.com/OMSociety/dsh-ssh-tunnel/main/scripts/inst
 | `read_session` / `send_input` / `resize_session` | 交互式会话的读取、输入与窗口尺寸 |
 
 - 会话策略：`reuse_or_create`（默认，会复活同主机已断开的会话）、`new`、`require_existing`，或显式传 `session_id`
-- `timeout_ms` 取值 1000–300000，作用于 exec / SFTP / shell；默认 exec 与 SFTP 元数据 30s，SFTP 传输 120s
+- 超时：默认 exec 30s、SFTP 元数据 30s、SFTP 传输 120s、shell 类操作（`read_session` / `send_input` / `resize_session`）10s；`timeout_ms` 可覆盖，取值钳制在 1000–300000，整次调用另有 300s 上限
+- `max_bytes`：exec 与 `sftp_read_text` 的单次输出上限，按字节钳制在 1024–1048576（默认 exec 262144 即 256 KiB、`sftp_read_text` 524288 即 512 KiB）；达到上限时结果带 `truncated: true` 且只含前 `max_bytes` 字节
+- exec 结算：结果带 `exitKnown` / `code` / `signal` / `connectionDropped`——正常退出 `exitKnown: true` 且 `code` 为退出码；按信号终止时返回 `signal`；连接被切断时 `code` 为 `null` 且 `connectionDropped: true`
+- 交互式输出的读取走 seq 游标协议（侧栏轮询的 `shellRead`）：客户端携带上次读到的 `since`，响应返回 `chunk` / `since` / `seq` / `baseSeq` / `dropped` / `chunkTruncated`；环形缓冲（512 KiB）淘汰后 `baseSeq` 前移且 `dropped: true`，客户端据此全量重取；单次响应的 `chunk` 上限 256 KiB
 - 认证方式只有**密码**或**私钥**；键盘交互式认证（含堡垒机网页 MFA）不支持
 
 ## 安全
 
+**信任边界（客观陈述）**：插件的 HTTP API 挂在 DSH 宿主的本地 web 服务上，只接受本机回环（`localhost` / `127.0.0.1` / `::1`）与配置的可信主机，并校验浏览器 `Origin`；API 没有鉴权 token——**能在本机访问该端口的进程都被视为已授权用户**，可以使用本插件的能力。会话 API 必须带 `projectPathKey`，跨项目不可见。
+
+授权与路径守卫动作清单：
+
+- **连接必须先授权**：未在「项目授权」里勾选的主机无法建立连接，Connect 不会自动写入授权
+- **授权撤销即时生效**：写类操作在发起前与结果回报前各复检一次授权；撤销后输出被丢弃并以 `not authorized` 失败，下载中的本地文件被删除，受影响的存活会话被关闭，重连拒绝复活已撤销主机
+- **本地路径守卫 fail-closed**：上传 / 下载 / 列举 / 建目录 / 删除 / 重命名的本机路径限制在**项目工作区根**内，词法 **与** realpath 双重校验，越界路径与指向工作区外的符号链接一律拒绝；工作区根取不到时直接拒绝操作（可用环境变量 `DSH_SSH_TUNNEL_WORKSPACE_ROOT` 显式指定）
 - 工具结果与列表 API 不返回 password / PEM / 口令
-- 本地上传、下载、列举、删除的路径限制在**项目工作区根**内（由宿主按当前会话工作区解析，不假设固定挂载点）：词法 **与** realpath 双重校验，越界路径与指向工作区外的符号链接一律拒绝
 - 主机密钥以 **SHA256 hex** 存入 `known_hosts.json`；首次连接或指纹变更时在侧栏确认（展示指纹）
-- HTTP API 限制在 loopback / trusted hosts；浏览器 `Origin` 必须匹配；会话 API 必须带 `projectPathKey`
 - 优先使用密钥登录；若 `secrets.json` 可能泄露请立即轮换凭据
-- 键盘交互式认证已下线：请把这类主机改为密码或私钥
+- 认证方式为密码或私钥
 
 ## 数据放在哪
 
-`$DSH_HOME/ssh-tunnel/`（目录 `0700`）：
+`$DSH_HOME/ssh-tunnel/`（目录权限 `0700`；此为 POSIX 系统行为——Windows 的 NTFS 权限由继承 ACL 决定，`chmod` 不改 DACL）：
 
-| 文件 | 内容 |
-|---|---|
-| `hosts.json` | 主机元数据（不含密钥明文） |
-| `secrets.json` | 密码 / PEM / 口令（`0600`） |
-| `grants.json` | `projectPathKey → hostIds[]` |
-| `known_hosts.json` | 已信任的主机密钥指纹 |
-
-## 界面国际化
-
-- 命名空间：`sshTunnel`；字典 `zh` / `en` 注册到 `ctx.locale`
-- Tab 标题与面板随 DSH 界面语言即时切换
-- 宿主侧 `SSHManager` 的描述保持英文（面向模型）
+| 文件 | 内容 | 权限（POSIX） |
+|---|---|---|
+| `hosts.json` | 主机元数据（不含密钥明文） | `0600` |
+| `secrets.json` | 密码 / PEM / 口令 | `0600` |
+| `grants.json` | `projectPathKey → hostIds[]` | `0600` |
+| `known_hosts.json` | 已信任的主机密钥指纹 | `0600` |
 
 ## 开发
 
-```powershell
-npm test                   # node --test：自检脚本全量回归
-npm run check              # 语法 + 自检
-bash scripts/sync-to-dsh.sh   # 以 link: 方式把本仓库接入 web profile（开发用）
-bash scripts/install.sh --dry-run   # 只看安装计划，不动 profile
+```sh
+npm test                            # 自检脚本全量回归（实际执行 node scripts/smoke-test.mjs）
+npm run check                       # 语法检查 + 自检
+node scripts/smoke-test.mjs         # 直接运行自检（离线设计，不起 SSH、不起 DSH 进程）
+bash scripts/sync-to-dsh.sh --dry-run                    # 预览 link: 接入命令；去掉 --dry-run 才会改写 profile
 node scripts/portal-probe.mjs       # 客户端 Tab 渲染探针（能解析到 react 时生效，否则明确跳过）
 ```
 
-目录与「改东西去哪」：
+项目目录：
 
 ```text
 lib/index.js            宿主入口：工具注册、/dsh-ssh-tunnel/api 路由、授权与路径守卫、xterm 资产下发
 lib/client.js           客户端 bundle（已入库；dsh plugin add 不做构建）
-lib/session.js          会话生命周期：连接、keepalive、掉线墓碑与自动重连
-lib/shared/             宿主与客户端共用纯函数：path / host-key / host-summary / http-trust / persist /
+lib/session.js          会话生命周期：连接、keepalive、掉线墓碑与自动重连、exec/SFTP 执行
+lib/shared/             宿主与客户端共用纯函数：path / args / host-key / host-summary / http-trust / persist /
                         session-auth / session-policy / shell-buffer / vendor
 scripts/                install.sh · install.ps1 · sync-to-dsh.sh · smoke-test.mjs · portal-probe.mjs
+scripts/lib/            安装链共享逻辑（.cjs，install.sh 与 install.ps1 共用）
 cordis.patch.yml        包内 bundle patch，CLI 据此写入 dsh.profile.bundles
 ```
 
@@ -170,11 +148,10 @@ cordis.patch.yml        包内 bundle patch，CLI 据此写入 dsh.profile.bundl
 
 - 如果这个插件对你有帮助，欢迎点亮 Star；有问题或建议请提 [Issue](https://github.com/OMSociety/dsh-ssh-tunnel/issues) 或 [Pull Request](https://github.com/OMSociety/dsh-ssh-tunnel/pulls)。
 - 变更记录见 [CHANGELOG](CHANGELOG.md)。
-- [LiveAgent](https://github.com/thirsty5034/LiveAgent)：产品形态与部分 UX 的参考来源（见上文「参考来源」）
-- [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)：右侧栏宿主与 Tab 契约
+- LiveAgent（[thirsty5034/LiveAgent](https://github.com/thirsty5034/LiveAgent)）：产品形态与部分 UX 的参考来源（见上文「参考来源」）
 - [dsh-git-forge](https://github.com/OMSociety/dsh-git-forge)：同门插件，Git 凭据与 push 策略
-- [DeepSeek Harness](https://github.com/deepseek-ai/dsh)：插件、工具与 agent shell 的宿主
+- DeepSeek Harness：插件、工具与 agent shell 的宿主
 
 ## 许可证与作者
 
-[MIT](LICENSE)。上游项目与代码作者 [@thirsty5034](https://github.com/thirsty5034)；本仓库的维护与新增部分 © 2026 [@OMSociety](https://github.com/OMSociety)。
+[MIT](LICENSE)。授权条款与版权归属以 LICENSE 为准；上游项目与代码作者 [@thirsty5034](https://github.com/thirsty5034)。

package/README_en.md

@@ -7,17 +7,18 @@
   <p>The model drives the <strong>SSHManager</strong> tool to run commands and move files; you manage hosts and grants in the sidebar. <strong>Secrets never enter model context</strong>.</p>
 
   <p>
-    <a href="https://github.com/OMSociety/dsh-ssh-tunnel/releases"><img src="https://img.shields.io/github/v/tag/OMSociety/dsh-ssh-tunnel?label=version&color=4f6ef7" alt="Version"></a>
-    <a href="https://github.com/deepseek-ai/dsh"><img src="https://img.shields.io/badge/DSH-%3E%3D0.1.7--rc.2_%3C0.3.0--0-4f6ef7" alt="DSH"></a>
+    <a href="https://www.npmjs.com/package/dsh-ssh-tunnel"><img src="https://img.shields.io/npm/v/dsh-ssh-tunnel?label=version&color=4f6ef7" alt="Version"></a>
+    <img src="https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.2%20%3C0.3.0--0-4f6ef7" alt="DSH">
     <a href="LICENSE"><img src="https://img.shields.io/github/license/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="License"></a>
     <a href="https://github.com/OMSociety/dsh-ssh-tunnel/stargazers"><img src="https://img.shields.io/github/stars/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="Stars"></a>
     <a href="https://github.com/OMSociety/dsh-ssh-tunnel/issues"><img src="https://img.shields.io/github/issues/OMSociety/dsh-ssh-tunnel?color=4f6ef7" alt="Issues"></a>
   </p>
+<a href="#what-this-is">What this is</a> • <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#sidebar">Sidebar</a> • <a href="#model-tool">Model tool</a> • <a href="#security">Security</a> • <a href="#development">Development</a> • <a href="#license-and-author">License and author</a>
 </div>
 
 ## What this is
 
-**dsh-ssh-tunnel** is a community plugin for [DeepSeek Harness](https://github.com/deepseek-ai/dsh), mounted in the sidebar host [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar). It collects your SSH hosts into one **host inventory**, authorizes them per project, and then opens an **interactive terminal** (xterm) or **dual-pane SFTP** in the center panel.
+**DSH SSH Tunnel** is a community plugin for DeepSeek Harness, mounted as a tab in the **official DSH right sidebar**. It collects your SSH hosts into one **host inventory**, authorizes them per project, and then opens an **interactive terminal** (xterm) or **dual-pane SFTP** in the center panel.
 
 It does **not** replace the global `fs` / `subprocess` with a remote disk: remote operations happen only in the `SSHManager` tool you call explicitly and inside the panel, and local and remote files remain two clearly separated sides.
 
@@ -27,8 +28,6 @@ Its companion plugin is [dsh-git-forge](https://github.com/OMSociety/dsh-git-for
 
 **The product shape and several UX patterns are informed by the open-source [LiveAgent](https://github.com/thirsty5034/LiveAgent)** (multi-host SSH inventory, project-scoped access, sidebar tunnel management, center terminal / SFTP surfaces).
 
-This package is a **DSH-native implementation** (Cordis host/client plugin, `dsh-better-sidebar` tab, `SSHManager` tool, DSH-local secret layout). It is **not** a git fork of LiveAgent and does **not** vendor LiveAgent sources. Consult LiveAgent under its own license when comparing designs.
-
 ## Features
 
 | Feature | Description |
@@ -42,38 +41,15 @@ This package is a **DSH-native implementation** (Cordis host/client plugin, `dsh
 | **Local path guard** | Local upload / download / list / delete paths are constrained to the **project workspace root**, with both lexical and realpath checks |
 | **Bilingual UI** | Sidebar and panel follow the DSH interface language between Chinese and English live |
 
-## Quick start
-
-**Option 1: install from npm (recommended)**
-
-```powershell
-# 1) stop dsh web first (a running server holds the dependency lock; start it again afterwards)
-dsh plugin --profile web add "dsh-ssh-tunnel@1.0.1"
-# 2) restart dsh web
-```
-
-The package is published to npm and ships the prebuilt artifacts, so no local build step is involved. Replace `@1.0.1` to install another version.
-
-**Option 2: install from the GitHub source**
-
-```powershell
-dsh plugin --profile web add "github:OMSociety/dsh-ssh-tunnel"
-```
-
-To reproduce a specific install, pin a ref by appending `#<tag or commit sha>` to the repository URL.
+## Installation
 
-**Option 3: one-line installer**
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/OMSociety/dsh-ssh-tunnel/main/scripts/install.sh | bash
-```
+**Install from npm**
 
 ```powershell
-irm https://raw.githubusercontent.com/OMSociety/dsh-ssh-tunnel/main/scripts/install.ps1 | iex
+# stop the running DSH first (a live service holds the dependency lock; start it again afterwards)
+dsh plugin --profile <profile> add "dsh-ssh-tunnel"
 ```
 
-The script installs from the GitHub source by default (`bash scripts/install.sh --from npm 1.0.1` switches to npm). Besides installing, it adds this plugin to the profile's `minimumReleaseAgeExclude`, verifies that `dsh.profile.bundles` really received the entry, and removes the mount older versions wrote by hand into the profile's `cordis.patch.yml`. Add `--dry-run` to print the plan without touching anything.
-
 > **Note**: After installing, **refresh the browser page** for the "SSH Tunnel" entry to appear in the sidebar — restarting the host alone is not enough, because the client artifact is fetched when the page loads.
 
 **First run**
@@ -109,42 +85,44 @@ One sidebar tab with three pages:
 | `read_session` / `send_input` / `resize_session` | Read, feed and resize an interactive session |
 
 - Session strategies: `reuse_or_create` (default; revives a disconnected session for that host), `new`, `require_existing`, or an explicit `session_id`
-- `timeout_ms` ranges from 1000 to 300000 and applies to exec / SFTP / shell; defaults are 30s for exec and SFTP metadata, 120s for SFTP transfers
+- Timeouts: exec 30s, SFTP metadata 30s, SFTP transfers 120s, shell operations (`read_session` / `send_input` / `resize_session`) 10s by default; `timeout_ms` overrides them, clamped to 1000–300000, with a 300s ceiling for the whole call
+- `max_bytes`: per-call output cap for exec and `sftp_read_text`, clamped to 1024–1048576 bytes (defaults: 262144 = 256 KiB for exec, 524288 = 512 KiB for `sftp_read_text`); when the cap is hit the result sets `truncated: true` and carries only the first `max_bytes` bytes
+- exec settlement: results carry `exitKnown` / `code` / `signal` / `connectionDropped` — a normal exit sets `exitKnown: true` with the exit code in `code`; a signal death returns `signal`; a cut connection returns `code: null` with `connectionDropped: true`
+- Interactive output is read through a seq cursor protocol (the sidebar polling API `shellRead`): the client sends the last `since` it has seen, and the response returns `chunk` / `since` / `seq` / `baseSeq` / `dropped` / `chunkTruncated`; ring-buffer eviction (512 KiB) moves `baseSeq` forward and sets `dropped: true`, telling the client to refetch in full; a single response caps `chunk` at 256 KiB
 - Authentication is **password** or **private key** only; keyboard-interactive (including bastion web MFA) is not supported
 
 ## Security
 
+**Trust boundary (stated as it is)**: the plugin's HTTP API is served by the DSH host's local web server and only accepts loopback (`localhost` / `127.0.0.1` / `::1`) plus configured trusted hosts, with the browser `Origin` checked; the API has no authentication token — **any local process that can reach the port is treated as an authorized user** and may use the plugin's capabilities. Session APIs require `projectPathKey` and are invisible across projects.
+
+Authorization and path-guard action list:
+
+- **Grant before connect**: a host that is not checked under Project access cannot be connected, and Connect never auto-writes grants
+- **Revocation takes effect immediately**: write operations re-check the grant once before being issued and once before the result is delivered; after a revocation the output is discarded and the call fails with `not authorized`, a local file mid-download is deleted, affected live sessions are closed, and reconnect refuses to resurrect the revoked host
+- **Local path guard fails closed**: local upload / download / list / mkdir / delete / rename paths are constrained to the **project workspace root**, with both lexical and realpath checks, and out-of-bounds paths or symlinks pointing outside the workspace are rejected; when no workspace root can be resolved the operation is refused (the environment variable `DSH_SSH_TUNNEL_WORKSPACE_ROOT` can set one explicitly)
 - Tool results and list APIs never return password / PEM / passphrase
-- Local upload, download, list and delete paths are constrained to the **project workspace root** (the host resolves it from the current session workspace rather than assuming a fixed mount point): both lexical and realpath checks apply, and out-of-bounds paths or symlinks pointing outside the workspace are rejected
 - Host keys are stored as **SHA256 hex** in `known_hosts.json`; the first connect or a fingerprint change is confirmed in the sidebar with the fingerprint shown
-- The HTTP API is fenced to loopback / trusted hosts; the browser `Origin` must match; session APIs require `projectPathKey`
 - Prefer key-based auth; rotate credentials immediately if `secrets.json` may have leaked
-- keyboard-interactive is retired: edit such hosts to password or private key
+- Authentication is password or private key
 
 ## Where data lives
 
-Under `$DSH_HOME/ssh-tunnel/` (directory mode `0700`):
+Under `$DSH_HOME/ssh-tunnel/` (directory mode `0700`; this is POSIX behavior — on Windows NTFS permissions come from inherited ACLs and `chmod` does not change the DACL):
 
-| File | Contents |
-|---|---|
-| `hosts.json` | Host metadata (no secret material) |
-| `secrets.json` | Passwords / PEM / passphrases (`0600`) |
-| `grants.json` | `projectPathKey → hostIds[]` |
-| `known_hosts.json` | Trusted host key fingerprints |
-
-## UI internationalization
-
-- Namespace: `sshTunnel`; dictionaries `zh` / `en` registered on `ctx.locale`
-- Tab title and panel follow the DSH interface language live
-- Host-side `SSHManager` strings stay English (model-facing)
+| File | Contents | Mode (POSIX) |
+|---|---|---|
+| `hosts.json` | Host metadata (no secret material) | `0600` |
+| `secrets.json` | Passwords / PEM / passphrases | `0600` |
+| `grants.json` | `projectPathKey → hostIds[]` | `0600` |
+| `known_hosts.json` | Trusted host key fingerprints | `0600` |
 
 ## Development
 
-```powershell
-npm test                   # node --test: full regression of the smoke scripts
-npm run check              # syntax + smoke tests
-bash scripts/sync-to-dsh.sh   # register this checkout into the web profile as link: (dev)
-bash scripts/install.sh --dry-run   # print the install plan without touching the profile
+```sh
+npm test                            # full regression of the smoke scripts (runs node scripts/smoke-test.mjs)
+npm run check                       # syntax check + smoke tests
+node scripts/smoke-test.mjs         # run the smoke scripts directly (offline by design: no SSH, no DSH process)
+bash scripts/sync-to-dsh.sh --dry-run                    # preview the link: registration; drop --dry-run to actually rewrite the profile
 node scripts/portal-probe.mjs       # client tab render probe (runs when react resolves, otherwise skips)
 ```
 
@@ -153,10 +131,11 @@ Layout and where to change what:
 ```text
 lib/index.js            Host entry: tool registration, /dsh-ssh-tunnel/api routes, grants and path guard, xterm asset serving
 lib/client.js           Client bundle (committed; dsh plugin add does not build)
-lib/session.js          Session lifecycle: connect, keepalive, drop tombstones and auto-reconnect
-lib/shared/             Pure functions shared by host and client: path / host-key / host-summary / http-trust / persist /
+lib/session.js          Session lifecycle: connect, keepalive, drop tombstones and auto-reconnect, exec/SFTP execution
+lib/shared/             Pure functions shared by host and client: path / args / host-key / host-summary / http-trust / persist /
                         session-auth / session-policy / shell-buffer / vendor
 scripts/                install.sh · install.ps1 · sync-to-dsh.sh · smoke-test.mjs · portal-probe.mjs
+scripts/lib/            Installer shared logic (.cjs, used by both install.sh and install.ps1)
 cordis.patch.yml        In-package bundle patch the CLI turns into dsh.profile.bundles
 ```
 
@@ -168,11 +147,10 @@ cordis.patch.yml        In-package bundle patch the CLI turns into dsh.profile.b
 
 - If this plugin helps you, a Star is welcome; questions and suggestions go to [Issues](https://github.com/OMSociety/dsh-ssh-tunnel/issues) or [Pull Requests](https://github.com/OMSociety/dsh-ssh-tunnel/pulls).
 - Changes are recorded in the [CHANGELOG](CHANGELOG.md).
-- [LiveAgent](https://github.com/thirsty5034/LiveAgent): prior art for the product shape and several UX patterns (see "Prior art" above)
-- [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar): the sidebar host and tab contract
+- LiveAgent ([thirsty5034/LiveAgent](https://github.com/thirsty5034/LiveAgent)): prior art for the product shape and several UX patterns (see "Prior art" above)
 - [dsh-git-forge](https://github.com/OMSociety/dsh-git-forge): sibling plugin for Git credentials and push policy
-- [DeepSeek Harness](https://github.com/deepseek-ai/dsh): the host for plugins, tools and agent shells
+- DeepSeek Harness: the host for plugins, tools and agent shells
 
 ## License and author
 
-[MIT](LICENSE). Upstream project and code author [@thirsty5034](https://github.com/thirsty5034); maintenance and additions in this repository © 2026 [@OMSociety](https://github.com/OMSociety).
+[MIT](LICENSE). The license terms and copyright are defined by LICENSE; upstream project and code author [@thirsty5034](https://github.com/thirsty5034).

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# dsh-ssh-tunnel bundle mount
-- insert:
-    - id: ssh-tunnel
-      name: dsh-ssh-tunnel
+# dsh-ssh-tunnel bundle mount
+- insert:
+    - id: ssh-tunnel
+      name: dsh-ssh-tunnel