一、什么是 Coding Agent?
Coding Agent(编程智能体)是一种能够理解软件开发任务,并通过访问代码仓库、调用开发工具和执行程序,自主完成编码任务的 AI Agent。
传统代码补全工具主要根据当前代码上下文预测后续代码,开发者仍然需要决定修改哪些文件、如何组织代码以及如何验证结果。
Coding Agent 则能够围绕一个完整的开发目标开展工作。
例如,用户提出:
在现有项目中增加用户注册接口,支持邮箱和密码注册,完成参数校验、密码加密、数据库保存,并补充单元测试。
Coding Agent 需要完成:
- 理解用户需求。
- 分析项目目录结构。
- 识别使用的编程语言和技术框架。
- 查找现有用户模块和接口规范。
- 理解数据库模型和业务逻辑。
- 制定代码修改计划。
- 创建或修改相关文件。
- 安装或调用必要依赖。
- 运行代码检查和测试。
- 根据错误信息修复代码。
- 检查最终变更。
- 向用户汇报修改内容和测试结果。
它不只是生成一段代码,而是能够参与完整的软件开发流程。
1. Coding Agent 与 AI 代码补全的区别
| 对比维度 | AI 代码补全 | Coding Agent |
|---|---|---|
| 核心目标 | 预测和生成代码 | 完成开发任务 |
| 工作范围 | 当前文件或局部上下文 | 整个代码仓库 |
| 文件操作 | 通常由开发者完成 | 可以自主读取和修改 |
| 任务规划 | 较少 | 可以拆解复杂任务 |
| 工具调用 | 有限 | 可以调用终端、测试、Git 等工具 |
| 错误处理 | 开发者主导 | 可以分析错误并尝试修复 |
| 测试验证 | 通常由开发者执行 | 可以自主运行测试 |
| 任务状态 | 以当前编辑上下文为主 | 可以维护多步骤执行状态 |
AI 代码补全主要解决代码输入效率问题,Coding Agent 则进一步解决软件开发任务的执行问题。
2. Coding Agent 与普通 Chatbot 的区别
普通 Chatbot 通常通过对话提供代码建议,Coding Agent 则可以在获得授权的环境中直接操作代码仓库。
| 对比维度 | 普通 Chatbot | Coding Agent |
|---|---|---|
| 代码理解 | 根据用户提供的上下文 | 可以主动读取项目文件 |
| 代码生成 | 返回代码片段 | 可以直接修改文件 |
| 项目分析 | 依赖用户描述 | 可以分析目录和依赖 |
| 命令执行 | 通常不能直接执行 | 可以调用终端工具 |
| 测试验证 | 提供测试建议 | 可以实际运行测试 |
| 错误修复 | 用户复制错误信息 | 可以读取错误并迭代修复 |
| 结果交付 | 返回文本 | 可以交付代码变更和测试结果 |
Coding Agent 的关键能力是形成一个可执行、可观察、可验证的开发闭环。
二、Coding Agent 的整体架构
Coding Agent 通常由任务规划器、代码理解模块、上下文检索模块、文件操作工具、代码执行环境、测试验证模块和状态管理模块组成。
1. 核心架构
flowchart TD
A["用户开发需求"] --> B["Agent 控制器"]
B --> C["任务理解与规划"]
C --> D["代码库分析"]
D --> E["上下文检索"]
E --> F["代码生成与修改"]
F --> G["文件操作工具"]
G --> H["代码仓库"]
F --> I["终端执行工具"]
I --> J["编译与测试"]
J --> K["结果分析"]
K --> L{"是否满足要求"}
L -->|"否"| M["定位问题并制定修复方案"]
M --> F
L -->|"是"| N["代码审查与变更汇总"]
N --> O["交付开发结果"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style I fill:#EAF3EC,stroke:#83A995,color:#315D49
style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style M fill:#F7EAE7,stroke:#C98D7C,color:#754438
style N fill:#EAF3EC,stroke:#83A995,color:#315D49
style O fill:#DCEFE5,stroke:#4F8B70,color:#24563F
各模块职责如下:
| 模块 | 主要职责 |
|---|---|
| Agent 控制器 | 管理任务执行和工具调用 |
| 任务规划器 | 将需求拆解成开发步骤 |
| 代码库分析 | 理解目录结构、技术栈和项目规范 |
| 上下文检索 | 查找相关代码、接口和依赖 |
| 代码生成模块 | 编写新代码和修改现有代码 |
| 文件操作工具 | 读取、创建、修改和删除文件 |
| 终端执行工具 | 运行命令、脚本和开发工具 |
| 测试验证模块 | 执行测试、编译和静态检查 |
| 状态管理模块 | 保存执行进度、历史结果和异常 |
| 代码审查模块 | 检查变更范围、质量和风险 |
2. Coding Agent 的四层结构
从工程设计角度,可以将 Coding Agent 划分为四个层次。
智能决策层
负责理解需求、分析任务、制定计划、选择工具和判断执行结果。
代码理解层
负责分析代码仓库、检索相关文件、理解函数调用关系、数据结构和模块依赖。
开发执行层
负责读取和修改文件、运行终端命令、执行编译和测试。
质量保障层
负责代码审查、测试验证、权限检查、异常处理和结果交付。
flowchart TB
A["智能决策层"]
A1["需求理解"]
A2["任务规划"]
A3["工具选择"]
A4["结果判断"]
B["代码理解层"]
B1["项目结构分析"]
B2["代码检索"]
B3["依赖关系分析"]
B4["调用链理解"]
C["开发执行层"]
C1["文件读取"]
C2["代码生成"]
C3["文件修改"]
C4["终端执行"]
D["质量保障层"]
D1["单元测试"]
D2["集成测试"]
D3["静态检查"]
D4["代码审查"]
A --> B
B --> C
C --> D
A1 --> A
A2 --> A
A3 --> A
A4 --> A
B1 --> B
B2 --> B
B3 --> B
B4 --> B
C1 --> C
C2 --> C
C3 --> C
C4 --> C
D1 --> D
D2 --> D
D3 --> D
D4 --> D
style A fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style A1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style A2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style A3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style A4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style B1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style B2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style B3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style B4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style C fill:#EAF3EC,stroke:#83A995,color:#315D49
style C1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style C2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style C3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style C4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style D1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
四层并不是简单的一次性流水线。代码理解结果会影响任务规划,测试失败会触发代码修改,代码审查也可能要求重新检索上下文。
三、代码库理解:智能体如何理解整个项目?
Coding Agent 首先要理解项目,而不是立即开始写代码。
如果不了解项目结构、技术栈、已有模块和编码规范,生成的代码很容易与现有系统脱节。
1. 项目目录扫描
假设一个 Python Web 项目具有以下结构:
project/
├── app/
│ ├── api/
│ │ ├── user.py
│ │ └── auth.py
│ ├── models/
│ │ └── user.py
│ ├── services/
│ │ └── user_service.py
│ ├── schemas/
│ │ └── user.py
│ └── main.py
├── tests/
│ ├── test_user.py
│ └── test_auth.py
├── requirements.txt
├── pyproject.toml
└── README.md
Agent 可以通过目录扫描识别:
- 项目使用的语言。
- 应用程序入口。
- API 路由所在位置。
- 数据模型定义。
- 业务逻辑所在模块。
- 测试文件的位置。
- 依赖管理方式。
- 项目文档和开发规范。
目录结构能够提供初步线索,但不能仅凭文件名就断定模块职责,还需要读取具体文件。
2. 项目文件读取
Coding Agent 可以通过文件工具读取代码。
例如:
from pathlib import Path
def read_project_files(root: str):
root_path = Path(root)
for path in root_path.rglob("*.py"):
if any(
part in {
".git",
".venv",
"__pycache__"
}
for part in path.parts
):
continue
print(path)
print(path.read_text(
encoding="utf-8"
))
实际系统不应该无条件读取整个项目。
需要过滤:
- 虚拟环境。
- 构建产物。
- 依赖目录。
- 大型二进制文件。
- 自动生成文件。
- 密钥和环境变量文件。
- 与当前任务无关的文件。
代码仓库可能包含大量文件,全部读取会造成上下文浪费和模型输入成本上升。
3. 项目规范识别
Agent 还需要识别项目中的开发规范。
常见规范文件包括:
| 文件 | 作用 |
|---|---|
| README.md | 项目说明和运行方式 |
| CONTRIBUTING.md | 贡献与开发规范 |
| AGENTS.md | Agent 开发指引 |
| pyproject.toml | Python 项目配置 |
| package.json | Node.js 项目配置 |
| tsconfig.json | TypeScript 配置 |
| .editorconfig | 编辑器格式规范 |
| .gitignore | Git 忽略规则 |
| Dockerfile | 容器构建配置 |
其中,AGENTS.md 可以用于说明代码目录结构、测试命令、代码风格和项目约束。
Agent 应当读取与当前任务相关的规范文件,并将其作为开发过程中的约束条件。
4. 代码结构与依赖关系分析
理解一个项目不能只看目录结构,还需要理解代码之间的关系。
例如:
# app/api/user.py
from app.services.user_service import (
create_user
)
def register_user(data):
return create_user(data)
# app/services/user_service.py
from app.models.user import User
def create_user(data):
user = User(
email=data.email
)
return user
可以看出:
- API 层负责接收请求。
- Service 层负责业务处理。
- Model 层负责数据模型。
Agent 需要理解这些调用关系,避免将业务逻辑错误地写进 API 层,或者重复实现已经存在的功能。
5. 代码检索与上下文构建
大型项目不可能将所有代码一次性输入模型。
通常需要根据任务检索相关代码。
常见方法包括:
关键词检索
通过函数名、类名、接口名称和业务关键词查找代码。
grep -R "create_user" app/
符号检索
通过函数、类、变量和方法的定义位置查找相关代码。
语法树分析
使用 AST(Abstract Syntax Tree,抽象语法树)分析代码结构,识别函数、类、导入关系和调用表达式。
语义检索
通过代码 Embedding 检索语义相近的代码片段。
调用链分析
分析函数之间的调用关系,找到修改目标涉及的上下游模块。
这些方式可以组合使用。
例如,用户要求修改用户注册接口,Agent 可以先搜索 register_user,再找到其调用的 Service、Model、Schema 和测试文件。
6. 代码上下文构建流程
flowchart TD
A["接收开发任务"] --> B["识别任务涉及的模块"]
B --> C["扫描项目目录"]
C --> D["读取项目规范"]
D --> E["检索相关代码"]
E --> F["分析函数和类"]
F --> G["构建依赖关系"]
G --> H["提取必要上下文"]
H --> I["检查上下文是否充分"]
I --> J{"是否能够理解修改范围"}
J -->|"否"| K["补充检索相关文件"]
K --> E
J -->|"是"| L["生成任务实施计划"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F
四、任务规划:智能体如何拆解开发需求?
用户提出的开发需求通常是自然语言,而代码修改需要明确的文件、函数和操作步骤。
Coding Agent 需要将高层需求转换为可以执行的开发计划。
1. 需求理解
例如:
为现有系统增加用户注册功能,支持邮箱和密码注册,验证邮箱格式,密码使用安全哈希存储,并补充测试。
Agent 需要识别:
| 需求 | 技术任务 |
|---|---|
| 用户注册 | 新增注册接口 |
| 邮箱验证 | 增加输入校验 |
| 密码安全存储 | 使用密码哈希算法 |
| 保存用户 | 调用数据库持久化 |
| 重复邮箱处理 | 增加唯一性检查 |
| 测试 | 编写成功和失败场景测试 |
2. 任务分解
可以将开发任务拆分成多个子任务:
- 分析现有用户模块。
- 检查用户模型和数据库约束。
- 检查已有密码处理逻辑。
- 定义注册请求和响应结构。
- 实现注册业务逻辑。
- 增加 API 路由。
- 编写单元测试。
- 运行测试并修复错误。
- 检查最终代码变更。
任务拆分应当考虑依赖关系,而不是简单地按照文本顺序执行。
3. 任务依赖图
flowchart TD
A["分析现有项目"] --> B["检查用户模型"]
A --> C["检查认证模块"]
B --> D["设计注册数据结构"]
C --> D
D --> E["实现注册 Service"]
E --> F["实现注册 API"]
F --> G["编写单元测试"]
G --> H["执行测试"]
H --> I{"测试是否通过"}
I -->|"否"| J["分析并修复错误"]
J --> H
I -->|"是"| K["代码审查"]
K --> L["交付开发结果"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style J fill:#F7EAE7,stroke:#C98D7C,color:#754438
style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F
4. 任务计划的数据结构
Agent 可以将开发计划保存为结构化数据。
{
"task": "实现用户注册功能",
"steps": [
{
"id": "step_1",
"description": "分析现有用户模块",
"status": "completed"
},
{
"id": "step_2",
"description": "实现注册业务逻辑",
"status": "pending"
},
{
"id": "step_3",
"description": "增加注册接口",
"status": "pending"
},
{
"id": "step_4",
"description": "编写和运行测试",
"status": "pending"
}
]
}
这种结构可以帮助 Agent:
- 追踪任务进度。
- 识别尚未完成的步骤。
- 判断任务依赖关系。
- 避免重复执行。
- 在异常后恢复任务。
5. 任务规划不是一次性固定的
开发过程中可能发现原有模块已经提供了注册能力,或者数据库模型不支持预期字段。
因此,计划需要根据实际执行结果动态调整。
例如:
- 发现已有密码加密工具,取消重复实现。
- 发现接口规范要求统一响应格式,调整 API。
- 发现数据库字段缺失,增加迁移任务。
- 发现测试失败,增加修复步骤。
Coding Agent 应当将计划视为可以更新的执行状态,而不是不可改变的静态清单。
五、代码生成:智能体如何编写代码?
理解项目并完成任务规划后,Coding Agent 才开始编写代码。
1. 代码生成的基本原理
大模型根据输入上下文预测后续 Token,逐步生成代码内容。
但在 Coding Agent 中,模型的上下文不只是用户需求,还包括:
- 项目已有代码。
- 相关文件内容。
- 代码规范。
- 依赖和接口定义。
- 任务实施计划。
- 工具执行结果。
- 历史修改记录。
这些信息共同决定生成代码的方向。
2. 基于现有代码进行生成
假设项目已经定义用户模型:
class User:
def __init__(
self,
email: str,
password_hash: str
):
self.email = email
self.password_hash = password_hash
Agent 在实现注册功能时,应当优先复用现有模型,而不是重新创建一套用户数据结构。
例如:
def create_user(
email: str,
password_hash: str
):
user = User(
email=email,
password_hash=password_hash
)
return user
实际项目还需要结合数据库 Session、事务、唯一性约束和异常处理完成持久化。
3. 代码生成的约束条件
Coding Agent 生成代码时,应当遵守以下约束:
语言约束
使用项目已有编程语言和版本。
框架约束
遵循项目已经使用的框架和组件。
接口约束
保持现有 API、函数签名和数据结构兼容。
风格约束
遵循命名、格式、注释和目录组织规范。
安全约束
避免硬编码密钥、明文存储密码和不安全的输入处理。
兼容性约束
避免未经授权地修改其他模块。
4. 新文件创建与代码修改
Coding Agent 可能需要执行两种不同操作。
创建文件
例如新增:
app/api/register.py
修改现有文件
例如修改:
app/api/user.py
两种操作都应记录文件路径和变更内容。
对于已经存在的文件,通常优先采用局部修改,而不是将整个文件重写。
这样可以降低意外删除原有逻辑的风险。
六、代码编辑:智能体如何安全地修改文件?
代码编辑是 Coding Agent 与普通代码生成工具的重要区别之一。
Agent 不仅需要生成代码,还必须将代码准确地写入目标文件,并保证修改范围可控。
1. 整文件覆盖
最简单的方式是读取原文件,生成完整的新文件,再覆盖旧文件。
from pathlib import Path
def write_file(
file_path: str,
content: str
):
path = Path(file_path)
path.write_text(
content,
encoding="utf-8"
)
这种方式适合:
- 创建新文件。
- 修改规模较小的配置文件。
- 重新生成结构简单的代码文件。
但对于大型文件,整文件覆盖容易引入不必要的变更。
2. Diff 补丁修改
更常见的方式是生成代码差异补丁。
例如原始代码:
def calculate_total(price, quantity):
return price * quantity
修改后:
def calculate_total(
price: float,
quantity: int
) -> float:
if price < 0:
raise ValueError(
"price cannot be negative"
)
if quantity < 0:
raise ValueError(
"quantity cannot be negative"
)
return price * quantity
对应的 Diff:
-def calculate_total(price, quantity):
- return price * quantity
+def calculate_total(
+ price: float,
+ quantity: int
+) -> float:
+ if price < 0:
+ raise ValueError(
+ "price cannot be negative"
+ )
+
+ if quantity < 0:
+ raise ValueError(
+ "quantity cannot be negative"
+ )
+
+ return price * quantity
Diff 可以清楚表达:
- 删除了什么代码。
- 新增了什么代码。
- 修改了哪些行。
- 变更涉及哪些文件。
这使代码修改更容易审查和回滚。
3. 基于 AST 的代码修改
AST(抽象语法树)不仅可以用于代码分析,也可以用于代码变换。
例如,Python 的 AST 可以识别函数定义、参数、返回值和表达式。
import ast
source = """
def add(a, b):
return a + b
"""
tree = ast.parse(source)
for node in ast.walk(tree):
if isinstance(
node,
ast.FunctionDef
):
print(node.name)
print(node.lineno)
print(node.end_lineno)
AST 修改适合结构明确的代码转换任务。
例如:
- 批量修改函数名称。
- 增加函数参数。
- 替换特定表达式。
- 分析导入依赖。
- 执行代码结构迁移。
不过,AST 变换需要额外关注注释、格式、装饰器和源代码位置等信息。并不是所有修改都适合直接操作 AST。
4. 代码修改方式对比
| 修改方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 整文件覆盖 | 实现简单 | 容易产生无关变更 | 新文件、小文件 |
| 字符串替换 | 操作直接 | 容易误匹配 | 明确的小范围替换 |
| Diff Patch | 变更清晰 | 需要正确匹配上下文 | 日常代码修改 |
| AST 变换 | 结构化、语义明确 | 实现复杂 | 批量结构化改造 |
| IDE 编辑接口 | 可结合编辑器上下文 | 依赖具体环境 | IDE 内智能编码 |
5. 文件修改前后的安全检查
在修改文件前,Agent 应当检查:
- 文件是否存在。
- 文件是否属于当前工作区。
- 是否有未提交的用户修改。
- 修改是否符合任务范围。
- 是否涉及敏感配置。
- 是否需要用户确认。
修改完成后,还应检查:
- 文件是否成功写入。
- Diff 是否符合预期。
- 是否误删其他代码。
- 是否产生格式错误。
- 是否修改了不相关文件。
6. 文件修改的完整流程
flowchart TD
A["确定目标文件"] --> B["读取原始内容"]
B --> C["分析修改范围"]
C --> D["生成修改方案"]
D --> E["生成 Diff 补丁"]
E --> F["检查补丁上下文"]
F --> G{"补丁是否合理"}
G -->|"否"| H["重新生成补丁"]
H --> E
G -->|"是"| I["检查文件修改权限"]
I --> J["应用补丁"]
J --> K["重新读取文件"]
K --> L["验证最终内容"]
L --> M["记录文件变更"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style E fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style H fill:#F7EAE7,stroke:#C98D7C,color:#754438
style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style J fill:#EAF3EC,stroke:#83A995,color:#315D49
style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style L fill:#EAF3EC,stroke:#83A995,color:#315D49
style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F
七、工具调用:智能体如何操作开发环境?
Coding Agent 的能力很大程度上取决于它能够调用哪些开发工具。
模型本身负责决策和生成参数,工具负责执行具体操作。
1. 常见开发工具
| 工具类别 | 典型工具 | 主要作用 |
|---|---|---|
| 文件读取 | Read、Glob | 查找和读取文件 |
| 文件编辑 | Edit、Write | 修改和创建文件 |
| 终端执行 | Bash、Shell | 执行命令 |
| 代码搜索 | Grep、ripgrep | 搜索代码 |
| 版本控制 | Git | 查看和管理代码变更 |
| 测试执行 | pytest、Jest | 运行测试 |
| 代码检查 | Ruff、ESLint | 静态检查和规范验证 |
| 构建工具 | Maven、Gradle、npm | 编译和构建 |
| 调试工具 | Debugger | 分析运行时问题 |
2. Tool Calling 的基本机制
假设模型需要运行测试。
它不会直接在模型内部执行命令,而是生成一个工具调用请求。
例如:
{
"tool": "run_command",
"arguments": {
"command": "pytest tests/"
}
}
工具执行后返回结果:
{
"exit_code": 0,
"stdout": "12 passed",
"stderr": ""
}
模型再根据结果决定下一步操作。
需要注意,工具调用参数必须经过程序验证,不能因为模型生成了命令,就直接给予无限制的系统执行权限。
3. 工具调用闭环
flowchart TD
A["Agent 分析开发任务"] --> B["选择开发工具"]
B --> C["生成工具调用参数"]
C --> D["工具参数校验"]
D --> E{"是否允许执行"}
E -->|"否"| F["拒绝或请求授权"]
E -->|"是"| G["执行工具"]
G --> H["获取执行结果"]
H --> I["结果返回 Agent"]
I --> J["模型分析结果"]
J --> K{"任务是否完成"}
K -->|"否"| B
K -->|"是"| L["整理最终结果"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style D fill:#EAF3EC,stroke:#83A995,color:#315D49
style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style F fill:#F7EAE7,stroke:#C98D7C,color:#754438
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style J fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style K fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F
4. 工具权限分级
不是所有工具都应该拥有相同权限。
可以按照操作风险划分:
| 权限等级 | 工具能力 | 控制策略 |
|---|---|---|
| 只读 | 查看文件、搜索代码 | 通常允许 |
| 受限写入 | 修改工作区文件 | 限定目录 |
| 普通执行 | 运行测试和格式化 | 沙箱执行 |
| 高风险执行 | 安装依赖、修改配置 | 审核和限制 |
| 特权执行 | 删除文件、访问外部资源 | 明确授权 |
| 发布操作 | 推送代码、部署生产 | 独立审批 |
特别需要注意:
- 不应将模型生成的命令直接拼接到高权限 Shell。
- 应限制工作区之外的文件访问。
- 应限制网络访问和敏感环境变量。
- 应对依赖安装和执行脚本设置权限。
- 应防止命令注入和路径穿越。
八、代码执行与测试验证
Coding Agent 生成代码后,不能仅凭模型判断代码正确。
必须通过实际执行和测试验证结果。
1. 为什么需要测试?
模型生成的代码可能存在:
- 语法错误。
- 类型错误。
- 未定义变量。
- 依赖缺失。
- 接口不兼容。
- 边界条件遗漏。
- 业务逻辑错误。
- 并发安全问题。
- 安全漏洞。
因此,代码生成之后需要建立质量验证机制。
2. 测试类型
| 测试类型 | 作用 | 常用工具 |
|---|---|---|
| 语法检查 | 检查语法是否合法 | Python、编译器 |
| 类型检查 | 检查类型问题 | mypy、TypeScript |
| 静态分析 | 识别潜在代码问题 | Ruff、ESLint |
| 单元测试 | 验证单个函数或模块 | pytest、Jest |
| 集成测试 | 验证模块之间的协作 | pytest、Testcontainers |
| 端到端测试 | 验证完整业务流程 | Playwright |
| 安全扫描 | 检查已知安全风险 | Semgrep、依赖扫描工具 |
| 构建验证 | 检查项目是否能够构建 | Maven、Gradle、npm |
3. 测试驱动的代码修复
例如,Agent 修改了一个计算函数:
def calculate_discount(
price: float,
discount: float
) -> float:
return price * (1 - discount)
可以编写测试:
def test_calculate_discount():
assert calculate_discount(
100,
0.2
) == 80
def test_zero_discount():
assert calculate_discount(
100,
0
) == 100
但这些测试还不够。
还需要考虑:
- 价格为负数。
- 折扣大于 1。
- 折扣小于 0。
- 输入为非数字。
- 浮点精度问题。
测试的作用是验证业务约束,而不只是验证代码能够运行。
4. 测试失败后的修复机制
当测试失败时,Agent 需要读取错误信息,并分析失败原因。
例如:
FAILED tests/test_user.py::test_create_user
AssertionError:
Expected password_hash
but received plain_password
Agent 应当:
- 读取失败测试。
- 定位对应业务代码。
- 分析预期结果与实际结果。
- 找到根本原因。
- 修改代码。
- 重新执行相关测试。
- 执行必要的回归测试。
不能仅通过修改测试断言,让测试变成通过状态。
5. 测试验证闭环
flowchart TD
A["完成代码修改"] --> B["执行语法检查"]
B --> C["执行静态分析"]
C --> D["运行单元测试"]
D --> E["运行集成测试"]
E --> F["汇总测试结果"]
F --> G{"是否全部满足要求"}
G -->|"是"| H["执行代码审查"]
G -->|"否"| I["分析失败原因"]
I --> J["定位问题代码"]
J --> K["制定修复方案"]
K --> L["修改代码"]
L --> B
H --> M["生成验证报告"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#EAF3EC,stroke:#83A995,color:#315D49
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style I fill:#F7EAE7,stroke:#C98D7C,color:#754438
style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style L fill:#EAF3EC,stroke:#83A995,color:#315D49
style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F
6. 测试通过不代表代码一定正确
测试只能验证已经覆盖的场景。
例如,一个接口的单元测试全部通过,并不能证明:
- 所有输入都合法。
- 数据库事务一定安全。
- 并发请求不会产生重复数据。
- 接口不存在权限漏洞。
- 代码在生产环境一定正常运行。
因此,Coding Agent 还需要结合静态分析、代码审查、集成测试和必要的人工验证。
九、代码审查:智能体如何检查自己的修改?
代码生成和测试通过之后,还需要进行代码审查。
代码审查的目标不仅是发现语法错误,更重要的是判断修改是否符合需求、是否影响现有系统,以及是否引入安全风险。
1. Git Diff 分析
Git Diff 可以显示代码仓库中的具体变更。
例如:
git status --short
git diff --stat
git diff
Agent 可以通过 Diff 检查: