AI Agent 应用指南（实战版）

一份产品无关的通用方法论：先学怎么想，再查用哪个，最后照着模板上手。

通用方法部分整理自开源指南《AI Agent 应用指南》；实战规则部分来自一线长期使用中真实踩过的坑。

---

导读 · 怎么用这份指南

这份指南分四块，建议按顺序读一次，之后当手册查：

四条最该先记住的话：

1. Agent = 模型 + 工具 + 上下文 + 规则，不是"更聪明的聊天框"。
2. 指令模糊 → 结果随机；验收缺失 → 它总是告诉你"完成"。
3. 验收的最低标准是可复现证据（E1），不采信自证。
4. 任何不可逆动作，人工确认。授权 ≠ 跳过门禁。

---

第一部分 · 怎么想

第一章 心智模型：Agent 到底是什么

1.1 一个公式

Agent = 大模型 + 工具 + 上下文 + 规则

它不是一个更聪明的聊天框，而是一个能读文件、执行命令、操作浏览器、调用 API、自己决定下一步的数字员工。这个区别是分水岭：聊天框只能给建议，Agent 能改你的东西。

1.2 四个关键概念

1.3 最重要的一条原则

把 Agent 当"有能力但需要明确指令的新员工"，而不是"什么都知道的神"。

由此直接推出两件事：指令必须明确，验收必须独立。

1.4 三条容易被忽略的真相

真相一：Agent 会失忆。

每一次新会话对它来说都是全新的开始。它不会"记得昨天"，除非你把记忆写成了文件。

所以：你的记忆必须是一堆文件，不是一个对话框。

• 每天一份日志（做了什么、结论、证据、下一步）
• 一份长期记忆（只放提炼过的结论，不放流水账）
• 一份"我在干什么"（交接单，随时可以换人接手）

一个真实教训：早期有整整一段时间的会话全部丢失，因为当时没有写日志文件。后来是把原始轨迹一点点刨回来才补上的。

而且——只写进每日日志是不够的，别的会话读不到。重要结论要当天写进长期记忆。

真相二：Agent 会"假成功"。

"完成"这个词，在 Agent 嘴里和在工程里，含义不一样。真实发生过的例子：

• 前端请求了一个根本不存在的接口，拿到错误页面，却因为状态码是 200 被记成"接口验证通过"。
• 限流错误（429）被当成"模型实测通过"。
• 报告写着"4 张图都生成并验证通过"，而当轮没有任何工具证据支撑这句话。

所以规则是：HTTP 200 不是成功，退出码 0 不是成功，"我检查过了"更不是成功。

成功必须有内容级证据。

真相三：Agent 救不了自己。

如果 Agent 跑在你的主程序进程内部，那么进程一死它就死了——它永远不可能自救，这是位置问题，不是能力问题。

所以：可靠的恢复机制必须在进程之外（系统级看门狗、计划任务、外部告警）。

---

第二章 类型与选型

2.1 按角色分

2.2 按能力面分

• 代码型：实现、重构、调试、部署
• 浏览器型：打开网页、点击、填表、截图、抓取
• 电脑操作型（Computer Use）：像人一样操作原生桌面应用
• 内容型：写作、翻译、总结、生成图文、做 PPT / 表格 / 文档
• 视觉 / 图像型：读图、设计、生成与编辑图片

2.3 主流产品七大族系

市面产品按「你让 agent 干什么」分七族：

两个关键协议值得记住：

• MCP：Agent 的 USB-C。把工具和数据源标准化，一次接入处处可用。
• A2A：Agent 之间的对话协议。不同厂商的 agent 互相发现、交接任务。

2.4 快速选型表

价格与版本会变，使用前以各厂商官网为准。

2.5 选型口诀

复杂靠强模型，批量靠低成本模型，验证永远换一个独立的视角。

---

第二部分 · 怎么干

第三章 协作：怎么让多个 Agent 一起干活

3.1 三种基本协作模式

3.2 通用分工表

3.3 多 Agent 协作的黄金规则

这五条与工具无关，是避免协作炸锅的硬规则：

① 每次只有一个写入者。 同一文件、同一时间，只允许一个 Agent 改；其他人只读，或写隔离的验证脚本。

多个 Agent 同时改同一个文件 = 互相覆盖 = 灾难。

② 共享一份交接单。 所有 Agent 开工前先读它；有进展就更新；切换前写清"已完成 / 当前步骤 / 下一步 / 证据"。

③ 实现 ≠ 验收。 让实现者自测可以，但最终验收必须由另一个视角（独立验证者或你本人）执行。

补充一条更硬的："多一个 Agent 看过"不等于独立验证。同一个体系内互检只能算互检。

④ 证据要可复现。 要求"退出码 + 输出 + 截图 + URL 响应"，而不是"看起来没问题"。

⑤ 破坏性动作需人工批准。 部署、外联、发布、删除数据，永远留给你确认。

两条实战补充：

⑥ 授权 ≠ 跳过门禁。 "我批准了"解除的是问不问，不是查不查。发送前该跑的去重、时间窗、幂等、前置条件校验，一条都不能省。

⑦ 规则要有单一数据源。 当你有多个 Agent、多份规则文件时，最大的风险是规则漂移——你以为改了，其实只改了一处。 做法：规则写在一个数据源目录，用脚本分发到每个 Agent 的规则文件，再用校验脚本查漂移，禁止手改生成物。

删掉一个 Agent 角色时，必须先做影响面普查。最容易漏掉的不是文档，而是代码里硬编码的路由——只改文档不改代码，队列仍会把活派给它。

3.4 交接单模板

# 任务交接单
状态：进行中
负责人：<Agent 名>
目标：<一句话>
验收标准：<可检查清单>
当前进度：<已完成 / 正在做>
下一步：<要做什么>
证据：<文件路径 / 命令输出 / 截图 / URL>
边界：<唯一写入者是谁、哪些文件不能动>

---

第四章 任务规划：D-I-C-E-R

4.1 万能五步

4.2 任务六要素

一个合格的任务描述必须包含：

"做好看一点"不是验收标准。"首屏 3 秒内出现标题 + 一个持续运动元素"才是。

4.3 分阶段推进（防翻车）

不要一次让 Agent 做完整页 / 整个系统。

第一轮：只做「骨架 + 最有代表性的一个模块」
   ↓
你 / 独立验证者核验是否真的对
   ↓
通过后再扩展其余部分
   ↓
全部完成后做全量验收（桌面 + 移动 + 无障碍 + 安全）

4.4 一个能省下大量返工的动作

先要方案，不要直接动手。

让 Agent 先说它打算怎么做，你看完再决定开不开工。

反面案例：有任务因为缺少明确契约，Agent 进入了「读文件 → 分析 → 再读 → 再分析」的死循环，四十多分钟一个字都没写。

---

第五章 功能模块与组件清单

先弄清你的 Agent 开了哪些模块——很多默认是关闭的，或需要单独授权。

5.1 基础模块

5.2 感知与操作模块

给指令时明确指定用哪个模块（"打开浏览器"、"生成一张流程图"），比笼统说"帮我看看"有效得多。

5.3 Skill / 插件体系

Skill = 给 Agent 的"说明书 + 流程"，让它按标准做法执行特定任务（如"网页验收 Skill""写邮件 Skill"）。

熟练标志：知道怎么列出 / 启用技能；需要标准流程时主动调用对应技能，而不是让它自由发挥；技能可随项目沉淀复用。

5.4 实战补充：模块默认是关的

装完不等于能用。 真实踩过的坑：

• 某个客户端的插件工具一个都不启动，根因是它的功能开关默认关闭，全新安装不会自动打开。
• 某个本地插件装好了却没生效，用户连说两次"没变"——最后发现是入口被插在可视区下方 35 像素，根本没滚到。

两条规则：① 装完必须验证工具真能被调用；② 听到"没变"时，先确认有没有看对地方，再怀疑实现。

---

第六章 Prompt 手册

6.1 结构化 Prompt 骨架

角色：你现在是 <角色>（资深前端工程师 / 独立 QA / 研究助理…）
背景：<相关文件、代码位置、已有调研结果>
任务：<要做什么，一句到三句>
范围：<只改 A/B/C，不改 D>
约束：<语言、编码、禁止事项、性能要求>
验收标准：<可检查清单>
输出：<DONE + 证据 / diff / 报告，格式是什么>

6.2 通用"约束性任务"模板

只修改以下文件：<列表>。不要读取或改动无关内容。
所有文件使用 <编码规范>，不要出现乱码。
完成后先自检：<跑哪些命令>，保证 <console 0 报错 / 无 404 / 测试通过>。
完成时回复 DONE，并附证据清单：命令输出、退出码、截图路径、URL。

6.3 实现类任务模板

请在 <工作区> 实现 <功能>。
背景：<指向现有代码位置与调用关系>。
做法：先读相关文件再动手；用 <语言/框架>；复用现有风格。
边界：不改 <模块/文件>。
验收：<给出可执行验证步骤>。
完成后回复 DONE + 改动文件清单 + 自测证据。

6.4 验证 / 验收类任务模板（给独立验证者）

请独立验收 <改动/页面>，不要采信实现者的口头结论。
执行：桌面 + 移动端截图对比、交互前后帧差、无障碍 / reduced-motion、
      console 错误与 404、真实资源加载、键盘焦点可达。
输出：每一项 PASS/FAIL + 可复现证据；不通过就列出复现步骤退回。

6.5 调研类任务模板（防幻觉）

调研 <主题>。要求：区分「已核实事实 / 推断 / 观点」三档，
每个数字追溯原始来源并给链接；找不到就明说"未核实"，
禁止把记忆或营销文案当结论。输出：要点 + 来源列表。

6.6 写法进阶技巧

6.7 反模式对照表

---

第七章 CLI 通用语义表

不同产品命令名略有差异，但语义高度一致。把这张表映射到任何工具上，都能快速上手。

拿到任何新 CLI 的第一步：跑 agent --help 和 agent exec --help，把上面这张表映射到它的真实命令名上。

---

第三部分 · 怎么验

第八章 质量与验收：怎么判断"真的做完了"

8.1 证据分级（自证无效）

验收最低要求 = E1。

三条硬规矩：

1. 不能拿 E3 冒充 E1。 把"谁说的"和"什么证据"分开记录。
2. 上下文压缩或换会话之后，旧的"已验证"作废，必须先复核再报告。
3. 多一个 Agent 看过 ≠ 独立验证。

8.2 通用验收检查单

• [ ] 构建 / 测试通过（贴真实退出码与输出）
• [ ] 功能按验收标准逐条核对（不是"看起来差不多"）
• [ ] 边界与回归：异常输入、空状态、断网 / 降级
• [ ] 移动端 / 小屏表现（如适用）
• [ ] 无障碍：键盘可达、reduced-motion
• [ ] console 0 错误、0 资源 404
• [ ] 真实内容已替换（无示例文字 / 占位图 / 假数据）
• [ ] 安全扫描（密钥泄露、注入、依赖漏洞）通过

8.3 先验证量具，再相信结论

这是全篇最省钱的一条。

真实发生过的例子：

「问 DOM，而不是问屏幕」；「先证明量具本身对，再去相信它给出的结论」。

这一条还有一个更狠的推论：让失败自己说出原因。

有一类事故的根因不是"某个 bug"，而是代理把上游的错误静默吞掉了——上游的 400 / 503 / 连接重置，被统一抹成"HTTP 200 + 空数据"。结果是：连续九次失败，看起来一模一样，被当成同一个"网络抖动"，实际原因是好几种。

「9 次失败看起来一样」不等于「9 次失败原因一样」。

把上游错误抹平成一句不可诊断的报错，才是真正被浪费的成本。

修复方向不是"再试一次"，而是让失败自己说出原因——状态码、错误体、终止事件，三样都不许吞。

8.4 先证明它会失败，再相信它会通过

新增的检查项如果从来没红过，你不知道它是"真的没问题"，还是"根本不会报警"。

做法：新加的每一条检查，都要先用一个故意做坏的样本证明它确实会触发，然后才允许它给通过。

一个永远亮绿灯的警报器，和一盏坏掉的灯没有区别。

8.5 安全门禁（正式交付前）

让独立扫描工具或验证 Agent 检查：密钥是否泄露、是否存在注入 / XSS、危险 API、依赖漏洞。

高危项必须修复并复扫通过后才能交付；中低危记录处置决定。

三条容易踩的坑：

1. 工具自带的默认模型可能是最贵的一档。 实测同一份请求的预扣费能差 25 倍——照抄默认 = 持续烧钱。
2. 报告文件存在 ≠ 扫描通过。 必须有退出码与复扫结论。
3. 最危险的失效是"把发现读成 0 然后输出 PASS"。 曾有一次扫描实际跑出 3 条发现（含 1 条严重级），但脚本读错了产物字段（把对象当成了字符串），统计成 0 条 → 结论 PASS。

任何一次 PASS，都必须能被独立复算出来。

门禁结论的退出码语义必须严格区分：

报"门禁失败"时，必须区分四件事：余额不足 / 工具故障 / 真实问题 / 通过。

前两者绝不可互相冒充，也绝不可冒充"通过"。

---

第九章 协作中的安全边界

① 凭据永不进 prompt / 文件 / 日志。 API key、token 只在环境变量或受管凭据里，并明示 Agent 禁止打印。

真实教训：脚本里只对输出做了遮蔽，没有对回显的命令行做遮蔽，结果 key 被完整明文打进了会话记录。

遮蔽必须先作用于「即将回显 / 落盘的整行」。

② 最小权限。 能用只读就不用可写；能用 workspace-write 就不用全盘。

③ 不可逆动作 = 人工闸门。 部署、发布、外联、删数据，必须由你确认后再执行，并在记录里留痕。

而且：授权过一次 ≠ 以后都授权。 换发件身份、换渠道、超出既定报价的谈判，都要重新确认。

④ 演练必须真的演练。 真实事故：为验证流程而在演练目录跑投递脚本，忘记加"只探测不发送"的参数，而发送脚本里的根目录是写死的真实目录 → 真的发出了 2 封信。

做法：演练环境的发送入口硬锁探测模式，不要依赖操作者记得加参数。

⑤ 外链与媒体要核源。 涉及外部图片 / 视频 / 字体 / 第三方库时，明确来源与授权。

⑥ AI 生成 ≠ 事实。 产品图、人物、建筑等客户可见内容必须真实或已授权。AI 图冒充真实产品是一票否决。

---

第四部分 · 怎么不重蹈覆辙

第十章 常见失败模式速查

按「现象 → 根因 → 规则」组织。每一条都是真实发生过的。

从这张表里能提炼出三条通则：

1. 写下来的规则会被忘记，自动跑的门禁不会。 有三类错误各自独立复发过至少 3 次（编码问题、假成功、批量脚本破坏既有成果）——说明光写下来不够，必须落到门禁。
2. 每一次翻车，都要变成一条不会再犯的规则。 这是复利最高的动作。
3. 先怀疑量具，再怀疑世界。

---

第十一章 从入门到熟练：练习路线

阶段 1 · 会对话

• 跑通交互会话与一次非交互执行。
• 学会把文件路径、截图、链接喂给它。
• 让它做完就贴证据，养成"看证据"的习惯。

阶段 2 · 会派活

• 用六要素写一个任务，交出去，再独立验收。
• 体验"先做最小一版 → 核验 → 扩展"的节奏，感受返工率下降。
• 开始写每日日志。

阶段 3 · 会协作

• 搭一个小型流水线：你当协调者，派实现者 + 验证者两个角色，用交接单接力。
• 故意让验证者独立挑实现者的毛病，训练"不采信自证"。
• 建立证据分级习惯：每次汇报都问"这是 E 几？"

阶段 4 · 会用全模块

• 逐个点亮浏览器控制、电脑操作、可视化、图像、Office/PDF 模块，各做一次小任务。
• 建立自己的模板库：任务模板、验收模板、调研模板，存成可复用的 Skill / 规则文件。
• 开始做成本路由：按任务难度分配模型，记录每次花费。

阶段 5 · 会建工厂（可选，进阶）

• 把重复流程固化成脚本：把"每次都解释一遍"变成"跑一条命令"。
• 建立不变量检查套件：一次跑完，给一条判决。
• 给每个流程配一个"会失败的证明"：新检查先用坏样本验证会触发。

---

附录 A · 成本与模型路由

四条实践：

1. 先看价目表再选模型。 同一服务商的模型价差可达 25 倍。
2. 先跑一个几十秒的预检，再决定要不要跑一整轮。
3. 按请求体大小计费的服务，大请求更容易因余额不足而失败——表现为"刚才能用，现在又不行"。这时先怀疑余额，别怀疑代码。
4. 记录每次花费。 没有这张表，你会在不知不觉中烧掉很多钱。

---

附录 B · 四条金句（贴在手边）

① 指令模糊 → 结果随机；验收缺失 → 它总是告诉你"完成"。

② 你怎么证明？——给不出命令输出、退出码、截图或哈希，那就是没完成。

③ 先证明量具本身对，再去相信它给出的结论。

④ 先证明它会失败，再相信它会通过。

---

最后一句

用明白 AI Agent，不是学会问它更多问题。

是学会把一件事说清楚、把结果验明白、把经验存下来。

这三件事，Agent 替不了你。

但它们一旦建立起来，Agent 就能替你干几乎所有的活。