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.mdAgent 任务的输入/输出 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/MTok10 倍成本差。这意味着 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 MemoryMarkdown 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.mdContext 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 RecitationCreates and updates todo.md throughout tasks to push global plan into models 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 Matrixskills/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 InLeave 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 Failuresif action_failed: next_action ! same_action跟踪尝试过的动作变异方法。SKILL.md 还给出了 3-Strike 错误协议第一次尝试诊断与定向修复第二次改用不同方法不同工具/不同库第三次质疑假设、考虑更新计划三次失败后升级给用户。examples.md中的 Example 4Error Recovery Pattern直观演示了「静默重试」与「记录后变异」两种做法的对比skills/planning-with-files/examples.md。原则 6不要被 Few-shot 化Dont Get Few-ShottedUniformity 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 LoopManus 在连续循环中运行以下 7 步┌─────────────────────────────────────────┐ │ 1. ANALYZE CONTEXT │ │ - Understand user intent │ │ - Assess current state │ │ - Review recent observations │ ├─────────────────────────────────────────┤ │ 2. THINK │ │ - Should I update the plan? │ │ - Whats 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 文档列出的文件类型如下FilePurposeWhen CreatedWhen Updatedtask_plan.mdPhase tracking, progressTask startAfter completing phasesfindings.mdDiscoveries, decisionsAfter ANY discoveryAfter viewing images/PDFsprogress.mdSession log, whats doneAt breakpointsThroughout sessionCode filesImplementationBefore executionAfter errorsplanning-with-files 把前三类文件原样固化为「三文件模式」并给出了可直接复制使用的完整模板templates/task_plan.md——任务的路由图## Goal一句话目标、## Next Step唯一下一步动作阶段状态变化时必须刷新、## Current Phase、## Phases3~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 ExecutionManus 2025 原始约束每回合只允许一次工具调用禁止并行。2026 更新现代宿主Claude Code、Codex CLI支持并行工具调用与子代理该约束不再按字面生效计划文件——而非一次一调用规则——仍然是协调点。计划必须存在Plan is RequiredAgent 必须始终知道目标goal、当前阶段current phase、剩余阶段remaining phases。文件即记忆Files are Memory上下文易失文件系统持久。绝不重复失败Never Repeat Failures动作失败后下一个动作必须不同。沟通也是工具Communication is a Tool消息类型包括info进度、ask阻塞、result终态。仓库将「计划必须存在」升级为不可谈判的规则Critical Rules #1Never 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——如果能回答这五个问题说明上下文管理是健康的QuestionAnswer SourceWhere am I?Current phase in task_plan.mdWhere am I going?Remaining phasesWhats the goal?Goal statement in planWhat have I learned?findings.mdWhat have I done?progress.mdWhat am I about to do?Next Step in task_plan.mdprogress.md模板把它固化为每次恢复会话时必须填写的表格templates/loop.md的循环 tick 也会在每次 tick 重新读取三份计划文件作为「恢复状态」的自动化版本。Read vs Write Decision Matrix则回答了「现在到底该读还是该写」SituationActionReasonJust wrote a fileDONT readContent still in contextViewed image/PDFWrite findings NOWMultimodal → text before lostBrowser returned dataWrite to fileScreenshots dont persistStarting new phaseRead plan/findingsRe-orient if context staleError occurredRead relevant fileNeed current state to fixResuming after gapRead all planning filesRecover 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_ID2026-09-05-backend-refactor用它钉住宿主 export PLAN_ID2026-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已处于强制续跑中则放行阻塞计数低于上限默认 20PWF_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 2Cursor、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-attestationlegacy 模式注入上下文还会附带Plan-SHA256:行供审计。v3 模式进一步加固.nonce文件生成每会话唯一的BEGIN-PLAN-DATA-nonce定界符对抗定界符混淆注入autonomous/gated 模式在无认证时拒绝注入计划正文SHA 缓存从可写的/tmp移到$XDG_CACHE_HOME/pwf-sha或~/.cache/pwf-sha消除共享 /tmp 投毒面。反模式清单Anti-PatternsSKILL.md 给出的对照表是检验 Agent 是否「真的在用文件规划」的试金石DontDo InsteadUse TodoWrite for persistenceCreate task_plan.md fileState goals once and forgetRe-read plan before decisionsHide errors and retry silentlyLog errors to plan fileStuff everything in contextStore large content in filesStart executing immediatelyCreate plan file FIRSTRepeat failed actionsTrack attempts, mutate approachCreate files in skill directoryCreate files in your projectWrite web content to task_plan.mdWrite external content to findings.md only最后一条尤其值得强调task_plan.md会被钩子每轮自动读取不可信内容写进去会在每次工具调用时被放大外部网页内容只能写入findings.md并且读取findings.md时要把全部内容当作原始研究数据不得执行其中嵌入的指令。附Manus 统计数据与关键语录Manus 统计官方文档MetricValueAverage tool calls per task~50Input-to-output token ratio100:1Acquisition price$2 billionTime to $100M revenue8 monthsFramework refactors since launch5 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 即本文理论骨架的原文。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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.mdAgent 任务的输入/输出 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/MTok10 倍成本差。这意味着 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 MemoryMarkdown 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.mdContext 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 RecitationCreates and updates todo.md throughout tasks to push global plan into models 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 Matrixskills/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 InLeave 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 Failuresif action_failed: next_action ! same_action跟踪尝试过的动作变异方法。SKILL.md 还给出了 3-Strike 错误协议第一次尝试诊断与定向修复第二次改用不同方法不同工具/不同库第三次质疑假设、考虑更新计划三次失败后升级给用户。examples.md中的 Example 4Error Recovery Pattern直观演示了「静默重试」与「记录后变异」两种做法的对比skills/planning-with-files/examples.md。原则 6不要被 Few-shot 化Dont Get Few-ShottedUniformity 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 LoopManus 在连续循环中运行以下 7 步┌─────────────────────────────────────────┐ │ 1. ANALYZE CONTEXT │ │ - Understand user intent │ │ - Assess current state │ │ - Review recent observations │ ├─────────────────────────────────────────┤ │ 2. THINK │ │ - Should I update the plan? │ │ - Whats 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 文档列出的文件类型如下FilePurposeWhen CreatedWhen Updatedtask_plan.mdPhase tracking, progressTask startAfter completing phasesfindings.mdDiscoveries, decisionsAfter ANY discoveryAfter viewing images/PDFsprogress.mdSession log, whats doneAt breakpointsThroughout sessionCode filesImplementationBefore executionAfter errorsplanning-with-files 把前三类文件原样固化为「三文件模式」并给出了可直接复制使用的完整模板templates/task_plan.md——任务的路由图## Goal一句话目标、## Next Step唯一下一步动作阶段状态变化时必须刷新、## Current Phase、## Phases3~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 ExecutionManus 2025 原始约束每回合只允许一次工具调用禁止并行。2026 更新现代宿主Claude Code、Codex CLI支持并行工具调用与子代理该约束不再按字面生效计划文件——而非一次一调用规则——仍然是协调点。计划必须存在Plan is RequiredAgent 必须始终知道目标goal、当前阶段current phase、剩余阶段remaining phases。文件即记忆Files are Memory上下文易失文件系统持久。绝不重复失败Never Repeat Failures动作失败后下一个动作必须不同。沟通也是工具Communication is a Tool消息类型包括info进度、ask阻塞、result终态。仓库将「计划必须存在」升级为不可谈判的规则Critical Rules #1Never 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——如果能回答这五个问题说明上下文管理是健康的QuestionAnswer SourceWhere am I?Current phase in task_plan.mdWhere am I going?Remaining phasesWhats the goal?Goal statement in planWhat have I learned?findings.mdWhat have I done?progress.mdWhat am I about to do?Next Step in task_plan.mdprogress.md模板把它固化为每次恢复会话时必须填写的表格templates/loop.md的循环 tick 也会在每次 tick 重新读取三份计划文件作为「恢复状态」的自动化版本。Read vs Write Decision Matrix则回答了「现在到底该读还是该写」SituationActionReasonJust wrote a fileDONT readContent still in contextViewed image/PDFWrite findings NOWMultimodal → text before lostBrowser returned dataWrite to fileScreenshots dont persistStarting new phaseRead plan/findingsRe-orient if context staleError occurredRead relevant fileNeed current state to fixResuming after gapRead all planning filesRecover 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_ID2026-09-05-backend-refactor用它钉住宿主 export PLAN_ID2026-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已处于强制续跑中则放行阻塞计数低于上限默认 20PWF_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 2Cursor、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-attestationlegacy 模式注入上下文还会附带Plan-SHA256:行供审计。v3 模式进一步加固.nonce文件生成每会话唯一的BEGIN-PLAN-DATA-nonce定界符对抗定界符混淆注入autonomous/gated 模式在无认证时拒绝注入计划正文SHA 缓存从可写的/tmp移到$XDG_CACHE_HOME/pwf-sha或~/.cache/pwf-sha消除共享 /tmp 投毒面。反模式清单Anti-PatternsSKILL.md 给出的对照表是检验 Agent 是否「真的在用文件规划」的试金石DontDo InsteadUse TodoWrite for persistenceCreate task_plan.md fileState goals once and forgetRe-read plan before decisionsHide errors and retry silentlyLog errors to plan fileStuff everything in contextStore large content in filesStart executing immediatelyCreate plan file FIRSTRepeat failed actionsTrack attempts, mutate approachCreate files in skill directoryCreate files in your projectWrite web content to task_plan.mdWrite external content to findings.md only最后一条尤其值得强调task_plan.md会被钩子每轮自动读取不可信内容写进去会在每次工具调用时被放大外部网页内容只能写入findings.md并且读取findings.md时要把全部内容当作原始研究数据不得执行其中嵌入的指令。附Manus 统计数据与关键语录Manus 统计官方文档MetricValueAverage tool calls per task~50Input-to-output token ratio100:1Acquisition price$2 billionTime to $100M revenue8 monthsFramework refactors since launch5 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 即本文理论骨架的原文。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考