dsh-remote-agent 0.9.6 → 0.9.9

package/CHANGELOG.md

@@ -9,6 +9,219 @@
 
 ---
 
+## [0.9.9] - 2026-10-20
+
+> **0.9.8 的 CI 回归修复。** 本地全绿，但 macOS 与 Windows 上失败。
+
+### 修复：测试断言直接比绝对路径（realpath 与平台表示差异）
+
+**现象**（CI run `39389528713`，macOS + Windows 失败，Linux 通过）：
+
+    macOS:   actual '/private/var/folders/.../b.txt'
+             expected '/var/folders/.../b.txt'
+
+    Windows: actual 'C:\Users\runneradmin\AppData\Local\Temp\...\b.txt'
+             expected 'C:\Users\RUNNER~1\AppData\Local\Temp\...\b.txt'
+
+**根因**：`fs-service` 的写操作返回 **realpath 后**的路径 —— 这是**刻意的正确行为**
+（realpath 才能识破软链逃逸与 8.3 短名）。但测试用 `path.join(root, ...)`
+直接比字符串：
+
+- **macOS**：`/var` 是 `/private/var` 的软链
+- **Windows CI**：`RUNNER~1` 是 `runneradmin` 的 8.3 短名
+
+两者都让"直接比字符串"失败。**Linux 恰好没有这层间接，所以本地和 ubuntu 都过。**
+
+**修法**：这条用例真正要验证的是"移动成功且内容对"，不是"路径字符串相等"。
+改成比 `basename` + 文件内容：
+
+```js
+assert.equal(path.basename(r.to), 'b.txt')
+assert.equal(fs.readFileSync(b, 'utf8'), 'A')
+```
+
+### 0.9.8 的四项能力（本版包含）
+
+| 能力 | 关键护栏 |
+|---|---|
+| **一键修复** | 只改托管块 / 写前备份 / 写后校验 / 二次确认 / 可撤销 / 绝不用 0.0.0.0 |
+| **外部工具检测** | 只探测 + 给命令，**不代下载**（守供应链边界）|
+| **写操作 ×4** | confirm 必填 / 默认不覆盖 / 不递归删 / 原子写 / 8MB 上限 / roots 护栏 |
+| **进程诊断 ×3** | kill 三道护栏：confirm / 拒杀自身与父进程 / 拒杀系统关键进程 |
+| **UI 折叠** | 首屏只留当下需要的；配置/体检/共享收进 `<details>` |
+
+```
+packaging   4 项
+doc-drift   131/131
+diag:inject 11 项
+tests       1032（1030 pass / 0 fail / 2 skip）
+lint        干净
+```
+
+## [0.9.8] - 2026-10-20
+
+### 四项能力（用户要求：一键修复 / 自动装依赖 / 更多工具 / 重写 UI）
+
+这四项**全都在放宽边界**，所以每一道护栏都不是"最佳实践"，而是**踩过的坑**。
+
+#### ① 一键修复配置（会改 DSH 的 cordis.patch.yml）
+
+用户此前明确说过「不要改 DSH」，而这个功能恰恰要改它。所以做成**两步流程**：
+
+    [预览修复] → 只读，列出"将要改什么" + "不会做什么"
+    [确认修复] → 才写盘（必须带 confirm: "yes"）
+
+护栏：
+- **只改托管块**（`# --- dsh-remote-agent (managed) ---` 之间），用户手写的
+  其它条目一个字节不碰
+- **写前必备份**（`.bak-<时间戳>`）
+- **写后必校验**：重新解析，确认条目在、无重复 id
+- **失败必回滚**，并给「撤销」按钮（`action: 'undo'`）
+- **绝不用 0.0.0.0**（新版 DSH 硬拒绝，会让它启动崩溃 —— 我们踩过 10 份 crash 日志）
+
+**只修机械可判定的项**（webserver host / role）。端口占用、防火墙、装软件、
+模型凭证这些需要人判断的，只给建议不动手。
+
+#### ② 外部工具检测（**不代下载**）
+
+用户原话是"自动装依赖"，我们把范围收窄到**外部工具**，且**不代下载**：
+
+- 零 npm 依赖是核心卖点 —— 代装 npm 包会自毁卖点
+- 代下载第三方二进制会让我们变成软件分发方（版本/来源/校验/责任/
+  供应链攻击面全落在我们头上）
+
+所以只做三件事：**探测**（Tailscale / PowerShell / git / Node.js）、
+**说清缺了会怎样**、**给官方链接 + 安装命令**（用户自己复制执行）。
+
+实测在本机探测到：Tailscale 1.102.4 / PowerShell 5 / git 2.54.0 / Node v24.18.0。
+
+#### ③ 更多工具：文件写操作（4 个）+ 进程诊断（3 个）
+
+工具数 12 → **19**。
+
+**写操作**（`remote_write` / `remote_mkdir` / `remote_move` / `remote_delete`）：
+
+- **必须传 `confirm: "yes"`**（不可逆操作，AI 会"顺手"多调一次工具）
+- **默认不覆盖**已有文件 —— 防手滑清空
+- **不递归删除**：非空目录一律拒绝（递归删除太容易造成不可逆损失）
+- **原子写**（临时文件 + rename），失败不留半截文件
+- 单次写入上限 8MB（防一次写爆磁盘）
+- roots 护栏：新增 `resolveWritable`，允许目标不存在但对**已存在的祖先**
+  做 realpath 校验（防软链逃逸）
+
+**进程诊断**（`remote_ps` / `remote_port` / `remote_kill`）：
+
+- `ps` / `port` **只读**
+- `kill` 有三道护栏：
+  1. 必须 `confirm: "yes"`
+  2. **拒绝杀本进程与父进程** —— 否则副机失联，用户彻底失去远程修复能力
+  3. **拒绝杀系统关键进程**（System/csrss/wininit/services/lsass 等）
+
+实测端口查询准确识别出 19387 的监听 PID。
+
+#### ④ UI 改进：折叠区块（信息密度）
+
+加了一键修复 / 外部工具 / SMB 共享之后，面板区块到了 **9 个**，首屏被淹没。
+
+改用原生 `<details>` 折叠（零 JS 状态、可访问性好、无 hydration 问题）：
+
+- 首屏只留：错误横幅 + 状态卡 + 节点 + 任务 + 派发表单
+- 「接入与配置」「环境体检与工具」「工作区共享」收进折叠块
+- **默认展开策略**：没副机在线 → 展开「接入」；体检有失败项 → 展开「体检」
+
+### 踩坑记录（都写进了代码注释）
+
+**① `resolveAny` 要求路径已存在 → `remote_write` 100% 失败**
+只读工具用 `realpathSync` 是对的（"读不存在的文件没有借口"），但写操作的
+目标**本来就是要新建的**。第一版直接复用，实测立刻暴露
+`path not found: .../a.txt`。修法：新增 `resolveWritable` —— 目标不存在时
+向上找第一个存在的祖先做 realpath，再校验 roots。
+
+**② 多行 PowerShell 脚本 `join(' ')` 缺分号**
+`$ErrorActionPreference="Stop" Get-Process ...` 被拼成一行，PowerShell 报
+`UnexpectedToken`。修法：用 `;` 分隔语句。
+
+**③ `process-service.js` 忘了导出 `createProcessService`**
+6 个测试文件全部加载失败（`does not provide an export named`）。
+
+**④ 测试锚点被新代码干扰**
+`indexOf('confirm-required')` 找到的第一处不再是被测的那条（一键修复也用
+同一个错误码）。修法：锚更具体的上下文。
+
+### 测试
+
+`test/capabilities-2026-10-20.test.js` **23 条**，重点不在"功能能用"而在
+"护栏挡得住"：
+
+- 写操作：默认不覆盖 / 越界拒绝 / 目标不存在也能写 / 超限拒绝 /
+  非空目录拒绝 / 原子性无残留
+- kill：无 confirm 拒绝 / 拒杀自己 / 拒杀父进程 / 非法 pid 拒绝
+- 一键修复：只标机械可修项 / 绝不 0.0.0.0 / plan 是只读的 /
+  备份名必须符合命名空间
+- 外部工具：结构完整 / **不得代执行安装命令**（反例断言）/ 清单与探测同源
+
+doc-drift 新增 91（一键修复护栏）、92（写操作护栏）、93（kill 三道护栏）、
+94（不代下载）、95（折叠 UI）。
+
+```
+packaging   4 项
+doc-drift   131/131
+diag:inject 11 项
+tests       1032（1030 pass / 0 fail / 2 skip）
+lint        干净
+```
+
+## [0.9.7] - 2026-10-20
+
+> **0.9.6 的 CI 回归修复。** 0.9.6 在本地全绿，但 GitHub Actions 的
+> `ubuntu-latest / node 24.x` 上 E2E 握手全部超时。
+
+### 修复：X25519 私钥重建改用 DER，不再依赖 JWK 的 `x` 校验
+
+**现象**（CI run `39384173448`，只有 ubuntu/node24 失败）：
+
+    Error: timeout waiting for e2e session on test-worker
+    code: 'ERR_CRYPTO_INVALID_JWK'
+
+**根因**：`lib/e2e.js` 用 JWK 重建私钥：
+
+```js
+createPrivateKey({ key: { kty: 'OKP', crv: 'X25519', d: b64, x: '' }, format: 'jwk' })
+```
+
+本地 Node 24.18 接受 `x: ''`，但 CI 那个 Node 24 小版本**不接受**
+（空串不是合法 base64url；省略 `x` 同样被拒）。
+
+**这个 bug 为什么藏了这么久**：失败表现为
+`timeout waiting for e2e session` —— **真因（ERR_CRYPTO_INVALID_JWK）被
+完全掩盖**，看起来像时序抖动，而本地又复现不了。
+
+**修法**：直接用 DER 构造 —— X25519 私钥的 PKCS#8 就是
+固定 16 字节前缀 + 32 字节标量。这条路径**不经过 JWK 校验**，跨 Node
+小版本稳定。
+
+实测验证：DER 构造出的私钥导出的公钥 `x` 与原始 JWK 完全一致，
+DH 协商结果与正常生成的密钥对一致。
+
+**测试**：`test/e2e.test.js` 新增 2 条 ——
+双方派生会话密钥必须一致（E2E 握手的核心数学）、非法长度必须明确抛错。
+
+### 0.9.6 的五项体验提升（本版包含）
+
+- **④ 统一错误翻译层** —— errno + 17 个协议码 + HTTP + 文案特征，每条带"下一步"
+- **① 副机连接状态可见** —— 记录每次连接尝试，空态显示原因与修法
+- **② 一键复制修法** —— 体检项旁的「复制修法」按钮（只复制，不代改文件）
+- **③ 首次使用向导** —— 编号步骤 + 每步"应该看到什么"
+- **⑤ 任务进度摘要** —— 任务行直接显示"最近：调用工具 Write · 共 23 步"
+
+```
+packaging   4 项
+doc-drift   126/126
+diag:inject 11 项
+tests       1009（1007 pass / 0 fail / 2 skip）
+lint        干净
+```
+
 ## [0.9.6] - 2026-10-20
 
 ### 用户体验：五项提升（"出了问题不知道原因"的正面回应）

package/README.md

@@ -16,7 +16,7 @@
 ┌─────────────── 主电脑（hub）────────────────┐
 │  DSH · 模型 · 会话日志 · 全部凭证            │
 │  ┌─ dsh-remote-agent ─────────────────────┐ │
-│  │ 12 个 remote_* 工具 + Web 面板          │ │
+│  │ 19 个 remote_* 工具 + Web 面板          │ │
 │  └────────────────────────────────────────┘ │
 └──────────────────▲──────────────────────────┘
                    │ 节点主动拨入（direct / relay）
@@ -177,7 +177,7 @@ node bin/dsh-remote-setup.js --doctor 你的配置.yml
 | **凭证不离开副机** | 协议里不带任何模型 key；副机用自己的模型配置跑自己的循环 |
 | **零 npm 依赖** | 只用 `node:` 内置模块，无构建步骤，`lib/` 就是产物 |
 
-### 工具速查（共 12 个）
+### 工具速查（共 19 个）
 
 | 类别 | 工具 |
 |---|---|
@@ -185,7 +185,9 @@ node bin/dsh-remote-setup.js --doctor 你的配置.yml
 | **任务** | `remote_task`（派发）· `remote_status`（查进度）· `remote_cancel`（取消）|
 | **审批** | `remote_task` 的 `approval: 'manual'` 会挂起 → 面板或工具批准/拒绝 |
 | **结果** | `remote_handoff`（结果卡）· `remote_manifest`（产物清单）· `remote_pull`（拉成品）· `remote_purge`（清理）|
-| **文件** | `remote_ls` · `remote_read` · `remote_grep` · `remote_tree` |
+| **文件（只读）** | `remote_ls` · `remote_read` · `remote_grep` · `remote_tree` |
+| **文件（写入）** | `remote_write` · `remote_mkdir` · `remote_move` · `remote_delete` —— **必须传 `confirm: "yes"`**；默认不覆盖、不递归删 |
+| **诊断** | `remote_ps`（列进程）· `remote_port`（查端口占用）· `remote_kill`（杀进程，**不可逆**，须 `confirm: "yes"`）|
 
 ---
 
@@ -442,7 +444,7 @@ ack 自动按明文兼容旧中继继续），安全边界与已知局限见
 | 路径 | 作用 |
 |---|---|
 | `lib/index.js` | 插件入口（角色分发器：`role: auto` / `hub` / `worker` / `both`） |
-| `lib/hub/**` | 主机侧：节点注册表、**12 个工具**、subagent provider、UI 路由、环境体检 |
+| `lib/hub/**` | 主机侧：节点注册表、**19 个工具**、subagent provider、UI 路由、环境体检 |
 | `lib/hub/views.js` | **投影共享层** —— 工具与 UI 用同一份字段白名单 |
 | `lib/node/**` | 副机侧：拨入、任务引擎、产物服务、exec/agent 双后端、SMB 共享 |
 | `lib/env-check.js` | 环境体检（命令行与面板共用一份逻辑） |

package/lib/auto-fix.js

@@ -0,0 +1,304 @@
+/**
+ * 一键修复（2026-10-20，用户要求的第四项能力）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么这件事要极其小心
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 用户之前明确说过「**不要改 DSH**」。而"一键修复"恰恰要改
+ * `<profile>/cordis.patch.yml` —— DSH 自己的配置文件。
+ *
+ * 我们**自己**刚因为动这个文件出过事故：
+ *   · 手写 `host: '0.0.0.0'` → DSH 启动崩溃（10 份 crash 日志）
+ *   · 追加 remote-agent 段 → 被 DSH 下次启动重写冲掉
+ *
+ * 所以本模块的每一道防线都不是"最佳实践"，而是**踩过的坑**：
+ *
+ *   1. **只改托管块**（`# --- dsh-remote-agent (managed) ---` 之间）。
+ *      用户手写的其它条目一个字节不碰 —— 复用 `writePatchBlock` 的既有保证。
+ *   2. **写前必备份**（`writePatchBlock` 自带 `.bak-<时间戳>`）。
+ *   3. **写后必校验**：重新解析一遍，确认我们的条目在、且没有重复 id。
+ *   4. **失败必回滚**（`writePatchBlock` 内部已做；本模块再兜一层）。
+ *   5. **面板二次确认**：`confirm: 'yes'` 才动手（与 SMB 共享同一模式）。
+ *   6. **可一键回滚**：记住上一次备份路径，给「撤销」按钮。
+ *
+ * ── 只修"机械可判定"的项 ───────────────────────────────────────────────
+ *
+ * **不修**需要人判断的（端口占用、防火墙、模型凭证）—— 那些只给建议。
+ *
+ * 可修的两类：
+ *   · `webserver.host` 绑在 loopback 或 0.0.0.0 → 改成自动选出的具体 IP
+ *   · `remote-agent.role` 缺失 → 按当前推断结果补上
+ *
+ * ⚠ **绝不用 0.0.0.0**（新版 DSH 硬拒绝，会让它启动崩溃）。
+ * 地址由 `resolveListenHost` 自动选（Tailscale > 私网 > 回环）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { resolveListenHost } from './listen-server.js'
+
+/**
+ * 生成一个修复计划（**只读**，不改任何文件）。
+ *
+ * 面板先展示"将要改什么"，用户确认后才调 `applyFixPlan`。
+ *
+ * @param {object} o
+ * @param {object} o.envCheck envChecks 的结果
+ * @param {string} o.patchFile 目标 cordis.patch.yml 绝对路径
+ * @param {string} [o.listenHost] 用户配置的监听地址（留空=自动选）
+ * @returns {{fixable:Array, skipped:Array, host:string, hostSource:string, file:string}}
+ */
+export function planFixes({ envCheck, patchFile, listenHost = '' } = {}) {
+  const picked = resolveListenHost({ listenHost })
+  const fixable = []
+  const skipped = []
+
+  const items = Array.isArray(envCheck?.items) ? envCheck.items : []
+  for (const it of items) {
+    if (!it || it.ok === true) continue
+    const id = typeof it.id === 'string' ? it.id : ''
+
+    if (id === 'reachability') {
+      // 这是**唯一**能机械修的：把 webserver.host 改成具体 IP
+      fixable.push({
+        id: 'reachability',
+        label: it.label,
+        // 说明将要做什么（面板必须展示，用户要知道自己在同意什么）
+        change: `把 webserver 的 host 改成 ${picked.host}（${describeSource(picked.source)}）`,
+        // 明确的"不会做什么"—— 比承诺做了什么更重要
+        note: '只改 host 这一个字段，不动 port、不动你的其它配置条目',
+      })
+      continue
+    }
+
+    if (id === 'role') {
+      fixable.push({
+        id: 'role',
+        label: it.label,
+        change: '在 remote-agent 的 config 里补上 role',
+        note: '按当前推断结果写入（没配 hubUrl 就是 hub）',
+      })
+      continue
+    }
+
+    // 其它项（端口占用 / 防火墙 / 模型 / Tailscale / roots 不存在）都需要人判断
+    skipped.push({
+      id,
+      label: it.label,
+      reason: skippedReason(id),
+    })
+  }
+
+  return {
+    fixable,
+    skipped,
+    host: picked.host,
+    hostSource: picked.source,
+    file: typeof patchFile === 'string' ? patchFile : '',
+  }
+}
+
+/** 为什么这项不能自动修（如实说明，不含糊）。 */
+function skippedReason(id) {
+  switch (id) {
+    case 'port':
+      return '端口被别的程序占用 —— 需要你决定换哪个端口，插件不能替你选'
+    case 'firewall':
+      return '防火墙规则需要管理员权限，且要你确认放行范围'
+    case 'tailscale':
+      return '装软件需要你同意（本插件不代下载第三方软件）'
+    case 'nodes':
+      return '副机连不上是**结果**不是原因 —— 先修上面那项「Web 服务绑在可达地址」'
+    case 'inject':
+      return 'inject 要跟着 role 一起改，且会影响插件能否加载 —— 请用面板「切换角色」，它会一次改对'
+    case 'roots':
+      return 'roots 目录不存在 —— 建目录要你确认路径（面板写入配置时会自动建）'
+    default:
+      return '这项需要你判断'
+  }
+}
+
+function describeSource(src) {
+  switch (src) {
+    case 'tailscale':
+      return 'Tailscale IP，固定不变、跨网可达'
+    case 'private':
+      return '局域网 IP'
+    case 'config':
+      return '你在配置里指定的地址'
+    default:
+      return '本机回环（仅同机可用）'
+  }
+}
+
+/**
+ * 应用修复计划（**会改文件**）。
+ *
+ * ⚠ 调用方必须已经拿到用户的明确确认（`confirm === 'yes'`）。
+ * 本函数不检查确认 —— 那是路由层的职责（分层：本模块只做"改得安全"，
+ * 不负责"该不该改"）。
+ *
+ * @param {object} o
+ * @param {object} o.plan planFixes 的返回值
+ * @param {object} o.writePatchBlock 注入的写盘函数（便于测试替身）
+ * @param {(file:string)=>string} o.readFile 注入的读函数
+ * @param {string} o.role 要写入的 role（hub/worker/both）
+ * @returns {{ok:boolean, file:string, backup:string, applied:Array, error?:string}}
+ */
+export function applyFixPlan({ plan, writePatchBlock, readFile, role = 'hub' } = {}) {
+  const applied = []
+  if (!plan || typeof plan !== 'object') {
+    return { ok: false, file: '', backup: '', applied, error: '缺少修复计划' }
+  }
+  const fixable = Array.isArray(plan.fixable) ? plan.fixable : []
+  if (fixable.length === 0) {
+    return { ok: false, file: plan.file || '', backup: '', applied, error: '没有可自动修的项' }
+  }
+  if (typeof writePatchBlock !== 'function') {
+    return { ok: false, file: plan.file || '', backup: '', applied, error: '写盘函数不可用' }
+  }
+  if (typeof readFile !== 'function') {
+    return { ok: false, file: plan.file || '', backup: '', applied, error: '读文件函数不可用' }
+  }
+
+  // ── 组装托管块（逐行构造，绝不把用户输入拼进 YAML）──────────────────
+  //
+  // ⚠ 与 setup-routes 的写法一致：每一行都是字面量 + 经过校验的值，
+  // 不做字符串插值以外的任何拼接（防 YAML 注入）。
+  const lines = [
+    '- id: remote-agent',
+    '  name: dsh-remote-agent',
+  ]
+  const wantRole = fixable.some((f) => f.id === 'role')
+  const wantHost = fixable.some((f) => f.id === 'reachability')
+
+  // inject 必须跟着 role 走（hub 要 webServer；worker 要 agentLoop/sessions）
+  const inject = role === 'worker'
+    ? ['tools', 'agentLoop', 'sessions']
+    : ['webServer', 'tools', 'systemPrompt']
+  lines.push(`  inject: [ ${inject.map((s) => `'${s}'`).join(', ')} ]`)
+  lines.push('  config:')
+  // role 总是写（它决定插件怎么跑，缺了会走包内默认 auto）。
+  // 不是"只在 wantRole 时写" —— 缺 role 的配置本身就是坏状态。
+  lines.push(`    role: ${role === 'worker' || role === 'both' ? role : 'hub'}`)
+  if (wantHost) {
+    // host 必须是具体 IP —— 绝不写 0.0.0.0（新版 DSH 会拒绝并崩溃）
+    const host = typeof plan.host === 'string' ? plan.host.trim() : ''
+    if (host !== '' && host !== '0.0.0.0') {
+      lines.push(`    listenHost: '${host.replace(/'/g, "''")}'`)
+    }
+  }
+  if (wantRole) applied.push('role')
+  if (wantHost) applied.push('reachability')
+
+  const blockYaml = `${lines.join('\n')}\n`
+
+  // ── 写盘（writePatchBlock 自带：备份 + 冲突检测 + 写后校验 + 失败回滚）──
+  let result
+  try {
+    result = writePatchBlock({ file: plan.file, blockYaml, force: false })
+  } catch (err) {
+    return { ok: false, file: plan.file, backup: '', applied, error: String(err?.message ?? err) }
+  }
+  if (!result || result.ok !== true) {
+    return {
+      ok: false,
+      file: (result && result.file) || plan.file,
+      backup: (result && result.backup) || '',
+      applied,
+      error: (result && result.error) || '写盘失败',
+    }
+  }
+
+  // ── 写后校验：重新读回来，确认我们的条目在、没有重复 id ──────────────
+  //
+  // 为什么再查一遍：writePatchBlock 校验的是"托管块格式"，而这里要确认的是
+  // "**从用户视角看，文件现在的状态是能用的**"——两者角度不同。
+  try {
+    const after = readFile(plan.file)
+    const ids = [...String(after).matchAll(/^- id:\s*(\S+)/gm)].map((m) => m[1])
+    const dup = ids.filter((x, i) => ids.indexOf(x) !== i)
+    if (dup.length > 0) {
+      return {
+        ok: false,
+        file: plan.file,
+        backup: result.backup || '',
+        applied,
+        error: `写后发现重复 id：${dup.join(', ')} —— 已保留备份，请用「撤销」恢复`,
+      }
+    }
+    if (!ids.includes('remote-agent')) {
+      return {
+        ok: false,
+        file: plan.file,
+        backup: result.backup || '',
+        applied,
+        error: '写后没找到 remote-agent 条目 —— 已保留备份，请用「撤销」恢复',
+      }
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      file: plan.file,
+      backup: result.backup || '',
+      applied,
+      error: `写后校验读文件失败：${String(err?.message ?? err)}`,
+    }
+  }
+
+  return { ok: true, file: plan.file, backup: result.backup || '', applied, error: undefined }
+}
+
+/**
+ * 撤销上一次修复（用备份覆盖回去）。
+ *
+ * @param {object} o
+ * @param {string} o.file 目标文件
+ * @param {string} o.backup 备份文件路径
+ * @returns {{ok:boolean, error?:string}}
+ */
+export function undoFix({ file, backup } = {}) {
+  if (typeof file !== 'string' || file === '') return { ok: false, error: '缺少目标文件' }
+  if (typeof backup !== 'string' || backup === '') return { ok: false, error: '没有可用的备份' }
+  try {
+    if (!fs.existsSync(backup)) return { ok: false, error: `备份文件不存在：${backup}` }
+    const content = fs.readFileSync(backup, 'utf8')
+    // 先写临时文件再 rename（原子，避免中途崩溃留下半截文件）
+    const tmp = `${file}.undo-${process.pid}-${Date.now().toString(36)}`
+    fs.writeFileSync(tmp, content, 'utf8')
+    fs.renameSync(tmp, file)
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err) }
+  }
+}
+
+/** 从 writePatchBlock 的备份命名里认出"这是我们写的备份"（用于列出可撤销项）。 */
+export function isManagedBackup(fileName) {
+  return typeof fileName === 'string' && /^cordis\.patch\.yml\.bak-/.test(fileName)
+}
+
+/** 列出某个目录下最近的备份（给面板「撤销」用）。 */
+export function listBackups(dir, limit = 5) {
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter(isManagedBackup)
+      .map((name) => {
+        const full = path.join(dir, name)
+        try {
+          const st = fs.statSync(full)
+          return { name, path: full, at: st.mtimeMs, bytes: st.size }
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.at - a.at)
+      .slice(0, limit)
+  } catch {
+    return []
+  }
+}