AI Agent 避坑指南:三个月实战踩坑与架构演进-夜雨聆风

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 工程，不是把新名词用上就能解决问题，而是要搞清楚每个症状背后的根本原因，再针对性地设计机制去解决它。

————————————————

原文链接：https://blog.csdn.net/guolong1983811/article/details/160523991