> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件检查点与回滚

> 自动文件快照、选择性回滚、外部副作用检测与 Agent 感知恢复。

# 文件检查点与回滚

每当 Agent 执行破坏性命令（文件编辑、Shell 命令）时，Myrm 会自动创建 **Shadow Git 快照**。你可以查看变更、选择性恢复文件，Agent 会自动适应你的回滚操作。

## 批量原子编辑

当 Agent 需要在同一文件内修改多处（批量改 import、更新多个常量等），`file_edit_tool` 支持 **`edits` 数组**（最多 20 条），并在**单次原子事务**中完成：

* **一次读、一次写** — 全部替换在内存中完成后再统一落盘
* **重叠预检** — 原文中搜索区域重叠的 edit 会被 upfront 拒绝
* **verify 全批回滚** — `verify_command` 失败（如语法检查）时，**整批** edit 一并撤销
* **UI** — 进度面板展示合并 diff，含 `--- edit 1 ---`、`--- edit 2 ---` 分段

避免「第 3 段失败但前 2 段已写坏文件」的多轮调用经典故障。已通过 Chrome LIVE WebUI E2E 验证（真实 LLM + 真实 workspace 写盘）。

## 工作流程

<Steps>
  <Step title="自动快照">
    在任何破坏性操作前，系统透明地使用隔离的 Shadow Git 仓库快照所有跟踪文件——完全独立于项目的 `.git`。
  </Step>

  <Step title="可视化时间线">
    打开历史面板查看所有快照的时间线。每张卡片显示哪些文件被更改，并附带行级统计（+X/-Y 行）。
  </Step>

  <Step title="选择性恢复">
    选择特定文件回滚，同时保留其他更改。也可以全量恢复并通过确认对话框二次确认。
  </Step>

  <Step title="Agent 自动感知">
    恢复文件后，Agent 在下一轮对话时自动检测到回滚操作并重新读取受影响的文件——无需手动干预。
  </Step>
</Steps>

## 多智能体活动视图

当多个 Agent 协作时，每个快照自动标记触发它的 Agent 名称。快照面板提供：

* **Agent 名称标签** — 每张快照卡片显示负责 Agent 的名称（蓝色标签）
* **按智能体过滤** — 当 2+ 个 Agent 产生快照时，过滤栏自动出现，支持查看特定 Agent 的快照
* **SSE 实时刷新** — 新快照通过 Server-Sent Events 自动出现，500ms 防抖（无需手动刷新）

轻松回答"哪个 Agent 改了什么？"并在需要撤销某个 Agent 的工作时进行精准回滚。

## 外部副作用预警

当命令涉及文件系统之外的不可逆副作用时，Myrm 自动标记：

| 类别       | 示例                                             | 警告                |
| -------- | ---------------------------------------------- | ----------------- |
| **数据库**  | `psql`、`mysql`、`redis-cli`、`mongo`             | 数据库变更无法通过文件回滚撤销   |
| **网络**   | `curl -d`、`http POST`、`wget --post`            | HTTP 写操作已发送到远程服务器 |
| **容器/云** | `docker rm`、`kubectl delete`、`terraform apply` | 基础设施变更在外部持久存在     |

恢复包含这些操作的快照时，UI 显示清晰警告：

> "文件将被恢复，但此命令期间的数据库/网络/容器操作无法撤销。"

## 零配置

文件检查点开箱即用：

* **无需配置** — 所有部署模式默认启用
* **不污染 Git** — Shadow Git 完全隔离于项目之外
* **零性能影响** — 异步快照，3 秒超时保护
* **自动存储管理** — 每项目 50 个快照、全局 2GB 上限、自动清理

## 存储架构

Shadow Git 使用共享裸仓库和按项目分支：

* **内容去重** — 跨项目相同文件只存一份
* **孤儿清理** — 已删除项目自动修剪
* **损坏修复** — 检测到损坏时自动 `git fsck` + repack
* **全局 GC** — 定期垃圾回收保持最小磁盘占用

## 崩溃恢复

服务器在任务中途崩溃时：

1. LangGraph 持久化 SQLite 检查点在每个图节点转换时保存完整状态
2. 重启时 `OfflineDurableTask` 检测中断的任务
3. 从精确断点恢复任务——无需用户重新操作

这在架构上优于手动检查点回调（某些竞品的做法），因为状态在每个图节点转换时自动捕获，而非仅在手动标注点保存。

## 6 层中断自愈体系

文件检查点只是 Myrm 完整中断恢复体系的一层：

| 层级       | 保护对象           | 恢复机制                               |
| -------- | -------------- | ---------------------------------- |
| **图状态**  | 整个 Agent 执行状态  | LangGraph SQLite 检查点 + 增量 dill 序列化 |
| **子任务**  | 关机时的子 Agent 工作 | SIGTERM 自动保存检查点 + 无缝恢复             |
| **对话分叉** | 对话探索分支         | 从任意检查点分叉 + 完整父级血统追踪 + 沙箱自动隔离       |
| **目标管理** | 因预算/用户暂停的长期目标  | 恢复时重置计数器，保留所有历史进展                  |
| **文件快照** | 工作区文件修改        | Shadow Git 选择性恢复 + Agent 自动感知      |
| **流恢复**  | LLM 流式传输网络中断   | 4 种策略：单次/续传/截断/溢出降级                |

无论何种中断——进程崩溃、网络中断、用户暂停或预算用尽——Myrm 都能从精确断点恢复，零数据丢失。

## 实时 Diff 可视化

Agent 每次修改文件后，Myrm 自动计算 unified diff 并通过 SSE 流式推送到界面——无需刷新。

### 你看到什么

* **文件列表 + 变更统计** — 每个被修改的文件显示 `+N/-N` 增删行数
* **点击展开** — 内联查看完整 diff，带语法高亮
* **Unified 或 Split 视图** — 一键切换单栏（GitHub 风格）和左右并排对比
* **语言感知高亮** — Prism.js 根据文件扩展名自动识别语言
* **行号** — 旧/新行号双列显示
* **复制 diff** — 一键复制原始 diff 内容

### 工作原理

1. **DiffCollectorObserver**（harness 层）拦截每次文件写入/编辑
2. 基于当前回合的初始快照计算累积 unified diff
3. 通过 `FILE_DIFF` SSE 事件推送到前端
4. **FilePathRenderer** 显示文件徽标和变更统计
5. **DiffViewer** 在展开时渲染完整的交互式 diff

### 安全限制

* 长 diff 自动截断至 **2000 行**，并显示 `(truncated)` 标记
* 二进制文件显示 "Binary file changed" 而非乱码
* DiffViewer 限制 **400px 最大高度** + 滚动——不会占满对话区

### 消息级 Turn Undo（Honest UX）

Agent 修改文件后，WebUI 每条助手消息旁有 **Undo**。可预览 diff 并仅还原该 turn 内可 revert 的文件。

**诚实反馈，不做假承诺：**

| 情况             | 界面表现                 |
| -------------- | -------------------- |
| 本消息无文件变更       | 提示「本消息无文件变更」         |
| 全部跳过（如文件 >2MB） | 明确原因：文件过大或快照存储已满     |
| 部分可还原          | Popover 标注哪些路径可/不可还原 |

会话顶部 chips 行提供 **会话级 Undo**，规则相同。

IM 渠道：`/undo` 删除最后一轮并还原关联文件；无法还原的路径会在回复中明确说明。

Turn Undo（消息级、会话级或 IM）成功后，Agent 在下一轮会通过 **restore\_inbox** 收到与 Shadow Git 恢复相同的通知，主动 re-read 文件，而不是沿用过时的对话记忆。

### 空写入拒绝与失败横幅

当 Agent 误调用 `file_write_tool` 且内容为**空、纯空白、或仅含零宽字符/BOM 等不可见字符**时，Myrm **不会**在磁盘创建误导性文件，而是：

1. 工具层返回明确错误（`Cannot write empty file content`）
2. Turn 级 mutation verifier 记录失败
3. WebUI 在该条助手消息下显示 **FileModificationWarning** 黄色横幅，告知「文件修改失败 — 变更已自动回滚」

刷新页面后横幅仍会保留（`fileMutationFailures` 随助手消息 metadata 持久化）。

这样用户不会把模型的「已写入」口头承诺误当成真实落盘。竞品（如 OpenClaw/nullclaw 路径）多数允许空 content 写入，且缺少同等 UI 诚实提示。

<Note>
  Turn Undo 使用轻量 per-message 快照（默认开启、零配置）。下方 Shadow Git 检查点是更深层的命令级回滚，二者互补。
</Note>

### 查看后决策

看完 diff 后，你可以：

* **Undo 本消息** — 一键还原该 turn（Honest UX，见上）
* **确认** — 继续对话，修改保留
* **回滚** — 使用文件检查点（上方）将任意文件恢复到修改前
* Agent 自动检测回滚并据此调整后续动作