AI Agent / 系统课时
设计代码编辑协议
设计代码编辑协议
本篇解决智能体如何安全表达代码修改意图的问题,最终建立一套统一的 Edit Operation 协议,让模型输出的修改动作可以被执行器解析、校验和回滚。
学习目标
- 理解代码编辑协议需要解决的核心问题
- 掌握替换、插入、删除、创建文件和符号修改等操作模型
- 能设计可验证、可追踪的 Edit Operation 数据结构
为什么需要统一编辑协议
代码智能体不能直接把自然语言回复当作修改结果。模型可能理解需求,但真正执行修改时还需要明确的目标文件、修改范围、原始内容校验以及变更类型。
编辑协议的作用是把“修改代码”转换成结构化操作。例如“把函数返回值改成对象”需要进一步表达为修改哪个文件、哪个符号、替换哪段内容,以及修改后的结果。
一个稳定协议通常包含操作类型、目标位置、上下文信息和新内容四部分。

设计 Edit Operation 数据模型
常见编辑动作可以抽象为有限集合:
| 操作类型 | 用途 |
|---|---|
| replace | 替换已有代码片段 |
| insert | 在指定位置插入内容 |
| delete | 删除目标区域 |
| create | 创建新文件 |
| symbol_update | 按函数、类等符号修改 |
一个基础协议示例如下:
json
{
"operation": "replace",
"filePath": "src/user.ts",
"target": {
"startLine": 10,
"endLine": 15
},
"oldContent": "return user.name;",
"newContent": "return { name: user.name };"
}预期结果
text
执行器能够识别一次 replace 操作,并在 src/user.ts 的指定范围内完成替换。协议中的 oldContent 不是冗余字段,它用于确认目标代码仍然保持预期状态。如果文件已经被其他提交修改,执行器可以拒绝应用补丁,避免错误覆盖。
处理符号级修改
文本位置适合简单替换,但大型项目更需要理解代码结构。符号级修改可以使用函数名、类名或模块路径作为目标。
例如:
json
{
"operation": "symbol_update",
"symbol": "UserService.createUser",
"change": "replace_method_body",
"newBody": "return repository.save(user);"
}预期结果
text
执行器定位 UserService.createUser 方法,并仅修改该方法实现。符号级协议降低了行号变化带来的风险,但需要依赖解析器提供 AST 或索引能力。
协议设计中的关键边界
编辑协议需要明确失败行为。常见约束包括:
- 文件不存在时直接失败,不自动创建错误路径
- 上下文不匹配时拒绝覆盖
- 多个操作执行失败时支持回滚
- 每个操作携带唯一 ID 便于日志追踪
这些约束让代码修改从一次性写入变成可验证的变更流程。
本课总结
- Edit Operation 将自然语言修改意图转换为机器可执行结构。
- replace、insert、delete、create 和 symbol_update 覆盖主要代码变更场景。
- 协议必须包含验证信息,避免智能体覆盖错误代码。
下一课预告
下一课将实现文本 Patch 生成机制,学习如何根据上下文生成最小修改范围,并在应用前检测目标是否仍然匹配。
按自己的节奏,确认真正理解。