本文由 源码七号站 原创首发，转载请注明出处。如果你正在寻找提升 AI Agent 开发效率的方法，这篇文章将为你打开新世界的大门。
前言：为什么这个项目值得你花时间研究
在 AI Agent 开发领域，有一个长期困扰开发者的核心问题：大模型聊久了就"忘事"。
你是否遇到过这样的情况：和 AI 对话了几十轮之后，它突然忘记了最初的任务目标？或者在执行复杂任务时，AI 的注意力逐渐漂移，最终输出的结果和你的预期相去甚远？
这不是 AI 的"智商问题"，而是上下文工程没有做好。
今天，源码七号站 要为大家深度解析一个在开源社区引起广泛关注的项目——Planning-with-Files。这个项目巧妙地复刻了 Manus 的上下文工程方法论，通过"文件即记忆"的设计理念，从根本上解决了 AI Agent 的上下文丢失问题。
在接下来的内容中，我会从原理到实操，手把手带你掌握这套方法论。无论你是 AI 开发的老手还是刚入门的新人，相信都能从中获得启发。
第一章：理解问题的本质——为什么传统对话模式会失效
1.1 对话历史的天然缺陷
在深入了解 Planning-with-Files 之前，我们需要先理解一个根本性的问题：为什么传统的对话模式无法支撑复杂的 AI Agent 任务？
传统的 AI 对话模式是这样工作的：每一轮对话都会被追加到对话历史中，AI 在生成回复时会参考这些历史记录。这种模式对于简单的问答场景完全够用，但当任务变得复杂时，问题就开始浮现。
对话历史的三大硬伤：
第一，线性结构的局限性。 对话历史是严格按时间顺序排列的线性结构。想象一下，如果你在进行一个需要多次迭代的开发任务，中间经历了多次方案调整、错误修正，这些信息全部混杂在一起。AI 要从中提取有效信息，就像在一堆杂乱的纸条中找关键内容一样困难。
第二，噪声信息的累积。 在实际工作中，我们会产生大量的"试错信息"——比如某个方案试了不行、某段代码有 bug 需要修改。这些信息虽然在当时有意义，但对于后续任务来说就是纯粹的噪声。传统对话模式会保留所有这些噪声，导致 AI 的注意力被严重分散。
第三，状态更新的混乱。 当任务涉及多个步骤时，每个步骤的状态（待处理、进行中、已完成）都在不断变化。对话历史中会充斥着各种状态的更新信息，AI 需要从头到尾梳理才能知道当前的真实状态。这不仅效率低下，还容易出错。
1.2 上下文窗口的物理限制
除了信息质量的问题，还有一个更现实的限制：上下文窗口的容量是有限的。
即使是最先进的大模型，其上下文窗口也有上限。当对话历史超过这个上限时，早期的内容就会被截断。这意味着什么？意味着 AI 可能会"忘记"任务最初的目标和背景。
更糟糕的是，上下文越长，AI 的注意力就越分散。研究表明，大模型在处理长上下文时，对中间部分内容的关注度会显著下降（这就是著名的"中间丢失"问题）。
1.3 问题的症结：对话流不适合当"大脑"
综合以上分析，我们可以得出一个核心结论：
对话流（Chat）只适合短暂的指令交互，而不适合作为 AI Agent 的长期记忆载体。
这就好比人类的工作方式：我们不会把所有的工作内容都记在脑子里，而是会使用笔记、文档、待办清单等外部工具来辅助记忆和管理任务。AI Agent 也需要类似的"外部大脑"。
这正是 Planning-with-Files 要解决的核心问题。
第二章：Manus 的上下文工程方法论——来自实战的智慧
在详细介绍 Planning-with-Files 之前，我们需要先了解它的理论基础——Manus 团队总结的上下文工程原则。这套方法论来自于大量的实战经验，是 AI Agent 开发领域的重要参考。
2.1 核心原则一：文件即单一真理来源
什么是"单一真理来源"（Single Source of Truth）？
在软件工程中，这个概念指的是：系统中的每一项数据，都应该只在一个地方被定义和维护。所有需要使用这项数据的地方，都应该从这个唯一的来源获取。
将这个概念应用到 AI Agent 中，就是：
打破 AI 的记忆主要依赖对话历史的传统做法，转而信任文件。
为什么文件比对话历史更可靠？
- 文件是经过整理的：你可以随时更新文件内容，删除过时的信息，保持内容的准确性
- 文件代表"当前状态"：文件中的内容就是最新的、最准确的状态，不需要从历史中推导
- 文件结构化程度高：你可以使用标题、列表、分节等方式组织信息，便于 AI 快速定位关键内容
实际应用中的做法：
AI 每次行动前，应该主动读取相关的状态文件，而不是回溯几千行的聊天记录。这确保了 AI 永远基于当前最准确的状态行动，而不是被历史中的过时信息误导。
2.2 核心原则二：状态显式化（外部化记忆）
这个原则是对第一个原则的具体延伸：不仅要用文件存储信息，还要用文件显式地记录任务状态。
最典型的实现方式是维护一个 ToDo 文件，用类似下面的格式记录任务进度：
## 任务进度
- [x] 步骤1：需求分析
- [x] 步骤2：技术选型
- [ ] 步骤3：核心功能开发（进行中）
- [ ] 步骤4：测试与优化
- [ ] 步骤5：文档编写这种设计的精妙之处在于：它实现了完美的可恢复性。
想象一个场景：你正在用 AI 进行一个复杂的开发任务，做到一半的时候电脑突然死机了。如果使用传统的对话模式，你可能需要重新描述任务背景，告诉 AI 之前做了什么，现在做到哪里了。
但如果使用了状态显式化的方法，AI 重新启动后只需要读取 ToDo 文件，立刻就能知道：
- 整体任务是什么
- 已经完成了哪些步骤
- 当前正在进行哪个步骤
- 下一步应该做什么
这就是"外部化记忆"的威力——记忆不再依赖于对话的连续性，而是固化在文件中。
2.3 核心原则三：上下文窗口极简主义
很多开发者有一个误区：觉得给 AI 的信息越多越好。实际上恰恰相反。
上下文越长，AI 的注意力越分散。
Manus 的实践表明，最好的做法是：只喂给 AI 当前步骤必要的信息。
这需要对信息进行合理的拆分和组织。例如：
- notes.md：存放调研资料、参考信息
- plan.md：存放任务规划、步骤拆解
- output.md：存放最终输出结果
当 AI 执行某一步时，只需要读取相关的文件片段，而不是把所有文件的全部内容都塞进上下文。这样做的好处是：
- 保持 AI "大脑清醒"：有限的信息量让 AI 能够集中注意力处理当前任务
- 降低 Token 消耗：每次请求的 Token 数量减少，成本和延迟都会下降
- 减少干扰：避免无关信息对 AI 决策的影响
2.4 核心原则四：思考与行动分离
这是一个非常重要但容易被忽视的原则：不让 AI 在一次回复中同时进行思考、规划和执行。
传统做法的问题是：你给 AI 一个任务，它一股脑地开始分析、规划、写代码，全部混在一起输出。这样做的风险很高——如果 AI 在执行过程中发现思路有问题，之前写的代码可能已经污染了代码库。
正确的做法是强制分离：
第一阶段：思考（Think）
- AI 在专门的 Notes 文件中写下调研结果、分析过程、架构思路
- 这个阶段不产生任何正式的代码或输出
- 开发者可以在这个阶段审核 AI 的思路，提出修正意见
第二阶段：行动（Act）
- 确认思路无误后，AI 再去修改正式的代码文件
- 这个阶段产生的是经过深思熟虑的、高质量的输出
这种分离设计的好处是：
- 降低试错成本：在思考阶段发现问题的修正成本远低于在代码库中修正
- 提高输出质量：经过充分思考的输出，质量通常更高
- 便于审核和追溯：思考过程被记录下来，便于后续回顾和学习
2.5 核心原则五：围绕 KV-Cache 进行设计
这是一个偏技术性的优化原则，但对于生产环境非常重要。
什么是 KV-Cache？
简单来说，当大模型处理输入时，会对每个 Token 进行复杂的计算。KV-Cache 是一种缓存机制，可以缓存之前计算过的结果，避免重复计算。
对于 AI Agent 来说，任务通常呈现"长输入、短输出"的特征——每次请求都需要带上系统提示、工具定义、任务上下文等大量信息，但 AI 的回复相对较短。如果不能有效利用 KV-Cache，每次请求都要从头计算这些重复的内容，成本和延迟将难以承受。
如何设计才能提高缓存命中率？
规则一：保持前缀稳定
不能在 System Prompt 或前置上下文中放入动态内容（如时间戳、随机数等），这会导致后续所有缓存失效。
// 错误做法：System Prompt 中包含动态时间
System: 当前时间是 2024-01-15 10:30:45，你是一个编程助手...
// 正确做法：动态信息放在用户消息中
System: 你是一个编程助手...
User: [当前时间 2024-01-15 10:30:45] 请帮我...规则二：只追加不修改
历史交互记录一旦生成，就不要再去修剪或改写。任何修改都会导致该位置之后的所有缓存失效。
规则三：确定性序列化
如果需要将数据结构序列化为字符串（如 JSON），必须保证相同的数据永远生成完全相同的字符串。这意味着 JSON 对象的 Key 排序必须固定。
# 错误做法：Python 的 dict 在不同版本中顺序可能不同
json.dumps({"b": 2, "a": 1})
# 正确做法：使用 sort_keys 确保顺序固定
json.dumps({"b": 2, "a": 1}, sort_keys=True)
# 始终输出 {"a": 1, "b": 2}2.6 核心原则六：掩码而非移除工具
随着 AI Agent 能力增强，它可能需要调用的工具会越来越多（文件操作、网络请求、代码执行、数据库访问等）。这些工具的定义通常放在 System Prompt 中。
一种直觉的优化做法是：动态移除当前不需要的工具定义，以节省 Token。比如，在只需要文件操作时，移除网络相关的工具定义。
但 Manus 的实践表明，这是一个错误的做法。
动态移除工具会带来两个严重问题：
问题一：破坏 KV-Cache
工具定义通常在 System Prompt 的开头部分。一旦修改，后面所有内容的缓存都会失效。
问题二：造成模型困惑
假设 AI 在第三轮对话中调用了"浏览器"工具，但在第五轮对话时你移除了这个工具的定义。当模型看到历史记录中调用了一个"不存在的工具"时，会产生困惑，可能导致不可预测的行为。
正确的做法是：
- 保留所有工具定义：始终将完整工具集留在 Context 中
- 在解码阶段进行掩码：通过修改 Logits（概率分布）来屏蔽当前不合法的工具
这种方法在底层屏蔽 Token，而不是修改 Prompt。对于模型来说，它仍然"看到"了所有工具，只是在实际选择时被限制了范围。
第三章：Planning-with-Files 项目深度解析
理解了 Manus 的方法论基础，现在我们来深入分析 Planning-with-Files 这个开源项目是如何将这些原则落地实现的。
3.1 项目定位与核心理念
Planning-with-Files 是一个 Claude Code Skill（技能插件），它的核心理念可以用一句话概括：
使用文件进行规划，为 AI 安装一个"外挂大脑"。
这个项目通过强制 AI 使用本地文件来记录进度和思考，解决了大模型在长对话中容易出现的"上下文丢失"和"目标漂移"问题。
项目的设计目标：
- 持久化任务状态：让 AI 的工作进度不依赖于对话连续性
- 分离关注点：将规划、笔记、输出分开管理
- 提高输出质量：强制 AI 先思考再行动
- 降低认知负担：让 AI 每次只关注必要的信息
3.2 三大核心文件详解
安装 Planning-with-Files 后，AI 在执行任务时会自动维护三个核心文件。理解这三个文件的作用和使用方式，是掌握这套工作流的关键。
3.2.1 task_plan.md —— 任务规划中枢
作用定位：
task_plan.md 是整个工作流的"控制中心"，记录了任务的全部规划信息。AI 每次行动前都会首先读取这个文件，确保自己清楚当前的任务目标和进度。
典型内容结构：
# 任务规划
## 任务目标
开发一个用户管理系统的 RESTful API，支持用户的增删改查操作。
## 技术选型
- 语言：Python 3.10
- 框架：FastAPI
- 数据库：PostgreSQL
- ORM：SQLAlchemy
## 任务拆解
### 阶段一：基础架构搭建
- [x] 1.1 初始化项目结构
- [x] 1.2 配置数据库连接
- [x] 1.3 定义用户数据模型
### 阶段二：API 开发
- [x] 2.1 实现用户创建接口
- [ ] 2.2 实现用户查询接口（当前进行中）
- [ ] 2.3 实现用户更新接口
- [ ] 2.4 实现用户删除接口
### 阶段三：测试与优化
- [ ] 3.1 编写单元测试
- [ ] 3.2 添加输入验证
- [ ] 3.3 实现错误处理
- [ ] 3.4 性能优化
## 当前状态
正在进行步骤 2.2，实现用户查询接口。
需要支持按 ID 查询、按用户名查询、分页列表查询三种方式。
## 待解决问题
1. 分页查询的性能优化方案待确定
2. 是否需要支持模糊查询待和需求方确认
## 下一步行动
完成用户查询接口的基础实现，先支持按 ID 查询和分页列表查询。设计要点解析：
- 任务目标明确具体：开头就清晰定义了要做什么，避免目标漂移
- 技术选型固化：提前确定技术栈，避免执行过程中反复摇摆
- 任务拆解合理：按阶段和步骤拆解，颗粒度适中
- 进度状态可视化：使用 checkbox 格式，一眼就能看出完成情况
- 当前状态描述详细：不仅标注在哪一步，还说明具体在做什么
- 问题追踪：记录待解决的问题，避免遗漏
- 下一步行动明确：指导 AI 立即要做的事情
使用技巧：
- 任务目标要尽可能具体，避免模糊的描述
- 任务拆解的颗粒度要适中：太粗会失去指导意义，太细会增加管理负担
- 每完成一个步骤，立即更新状态，保持文件的实时性
- "当前状态"部分要详细，这是 AI 每次读取时最关注的内容
3.2.2 notes.md —— 调研与思考的存储区
作用定位：
notes.md 是 AI 的"草稿本"，用于存放调研资料、中间代码片段、临时的想法、长文本内容等。它的核心价值是保持对话窗口干净，避免因为塞入太多细节而分散 AI 的注意力。
典型内容结构：
# 开发笔记
## 调研记录
### FastAPI 分页实现方案调研
查阅了以下资料：
1. FastAPI 官方文档的分页示例
2. SQLAlchemy 的 limit/offset 使用方法
3. 社区讨论的游标分页 vs 偏移分页优劣
结论：
对于用户量不大的场景（<10万），使用 offset/limit 分页即可。
如果后续需要优化，可以考虑游标分页。
### 用户模型字段设计
参考了业界通用做法，确定以下字段：
- id: UUID 主键
- username: 用户名，唯一
- email: 邮箱，唯一
- password_hash: 密码哈希
- created_at: 创建时间
- updated_at: 更新时间
- is_active: 是否激活
## 代码片段
### 分页参数定义
```python
from pydantic import BaseModel
class PaginationParams(BaseModel):
page: int = 1
page_size: int = 20
@property
def offset(self):
return (self.page - 1) * self.page_size分页响应模型
from typing import Generic, TypeVar, List
from pydantic import BaseModel
T = TypeVar('T')
class PaginatedResponse(BaseModel, Generic[T]):
items: List[T]
total: int
page: int
page_size: int
total_pages: int遇到的问题与解决方案
问题1：SQLAlchemy 2.0 语法变更
问题描述： 按照旧教程写的查询语句报错
原因分析： SQLAlchemy 2.0 使用新的查询语法
解决方案： 使用 select() 语句代替旧的 Query 对象
# 旧语法（不再推荐）
users = session.query(User).all()
# 新语法（SQLAlchemy 2.0）
from sqlalchemy import select
stmt = select(User)
users = session.execute(stmt).scalars().all()待验证的想法
- 是否可以使用 Redis 缓存热门查询结果？
- 用户删除是物理删除还是软删除？
设计要点解析：
1. 调研记录结构化：按主题组织调研内容，方便后续查阅
2. 结论明确：每项调研都要有明确的结论，不是单纯的资料堆砌
3. 代码片段可复用：存放的代码片段可以直接被引用到正式代码中
4. 问题解决过程完整：记录问题、原因、解决方案的完整链路
5. 待验证想法单独列出：区分"已确定"和"待验证"的内容
使用技巧：
- 调研时先在 notes.md 中整理信息，不要急于写代码
- 遇到问题时，先在这里记录分析过程，找到解决方案后再动手
- 好的代码片段可以作为模板保留，后续复用
- 定期清理过时的笔记，保持文件的价值密度
#### 3.2.3 [deliverable].md —— 纯净的输出结果
作用定位：
这是最终输出的文件，可以是代码、文章、报告或其他任何形式的交付物。它的核心特点是纯净——只包含最终结果，不包含思考过程和中间产物。
命名说明：
`[deliverable]` 是一个占位符，实际文件名应该根据输出内容来命名。例如：
- 如果输出是代码：`user_api.py`、`models.py`
- 如果输出是文章：`article.md`、`report.md`
- 如果输出是设计文档：`design_doc.md`
为什么要分离思考过程和最终输出？
1. 便于交付：最终输出可以直接交付给使用方，不需要额外整理
2. 避免污染：思考过程中的试错内容不会混入正式输出
3. 便于审核：审核人可以单独查看最终输出，也可以追溯思考过程
典型工作流程：调研阶段 → 在 notes.md 中记录调研结果
规划阶段 → 在 task_plan.md 中制定计划
执行阶段 → 读取 notes.md 中的结论，生成 [deliverable]
### 3.3 工作流运转机制
了解了三个核心文件后，我们来看看整个工作流是如何运转的。
#### 3.3.1 任务启动阶段
当你向 AI 提出一个任务时，如果任务涉及"规划"相关的关键词（如"规划一下"、"planning"、"制定计划"等），AI 会自动进入 Planning-with-Files 工作模式。
这个阶段 AI 会做的事情：
1. 创建 task_plan.md 文件
2. 分析任务需求：理解用户想要什么
3. 进行任务拆解：将大任务分解为可执行的小步骤
4. 评估技术方案：确定实现路径
5. 记录初始计划：将以上内容写入 task_plan.md
这个阶段你可以做的事情：
- 审核 AI 的任务理解是否正确
- 检查任务拆解是否合理
- 对技术方案提出修正意见
- 补充 AI 可能遗漏的需求点
#### 3.3.2 调研与思考阶段
对于复杂的任务，AI 在动手实现之前会先进行调研和思考。
这个阶段 AI 会做的事情：
1. 创建 notes.md 文件（如果还没有）
2. 进行必要的调研：查阅资料、分析需求、对比方案
3. 记录调研结果：将关键信息写入 notes.md
4. 形成实现思路：在 notes.md 中写下具体的实现方案
5. 更新任务计划：根据调研结果修正 task_plan.md（如果需要）
这个阶段的价值：
- 避免"边做边想"导致的返工
- 让思考过程可见、可审核
- 积累可复用的知识和代码片段
#### 3.3.3 执行与输出阶段
思考成熟后，AI 开始执行具体的任务。
这个阶段 AI 会做的事情：
1. 读取 task_plan.md：确认当前要做的步骤
2. 读取 notes.md：获取相关的调研结论和代码片段
3. 执行任务：生成代码、编写内容等
4. 输出结果：将成果写入 [deliverable] 文件
5. 更新进度：在 task_plan.md 中标记步骤完成
这个阶段的注意事项：
- 每完成一个步骤都要及时更新 task_plan.md
- 如果执行中发现新问题，先记录到 notes.md，不要急于改动计划
- 输出文件要保持干净，不包含思考过程
#### 3.3.4 迭代与完善阶段
复杂任务通常需要多次迭代。
迭代时 AI 会做的事情：
1. 审视当前进度：读取 task_plan.md 了解全局状态
2. 分析反馈意见：理解用户的修改需求
3. 更新计划：在 task_plan.md 中调整后续步骤
4. 记录新发现：在 notes.md 中补充新的信息
5. 继续执行：按更新后的计划推进任务
迭代的优势：
由于状态是显式存储在文件中的，即使对话中断也可以无缝继续。AI 不需要你重新描述背景，只需要读取文件就能了解所有情况。
---
## 第四章：安装与使用实战指南
理论讲完了，现在进入实战环节。源码七号站 为大家整理了详细的安装和使用步骤。
### 4.1 前置准备
#### 4.1.1 确认 Claude Code 已安装
Planning-with-Files 是一个 Claude Code Skill，所以你需要先安装 Claude Code。
什么是 Claude Code？
Claude Code 是 Anthropic 推出的命令行工具，允许开发者在终端中直接与 Claude AI 进行代码相关的交互。它支持 Skill（技能）系统，可以通过安装不同的 Skill 来扩展 AI 的能力。
安装 Claude Code：
如果你还没有安装 Claude Code，请参考 Anthropic 官方文档进行安装。安装完成后，在终端中输入以下命令验证：
```bash
claude --version如果能看到版本号输出，说明安装成功。
4.1.2 了解 Skill 系统
在安装 Planning-with-Files 之前，你需要对 Claude Code 的 Skill 系统有基本了解。
Skill 是什么？
Skill 是一种扩展 Claude Code 能力的机制，类似于浏览器的插件或 IDE 的扩展。每个 Skill 定义了一组专门的行为模式，让 AI 能够以特定的方式处理特定类型的任务。
Skill 的工作原理：
当 Skill 被激活时，它会向 AI 注入特定的指令和工作流程。这些指令告诉 AI：
- 在什么情况下激活这个工作模式
- 需要创建和维护哪些文件
- 应该遵循什么样的工作流程
4.2 安装 Planning-with-Files
4.2.1 通过 Plugin Marketplace 安装
Claude Code 提供了一个 Plugin Marketplace（插件市场），你可以通过它来安装 Planning-with-Files。
在 Claude Code 的命令行界面中执行以下命令：
/plugin marketplace add OthmanAdi/planning-with-files然后安装这个插件：
/plugin install planning-with-files@planning-with-files4.2.2 验证安装
安装完成后，你可以通过以下命令查看已安装的插件列表：
/plugin list如果列表中出现 planning-with-files，说明安装成功。
4.2.3 手动安装方式
如果通过 Marketplace 安装遇到问题，你也可以选择手动安装。
步骤一：克隆项目仓库
git clone https://github.com/OthmanAdi/planning-with-files.git步骤二：进入项目目录
cd planning-with-files步骤三：按照项目 README 中的说明完成安装
具体步骤可能因版本更新而有所变化，请以项目仓库中的最新文档为准。
