AI Agent / 系统课时

生成可审查 Diff

生成可审查 Diff

本篇解决代码修改结果难以检查的问题,将智能体产生的文件变化转换为统一 Diff 视图,让用户、审核流程和自动验证系统都能明确知道改了什么、为什么改以及是否符合预期。

学习目标

  • 理解代码修改结果为什么需要标准化 Diff 表示
  • 掌握生成文件级和行级差异的基本流程
  • 能设计供审查与验证使用的 Diff 数据结构

为什么修改结果需要 Diff

代码智能体执行修改后,直接展示完整文件内容通常不是最佳方式。审查者更关心的是变化部分:新增了哪些代码、删除了哪些逻辑、哪些位置被替换,以及修改范围是否符合任务目标。

Diff 的核心价值是把工作区状态变化表示为可比较的数据。它连接了修改执行阶段和人工审核、自动测试阶段,使后续流程可以基于同一种结构处理结果。

一个可审查 Diff 通常包含文件路径、修改类型、变更前内容、变更后内容以及具体行级变化。

Diff 生成流程

生成 Diff 时,需要先保存修改前状态,再获取修改后的工作区状态,最后通过比较算法计算差异。

代码修改 Diff 生成流程图

一个简单的 Diff 记录结构可以如下设计:

json
{
  "file": "src/user.js",
  "changeType": "modify",
  "before": "return user.name;",
  "after": "return user?.name ?? 'unknown';"
}

预期结果

text
生成一条文件修改记录,标识 src/user.js 被修改,并保留修改前后的内容。

实际工程中不会只保存字符串,而会进一步保存行号、上下文和补丁信息,方便精确定位。

设计 Diff 数据模型

智能体修改引擎中的 Diff 不只是展示数据,也可能被后续验证流程消费。因此需要保持结构稳定。

常见字段包括:

字段 作用
filePath 标识修改文件
operation 表示新增、删除或修改
hunks 保存局部变化块
additions 新增行数量
deletions 删除行数量

如果 Diff 数据需要支持回滚,还应包含修改批次 ID,让系统能够找到对应执行记录。

使用 Diff 进行审查和验证

生成 Diff 后,审查流程可以检查修改范围。例如:

python
from dataclasses import dataclass

@dataclass
class DiffSummary:
    file_path: str
    additions: int
    deletions: int

summary = DiffSummary(
    file_path="src/user.py",
    additions=5,
    deletions=2
)

print(summary)

预期输出

text
DiffSummary(file_path='src/user.py', additions=5, deletions=2)

自动化系统可以根据 Diff 判断是否需要触发测试、人工审批或安全检查。例如修改核心配置文件时提高审核等级,修改普通注释时降低处理成本。

常见错误

只保存最终文件内容是最常见的问题,因为它无法解释变化来源。另一个问题是 Diff 与实际执行记录脱节,导致无法追踪是哪一次智能体操作产生了修改。

好的 Diff 系统应该同时关注可读性、机器处理能力和历史追踪能力。

本课总结

  • Diff 是连接代码修改、审核和验证的重要中间表示。
  • 生成 Diff 需要保存修改前后状态并计算结构化变化。
  • 稳定的 Diff 数据模型能够支持自动审核和后续回滚。

下一课预告

下一课将继续完善代码修改引擎,学习如何保存修改批次并实现安全撤销与回滚。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成可审查 Diff

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通