@zhangfengshun/dsh-remote-ssh 2.4.12 → 2.4.14

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.14] — 远程工作区里 agent 的 `write`/`edit` 现在会同步到远端（issue #15）
+### 新增
+- **模型侧文件工具写回远端**（感谢 @Linhaojing 的桥接面分析与三条修法）：远程工作区会话里 agent 的 `write` / `edit` 走的是**进程内 `ctx.fs`**（宿主 base bundle 挂的是本地 `fs-sandbox`），不经过任何 HTTP 路由——因此此前只落**本地镜像**，用户在远端机器上找不到文件，只能人工 `remote_ssh_push`/`scp`；工具返回"已创建"而远端 `ls` 为空，容易被误判为失败。这与 #10（`fileReferences` 是进程内服务）同源不同面。
+  - **接法刻意保守**：包装 `ctx.fs` 的 `writeText` / `editText`，**原方法照旧调用**——镜像内容、沙箱围栏（`sandboxPolicy`）、写意图（`createIfAbsent` / `replaceIfVersion`）、`signal` 全部原样透传，我们**不伪造 `FsTarget`、不改 `resolve()` 行为**，只读它的返回值（`FsWriteOutcome.after` / `FsEditOutcome.after` 即写入后的完整内容）；
+  - 成功后把**这一份内容定向推回远端对应的那个文件**（沿用既有 `remoteWriteFile` 的 base64 写入 + 缓存失效），写前自动 `mkdir -p` 远端父目录；**不调用整镜像 push**（那会用旧镜像覆盖远端其它文件——正是报告者担心的点）；
+  - **等待同步完成再返回**：工具说"写好了"时远端已有该文件，消除"说写了却找不到"的歧义；
+  - **失败只告警，绝不让写操作变失败**：本地写入已成功，推送失败打一条 warn（提示可用 `remote_ssh_push` 补推）；
+  - 路径识别用「向上找最近的 `.remote-ssh.json`」（有界 8 层），非远程工作区路径直接返回 → **本地会话零影响**；软注入 `ctx.fs`（服务缺失/被替换时退回旧行为并打日志），清理时恢复原方法。
+- **文档补齐**（同 issue 的方案 1）：README「原理」与「缓存与一致性」写明模型侧文件工具的落点与 2.4.14 起的同步行为；新增一条已知限制——**agent 的 `read` 仍读本地镜像**（远端被他人改动时 agent 读到旧内容，需 `remote_ssh_sync` 刷新）。
+
+### 测试
+- 新增 `tests/fs-write-bridge.test.mjs`（**33 条断言**）：`installFsWriteBridge` 行为（原方法先调用、返回值透传、`expected`/`signal`/`sandboxPolicy` 原样透传、`target` 不被伪造、回调收到 `processPath` 规范路径与 `outcome.after`、原写入抛错时不回调、回调抛错不影响写入结果且只告警、无 `processPath` 时退回 `displayPath`、非法服务安全返回 null、恢复函数生效）、`findMirrorRoot` 真实文件系统测试（嵌套深层识别、非镜像路径、标记缺字段不误判、超 8 层有界）、以及接线断言（软注入、清理恢复、定向推送而非整镜像、`mkdir -p` 父目录）。
+
+## [2.4.13] — `remote_ssh_push` / `remote_ssh_sync` 成功却报 `returned invalid output`（issue #14）
+### 修复
+- **推送成功却被判为工具输出非法**（感谢 @Linhaojing 的根因定位与复现）：`sync` / `push` 共用的 output schema 把 `error` 声明为**必填**且 `additionalProperties: false`，而两条成功路径返回 `{ ok: true, mirrorPath }` / `{ ok: true, remotePath }` —— 成功时既缺 `error` 又带未声明字段，必然被 output 校验拒掉；**失败路径反而合法**，于是症状是「**只有成功会报错**」：模型看到 `Error: tool "remote_ssh_push" returned invalid output: missing required property "value.error"; "value.remotePath" is not a declared property`，但远端文件其实已经写好了，只能靠再跑一次 `ls`/`sha256sum` 确认，很容易误判成需要重试。而这条链路正是远程工作区里 agent `write`/`edit` 落回远端的唯一通道，成功信号不可信影响面不小。
+  - `syncOutput` 现在声明 `remotePath` / `mirrorPath`（成功路径本来就会带），`error` 改为**可选**；
+  - 两条成功路径补上 `error: ""`，与同文件其它工具（`normExec()`、`remote_ssh_ls` / `cat` / `grep` / `glob`）的风格一致；
+  - **并把全文件 6 处 output schema 的 `error` 一律改为可选**（通用护栏：`error` 按定义在成功时不存在，标必填就是定时炸弹）。失败路径的 `{ ok: false, error }` 不受影响。
+
+### 测试
+- 新增 `tests/tool-output-schema.test.mjs`（**17 条断言**）：用**真实的 `remoteSyncUp` / `remoteSyncDown`**（桩掉 `subprocess`）取实际返回对象，再用**真实的 `syncOutput.schema`** 跑一个模拟宿主校验器的 mini-validator（必填齐全 + 无未声明字段 + 类型正确）——成功路径、参数缺失失败路径、非零退出码失败路径全部通过校验；另有静态护栏断言（**任何** output schema 都不得把 `error` 标成必填、`ok` 仍必填、两个路径字段已声明）与**反向自检**（把历史的坏 schema 喂给校验器，逐字复现报告者看到的 `missing required property "value.error"; "value.mirrorPath" is not a declared property`）。
+
 ## [2.4.12] — 公开产物脱敏（无功能改动）
 ### 变更
 - **移除文档、代码注释与测试夹具中的真实标识**：此前 CHANGELOG / README / 代码注释 / issue 回复里出现了真实的项目名、HPC 主机名、内网 IP、真实远程路径与镜像目录 ID。现已全部替换为通用占位符（`proj-a` / `my-project` / `project-b`、`~/proj`、`hpc-a.example.com`、`192.0.2.10`（TEST-NET-1 文档网段）、`wmirror1`…、`solver`），并在 `MAINTENANCE.md` 写入硬规则：**公开产物一律用占位符**，发布前跑一次私有标识扫描。README 七夕段落里刻意保留的署名不受影响。

package/README.md

@@ -46,7 +46,7 @@
 **一条命令安装**（无需 token、API Key 或额外配置）：
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.12
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.14
 ```
 
 安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
@@ -207,6 +207,7 @@ dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 | 远程工作区里「按文件名搜索」一直转圈（大工作区） | 2.4.11 起已修复：改为浅层优先（`-maxdepth 3`，实测冷 0.68s / 热 0.11s）且**有命中就立即返回**（深挖转后台预热缓存，浅层零命中才同步等深挖 `-maxdepth 8`），遍历前剪噪声目录、去掉会阻塞短路的 `sort`，并加远端墙钟预算——到点返回**已收集的部分结果**并标记不完整。实测某大型远程项目工作区：旧实现 5 分钟零输出 → 现在 **0.96s 返回 43 条** |
 | 远程会话里 `@文件名` 没有候选，但单独输入 `@` 有 | 2.4.11 起已修复：模糊查询依赖索引，而索引首选 `git ls-files --cached --others`（`--others` 要遍历整棵工作树，巨型项目上跑不完 → 索引为空）。现在三级降级（完整 git 6s → 仅索引 git 3s → 有界 `find` `maxdepth 3` + 5s），并在索引未就绪时用有界 find 即时兜底（实测 0.65s），不再出现「全空」 |
 | 安装时提示 `minimumReleaseAge` 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
+| `remote_ssh_push` / `remote_ssh_sync` 明明推送成功却报 `returned invalid output` | 2.4.13 起已修复：这两个工具共用的 output schema 把 `error` 标成必填、成功路径又返回未声明的 `remotePath`/`mirrorPath`，于是**只有成功会报错**（失败路径反而合法）。现在 schema 声明两个路径字段、`error` 改为可选，成功路径也带 `error: ""`；全文件所有 output schema 的 `error` 一并改为可选 |
 | 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 `timeoutMs: 0`，随时可用 `remote_ssh_kill` 强杀 |
 | 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 `remote_ssh_exec` + `head`/`tail` 分段处理 |
 
@@ -214,6 +215,8 @@ dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 
 插件注册 6 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`，以及 better-sidebar 0.19 新增的 `fs.rename`、`fs.remove`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
 
+**模型侧的文件工具（agent 的 `write`/`edit`）**走的是**进程内** `ctx.fs`（宿主 base bundle 挂的是本地 `fs-sandbox`），不经过任何 HTTP 路由，因此 2.4.13 及以前只落**本地镜像**——用户在远端机器上找不到文件，只能人工 `remote_ssh_push`。2.4.14 起插件包装 `ctx.fs` 的 `writeText`/`editText`：**原写入照旧**（镜像内容、沙箱围栏、写意图语义全不变），成功后把同一份内容**定向推回远端对应的那个文件**（不是整镜像 tar，避免用旧镜像覆盖远端其它文件），写前自动 `mkdir -p` 远端父目录。推送失败只记一条 warn——本地写入已成功，桥接层不会让写操作变成失败；包装不可用时（服务缺失/被替换）退回旧行为并在日志提示。
+
 远程读取采用**单往返合并读**：一条池化命令同时返回 `size/mtime` 帧与文件内容（文本类扩展名优先 raw 直传，字节长 + U+FFFD 双校验失败自动回退 base64，结果逐字节一致）；配合主机侧结果缓存与变更失效（见下节）。
 
 Shell wrapper（`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`）检测工作区 `.remote-ssh.json`，自动 `ssh -tt` 连接远程，使内置「终端」页签透明接入。
@@ -225,6 +228,7 @@ Shell wrapper（`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`）检测工作区 `.r
 已知限制：
 
 - 集成终端（`ssh -tt`）与远端其它进程改动的文件依赖 TTL + 复验兜底，最多 **5 秒**陈旧；
+- **agent 的 `read` 仍读本地镜像**：2.4.14 起 `write`/`edit` 会同步到远端，但若文件在远端被其它人改动，agent 读到的是镜像里的旧内容（用 `remote_ssh_sync` 重新拉取镜像即可）；
 - `/sidebar/file` 下载池化路径有效上限约 **6.29MB**，更大文件自动退回一次性连接下载（可成功，多一次重连开销）；
 - 二进制内容伪装成文本扩展名时会多一次 base64 回退往返（结果正确）。
 

package/README_EN.md

@@ -46,7 +46,7 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 **One command** (no token, API key or extra configuration needed):
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.12
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.14
 ```
 
 **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
@@ -207,6 +207,7 @@ The plugin never patches DSH sources or injects into the profile dependency tree
 | "Search by file name" spins forever in a remote workspace (large trees) | Fixed in 2.4.11: shallow-first (`-maxdepth 3`, measured 0.68s cold / 0.11s warm) **returning as soon as anything matches** (the deeper pass becomes a background cache warm-up and only runs synchronously when the shallow pass finds nothing), noise directories pruned before traversal, the short-circuit-blocking `sort` removed, and a remote wall-clock budget that returns the **partial results collected so far** and flags them as incomplete. Measured on an 大型项目 workspace: 5 minutes with zero output before → **43 matches in 0.96s** now |
 | In a remote session `@filename` shows no candidates, while a bare `@` works | Fixed in 2.4.11: fuzzy queries rely on the index, and the index preferred `git ls-files --cached --others` (`--others` must walk the whole working tree and never finishes on huge projects → empty index). It now degrades in three budgeted steps (full git 6s → index-only git 3s → bounded `find` `maxdepth 3` + 5s) and falls back to a bounded `find` (measured 0.65s) whenever the index is not ready yet, so candidates are never empty |
 | Install fails with `minimumReleaseAge` or "No matching version" right after a release | npm supply-chain freshness policy — retry after 1–5 minutes |
+| `remote_ssh_push` / `remote_ssh_sync` report `returned invalid output` even though the push succeeded | Fixed in 2.4.13: their shared output schema marked `error` as required while the success path returned an undeclared `remotePath`/`mirrorPath`, so **only success failed** (failures validated fine). The schema now declares both path fields, `error` is optional, the success paths carry `error: ""`, and every output schema in the file treats `error` as optional |
 | A command hangs forever | The 120s timeout discards the pooled session automatically; use `timeoutMs: 0` for long jobs and `remote_ssh_kill` at any time |
 | Large files are truncated | 4MB per read, ≈6.29MB on the pooled download path (larger files fall back to a one-shot connection); use `remote_ssh_exec` with `head`/`tail` to page through |
 
@@ -214,6 +215,8 @@ The plugin never patches DSH sources or injects into the profile dependency tree
 
 The plugin registers 6 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.write`, `fs.search`, plus `fs.rename` and `fs.remove` added by better-sidebar 0.19) that intercept better-sidebar's prefix route. When the session cwd contains `.remote-ssh.json`, requests go through SSH; otherwise local fs. The client sees local mirror paths — the Host transparently translates them to remote paths.
 
+**The model-side file tools (the agent's `write`/`edit`) use the in-process `ctx.fs`** (the host base bundle mounts the local `fs-sandbox`), never an HTTP route — so up to 2.4.13 they only landed in the **local mirror**, leaving users unable to find the file on the remote machine without a manual `remote_ssh_push`. Since 2.4.14 the plugin wraps `ctx.fs`'s `writeText`/`editText`: the **original write runs unchanged** (mirror content, sandbox fence and write-intent semantics intact), and on success the same content is pushed to **that one remote file** (not a whole-mirror tar, which could overwrite unrelated remote files), creating the remote parent directory first. A failed push only logs a warning — the local write already succeeded, so the bridge never turns a write into a failure; if the service cannot be wrapped, the old behaviour returns with a log line.
+
 Remote reads use a **single-roundtrip merged read**: one pooled command returns the `size/mtime` frame plus the file content (text extensions prefer raw transfer with byte-length + U+FFFD validation and automatic base64 fallback — results are byte-identical), combined with host-side result caching and change invalidation (see below).
 
 A shell wrapper (`~/.dsh/remote-ssh/dsh-remote-shell[.cmd]`) detects the workspace's `.remote-ssh.json` and auto-launches `ssh -tt`, making the built-in **Terminal** tab transparently connect to remote.
@@ -225,6 +228,7 @@ Remote reads and directory listings are cached host-side (read LRU 32 + listing
 Known limitations:
 
 - Files changed from the integrated terminal (`ssh -tt`) or by other remote processes rely on TTL + revalidation and may be stale for up to **5 seconds**;
+- **The agent's `read` still reads the local mirror**: since 2.4.14 `write`/`edit` are mirrored to the remote, but if someone else changes the file remotely the agent reads the older mirror copy (run `remote_ssh_sync` to refresh the mirror);
 - The pooled `/sidebar/file` download path has an effective limit of ≈**6.29MB**; larger files automatically fall back to a one-shot connection download (succeeds, with one extra reconnect);
 - Binary content masquerading with a text extension costs one extra base64 fallback round-trip (results are still correct).
 

package/lib/index.js

@@ -1087,7 +1087,7 @@ async function remoteSyncDown(subprocess, p, remotePath, mirrorPath) {
   const sshErr = readCollected(sshH, "stderr");
   const tarErr = readCollected(tarH, "stderr");
   // ssh 正常退出且 tar 正常退出才算成功
-  if (sshOut.exitCode === 0 && tarOut.exitCode === 0) return { ok: true, mirrorPath: mirrorPath };
+  if (sshOut.exitCode === 0 && tarOut.exitCode === 0) return { ok: true, error: "", mirrorPath: mirrorPath };
   const parts = [];
   if (pipeErr) parts.push("管道: " + pipeErr);
   if (sshOut.exitCode !== 0) parts.push("ssh 退出码 " + sshOut.exitCode + (sshErr ? ": " + sshErr.slice(0, 500) : ""));
@@ -1125,7 +1125,7 @@ async function remoteSyncUp(subprocess, p, remotePath, mirrorPath) {
   if (tarOut.exitCode === 0 && sshOut.exitCode === 0) {
     // 批量覆盖远端文件：清空该 profile 的读/列举缓存（findings §4.3a）
     clearCachesForProfile(p);
-    return { ok: true, remotePath: remotePath };
+    return { ok: true, error: "", remotePath: remotePath };
   }
   const parts = [];
   if (pipeErr) parts.push("管道: " + pipeErr);
@@ -1278,7 +1278,7 @@ function execSchema() {
       exitCode: { type: "number", required: true },
       stdout: { type: "string", required: true },
       stderr: { type: "string", required: true },
-      error: { type: "string", required: true },
+      error: { type: "string" },
       truncated: { type: "boolean", required: true },
       isTimeout: { type: "boolean", required: true }
     }
@@ -1556,6 +1556,96 @@ function fsSearchResult(matches, entries, truncated) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// agent 文件工具写回远端（issue #15）
+//
+// 远程工作区会话里 agent 的 write / edit 走**进程内** ctx.fs（base bundle 挂的是本地
+// fs-sandbox：`@deepseek-ai/dsh-base/cordis.patch.yml` 的 `fs-sandbox` 行），因此只落在本地
+// 镜像 —— 用户在远端机器上找不到文件，只能人工 push/scp。这条链路不经过任何 HTTP 路由，
+// 与 #10（`fileReferences` 是进程内服务）同源不同面。
+//
+// 接法（刻意保守）：
+//   - **原方法照旧调用**：镜像内容、沙箱围栏（sandboxPolicy）、写意图（createIfAbsent /
+//     replaceIfVersion）与审计语义全部不变 —— 我们只读它的返回值（`outcome.after` 即写入后的
+//     完整内容），不伪造 FsTarget、不改 resolve 行为；
+//   - 成功后把**这一份内容定向推回远端对应的那个文件**（不是整镜像 tar —— 那会用旧镜像覆盖
+//     远端其它文件）；
+//   - 推失败只记一条 warn：本地写入已经成功，桥接层绝不让写操作变成失败。
+// ---------------------------------------------------------------------------
+
+/** 从文件路径向上找最近的「镜像根」（含 `.remote-ssh.json` 的目录）；有界 8 层。 */
+function findMirrorRoot(filePath) {
+  if (!filePath) return null;
+  let dir = dirname(String(filePath));
+  for (let i = 0; i < 8 && dir; i++) {
+    try {
+      const marker = join(dir, ".remote-ssh.json");
+      if (existsSync(marker)) {
+        const info = JSON.parse(readFileSync(marker, "utf8"));
+        if (info && info.host && info.user && info.remotePath) return { root: dir, info: info };
+      }
+    } catch (e) {}
+    const parent = dirname(dir);
+    if (!parent || parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * 包装 ctx.fs 的 `writeText` / `editText`：原调用照旧，成功后回调 `onWritten(本地绝对路径, 写入后的内容)`。
+ * 返回恢复函数；服务缺失/不可包装时返回 null（插件照常工作，只是不桥接）。
+ */
+function installFsWriteBridge(svc, hooks) {
+  if (!svc || typeof svc.writeText !== "function") return null;
+  const onWritten = hooks && typeof hooks.onWritten === "function" ? hooks.onWritten : null;
+  if (!onWritten) return null;
+  const log = (hooks && hooks.log) || null;
+  const warn = function (msg) { try { if (log && typeof log.warn === "function") log.warn(msg); } catch (e) {} };
+  const originalWrite = svc.writeText.bind(svc);
+  const originalEdit = typeof svc.editText === "function" ? svc.editText.bind(svc) : null;
+  const originalProcessPath = typeof svc.processPath === "function" ? svc.processPath.bind(svc) : null;
+
+  /** target → 本地绝对路径：优先 processPath（后端执行世界的规范路径），退回 displayPath。 */
+  function pathOf(target) {
+    try { if (originalProcessPath) { const p = originalProcessPath(target); if (p) return String(p); } } catch (e) {}
+    try { return target && target.displayPath ? String(target.displayPath) : ""; } catch (e) { return ""; }
+  }
+  /** 同步到远端；**等待**它完成再返回（"写好了"就意味着远端也已有），但失败只告警不抛出。 */
+  async function mirror(target, content) {
+    if (typeof content !== "string") return;
+    const abs = pathOf(target);
+    if (!abs) return;
+    try {
+      await onWritten(abs, content);
+    } catch (e) {
+      warn("[dsh-remote-ssh] 文件同步到远端失败（本地镜像已写入）: " + String(e && e.message ? e.message : e));
+    }
+  }
+
+  const patchedWrite = async function (target, content, expected, signal, sandboxPolicy) {
+    const out = await originalWrite(target, content, expected, signal, sandboxPolicy);
+    await mirror(target, out && typeof out.after === "string" ? out.after : content);
+    return out;
+  };
+  const patchedEdit = originalEdit ? async function (target, edit, expected, signal, sandboxPolicy) {
+    const out = await originalEdit(target, edit, expected, signal, sandboxPolicy);
+    await mirror(target, out && typeof out.after === "string" ? out.after : undefined);
+    return out;
+  } : null;
+
+  try {
+    svc.writeText = patchedWrite;
+    if (patchedEdit) svc.editText = patchedEdit;
+  } catch (e) {
+    return null;
+  }
+  return function restoreFsWriteBridge() {
+    try { if (svc.writeText === patchedWrite) svc.writeText = originalWrite; } catch (e) {}
+    try { if (patchedEdit && svc.editText === patchedEdit) svc.editText = originalEdit; } catch (e) {}
+  };
+}
+
 // ---------------------------------------------------------------------------
 // apply
 // ---------------------------------------------------------------------------
@@ -2194,7 +2284,7 @@ function apply(ctx, config) {
           ok: { type: "boolean", required: true },
           path: { type: "string", required: true },
           entries: { type: "array", required: true, items: { type: "object", additionalProperties: true } },
-          error: { type: "string", required: true }
+          error: { type: "string" }
         }
       },
       render: textRender(function (a, v) {
@@ -2223,7 +2313,7 @@ function apply(ctx, config) {
           content: { type: "string", required: true },
           binary: { type: "boolean", required: true },
           truncated: { type: "boolean", required: true },
-          error: { type: "string", required: true }
+          error: { type: "string" }
         }
       },
       render: textRender(function (a, v) { return v.error || v.content || ""; })
@@ -2262,10 +2352,16 @@ function apply(ctx, config) {
   const syncParams = {
     workspaceId: { type: "string", description: "远程工作区 id（留空则在当前远程工作区会话中自动识别）。" }
   };
+  // sync / push 共用的输出 schema（issue #14）：`error` **不能**标成必填 —— 成功路径本来就没有
+  // error，标必填会让「推送成功」被判成 `returned invalid output`（模型看到失败、副作用却已落地，
+  // 只能靠再跑一次 ls 才能确认）。同理成功路径会带上 remotePath / mirrorPath，必须在 schema 里声明
+  // （additionalProperties: false 会拒掉未声明字段）。
   const syncOutput = {
     schema: { type: "object", additionalProperties: false, properties: {
       ok: { type: "boolean", required: true },
-      error: { type: "string", required: true }
+      remotePath: { type: "string" },
+      mirrorPath: { type: "string" },
+      error: { type: "string" }
     } },
     render: textRender(function (a, v) { return v.ok ? "同步完成" : (v.error || "同步失败"); })
   };
@@ -2327,7 +2423,7 @@ function apply(ctx, config) {
           path: { type: "string", required: true },
           matches: { type: "array", required: true, items: { type: "object", additionalProperties: true } },
           truncated: { type: "boolean", required: true },
-          error: { type: "string", required: true }
+          error: { type: "string" }
         }
       },
       render: textRender(function (a, v) {
@@ -2364,7 +2460,7 @@ function apply(ctx, config) {
           path: { type: "string", required: true },
           files: { type: "array", required: true, items: { type: "string" } },
           truncated: { type: "boolean", required: true },
-          error: { type: "string", required: true }
+          error: { type: "string" }
         }
       },
       render: textRender(function (a, v) {
@@ -3467,9 +3563,43 @@ function apply(ctx, config) {
     }
   });
 
+  // ---- agent 文件工具写回远端（issue #15）----
+  // ctx.fs 是进程内服务（agent 的 write/edit 走它），这里在原写入成功之后把同一份内容定向推到
+  // 远端对应文件；非远程工作区路径（找不到 .remote-ssh.json）时什么都不做。
+  async function mirrorWriteToRemote(absPath, content) {
+    if (!absPath || typeof content !== "string") return;
+    const hit = findMirrorRoot(absPath);
+    if (!hit) return;                                   // 本地工作区 / 非镜像路径：不动
+    const p = getProfile(hit.info.profileId);
+    if (!p) return;
+    const remoteFile = localToRemote(absPath, hit.root, hit.info.remotePath);
+    if (!remoteFile || remoteFile === hit.info.remotePath) return;
+    // 远端父目录可能还不存在（新文件常落在新建目录里）
+    const remoteDir = posixDirname(remoteFile);
+    if (remoteDir && remoteDir !== remoteFile) {
+      try { await runPooled(p, "mkdir -p " + shellQuotePath(remoteDir), undefined, undefined); } catch (e) {}
+    }
+    const r = await remoteWriteFile(runPooled, p, remoteFile, content);
+    if (r && r.ok) {
+      try { ctx.logger?.info?.("[dsh-remote-ssh] agent 写入已同步到远端: " + remoteFile); } catch (e) {}
+    } else {
+      try { ctx.logger?.warn?.("[dsh-remote-ssh] agent 写入同步远端失败（本地镜像已写入，可用 remote_ssh_push 补推）: " + remoteFile + " — " + ((r && r.error) || "")); } catch (e) {}
+    }
+  }
+
+  let restoreFsWrite = null;
+  ctx.inject(["fs"], (sctx) => {
+    const svc = sctx && (sctx.fs || (typeof sctx.get === "function" ? sctx.get("fs") : null));
+    restoreFsWrite = installFsWriteBridge(svc, { onWritten: mirrorWriteToRemote, log: ctx.logger });
+    if (!restoreFsWrite) {
+      try { ctx.logger?.warn("[dsh-remote-ssh] ctx.fs 不可包装：远程工作区里 agent 的 write/edit 仍只落本地镜像（需 remote_ssh_push）"); } catch (e) {}
+    }
+  });
+
   // ---- 清理 ----
   ctx.effect(() => () => {
     if (restoreFileReferences) { try { restoreFileReferences(); } catch (e) {} restoreFileReferences = null; }
+    if (restoreFsWrite) { try { restoreFsWrite(); } catch (e) {} restoreFsWrite = null; }
     clearInterval(idleTimer);
     sessions.forEach(function (s) { try { s.close(); } catch (e) {} });
     sessions.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.4.12",
+  "version": "2.4.14",
   "description": "DSH web plugin: VSCode Remote-SSH-like remote development (SSH to supercomputers/servers, remote workspace, file explorer, integrated terminal), integrated with dsh-better-sidebar and DSH settings.",
   "keywords": [
     "dsh",