Phase 1 / Ep 05: 物理外挂 planning-with-files

⏱ 预计阅读 4 分钟 更新于 2026/4/13

如果说前面几节是提升 Agent 的“人设”和“纪律”，那这一节就是实实在在突破当前所有大型语言模型（LLM）理论天花板——记忆容量与上下文坍塌的核心技术。

当我们的 T-Block 日历管理系统复杂到有 50 个文件、上百条 API 通讯时。哪怕是最强的模型也会在第 50 轮对话中不可避免地忘记你在第 1 轮说的某个关键约束。

这套模式脱胎于顶级明星级产品 Manus：好记性不如烂笔头。用持久的文本文件代替 Token 会话。

1. 原理：用文件系统充当大模型的海马体

Context Window 聊天框上下文 = 电脑的内存条（RAM）——随时清空，容量极其有限。
Filesystem 项目文件 = 电脑的硬盘（Disk）——持久存在，随时按名检索。

我们要给 Agent 注入一个强制性、非黑即白的逻辑观念：“凡是重要的决定、发现、规划，必须写进硬盘里。”

2. 建立技能规划法则

在 .agents/skills/planning-with-files/SKILL.md 中，创建如下极度纯粹的方法论核心：

name: planning-with-files
description: 在面对任何复杂任务、研发现象或长期构建时使用，防止核心步骤在上下文中丢失。

## 核心机制 (The Manus Way)
当你面对多步骤的任务前，不要立刻开始搜索代码。强制建立或读取以下三个文件：

1. **`docs/task_plan.md`**：记录大步骤计划、每一个目标完成状态 (`[ ]` `[/]` `[x]`) 以及关键决策。
2. **`docs/findings.md`**：当作知识外挂区。每次你分析了某 API 结构、或是遇到了某种特殊的机制现象，绝不只停留在对话框回答用户，立刻把它固化下来写入这个文档！
3. **`docs/progress.md`**：用于本次对话/会话 Session 留存的归档日记。交代今天解决了什么错误。

**【两部行动法则】：** 永远不要连续做超过了三次查文件或浏览操作而不总结！查两下，就一定要回到 findings.md 记录发现。
**【不重复犯错原则】：** 如果某步骤错误，你在进行 plan_task 第二次尝试前，必须在进步文档里记录：“使用 A 方式产生了 B 的 Error，因此我必须变更工具去寻找出路”。

3. 三剑客（三份核心 MD 文件）为何无坚不摧？

  • task_plan.md：你的任务板（类似于内网 Jira）。当对话超过 8000 token 甚至重启环境后。Agent 只要看一眼它，就知道：“原来我们在等 Google 接口调试，前置配置已经做完了。”
  • findings.md：科研笔记本。我们在接入 Google Calendar 时，必然会遇到各种时区坑、权限坑。Agent 要把掉过的坑写进去，之后的重构就不可能再重蹈覆辙。
  • progress.md：每日交接版。如果明天你是换了一台电脑另一套模型接入，你可以无缝续接今日进展。

有了这“物理三剑客”。即便是长达 30 期的超级项目，哪怕中途你休息了一个月再打开。只要给新唤醒的 Agent 一个指令：“请阅读一下 docs 目录的 plan 和 findings”，它就能 1 秒钟回忆起数万字的前生因果！

下一步，也就是 Phase 1 的尾声：我们要把这些孤立的法则，串联成真正开工运行的生产流水线（Workflows）。