从 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-filesManus 上下文工程原则Context Engineering Principles是 AI Agent 生产化运行的核心方法论而 planning-with-files 正是把这一方法论工程化为可运行、可复现工具链的开源实现。本指南以仓库内 reference.md 为骨架完整讲解 Manus 的 6 条上下文工程原则、3 大上下文工程策略与 7 步 Agent 循环并结合本仓库的 hooks、scripts 与 templates 源码说明每条原则在真实 Agent 工作流Claude Code、Codex、Cursor 等中如何被落地为持久化 Markdown 规划、生命周期注入、哈希背书与完成门控。读完后你将既理解为什么 Agent 需要文件化记忆也掌握如何用一套可复用的技能/脚本体系实现它。文档定位从 Manus 实战中提炼的上下文工程纲要本仓库的参考文档reference.md是一份浓缩的Manus 上下文工程原理备忘录其源头是 Manus2025 年 12 月被 Meta 以 20 亿美元收购的 AI Agent 公司官方发布的上下文工程文档。它回答了生产环境中 AI Agent 最棘手的一类问题当上下文窗口是易失、有限的内存RAM时Agent 如何依靠文件系统这块持久、无限的磁盘Disk来完成长任务整份文档可以分为四个层次6 条底层原则——关于 KV-Cache、注意力、记忆与失败处理的第一性原理3 大工程策略——上下文缩减、隔离、卸载的架构手段7 步 Agent 循环——Agent 单次行动的统一执行框架配套约束、统计与金句——可操作的行为规则与经验数据。下文将逐层展开并在每一节末尾以仓库实现印证的形式指出本仓库中对应落地这些原则的源码与配置。一、6 条 Manus 上下文工程原则原则 1围绕 KV-Cache 设计Design Around KV-CacheKV-cache hit rate is THE single most important metric for production AI agents.KV-Cache 命中率是生产环境 AI Agent 最重要的单一指标。KV-Cache键值缓存是 LLM 推理中缓存历史注意力计算结果的机制其命中率直接决定成本与延迟。参考文档给出的关键数据输入/输出 token 比例约为100:1缓存 token 约$0.30/MTok未缓存 token 约$3/MTok存在10 倍成本差。由此推导出三条实现纪律保持 prompt 前缀稳定——哪怕单个 token 的变化也会使整个缓存失效系统提示词中不写时间戳——动态内容会破坏前缀稳定性上下文只做追加APPEND-ONLY并使用确定性序列化——保证重复请求产生字节级一致的前缀。仓库实现印证本仓库的 v3 模式正是围绕注入块必须 KV-Cache 稳定设计的。在 autonomous/gated 模式下进度注入不再使用原始的progress.md尾部而是由 scripts/ledger-summary.sh 合成一个摘要块——文档明确说明该摘要不含磁盘上的任何自由文本且块内不带时间戳因此从构造上就是 KV-Cache 稳定的。机器账本 scripts/ledger-append.sh 对应的.planning/id/ledger-agent.jsonl为追加式、每行一个 JSON 对象正是APPEND-ONLY 确定性序列化的直接体现。原则 2掩盖而非移除Mask, Dont Remove不要动态地从 Agent 的工具列表中移除工具——工具集的动态变化同样会破坏 KV-Cache 前缀。正确的做法是使用logit 屏蔽logit masking让模型在推理层看不到某些工具的 logits而不是改变工具列表本身。最佳实践为动作使用一致的前缀如browser_、shell_、file_便于统一屏蔽。前缀的命名空间既是给模型的语义提示也是给屏蔽机制masking提供可枚举的锚点。仓库实现印证本仓库的 SKILL.md frontmatter 中声明了allowed-tools: Read Write Edit Bash Glob Grep并在PreToolUse钩子上使用matcher: Write|Edit|Bash|Read|Glob|Grep只对匹配的工具注入规划上下文。这与用一致前缀约束工具面的思路一致钩子按固定集合匹配而不是随任务动态增删。原则 3文件系统即外部记忆Filesystem as External MemoryMarkdown is my working memory on disk.Markdown 就是我磁盘上的工作记忆。这是本仓库的灵魂公式Context Window RAM易失、有限 Filesystem Disk持久、无限任何重要的信息都必须落盘。更进一步压缩必须可还原Compression Must Be Restorable丢弃网页正文时保留 URL丢弃文档内容时保留文件路径永远不要丢失指向完整数据的指针。这意味着缩减上下文与保留信息并不矛盾上下文里可以只放引用reference但磁盘上必须保有可回溯的原始数据。仓库实现印证本仓库的全部机制都建立在这个公式之上。三件套规划文件task_plan.md、findings.md、progress.md就是 Agent 的磁盘记忆SKILL.md 中Core Pattern一节原样复刻了这个公式Context Window RAM (volatile, limited)Filesystem Disk (persistent, unlimited)→ Anything important gets written to disk.。同时findings.md被规定为外部不可信内容的唯一落脚点参考 SKILL.md 的 Security Boundary因为task_plan.md会被钩子自动读取注入未受信内容放在那里会在每次工具调用时被放大——这正是保留指针、隔离不可信负载的工程化。原则 4通过复述操纵注意力Manipulate Attention Through RecitationCreates and updates todo.md throughout tasks to push global plan into models recent attention span.在整个任务中持续创建并更新 todo.md把全局计划推进到模型最近的注意力区间。Transformer 的注意力天然偏向上下文的开头与结尾。问题大约 50 次工具调用之后模型会遗忘最初的目即lost in the middle效应。解决方案在每次重大决策前重新读取task_plan.md让目标重新出现在注意力窗口的末端Start of context: [原始目标 —— 很远已被遗忘] ...大量工具调用... End of context: [刚读入的 task_plan.md —— 获得注意力]仓库实现印证这就是本仓库 hook 注入机制的理论依据。SKILL.md 中的核心规则第 3 条Read Before Decide明确要求在做重大决策前读取计划文件让目标保持在注意力窗口内。工程层面hooks/hooks.json 与 skills/planning-with-files/SKILL.md frontmatter 注册了UserPromptSubmit回合开始注入完整计划头部与PreToolUse每次工具调用前注入计划头部两类生命周期钩子把复述从口头约定变成每回合自动执行scripts/skill-hook.sh 则是这套注入逻辑的独立入口。SKILL.md 中的5-Question Reboot Test我在哪、我要去哪、目标是什么、学到了什么、做了什么、下一步做什么也直接服务于注意力重置。原则 5把错误的东西留在上下文里Keep the Wrong Stuff InLeave the wrong turns in the context.把走错的路留在上下文里。为什么带堆栈跟踪的失败动作能让模型隐式更新信念belief知道什么不可行从而减少重复犯错错误恢复error recovery被认为是**真正的 Agent 化行为最清晰的信号之一**。这条原则与直觉相反——多数人会倾向于清空失败记录但 Manus 的经验是失败本身就是最珍贵的训练信号保留它比掩盖它更有价值。仓库实现印证SKILL.md 的Critical Rules第 5 条Log ALL Errors规定每个错误都必须写进计划文件并给出了标准错误表结构Error | Attempt | Resolution第 6 条Never Repeat Failures则给出伪代码if action_failed: next_action ! same_action要求追踪尝试历史、变更方法。此外本仓库的并行写入守护Parallel-write guardv3.10.0在检测到已完成的 phase 数量回退时会打印一条提示指明丢失了多少工作并指向git diff——它不阻塞、只是留痕正是保留错误痕迹供模型更新信念的又一个例证。原则 6不要被少样本范式固化Dont Get Few-ShottedUniformity breeds fragility.千篇一律孕育脆弱性。问题重复的动作-观察action-observation配对会导致模型漂移与幻觉——一旦成功路径高度同质模型就变成背诵而非推理。解决方案引入受控的变化controlled variation略微变化措辞不要盲目复制粘贴既有模式在重复性任务上主动重新校准recalibrate。仓库实现印证本仓库的PWF_INJECTsmart结构感知注入v3.8.0从注入内容本身规避了每次都注入相同头部的退化默认注入是位置无关的head -50/head -30而 smart 模式改为按结构挑选计划标题、Goal/Next Step/Current Phase、phase 数量、当前 in_progress 的完整 phase 段、最近 3 行 Decisions Made让注入内容随计划结构变化。SKILL.md 中Continue After Completion规则也要求任务扩展时新增 phasePhase 6、7…并追加 progress.md 会话条目——维持计划本身的动态性避免范式固化。二、3 大上下文工程策略参考文档基于 Lance Martin 对 Manus 架构的分析归纳出三种系统级策略。它们解决的是同一枚硬币的两面如何让进入上下文的更少缩减、更专隔离、更晚卸载。策略 1上下文缩减Context Reduction压缩Compaction——每个工具调用都有两种表示├── FULL: 原始工具内容存储在文件系统中 └── COMPACT: 仅引用 / 文件路径 规则 - 对较旧STALE的工具结果应用压缩 - 保留最近RECENT的结果为 FULL用于指导下一步决策摘要Summarization——当压缩达到收益递减diminishing returns时启用使用完整工具结果生成标准化摘要对象而不是在上下文里保留原始输出。这条策略把上下文窗口当作一个需要主动治理的稀缺资源老结果降级为指针指针本身满足原则 3 的可还原性新结果保持完整满足原则 4 的决策依赖最新信息。仓库实现印证本仓库没有把整个progress.md塞进上下文而是分层注入——legacy 模式注入原始progress.md尾部tail -20v3 模式则注入ledger-summary.sh合成的结构化摘要tick 数、phase 完成/总数、当前 in_progress 阶段标题、各 Agent 最近事件类型这就是原始结果落盘 上下文只放压缩表示的镜像实现。check-complete 工具scripts/check-complete.sh则用极小的输出ALL PHASES COMPLETE或剩余 phase 列表替代对整个计划的重复比对避免冗余。策略 2上下文隔离Context Isolation多 Agent 架构架构图引用自参考文档┌─────────────────────────────────┐ │ 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 调用执行子代理的架构。每个执行子代理拥有自己的上下文窗口规划者负责任务拆分知识管理者负责把对话中的发现沉淀到文件系统。仓库实现印证这正是本仓库并行任务工作流与单一计划所有者规则的出处。SKILL.md 规定并行任务时每个任务用scripts/init-session.sh Task Name生成独立计划目录.planning/YYYY-MM-DD-slug/并通过PLAN_ID环境变量把每个 Agent 主机钉在自己的计划上多个 Agent 协作同一任务时只保留一个编排者orchestrator作为task_plan.md的所有者worker 通过各自的 ledger 或指定文件汇报不得并发改写共享计划文件参考 SKILL.md 与 templates/task_plan_autonomous.md。PLAN_ID绑定语义还体现在 scripts/resolve-plan-dir.sh 中设置了$PLAN_ID就必须解析到该计划否则停止解析而不是落到别的计划issue #237 的教训。策略 3上下文卸载Context Offloading工具设计的五个要点总共使用少于 20 个原子函数atomic functions完整结果存储在文件系统中而非上下文里使用glob和grep进行搜索而不是把整个文件树读进上下文渐进式披露Progressive disclosure只在需要时加载信息。这实际上是一套最小工具面 按需加载的设计哲学工具数量少则前缀稳定呼应原则 1结果落盘则上下文干净呼应原则 3搜索而非读取则成本可控。仓库实现印证SKILL.md 声明了allowed-tools: Read Write Edit Bash Glob Grep——恰好是 6 个原子能力且把Glob/Grep作为检索手段。渐进式披露体现在注入策略上legacy 默认注入是head -50回合开始与head -30每次工具调用的计划头部v3 的inject-smart进一步只挑当前真正相关的结构段当前 in_progress 阶段、Next Step、最近决策晚加载、少加载把 token 花在刀刃上。三、The Agent Loop7 步执行循环Manus 在一个持续的 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 │ └─────────────────────────────────────────┘值得注意的细节第 2 步THINK的第一个问题是Should I update the plan?——计划更新是循环的内建动作而非额外负担第 1 步要求Review recent observations与原则 5保留失败记录直接衔接第 7 步DELIVER OUTCOME要求附带所有相关文件呼应文件是交付物的理念。仓库实现印证本仓库把计划更新这个内建动作自动化了。PostToolUse钩子在每次写操作后注入Update progress.md with what you just did. If a phase is now complete, update task_plan.md status.提醒见 scripts/skill-hook.shStop钩子则接入完成门控gate-stop——但注意门控只在 gated 模式、存在 in_progress 阶段且满足 5 项条件时才会请求继续见下文的Gate decision table这保证了第 7 步交付前计划必须是完整的。此外templates/loop.md 提供了规划感知的循环 tick 模板每个 tick 重读三个规划文件、运行 check-complete、在无进展时追加 progress.md 条目把第 6 步ITERATE变成可由/loop驱动的持续进程。四、Manus 创建的文件类型三件套 代码文件参考文档给出了 Manus 在任务中创建的完整文件清单FilePurposeWhen CreatedWhen Updatedtask_plan.mdPhase tracking, progress阶段跟踪、进度Task start任务开始After completing phases完成阶段后findings.mdDiscoveries, decisions发现、决策After ANY discovery任何发现后After viewing images/PDFs查看图片/PDF 后progress.mdSession log, whats done会话日志、已完成事项At breakpoints断点处Throughout session整个会话中Code filesImplementation实现代码Before execution执行前After errors出错后仓库实现印证本仓库完整继承了这套三件套并在 SKILL.md 中细化了更新时机——task_plan.md每个阶段后更新、findings.md任何发现后更新、progress.md贯穿会话更新。同时提供了可直接复制的模板templates/task_plan.md阶段跟踪、templates/findings.md研究存储、templates/progress.md会话日志以及针对长任务的强化版 templates/task_plan_autonomous.md含 Runtime Behavior、Next Step、Current Phase、Phase 状态机pending → in_progress → complete、Decisions Made 与 Errors Encountered 表格。初始化命令 scripts/init-session.sh 会一次性创建这三件套legacy 模式写在项目根目录slug 模式写在.planning/date-slug/下并输出PLAN_ID。五、关键约束Critical Constraints参考文档记录了 Manus 的 5 条硬约束其中第一条在 2026 年有明确更新单动作执行Manus 2025 原始约束每回合只允许一次工具调用、禁止并行执行。2026 更新现代宿主Claude Code、Codex CLI已支持并行工具调用与子代理因此该约束按字面已不再适用协调点不再是一回合一次调用而是磁盘上持久化的 Markdown 计划文件——并行调用与子代理都通过它共享状态。本仓库正是围绕这一更新后的协调点设计的PLAN_ID与PWF_PLAN_ROOT把并发会话钉到同一份计划。计划必需Plan is RequiredAgent 必须始终知道目标、当前阶段、剩余阶段。对应 SKILL.md 的5-Question Reboot Test与task_plan.md中的 Goal / Current Phase / Phases 结构。文件即记忆Files are Memory上下文易失、文件系统持久。对应原则 3。绝不重复失败Never Repeat Failures若动作失败下一个动作必须不同。对应 SKILL.md 的3-Strike Error Protocol第 1 次诊断修复、第 2 次换方法换工具、第 3 次质疑假设并考虑更新计划3 次失败后升级给用户。沟通是一种工具Communication is a Tool消息类型info进度、ask阻塞、result终结。对应 PostToolUse 钩子的进度提醒与 gated 模式的阻塞请求。六、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.七、从原则到工程本仓库的落地机制速览把上面的原则映射到本仓库的实现面可以得到一张完整的对应表Manus 原则/策略planning-with-files 落地机制关键文件原则 1KV-Cache 稳定ledger 摘要注入、块内无时间戳、追加式 jsonl 账本scripts/ledger-summary.sh、scripts/ledger-append.sh原则 2掩盖而非移除固定 allowed-tools PreToolUse matcherskills/planning-with-files/SKILL.md原则 3文件系统即记忆task_plan/findings/progress 三件套 模板 初始化scripts/init-session.sh、templates原则 4复述操纵注意力UserPromptSubmit / PreToolUse 每回合注入计划头部hooks/hooks.json、scripts/inject-plan.sh、scripts/skill-hook.sh原则 5保留错误痕迹Errors 表强制记录 并行写入守护留痕skills/planning-with-files/SKILL.md原则 6避免范式固化inject-smart 结构感知注入、阶段动态扩展scripts/inject-plan.sh策略 1上下文缩减tail 注入 → ledger 摘要、check-complete 轻量判定scripts/check-complete.sh策略 2上下文隔离并行任务 PLAN_ID 钉扎、单一计划所有者scripts/resolve-plan-dir.sh策略 3上下文卸载6 原子工具、Glob/Grep 检索、渐进注入skills/planning-with-files/SKILL.md两条值得单独说明的加固机制哈希背书Attestationv2.37.0[scripts/attest-plan.sh](https://link.gitcode.com/i/afb993ce117fb8bc6c91f3aece6a58ff)对task_plan.md计算 SHA-256 存入.planning/id/.attestation或 legacy 的./.plan-attestation此后每次注入时钩子重算哈希并比对不一致则拒绝注入并给出[PLAN TAMPERED]警告。这直接守护原则 3 的文件即记忆——记忆被篡改时系统必须知情。对应测试见 tests/test_plan_attestation.py。完成门控Gated Modev3gate 是终止判定器termination oracle它判定磁盘上的计划工件而非对话转写——因为转写可被模型幻觉而计划状态机不可。gate 仅在同时满足 5 个条件时才会请求继续存在 gated 模式标记、存在 in_progress 阶段、非 forced continuation、阻塞次数未达上限、账本有进展且按宿主能力分级执行Claude Code/Codex 为硬阻塞、Cursor/Pi/Kiro 为 follow-up 注入、Gemini 等仅通知。对应测试见 tests/test_gate.py 与 tests/test_phase_status_locking.py。实操10 秒上手# 1. 初始化一个命名计划slug 模式适合并行任务 sh scripts/init-session.sh Backend Refactor # 输出类似 PLAN_ID2026-09-10-backend-refactor # 2. 把当前终端钉到该计划hooks 只认这份计划 export PLAN_ID2026-09-10-backend-refactor # 3. 之后每个回合 hooks 会自动注入计划上下文 # 阶段完成时把 task_plan.md 中的 **Status:** 从 in_progress 改为 complete # 并同步刷新 ## Next Step # 4. 校验所有阶段是否完成 sh scripts/check-complete.sh # 5. 可选v3 模式低复述 默认背书 账本摘要 sh scripts/init-session.sh --autonomous Long Research Run # 或加上完成门控 sh scripts/init-session.sh --gated Build Pipeline结语原则是为什么文件是怎么做Manus 上下文工程原则的价值不在于口号而在于它把三个反直觉的事实固定成了可执行的纪律上下文是稀缺且易失的所以围绕 KV-Cache 设计、把记忆放磁盘注意力是可以被操纵的所以每回合复述计划失败是必须保留的所以记录错误、变更方法。本仓库的 reference.md 是这份纪律的理论纲要而 SKILL.md、hooks、scripts 与 templates 则是它的工程化身。理解原则你便知道 Agent 为何需要三件套规划文件掌握本仓库你便拥有了在任何支持 hooks 的宿主Claude Code、Codex、Cursor、OpenCode 等 60 Agent上让这套原则自动运转的工具链。【免费下载链接】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），仅供参考