超越 Context Window：为何文件系统是 AI Agent 的终极记忆体

超越 Context Window：为何文件系统是 AI Agent 的终极记忆体

"AI 不会因为上下文太短而失败，它们失败是因为不知道如何管理遗忘。"

2025 年 12 月，Meta 以 20 亿美元收购 Agent 初创公司 Manus 的消息引爆了科技圈。除了惊人的估值，最让开发者好奇的是：Manus 到底解决了什么核心难题？答案可能比大多数人想象的要朴素得多------上下文工程（Context Engineering）。

如果你用过 AutoGPT 或早期的 Agent 框架，你一定经历过这种绝望：Agent 充满激情地出发，执行了 10 步之后，突然开始在一个死循环里打转，或者干脆忘记了最初是要"写一个贪吃蛇游戏"，转而去研究"如何安装 Python"。

这就是 Agent 的"金鱼效应"。

今天，我们将深入拆解 Claude Code 中的 Planning with Files 技能。这不仅是一个工具，更是一套源自 Manus 的工程哲学。它告诉我们：解决上下文限制的最好方法，不是扩大窗口，而是把记忆写进磁盘。

一、为什么 RAG 救不了 Agent？

在 LLM 时代，我们习惯于用 RAG（检索增强生成）来解决知识不足的问题。把文档切片、存入向量数据库、检索 Top-K。但在 Agent 的长程任务中，RAG 往往失效了。

为什么？因为 Agent 需要的不是"知识片段"，而是"状态全景"。

当一个 Agent 正在重构 50 个文件中的 API 调用时，它需要的不是"API 的文档定义"（静态知识），而是"我已经改了哪 20 个？剩下哪 30 个？上一步报错的文件是谁？"（动态状态）。

向量检索是模糊的、碎片化的；而文件系统是精确的、结构化的。

Planning with Files 的核心理念就是：将文件系统作为 Agent 的外部显式记忆（External Explicit Memory）。

相比单纯扩展上下文窗口，文件系统有三个不可替代的优势：

1. 容量无限：磁盘存储远超任何上下文窗口，只在需要时加载相关部分
2. 压缩可逆：上下文中的信息经模型压缩后难以恢复，文件中的原始文本可精确读取
3. 跨任务复用：同一份笔记可以在多个相关任务中持续发挥作用

二、"三驾马车"模式：给 Agent 装上大脑结构

这套技能强制 Agent 在执行复杂任务时，维护三个特定的 Markdown 文件。这听起来像是增加了繁琐的手续，实则是构建了 Agent 的思维骨架。

1. task_plan.md ------ 前额叶（执行控制）

这是整个系统的指挥中心。它不仅仅是一个 Todo List，它是 Agent 的注意力锚点。

在 LLM 中存在著名的 "Lost in the Middle" 现象：当上下文超过 30k tokens 时，模型往往会忽略中间的信息，只记得开头和结尾。

task_plan.md 的妙处在于，Agent 被强制要求在每次关键决策前重新读取这个文件。这就相当于把"当前目标"和"进度状态"强行刷到了上下文的最末端（Recency Bias），让模型瞬间找回注意力焦点。

一个标准的 task_plan.md 包含：

• Goal: 永恒的北极星指标
• Phases: 状态机的流转节点
• Key Questions: 动态更新的知识缺口
• Decisions Made: 架构决策的快照（防止反复横跳）
• Errors Encountered : 这一点至关重要------显式记录错误。普通 Agent 遇到报错会默默重试直到崩溃；而高级 Agent 会把错误写下来，分析原因，避免重蹈覆辙

2. notes.md ------ 海马体（长期记忆）

这是 Agent 的草稿纸和知识库。

在传统的 ReAct 循环中，观察结果（Observation）往往转瞬即逝。如果 Agent 查了 5 个 API 文档，这 5 次搜索结果会迅速占满上下文。

通过 notes.md，Agent 可以将 Research 阶段的成果压缩并持久化：

• "我查了 Stripe 的 API，关于退款的限制是..." -> 写入 notes.md
• 下次需要时，只需读取 notes.md，而不需要重新搜索或回翻几千 tokens 的对话历史

3. Deliverables ------ 肌肉记忆（产出物）

将最终产出（代码、文档、报告）与过程文件分离。这保持了工作区的整洁，也让 Agent 明确"我在思考"（Plan/Notes）和"我在产出"（Deliverables）的界限。

三、实战演示：重构一个遗留系统

让我们通过一个真实的场景，看看这套系统是如何运作的。

任务：将一个基于 Flask 的老旧后端重构为 FastAPI，涉及 12 个 Endpoints。

阶段 1：初始化 (The Setup)

Agent 不会直接开始写代码。它首先创建 task_plan.md：

# Task Plan: Flask to FastAPI Migration

## Goal
Migrate all 12 endpoints from Flask to FastAPI preserving business logic.

## Phases
- [x] Phase 1: Analysis & Dependency Mapping
- [ ] Phase 2: Core Middleware & Auth Migration
- [ ] Phase 3: Endpoint Migration (Batch 1: Users)
- [ ] Phase 4: Endpoint Migration (Batch 2: Products)
- [ ] Phase 5: Verification

阶段 2：研究与积累 (Research Loop)

Agent 扫描代码库，发现老的鉴权逻辑很复杂。它不会把所有代码都塞进上下文，而是将分析结果写入 notes.md：

# Notes

## Auth Logic Analysis
- Uses `flask_login` currently.
- Dependency: `User` model in `models.py`.
- **Decision**: Port to `FastAPI` dependency injection system using `OAuth2PasswordBearer`.

阶段 3：决策与记录 (Decision Making)

在迁移过程中，Agent 发现了一个循环依赖问题。

普通 Agent 可能会尝试修复 -> 失败 -> 再尝试 -> 再失败，直到耗尽 Token。

Planning-with-Files Agent 会这样做：

1. 捕获错误 ：将 ImportError 写入 task_plan.md 的 Errors Encountered 区域
2. 分析策略：读取 Plan，看到这个错误已经出现过一次
3. 调整决策 ：在 Decisions Made 中记录："由于循环依赖，决定将 DTO 模型拆分到单独的 schemas.py 文件"
4. 执行：执行拆分

阶段 4：状态机流转 (State Transition)

每完成一批迁移，Agent 就会在 task_plan.md 中打钩。

这不仅仅是为了给人类看，更是为了告诉未来的自己："这一步已经稳了，不要再回头怀疑这部分代码。"

四、适用边界：什么时候该用，什么时候别用

任何工具都有它的适用边界。Planning with Files 不是银弹。

适合使用的场景

• 多阶段复杂任务：需要 3 个以上阶段、跨越不同领域
• 研究密集型任务：需要收集大量外部信息并综合
• 长时间跨度任务：可能中断后恢复，需要重建上下文
• 需要回溯决策的任务：架构决策需要被记录和审查

不适合使用的场景

• 简单查询任务：单次工具调用即可完成，无需额外开销
• 快速探索性任务：过度结构化会阻碍灵活性
• 实时性要求高的任务：文件 I/O 延迟在毫秒级敏感系统中可能成为瓶颈

与 TodoWrite 的关系

Planning with Files 并非要取代 TodoWrite。TodoWrite 更适合轻量级任务追踪，3 文件模式则针对持久化、知识积累、复杂协调进行了优化。选择取决于任务复杂度------简单任务用 Todo，复杂任务用 Files。

五、为什么这改变了游戏规则？

Planning with Files 实际上实现了一个慢思考（System 2） 循环。

• LLM 的直觉是 System 1：快速、直接、容易出错
• 文件系统强化的循环是 System 2：规划、记录、反思、修正

这套机制最大的价值，在于它赋予了 Agent "时间感"。

普通的 Agent 生活在"永远的现在"（Eternal Now），只有当前的上下文。

拥有文件系统的 Agent 拥有了"过去"（Decisions/Errors）和"未来"（Phases）。

六、实践建议：从模式到习惯

渐进式采用

首次接触？从单一文件 task_plan.md 开始，熟悉后再引入 notes.md 和交付物文件。

模板定制

默认模板是通用起点，但应根据需求定制。例如增加"风险项"部分记录潜在风险，或增加"依赖项"部分追踪外部依赖。

与版本控制集成

task_plan.md 和 notes.md 本身也是文本文件，可以纳入 Git。这为任务级别的回滚和历史追踪提供了可能------当一个决策路径被证明不可行时，可以快速恢复到之前的状态。

结语

技术圈常说："Talk is cheap, show me the code."

但在 Agent 开发中，我要说："Code is ephemeral, show me the plan."

如果你正在构建或使用 AI Agent，试着强迫它（或者强迫你自己）使用这套 3 文件模式。你会发现，原本不可控的随机过程，突然变成了可预测的工程流水线。

这就是 20 亿美元背后的秘密：让 AI 学会像工程师一样，拿笔记录，而不是像赌徒一样，凭记忆梭哈。

---

本文的核心方法论来源于 Manus 团队的官方博客《Context Engineering for AI Agents: Lessons from Building Manus》。