从一个任务理解 Agent

把“这里不对齐，帮我改一下”交给 AI，它可能给出一段 CSS，也可能真正打开项目、定位样式、修改文件并检查页面。本手册讨论的是后一种工作方式：软件工程师怎样使用能执行任务的 AI，并判断结果是否值得接受。

你需要能看懂基本代码、运行项目命令、检查 Git diff。暂时不需要学习模型训练，也不需要先搭一个多 Agent 系统。

同一个问题，两种交付

以本站出现过的“Header 与正文左边缘不一致”为例：

右栏多出来的工作，需要文件读取、命令执行、浏览器等工具。模型可以提出工具调用；宿主程序检查权限、执行调用，再把结果交回模型。模型本身并不会因为说出“已修改”就让文件发生变化。

一个 Agent 最小需要什么

在本文的用法里，Agent 是一个能根据工具返回结果继续决定下一步的系统。典型过程如下：

用户：修复全站容器不对齐，保持现有风格。
模型：先找容器定义。
工具返回：Header 使用 site-frame，正文使用 page-shell。
模型：继续找这两个类的宽度规则。
工具返回：对应 CSS，以及可能覆盖它们的局部规则。
模型：提出修改，调用编辑工具。
工具返回：文件修改成功。
模型：检查页面；若仍不对齐，继续调查；否则汇报证据。

这是一条教学示意轨迹，不是本站某次会话的逐字日志。

理解四个词就够开始：

• 模型：根据当前输入生成文字或工具调用，例如判断下一步应该查什么。
• 上下文：模型这一次实际能看到的材料，包括任务、规则、文件片段和工具结果。
• 工具：读取或改变外部状态的接口，例如搜索文件、执行测试。
• 运行环境（Harness）：连接模型与工具、管理状态、权限和停止条件的外围程序。

工具返回“测试失败”，只是提供了新信息，不保证模型会正确修复。你仍需要检查它是否读懂失败、是否改变了原本的验收要求。

不是什么任务都需要 Agent

如果要把一组确定格式的数据排序，一段脚本通常更直接；如果要解释一个概念，一次问答也可能足够。只有当下一步取决于调查结果时，动态选择工具才更有价值。

Anthropic 对 workflow 与 agent 的区分也采用这个角度：前者按预先规定的路径编排，后者更多由模型决定过程。这里讨论的是设计差异，不是产品等级。

对“修复不对齐”，你很难预先断言原因一定在 Header：也可能是正文的二次限宽、滚动条或某个路由特例。先查证据再选动作，比要求模型照着猜测改更合适。

这本手册怎样读

按顺序读，可以完成五件事：

想先动手，读完成第一个小任务，再读验证与评审。已经用过 coding agent，可以直接看全站对齐案例。

记忆、Skill、评估和蒸馏各自解决不同问题，后文会给独立例子。蒸馏属于模型训练，不是日常使用 Agent 的前置条件。

示例与资料的边界

本站代码案例会注明真实路径；为了便于解释而简化的代码、设想中的功能与演算数据会单独标注。示例中的“预期通过”不是已经执行的结果，也不要把本文写的路径原样套到其他仓库。

官方文档用于核对产品机制；本手册补充的是如何选材料、做判断和检查产物。需要更深入的系统原理，可以继续读《深入理解 AI Agent》，不必先读完全书再开始一个小任务。