dsh-remote 0.8.5 → 0.8.7

package/README.zh.md

@@ -1,179 +1,179 @@
-[English](./README.md) · **中文**
-
----
-
-# dsh-remote
-
-[![npm version](https://img.shields.io/npm/v/dsh-remote)](https://www.npmjs.com/package/dsh-remote)
-[![license](https://img.shields.io/github/license/flymysql/dsh-remote)](LICENSE)
-[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-7a)](https://github.com/topics/dsh-plugin)
-
-**为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）打造的远程工作助手。**
-
-维护多台 SSH 机器，然后在「选择工作区」时选一个**远程工作区**（或**本地工作区**），Agent 就能在不离开 harness 的情况下直接操作——列文件、读代码、在远程主机上跑构建/命令，并把远程目录镜像成一个真实的本地工作区对象。
-
-DSH 的 Web 界面刻意只监听 `127.0.0.1`（CLI 为安全拒绝 `--host 0.0.0.0`）。本插件反过来：**由你主动连出**到你维护的机器，选一个工作区，然后通过 DSH 原生的工作区 + 文件流来工作——**不改动 `dsh-workspace` 核心**。
-
-## 界面预览
-
-设置 → **远程工作区** —— 多机 SSH 列表（增/删/改/设为当前，密码本地保存、不回显）：
-
-<img src="https://cdn.jsdelivr.net/gh/flymysql/dsh-remote@main/docs/ui-settings-panel.png" alt="dsh-remote 设置页 — 多机列表（浅色主题，主机已打码）" width="720"/>
-
-原生 **「Add workspace / 选择工作区」** 流程 —— **居中弹窗**、两个 tab，**默认落在「本机」**；切到 **「远程」**：
-
-- **远程** —— 一个**机器下拉**；路径输入框**自动预填 `/` 并实时补全目录**（点选一个目录后**立即列出它的下一级**，像系统/VSCode 逐级选目录）；另外有**「浏览…」浮窗**，选中仅回填到输入框（不直接提交），你复核 / 修改后点「设为远程工作区」。
-
-真实截图（机器已打码为占位）：
-
-<img src="https://cdn.jsdelivr.net/gh/flymysql/dsh-remote@main/docs/ui-picker-panel.png" alt="dsh-remote 工作区选择 — 真实弹窗；默认本机 tab；远程：机器下拉 + 预填根路径 + 自动补全" width="720"/>
-
----
-
-## 功能
-
-- **多机 SSH** —— 可存任意多台主机（host/port/user + **私钥**或**密码**）。密码只存在本地，界面不回显；在设置里一键切当前机。
-- **双 tab 工作区选择器**（填充原生「Add workspace」流程）：
-  - **本机** —— 走 **host 端原生系统文件夹对话框**选本地目录（或直接输入本地路径）→ 直接成为普通 DSH 本地工作区（与本地工作区共存）。优先用 DSH 的 `directoryPicker` 服务，服务缺失时**回退到插件自持的原生选择器**（macOS `osascript` / Linux `zenity`→`kdialog`）——桌面启动路径上框架服务不注册也能用。
-  - **远程** —— 选择器是**居中弹窗**（窄侧边栏也不会被挤压）。先**选机器** → 路径框**自动预填 `/`** 并**实时补全**目录；**选中一个目录立即列出它下一级**（OS/VSCode 式级联）。另有 **「浏览…」浮层**（不透明、定高、内部滚动、跟随软链），选中**回填输入框不提交**，你复核/修改后再确定。确定会创建**真实本地镜像**（`$DSH_HOME/remote-workspaces/<host>-<user>-<port>/<basename>`；仅当同主机上**别的远端路径**已占用同名 basename 时才追加短路径 hash）→ harness 把它当真实工作区收养，同时 dsh-remote 通过 SFTP 保持同步。所选工作区会**持久化到该机器**，重启不丢。
-- **双向 SFTP 同步（增量）** —— `rw_sync`（远程→镜像）、`rw_push`（镜像→远程），本地镜像改动可回传机器。两者都会**跳过 size+mtime 未变化的文件**，并有**单文件大小上限**防误拉大二进制；目录遍历带**有界并发**。
-- **模型工具** —— `rw_info`、`rw_connect`、`rw_pick_workspace`、`rw_list_dir`、`rw_read_file`、`rw_write_file`、`rw_exec`（默认在工作区目录执行，可传 `cwd=`）、`rw_search`（可移植递归 grep）、`rw_download`、`rw_upload`、`rw_sync`、`rw_push`、`rw_disconnect`。
-- **直接写远程文件** —— `rw_write_file` 直接创建/覆盖远程文件（自动建父目录），单个文件改动不必绕本地镜像来回同步；`rw_download` / `rw_upload` 可单文件双向取真字节。
-- **连接体检** —— 设置页提供「测试连接」按钮，在保存机器之前先验证 host/user/密码/私钥是否可用。
-- 当前 `user@host:/path` 会注入每次系统提示，让 Agent 明确自己的工作根。
-- **远端跨平台** —— 命令全部用可移植 POSIX 写法（`ls -la` / `sed -n` / `find … -exec grep`），macOS/BSD 与 GNU/Linux 远端都能用。
-- **主机指纹校验（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` 的数据**首次启动自动迁移**，不丢失。
-- **不改任何 `dsh-workspace` 官方代码** —— 全部作为普通插件实现（client 半以 `priority -100` 填充 directory-flow holes）。
-
-## 安装
-
-```bash
-dsh plugin add dsh-remote            # 添加 bundle
-```
-
-一条命令装齐：从 **v0.7.2** 起，侧边栏
-（[dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)）是
-**硬依赖并自动挂载** —— 装完 dsh-remote 后，侧边栏里的「🌐 远程文件」目录树和
-远程文件查看器即可直接用，无需额外步骤。如果你已单独安装过该侧边栏，内嵌副本
-会自动退避（不会重复挂载）。
-
-> **要求 profile 的 pnpm linker 为 `hoisted`**（DSH profile 默认，
-> `pnpm-workspace.yaml` 里 `nodeLinker: hoisted`）。loader 从 profile 根解析
-> 插件包，侧边栏必须能在顶层 `node_modules` 被解析到。如果你的
-> `pnpm-workspace.yaml` 被重写丢掉了 `nodeLinker: hoisted`，请补回并执行一次
-> `pnpm install` —— 否则内嵌侧边栏行会报
-> `Cannot find package 'dsh-better-sidebar'`。
-
-（或 `npm install dsh-remote`，再在 `cordis.patch.yml` 加 `- id: dsh-remote / name: dsh-remote`。）
-
-## 快速上手
-
-1. **加一台机器** —— 设置 → 远程工作区 → 填 host/port/user + 密码或 key →（可选）设为当前。
-2. **选工作区** —— 点侧边栏/会话的 **Add workspace**：
-   - **本机** → 系统文件夹选择（或输入本地路径）→ 本地工作区。
-   - **远程** → 选机器 → 浏览到远程目录（或输入 `/path`）→ 「设为远程工作区」⇒ 创建并收养一个本地镜像工作区。
-3. **让 Agent 工作** —— 把它当普通工作区用：
-   - `rw_list_dir(path?)` / `rw_read_file` —— 查看远程文件
-   - `rw_write_file(path, content)` —— 直接创建或覆盖远程文件
-   - `rw_search(pattern, path?)` —— 远程 grep
-   - `rw_exec(command, cwd?)` —— 在远程执行命令（默认在工作区目录）
-   - `rw_sync` / `rw_push` —— 拉取/推送本地镜像 <-> 远程
-
-## 可选：CLI 默认机
-
-可在 `cordis.patch.yml` 提供默认机：
-
-```yaml
-# 示例：请换成你自己的机器
-- id: dsh-remote
-  name: dsh-remote
-  config:
-    host: 203.0.113.10   # 或你的真实主机 / hostname
-    port: 22
-    username: dev
-    privateKeyPath: ~/.ssh/id_rsa
-    # 或用密码登录：
-    # password: '…'
-    workspace: ~/project
-```
-
-若 `host` 为空，插件启动时处于断开状态，在 UI 里配置机器即可。
-
-## 常用命令（安装 / 查看 / 启动）
-
-DSH 的 `dsh` 可能不在某些 shell 的 PATH（比如 Windows PowerShell 里在某个仓库目录下），所以同时列出 `dsh` 与 `npx` 两种写法。操作都要用 `--profile <name>` 指定 profile（一般 `web`）：
-
-```bash
-# 安装（从 npm 拉到 profile）
-dsh plugin --profile web add dsh-remote
-# 同一效果：当 `dsh` 不在 PATH 时用 npx
-npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote
-
-# 确认已装
-dsh plugin --profile web list
-npx --yes @deepseek-ai/dsh plugin --profile web list
-
-# 启动 web 界面（重载 profile，新插件在启动时生效）
-dsh --profile web
-npx --yes @deepseek-ai/dsh --profile web   # 访问 http://127.0.0.1:3080
-
-# 迭代用本地源码替换 npm 版（便于改 dsh 插件代码后即测）
-npx --yes @deepseek-ai/dsh plugin --profile web add D:/path/to/dsh-remote
-npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # 恢复用发行版
-```
-
-启动成功后，设置 →「远程工作区」会出现；「Add workspace」流程会带「本机 / 远程」两个 tab（见上方效果图）。
-
-## 开发（沙箱优先，勿改产品）
-
-迭代**一律在沙箱**里做，绝不手工改产品 profile——产品 profile 由插件管理器重管，
-重装会把手工部署的文件还原掉。用仓库内的辅助脚本：
-
-```bash
-scripts/dev-run.sh --restart   # 启动 / 重启隔离沙箱
-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/*` 的解析。
-- 每次提交前跑 `scripts/check.mjs`（静态框架约束闸门：命令名正则等）；
-  `scripts/boot-smoke.sh` 用隔离实例证明插件仍能启动。
-- 完整规则见 `scripts/dev-standards.md`（命令名、cordis 服务只许 `ctx.get()`、
-  可选框架服务可能压根不注册、三方库回调契约以真实运行为准等）。
-
-部署到产品 profile 是单独的受控动作（`./sync.sh`），只在确定要发布时做。
-
-## 配置
-
-| 键 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `host` | string | `''` | 默认 SSH 主机（空=断开） |
-| `port` | int | `22` | 默认 SSH 端口 |
-| `username` | string | `''` | 默认 SSH 用户 |
-| `password` | string | `''` | 默认 SSH 密码（非空覆盖 key） |
-| `privateKeyPath` | string | `''` | 私钥路径（仅在显式提供时使用） |
-| `workspace` | string | `''` | 默认远程工作区路径 |
-| `commandTimeoutMs` | int | 20000 | 单条远程命令超时 |
-| `connectTimeoutMs` | int | 15000 | SSH 连接超时 |
-| `maxFileBytes` | int | 52428800 | 镜像同步时跳过超过该大小的文件（0=不设上限） |
-| `hostKeyMode` | string | `accept-new` | 主机指纹策略：`accept-new`（首次信任）、`verify`（拒绝未知主机）、`off`（跳过校验） |
-
-## 安全提醒
-
-把机器凭据交给插件，等于允许 Agent 以你的用户身份在主机上执行 **shell 命令**。只添加你可信的机器。密码保存在本机文件里，请当作敏感数据处理（可收紧文件 ACL）。
-
-## License
-
-MIT
-
-## 变更记录
-
+[English](./README.md) · **中文**
+
+---
+
+# dsh-remote
+
+[![npm version](https://img.shields.io/npm/v/dsh-remote)](https://www.npmjs.com/package/dsh-remote)
+[![license](https://img.shields.io/github/license/flymysql/dsh-remote)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-7a)](https://github.com/topics/dsh-plugin)
+
+**为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）打造的远程工作助手。**
+
+维护多台 SSH 机器，然后在「选择工作区」时选一个**远程工作区**（或**本地工作区**），Agent 就能在不离开 harness 的情况下直接操作——列文件、读代码、在远程主机上跑构建/命令，并把远程目录镜像成一个真实的本地工作区对象。
+
+DSH 的 Web 界面刻意只监听 `127.0.0.1`（CLI 为安全拒绝 `--host 0.0.0.0`）。本插件反过来：**由你主动连出**到你维护的机器，选一个工作区，然后通过 DSH 原生的工作区 + 文件流来工作——**不改动 `dsh-workspace` 核心**。
+
+## 界面预览
+
+设置 → **远程工作区** —— 多机 SSH 列表（增/删/改/设为当前，密码本地保存、不回显）：
+
+<img src="https://cdn.jsdelivr.net/gh/flymysql/dsh-remote@main/docs/ui-settings-panel.png" alt="dsh-remote 设置页 — 多机列表（浅色主题，主机已打码）" width="720"/>
+
+原生 **「Add workspace / 选择工作区」** 流程 —— **居中弹窗**、两个 tab，**默认落在「本机」**；切到 **「远程」**：
+
+- **远程** —— 一个**机器下拉**；路径输入框**自动预填 `/` 并实时补全目录**（点选一个目录后**立即列出它的下一级**，像系统/VSCode 逐级选目录）；另外有**「浏览…」浮窗**，选中仅回填到输入框（不直接提交），你复核 / 修改后点「设为远程工作区」。
+
+真实截图（机器已打码为占位）：
+
+<img src="https://cdn.jsdelivr.net/gh/flymysql/dsh-remote@main/docs/ui-picker-panel.png" alt="dsh-remote 工作区选择 — 真实弹窗；默认本机 tab；远程：机器下拉 + 预填根路径 + 自动补全" width="720"/>
+
+---
+
+## 功能
+
+- **多机 SSH** —— 可存任意多台主机（host/port/user + **私钥**或**密码**）。密码只存在本地，界面不回显；在设置里一键切当前机。
+- **双 tab 工作区选择器**（填充原生「Add workspace」流程）：
+  - **本机** —— 走 **host 端原生系统文件夹对话框**选本地目录（或直接输入本地路径）→ 直接成为普通 DSH 本地工作区（与本地工作区共存）。优先用 DSH 的 `directoryPicker` 服务，服务缺失时**回退到插件自持的原生选择器**（macOS `osascript` / Linux `zenity`→`kdialog`）——桌面启动路径上框架服务不注册也能用。
+  - **远程** —— 选择器是**居中弹窗**（窄侧边栏也不会被挤压）。先**选机器** → 路径框**自动预填 `/`** 并**实时补全**目录；**选中一个目录立即列出它下一级**（OS/VSCode 式级联）。另有 **「浏览…」浮层**（不透明、定高、内部滚动、跟随软链），选中**回填输入框不提交**，你复核/修改后再确定。确定会创建**真实本地镜像**（`$DSH_HOME/remote-workspaces/<host>-<user>-<port>/<basename>`；仅当同主机上**别的远端路径**已占用同名 basename 时才追加短路径 hash）→ harness 把它当真实工作区收养，同时 dsh-remote 通过 SFTP 保持同步。所选工作区会**持久化到该机器**，重启不丢。
+- **双向 SFTP 同步（增量）** —— `rw_sync`（远程→镜像）、`rw_push`（镜像→远程），本地镜像改动可回传机器。两者都会**跳过 size+mtime 未变化的文件**，并有**单文件大小上限**防误拉大二进制；目录遍历带**有界并发**。
+- **模型工具** —— `rw_info`、`rw_connect`、`rw_pick_workspace`、`rw_list_dir`、`rw_read_file`、`rw_write_file`、`rw_exec`（默认在工作区目录执行，可传 `cwd=`）、`rw_search`（可移植递归 grep）、`rw_download`、`rw_upload`、`rw_sync`、`rw_push`、`rw_disconnect`。
+- **直接写远程文件** —— `rw_write_file` 直接创建/覆盖远程文件（自动建父目录），单个文件改动不必绕本地镜像来回同步；`rw_download` / `rw_upload` 可单文件双向取真字节。
+- **连接体检** —— 设置页提供「测试连接」按钮，在保存机器之前先验证 host/user/密码/私钥是否可用。
+- 当前 `user@host:/path` 会注入每次系统提示，让 Agent 明确自己的工作根。
+- **远端跨平台** —— 命令全部用可移植 POSIX 写法（`ls -la` / `sed -n` / `find … -exec grep`），macOS/BSD 与 GNU/Linux 远端都能用。
+- **主机指纹校验（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` 的数据**首次启动自动迁移**，不丢失。
+- **不改任何 `dsh-workspace` 官方代码** —— 全部作为普通插件实现（client 半以 `priority -100` 填充 directory-flow holes）。
+
+## 安装
+
+```bash
+dsh plugin add dsh-remote            # 添加 bundle
+```
+
+一条命令装齐：从 **v0.7.2** 起，侧边栏
+（[dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)）是
+**硬依赖并自动挂载** —— 装完 dsh-remote 后，侧边栏里的「🌐 远程文件」目录树和
+远程文件查看器即可直接用，无需额外步骤。如果你已单独安装过该侧边栏，内嵌副本
+会自动退避（不会重复挂载）。
+
+> **要求 profile 的 pnpm linker 为 `hoisted`**（DSH profile 默认，
+> `pnpm-workspace.yaml` 里 `nodeLinker: hoisted`）。loader 从 profile 根解析
+> 插件包，侧边栏必须能在顶层 `node_modules` 被解析到。如果你的
+> `pnpm-workspace.yaml` 被重写丢掉了 `nodeLinker: hoisted`，请补回并执行一次
+> `pnpm install` —— 否则内嵌侧边栏行会报
+> `Cannot find package 'dsh-better-sidebar'`。
+
+（或 `npm install dsh-remote`，再在 `cordis.patch.yml` 加 `- id: dsh-remote / name: dsh-remote`。）
+
+## 快速上手
+
+1. **加一台机器** —— 设置 → 远程工作区 → 填 host/port/user + 密码或 key →（可选）设为当前。
+2. **选工作区** —— 点侧边栏/会话的 **Add workspace**：
+   - **本机** → 系统文件夹选择（或输入本地路径）→ 本地工作区。
+   - **远程** → 选机器 → 浏览到远程目录（或输入 `/path`）→ 「设为远程工作区」⇒ 创建并收养一个本地镜像工作区。
+3. **让 Agent 工作** —— 把它当普通工作区用：
+   - `rw_list_dir(path?)` / `rw_read_file` —— 查看远程文件
+   - `rw_write_file(path, content)` —— 直接创建或覆盖远程文件
+   - `rw_search(pattern, path?)` —— 远程 grep
+   - `rw_exec(command, cwd?)` —— 在远程执行命令（默认在工作区目录）
+   - `rw_sync` / `rw_push` —— 拉取/推送本地镜像 <-> 远程
+
+## 可选：CLI 默认机
+
+可在 `cordis.patch.yml` 提供默认机：
+
+```yaml
+# 示例：请换成你自己的机器
+- id: dsh-remote
+  name: dsh-remote
+  config:
+    host: 203.0.113.10   # 或你的真实主机 / hostname
+    port: 22
+    username: dev
+    privateKeyPath: ~/.ssh/id_rsa
+    # 或用密码登录：
+    # password: '…'
+    workspace: ~/project
+```
+
+若 `host` 为空，插件启动时处于断开状态，在 UI 里配置机器即可。
+
+## 常用命令（安装 / 查看 / 启动）
+
+DSH 的 `dsh` 可能不在某些 shell 的 PATH（比如 Windows PowerShell 里在某个仓库目录下），所以同时列出 `dsh` 与 `npx` 两种写法。操作都要用 `--profile <name>` 指定 profile（一般 `web`）：
+
+```bash
+# 安装（从 npm 拉到 profile）
+dsh plugin --profile web add dsh-remote
+# 同一效果：当 `dsh` 不在 PATH 时用 npx
+npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote
+
+# 确认已装
+dsh plugin --profile web list
+npx --yes @deepseek-ai/dsh plugin --profile web list
+
+# 启动 web 界面（重载 profile，新插件在启动时生效）
+dsh --profile web
+npx --yes @deepseek-ai/dsh --profile web   # 访问 http://127.0.0.1:3080
+
+# 迭代用本地源码替换 npm 版（便于改 dsh 插件代码后即测）
+npx --yes @deepseek-ai/dsh plugin --profile web add D:/path/to/dsh-remote
+npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # 恢复用发行版
+```
+
+启动成功后，设置 →「远程工作区」会出现；「Add workspace」流程会带「本机 / 远程」两个 tab（见上方效果图）。
+
+## 开发（沙箱优先，勿改产品）
+
+迭代**一律在沙箱**里做，绝不手工改产品 profile——产品 profile 由插件管理器重管，
+重装会把手工部署的文件还原掉。用仓库内的辅助脚本：
+
+```bash
+scripts/dev-run.sh --restart   # 启动 / 重启隔离沙箱
+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/*` 的解析。
+- 每次提交前跑 `scripts/check.mjs`（静态框架约束闸门：命令名正则等）；
+  `scripts/boot-smoke.sh` 用隔离实例证明插件仍能启动。
+- 完整规则见 `scripts/dev-standards.md`（命令名、cordis 服务只许 `ctx.get()`、
+  可选框架服务可能压根不注册、三方库回调契约以真实运行为准等）。
+
+部署到产品 profile 是单独的受控动作（`./sync.sh`），只在确定要发布时做。
+
+## 配置
+
+| 键 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `host` | string | `''` | 默认 SSH 主机（空=断开） |
+| `port` | int | `22` | 默认 SSH 端口 |
+| `username` | string | `''` | 默认 SSH 用户 |
+| `password` | string | `''` | 默认 SSH 密码（非空覆盖 key） |
+| `privateKeyPath` | string | `''` | 私钥路径（仅在显式提供时使用） |
+| `workspace` | string | `''` | 默认远程工作区路径 |
+| `commandTimeoutMs` | int | 20000 | 单条远程命令超时 |
+| `connectTimeoutMs` | int | 15000 | SSH 连接超时 |
+| `maxFileBytes` | int | 52428800 | 镜像同步时跳过超过该大小的文件（0=不设上限） |
+| `hostKeyMode` | string | `accept-new` | 主机指纹策略：`accept-new`（首次信任）、`verify`（拒绝未知主机）、`off`（跳过校验） |
+
+## 安全提醒
+
+把机器凭据交给插件，等于允许 Agent 以你的用户身份在主机上执行 **shell 命令**。只添加你可信的机器。密码保存在本机文件里，请当作敏感数据处理（可收紧文件 ACL）。
+
+## License
+
+MIT
+
+## 变更记录
+
 见 [CHANGELOG.md](./CHANGELOG.md)。

package/cordis.patch.yml

@@ -1,24 +1,53 @@
-# dsh-remote bundle patch: inserts this plugin into a profile's layer stack.
-# Applied when a profile lists this bundle; rows reference the package by name so
-# Node resolution finds the installed code.
-#
-# Since v0.7.2 dsh-remote ships dsh-better-sidebar as a hard dependency and
-# mounts it here, so `dsh plugin add dsh-remote` brings up the sidebar with
-# zero extra steps. The sidebar row uses a DEDICATED id (`dsh-remote-sidebar`)
-# and a guard so it backs off when another entry already mounts
-# `dsh-better-sidebar` (e.g. the user installed the sidebar bundle on its own,
-# or an aggregate bundle owns it) — two enabled mounts would both register
-# /sidebar/api and fail the whole plugin tree at boot.
-#
-# The guard checks EXISTENCE only (id + name), never the `disabled` property of
-# other rows: reading another row's disabled inside this row's disabled
-# expression would recursively re-enter the loader and overflow the stack
-# (dsh-better-sidebar's own row carries a disabled expression too, so the two
-# would ping-pong). Existence is sufficient — the standalone row is only ever
-# created when the user (or an aggregate bundle) explicitly mounts the sidebar.
-- insert:
-    - id: dsh-remote
-      name: 'dsh-remote'
-    - id: dsh-remote-sidebar
-      name: 'dsh-better-sidebar'
-      disabled: !!js "[...ctx.loader.entries()].some((e) => e.options.name === 'dsh-better-sidebar' && e.options.id !== 'dsh-remote-sidebar')"
+# dsh-remote bundle patch: inserts this plugin into a profile's layer stack.
+# Applied when a profile lists this bundle; rows reference the package by name so
+# Node resolution finds the installed code.
+#
+# Since v0.7.2 dsh-remote ships dsh-better-sidebar as a hard dependency and
+# mounts it here, so `dsh plugin add dsh-remote` brings up the sidebar with
+# zero extra steps. The sidebar row uses a DEDICATED id (`dsh-remote-sidebar`)
+# and a guard so it backs off when another row mounts `dsh-better-sidebar`
+# (e.g. the user installed the sidebar bundle on its own, or an aggregate
+# bundle owns it) — two enabled mounts would both register /sidebar/api and
+# fail the whole plugin tree at boot.
+#
+# Order-independence (issue #12): the guard must NOT depend on
+# `ctx.loader.entries()` creation order. The loader creates entries in bundle
+# order and each row's disabled expression is evaluated at creation time, when
+# only rows created BEFORE it are visible — so with
+# `bundles: [..., "dsh-remote", "dsh-better-sidebar", ...]` (standalone sidebar
+# installed after dsh-remote, the normal `dsh plugin add` append order) both
+# rows saw no other sidebar mount and BOTH started, crashing boot with
+# `duplicate prefix route "/sidebar/api"`.
+#
+# Instead we scan the COMPOSED PATCH STACK — the include entry's
+# `config.patches` (every bundle layer in `dsh.profile.bundles` order, then the
+# profile/home/overlay layers) — for any OTHER row that mounts
+# `dsh-better-sidebar`. That data is fully materialized before any row guard
+# evaluates, so the outcome is identical no matter where the standalone bundle
+# sits in the bundle list. It is also pure data: it never reads another row's
+# `disabled` (reading another row's disabled expression would recursively
+# re-enter the loader — dsh-better-sidebar's own row carries one too, so the
+# two would ping-pong), so no recursion is possible. The old entries()-based
+# check is kept as a belt-and-suspenders fallback for rows not visible in the
+# patch stack (e.g. an entry injected at runtime by HMR or another plugin).
+- insert:
+    - id: dsh-remote
+      name: 'dsh-remote'
+    - id: dsh-remote-sidebar
+      name: 'dsh-better-sidebar'
+      disabled: !!js >-
+        (function () {
+          try {
+            const inc = ctx.loader && ctx.loader.resolve && ctx.loader.resolve('include')
+            const patches = inc && inc.subtree && inc.subtree.config && inc.subtree.config.patches
+            if (Array.isArray(patches)) {
+              for (const p of patches) {
+                if (!p || !Array.isArray(p.insert)) continue
+                for (const row of p.insert) {
+                  if (row && row.name === 'dsh-better-sidebar' && row.id !== 'dsh-remote-sidebar') return true
+                }
+              }
+            }
+          } catch (e) {}
+          return [...ctx.loader.entries()].some((e) => e.options.name === 'dsh-better-sidebar' && e.options.id !== 'dsh-remote-sidebar')
+        })()

package/lib/client.js

@@ -379,7 +379,7 @@ window.__ModuleLoader__.load({
           React.createElement('a', { href: 'https://github.com/flymysql/dsh-remote', target: '_blank', rel: 'noopener noreferrer', style: { color: 'inherit' } }, '⭐ 去 GitHub 点个 Star'),
           React.createElement('span', {}, '·'),
           React.createElement('a', { href: 'https://github.com/flymysql/dsh-remote/issues/new', target: '_blank', rel: 'noopener noreferrer', style: { color: 'inherit' } }, '💬 反馈建议 / 提 issue'),
-          React.createElement('span', { style: { marginLeft: 'auto', opacity: 0.5 } }, 'dsh-remote v0.8.3'),
+          React.createElement('span', { style: { marginLeft: 'auto', opacity: 0.5 } }, 'dsh-remote v' + (upd && upd.current ? upd.current : '?.?.?')),
         ),
       )
     }
@@ -436,6 +436,9 @@ window.__ModuleLoader__.load({
       const [suggest, setSuggest] = React.useState([])
       const [suggestOpen, setSuggestOpen] = React.useState(false)
       const [recent, setRecent] = React.useState([])
+      // 本机浏览浮层（browse 后端）：{ path, home, crumbs, entries, truncated }。
+      const [localPop, setLocalPop] = React.useState(null)
+      const [newDirName, setNewDirName] = React.useState('')
       const suggestTimer = React.useRef(null)
       const suggestRef = React.useRef(null)
       React.useEffect(() => {
@@ -485,6 +488,7 @@ window.__ModuleLoader__.load({
       }
 
       React.useEffect(() => { if (open) {
+        setLocalPop(null); setNewDirName('')
         api('GET', '/dsh-remote/machines').then((r) => {
           setMachines(r.machines || [])
           const cur = (r.machines || []).find((m) => m.id === r.currentId)
@@ -493,16 +497,45 @@ window.__ModuleLoader__.load({
         })
       } }, [open])
 
+      // 本机目录浏览（browse 后端兜底）：列出 path 的子目录；path 为空 → 宿主家目录。
+      const loadLocal = (p) => {
+        setLoading(true); setErr('')
+        api('GET', '/dsh-remote/local-list' + (p ? '?path=' + encodeURIComponent(p) : ''))
+          .then((r) => setLocalPop({ path: (r && r.path) || p || '', home: (r && r.home) || '', crumbs: (r && r.crumbs) || [], entries: (r && r.entries) || [], truncated: !!(r && r.truncated), drives: (r && r.drives) || [] }))
+          .catch((e) => setErr(String((e && e.message) || e)))
+          .finally(() => setLoading(false))
+      }
+
       const chooseLocal = () => {
         setLoading(true); setErr('')
         api('POST', '/dsh-remote/local-pick')
           .then((r) => {
-            if (r && r.path) onPicked(String(r.path))
-            else if (r && r.cancelled) setErr('已取消选择')
-            else setErr((r && r.error) || '无法打开系统文件夹选择器，可直接在输入框填本地路径')
+            if (r && r.path) { setLoading(false); onPicked(String(r.path)) }
+            // browse 后端（DSH Desktop / 无显示的远程宿主）：没有 OS 对话框可开
+            // → 打开内置本机目录浏览器。
+            else if (r && r.kind === 'browse') loadLocal('')
+            else if (r && r.cancelled) { setLoading(false); setErr('已取消选择') }
+            else { setLoading(false); setErr((r && r.error) || '无法打开系统文件夹选择器，可直接在输入框填本地路径') }
           })
-          .catch((e) => setErr(String((e && e.message) || e) + ' — 可直接在输入框填本地路径'))
-          .finally(() => setLoading(false))
+          .catch((e) => { setLoading(false); setErr(String((e && e.message) || e) + ' — 可直接在输入框填本地路径') })
+      }
+
+      // 在浮层当前目录下新建文件夹（browse 后端 createDirectory），成功后刷新列表。
+      const mkdirLocal = () => {
+        const cur = localPop
+        const name = newDirName.trim()
+        if (!cur || !cur.path || !name || loading) return
+        setLoading(true); setErr('')
+        api('POST', '/dsh-remote/local-mkdir', { path: cur.path, name })
+          .then(() => { setNewDirName(''); loadLocal(cur.path) })
+          .catch((e) => { setErr(String((e && e.message) || e)); setLoading(false) })
+      }
+
+      // 选用浮层中的本机目录：回填输入框（不直接提交），复核后再点「选用此本地路径」。
+      const acceptLocalPick = (p) => {
+        setPath(String(p || ''))
+        setErr('')
+        setLocalPop(null)
       }
 
       const switchTab = (t) => {
@@ -612,6 +645,77 @@ window.__ModuleLoader__.load({
           .catch((e) => setErr(String((e && e.message) || e)))
       }
 
+      // 本机浏览浮层的面包屑：browse 后端给出完整祖先链（含盘符根），可点击跳转。
+      const localCrumbs = (cur) => {
+        const crumbs = (cur && cur.crumbs) || []
+        if (!crumbs.length) return React.createElement('span', null, '/')
+        const out = []
+        crumbs.forEach((c, i) => {
+          if (i > 0) out.push(React.createElement('span', { key: 'sep' + i, style: { color: T.muted } }, ' › '))
+          out.push(React.createElement('span', {
+            key: c.path || i,
+            title: c.path,
+            onClick: () => loadLocal(c.path),
+            style: { cursor: 'pointer', color: i === crumbs.length - 1 ? T.label : T.ok, fontWeight: i === crumbs.length - 1 ? 700 : 400 },
+          }, c.name))
+        })
+        return React.createElement('span', null, out)
+      }
+
+      // 本机目录浏览浮层（browse 后端）：进入子目录 / 面包屑跳转 / 回家目录 /
+      // 新建文件夹 / 选用回填。与远程浏览弹层同一套交互。
+      function renderLocalPopup() {
+        const cur = localPop
+        if (!cur) return null
+        const crumbs = cur.crumbs || []
+        const parent = crumbs.length >= 2 ? crumbs[crumbs.length - 2].path : null
+        return React.createElement('div', {
+          style: { position: 'fixed', inset: 0, zIndex: 9999, background: 'rgba(0,0,0,0.5)', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 12 },
+          onClick: () => setLocalPop(null),
+        },
+          React.createElement('div', { style: { background: v('--dsw-alias-bg-overlay', '#1e1e1e'), border: '1px solid ' + T.borderStrong, borderRadius: 10, boxShadow: '0 10px 40px rgba(0,0,0,0.5)', width: 'min(560px, 94vw)', minWidth: 320, display: 'flex', flexDirection: 'column', maxHeight: 'min(460px, 84vh)', overflow: 'hidden' }, onClick: (e) => e.stopPropagation() },
+            React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center', padding: '8px 12px', borderBottom: '1px solid ' + T.border } },
+              React.createElement('button', { style: { ...buttonS, padding: '3px 10px' }, onClick: () => parent && loadLocal(parent), disabled: !parent || loading, title: parent || '' }, '回上一级 ▴'),
+              cur.home ? React.createElement('button', { style: { ...buttonS, padding: '3px 8px' }, onClick: () => loadLocal(cur.home), disabled: loading, title: cur.home }, '🏠') : null,
+              React.createElement('div', { style: { fontSize: 11, opacity: 0.75, fontFamily: 'monospace', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', flex: 1 } }, localCrumbs(cur)),
+              React.createElement('button', { style: { ...buttonS, padding: '3px 10px' }, onClick: () => setLocalPop(null) }, '关闭 ✕'),
+            ),
+            // 盘符切换行（Windows 无统一根目录，browse 面包屑到不了其他盘）。
+            (cur.drives && cur.drives.length > 1) ? React.createElement('div', { style: { display: 'flex', gap: 4, flexWrap: 'wrap', padding: '6px 12px', borderBottom: '1px solid ' + T.border } },
+              cur.drives.map((d) => {
+                const active = String(cur.path).toUpperCase().startsWith(String(d.name).toUpperCase())
+                return React.createElement('button', {
+                  key: d.path,
+                  onClick: () => loadLocal(d.path),
+                  disabled: loading,
+                  title: d.path,
+                  style: { ...buttonS, padding: '2px 8px', fontSize: 11, fontFamily: 'monospace', fontWeight: active ? 700 : 400, color: active ? T.ok : T.label },
+                }, d.name)
+              }),
+            ) : null,
+            React.createElement('div', { style: { overflowY: 'auto', overflowX: 'hidden' } },
+              loading ? React.createElement('div', { style: { opacity: 0.7, padding: 12 } }, '加载中…')
+                : (cur.entries.length ? cur.entries.slice(0, 400).map((it, i) => React.createElement('div', {
+                    key: it.path || i, title: '进入 ' + it.name,
+                    onClick: () => loadLocal(it.path),
+                    style: { padding: '7px 12px', cursor: 'pointer', color: T.label, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', display: 'flex', gap: 8, alignItems: 'center', fontSize: 13, borderBottom: '1px solid ' + T.border },
+                  },
+                    React.createElement('span', null, '📁'),
+                    React.createElement('span', { style: { overflow: 'hidden', textOverflow: 'ellipsis' } }, it.name),
+                  )) : React.createElement('div', { style: { opacity: 0.6, padding: 12 } }, '（没有子目录 — 可直接选用当前目录）')),
+              cur.truncated ? React.createElement('div', { style: { opacity: 0.6, padding: '6px 12px', fontSize: 11 } }, '（条目过多已截断）') : null,
+            ),
+            err ? React.createElement('div', { style: { color: T.danger, fontSize: 12, padding: '4px 12px' } }, err) : null,
+            React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center', padding: '8px 12px', borderTop: '1px solid ' + T.border } },
+              React.createElement('input', { value: newDirName, onChange: (e) => setNewDirName(e.target.value), placeholder: '新建文件夹', style: { ...inputS, width: 110, flex: '0 0 auto', padding: '4px 8px', fontSize: 12 } }),
+              React.createElement('button', { style: { ...buttonS, padding: '4px 10px', whiteSpace: 'nowrap' }, onClick: mkdirLocal, disabled: loading || !newDirName.trim() || !cur.path }, '新建'),
+              React.createElement('span', { style: { fontSize: 11, opacity: 0.75, fontFamily: 'monospace', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', flex: 1 } }, '所选: ' + cur.path),
+              React.createElement('button', { style: { ...buttonS, fontWeight: 600, whiteSpace: 'nowrap' }, onClick: () => acceptLocalPick(cur.path) }, '选用此路径'),
+            ),
+          ),
+        )
+      }
+
       function renderDirPopup() {
         if (!levels || !levels.length) {
           return React.createElement('div', { style: { opacity: 0.6, fontSize: 12 } }, (loading ? '加载中…' : '正在读取根目录…'))
@@ -660,13 +764,14 @@ window.__ModuleLoader__.load({
         ),
         tab === 'local'
           ? React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8 } },
-              React.createElement('div', { style: { fontSize: 12, opacity: 0.8 } }, '系统选择器优先；不可用时直接输入本机目录。'),
+              React.createElement('div', { style: { fontSize: 12, opacity: 0.8 } }, '弹出系统文件夹对话框选择；不可用时用内置目录浏览，也可直接输入本机目录。'),
               React.createElement('div', { style: { display: 'flex', gap: 6 } },
                 React.createElement('input', { value: path, onChange: (e) => setPath(e.target.value), placeholder: '本机目录，如 C:\\Users\\you\\project', style: inputS }),
                 React.createElement('button', { style: buttonS, onClick: () => (path.trim() ? onPicked(path) : undefined), disabled: !path.trim() }, '选用此本地路径'),
               ),
               React.createElement('button', { style: { ...buttonS, alignSelf: 'flex-start' }, onClick: chooseLocal, disabled: loading }, loading ? '打开中…' : '打开系统文件夹选择器'),
               err ? React.createElement('div', { style: { color: T.danger, fontSize: 12 } }, err) : null,
+              localPop ? renderLocalPopup() : null,
             )
           : React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 8, minHeight: 0, overflowY: 'auto' } },
               React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center' } },