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 生成机制,学习如何根据上下文生成最小修改范围,并在应用前检测目标是否仍然匹配。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计代码编辑协议

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

登录哪都通