# Patch File 工具设计

> 创建: 2026-06-15 | 状态: 设计定稿待实施 | 优先级: P0
> 关联 todo: F-260615-06 [P0]

---

## 一、问题定义

### 1.1 现状缺口

DevFlow AI agent 有 `write_file`（全量覆盖写入）但**无局部编辑能力**。AI 需要修改文件中某几行时只能：

```
read_file → AI 在 context 中拼出完整新内容 → write_file 全量覆盖
```

**问题链**：
1. **Token 浪费**：大文件（几百行）只改 3 行却要重发全部内容
2. **事故风险**：write_file 全量覆盖已出事故（PROGRESS.md 762 行 → 248 字节，FR-S7 记录）
3. **无审计粒度**：无法知道「改了哪里」，只有「整个文件被替换了」
4. **并发不安全**：join_all 并行场景下多工具操作同一文件无保护

### 1.2 目标

提供 `patch_file` 工具，让 AI 能做**精确的局部文本替换**，形成完整的文件操作闭环：

```
read_file(读) → search_in_file(定位) → patch_file(改) → run_command(验证)
```

---

## 二、API 设计

### 2.1 请求结构

```rust
/// 局部文件更新请求
struct PatchFileRequest {
    /// 目标文件路径（必填，走 validate_path 校验 + 黑名单）
    path: String,

    /// 文件指纹（可选）：用于检测外部修改
    /// 格式: "{unix_timestamp}_{size}" 如 "1718400000_12345"
    /// 由 read_file 返回的 file_hash 字段携带
    expected_hash: Option<String>,

    /// 有序补丁列表（从文件末尾往前执行，避免行号偏移）
    patches: Vec<Patch>,
}

/// 单个补丁
struct Patch {
    /// 必填：要替换的旧文本（精确匹配 = 乐观锁）
    old_text: String,

    /// 必填：替换后的新文本
    new_text: String,

    /// 可选：行号辅助定位（快速跳转 + 去歧增强）
    /// 有值时优先跳到该行检查 old_text；不匹配则降级全文扫描
    line: Option<u32>,

    /// 可选：old_text 之前的上下文锚（去歧——多匹配时精确锁定）
    before_text: Option<String>,

    /// 可选：old_text 之后的上下文锚（去歧）
    after_text: Option<String>,
}
```

### 2.2 响应结构

```rust
struct PatchResult {
    success: bool,
    patches_applied: usize,   // 成功替换的 patch 数
    total_matches: usize,     // 每个 patch 的总命中数（含未替换的）
    lines_changed: i32,       // 总行数变化（正=增加 负=减少）
    warnings: Vec<String>,    // ["匹配到 3 处，仅替换第 1 处"]
    file_hash: String,        // 操作后的新指纹（下次操作用）
}
```

### 2.3 read_file 扩展（返回指纹）

现有 read_file 返回值新增字段：

```rust
struct ReadFileResult {
    path: String,
    content: String,
    size: u64,
    lines: u32,
    // 新增：
    modified: String,     // ISO8601 或 unix timestamp
    file_hash: String,    // mtime+size 指纹，如 "1718400000_12345"
}
```

### 2.4 LLM 描述（tool_registry 注册用）

```
"局部更新文件内容。用于精确修改文件的特定部分（而非全量覆盖）。
 每个补丁指定 old_text（要替换的原文）和 new_text（新内容）。
 可选 line 辅助定位、before/after_text 上下文锚定消除歧义。
 属 Medium 风险操作（修改已有文件），需人工审批。
 注意：old_text 必须与文件内容完全匹配（含空格/缩进）；若文件已被外部修改，
 请先重新 read_file 获取最新内容和 file_hash。"
```

---

## 三、核心决策记录

### 决策 1：定位方式 — old_text 精确匹配为主，line 为辅

| 方案 | 示例 | 优点 | 缺点 |
|------|------|------|------|
| **A: old_text ✅ 选定** | 匹配 "fn main() {" 替换 | =隐式乐观锁；AI零认知负担（复制即用）；内容变了自动冲突报错 | 改动大时 old_string 长 |
| B: line 行号 | 替换第 42 行 | 短小精悍 | 文件改了行号偏移；AI需先search定位（多一轮IPC） |
| C: 正则 regex | 匹配 `/return Err\(.*\)/` | 表达力强 | AI生成regex易出错；转义复杂 |

**折中**：old_text **必填**（主定位），line **可选**（辅助快速跳转+去歧），before/after_text **可选**（多匹配去歧）。

**理由**：
- AI 做 edit 时天然持有「要改哪段」上下文，复制即用（最小认知路径）
- old_text 天然防并发冲突（CAS 语义：Compare-And-Swap）
- line 不单独使用（无内容校验=盲替换，并发不安全）

### 决策 2：多匹配处理 — 替换第 1 处 + warning

```
文件中有 N(N>1) 处相同 old_text:
  → 仅替换第 1 处
  → 返回 warning: "⚠️ 匹配到 N 处，仅替换第 1 处"
  → AI 收到 warning 后可加 before/after_text 缩小范围重试
```

**不选**「全部替换」（太危险，可能批量错改）或「拒绝执行」（太严格，第 1 处往往就是目标）。

### 决策 3：并发安全 — 文件级 Mutex（不用队列）

#### 为什么不用队列

| 维度 | 通用文件锁队列 | DevFlow 实际需要 |
|------|-------------|-----------------|
| 范围 | 全局、所有会话、所有文件 | 仅 join_all 并发窗口 + 远期多会话 |
| 粒度 | 每文件独立 FIFO 队列 | 文件级 Mutex 就够 |
| 复杂度 | 高（调度/超时/死锁检测） | **极低（~15行）** |
| 场景 | 多用户 / 分布式 | 单进程单用户桌面应用 |

#### 当前真实并发源

```
唯一并行点: audit.rs:338 join_all — Low 风险工具并行执行
典型场景: AI 同时 list_projects + read_file + (未来) patch_file 同一文件
```

#### 实现

```rust
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Mutex;
use once_cell::sync::Lazy;

/// 全局文件锁表：每个路径一把互斥锁
static FILE_LOCKS: Lazy<Mutex<HashMap<PathBuf, ()>>> =
    Lazy::new(|| Mutex::new(HashMap::new()));

// handler 内使用:
let abs_path = validated_path.canonicalize()?;
let _guard = FILE_LOCKS
    .lock()
    .entry(abs_path)
    .or_insert_with(|| ());
// guard drop 时自动释放
```

**效果**：同一文件读写串行化，不同文件仍并行。Mutex 释放后后续操作继续。

### 决策 4：外部脏写防御 — expected_hash 指纹校验

#### 指纹选型

| 方案 | 精度 | 开销 | 适用 |
|------|------|------|------|
| **mtime + size ✅ 选定** | 秒级 | ~μs（一次 metadata 调用） | 本地桌面应用 |
| blake3/sha256 | 内容级 | 大文件 ms 级 | 需要密码学强度时 |
| inode + mtime | Unix 语义 | ~μs | Windows inode 不同 |

选 **mtime + size**：DevFlow 是本地桌面应用，「外部修改」= 用户切 VS Code 改了几行再回来，时间差 >1s。实现最简单。

#### 流程

```
read_file(path) → { content, file_hash: "1718400000_23456" }
                    ↓
AI 基于内容决策                  ↓
patch_file({ path, expected_hash: "1718400000_23456", ... })
                    ↓
后端:
  ① current_meta = metadata(path)
  ② current_hash = format!("{}_{}", modified.timestamp(), size)
  ③ current_hash != expected_hash?
     → Err("⚠️ 文件已被外部修改(hash 不匹配)，请重新读取")
        含 current_hash 让前端可选自动重读
  ④ hash 通过 → 执行 patch（L2 old_text 校验 + L3 .bak）
```

### 决策 5：截断策略 — 软删除标记（非真删）

关联 UX-2025-09 编辑消息功能。patch_file 本身不涉及消息截断，但设计原则一致：

```
messages 表: status 列
  active    — 正常显示
  truncated — 被编辑截断（前端不展示，后端不进 context）
  保留历史可追溯，与 WF-A soft_delete 模式一致
```

---

## 四、三层防御架构

```
┌─────────────────────────────────────────────┐
│           L1: 文件级 Mutex                   │
│  防时机冲突：同文件读写自动串行化              │
│  实现: HashMap<PathBuf, Mutex<()>> (~15行)   │
│                                             │
│  ┌───────────────────────────────────────┐  │
│  │         L2: old_text 精确匹配          │  │
│  │  防内容错配：= 乐观锁(CAS)             │  │
│  │  内容变了 → 匹配不上 → 报错            │  │
│  │  实现: 内容扫描 (~20行)                │  │
│  │                                       │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │    L3: expected_hash 指纹校验     │  │  │
│  │  │  防版本漂移: 外部修改检测         │  │  │
│  │  │  实现: metadata() (~10行)         │  │  │
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
│                                             │
│  底层兜底: FR-S7 .bak 备份（误操作可恢复）    │
└─────────────────────────────────────────────┘
```

各层职责独立、互补：

| 层 | 管 | 防什么 | 失效后果 |
|----|-----|--------|---------|
| L1 Mutex | 时机 | 两操作同时碰同一文件 | 数据丢失/半写 |
| L2 old_text | 内容 | 操作基于过时内容 | 错改别处 |
| L3 hash | 版本 | read→patch之间文件被外部改 | 基于错误版本操作 |
| .bak | 恢复 | 以上全失效时的最后防线 | 可回滚 |

---

## 五、查找策略（line + old_text 组合）

```
有 line 参数?
  ├─ YES → 跳到该行，检查周围是否包含 old_text
  │   ├─ 匹配 → 替换（快速路径 ✅）
  │   └─ 不匹配(行已偏移) → 降级: 全文扫描 old_text
  └─ NO  → 全文扫描 old_text

全文扫描结果:
  ├─ 0 处匹配 → Err("未找到目标文本，文件可能已被修改")
  ├─ 1 处匹配 → 替换 ✅
  └─ N 处匹配(N>1) → 替换第 1 处 + warning("匹配到 N 处...")
```

---

## 六、边界情况处理

| 边界情况 | 行为 | 理由 |
|---------|------|------|
| 文件不存在 | Err("文件不存在") | 安全第一 |
| 文件 >1MB | warn + 继续或拒绝（复用 FR-S2 上限） | 防性能问题 |
| 二进制文件（含 \0） | Err("不支持二进制文件") | 文本操作不适用 |
| old_text 为空串 | Err("old_text 不能为空") | 防全文件匹配 |
| new_text == old_text | success + warning("无实际更改") | 不浪费 I/O |
| patches 为空 | Err("patches 不能为空") | 无意义调用 |
| 单次 patch 文件膨胀 >900% | warn（复用 FR-S7 逻辑） | 异常检测 |
| 目标路径是 .bak/.tmp | is_noise_file 过滤拒绝（CR-03） | 不改临时文件 |
| 路径含 ".." | validate_path 黑名单拦截 | 路径遍历防护 |
| RiskLevel | **Medium**（修改已有文件） | 比 write_file 同级（都是改文件） |

---

## 七、性能分析

| 操作 | 开销 | 对比基准 |
|------|------|---------|
| Mutex 获取/释放 | ~100ns（非竞争）/ μs 级（等待） | 文件 I/O 是 ms 级，可忽略 |
| 全文扫描 old_text | O(n), n=行数(<1MB) | <1ms |
| hash 计算 | metadata() 一次系统调用 | ~μs 级 |
| .bak 备份 | 文件大小一次 copy | SSD ~100MB/s |
| **总开销** | | **<5ms（<< LLM 秒级延迟）** |

---

## 八、与现有架构兼容性

| 维度 | 兼容性 |
|------|--------|
| tool_registry 注册 | ✅ 完全复用 write_file 模式 |
| RiskLevel 分流 | ✅ Medium → 审批（白名单收紧：纯读取外全审） |
| audit 审计日志 | ✅ process_tool_calls 自动入库 |
| validate_path | ✅ 复用黑名单 + canonicalize |
| .bak 备份 | ✅ 复用 FR-S7 已有逻辑 |
| ToolCard 前端渲染 | ✅ args 键值对自动适配 |
| 数据变更联动 AR-11 | ✅ emit df-data-changed 触发刷新 |
| 会话级授权 AE-04 | ✅ write_file 同类操作，可纳入 session_trust |

---

## 九、实施步骤

### 第一批（核心三件套，~50 行后端 + 前端零改动）

1. **`mod.rs` 或 `tool_registry.rs` 顶层**：加 `FILE_LOCKS` 静态 Mutex（~10 行）
2. **`tool_registry.rs`**：注册 `patch_file` handler（~40 行）
   - 参数解析 + validate_path
   - expected_hash 校验（可选，第一批可先加框架）
   - 逐 patch 执行：扫描 old_text → 替换 → 记录结果
   - .bak 备份（复用 write_file 逻辑）
   - 截断输出（stdout/stderr 各 10KB）
3. **测试**：AI 调用 `patch_file` 改一个已知文件，验证替换正确性

### 第二批（增强层，按需）

4. before/after_text 锁定逻辑（~15 行）
5. expected_hash 指纹校验完整接入（~10 行）
6. read_file 返回值扩展 file_hash 字段（~5 行）

### 第三批（远期）

7. replace_all 开关
8. regex 支持（old_regex 字段）
9. undo stack（会话内 patch 历史）

---

## 十、替代方案否决记录

| 方案 | 否决理由 |
|------|---------|
| sed/awk via run_command | B-37 stdout 空；修好后也是间接操作，无原子性/备份/审计 |
| write_file 全量覆盖 | 已出事故(762→248字节)；大文件 token 浪费；无 diff |
| git apply (Git-based patch) | 强依赖 git 仓库；非 git 目录不可用 |
| JSON Patch (RFC 6902) | 面向 JSON/结构化数据；不适合自由格式文本 |
| AST-level (tree-sitter) | 过度工程；需每语言 parser；AI 代码未必能 parse |
| 纯 line 号编辑 | 无内容校验=并发不安全；行号漂移易出错 |
| 全局文件队列 | 单用户桌面不需要；Mutex 够用且简单 10x |