AI Agent 避坑指南：三个月实战踩坑与架构演进
> 本文整理自 YouTube 视频转录，作者分享了独立开发 AI 视频生成 Agent 三个月中经历的架构迭代与深层思考。
一、背景：一个真实的 AI Agent 项目
作者开发了一款自动生成讲解视频的 AI Agent（视频中的动画效果均由该 Agent 生成）。三个月间，历经多次架构推倒重来，深刻体会到"教科书方案"与"真实工程"之间的巨大鸿沟。
> 行业每天都在往前冲：context engineering → skill → harness engineering……
> 但你自己写的 Agent 却慢、笨、不稳定，不断跑偏。
> 每次看到新架构，总以为"这次能解决所有问题"，用上之后却发现事情没有变化，甚至更差。
二、第一版架构：Plan & Execute 三层结构
2.1 初始设计
采用业界流行的Plan & Execute架构，思路直接：
【第一版架构】 ┌─────────────────────────────┐ │ Main Agent │ │ （负责编排 / Orchestration）│ └──────────┬──────────────────┘ │ 分发任务 ┌──────┴──────┐ ▼ ▼ ┌────────┐ ┌────────┐ │ Design │ │ Coding │ │Sub-Agent│ │Sub-Agent│ └────────┘ └────────┘流程说明：
- 用户提交任务
- Main Agent 进行整体规划（Orchestration Layer）
- 根据任务类型，将子任务分发给 Design Sub-Agent 或 Coding Sub-Agent
- Sub-Agent 执行具体工作并返回结果
- Main Agent 汇总输出
2.2 暴露的两个核心问题
| 问题 | 现象描述 |
|---|---|
| 小改动成本太高 | 改一行代码，仍需走完整流程：主 Agent → Sub-Agent → 执行，架构太重 |
| 主 Agent 越权 | 本应只负责编排，但它忍不住自己下场修改代码；提示词约束无效 |
> 💡根本误区：把"Plan & Execute"这种工作方式，错误翻译成了一种系统架构形态（必须有 Planner、必须有 Executor、必须切得工整）。
三、第一次架构重构：Skill 替代 Sub-Agent
3.1 Skill 是什么？
Skill = 提示词的动态注入：在 Agent 需要某种能力时，将对应的 Skill（规则/提示词）注入到当前上下文，而不是新起一个 Sub-Agent。
3.2 改造流程对比
【改造前：Sub-Agent 架构】 用户任务 │ ▼ Main Agent（规划） │ ├──→ Design Sub-Agent（独立上下文）──→ 设计结果 │ ▲ 需要额外传递上下文信息 └──→ Coding Sub-Agent（独立上下文）──→ 代码结果 问题：通信成本高，上下文传递复杂 【改造后：Skill 注入架构】 用户任务 │ ▼ Main Agent（单一上下文） │ 需要设计能力时 ├──→ 注入 Design Skill ──→ 继续执行 │ 需要编码能力时 └──→ 注入 Coding Skill ──→ 继续执行 优势：天然继承上下文，无通信成本3.3 改造效果
- ✅ 整体性能未下降，复杂任务反而有提升
- ✅ Token 开销变小
- ✅ 架构被"压平"，更简单、更顺滑
- ✅ 无需额外设计上下文传递机制
> 💡核心结论：原来的 Sub-Agent 从一开始就是冗余设计，Skill 只是暴露了这个问题，而不是"替代"了 Sub-Agent。
四、Long Running Task：记忆系统的加入
4.1 真实问题的升级
从"跑通小任务"到"连续生成100段代码且质量不降"，这是完全不同量级的挑战——类比双十一高并发与普通电商访问的区别。
4.2 加入 To-Do List 记忆系统
【Long Running Task 执行流程（加入 To-Do List）】 ┌──────────────────────────────────────────┐ │ Agent 执行循环 │ │ │ │ Step 1：读取 To-Do List，确认当前步骤 │ │ ↓ │ │ Step 2：执行当前步骤任务 │ │ ↓ │ │ Step 3：输出结果 │ │ ↓ │ │ Step 4：更新 To-Do List（标记已完成） │ │ ↓ │ │ Step 5：重申下一步任务（Restatement） │ │ ↓ │ │ 重复循环，直到所有步骤完成 │ └──────────────────────────────────────────┘4.3 仍然出现的三个问题
即使有了 To-Do List，依然出现：
| 问题 | 现象 | 根因 |
|---|---|---|
| 步骤被合并/跳过 | 后期把多段代码合并生成，像在"赶工" | 上下文焦虑 |
| 规则开始失效 | 前期认真遵守的 Skill 规则，后期当空气 | Skill 被上下文"埋掉" |
| 输出同质化 | 后期代码越来越像前面的复制改写 | 模型模仿前置上下文 |
五、核心机制：注意力分布与 Restatement
5.1 LLM 的注意力分布规律
【大语言模型上下文注意力分布示意】 注意力强度 ▲ │ 高 │ ████ ████ │ ████ System Prompt ████ 最新输出附近 │ ████ ████ 中 │ ░░░░░░░░░░░░░░░░░░░░░░░░ │ ░ 中间段（随长度增加注意力越弱）░ 低 │ ░░░░░░░░░░░░░░░░░░░░░░░░ └──────────────────────────────────────→ 开头 结尾 (System Prompt) (最新生成内容)关键结论：
- 注意力最强：System Prompt 开头+当前输出附近
- 注意力最弱：上下文中间段（越长越弱）
- 规则失效 ≠ 规则没写进去，而是被"埋掉"看不见了
5.2 Restatement 机制
Restatement = 把重要信息不断重新放回"注意力高地"
【Restatement 工作原理】 每次生成后： ┌─────────────────────────────────────┐ │ ...前99步的输出内容... │ ← 注意力弱区 │ │ │ [当前步骤重申]： │ │ - 现在做到第 X 步 │ ← 注意力强区 │ - 下一步是：XXX │ ← 注意力强区 │ - 关键规则提醒：[Skill核心规则] │ ← 注意力强区 └─────────────────────────────────────┘ ↓ 继续生成> 💡To-Do List 真正的价值不是"记录"，而是每步都在做 Restatement。
> 静静放在开头、后续不再提的 To-Do List，基本没有作用。
5.3 两类信息的分类管理
| 信息类型 | 特征 | 放置位置 | 原因 |
|---|---|---|---|
| 静态规则 | 全局适用、不变（代码风格、输出格式） | System Prompt | 始终可见，常驻注意力高地 |
| 动态信息 | 计划、To-Do List、阶段 Skill | 上下文尾端（不断追加） | 避免破坏 KV Cache；确保实时可见 |
5.4 KV Cache 与 System Prompt 修改的代价
【KV Cache 机制说明】 正常情况（只追加新内容）： [缓存✓] [缓存✓] [缓存✓] | [新增内容，只算新增部分] ↑ 成本低 修改了 System Prompt（改动前面内容）： [失效✗] [失效✗] [失效✗] [失效✗] 全部重新计算 ↑ 成本高，应避免频繁修改5.5 Restatement 内容的完整性
记忆系统不只需要 To-Do List，还需要：
【完整的 Restatement 内容结构】 每步执行后，重申内容包括： ├── To-Do List（当前进度 + 下一步） ├── 关键 Findings（本次执行的重要发现） ├── Plan（整体计划的关键约束） └── 阶段 Skill 核心规则（周期性重申） 作用： "告诉模型下一步是什么" + "告诉模型下一步怎么做"六、第二次架构重构：Sub-Agent 回归（上下文隔离）
6.1 新问题：不该看到的被看到了
前面的问题是"该看到的信息没被注意到"，现在的问题反转了：
- 模型会模仿已有代码的写法，输出越来越同质化
- 创意任务需要每段代码有独立思考，但共享上下文让模型"照抄前面"
> 这两个方向的问题，仅靠 Restatement 解决不了。
6.2 Sub-Agent 回归：上下文隔离
【第二次重构：精准上下文注入的 Sub-Agent】 Main Agent（持续运行） │ │ 需要生成第 N 段代码时 ▼ ┌──────────────────────────────────────────┐ │ Sub-Agent（新鲜上下文窗口） │ │ │ │ 注入内容（精准控制）： │ │ ✅ To-Do List（当前进度） │ │ ✅ Skill 关键规则（本次任务规则） │ │ ✅ Plan/Findings（必要背景） │ │ ❌ 前 N-1 段代码结果（屏蔽！） │ │ │ │ → 独立思考，输出第 N 段代码 │ └──────────────────────────────────────────┘6.3 新旧 Sub-Agent 的本质区别
| 对比维度 | 第一版 Sub-Agent | 重构后 Sub-Agent |
|---|---|---|
| 存在理由 | 架构层次分离（强迫症式） | 上下文隔离（必要的） |
| 去掉后效果 | 系统变得更轻更好 | 系统变得更差 |
| 核心价值 | 无（冗余） | 给局部任务提供干净的上下文 |
| 与 Restatement 关系 | 无关 | 结合使用：注入需要的，屏蔽不该有的 |
七、架构演进全貌
【AI Agent 架构演进路线】 第一版（Plan & Execute 三层） Main Agent ├── Design Sub-Agent └── Coding Sub-Agent 问题：重、越权、通信成本高 ↓ 第一次重构（Skill 注入，压平架构） Main Agent（单一上下文） ├── 注入 Design Skill └── 注入 Coding Skill 解决：通信成本，架构简化 新问题：长任务不稳定（100步后失控） ↓ 加入记忆系统（To-Do List + Restatement） Main Agent ├── To-Do List（步骤追踪） ├── Findings（执行发现） ├── Plan（全局计划） └── 周期性 Skill 规则重申 解决：规则失效、上下文焦虑 新问题：输出同质化（创意丧失） ↓ 第二次重构（Sub-Agent 回归，上下文隔离） Main Agent（持续上下文） └── Sub-Agent（按需调用，精准注入上下文） ✅ 注入：进度 + 规则 + 背景 ❌ 屏蔽：前序代码结果 解决：输出同质化，创意保留八、核心方法论总结
8.1 三大核心认知
Plan & Execute 是工作方式，不是架构形态
不要把它翻译成"必须有 Planner 和 Executor 两个组件"注意力管理 > 信息堆砌
重要的信息放到模型注意力能看到的地方（开头 + 结尾），而不是塞更多内容架构设计要解决真实问题
Sub-Agent 的存在要有必要性（上下文隔离），而不是为了看起来"高级"
8.2 工程实践清单
AI Agent 工程实践 Checklist 上下文管理： □ 静态全局规则 → System Prompt □ 动态信息（计划/进度/阶段规则）→ 追加到上下文尾端 □ 避免频繁修改 System Prompt（KV Cache 代价） 记忆系统： □ To-Do List：每步执行后重申进度和下一步 □ Findings：记录执行过程中的重要发现 □ Plan：保留全局计划约束 □ 关键 Skill 规则：周期性重申，不仅告知"做什么"还告知"怎么做" Sub-Agent 使用原则： □ 需要上下文隔离时才用（不是为了架构好看） □ 精准控制注入内容：该有的要有，不该有的屏蔽 □ 与 Restatement 结合：注入重要状态信息 Skill 使用： □ 提示词动态注入，避免冗余 Sub-Agent □ 如需 Sub-Agent，与 Restatement 结合使用九、一句话提炼
>真实的 AI Agent 工程，不是把新名词用上就能解决问题，而是要搞清楚每个症状背后的根本原因，再针对性地设计机制去解决它。