dsh-remote 0.4.5 → 0.5.1

package/README.md

@@ -1,86 +1,113 @@
-# dsh-remote
-
-Remote-work assistant for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).
-
-Connect an SSH host, pick a **remote workspace** directory, and let the agent operate on it — list dirs, read files, run commands — without leaving the harness.
-
-The harness Web UI intentionally binds `127.0.0.1` (the CLI rejects `--host 0.0.0.0` for safety). This plugin goes the other way: **you connect out** to a remote host over SSH and work in a remote directory.
-
-## What it gives you
-
-- **Connect** a remote host with **password or SSH key** (SSH/SFTP via `ssh2`).
-- **Pick a remote workspace** — a remote directory the active session treats as its project root.
-- **Model tools** — `rw_info`, `rw_connect`, `rw_pick_workspace`, `rw_list_dir`, `rw_read_file`, `rw_exec`, `rw_sync`.
-- **Local mirror** — picking a remote workspace also creates a **real local directory** (`~/.dsh/remote-workspaces/<host>/<base>-<hash>`) that mirrors it over SFTP. Because that path passes `fs.realpath`, the DSH **native workspace selector** can pick it and `createWorkspace({ path })` adopts it — so the browser/Session workspace sees the remote project as a normal local workspace, while dsh-remote keeps it in sync with the remote.
-- **Settings → 远程工作区** — enter host/login, connect, browse the remote filesystem, set the workspace, all from the UI.
-- The current remote workspace (`user@host:/path`) is injected into every system prompt so the agent knows the working root.
-
-## Install
-
-```bash
-dsh plugin --profile web add dsh-remote
-```
-
-(adds the bundle; the row is `id: dsh-remote`, `name: dsh-remote`).
-
-## Usage
-
-### 1. Configure a default host (optional)
-
-In `cordis.patch.yml`:
-
-```yaml
-- id: dsh-remote
-  name: dsh-remote
-  config:
-    host: 10.0.0.8
-    port: 22
-    username: dev
-    privateKeyPath: C:/Users/you/.ssh/id_rsa
-    # OR use password login:
-    # password: '…'
-    workspace: /home/dev/project
-```
-
-If `host` is empty the plugin starts disconnected and you connect at runtime.
-
-### 2. Connect + pick a workspace
-
-- **From the UI**: Settings → 远程工作区 → enter host/port/user + (password or key path) → **连接远程** → type a remote path and **设为远程工作区** (or **列目录** to browse).
-- **From the agent**: ask it to `rw_connect(host)`, then `rw_pick_workspace(path=/…/project)`. You can also use `/remote` to see the current status.
-
-### 3. Work in the remote workspace
-
-The agent uses:
-
-```
-rw_list_dir(path?)      # list a remote dir (defaults to the workspace)
-rw_read_file(path=-…)   # read a remote file (paged)
-rw_exec(command=…)      # run any shell command on the remote
-```
-
-Because the workspace path is in the system prompt, the agent treats it as the working root and combines these tools to inspect/build/test the remote project.
-
-## Configuration
-
-| Key | Type | Default | Meaning |
-| --- | --- | --- | --- |
-| `host` | string | `''` | Remote SSH host (empty = start disconnected) |
-| `port` | int | `22` | Remote SSH port |
-| `username` | string | `''` | SSH login user |
-| `password` | string | `''` | SSH password (overrides the key when non-empty) |
-| `privateKeyPath` | string | `''` | Absolute key path; empty → `~/.ssh/id_rsa` |
-| `passphrase` | string | `''` | Key passphrase if encrypted |
-| `workspace` | string | `''` | Initial remote workspace dir |
-| `commandTimeoutMs` | int | 20000 | Per remote command timeout |
-| `connectTimeoutMs` | int | 15000 | SSH connect timeout |
-
-## Browser page
-
-Settings → 远程工作区: connect form (host/port/user/password|key), directory browse (`/dsh-remote/ls`), and "设为远程工作区" (`/dsh-remote/workspace`). All same-origin JSON routes on the harness `webServer`; the SSH pool lives in the host half, so credentials are only posted to loopback.
-
-**Safety note**: giving the plugin remote credentials lets the agent run shell commands on that host **as your user**. Grant only on hosts you trust.
-
-## License
-
+# dsh-remote
+
+**Remote-work assistant for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).**
+
+Manage several SSH machines, then pick a **remote workspace** (or a **local** one) and let the agent operate right there without leaving the harness — listing files, reading code, running builds & commands over the remote host, and keeping that remote directory mirrored into a real local workspace object.
+
+The harness Web UI intentionally binds `127.0.0.1` (the CLI rejects `--host 0.0.0.0` for safety). This plugin goes the other way: **you connect out** to the machines you maintain, pick a workspace, and work in it through the normal DSH workspace + agent fs flows — no changes to `dsh-workspace` or the harness core.
+
+## Screen previews
+
+Settings → **远程工作区** — a multi-machine SSH registry (add / edit / delete / set-current, password stored locally):
+
+<img src="./docs/ui-settings.svg" alt="dsh-remote settings — multi-machine registry" width="720"/>
+
+The native **"Add workspace" / "Select workspace"** flow — one dialog, two tabs (本地 local / 远程 remote):
+
+<img src="./docs/ui-picker.svg" alt="dsh-remote workspace picker — 本机 (native OS folder) + 远程 (machine → directory)" width="720"/>
+
+---
+
+## Features
+
+- **Multi-machine SSH** — save any number of hosts (`host`/`port`/`user` + **private key** or **password**). Passwords are stored locally and never shown back in the UI. Switch with one click in Settings.
+- **Two-tab workspace picker** (fills the native "Add workspace" flow):
+  - **本机 / Local** — opens the **native OS folder chooser** over the host, or lets you type a local path → adopted directly as a normal DSH local workspace (local workspaces fully coexist).
+  - **远程 / Remote** — pick a **machine**, then browse its directories (or type a path) 🡺 on confirm it creates a **real local mirror** (`~/.dsh/remote-workspaces/<host>/<base>-<hash>`) that passes `fs.realpath` → the harness adopts it as a real workspace while dsh-remote keeps it synced over SFTP.
+- **Bidirectional SFTP sync** — `rw_sync` (remote → mirror) and `rw_push` (mirror → remote) round-trip your local-mirror edits back to the machine.
+- **Model tools** — `rw_info`, `rw_connect`, `rw_pick_workspace`, `rw_list_dir`, `rw_read_file`, `rw_exec`, `rw_sync`, `rw_push`.
+- The active `user@host:/path` is injected into every system prompt so the agent knows its working root.
+- **No official `dsh-workspace` core is modified** — everything is delivered as a normal plugin (directory-flow holes filled by the client half at `priority -100`).
+
+## Install
+
+```bash
+dsh plugin add dsh-remote            # add the bundle
+```
+
+(or `npm install dsh-remote` + add `- id: dsh-remote / name: dsh-remote` in `cordis.patch.yml`).
+
+## Quick start
+
+1. **Add a machine** — Settings → 远程工作区 → add host/port/user + key or password → (optional) set it current.
+2. **Open a workspace** — click **Add workspace** in the sidebar / conversation:
+   - **本机** → system folder chooser (or type a local path) → local workspace.
+   - **远程** → choose the machine → browse to a remote directory (or type `/path`) → "设为远程工作区" ⇒ a local mirror workspace is created and adopted.
+3. **Work with the agent** — treat it like any workspace:
+   - `rw_list_dir(path?)`/`rw_read_file` — inspect remote files
+   - `rw_exec(command)` — run remote shell commands
+   - `rw_sync` / `rw_push` — pull/push the local mirror to and from the remote
+
+## CLI defaults (optional)
+
+Provide a default machine in `cordis.patch.yml`:
+
+```yaml
+- id: dsh-remote
+  name: dsh-remote
+  config:
+    host: 10.0.0.8
+    port: 22
+    username: dev
+    privateKeyPath: C:/Users/you/.ssh/id_rsa
+    # or password: '…'
+    workspace: /home/dev/project
+```
+
+If `host` is empty the plugin starts disconnected and you configure machines in the UI.
+
+## CLI quick reference
+
+Installing and driving DSH may live in different shells, so both the `dsh` binary and the `npx` form are shown. Always tell DSH **which profile** to use with `--profile <name>` (usually `web`).
+
+```bash
+# install the bundle into a profile (npm is pulled by pnpm; recommended)
+dsh plugin --profile web add dsh-remote
+# same but when `dsh` is not on PATH (e.g. Windows PowerShell inside a repo)
+npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote
+
+# confirm it is installed wire
+dsh plugin --profile web list
+npx --yes @deepseek-ai/dsh plugin --profile web list
+
+# start the web surface (reload profile; the plugin activates on boot)
+dsh --profile web
+npx --yes @deepseek-ai/dsh --profile web   # http://127.0.0.1:3080
+
+# use a local checkout instead of the npm version (dev iteration)
+npx --yes @deepseek-ai/dsh plugin --profile web add D:/work/dsh-community/dsh-remote
+npx --yes @deepseek-ai/dsh plugin --profile web remove dsh-remote   # back to release
+```
+
+After a successful start, `Settings → 远程工作区` appears and the "Add workspace" flow gains the 本机 / 远程 tabs (screenshots above).
+
+## Configuration
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | string | `''` | default SSH host (else start disconnected) |
+| `port` | int | `22` | default SSH port |
+| `username` | string | `''` | default SSH user |
+| `password` | string | `''` | default SSH password (non-empty overrides key) |
+| `privateKeyPath` | string | `''` | private key path (`~/.ssh/id_rsa` when empty) |
+| `workspace` | string | `''` | default remote workspace path |
+| `commandTimeoutMs` | int | 20000 | per remote command timeout |
+| `connectTimeoutMs` | int | 15000 | SSH connect timeout |
+
+## Safety
+
+Giving the plugin a machine's credentials lets the agent run **shell commands as your user** on that host. Only add machines you trust. Passwords are saved on the local machine file; treat it as sensitive (you may lock file ACLs).
+
+## License
+
 MIT

package/README.zh.md

@@ -1,84 +1,114 @@
-# dsh-remote
-
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的远程工作助手。
-
-连接一台 SSH 主机，选取一个**远程工作区**目录，让 Agent 在不离开 harness 的情况下直接对它操作——列目录、读文件、跑命令。
-
-DSH Web 界面刻意只监听 `127.0.0.1`（`--host 0.0.0.0` 被安全地拒绝）。这个插件的思路相反：**由你主动向外连**到远程主机，在远程目录里工作。
-
-## 能力
-
-- **连接远程**：支持**密码或 SSH key**（基于 `ssh2`）。
-- **选取远程工作区**：把远程某个目录当作本会话的项目根。
-- **模型工具**：`rw_info`、`rw_connect`、`rw_pick_workspace`、`rw_list_dir`、`rw_read_file`、`rw_exec`、`rw_sync`。
-- **本地镜像**：选远程工作区时会在本地 `~/.dsh/remote-workspaces/<host>/<base>-<hash>` 生成一个**真实本地目录**并经 SFTP 镜像。该路径通过 `fs.realpath`，因此 DSH 原生工作区选择器能选中它、`createWorkspace({path})` 能把它收养——浏览器/会话里的工作区把它当普通本地工作区，同时 dsh-remote 与远程保持同步。
-- **设置 → 远程工作区**：输入主机与登录方式→连接→浏览远程文件系统→设为工作区。
-- 当前远程工作区（`user@host:/path`）会注入每次系统提示，让 Agent 明确知道工作根目录。
-
-## 安装
-
-```bash
-dsh plugin --profile web add dsh-remote
-```
-
-（bundle 安装；行内容是 `id: dsh-remote`、`name: dsh-remote`。）
-
-## 使用
-
-### 1. 可选：在配置里设默认主机
-
-`cordis.patch.yml`：
-
-```yaml
-- id: dsh-remote
-  name: dsh-remote
-  config:
-    host: 10.0.0.8
-    port: 22
-    username: dev
-    privateKeyPath: C:/Users/you/.ssh/id_rsa
-    # 或用密码登录：
-    # password: '…'
-    workspace: /home/dev/project
-```
-
-若 `host` 为空，插件启动时处于断开状态，可在运行时连接。
-
-### 2. 连接并选工作区
-
-- **UI**：设置 → 远程工作区 → 填 host/port/user +（密码或 key 路径）→ **连接远程** → 输入远程路径并按 **设为远程工作区**（或用 **列目录** 浏览）。
-- **让 Agent 做**：`rw_connect(host)` 之后 `rw_pick_workspace(path=/…/project)`；随时可用 `/remote` 看状态。
-
-### 3. 在远程工作区里工作
-
-Agent 使用：
-```
-rw_list_dir(path?)
-rw_read_file(path=…)
-rw_exec(command=…)
-```
-由于工作区路径在系统提示里，Agent 会把它当作工作根，组合这些工具对远程项目做查看/构建/测试。
-
-## 配置
-
-| 键 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `host` | string | `''` | 远程 SSH 主机（空=断开） |
-| `port` | int | `22` | 远程 SSH 端口 |
-| `username` | string | `''` | 登录用户 |
-| `password` | string | `''` | SSH 密码（非空则覆盖 key） |
-| `privateKeyPath` | string | `''` | 私钥绝对路径；空=`~/.ssh/id_rsa` |
-| `passphrase` | string | `''` | 私钥口令（若加密） |
-| `workspace` | string | `''` | 初始远程工作区目录 |
-| `commandTimeoutMs` | int | 20000 | 单条命令超时 |
-| `connectTimeoutMs` | int | 15000 | SSH 连接超时 |
-
-## 浏览器页
-
-设置 → 远程工作区：连接表单（host/port/user/密码|key）、目录浏览（`/dsh-remote/ls`）、「设为远程工作区」（`/dsh-remote/workspace`）。全部走 harness `webServer` 的同源 JSON 路由；SSH 池在 host 端，凭据只在本地回环上提交。
-
-**安全提醒**：把远程凭据交给插件，等于允许 Agent 以你的用户身份在该主机上执行 shell 命令。只对可信主机开放。
-
-## License
-
+# dsh-remote
+
+**为 [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="./docs/ui-settings.svg" alt="dsh-remote 设置页 — 多机列表" width="720"/>
+
+原生 **「Add workspace / 选择工作区」** 流程 —— 一个对话框两个 tab（本地+远程）：
+
+<img src="./docs/ui-picker.svg" alt="dsh-remote 工作区选择 — 本机系统文件夹 + 远程(选机器→列目录)" width="720"/>
+
+---
+
+## 功能
+
+- **多机 SSH** —— 可存任意多台主机（host/port/user + **私钥**或**密码**）。密码只存在本地，界面不回显；在设置里一键切当前机。
+- **双 tab 工作区选择器**（填充原生「Add workspace」流程）：
+  - **本机** —— 走 **host 端原生系统文件夹对话框**选本地目录（或直接输入本地路径）→ 直接成为普通 DSH 本地工作区（与本地工作区共存）。
+  - **远程** —— 先**选机器**，再浏览其目录（或输入路径）🡺 确定后会创建**真实本地镜像**（`~/.dsh/remote-workspaces/<host>/<basename>-<hash>`，`fs.realpath` 通过）→ harness 把它当真实工作区收养，同时 dsh-remote 通过 SFTP 保持同步。
+- **双向 SFTP 同步** —— `rw_sync`（远程→镜像）、`rw_push`（镜像→远程），本地镜像改动可回传机器。
+- **模型工具** —— `rw_info`、`rw_connect`、`rw_pick_workspace`、`rw_list_dir`、`rw_read_file`、`rw_exec`、`rw_sync`、`rw_push`。
+- 当前 `user@host:/path` 会注入每次系统提示，让 Agent 明确自己的工作根。
+- **不改任何 `dsh-workspace` 官方代码** —— 全部作为普通插件实现（client 半以 `priority -100` 填充 directory-flow holes）。
+
+## 安装
+
+```bash
+dsh plugin add dsh-remote            # 添加 bundle
+```
+
+（或 `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_exec(command)` —— 在远程执行命令
+   - `rw_sync` / `rw_push` —— 拉取/推送本地镜像 <-> 远程
+
+## 可选：CLI 默认机
+
+可在 `cordis.patch.yml` 提供默认机：
+
+```yaml
+- id: dsh-remote
+  name: dsh-remote
+  config:
+    host: 10.0.0.8
+    port: 22
+    username: dev
+    privateKeyPath: C:/Users/you/.ssh/id_rsa
+    # 或用密码登录：
+    # password: '…'
+    workspace: /home/dev/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（见上方效果图）。
+
+## 配置
+
+| 键 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `host` | string | `''` | 默认 SSH 主机（空=断开） |
+| `port` | int | `22` | 默认 SSH 端口 |
+| `username` | string | `''` | 默认 SSH 用户 |
+| `password` | string | `''` | 默认 SSH 密码（非空覆盖 key） |
+| `privateKeyPath` | string | `''` | 私钥路径（空=`~/.ssh/id_rsa`） |
+| `workspace` | string | `''` | 默认远程工作区路径 |
+| `commandTimeoutMs` | int | 20000 | 单条远程命令超时 |
+| `connectTimeoutMs` | int | 15000 | SSH 连接超时 |
+
+## 安全提醒
+
+把机器凭据交给插件，等于允许 Agent 以你的用户身份在主机上执行 **shell 命令**。只添加你可信的机器。密码保存在本机文件里，请当作敏感数据处理（可收紧文件 ACL）。
+
+## License
+
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Remote-work assistant for DeepSeek Harness: connect SSH (password or key), pick a remote workspace, operate on it with rw_pick_workspace / rw_list_dir / rw_read_file / rw_exec / rw_sync tools, and mirror it to a real local directory (SFTP) so the DSH native workspace can adopt it.",
   "keywords": [
     "deepseek-harness",