工具与 Agent 工程：可验证的行动闭环

提示词和上下文准备好之后，AI 编程会进入另一个阶段：不只是给建议，而是读项目、改文件、运行命令、观察失败、继续修复，直到能用证据说明任务完成。

订单导出很适合说明这个变化。只回答“可以这样实现”并不能交付功能；真正有用的 Agent 要能找到订单列表入口，接入导出 API，补权限测试，运行构建，发现失败后回到代码继续调整。

从建议到行动

没有工具时，模型只能给出步骤：

你可以在订单列表增加导出按钮，调用后端接口生成 CSV，
并为权限和失败情况补充测试。

这些建议可能正确，但执行仍然落在人身上。人要自己找文件、改代码、跑测试、复制错误、再把错误交给模型分析。

有工具的 Agent 可以把这件事变成闭环：

1. 读取订单列表页面和 API 模块。
2. 根据上下文确认筛选参数和权限点。
3. 修改页面、接口调用和导出服务。
4. 补充权限、字段、空结果、失败状态测试。
5. 运行相关测试和构建命令。
6. 如果失败，读取错误，回到对应文件修复。
7. 汇报 diff、验证结果和剩余风险。

这个闭环的核心不是“自动改代码”，而是每一步都有观察和验证。

Agent 需要哪些工具

订单导出任务通常需要几类工具协作：

工具能力	在订单导出中的作用
文件读取	理解页面结构、接口封装、权限判断和测试风格
文件编辑	修改导出入口、服务代码、测试和文档
搜索	找到已有导出实现、CSV 工具、权限点和字段定义
命令执行	运行单元测试、类型检查、构建和文档构建
浏览器	验证按钮状态、下载流程、错误提示和响应式布局
Git	查看 diff、确认改动范围、保留可 review 的变更记录

工具越强，越需要清晰的规格和 Harness。否则 Agent 只是更快地制造不确定性。

计划不是装饰

Agent 在动手前应该形成短计划。对于订单导出，计划可以是：

1. 搜索订单列表、订单 API、权限点和已有 CSV 工具。
2. 确认筛选参数如何从页面传到接口。
3. 增加导出入口和请求方法，复用当前筛选条件。
4. 服务端按字段白名单生成 CSV，并处理空结果和超量。
5. 补充权限、字段白名单、空结果和失败状态测试。
6. 运行相关测试、构建和文档检查。

计划的价值在于暴露风险。如果第 4 步发现当前仓库没有服务端代码，Agent 就应该调整计划，而不是假装已经实现完整导出。

验证闭环

Agent 的完成汇报不能只写“已完成”。它应该拿出验证证据：

验证结果：
- npm run test -- order-export：通过
- npm run test -- order-list：通过
- npm run build：通过
- 手动检查：无权限用户看不到导出入口
- diff 检查：未修改权限体系和订单查询接口响应结构

剩余风险：
- 当前版本同步导出限制 1 万行，异步导出未实现
- 浏览器下载中断场景未做端到端覆盖

这类汇报让人类可以快速判断是否进入 review，而不是重新猜 Agent 做了什么。

根据失败继续修复

工具闭环最有价值的地方，是失败后能继续定位。比如测试失败：

Expected CSV header not to contain receiverPhone
Received: orderNo,payTime,status,amount,receiverPhone

好的 Agent 不应只把错误贴给用户，而应回到字段映射处检查白名单，删除敏感字段，补充测试，然后重新运行命令。

又比如构建失败：

Property 'exportOrders' does not exist on type OrderApi

Agent 应该检查 API 类型定义和导出方法是否同步，而不是绕过类型检查。

人类仍然负责什么

Agent 可以执行明确任务，但不能替代所有判断。订单导出中的这些问题仍应由人确认：

• 是否允许导出某个敏感字段。
• 超过 1 万行时是提示缩小范围，还是进入异步任务。
• CSV 是否满足财务对账要求。
• 是否需要新增审计日志或合规审批。
• 发布窗口和回滚策略是否可接受。

Agent 适合处理有明确规格和验证入口的部分，人类负责业务取舍、风险接受和跨团队协调。

常见风险

风险	表现	控制方式
改动过宽	为了导出顺手重构订单列表	用规格限制范围，diff review
验证不足	只跑单个 happy path	给出必须运行的测试和构建命令
忽略禁区	修改权限体系或生产配置	Harness 设置禁区和人工确认点
依赖漂移	为 CSV 新增不必要依赖	优先搜索项目已有工具
错误自信	测试未跑却声称完成	汇报必须包含命令结果

实践方式

个人项目可以从最小闭环开始：让 Agent 先搜索、再改小范围文件、最后至少运行一个测试或构建命令。团队项目则应把核心命令写进项目文档，把高风险操作列为需要确认的动作。

订单导出这类功能，适合要求 Agent 每次汇报三件事：改了哪些文件，跑了哪些验证，哪些风险没有覆盖。这样人类 review 才能聚焦在业务和架构判断上。

总结

工具与 Agent 工程把 AI 编程从“给建议”推进到“执行并验证”。它的关键不是让模型拥有更多权限，而是让每次行动都有输入、计划、工具结果、修复循环和可审查输出。

当订单导出的规格和上下文足够清楚，Agent 就可以承担大量机械执行工作。下一步需要 Harness，把这些行动放进更稳定的规则系统。

→ 下一步：Harness 工程