planning-with-files 中的 Manus 上下文工程：六大原则、三大策略与持久化文件规划实战-港品优选

planning-with-files 中的 Manus 上下文工程：六大原则、三大策略与持久化文件规划实战

【免费下载链接】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

本文以 Manus 官方上下文工程文档（"Context Engineering for AI Agents: Lessons from Building Manus"）为理论骨架，结合开源仓库 planning-with-files 的真实实现（持久化 Markdown 计划文件、生命周期钩子注入、防崩溃恢复与确定性完成闸门），系统讲解如何把「KV-cache 优先、文件系统即外部记忆、复述驱动注意力」等思想落地到 AI 编码 Agent 的日常任务中。读完你将掌握上下文工程的六大原则与三大策略，并能直接用三文件模式（task_plan.md/findings.md/progress.md）让长任务不丢目标、崩溃后可恢复、重复失败被消灭。

背景：为什么上下文工程决定了生产级 Agent 的成败

Manus 是 2025 年 12 月被 Meta 以 20 亿美元收购的 AI Agent 公司。在其官方上下文工程文档中，Manus 团队总结出一组可复用的工程原则，核心判断只有一句话：

"KV-cache hit rate is THE single most important metric for production AI agents."（KV-cache 命中率是生产级 AI Agent 最重要的指标。）

这背后的成本结构非常直观（数据出自 Manus 官方文档与仓库 reference.md）：

Agent 任务的输入/输出 token 比约为100:1；
命中的缓存 token 价格为$0.30/MTok，未命中为$3/MTok，存在10 倍成本差；
因此，任何导致缓存失效的「前缀抖动」——哪怕只改了一个 token——都会让成本与延迟成倍上升。

planning-with-files 仓库正是围绕这套思想构建的：它用磁盘上的持久化 Markdown 文件充当模型的「工作记忆」，并通过生命周期钩子在每轮对话开始、每次工具调用前把选定的计划上下文注入模型，以对抗上下文腐烂（context rot）。你可以从 skills/planning-with-files/SKILL.md 的完整实现、scripts/ 下的辅助脚本以及 .cursor/skills/planning-with-files/reference.md 的参考文档中，逐条对照本文的原则与落地代码。

Manus 六大上下文工程原则

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

统计事实：输入/输出 token 比约 100:1；缓存 token $0.30/MTok vs 未缓存 $3/MTok，10 倍成本差。这意味着 Agent 的每一轮请求，绝大部分 token 都是重复发送的「前缀」，能否命中 KV-cache 直接决定成本曲线。

三条实现纪律：

保持提示词前缀稳定（STABLE）——单个 token 的变化就会使整段缓存失效；
系统提示词中不要放时间戳——时间戳是每轮必变的缓存杀手；
让上下文只追加、使用确定性序列化（append-only + deterministic serialization）。

仓库对这条原则最直接的回应，是 scripts/inject-plan.sh 中固定形状的注入内容：计划注入使用确定的head -50（回合开始）与head -30（每次工具调用）窗口，并包裹在固定的===BEGIN PLAN DATA===/===END PLAN DATA===定界符之间（见 scripts/_v240_update_hook_bodies.py）。只要计划文件没有变化，注入字节就是逐字节稳定的，钩子输出不会成为缓存失效的来源。更进一步，v3 模式下的 scripts/ledger-summary.sh 合成的账本摘要「不携带时间戳、不携带磁盘自由文本」，官方文档明确说明这是「by construction」KV-cache 稳定的注入块——参见 skills/planning-with-files/SKILL.md 的 Ledger contract summary 一节。

原则 2：遮蔽（Mask），不要移除（Remove）

不要动态地从工具列表中移除工具——这同样会破坏 KV-cache。正确做法是使用logit 遮蔽（logit masking），即模型仍在完整的工具空间中打分，但某些工具的 logits 被强制压低。

最佳实践：为动作使用一致的前缀（如browser_、shell_、file_），让遮蔽更易于按前缀分组实现。这条原则对钩子实现的意义在于：宁可保持工具集合与提示词形状不变，也不要每轮动态增删，因为任何形状变化都会让「稳定前缀」的目标落空。

原则 3：文件系统即外部记忆（Filesystem as External Memory）

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

这是全篇最容易被复用的公式：

Context Window = RAM (volatile, limited) ← 易失、有限 Filesystem = Disk (persistent, unlimited) ← 持久、无限

压缩必须可恢复（Compression Must Be Restorable）：

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

在 planning-with-files 中，这一公式被直接写进了技能的核心模式（skills/planning-with-files/SKILL.md）：

Context Window = RAM (volatile, limited) Filesystem = Disk (persistent, unlimited) → Anything important gets written to disk. ← 任何重要的东西都写到磁盘

仓库的「2-Action Rule」正是这条原则的操作化：每执行 2 次查看/浏览器/搜索操作后，立即把关键发现写入文本文件，防止多模态信息（截图、PDF、网页）在上下文滚动中丢失。而findings.md模板中专门设有## Visual/Browser Findings一节，要求「在源还可用时，把图片、PDF、图表、浏览器结果中的相关信息转换成简洁文本」（见 skills/planning-with-files/templates/findings.md）。

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

"Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."（在任务全程创建并更新 todo.md，把全局计划推入模型最近的注意力窗口。）

问题：约 50 次工具调用之后，模型会遗忘原始目标——这就是著名的「中间丢失」（lost in the middle）效应：

Start of context: [Original goal - far away, forgotten] ← 原始目标太远，被遗忘 ...many tool calls... End of context: [Recently read task_plan.md - gets ATTENTION!] ← 刚读的计划文件获得注意力

解法：在每次决策前重新读取task_plan.md，让目标重新出现在注意力窗口内。

这条原则在仓库中的落地有两层：

第一层是「读后再决策」规则。SKILL.md 的 Critical Rules 第 3 条要求：重大决策前必须读取计划文件，让目标保持在注意力窗口内；配合 Read vs Write Decision Matrix（skills/planning-with-files/SKILL.md），在「开始新阶段」「出错后」「长时间间隔后恢复」三种场景下都要先读计划/发现文件再行动。

第二层是自动复述（recitation）。仓库的UserPromptSubmit与PreToolUse生命周期钩子会在每轮开始、每次工具调用前把计划头部注入上下文——这正是「把全局计划推入模型最近的注意力窗口」的自动化实现。从 scripts/inject-plan.sh 的注释可以看到，v3 的 autonomous/gated 模式会放弃每工具调用一次的复述（该注入约 90 token/次，是随工具调用次数线性增长的组件），因为强模型漂移更小；但回合开始的注入被保留，因为证据（论文 arXiv 2603.03258、Opus 4.7+ 子代理上的观测）表明漂移是真实存在的，「完全消除复述」没有证据支持。

原则 5：把「错误的东西」留在上下文里（Keep the Wrong Stuff In）

"Leave the wrong turns in the context."（把走过的弯路留在上下文里。）

原因：

带有堆栈追踪的失败动作可以让模型隐式更新信念；
减少重复犯错；
错误恢复是「真正 Agentic 行为最清晰的信号之一」（"one of the clearest signals of TRUE agentic behavior"）。

仓库把这条原则操作化为两条硬性规则：

记录所有错误（Log ALL Errors）：每个错误都写进计划文件的## Errors Encountered表格（Error / Attempt / Resolution），既积累知识又防止重蹈覆辙；task_plan.md模板为此提供了固定表格（skills/planning-with-files/templates/task_plan.md）。
绝不重复失败（Never Repeat Failures）：

if action_failed: next_action != same_action

跟踪尝试过的动作，变异方法。SKILL.md 还给出了 3-Strike 错误协议：第一次尝试诊断与定向修复；第二次改用不同方法（不同工具/不同库）；第三次质疑假设、考虑更新计划；三次失败后升级给用户。examples.md中的 Example 4（Error Recovery Pattern）直观演示了「静默重试」与「记录后变异」两种做法的对比（skills/planning-with-files/examples.md）。

原则 6：不要被 Few-shot 化（Don't Get Few-Shotted）

"Uniformity breeds fragility."（千篇一律滋生脆弱性。）

问题：重复的动作-观察对（action-observation pairs）会导致漂移（drift）与幻觉（hallucination）。

解法：引入受控变异（controlled variation）：

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

三大上下文工程策略（基于 Lance Martin 对 Manus 架构的分析）

策略 1：上下文缩减（Context Reduction）

压缩（Compaction）：工具调用拥有两种表示：

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) ← 最近的保留完整形态以指导下一步

摘要（Summarization）：当压缩进入收益递减区间时，改用摘要——基于完整工具结果生成，产出标准化的摘要对象。

这与仓库的session-catchup.py --metadata模式同构：显式调用时只读取同项目的本地会话记录并输出聚合计数，绝不输出转录原文；--replay才是可选的、有界的、以 nonce 框架包裹的摘录回放（见 skills/planning-with-files/SKILL.md）。自动恢复与裸调用session-catchup.py不读取任何 Agent 会话存储——保持最小信息暴露，正是「引用/路径 vs 全文」哲学在隐私维度上的延伸。

策略 2：上下文隔离（Context Isolation，多 Agent 架构）

Manus 的架构把上下文按角色隔离：

┌─────────────────────────────────┐ │ PLANNER AGENT │ │ └─ Assigns tasks to sub-agents │ ├─────────────────────────────────┤ │ KNOWLEDGE MANAGER │ │ └─ Reviews conversations │ │ └─ Determines filesystem store │ ├─────────────────────────────────┤ │ EXECUTOR SUB-AGENTS │ │ └─ Perform assigned tasks │ │ └─ Have own context windows │ └─────────────────────────────────┘

关键洞察：Manus 最初用todo.md做任务规划，但发现约有33% 的动作花在更新它上面，于是转向专职 planner agent 调用 executor 子代理。

仓库沿用了「隔离 + 单一协调点」的思路并做了一个关键更新（见 reference.md 的 2026 update）：现代宿主（Claude Code、Codex CLI）支持并行工具调用与子代理，Manus 2025 年的「每回合只允许一次工具调用」约束不再适用；协调点从「一次一调用」规则转移到了磁盘上持久化的 Markdown 计划文件——并行调用与子代理通过这份耐久计划共享状态。在 skills/planning-with-files/SKILL.md 的并行工作流中，每个任务通过scripts/init-session.sh "Task Name"建立独立的.planning/<date>-<slug>/计划目录，并用export PLAN_ID=...把每个 Agent 宿主钉（pin）到自己的计划上；多 Agent 协作同一任务时共享PLAN_ID、由唯一 orchestrator 拥有计划文件、worker 使用各自的 ledger 或分配文件——这正是 Planner/Executor 隔离在单仓库多任务场景下的文件级实现。

策略 3：上下文卸载（Context Offloading）

工具设计原则：

全部原子函数控制在20 个以内；
完整结果存文件系统，不占上下文；
用glob和grep检索；
渐进式披露（progressive disclosure）：只在需要时按需加载信息。

仓库的技能 frontmatter 将可用工具显式限制为Read Write Edit Bash Glob Grep（见 skills/planning-with-files/SKILL.md），与「<20 个原子函数」的思想一致；而 templates/loop.md 中的 planning-aware 循环 tick 明确指示「只重新读取task_plan.md、progress.md与findings.md最近 20 行」——按需加载而非全量塞入，正是渐进式披露的落地形态。

Manus 的 7 步 Agent Loop

Manus 在连续循环中运行以下 7 步：

┌─────────────────────────────────────────┐ │ 1. ANALYZE CONTEXT │ │ - Understand user intent │ │ - Assess current state │ │ - Review recent observations │ ├─────────────────────────────────────────┤ │ 2. THINK │ │ - Should I update the plan? │ │ - What's the next logical action? │ │ - Are there blockers? │ ├─────────────────────────────────────────┤ │ 3. SELECT TOOL │ │ - Choose ONE tool │ │ - Ensure parameters available │ ├─────────────────────────────────────────┤ │ 4. EXECUTE ACTION │ │ - Tool runs in sandbox │ ├─────────────────────────────────────────┤ │ 5. RECEIVE OBSERVATION │ │ - Result appended to context │ ├─────────────────────────────────────────┤ │ 6. ITERATE │ │ - Return to step 1 │ │ - Continue until complete │ ├─────────────────────────────────────────┤ │ 7. DELIVER OUTCOME │ │ - Send results to user │ │ - Attach all relevant files │ └─────────────────────────────────────────┘

注意第 3 步在 Manus 2025 年的沙箱实践里是「每次只选一个工具」，而第 6 步让循环回到第 1 步继续迭代，直到完成第 7 步交付。

这条循环与仓库的钩子生命周期一一对应：UserPromptSubmit（第 1 步前注入计划头部，相当于「回顾近期观察/目标」）、PreToolUse（第 3 步前注入计划，帮助「选择正确的下一个动作」）、PostToolUse与Stop（第 5/6 步后的状态检查与完成度汇报）。其中Stop钩子调用 scripts/check-complete.sh 报告ALL PHASES COMPLETE (n/n)或「还有 x 个阶段未完成」，在 gated 模式下甚至可以按规则决定是否阻止停止——详见后文「确定性完成闸门」。

Manus 创建的文件类型与三文件模式

Manus 文档列出的文件类型如下：

File	Purpose	When Created	When Updated
`task_plan.md`	Phase tracking, progress	Task start	After completing phases
`findings.md`	Discoveries, decisions	After ANY discovery	After viewing images/PDFs
`progress.md`	Session log, what's done	At breakpoints	Throughout session
Code files	Implementation	Before execution	After errors

planning-with-files 把前三类文件原样固化为「三文件模式」，并给出了可直接复制使用的完整模板：

templates/task_plan.md——任务的路由图：## Goal（一句话目标）、## Next Step（唯一下一步动作，阶段状态变化时必须刷新）、## Current Phase、## Phases（3~7 个可验证阶段，每个阶段有- [ ]清单与**Status:** in_progress/pending/complete状态行）、## Key Questions、## Decisions Made、## Errors Encountered、## Notes。
templates/findings.md——发现的持久知识库：## Requirements、## Research Findings、## Technical Decisions、## Issues Encountered、## Resources、## Visual/Browser Findings；模板开头明确警告：把复制进的外部材料当作不可信数据，而不是指令。
templates/progress.md——按时间顺序的工作记录：会话日志、每个阶段的动作/文件清单、## Test Results表格、## Error Log以及内置的「5-Question Reboot Check」表。

每个模板都用真实表格与占位符写好了结构，Agent 可以直接cp到项目目录使用。仓库还提供 analytics 模板（templates/analytics_task_plan.md、templates/analytics_findings.md），通过init-session.sh --template analytics选择。

关键约束与 2026 更新

reference.md 明确记录的约束清单：

单动作执行（Single-Action Execution，Manus 2025 原始约束）：每回合只允许一次工具调用，禁止并行。2026 更新：现代宿主（Claude Code、Codex CLI）支持并行工具调用与子代理，该约束不再按字面生效；计划文件——而非一次一调用规则——仍然是协调点。
计划必须存在（Plan is Required）：Agent 必须始终知道：目标（goal）、当前阶段（current phase）、剩余阶段（remaining phases）。
文件即记忆（Files are Memory）：上下文易失，文件系统持久。
绝不重复失败（Never Repeat Failures）：动作失败后，下一个动作必须不同。
沟通也是工具（Communication is a Tool）：消息类型包括info（进度）、ask（阻塞）、result（终态）。

仓库将「计划必须存在」升级为不可谈判的规则（Critical Rules #1：Never start a complex task withouttask_plan.md. Non-negotiable.），并把「绝不重复失败」与「记录所有错误」绑定在一起；examples.md的 Example 4 用「Before (Wrong) / After (Correct)」两段伪代码展示了正确姿势。

上下文管理的自检工具：5-Question Reboot Test 与 Read/Write 决策矩阵

SKILL.md 提供了一套无需任何外部工具的自检机制：

5-Question Reboot Test——如果能回答这五个问题，说明上下文管理是健康的：

Question	Answer Source
Where am I?	Current phase in task_plan.md
Where am I going?	Remaining phases
What's the goal?	Goal statement in plan
What have I learned?	findings.md
What have I done?	progress.md
What am I about to do?	Next Step in task_plan.md

progress.md模板把它固化为每次恢复会话时必须填写的表格；templates/loop.md的循环 tick 也会在每次 tick 重新读取三份计划文件，作为「恢复状态」的自动化版本。

Read vs Write Decision Matrix则回答了「现在到底该读还是该写」：

Situation	Action	Reason
Just wrote a file	DON'T read	Content still in context
Viewed image/PDF	Write findings NOW	Multimodal → text before lost
Browser returned data	Write to file	Screenshots don't persist
Starting new phase	Read plan/findings	Re-orient if context stale
Error occurred	Read relevant file	Need current state to fix
Resuming after gap	Read all planning files	Recover state

在 planning-with-files 中的完整落地：三文件模式、并行任务与完成闸门

三文件模式的启动与阶段流转

使用scripts/init-session.sh初始化规划文件（scripts/init-session.sh）：

# 旧式（legacy）：在项目根目录创建 task_plan.md / findings.md / progress.md ./scripts/init-session.sh # slug 模式：为并行多任务建立隔离计划目录 .planning/<date>-<slug>/ ./scripts/init-session.sh "Backend Refactor" # 输出 PLAN_ID=2026-09-05-backend-refactor，用它钉住宿主： export PLAN_ID=2026-09-05-backend-refactor # v3 自主模式 / gated 模式（可选，见下文） sh scripts/init-session.sh --autonomous "Long Research Run" sh scripts/init-session.sh --gated "Build Pipeline"

阶段流转遵循四条核心规则：阶段状态只取pending → in_progress → complete三值；阶段状态变化时同步刷新## Next Step使其指向唯一的下一步动作；每个错误写入## Errors Encountered；全部阶段完成但用户追加工作时，在task_plan.md中追加新阶段（如 Phase 6、Phase 7）并在progress.md记录新会话条目，继续正常流程。

完成度检查由 scripts/check-complete.sh 执行：它统计### Phase标题总数，并按**Status:** complete/in_progress/pending（或内联[complete]等格式）分别计数，输出ALL PHASES COMPLETE (n/n)或Task in progress (n/n phases complete)。其解析逻辑支持两种状态书写格式混用的计划文件——这正是「计划文件是协调点」这一约束的代码级体现。

确定性完成闸门（gated 模式）

v3 的 gated 模式把「计划文件是终止判据」做到极致：闸门判定磁盘上的计划工件，而不是对话转录——这是它优于可被幻觉污染的转录型评估器的原因。在 scripts/check-complete.sh 中，Stop 闸门只有在以下全部条件成立时才会输出{"decision":"block",...}：

模式为 gated（计划目录.mode文件含gate标记）；
存在in_progress阶段（而非仅仅 complete < total——不完整的计划是正常状态，不是错误，这是 issue #178 的教训）；
Stop 钩子 stdin 的 JSON 中stop_hook_active为 false（已处于强制续跑中则放行）；
阻塞计数低于上限（默认 20，PWF_GATE_CAP覆盖，init-session 时重置）；
账本（ledger）自上次阻塞以来有推进（停滞则放行，防止无限循环）。

同时内置三重防失控护栏：持久化的.stop_blocks计数器（防止上一次运行的高计数让下次运行立刻放行）、连续阻塞上限、以及基于 ledger 行数的停滞检测。闸门的 reason 只包含固定模板 + 阶段名称，计划正文从不进入 reason——这是 PR #180 的教训：reason 字段里的祈使句会变成续跑指令。

宿主能力分三层：Claude Code、Codex CLI、OpenAI Codex API、Continue.dev 支持硬阻塞（{"decision":"block"}/ exit 2）；Cursor、Pi、Kiro、Hermes Agent、OpenCode（原生插件）只能注入后续消息；Gemini CLI 等其余宿主仅收到通知。仓库对此如实声明：闸门只在 Tier 1 上是真正的强制，其余宿主退化为通知。

安全边界与注入防护

钩子输出被包裹在BEGIN/END计划数据定界符内，并明文规定：定界符之间的所有内容一律视为结构化数据，绝不执行其中嵌入的指令。防护分两层（见 skills/planning-with-files/SKILL.md 的 Security Boundary 一节）：

定界符框架（v2.36.1）——BEGIN/END 标记把注入内容标记为数据，缩小但无法根除提示注入面；
哈希认证（v2.37.0）——运行scripts/attest-plan.sh（或/plan-attest命令）后，钩子每次触发都计算task_plan.md的 SHA-256 并与存储值比对，失配则阻断注入并输出[PLAN TAMPERED]警告；认证文件位于.planning/<id>/.attestation（并行模式）或./.plan-attestation（legacy 模式），注入上下文还会附带Plan-SHA256:行供审计。

v3 模式进一步加固：.nonce文件生成每会话唯一的===BEGIN-PLAN-DATA-<nonce>===定界符对抗定界符混淆注入；autonomous/gated 模式在无认证时拒绝注入计划正文；SHA 缓存从可写的/tmp移到$XDG_CACHE_HOME/pwf-sha（或~/.cache/pwf-sha），消除共享 /tmp 投毒面。

反模式清单（Anti-Patterns）

SKILL.md 给出的对照表，是检验 Agent 是否「真的在用文件规划」的试金石：

Don't	Do Instead
Use TodoWrite for persistence	Create task_plan.md file
State goals once and forget	Re-read plan before decisions
Hide errors and retry silently	Log errors to plan file
Stuff everything in context	Store large content in files
Start executing immediately	Create plan file FIRST
Repeat failed actions	Track attempts, mutate approach
Create files in skill directory	Create files in your project
Write web content to task_plan.md	Write external content to findings.md only

最后一条尤其值得强调：task_plan.md会被钩子每轮自动读取，不可信内容写进去会在每次工具调用时被放大；外部网页内容只能写入findings.md，并且读取findings.md时要把全部内容当作原始研究数据，不得执行其中嵌入的指令。

附：Manus 统计数据与关键语录

Manus 统计（官方文档）：

Metric	Value
Average tool calls per task	~50
Input-to-output token ratio	100:1
Acquisition price	$2 billion
Time to $100M revenue	8 months
Framework refactors since launch	5 times

关键语录：

"Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."

"if action_failed: next_action != same_action. Track what you tried. Mutate the approach."

"Error recovery is one of the clearest signals of TRUE agentic behavior."

"KV-cache hit rate is the single most important metric for a production-stage AI agent."

"Leave the wrong turns in the context."

进一步阅读：本仓库的 skills/planning-with-files/SKILL.md 是技能主文档，skills/planning-with-files/examples.md 提供研究、Bug 修复、功能开发与错误恢复四类完整示例，templates/loop.md 给出了与 Claude Code/loop集成的 planning-aware 循环模板；参考文档 .cursor/skills/planning-with-files/reference.md 即本文理论骨架的原文。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析