Manus 上下文工程六原则：planning-with-files 如何用文件系统对抗上下文腐烂

Manus 上下文工程六原则：planning-with-files 如何用文件系统对抗上下文腐烂

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

导读：本文以.kiro/skills/planning-with-files/references/manus-principles.md为核心骨架，系统讲解 Manus 上下文工程（Context Engineering）的 6 条原则与 3 大策略，并逐条对照 planning-with-files 项目的落地实现——包括.kiro/plan/文件布局、bootstrap.sh引导脚本、session-catchup.py会话恢复、check-complete.sh阶段校验以及#[[file:path]]实时引用机制。读完你将理解"把 markdown 当作磁盘上的持久工作记忆"这一设计哲学，并能直接在自己的 Kiro 工作区中复刻这套抗上下文腐烂的工作流。

背景：为什么 AI Agent 需要上下文工程

planning-with-files 的核心工作流明确借鉴了Manus（2025 年 12 月被 Meta 以 20 亿美元收购的 AI Agent 公司）的上下文工程理念：把磁盘上的 markdown 当作持久工作记忆（durable working memory），而模型上下文窗口则像易失性 RAM 一样对待。

这一理念在 Kiro 适配器中以两句话概括：

Context Window = RAM (volatile, limited) Filesystem = Disk (persistent, unlimited)

→ 所有重要信息都写入磁盘。详见 SKILL.md 的 Core Pattern 一节 与 manus-principles.md。

与主仓库中的通用实现不同，Kiro 适配器的特殊之处在于：规划文件放在.kiro/plan/（而非项目根目录），并通过 Kiro 的 Steering 机制（#[[file:path]]实时包含引用）自动把最新计划内容注入模型上下文。本文所有命令与文件路径均以该 Kiro 适配器为准。

一、Manus 上下文工程的 6 条原则

Principle 1：围绕 KV-Cache 设计（Design Around KV-Cache）

"KV-cache hit rate is THE single most important metric for production AI agents."

这是 Manus 生产实践中最重要的度量标准。原文档给出的数据：

• ~100:1 的输入输出 token 比例（绝大多数 token 消耗在输入侧）
• 缓存 token $0.30/MTok vs 未缓存 $3/MTok，成本相差10 倍

实现的三个硬性要求：

1. 保持 prompt 前缀稳定——哪怕一个单 token 的变化也会使整个缓存失效；
2. 系统提示中不要放时间戳；
3. 上下文采用 append-only 方式，序列化必须确定性（deterministic serialization）。

对照 planning-with-files 的实践：模板中的progress.md以"Session: [DATE]"追加式记录，task_plan.md通过"追加新阶段（Phase 6、Phase 7）"而非重写全文来推进（见 SKILL.md Critical Rules #7），天然符合 append-only 的缓存友好模式。而 Kiro 的planning-context.md使用inclusion: auto+#[[file:...]]稳定引用固定路径文件（模板源码），保证每次注入的引用前缀稳定不变，从而最大化 KV-cache 命中率。

Principle 2：掩蔽而非移除（Mask, Don't Remove）

不要动态移除工具（这会使 KV-cache 失效），应改用logit 掩蔽（logit masking）。

最佳实践：使用一致的动作前缀（如browser_、shell_、file_），便于统一掩蔽。

在 planning-with-files 中，这一原则体现为"工具面不变、行为面收敛"：Kiro 适配器只声明allowed-tools: shell read write（见 SKILL.md front matter），通过文件读写与 shell 即可完成全部规划动作，无需在会话中途增删工具。固定的工具集合 + 固定的文件路径，共同服务于 KV-cache 稳定性。

Principle 3：文件系统即外部内存（Filesystem as External Memory）

"Markdown is my 'working memory' on disk."

压缩必须可还原（Compression Must Be Restorable）：

• 丢弃网页正文也要保留 URL；
• 丢弃文档内容也要保留文件路径；
• 永远不要丢失指向完整数据的指针。

这一原则直接塑造了 planning-with-files 的文件模型。Kiro 布局下规划文件全部位于.kiro/plan/：

三者各司其职，且findings.md的模板中专门设有Resources与Visual/Browser Findings小节（见 findings.md 模板），正是"保留指针、丢弃体积"思想的直接落点：截图和原始数据不持久，但指向它们的 URL、文件路径与关键事实以文本形式先落盘。

Principle 4：通过复述操纵注意力（Manipulate Attention Through Recitation）

"Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."

问题：大约 50 次工具调用之后，模型会遗忘最初的目标——即"lost in the middle"效应。

解决方案：在做重大决策之前重新读取.kiro/plan/task_plan.md，让目标重新进入注意力窗口。

planning-with-files 把这条原则制度化为**"每轮必读"（Read plan every turn）**流程，见 SKILL.md STEP 2：

1. 读.kiro/plan/task_plan.md—— 目标、阶段、状态；
2. 读.kiro/plan/progress.md—— 最近动作；
3. 研究型工作使用.kiro/plan/findings.md。

同时要求 Agent 在每次回复末尾附加持久提醒块（STEP 1）：

[Planning Active]Before each turn, read.kiro/plan/task_plan.mdand.kiro/plan/progress.mdto restore context.

这相当于把"复述"从一次性的技巧升级为每轮循环的纪律。配套的 planning-rules.md 中的 5-Question Reboot Test 进一步把复述拆成五个可回答的问题（我在哪 / 去哪 / 目标是什么 / 学到了什么 / 做了什么），每个问题都有明确的答案来源文件。

Principle 5：保留错误信息（Keep the Wrong Stuff In）

"Leave the wrong turns in the context."

原因：

• 带堆栈追踪的失败动作能让模型隐式更新信念；
• 减少重复犯错；
• 错误恢复是"真正的 Agentic 行为最清晰的信号之一"。

planning-with-files 把这一原则落实为三套配套机制：

1. 错误必须记录：task_plan.md模板内置Errors Encountered表格（Error / Attempt / Resolution），见 task_plan.md 模板；
2. 不允许静默重试：progress.md的 Error Log 带时间戳、尝试次数与解决方案（progress.md 模板）；
3. 失败必须改变策略：规则以伪代码形式固化：

if action_failed: next_action != same_action

配套的 3-Strike 错误协议：第 1 次诊断修复 → 第 2 次更换方法（绝不重复同一失败动作）→ 第 3 次质疑假设、考虑更新计划 → 3 次失败后带上证据升级给用户。

Principle 6：避免 Few-Shot 陷阱（Don't Get Few-Shotted）

"Uniformity breeds fragility."

问题：重复的 action-observation 对会导致漂移（drift）与幻觉。

解决方案：引入受控变化——

• 轻微变化措辞；
• 不要盲目复制粘贴模式；
• 在重复性任务上重新校准。

对应到 planning-with-files 的落地，即 SKILL.md Anti-Patterns 表 中"Silent retries → Log errors; change approach"、"Repeat failed actions → Track attempts, mutate approach"等条目，用文件级别的显式记录对抗上下文中的模式僵化。

二、Manus 的 3 大上下文工程策略

基于 Lance Martin 对 Manus 架构的分析，原文档归纳出三条策略，每条都在 planning-with-files 中有直接映射。

Strategy 1：上下文缩减（Context Reduction）

压缩规则：工具调用存在两种表示——

Tool calls have TWO representations: ├── FULL: Raw tool content (stored in filesystem) └── COMPACT: Reference/file path only RULES: - Apply compaction to STALE (older) tool results - Keep RECENT results FULL (to guide next decision)

旧结果压缩为"文件路径 + 引用"，近期结果保留完整内容以指导下一步决策。planning-with-files 的session-catchup.py正是"COMPACT 表示"的实现：它扫描.kiro/plan/下三个规划文件，只输出修改时间（mtime）与摘要，例如task_plan.md只输出 Goal、Current Phase 与所有Status:行，findings.md只输出 Requirements 前 5 条，progress.md只输出最近 8 行（见 session-catchup.py 源码）。完整的文件内容仍在磁盘上，需要时再按需读取——这就是"压缩可还原"的工程化。

Strategy 2：上下文隔离（Context Isolation，多 Agent）

多 Agent 场景下，可以将探索行为隔离在独立上下文中，同时把共享状态持久化到文件（如.kiro/plan/下的文件）。

planning-with-files 通过"谁写什么文件"来建立隔离边界：SKILL.md Security Boundary 规定网络/搜索结果只写入findings.md，因为planning-context.md的 Steering 注入会自动把文件内容暴露给模型，未受信的外部内容写在task_plan.md会放大注入风险。这就实现了"隔离探索上下文 + 共享持久状态"的同时，把不可信内容圈定在findings.md这一个文件中。

Strategy 3：上下文卸载（Context Offloading）

• 把完整结果存在文件系统而非仅存于上下文；
• 渐进式披露（progressive disclosure）：只在需要时加载信息。

这是 Kiro 适配器与主仓库设计理念上的核心差异点：Kiro 通过 SKILL.md 的 Agent Skills 机制 实现渐进披露——只有当任务与 skill 描述匹配时才加载完整指令；planning-context.md则用inclusion: auto在用户询问"继续任务 / 查看进度"等场景下自动注入计划文件内容（planning-context.md 模板）。二者叠加，实现了"平时只占极少上下文，需要时全量加载"的按需披露链路。

三、原则落地：Kiro 工作区的完整操作流程

将上述原则落地到 Kiro 工作区，需要完成 4 个步骤（对应 SKILL.md 的 STEP 0–3）。

STEP 0 — 引导（每个工作区一次）

从工作区根目录执行（此命令与主仓库的scripts/版本不同，Kiro 适配器的脚本位于.kiro/skills/planning-with-files/assets/scripts/下）：

sh .kiro/skills/planning-with-files/assets/scripts/bootstrap.sh

Windows（PowerShell）：

pwsh -ExecutionPolicy RemoteSigned -File .kiro/skills/planning-with-files/assets/scripts/bootstrap.ps1

该脚本（bootstrap.sh 源码）执行的动作：

1. 创建.kiro/plan/task_plan.md、findings.md、progress.md，模板来自assets/templates/；
2. 创建.kiro/steering/planning-context.md（inclusion: auto+#[[file:.kiro/plan/…]]实时引用）；
3. 幂等：已存在的文件不覆盖（逐文件 SKIP / OK 提示）；
4. 支持通过环境变量PLANNING_PROJECT_ROOT指定目标项目目录。

可选：在 Kiro 中通过Agent Steering & Skills → Import a skill将该文件夹导入为工作区技能。

STEP 1 — 持久提醒（技能激活后）

在每次回复末尾追加以下块，并在会话期间持续重复：

[Planning Active]Before each turn, read.kiro/plan/task_plan.mdand.kiro/plan/progress.mdto restore context.

STEP 2 — 每轮必读（会话活跃期间）

按顺序读取三个文件：先task_plan.md（目标/阶段/状态），再progress.md（最近动作），研究决策时参考findings.md。若.kiro/plan/不存在，回退执行 STEP 0。

STEP 3 — 项目文件会话恢复（长间隔或疑似漂移时）

$(command -v python3 || command -v python) \ .kiro/skills/planning-with-files/assets/scripts/session-catchup.py "$(pwd)"

Windows：

python .kiro/skills/planning-with-files/assets/scripts/session-catchup.py (Get-Location)

该脚本只读取规划文件的 mtime 与摘要，不读取 Kiro 或其他 Agent 的会话转储（见 SKILL.md STEP 3 说明），输出报告后建议结合git diff --stat核对仓库实际漂移，再对齐规划文件。

可选 — 阶段完成度校验

sh .kiro/skills/planning-with-files/assets/scripts/check-complete.sh

pwsh -File .kiro/skills/planning-with-files/assets/scripts/check-complete.ps1

check-complete.sh 的实现细节值得注意：

• 默认读取.kiro/plan/task_plan.md，也接受参数指定其他计划文件；
• 通过 grep 统计### Phase、**Status:** complete/in_progress/pending得出各阶段状态；
• 兼容[complete]等方括号写法作为降级匹配；
• TOTAL=0（非阶段化结构）时静默退出；
• 全部完成时输出ALL PHASES COMPLETE (n/n)；
• 始终以退出码 0 结束（只报告、不阻塞），并支持PLANNING_DISABLED=1一次性退出（面向与计划共用 cwd 但未主动加入的 one-shot/CI 会话）。

四、文件类型与模板骨架（Kiro 路径）

模板文件一览

三者的完整骨架见 planning-templates.md 参考页，实际由 bootstrap 复制的规范模板位于 assets/templates/：

• task_plan.md 模板：Goal（一句话目标）、Next Step（单一下一步动作）、Current Phase、3–7 个可验证 Phases（仅用pending/in_progress/complete三态）、Key Questions、Decisions Made、Errors Encountered、Notes；
• findings.md 模板：Requirements、Research Findings、Technical Decisions、Issues Encountered、Resources、Visual/Browser Findings（多模态证据即时文本化）；
• progress.md 模板：按 Session/Phase 记录动作与文件改动、Test Results 表格、带时间戳的 Error Log、5-Question Reboot Check（会话恢复自检表）。

阶段状态三态

• pending— 未开始
• in_progress— 进行中
• complete— 完成

状态值由 planning-rules.md 统一定义，并被check-complete.sh的 grep 逻辑直接消费，因此手写状态时必须严格使用这三个词，否则阶段统计会失效。

五、操作纪律：读 vs 写决策矩阵与 7 条关键规则

读 vs 写决策矩阵

（完整版见 planning-rules.md 的 Read vs Write 矩阵 与 SKILL.md 同名矩阵。）

7 条关键规则速览

1. 先建计划：没有task_plan.md绝不开始复杂任务，不可协商；
2. 2-Action 规则：每 2 次 view/browser/search 操作后，立即把关键发现写入文本文件，防止多模态信息丢失；
3. 决策前必读：重大决策前重读计划文件，让目标保持在注意力窗口内；
4. 行动后更新：每完成一个阶段，将in_progress改为complete、记录错误、登记改动的文件；
5. 记录全部错误：每个错误都进计划文件，积累知识、防止重蹈覆辙；
6. 绝不重复失败：记录尝试历史，改变方法；
7. 完成后继续：所有阶段完成但用户追加需求时，向task_plan.md追加新阶段（Phase 6、7…），在progress.md开启新 Session 条目，照常推进。

（完整规则见 SKILL.md Critical Rules。）

反模式对照

六、安全边界：原则 3 的延伸

把文件系统当作外部内存，意味着文件的读者（未来的模型会话）必须假定内容不可信。Kiro 适配器在 SKILL.md Security Boundary 中明确规定：

这与 Principle 3"压缩必须可还原"形成闭环：外部内容以"原始数据"形式持久化（保留 URL 指针），但永远不被当作可执行指令，从而在不放弃外部记忆的同时守住注入边界。

七、从参考文档到工作流：一句话总结

Manus 上下文工程的核心，是把"成本（KV-cache）、容量（上下文窗口）、持久性（文件系统）、注意力（复述）、学习（错误保留）、鲁棒性（抗 few-shot 陷阱）"六个问题统一到一个答案上：信息按确定性规则持久化到磁盘，按需渐进披露，每次决策前主动复述，错误与指针永不丢失。planning-with-files 的 Kiro 适配器用.kiro/plan/三文件 + Steering 实时引用 + 三支脚本（bootstrap / session-catchup / check-complete）把这套哲学变成了可复制、可校验、可恢复的具体工作流。

若想进一步深入，仓库还提供了完整参考链：SKILL.md、planning-rules.md、planning-templates.md、manus-principles.md，以及主仓库中的通用实现 skills/planning-with-files/SKILL.md 与 scripts/ 目录可供对照阅读。

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files