返回专栏
· 31 分钟阅读

Coding Agent:智能体如何编写和修改代码?


一、什么是 Coding Agent?

Coding Agent(编程智能体)是一种能够理解软件开发任务,并通过访问代码仓库、调用开发工具和执行程序,自主完成编码任务的 AI Agent。

传统代码补全工具主要根据当前代码上下文预测后续代码,开发者仍然需要决定修改哪些文件、如何组织代码以及如何验证结果。

Coding Agent 则能够围绕一个完整的开发目标开展工作。

例如,用户提出:

在现有项目中增加用户注册接口,支持邮箱和密码注册,完成参数校验、密码加密、数据库保存,并补充单元测试。

Coding Agent 需要完成:

  1. 理解用户需求。
  2. 分析项目目录结构。
  3. 识别使用的编程语言和技术框架。
  4. 查找现有用户模块和接口规范。
  5. 理解数据库模型和业务逻辑。
  6. 制定代码修改计划。
  7. 创建或修改相关文件。
  8. 安装或调用必要依赖。
  9. 运行代码检查和测试。
  10. 根据错误信息修复代码。
  11. 检查最终变更。
  12. 向用户汇报修改内容和测试结果。

它不只是生成一段代码,而是能够参与完整的软件开发流程。

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. 任务分解

可以将开发任务拆分成多个子任务:

  1. 分析现有用户模块。
  2. 检查用户模型和数据库约束。
  3. 检查已有密码处理逻辑。
  4. 定义注册请求和响应结构。
  5. 实现注册业务逻辑。
  6. 增加 API 路由。
  7. 编写单元测试。
  8. 运行测试并修复错误。
  9. 检查最终代码变更。

任务拆分应当考虑依赖关系,而不是简单地按照文本顺序执行。

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 应当:

  1. 读取失败测试。
  2. 定位对应业务代码。
  3. 分析预期结果与实际结果。
  4. 找到根本原因。
  5. 修改代码。
  6. 重新执行相关测试。
  7. 执行必要的回归测试。

不能仅通过修改测试断言,让测试变成通过状态。

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 检查: