告别聊天记录：AI 编程的“三级上下文”架构演进

在深度使用 OpenCode 一段时间后，我发现单纯的修修补补已无法满足需求。

我意识到了一个根本性的架构谬误：对于 AI 编程而言，线性的聊天记录（Chat History）不仅不是助力，反而是累赘。

痛点：流（Stream）无法承载状态（State）

目前的交互模式习惯将 System Prompt + User History 一股脑喂给模型。随着对话轮数增加，弊端暴露无遗：

• 信噪比极低：历史中充斥着试错、报错和已修正的代码。AI 必须耗费巨大的注意力（Attention）在噪音中寻找信号。
• 上下文污染：旧的错误思路会残留在 Context 中，导致 AI 反复“鬼打墙”。
• Token 滥用：为了修改一个函数，可能被迫携带了前十轮无关的闲聊。

对话是流（Stream），但编程本质上维护的是状态（State）。

试图用线性的、易逝的对话流来维护复杂的、结构化的项目状态，可能是当前 AI 编程工具最大的架构瓶颈。

破局：Manager-Worker 双层架构

为了解决这个问题，我在试验一种新架构。其核心是将 AI 的职能解耦为 Manager Agent（大脑/项目经理） 和 Execution Agent（手/工程师），并彻底摒弃“聊天记录”作为核心上下文的地位。

在这个架构中，上下文不再是一锅粥，而是被严格分层管理的。

架构数据流向示意

Manager Agent (大脑)
├── 维护: Level 1 项目全局状态 (持久化)
└── 动作: 蒸馏 (Distill)
       │
       ▼
Execution Agent (手)
├── 接收: Level 2 任务上下文 (最小完备集)
├── 运行: Level 3 执行上下文 (动态生长)
│      └── 动作: 按需查询 (LSP/File Read)
└── 产出: 代码变更 -> 同步回 Manager

核心创新：三级上下文体系

我们将上下文从宏观到微观划分为三个层级，每一层都有明确的生命周期和职责：

Level 1: 项目上下文 (Project Context)

• 持有者：Manager Agent
• 内容：项目的全局拓扑。包括文件树结构、依赖关系图谱、已确认的需求列表、技术栈规范等。
• 特性：持久化、高抽象。 它像一张地图，不包含具体代码细节，但知道“什么东西在哪里”。

Level 2: 任务上下文 (Task Context)

• 持有者：由 Manager 生成，传递给 Execution Agent
• 内容：执行当前具体任务所需的 “最小完备集”。
  • Bad Case: 把整个 src 文件夹扔给 AI。
  • Good Case: “修改 auth.ts 中的 login 函数，仅需参考 user.ts 中的 User 接口定义。”
• 特性：一次性、高提纯。 这是经过 Manager “蒸馏”后的上下文，去除了所有无关噪音。

Level 3: 执行上下文 (Execution Context)

• 持有者：Execution Agent (Runtime)
• 内容：Worker 在干活时的“工作台”。它包含 Task Context，但更重要的是，它包含 Worker 在编写代码过程中动态查询到的补充细节。
• 特性：动态生长、按需加载，用后即焚。 例如 Worker 发现缺少类型定义时，可以通过 LSP 工具主动读取定义，而不是依赖 Manager 的猜测。

动态协作流程：从“填鸭式”到“按需索取”

传统的 RAG 是“我预判你需要这些，全塞给你”。而三级上下文架构支持 Lazy Loading（懒加载）。

场景举例：

当 Manager 派发一个“修复登录 Bug”的任务时，Execution Agent 得到的初始环境是纯净的。

1. Worker 阅读 login 函数，发现调用了未知的 validate 方法。
2. Worker 主动发起 Tool Call，读取 utils.ts 中 validate 的定义。
3. Worker 修复代码，运行测试。
4. 任务结束，Execution Context 销毁，仅将最终代码变更同步回项目状态。

核心优势

1. 极大的降低幻觉
   Execution Agent 永远在一个极其纯净的“真空环境”中工作。它看不到用户之前的吐槽，也看不到之前的错误尝试。它只看到明确的指令和精准的代码片段。输入越纯净，输出越确定。

2. 无限的上下文窗口
   通过 Level 3 的动态查询机制，Worker 不需要一开始就加载整个项目，它可以在需要时随时向 Manager 或文件系统“伸手要”。这使得处理数万个文件的超大型项目成为可能，打破了 Context Window 的物理限制。

3. 自我纠错与状态机
   Manager Agent 维护的是状态（State），而不是历史（History）。当 Worker 完成任务，Manager 会更新项目状态；如果任务失败，Manager 会基于当前状态生成新的修复任务。这是一个不断收敛的有限状态机（FSM），而不是无限发散的对话流。

对比：从静态的 CLAUDE.md 到动态的 Agent State

为了更好地理解这一架构的演进，我们可以参考目前流行的 CLAUDE.md 实践。

在现有的最佳实践中，开发者会在项目根目录维护一个 CLAUDE.md 文件，用来记录架构规范、常用命令和代码风格。这实际上是 Level 1（项目上下文）的雏形，但它存在两个致命的局限性：

1. 维护成本
   CLAUDE.md 依赖人类开发者手动更新。一旦代码变更而文档未同步，过期的上下文反而会成为误导 AI 的“毒药”。而在三级上下文架构中，Manager Agent 负责实时更新项目状态，保证“地图”永远与“地形”一致。
2. 粒度问题
   CLAUDE.md 是一个“扁平”的文件。无论任务大小，AI 每次都要被迫读取整个文件。而在我们的架构中，Manager 会从全局状态中动态裁剪出 Level 2（任务上下文）。
   • CLAUDE.md 模式：“这是项目的所有规则，你自己看着办。”
   • 三级上下文模式：“针对此任务，你必须遵守这几条规则。”

简而言之，CLAUDE.md 是静态的、由人维护的只读快照；而三级上下文架构则是动态的、由 Agent 维护的活体状态。我们正在将“写文档给 AI 看”的负担，转变为“让 AI 自己维护记忆”的能力。

结语

随着 AI 编程的深度使用，我越来越意识到：上下文的构建是一门艺术。

人类的大脑习惯于线性的逻辑推演，但 AI 不同，它依赖的是基于海量知识的泛化联想。

因此，未来的 AI 编程工具，其核心竞争力不再仅仅是模型本身，而是如何设计出高效的上下文体系——精准地“触发”并“引导” AI 的泛化能力，使其产出符合人类预期的结果。