dsh-remote 0.8.33 → 0.8.35

package/README.md

@@ -22,160 +22,88 @@ 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 选择器 / 三路同步 / 远程 @ 补全 / 安全审计 / 端口转发 / 侧栏编辑 / 自动更新，以及 20 个 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 回潮。
+caret 在 `0.x` 上会锁死小版本线（`^0.1.x` 容不下 `0.2.x`，反之亦然），所以自 **0.8.29** 起改为跨线区间 `>=0.1.0-rc.6 <0.3.0`。**低于 0.8.29 请在升级 DSH 前先升级本插件**。
 
-### 官方 Desktop 兼容适配（实验性，尚未发布）
+### 官方 Desktop 兼容适配（实验性）
 
-本分支增加对 [DeepSeek 官方 Desktop](https://github.com/deepseek-ai/deepseek-harness)
-的适配，以 `0.1.5-rc.2` Host 通信协议验证，不修改 Harness 核心：
+对 [DeepSeek 官方 Desktop](https://github.com/deepseek-ai/deepseek-harness) 的适配（以 `0.1.5-rc.2` Host 协议验证，不修改 Harness 核心）：
 
-- 通过 `ctx.connection.fetch` 注册 `/api/dsh-remote/*`，由 Desktop 的
-  `dsh-app:` 通道承载请求，鉴权仍由宿主负责，不启动 Web Server。
-- 通过 `sidebarRightTabs` 和 `sidebar.right.pane.tab` 提供原生“远程文件”入口，
-  复用原来的文件树与编辑器，不把远端路径传给本地文件预览器。
-- `dsh-better-sidebar` 不再内置；Web 版可以单独安装，官方 Desktop 则使用
-  原生右侧栏集成。
+- 经 `ctx.connection.fetch` 注册 `/api/dsh-remote/*`，由 Desktop 的 `dsh-app:` 通道承载，不启动 Web Server。
+- 经 `sidebarRightTabs` 提供原生「远程文件」入口，不把远端路径传给本地预览器。
+- `dsh-better-sidebar` 不再内置；官方 Desktop 用原生右侧栏，不需要它。
 
-已验证 Host 启动、IPC 请求、真实 SSH 的只读连接/目录列表/文本读取，以及设置页和
-测试 SSH 配置的导入。**v0.8.19** 起侧栏 `/ls` `/read` `/write` `/fs` 在请求带
-`sessionId` 时按该会话的镜像绑定选机（与 `rw_*` 同一套），不再落到「当前机器」
-连接池；宿主侧测试覆盖双机会话路由与编辑 409/重读/保存。原生文件标签的完整 GUI、
-失败/取消交互、非 macOS 宿主以及旧 Web 版完整 UI 回归仍属实验性。
-
-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_*`。
 
 ## 可选：CLI 默认机
 
@@ -224,8 +152,7 @@ npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # 恢复用
 
 ## 开发（沙箱优先，勿改产品）
 
-迭代**一律在沙箱**里做，绝不手工改产品 profile——产品 profile 由插件管理器重管，
-重装会把手工部署的文件还原掉。用仓库内的辅助脚本：
+迭代一律在沙箱里做——手工改产品 profile 会被插件管理器在重装时还原：
 
 ```bash
 scripts/dev-run.sh --restart   # 启动 / 重启隔离沙箱
@@ -233,18 +160,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,6 +196,8 @@ 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` |
@@ -284,29 +206,29 @@ scripts/dev-run.sh --status    # 是否在运行
 
 ## 常见问题 / 排查
 
-**`@` 能列出远程文件，但内置的读文件工具打不开** —— 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；公司机器要求 OTP/动态码时勾选 keyboard-interactive。
+**连接报「认证失败」** —— 检查用户名/密码/私钥路径；加密私钥要填 Passphrase；需要动态码时勾选 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`、`target` 等）会跳过；在 `$DSH_HOME/remote-workspaces/.dsh-remote-ignore` 加 `!` 之外的条目即可调整（gitignore 语法）。
+**镜像里缺目录** —— 默认 ignore 会跳过 `.git`/`node_modules` 等；在 `$DSH_HOME/remote-workspaces/.dsh-remote-ignore` 调整（gitignore 语法）。
 
-**侧边栏远程文件保存失败（409）** —— 远端文件在你打开后已被改动，重新读取后再编辑（mtime 乐观锁保护）。
+**保存远程文件报 409** —— 打开后远端已被改动，重新读取再编辑。
 
-**密码怎么加密保存** —— 机器表单勾选「加密保存密码」：macOS 用系统钥匙串（security），Windows 用 DPAPI，Linux 需要 secret-tool（libsecret）；后端不可用时自动回退明文。
+**密码怎么加密保存** —— 勾选「加密保存密码」：macOS 钥匙串 / Windows DPAPI / Linux secret-tool（libsecret）；后端不可用时回退明文。
 
-**升级后插件整个不见了** —— 多半是 DSH 兼容性判定把 bundle 丢弃了（见上文「DSH 版本兼容性」）。升到 **0.8.29+** 即可同时兼容 `0.1.x` / `0.2.x`。
+**升级后插件整个不见了** —— DSH 兼容性判定丢弃了 bundle，升到 **0.8.29+** 即可（见上文「DSH 版本兼容性」）。
 
 ## 安全提醒
 
-把机器凭据交给插件，等于允许 Agent 以你的用户身份在主机上执行 **shell 命令**。只添加你可信的机器。密码保存在本机文件里（或启用后的系统钥匙串），请当作敏感数据处理（可收紧文件 ACL）。开启 `auditLog` 时每条执行的命令都会记入审计日志——可在设置页查看。
+把凭据交给插件等于允许 Agent 以你的用户身份在该主机执行 **shell 命令**——只添加可信机器。密码存在本机文件（或钥匙串），请当作敏感数据。开启 `auditLog` 时每条命令都会记入审计日志。
 
 ## License
 

package/lib/client.js

@@ -144,6 +144,7 @@ window.__ModuleLoader__.load({
 'settings.updateAppliedNoReload': '✅ 已更新到 v{to}（{from} → {to}）。重启 Harness 生效。',
 'settings.updatePendingReload': '⚠️ 磁盘已是 v{disk}，运行中的仍是 v{loaded}；点「立即更新」或重启 Harness 完成切换。',
 'settings.selfUpdateBlocked': 'ℹ️ 当前是 link:/开发模式安装（不在 node_modules 下），已禁止自动更新以免覆盖源码——请在你的源码仓库里更新。',
+'settings.updateRegistryError': 'npm registry 查询失败：{msg}',
         'settings.updateFailed': '更新失败',
         'settings.updateFailedMsg': '更新失败: {msg}',
         'settings.registryUnreachable': '无法连接 npm registry',
@@ -371,6 +372,7 @@ window.__ModuleLoader__.load({
 'settings.updateAppliedNoReload': '✅ Updated to v{to} ({from} → {to}). Restart Harness to apply.',
 'settings.updatePendingReload': '⚠️ v{disk} is on disk but v{loaded} is still running; update again or restart Harness to switch.',
 'settings.selfUpdateBlocked': 'ℹ️ This is a link:/dev install (not under node_modules), so self-update is disabled to avoid overwriting source — update it from its source repo.',
+        'settings.updateRegistryError': 'npm registry query failed: {msg}',
         'settings.updateFailed': 'Update failed',
         'settings.updateFailedMsg': 'Update failed: {msg}',
         'settings.registryUnreachable': 'Cannot reach the npm registry',
@@ -830,9 +832,17 @@ window.__ModuleLoader__.load({
         setUpdBusy(true); setUpdMsg('')
         api('GET', '/dsh-remote/update-check')
           .then((r) => {
-            if (!r || !r.ok) { setUpdMsg((r && r.error) || tr('settings.updateFail')); return }
-            setUpd(r)
-            if (r.updateMode) setUpdMode(r.updateMode)
+            if (!r) { setUpdMsg(tr('settings.updateFail')); return }
+            // 即使 registry 查不到（限流/离线/超时），也先用本地状态填充面板，
+            // 否则 latest 永远为 null，界面会一直停在「版本信息加载中…」——
+            // 看起来像卡死，而本地版本/更新模式其实都是已知的。
+            if (r.ok) { setUpd(r); if (r.updateMode) setUpdMode(r.updateMode) }
+            if (r.registryError) {
+              // 把真实原因说出来：限流是"稍后自动恢复"，与"网络坏了"处置不同。
+              setUpdMsg(tr('settings.updateRegistryError', { msg: r.registryError }))
+              return
+            }
+            if (!r.ok) { setUpdMsg(r.error || tr('settings.updateFail')); return }
             if (!quiet) setUpdMsg(r.updateAvailable ? tr('settings.updateAvailable', { version: r.latest }) : tr('settings.updateLatest', { version: r.current }))
           })
           .catch((e) => setUpdMsg(String((e && e.message) || e)))

package/lib/ignore.js

@@ -106,6 +106,39 @@ export const DEFAULT_IGNORE = [
   '.dsh-remote-sync-state.json',
 ]
 
+/**
+ * Extra directories skipped by `rw_search` (but NOT by mirror sync — a user may
+ * legitimately want their cache tree mirrored, and silently excluding it from
+ * sync would lose data).
+ *
+ * These are machine-local package/tool caches: enormous numbers of tiny files
+ * that essentially never contain what a human is searching for, and that are
+ * the main way a "search my home directory" turns into a multi-hour walk
+ * (issue #44 reports `~/.npm/_cacache` specifically). Searching them is
+ * available via an explicit `path`, which bypasses these excludes.
+ */
+export const DEFAULT_SEARCH_IGNORE = [
+  ...DEFAULT_IGNORE,
+  '.npm/',
+  '.cache/',
+  '.local/',
+  '.cargo/',
+  '.rustup/',
+  '.gradle/',
+  '.m2/',
+  '.pnpm-store/',
+  '.yarn/',
+  '.conda/',
+  '.docker/',
+  '.nvm/',
+  '.pyenv/',
+  '.Trash/',
+  '.Trash-1000/',
+  'snap/',
+  'AppData/',
+  'Library/Caches/',
+]
+
 /**
  * Load the user ignore file (gitignore syntax) and merge with defaults.
  * Returns `{ patterns, fromFile }`.

package/lib/index.js

@@ -31,7 +31,7 @@ import {
   toShellPath, toDisplayPath, remotePathBase, truncate, shortHash,
 } from './paths.js'
 import { createHostKeyGuard, isHostKeyKnown as _isHostKeyKnown } from './hostkey.js'
-import { compileIgnore, DEFAULT_IGNORE } from './ignore.js'
+import { compileIgnore, DEFAULT_IGNORE, DEFAULT_SEARCH_IGNORE } from './ignore.js'
 import { friendlyMessage } from './errors.js'
 import { importableEntries, sshConfigPath, readSshConfigText, resolveMachineSshConfig } from './sshconfig.js'
 import { createRemoteFileReference, installFileReferenceOverlay, DEFAULT_EXCLUDED_DIRECTORIES } from './file-reference.js'
@@ -134,6 +134,14 @@ export const Config = z.object({
   /** Wall-clock budget (ms) for one remote `@` index pass; on expiry the
    *  partial index answers rather than making the caret wait. */
   fileReferenceTimeoutMs: z.number().step(1).min(200).default(4000),
+  /** Cooperative budget (ms) for `rw_search`; also declared as the tool's
+   *  `timeoutMs` so @deepseek-ai/dsh-tool-call-timeout-policy can end a call
+   *  that overruns. The search itself stops at this budget and returns partial
+   *  results (issue #44: an unbounded walk over a home directory could never be
+   *  stopped and left the turn `running` forever). */
+  searchTimeoutMs: z.number().step(1).min(1000).default(60000),
+  /** Max files `rw_search` will stat/read before returning partial results. */
+  searchMaxEntries: z.number().step(1).min(1).default(50000),
   /** Update mode: `auto` (default) checks on load and periodically, applies a
    * newer npm release automatically, then hot-swaps the host half (see
    * `updateAutoReload`); `manual` only checks when the user asks; `off` disables
@@ -734,6 +742,9 @@ export async function apply(ctx, config) {
   }
 
   // ── ignore rules (defaults + user file) ───────────────────────────────────
+  // NOTE: this matcher is shared by mirror sync (rw_sync/rw_push) and search.
+  // Do NOT add search-only cache excludes here: widening it would silently stop
+  // syncing directories a user may rely on. Search uses searchIgnoreMatcher().
   const ignoreMatcher = () => {
     try {
       const fromFile = readFileSync(ignoreFile(), 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
@@ -742,6 +753,18 @@ export async function apply(ctx, config) {
       return compileIgnore(DEFAULT_IGNORE)
     }
   }
+  /** Search-only matcher: same as ignoreMatcher() plus machine-local cache trees
+   *  (`~/.npm`, `~/.cache`, …) that are huge, almost never what a human is
+   *  looking for, and the main cause of the issue #44 hang. Mirror sync is
+   *  deliberately unaffected. An explicit `path` still searches anywhere. */
+  const searchIgnoreMatcher = () => {
+    try {
+      const fromFile = readFileSync(ignoreFile(), 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+      return compileIgnore(DEFAULT_SEARCH_IGNORE.concat(fromFile))
+    } catch {
+      return compileIgnore(DEFAULT_SEARCH_IGNORE)
+    }
+  }
 
   // ── task + forward managers ───────────────────────────────────────────────
   const tasks = new TaskManager()
@@ -1593,21 +1616,44 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_edit',
       description:
-        'Edit a remote text file by replacing literal text (read-modify-write with an mtime optimistic lock: aborts if the file changed on the remote between read and write). Path is absolute.',
+        'Edit a remote text file by replacing literal text (read-modify-write with an mtime optimistic lock: aborts if the file changed on the remote between read and write). Path is absolute. Accepts the aliases old_string/new_string (and file_path for path), matching the host edit tool, so either spelling works.',
       parameters: {
-        path: { type: 'string', required: true, description: 'Absolute remote file path' },
-        old: { type: 'string', required: true, description: 'Literal text to replace (must appear exactly once unless count is given)' },
-        new: { type: 'string', required: true, description: 'Replacement text' },
+        // `path`/`old`/`new` also accept the host edit tool's spellings
+        // (file_path/old_string/new_string): models habitually use those, and a
+        // schema-level `required` on only one spelling rejects the other before
+        // execute() ever runs. So NONE of them is declared required here — the
+        // resolver below enforces "path + old + new" and reports which spelling
+        // to pass. Keep this in sync: adding `required: true` back to any of
+        // these silently breaks its alias.
+        path: { type: 'string', description: 'Absolute remote file path (alias: file_path)' },
+        old: { type: 'string', description: 'Literal text to replace (must appear exactly once unless count is given). Alias: old_string' },
+        new: { type: 'string', description: 'Replacement text; an empty string deletes the old text. Alias: new_string' },
+        old_string: { type: 'string', description: 'Alias of old (same meaning)' },
+        new_string: { type: 'string', description: 'Alias of new (same meaning)' },
+        file_path: { type: 'string', description: 'Alias of path (same meaning)' },
         count: { type: 'integer', description: 'How many occurrences to replace (default: error if the text appears more than once)' },
         encoding: { type: 'string', description: 'Text encoding, e.g. utf-8 (default) or gbk' },
       },
       output: okOut,
       async execute(args, exec) {
         const b = requireMachine(exec, 'rw_edit')
-        const p = resolveRemoteArg(b, args.path)
-        if (!p || p === '/') throw new Error('rw_edit: a file path is required')
-        const oldS = String(args.old ?? '')
-        const newS = String(args.new ?? '')
+        // Presence must be checked on the RAW argument, not on the resolved
+        // path: resolveRemoteArg falls back to the workspace root for an empty
+        // string, so `!p` would never fire and a pathless rw_edit would silently
+        // target the workspace root. (That is why `path` cannot simply lose its
+        // schema `required` without this check replacing it.)
+        const rawPath = args.path ?? args.file_path
+        if (rawPath == null || String(rawPath).trim() === '') {
+          throw new Error('rw_edit: a file path is required — pass path (alias: file_path)')
+        }
+        const p = resolveRemoteArg(b, rawPath)
+        if (!p || p === '/') throw new Error('rw_edit: a file path is required — pass path (alias: file_path)')
+        const oldRaw = args.old ?? args.old_string
+        const newRaw = args.new ?? args.new_string
+        if (oldRaw == null) throw new Error('rw_edit: old text is required — pass old (alias: old_string)')
+        if (newRaw == null) throw new Error('rw_edit: replacement text is required — pass new (alias: new_string); use an empty string to delete the old text')
+        const oldS = String(oldRaw)
+        const newS = String(newRaw)
         if (oldS === '') throw new Error('rw_edit: old text must not be empty')
         const sftp = await b.pool.sftp()
         const st0 = await sftp.stat(p)
@@ -1772,6 +1818,7 @@ export async function apply(ctx, config) {
           if (!parts.length) parts.push('(no output)')
           let text = parts.join('\n')
           if (res.signal === 'TIMEOUT') text += `\n[command timed out after ${config.commandTimeoutMs}ms]`
+          else if (res.signal === 'ABORTED') text += '\n[cancelled — the remote command was stopped]'
           else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
           return { text }
         } catch (err) {
@@ -1783,7 +1830,12 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_search',
       description:
-        'Search remote files for a pattern. POSIX remotes try `rg` then `grep -R` first; Windows and fallbacks use a portable SFTP walk. Honors ignore rules. Returns matching file:line rows; output is capped.',
+        'Search remote files for a pattern. POSIX remotes try `rg` then `grep -R` first; Windows and fallbacks use a portable SFTP walk. Honors ignore rules. Returns matching file:line rows; output is capped. Search is bounded (maxEntries/maxDurationMs) and can be cancelled: on a very large tree it returns partial results marked TRUNCATED instead of running indefinitely.',
+      // A cooperative budget for @deepseek-ai/dsh-tool-call-timeout-policy.
+      // Only useful together with the cancellation support below: the policy can
+      // only *ask* a tool to stop, so a tool that ignores exec.signal would keep
+      // the caller waiting (issue #44).
+      timeoutMs: config.searchTimeoutMs,
       parameters: {
         pattern: { type: 'string', required: true, description: 'Pattern to search for (extended regex)' },
         path: { type: 'string', description: 'Directory to search (default: current remote workspace)' },
@@ -1791,6 +1843,8 @@ export async function apply(ctx, config) {
         ignoreCase: { type: 'boolean', description: 'Case-insensitive search (default true)' },
         contextLines: { type: 'integer', description: 'Lines of context around each match (default 0)' },
         maxMatches: { type: 'integer', description: 'Max matches to return (default 500)' },
+        maxEntries: { type: 'integer', description: 'Stop after scanning this many files (default 50000)' },
+        maxDurationMs: { type: 'integer', description: 'Stop after this many ms and return partial results (default 60000)' },
       },
       output: textOut,
       async execute(args, exec) {
@@ -1807,21 +1861,36 @@ export async function apply(ctx, config) {
           throw new Error('rw_search: bad pattern: ' + ((err && err.message) || err))
         }
         const maxMatches = Math.min(Math.max(Number(args.maxMatches) || 500, 1), 2000)
-        const matcher = ignoreMatcher()
-        const { matches, scanned, truncated } = await searchRemote(b.pool, dir, {
+        // Budgets. The SFTP walk had NO entry/duration cap before, so a search
+        // over a home directory could run for hours while the turn stayed
+        // `running` and cancel/steer did nothing (issue #44).
+        const maxFiles = Math.min(Math.max(Number(args.maxEntries) || config.searchMaxEntries, 1), 500000)
+        const maxDurationMs = Math.min(Math.max(Number(args.maxDurationMs) || config.searchTimeoutMs, 1000), 600000)
+        const matcher = searchIgnoreMatcher()
+        const { matches, scanned, truncated, cancelled } = await searchRemote(b.pool, dir, {
           pattern,
           regex,
           glob: args.glob,
           ignoreCase: args.ignoreCase !== false,
           contextLines: Math.min(Math.max(Number(args.contextLines) || 0, 0), 10),
           maxMatches,
+          maxFiles,
+          maxDurationMs,
+          signal: exec.signal,
           maxScanBytes: Math.min(config.maxFileBytes || 1024 * 1024, 1024 * 1024),
           isIgnored: (name, isDir) => matcher(name, isDir),
-          timeoutMs: config.commandTimeoutMs,
+          timeoutMs: Math.min(config.commandTimeoutMs, maxDurationMs),
         })
-        if (!matches.length) return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned)` }
+        const note = cancelled
+          ? `, CANCELLED after ${scanned} files scanned`
+          : truncated
+            ? ', TRUNCATED'
+            : ''
+        if (!matches.length) {
+          return { text: `no matches for /${pattern}/ in ${dir} (${scanned} files scanned${note})` }
+        }
         let text = matches.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n')
-        text += `\n(${matches.length} match(es), ${scanned} files scanned${truncated ? ', TRUNCATED' : ''})`
+        text += `\n(${matches.length} match(es), ${scanned} files scanned${note})`
         return { text: truncate(text, config.maxOutputChars) }
       },
     }),
@@ -2822,13 +2891,21 @@ export async function apply(ctx, config) {
           // a link:/dev install must not be overwritten by an npm publish.
           selfUpdateAllowed: isInstalledCopy(),
         }
-        const latest = await fetchLatestVersion()
-        if (latest === null) return sendJson(res, 200, { ok: false, ...base, error: '无法连接 npm registry' })
+        const probe = await fetchLatestVersion()
+        // 即使查不到最新版，也把**本地状态**照常返回（ok:true），只把 registry
+        // 的失败原因放在 registryError 里。
+        //
+        // 为什么：原先 registry 失败时整条响应 ok:false，客户端遇到 !ok 就只设错误
+        // 文案、不 setUpd，于是面板永远停在「版本信息加载中…」——看起来像卡死，
+        // 而实际上本地版本、更新模式、是否允许自更新都是已知的，完全可以展示。
+        if (probe.error) {
+          return sendJson(res, 200, { ok: true, ...base, latest: null, updateAvailable: false, registryError: probe.error, registryReason: probe.reason })
+        }
         return sendJson(res, 200, {
           ok: true,
           ...base,
-          latest,
-          updateAvailable: gtVersion(latest, loaded),
+          latest: probe.version,
+          updateAvailable: gtVersion(probe.version, loaded),
         })
       },
     },
@@ -2904,9 +2981,20 @@ export async function apply(ctx, config) {
   const rawMode = readUpdateMode() || config.updateMode || DEFAULT_UPDATE_MODE
   const effectiveUpdateMode = ['manual', 'auto', 'off'].includes(rawMode) ? rawMode : DEFAULT_UPDATE_MODE
   if (effectiveUpdateMode === 'auto') {
+    // 限流/网络失败后的退避：命中后跳过接下来若干轮检查，避免在被 npm 限流
+    // （HTTP 429）时反复重试把配额烧得更久。指数增长，上限 24 轮（配合默认
+    // 6h 间隔即最多约 6 天，足以让限流窗口滑过且不会永久停摆）。
+    let backoffRounds = 0
     const checkAndApply = async () => {
-      const latest = await fetchLatestVersion()
-      if (!latest) return
+      if (backoffRounds > 0) { backoffRounds -= 1; return }
+      const probe = await fetchLatestVersion()
+      if (probe.error) {
+        // 限流与网络故障都要退避；成功一次即重置。
+        backoffRounds = Math.min(backoffRounds === 0 ? 1 : backoffRounds * 2, 24)
+        return
+      }
+      backoffRounds = 0
+      const latest = probe.version
       // The version in flight is whichever of "already on disk" / "already
       // loaded" is newer. Pinning it once outside this closure (as v0.8.23 did)
       // made every later interval re-download and re-apply the same tarball,