dsh-remote 0.8.34 → 0.8.36

package/README.md

@@ -22,160 +22,131 @@ DSH 的 Web 界面刻意只监听 `127.0.0.1`（CLI 为安全拒绝 `--host 0.0.
 
 ## 数据采集 / 遥测
 
-dsh-remote 每次启动会发送**一次匿名心跳**（同一安装最多每 6 小时一次），用于统计真实使用量：去重日活、实际在跑的版本、平台分布。npm 下载量回答不了这些问题（由发版驱动、且含镜像与爬虫），GitHub clone 也混有 CI。
+每次启动发送一次匿名心跳（同一安装最少间隔 6 小时），只用于统计用量：**去重日活、实际在跑的版本、平台分布**。npm 下载量由发版驱动、且含镜像与爬虫，GitHub clone 混有 CI，都回答不了这些。
 
-**发送的内容** —— 严格只有 5 个字段，一个都不多：
+只发送 5 个字段：`idHash`（`HMAC-SHA256('dsh-remote/telemetry/v1', installId)` 的伪名）、`version`、`platform`、`arch`、`node`。**不发送**主机名、用户名、路径、IP、SSH 主机/端口/密钥、机器列表、会话内容。原始 `installId`（`<DSH_HOME>/.dsh-remote-install-id`）不离开本机，只传它的 HMAC。
 
-| 字段 | 示例 | 用途 |
-|---|---|---|
-| `idHash` | `872bd8cf…`（32 位 hex） | `HMAC-SHA256('dsh-remote/telemetry/v1', installId)`，本安装的伪名 |
-| `version` | `0.8.29` | 实际在运行的版本 |
-| `platform` | `win32` / `darwin` / `linux` | 平台分布 |
-| `arch` | `x64` / `arm64` | 架构 |
-| `node` | `24.14.0` | Node 版本 |
-
-**绝不发送** —— 主机名、用户名、文件路径、IP、SSH 主机/端口/密钥、你的机器列表、会话内容、任何远程工作区数据。本插件恰恰能拿到这些信息，所以边界在这里划得很硬：原始 `installId` **不离开本机**，只有它的 HMAC 被传出，服务端无法与其他数据关联，也无法反推身份。
-
-**身份存放位置** —— `<DSH_HOME>/.dsh-remote-install-id`（如 `~/.dsh/`）中的一个随机 UUID。刻意**不放在插件目录**：npm/pnpm 每次升级都会覆盖插件目录，放那里会让同一台机器每次升级都换身份，把 1 个用户算成 N 个。删除该文件即重置身份。
-
-心跳是**尽力而为**的旁路：不阻塞加载、不产生日志噪音、任何失败（离线/被拦截/端点变更）都静默吞掉，绝不影响插件的任何功能。
+心跳是尽力而为的旁路：不阻塞加载，失败静默忽略。
 
 [实时用量看板](https://flymysql.github.io/dsh-remote/stats/) · [插件主页](https://flymysql.github.io/dsh-remote/)
 
 ## 界面预览
 
-设置 → **远程工作区** —— 多机 SSH 列表（增/删/改/设为当前，密码本地保存、不回显）：
-
-<img src="docs/ui-settings-panel.png" alt="dsh-remote 设置页 — 多机列表（浅色主题，主机已打码）" width="720"/>
+**设置 → 远程工作区** —— 多机列表、高级配置（私钥/跳板机/agent）、连接体检、端口转发、审计日志、更新：
 
-原生 **「Add workspace / 选择工作区」** 流程 —— **居中弹窗**、两个 tab，**默认落在「本机」**；切到 **「远程」**：
+<img src="docs/shots/settings-panel.png" alt="dsh-remote 设置页：机器列表、高级配置、端口转发、审计日志、更新" width="640"/>
 
-- **远程** —— 一个**机器下拉**；路径输入框**自动预填 `/` 并实时补全目录**（点选一个目录后**立即列出它的下一级**，像系统/VSCode 逐级选目录）；另外有**「浏览…」浮窗**，选中仅回填到输入框（不直接提交），你复核 / 修改后点「设为远程工作区」。
+原生 **「Add workspace / 选择工作区」** 流程 —— 居中弹窗、两个 tab，默认落在「本机」；切到**「远程」**：
 
-真实截图（机器已打码为占位）：
+<img src="docs/shots/picker-dialog.png" alt="选择工作目录弹窗的「远程」tab：机器下拉、最近工作区、浏览…、设为远程工作区" width="632"/>
 
-<img src="docs/ui-picker-panel.png" alt="dsh-remote 工作区选择 — 真实弹窗；默认本机 tab；远程：机器下拉 + 预填根路径 + 自动补全" width="720"/>
+- 路径框实时补全；Windows 主机根级显示「此电脑」多盘视图；「浏览…」浮层选中只回填、不直接提交。
+- 确定后创建**真实本地镜像**并被 harness 收养，同时通过 SFTP 保持同步；所选工作区持久化到该机器。
 
 ---
 
 ## 功能
 
-- **多机 SSH** —— 可存任意多台主机（host/port/user + **私钥**或**密码**）。密码只存在本地，界面不回显；在设置里一键切当前机。每机可配 passphrase / 主机指纹策略 / SSH agent / keyboard-interactive（OTP）/ 跳板机，以及可选的 **系统钥匙串加密密码**。
-- **`~/.ssh/config` 别名（实时解析，不存副本）** —— 机器可以只保存一个 **Host 别名**（`useSshConfig`）：主机名/用户/端口/私钥/跳板机**每次连接都从 `~/.ssh/config` 实时解析**，改配置立刻生效、无需重新导入；注册表里**不存这些值的副本**（私钥只引用路径，永不读内容）。支持 OpenSSH 语义：`Host a b` 多别名、`*`/`?` 通配、`!` 取反、`Include`（含通配、相对 `~/.ssh`）、行尾 `\` 续行、以及 ssh_config(5) 的**首个取值优先**规则。设置页「从 ~/.ssh/config 导入」列表里点别名即按别名保存（也可以「复制字段」成普通机器）；列表与机器行都会显示 **别名 → 实际解析到哪台机**，`ProxyJump` 多跳、`ProxyCommand` 等插件无法照做的事会**显式告警**而不是静默降级。
-- **双 tab 工作区选择器**（填充原生「Add workspace」流程）：
-  - **本机** —— 走 **host 端原生系统文件夹对话框**选本地目录（或直接输入本地路径）→ 直接成为普通 DSH 本地工作区（与本地工作区共存）。优先用 DSH 的 `directoryPicker` 服务，服务缺失时**回退到插件自持的原生选择器**（macOS `osascript` / Linux `zenity`→`kdialog` / Windows `FolderBrowserDialog`）——桌面启动路径上框架服务不注册也能用。
-  - **远程** —— 选择器是**居中弹窗**（窄侧边栏也不会被挤压）。先**选机器** → Windows 主机根级显示 **「此电脑」多盘视图**（`C:\`、`D:\`、`E:\`…，而不是 Git Bash 的 MSYS 根），路径框**实时补全**目录（支持 `C:\Users\…` 或 `/c/Users/…` 任意写法，Windows 路径在底层自动改写为 Git Bash 形式）；**选中一个目录立即列出它下一级**（OS/VSCode 式级联）。另有 **「浏览…」文件选择式浮层**（Windows 面包屑 `此电脑 / C:\ / Users / dev` 可点击跳级、驱动器行、大小/时间、跟随软链），选中**回填输入框不提交**，你复核/修改后再确定；「回上一级」任意深度可用（包括浮层直接打开在路径栏当前路径时）。**最近工作区**快捷入口、**`~` 主目录**、**新建目录**一键可达。确定会创建**真实本地镜像**（`$DSH_HOME/remote-workspaces/<host>-<user>-<port>/<basename>`；仅当同主机上**别的远端路径**已占用同名 basename 时才追加短路径 hash）→ harness 把它当真实工作区收养，同时 dsh-remote 通过 SFTP 保持同步。所选工作区会**持久化到该机器**，重启不丢。
-- **Git Bash 默认终端（Windows 主机）** —— 自动探测远程平台（`cmd /c ver`，附 `uname -s` 的 MINGW/MSYS 探测兜底）；Windows 机器自动定位 Git Bash（`config.shell` 可显式指定或 `native` 关闭），所有命令经 `bash -s` 从 SSH 通道 stdin 管道执行，不依赖 cmd/PowerShell，也不受引号/反斜杠转义困扰；`rw_exec` 默认在 Git Bash 形式的 cwd（`/c/Users/…`）下执行。`/dsh-remote/status`、`rw_info`、设置页「测试连接」都会报告检测到的平台与 shell。
-- **Windows 路径自动改写** —— 用户输入 `C:\Users\dev\project`（或 `C:/…`、`/c/…`、`/C:/…`）时底层自动规范为 Git Bash 形式 `/c/Users/dev/project` 执行；工作区存储与展示为 Windows 形式 `C:\Users\dev\project`。模型工具全部接受并展示两种写法；SFTP 访问使用 Win32-OpenSSH 的 `/D:/…` 形式（见 `toSftpPath`）。
-- **远程 `@` 补全（issue #39）** —— 远程会话里输入 `@` 会**列出远端目录树**（走 SFTP 实时读，不是本地镜像）。目录逐级下钻、无斜杠时在整棵树上模糊匹配，候选是**相对远程工作区根的路径**（`@src/main.c`），与本地会话的写法一致；`rw_*` 工具接受这种相对路径并自动拼到远程工作区根上。索引有预算保护（条目/目录/时限 + 缓存 + 失败熔断），**远端不可达时自动回退到本地镜像**（不会静默变成空列表）。本地会话完全不受影响。
-- **双向 SFTP 同步（三路冲突检测）** —— `rw_sync`（远程→镜像）、`rw_push`（镜像→远程）。两边都改过的文件会列出冲突、绝不静默覆盖（`force=true` 覆盖）。默认 **深度 8 / 2000 文件**，触顶会标明 **`TRUNCATED`**。支持 dry-run、后台任务、gitignore 风格 ignore 规则。
-- **模型工具（20 个）** —— `rw_info`、`rw_connect`（可 `save`）、`rw_pick_workspace`、`rw_list_dir`（大小+mtime）、`rw_stat`、`rw_read_file`（utf-8/gbk）、`rw_write_file`、`rw_edit`（字面替换 + mtime 乐观锁）、`rw_append`、`rw_mkdir`、`rw_remove`（递归、有上限）、`rw_move`、`rw_exec`（pty/env）、`rw_search`（**POSIX 快路径 `rg` → `grep -R -E`，远端两者都没有时回退 SFTP 遍历**，因此 Windows 主机也可用；遵守 ignore 规则、支持上下文行）、`rw_download`/`rw_upload`（流式 fastGet/fastPut + 体积上限）、`rw_forward`（SSH 隧道）、`rw_sync`、`rw_push`、`rw_disconnect`。
-- **端口转发面板** —— 设置页或 `rw_forward` 创建/启停/删除**本地**（`127.0.0.1:port → 远端`）与**反向**（`远端 → 本地`）隧道；定义持久化，开启时重连自动恢复，断开时全部停止。
-- **侧栏远程编辑** —— 远程文件 tab 可编辑并保存到远端（mtime 乐观锁，冲突返回 409 + 「重新读取」）。**v0.8.19** 起文件操作按会话绑定机器（前端带 `sessionId`），两台不同主机的会话不会共用当前机连接池。文件树显示文件大小，并有**右键菜单**（下载到本地镜像 / 重命名 / 删除 / 新建目录）。
-- **命令审计** —— 每次 `rw_exec`/写/删/移动/转发都追加到 `$DSH_HOME/remote-workspaces/audit.log`（时间 · user@host · 操作 · 退出码 · 命令）；设置页显示最近 30 条。
-- **长任务异步化** —— `rw_sync`/`rw_push` 传 `async: true` 返回 `taskId`，通过 `/dsh-remote/task` 查询进度/结果/取消（单飞队列）。
-- **连接体检** —— 设置页「测试连接」按类别提示（认证 / 网络 / 主机指纹 / 超时）；延迟会缓存在机器记录里。
-- 当前 `user@host:/path`（以及生效的转发）会注入每次系统提示，让 Agent 明确自己的工作根。
-- **不改任何 `dsh-workspace` 官方代码** —— 全部作为普通插件实现（client 半以 `priority -100` 填充 directory-flow holes）。
-- **远端跨平台** —— 文件访问走 SFTP 协议（不依赖 POSIX shell），Linux/macOS/Windows 远端都能列/读/写/搜索/同步。
-- **主机指纹校验（TOFU）** —— 每次 SSH 连接都校验主机密钥（`hostKeyMode: accept-new`）：首次连接记录，之后**密钥一旦变化立即拒绝**（防中间人）。`verify` 模式还会拒绝从未见过的机器；`off` 关闭校验。指纹存于 `$DSH_HOME/remote-workspaces/known_hosts.json`；误判可用 `/remote forget-key` 重置。
-- **数据跟随 Harness 根目录** —— 机器清单与镜像放在 `$DSH_HOME/remote-workspaces`（桌面版即 `userData/harness` 下）；0.6 之前落在 `~/.dsh/remote-workspaces` 的数据**首次启动自动迁移**，不丢失。
+![核心能力总览 — 多机 SSH / 别名实时解析 / 双 tab 选择器 / 三路同步 / 远程 @ 补全 / 安全审计 / 端口转发 / 侧栏编辑 / 自动更新，以及 21 个 rw_* 工具](docs/shots/features.png)
+
+上图是能力总览；下面只列**上图没说清、但用起来需要知道**的部分。
+
+其余要点：
+
+- **20 个模型工具**（便于复制/检索）：`rw_info`、`rw_connect`、`rw_pick_workspace`、`rw_list_dir`、`rw_stat`、`rw_read_file`、`rw_write_file`、`rw_edit`、`rw_append`、`rw_mkdir`、`rw_remove`、`rw_move`、`rw_exec`、`rw_search`、`rw_download`、`rw_upload`、`rw_sync`、`rw_push`、`rw_forward`、`rw_disconnect`。
+- **远端跨平台** —— 文件访问走 SFTP 协议层（不依赖 POSIX shell），Linux/macOS/Windows 远端都能列/读/写/搜索/同步。
+- **Windows 主机** —— 自动探测平台并定位 Git Bash，命令经 `bash -s` 走 stdin 执行，不受引号/反斜杠转义困扰（`config.shell` 可指定或设 `native` 关闭）；`C:\Users\dev` 与 `/c/Users/dev` 两种写法都接受。
+- **长任务异步化** —— `rw_sync`/`rw_push` 传 `async: true` 返回 `taskId`，可查询进度/结果/取消。
+- **数据跟随 Harness 根目录** —— 机器清单与镜像在 `$DSH_HOME/remote-workspaces`；0.6 之前的数据首次启动自动迁移。
+- **不改动 `dsh-workspace` 官方代码** —— 全部作为普通插件实现。
 
 ## 安装
 
 ### DSH 版本兼容性
 
-`dsh-remote` **同时支持 `0.1.x` 与 `0.2.x` 两条 DSH 线**。自 **0.8.29** 起，所有
-`@deepseek-ai/dsh-*` 的 peer 范围都是**跨线区间**（`>=0.1.0-rc.6 <0.3.0`，其中三个
-`dsh-client-*` 保持各自原有的 `>=0.1.2-rc.1` 下界），而不再是 caret。
-
-这一点的必要性在于：DSH 会在导入 bundle **之前**，把每条 `@deepseek-ai/dsh` /
-`@deepseek-ai/dsh-*` 的 peer 范围与运行时版本比对，**只要有一条不匹配就整包丢弃**：
+同时支持 `0.1.x` 与 `0.2.x` 两条 DSH 线。DSH 会在导入 bundle **之前**校验所有 `@deepseek-ai/dsh-*` 的 peer 范围，**任一条不匹配就整包丢弃**（没有设置页、没有 `rw_*` 工具）：
 
 ```
 dsh: skipping profile bundle "dsh-remote": Error: Plugin dsh-remote@… is incompatible …
 ```
 
-而 caret 在 `0.x` 上会锁死该小版本线，所以 `^0.1.0-rc.6` 永远无法容纳 `0.2.x` 运行时，
-`^0.2.0-rc.1` 也永远无法容纳 `0.1.x`。**如果你用的版本低于 0.8.29，请升级**——若你在升级
-DSH 后插件整个消失（没有设置页、没有 `rw_*` 工具），原因就是它。
-`test/compat.test.js` 用 DSH 自己的判定谓词钉住这些范围，防止 caret 回潮。
-
-### 官方 Desktop 兼容适配（实验性，尚未发布）
+caret 在 `0.x` 上会锁死小版本线（`^0.1.x` 容不下 `0.2.x`，反之亦然），所以自 **0.8.29** 起改为跨线区间 `>=0.1.0-rc.6 <0.3.0`。**低于 0.8.29 请在升级 DSH 前先升级本插件**。
 
-本分支增加对 [DeepSeek 官方 Desktop](https://github.com/deepseek-ai/deepseek-harness)
-的适配，以 `0.1.5-rc.2` Host 通信协议验证，不修改 Harness 核心：
+### 官方 Desktop 兼容适配（实验性）
 
-- 通过 `ctx.connection.fetch` 注册 `/api/dsh-remote/*`，由 Desktop 的
-  `dsh-app:` 通道承载请求，鉴权仍由宿主负责，不启动 Web Server。
-- 通过 `sidebarRightTabs` 和 `sidebar.right.pane.tab` 提供原生“远程文件”入口，
-  复用原来的文件树与编辑器，不把远端路径传给本地文件预览器。
-- `dsh-better-sidebar` 不再内置；Web 版可以单独安装，官方 Desktop 则使用
-  原生右侧栏集成。
+对 [DeepSeek 官方 Desktop](https://github.com/deepseek-ai/deepseek-harness) 的适配（以 `0.1.5-rc.2` Host 协议验证，不修改 Harness 核心）：
 
-已验证 Host 启动、IPC 请求、真实 SSH 的只读连接/目录列表/文本读取，以及设置页和
-测试 SSH 配置的导入。**v0.8.19** 起侧栏 `/ls` `/read` `/write` `/fs` 在请求带
-`sessionId` 时按该会话的镜像绑定选机（与 `rw_*` 同一套），不再落到「当前机器」
-连接池；宿主侧测试覆盖双机会话路由与编辑 409/重读/保存。原生文件标签的完整 GUI、
-失败/取消交互、非 macOS 宿主以及旧 Web 版完整 UI 回归仍属实验性。
+- 经 `ctx.connection.fetch` 注册 `/api/dsh-remote/*`，由 Desktop 的 `dsh-app:` 通道承载，不启动 Web Server。
+- 经 `sidebarRightTabs` 提供原生「远程文件」入口，不把远端路径传给本地预览器。
+- `dsh-better-sidebar` 不再内置；官方 Desktop 用原生右侧栏，不需要它。
 
-Desktop 安装器还可能要求明确配置 `ssh2` / `cpu-features` 可选构建脚本策略。
-隔离验证中禁用了这些可选脚本；本改动不放宽应用的构建白名单，也不自动批准脚本。
+已验证 Host 启动、IPC 请求、真实 SSH 的只读连接/列目录/读文件，以及双机会话路由（侧栏 `/ls` `/read` `/write` `/fs` 带 `sessionId` 时按会话选机）。原生文件 tab 的完整 GUI、失败/取消交互、非 macOS 宿主仍属实验性。Desktop 安装器可能需为 `ssh2` / `cpu-features` 可选构建脚本配置策略。
 
 ### 已发布的 Web bundle
 
-```bash
-dsh plugin add dsh-remote            # 添加 bundle
-```
-
-从 **v0.8.18** 起，`dsh-remote` 只安装并挂载自身。Web 侧边栏
-（[dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)）
-改为可选，不再是依赖，也不会被自动挂载。这样 SSH 工具和设置页不再被某个侧边栏
-实现的版本/API 变化拖垮。
-
-如需 Web 版远程文件浏览/编辑，请显式安装两个 bundle：
-
 ```bash
 dsh plugin add dsh-remote
-dsh plugin add dsh-better-sidebar
 ```
 
-独立侧边栏 service 存在时，`dsh-remote` 会动态发现它并注册远程文件 tab；
-不安装时，`rw_*` 工具、设置页、同步、审计日志和端口转发均照常工作。
-官方 Desktop 使用原生右侧栏，不需要安装 `dsh-better-sidebar`。
+自 **v0.8.18** 起只安装并挂载自身；Web 侧边栏（[dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)）改为可选。需要 Web 版远程文件浏览/编辑时再单独装它；不装时 `rw_*` 工具、设置页、同步、审计与转发均照常工作。
 
-> **从 0.7.2–0.8.17 升级：** 升到 0.8.18 后，内嵌侧边栏依赖和挂载会消失。
-> 只有仍需要 Web 侧边栏 UI 时才单独安装 `dsh-better-sidebar`。旧 profile 里针对
-> `id: dsh-remote-sidebar` 的覆盖可以删除，因为这行已不存在。
+> **从 0.7.2–0.8.17 升级：** 内嵌侧边栏会消失，旧 profile 里 `id: dsh-remote-sidebar` 的覆盖可以删除。
 
 （或 `npm install dsh-remote`，再在 `cordis.patch.yml` 加 `- id: dsh-remote / name: dsh-remote`。）
 
 ## 快速上手
 
-1. **加一台机器** —— 设置 → 远程工作区 → 填 host/port/user + 密码或 key →（可选）设为当前。
-   > **保存 ≠ 激活（v0.8.8+）**：保存的机器只是备用连接，不会自动进入任何 session 的
-   > remote context。只有「设为当前」（或 Agent 显式调用 `rw_connect`）才激活当前机器；
-   > 「取消设为当前」可回到 `active remote = none`。
+1. **加一台机器** —— 设置 → 远程工作区 → 填 host/port/user + 密码或 key → 设为当前。
+   > **保存 ≠ 激活**：保存只是备用连接；只有「设为当前」（或 Agent 调 `rw_connect`）才进入会话的 remote context。
 2. **选工作区** —— 点侧边栏/会话的 **Add workspace**：
-   - **本机** → 系统文件夹选择（或输入本地路径）→ 本地工作区。
-     宿主没有可用的系统对话框时（DSH Desktop 的 browse 后端、无 zenity/kdialog 的无头
-     SSH 主机），改为弹出插件内置的目录浏览器——面包屑、Windows 盘符切换、新建目录、
-     选中回填。
-   - **远程** → 选机器 → 浏览到远程目录（或输入 `/path`）→ 「设为远程工作区」⇒ 创建并收养一个本地镜像工作区。
-3. **让 Agent 工作** —— 把它当普通工作区用：
-   - `rw_list_dir(path?)` / `rw_read_file` / `rw_stat` —— 查看远程文件
-   - `rw_write_file` / `rw_edit` / `rw_append` —— 创建、补丁、追加远程文件
-   - `rw_mkdir` / `rw_remove` / `rw_move` —— 管理远程路径
-   - `rw_search(pattern, path?)` —— 远程 grep（POSIX 走 rg/grep，否则 SFTP 遍历）
-   - `rw_exec(command, cwd?, pty?)` —— 在远程执行命令（默认在工作区目录）
-   - `rw_forward` —— SSH 隧道
-   - `rw_sync` / `rw_push` —— 冲突感知的镜像拉取/推送
-
-> **Remote context 是 session 级的（v0.8.8+）**：system prompt 只会在**当前 session 的
-> cwd 位于某个远程 mirror 内**（即你把远程目录选成了这个 session 的工作区）时注入
-> 「Remote workspace」段落；普通本地 session 不注入、侧边栏「远程文件」也不显示任何
-> 机器默认目录，模型不会主动调用 `rw_*`。混合访问（本地 + 远程同屏比较）请通过显式
-> 选择远程工作区进行。
+   - **本机** → 系统文件夹选择（或手输路径）→ 本地工作区。宿主没有可用系统对话框时改用插件内置浏览器。
+   - **远程** → 选机器 → 浏览到远程目录（或输入 `/path`）→ 「设为远程工作区」⇒ 创建并收养本地镜像工作区。
+3. **让 Agent 工作** —— 当作普通工作区使用，例如 `rw_read_file` / `rw_write_file` / `rw_edit` / `rw_exec` / `rw_search` / `rw_sync` / `rw_push` / `rw_forward`（完整列表见上文）。
+
+> **Remote context 是 session 级的**：只有当前 session 的工作区是某个远程镜像时，system prompt 才注入「Remote workspace」段落；普通本地 session 不受影响，模型也不会主动调 `rw_*`。
+
+## 在本地打开远程机器上的 DSH 界面
+
+远程机器上那个 `dsh web` 也可以**当成本机的一个页面打开**（issue #46）。方向仍然是「本地主动连出去」：
+
+> **远端不需要开放任何端口**。DSH 刻意拒绝 `--host 0.0.0.0`（它会把远程代码执行能力暴露到网络上），
+> 所以正确的做法是由本机 SSH 连过去，在远端**只监听 127.0.0.1** 地起一个 `dsh web`，
+> 再把它的端口经 SSH 隧道搬回本机的一个 loopback 端口。
+
+用法：设置 → 远程工作区 → **「远程 DSH 界面」** → 选一台机器 → **连接并打开**。
+浏览器会新开一个标签页，显示的就是**那台远端机器**的完整 DSH 界面（聊天、工具树、设置都在）。
+
+- 界面地址形如 `http://127.0.0.1:3088/?token=…`。那个 token 是远端进程启动时打印的一次性凭据，
+  只在**本机**的这次跳转里用一次：DSH 会把它换成 30 天有效的签名 cookie 并跳转到干净的 `/`。
+  **请不要把这个带 token 的地址外发**。
+- 「断开」只关隧道，**不会**杀掉远端进程（它可能是你在别处也在用的实例）；
+  要连远端进程一起停，用「断开并停止远端」——它只会结束**本次由插件启动**的那个进程。
+- 若远端已经在跑一个界面（比如你自己在终端里起的），可以选机器后把它的
+  `http://127.0.0.1:<端口>/?token=…` 粘进输入框，点「连接已有实例」，插件不会再去启第二个。
+- 远端 `dsh` 不在 SSH 登录 PATH 时，用 `webAttachCommand` 指向它的绝对路径；
+  想让它别污染远端用户自己的会话/设置，用 `webAttachDshHome` 指一个临时目录。
+
+### 连不上？先体检，再一键部署
+
+**连不上大多不是插件的问题，而是远端 dsh 的版本或环境不对。** 最典型的一种：dsh 0.1.0-rc.6
+依赖 `node-pty@1.1.0`，而**那个版本发布的包里没有 `linux-x64` 预编译产物** ⇒ `dsh web`
+在 Linux 上根本起不来。这种情况以前只能看到「没拿到启动令牌」，无从判断。
+
+设置 → 远程工作区 → **「远端 dsh 体检与部署」**：
+
+1. **体检（只读）** —— 探测远端平台/node/npm/dsh 版本/**原生模块能否启动**/是否认识
+   `--no-open`/代理与 npm 源，给出结论与修复建议。**不写任何东西**，可以随便点。
+2. **部署并验证** —— 只在上一步判定「需要且可以自动装」时才出现。它会装到远端
+   **私有目录**（默认 `~/.dsh-remote/dsh`）：**不写系统目录、不改 PATH、不覆盖你在用的版本**，
+   删掉那个目录即完全回滚。装完逐步校验（二进制 / 原生模块 / `web` 子命令），
+   成功后**按机器记住**这条 dsh 路径，之后连接就用它。
+3. **让 AI 排查** —— 只在失败后出现。它会创建一个会话，让内置的 `dsh-remote-deploy`
+   技能去处理确定性流程覆盖不到的长尾（没有 npm、要 sudo、代理、内网镜像源、Windows 远端等）。
+   **只有你点它才会创建**，因为这会消耗模型额度。
+
+相关配置：`webInstallPrefix`（装哪，默认 `$HOME/.dsh-remote/dsh`）、
+`webInstallVersion`（装哪个版本，默认 `0.1.5-rc.2`——第一个在 Linux 上能起 web 的版本）、
+`webInstallRegistry`（npm 源；**留空则沿用远端自己的配置**，不会覆盖你的内网镜像）。
 
 ## 可选：CLI 默认机
 
@@ -224,8 +195,7 @@ npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # 恢复用
 
 ## 开发（沙箱优先，勿改产品）
 
-迭代**一律在沙箱**里做，绝不手工改产品 profile——产品 profile 由插件管理器重管，
-重装会把手工部署的文件还原掉。用仓库内的辅助脚本：
+迭代一律在沙箱里做——手工改产品 profile 会被插件管理器在重装时还原：
 
 ```bash
 scripts/dev-run.sh --restart   # 启动 / 重启隔离沙箱
@@ -233,18 +203,11 @@ scripts/dev-run.sh --stop      # 停止
 scripts/dev-run.sh --status    # 是否在运行
 ```
 
-- 自带一套独立 DSH 实例（仓库内 `dev-harness/harness`），把 `lib/` 复制进沙箱
-  profile——与桌面 App 走同一条 `bin.js web --patch` 启动路径，沙箱即产品启动行为。
-- 沙箱 web UI 在 `http://127.0.0.1:50599`，插件路由立即可见（如
-  `GET /dsh-remote/machines`）。
-- **宿主半改动**（`lib/index.js`）需重启沙箱（`--restart`）；**客户端半改动**
-  （`lib/client.js`）只需刷新页面。
-- Node ESM 按导入文件的真实路径解析依赖，脚本用**硬链接拷贝**（`cp -al`）把
-  `lib/` 复制进沙箱 profile，而不是软链——软链会破坏 `@deepseek-ai/*` 的解析。
-- 每次提交前跑 `node check.mjs`（静态框架约束闸门：命令名正则等）；
-  `scripts/boot-smoke.sh` 用隔离实例证明插件仍能启动。
-- 完整规则见 `scripts/dev-standards.md`（命令名、cordis 服务只许 `ctx.get()`、
-  可选框架服务可能压根不注册、三方库回调契约以真实运行为准等）。
+- 沙箱自带独立 DSH 实例（仓库内 `dev-harness/harness`），UI 在 `http://127.0.0.1:50599`。
+- **宿主半**（`lib/index.js`）改动需 `--restart`；**客户端半**（`lib/client.js`）改动刷新页面即可。
+- 脚本用**硬链接拷贝**把 `lib/` 放进沙箱而非软链——软链会破坏 `@deepseek-ai/*` 的解析。
+- 提交前跑 `node check.mjs`（框架约束闸门）与 `npm test`；`scripts/boot-smoke.sh` 证明插件仍能启动。
+- 完整规则见 `scripts/dev-standards.md`。
 
 部署到产品 profile 是单独的受控动作（`./sync.sh`），只在确定要发布时做。
 
@@ -276,37 +239,54 @@ scripts/dev-run.sh --status    # 是否在运行
 | `fileReferenceMaxEntries` | int | `3000` | 一棵远程工作区索引最多保留多少条目 |
 | `fileReferenceExcludedDirectories` | string[] | `[.git, node_modules, dist, build, out, coverage, target, .next, .nuxt, .turbo, .venv, __pycache__, .pytest_cache, .mypy_cache, .gradle]` | 远程 `@` 遍历跳过的目录名 |
 | `fileReferenceTimeoutMs` | int | `4000` | 一次远程索引遍历的墙钟预算（超时用已扫到的部分结果，不让光标等） |
+| `searchTimeoutMs` | int | `60000` | `rw_search` 的协作式预算（ms）：既作为工具声明的 `timeoutMs` 交给 DSH 的 timeout-policy，也是搜索自身的墙钟上限；到点返回部分结果并标 `TRUNCATED`（issue #44）。 |
+| `searchMaxEntries` | int | `50000` | `rw_search` 在返回部分结果前最多扫描多少个文件。 |
 | `updateMode` | string | `auto` | 自更新模式：`auto`=加载时及每 6 小时检查并自动应用、`manual`=仅在手动检查时查、`off`=完全不查。**0.8.27 起默认 `auto`**——之所以现在才安全，是因为 0.8.24 补上了宿主半热切换 |
 | `updateCheckIntervalMs` | int | 21600000（6h） | `auto` 模式检查 npm 的间隔（下限 60000） |
 | `updateAutoReload` | bool | `true` | 更新落地后自动热切换宿主半；`false` 则留到下次启动，设置页会显示 `pendingReload` |
+| `webAttachPortStart` | int | `3088` | 「远程 DSH 界面」在本机监听的起始端口（占用则顺延，仅监听 127.0.0.1） |
+| `webAttachCommand` | string | `dsh` | 在远端启动 `dsh web` 用的命令；远端 `dsh` 不在 SSH 登录 PATH 时改这里 |
+| `webAttachDshHome` | string | `''` | 远端启动时导出的 `DSH_HOME`；留空则复用远端用户自己的 harness home |
+| `webAttachWaitSeconds` | int | `45` | 等待远端 `dsh web` 打印启动令牌的秒数 |
+| `webInstallPrefix` | string | `''` | 自动部署装到远端的哪个目录；留空用 `$HOME/.dsh-remote/dsh`（不写系统目录、不改 PATH） |
+| `webInstallVersion` | string | `0.1.5-rc.2` | 自动部署安装的 dsh 版本；默认值是第一个在 Linux 上能启动 web 的版本 |
+| `webInstallRegistry` | string | `''` | 安装用的 npm 源；**留空沿用远端自己的配置**，不会覆盖内网镜像 |
 
 > 权威清单是 `lib/index.js` 里的 `Config` schema，本表与之一致。
 
 ## 常见问题 / 排查
 
-**`@` 能列出远程文件，但内置的读文件工具打不开** —— harness 自带的文件工具看到的是会话的**本地镜像**（`$DSH_HOME/remote-workspaces/…`），要等 `rw_sync` 下载后才有内容。读远程文件请用 `rw_read_file` 或侧栏的远程文件 tab：远程会话里的 `@src/main.c` 指 `<远程工作区>/src/main.c`，所有 `rw_*` 工具会把这种相对路径解析到远程工作区根。完全看不到候选？远端不可达时 `@` 索引会回退到本地镜像，设置页「测试连接」会告诉你原因。
+**`@` 能列出远程文件，但内置读文件工具打不开** —— harness 自带工具看到的是**本地镜像**，要等 `rw_sync` 下载后才有内容。读远程文件请用 `rw_read_file` 或侧栏远程文件 tab。
+
+**主机指纹变了** —— `/remote forget-key`（或设置页 → 机器 → 重新信任）。
 
-**主机指纹变了 / 提示可能中间人** —— 主机重装过或密钥更换过：`/remote-forget-key`（或设置页 → 机器 → 重新信任），下次连接重新记录。
+**连接报「认证失败」** —— 检查用户名/密码/私钥路径；加密私钥要填 Passphrase；需要动态码时勾选 keyboard-interactive。
 
-**连接报「认证失败」** —— 检查用户名/密码/私钥路径；私钥加密了要填 Passphrase；公司机器要求 OTP/动态码时勾选 keyboard-interactive。
+**连不上内网机器** —— 填「跳板机」主机（也可先把跳板机本身配成一台机器）。
 
-**连不上内网机器** —— 走跳板机：机器表单里填「跳板机」主机（也可以先把它本身配成一台机器）。主机不可达类错误会给出分类提示。
+**`rw_sync`/`rw_push` 报冲突** —— 两边都改过的文件会被跳过并列出（绝不静默覆盖）；手动合并后重试，或用 `force=true` 以一边为准。
 
-**`rw_sync`/`rw_push` 报冲突** —— 远端和本地都改过同一个文件时会跳过并列出冲突（绝不静默覆盖）。处理：手动合并后重新同步，或用 `force=true` 以一边为准。
+**Windows 远程** —— 全部走 SFTP，不依赖 POSIX shell；中文文件用 `encoding=gbk`。
 
-**Windows 远程** —— 列表/读写/搜索/同步全部走 SFTP 协议，不依赖 POSIX shell；中文文件用 `encoding=gbk` 读。
+**镜像里缺目录** —— 默认 ignore 会跳过 `.git`/`node_modules` 等；在 `$DSH_HOME/remote-workspaces/.dsh-remote-ignore` 调整（gitignore 语法）。
 
-**镜像里没有某个目录** —— 默认 ignore 规则（`.git`、`node_modules`、`target` 等）会跳过；在 `$DSH_HOME/remote-workspaces/.dsh-remote-ignore` 加 `!` 之外的条目即可调整（gitignore 语法）。
+**保存远程文件报 409** —— 打开后远端已被改动，重新读取再编辑。
 
-**侧边栏远程文件保存失败（409）** —— 远端文件在你打开后已被改动，重新读取后再编辑（mtime 乐观锁保护）。
+**密码怎么加密保存** —— 勾选「加密保存密码」：macOS 钥匙串 / Windows DPAPI / Linux secret-tool（libsecret）；后端不可用时回退明文。
 
-**密码怎么加密保存** —— 机器表单勾选「加密保存密码」：macOS 用系统钥匙串（security），Windows 用 DPAPI，Linux 需要 secret-tool（libsecret）；后端不可用时自动回退明文。
+**升级后插件整个不见了** —— DSH 兼容性判定丢弃了 bundle，升到 **0.8.29+** 即可（见上文「DSH 版本兼容性」）。
 
-**升级后插件整个不见了** —— 多半是 DSH 兼容性判定把 bundle 丢弃了（见上文「DSH 版本兼容性」）。升到 **0.8.29+** 即可同时兼容 `0.1.x` / `0.2.x`。
+**「远程 DSH 界面」连不上/一直转圈** —— 先确认那台机器上的 `dsh web` **本身**能起来。
+两个已知坑（插件会在报错里直接点出来）：
+① **dsh 0.1.0-rc.6 在 Linux 上无法启动 web**——它依赖的 `node-pty@1.1.0` 只带了
+macOS/Windows 的预编译产物，**没有 `linux-x64`**，会报 `Failed to load native module: pty.node`。
+升到 0.1.5-rc.2+ 即可（其 `node-pty@1.2.0-beta.15` 带 Linux 预编译）。
+② **dsh 0.1.0-rc.6 不认识 `--no-open`**（该 flag 是后加的）；插件会自动去掉它重试一次，无需你处理。
+如果远端 `dsh` 不在 SSH 登录 PATH 里（例如装在私有前缀），用 `webAttachCommand` 指向它的绝对路径。
 
 ## 安全提醒
 
-把机器凭据交给插件，等于允许 Agent 以你的用户身份在主机上执行 **shell 命令**。只添加你可信的机器。密码保存在本机文件里（或启用后的系统钥匙串），请当作敏感数据处理（可收紧文件 ACL）。开启 `auditLog` 时每条执行的命令都会记入审计日志——可在设置页查看。
+把凭据交给插件等于允许 Agent 以你的用户身份在该主机执行 **shell 命令**——只添加可信机器。密码存在本机文件（或钥匙串），请当作敏感数据。开启 `auditLog` 时每条命令都会记入审计日志。
 
 ## License