AI Agent / 系统课时
生成可审查 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 数据模型能够支持自动审核和后续回滚。
下一课预告
下一课将继续完善代码修改引擎,学习如何保存修改批次并实现安全撤销与回滚。
按自己的节奏,确认真正理解。