10.3 Patch 系统

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

除了逐行编辑（Edit 工具）和全量覆写（Write 工具）之外，OpenCode 还提供了一种基于补丁（Patch）的文件修改方式——apply_patch 工具。它允许 LLM 以标准化的补丁格式一次性描述对多个文件的创建、删除和修改操作。本节将解析 patch/index.ts 的实现。

10.3.1 patch/index.ts：Diff 补丁的生成与应用

Patch 模块（681 行）实现了一个完整的补丁解析和应用系统。它的补丁格式不是标准的 unified diff，而是一种专为 LLM 设计的自定义格式。

补丁格式

OpenCode 的补丁格式使用 *** 标记来区分不同的操作：

*** Begin Patch
*** Add File: path/to/new-file.ts
+line 1 of new file
+line 2 of new file

*** Delete File: path/to/old-file.ts

*** Update File: path/to/existing.ts
@@ context line
-old line to remove
+new line to add
 unchanged line

*** End Patch

Hunk 类型

补丁被解析为一组 Hunk（操作单元），每个 Hunk 对应一个文件的操作：

export type Hunk =
  | { type: "add"; path: string; contents: string }       // 新增文件
  | { type: "delete"; path: string }                       // 删除文件
  | { type: "update"; path: string; move_path?: string;    // 修改文件
      chunks: UpdateFileChunk[] }

export interface UpdateFileChunk {
  old_lines: string[]          // 被替换的旧行
  new_lines: string[]          // 替换后的新行
  change_context?: string      // 上下文标识（用于定位）
  is_end_of_file?: boolean     // 是否在文件末尾操作
}

update 类型的 Hunk 最为复杂——它包含多个 UpdateFileChunk，每个 chunk 描述了文件中一处局部的替换操作。

补丁解析

parsePatch() 函数解析补丁文本，提取结构化的 Hunk 列表：

export function parsePatch(patchText: string): { hunks: Hunk[] } {
  const cleaned = stripHeredoc(patchText.trim())  // 去除 heredoc 包装
  const lines = cleaned.split("\n")
  const hunks: Hunk[] = []

  // 查找 Begin/End 标记
  const beginIdx = lines.findIndex(line => line.trim() === "*** Begin Patch")
  const endIdx = lines.findIndex(line => line.trim() === "*** End Patch")

  // 遍历标记之间的内容
  while (i < endIdx) {
    if (lines[i].startsWith("*** Add File:")) {
      // 解析新增文件的内容（以 "+" 开头的行）
      hunks.push({ type: "add", path, contents })
    } else if (lines[i].startsWith("*** Delete File:")) {
      hunks.push({ type: "delete", path })
    } else if (lines[i].startsWith("*** Update File:")) {
      // 解析更新 chunks
      hunks.push({ type: "update", path, move_path, chunks })
    }
  }
  return { hunks }
}

模糊匹配应用

apply_patch 的一个突出特点是多级模糊匹配。当在文件中查找要替换的旧行时，它不要求严格的字符级精确匹配，而是提供了四级递进的匹配策略：

function seekSequence(
  lines: string[],
  pattern: string[],
  startIndex: number,
  eof = false
): number {
  // Pass 1: 精确匹配
  const exact = tryMatch(lines, pattern, startIndex, (a, b) => a === b, eof)
  if (exact !== -1) return exact

  // Pass 2: 去除尾部空白后匹配
  const rstrip = tryMatch(lines, pattern, startIndex,
    (a, b) => a.trimEnd() === b.trimEnd(), eof)
  if (rstrip !== -1) return rstrip

  // Pass 3: 去除首尾空白后匹配
  const trim = tryMatch(lines, pattern, startIndex,
    (a, b) => a.trim() === b.trim(), eof)
  if (trim !== -1) return trim

  // Pass 4: Unicode 标准化后匹配
  const normalized = tryMatch(lines, pattern, startIndex,
    (a, b) => normalizeUnicode(a.trim()) === normalizeUnicode(b.trim()), eof)
  return normalized
}

为什么需要多级匹配？因为 LLM 生成的补丁中，上下文行可能存在细微的差异：

• 空白差异：LLM 可能多加或少加了空格/缩进。

• Unicode 差异：LLM 可能将普通引号 ' 变成了智能引号 '，或将连字符 - 变成了破折号 —。

normalizeUnicode() 函数处理了这些常见的 Unicode 替换：

function normalizeUnicode(str: string): string {
  return str
    .replace(/[\u2018\u2019\u201A\u201B]/g, "'")  // 智能单引号 → 普通单引号
    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')   // 智能双引号 → 普通双引号
    .replace(/[\u2010-\u2015]/g, "-")               // 各种破折号 → 连字符
    .replace(/\u2026/g, "...")                       // 省略号 → 三个点
    .replace(/\u00A0/g, " ")                         // 不间断空格 → 普通空格
}

替换应用

找到匹配位置后，applyReplacements() 以倒序应用所有替换，避免索引偏移问题：

function applyReplacements(
  lines: string[],
  replacements: Array<[number, number, string[]]>
): string[] {
  const result = [...lines]
  // 从后往前应用，避免索引偏移
  for (let i = replacements.length - 1; i >= 0; i--) {
    const [startIdx, oldLen, newSegment] = replacements[i]
    result.splice(startIdx, oldLen)
    for (let j = 0; j < newSegment.length; j++) {
      result.splice(startIdx + j, 0, newSegment[j])
    }
  }
  return result
}

10.3.2 apply_patch 工具的实现细节

apply_patch 工具实际上是 Bash 工具的一个"影子功能"——当 Bash 命令被检测为 apply_patch 调用时，会拦截并使用 Patch 模块来处理，而非真正执行 Shell 命令：

// tool/bash.ts 中的检测逻辑
const result = Patch.maybeParseApplyPatch(argv)
if (result.type === "Body") {
  // 拦截！不执行 Shell 命令，而是使用 Patch 模块应用补丁
  const action = await Patch.maybeParseApplyPatchVerified(argv, cwd)
  // ... 应用补丁并返回结果
}

maybeParseApplyPatchVerified() 不仅解析补丁，还会预验证每个操作的正确性——在实际写入文件之前就检查所有替换是否能找到匹配。如果有任何 chunk 无法在目标文件中找到匹配的旧行，会返回 CorrectnessError 而不是部分应用补丁，确保操作的原子性。

---

本节小结

OpenCode 的 Patch 系统实现了一种为 LLM 优化的补丁格式，支持文件的新增、删除和修改操作。核心亮点是四级递进的模糊匹配策略（精确 → 去尾空白 → 去首尾空白 → Unicode 标准化），容忍 LLM 生成补丁时常见的空白和字符差异。替换以倒序方式应用以避免索引偏移，整个操作通过预验证确保原子性。