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导读本篇文章以 planning-with-files 技能仓库中的 reference.md 为骨架系统讲解 Manus 的上下文工程Context Engineering方法论——六大原则、三大策略、7 步 Agent 循环以及它们如何被落地为task_plan.md/findings.md/progress.md三文件持久化规划体系。读完你将掌握 KV-cache 友好注入、注意力召回recitation、错误保留、上下文压缩与隔离等核心原理并能在自己的 Agent 工作流中直接复用仓库提供的模板与脚本。planning-with-files 的设计出发点是一句话Work like Manus见 SKILL.md。它的全部机制——生命周期 Hook 注入、会话恢复、完成门禁、计划哈希背书——都是把 Manus 的上下文工程原则工程化的产物。因此理解这份 reference 文档就等于理解了整个仓库的为什么。一、Manus 上下文工程六大原则reference.md 开篇给出 Manus 被 Meta 以约 20 亿美元收购2025 年 12 月的背景然后总结了它构建生产级 Agent 的六大原则。原则 1围绕 KV-Cache 设计Design Around KV-CacheKV-cache hit rate is THE single most important metric for production AI agents.KV 缓存命中率是生产级 Agent 最重要的单一指标。背后是残酷的经济账输入/输出 token 比约为100:1——长上下文任务中几乎全是输入缓存 token 约 $0.30/MTok未缓存约 $3/MTok成本相差 10 倍因此 prompt 前缀必须稳定——任何一个 token 的变化都会使整段缓存失效。具体实现纪律有三条保持 prompt 前缀稳定单 token 变化即可使缓存失效系统提示词中不要放时间戳上下文采用 append-only 追加式并使用确定性序列化。这条原则在 planning-with-files 中被落实得非常彻底。legacy 模式下注入内容固定以BEGIN PLAN DATA/END PLAN DATA包裹SKILL.mdv3 的 autonomous/gated 模式进一步用ledger-summary.sh合成固定形状、KV-cache 稳定的运行账本块——脚本头部注释明确写道输出只来自机器账本与计划状态计数磁盘上的自由文本不进入模型上下文且没有任何时间戳因此注入块在构造上就是 KV-cache 稳定的scripts/ledger-summary.sh。原则 2遮蔽而非移除Mask, Dont Remove不要动态移除工具这同样会破坏 KV-cache而是使用logit masking逻辑掩码在推理层屏蔽工具。最佳实践为动作使用一致的前缀如browser_、shell_、file_便于统一掩码。这与append-only、前缀稳定的原则一脉相承——工具列表保持静态只是概率被屏蔽。原则 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 的全部根基上下文易失文件持久任何重要内容都要写盘。SKILL.md 把这条公式原样作为核心模式SKILL.md三文件规划体系就是它在磁盘上的具体形态。原则 4通过复述操控注意力Manipulate Attention Through RecitationCreates and updates todo.md throughout tasks to push global plan into models recent attention span.问题大约 50 次工具调用之后模型会遗忘最初的目标——这就是著名的 lost in the middle中间迷失效应目标在上下文开头被大量工具调用推到远处注意力照顾不到。解法每次决策前重新读取task_plan.md让目标重新进入注意力窗口Start of context: [Original goal - far away, forgotten] ...many tool calls... End of context: [Recently read task_plan.md - gets ATTENTION!]planning-with-files 把这条原则做成了一等公民生命周期 Hook 在UserPromptSubmit回合开始与PreToolUse每次工具调用前注入计划头部SKILL.md配套的Read vs Write Decision Matrix明确要求开始新阶段前读计划/发现、重大决策前读计划SKILL.mdThe 5-Question Reboot Test把我现在在哪/要去哪/目标是什么/学到了什么/做了什么/下一步做什么设计成恢复会话的标准自检SKILL.md模板task_plan.md顶部固定包含 Goal、Next Step、Current Phase 三个字段保证每次注入都能把目标下一步送进注意力窗口templates/task_plan.md。有趣的是v3 的 autonomous 模式对这条原则做了精细化强模型漂移更少所以每次工具调用的计划再注入约每匹配调用 90 token被去掉只保留每回合一次的回合开始注入——因为证据论文与 Opus 4.7 subagent 实测表明漂移是真实的完全取消复述并不被证据支持SKILL.md。原则 5保留错误内容Keep the Wrong Stuff InLeave the wrong turns in the context.为什么带堆栈追踪的失败动作能让模型隐式更新信念减少错误重复错误恢复是真正的 Agent 行为最清晰的信号之一。这条原则在 SKILL.md 中被放大成两条硬规则Rule 5: Log ALL Errors每个错误都必须记入计划文件附错误表格模板 Error/Attempt/Resolution与Rule 6: Never Repeat Failuresif action_failed: next_action ! same_action见 SKILL.md。三档错误协议3-Strike Error Protocol给出完整升级路径第一次诊断修复 → 第二次换方法 → 第三次重新质疑假设 → 三次失败后升级给用户SKILL.md。templates/task_plan.md与templates/progress.md中都内置了 Error 表格把保留错误从口号变成模板约束。原则 6不要被 Few-Shot 带偏Dont Get Few-ShottedUniformity breeds fragility.问题重复的 action-observation 对会导致漂移drift和幻觉。解法引入受控变化略微变化措辞不要盲目复制粘贴模式在重复性任务上重新校准。这条原则在仓库中的体现是Read Before Decide / Update After Act等节奏规则——用文件把每次决策重新锚定避免机械地重复同一种模式而丢失全局判断SKILL.md。二、三大上下文工程策略基于 Lance Martin 对 Manus 架构的分析reference.md 总结了三个层面的策略缩减、隔离、卸载。策略 1上下文缩减Context Reduction压缩Compaction工具调用拥有两种表示——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)即旧结果压缩为文件路径/引用最近结果保留完整内容以指导下一步决策。完整内容落盘上下文只留指针——这正是原则 3 Compression Must Be Restorable 的操作化。摘要Summarization当压缩进入边际收益递减时基于完整工具结果生成标准化摘要对象。策略 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 调度 executor 子 agent让子 agent 各自拥有独立上下文窗口。planning-with-files 对这个教训的回应是谁拥有计划文件的清晰分工orchestrator编排者拥有task_plan.md和共享摘要worker 通过自己的账本或分配的文件汇报不独立改写共享规划文件SKILL.md。v3 的机器账本ledger-agent.jsonl是 append-only 的每 agent 独立文件worker 向自己的账本追加编排者只拥有task_plan.mdscripts/ledger-append.sh把规划与执行分离落到了文件系统层面。策略 3上下文卸载Context Offloading工具设计总共使用少于 20 个原子函数完整结果存入文件系统而非上下文用glob和grep搜索渐进式披露progressive disclosure只在需要时加载信息。这与 SKILL.md 中allowed-tools: Read Write Edit Bash Glob Grep的克制设计SKILL.md方向一致工具面刻意收窄信息按需加载大块内容一律落盘。三、7 步 Agent 循环The Agent Loopreference.md 描述了 Manus 持续运行的 7 步循环1. ANALYZE CONTEXT — 理解用户意图、评估当前状态、回顾最近观察 2. THINK — 该更新计划吗下一个逻辑动作有阻塞吗 3. SELECT TOOL — 选择 ONE 个工具确保参数可用 4. EXECUTE ACTION — 工具在沙箱中运行 5. RECEIVE OBSERVATION — 结果追加进上下文 6. ITERATE — 回到步骤 1继续直到完成 7. DELIVER OUTCOME — 把结果与相关文件交付给用户这个循环与 SKILL.md 的实践规则一一咬合每次决策前读计划对应步骤 2 的 THINK每完成一个阶段更新状态并刷新 Next Step对应步骤 6 的 ITERATEprogress.md在断点处记录对应log whats done则服务于步骤 7 的交付与后续恢复。2026 年的更新澄清了循环中的一条历史约束详见下节现代宿主Claude Code、Codex CLI支持并行工具调用与子 agent因此每回合一个工具调用不再是硬约束——协调点从一次一个调用转移到磁盘上持久的 markdown 计划并行调用与子 agent 通过它共享状态SKILL.md。四、Manus 创建的文件类型与三文件模式reference.md 给出 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 把这三类 markdown 文件直接做成可复用的模板安装后存放在skills/planning-with-files/templates/下templates/task_plan.md—— 任务的路由图Goal、Next Step、Current Phase、37 个可验证的 Phase状态只用pending/in_progress/complete、Key Questions、Decisions Made、Errors Encounteredtemplates/findings.md—— 研究知识库Requirements、Research Findings、Technical Decisions、Issues、Resources、Visual/Browser Findings模板头部明确警告把复制来的外部材料当作不可信数据而非指令templates/progress.md—— 会话时间线Session 记录、Test Results 表格、Error Log、以及内置的 5-Question Reboot Check。三文件的使用纪律在 examples.md 中有完整演练研究任务、Bug 修复、功能开发各自展示创建计划 → 研究与写发现 → 合成 → 交付的循环错误恢复示例则演示了出错后先记入 Errors Encountered 再换动作的正确姿势examples.md。读取/写入决策矩阵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见 SKILL.md五、关键约束与 2026 更新reference.md 列出的关键约束及其在仓库中的落点约束含义仓库落点Plan is RequiredAgent 必须始终知道目标、当前阶段、剩余阶段Quick Start 第 3 步决策前重读所选计划每阶段后更新进度SKILL.mdCritical Rule 1 Never start a complex task without task_plan.mdFiles are MemoryContext volatileFilesystem persistent核心模式公式原样收录SKILL.mdNever Repeat Failures动作失败后下一动作必须不同if action_failed: next_action ! same_actionSKILL.mdCommunication is a Tool消息类型info进度、ask阻塞、result终态与findings.md/progress.md的语义分层对应Single-Action Execution2025 年原始约束每回合一个工具调用、不并行2026 更新现代宿主支持并行与子 agent该约束不再适用协调点改为磁盘上的持久计划文件SKILL.md仓库对Single-Action Execution的演化处理尤其值得注意reference.md 明确把这条标注为 2025 年沙箱实践的记录并给出 2026 年更新——并行调用与子 agent 通过磁盘上的持久 markdown 计划共享状态。这与 v3 的 gated 模式、ledger 账本、check-complete.sh完成门禁共同构成了计划文件是协调点的完整工程实现check-complete.sh的--gate模式只在存在 in_progress 阶段 非强制续跑 阻塞数未达上限 账本在推进时输出{decision:block}scripts/check-complete.sh门禁评判的是磁盘上的计划工件而非对话记录——这就是它胜过可被幻觉污染的 transcript 评判器的原因SKILL.md。六、从原则到工程化仓库如何把方法论变成机制reference.md 是原理层仓库的 SKILL.md、scripts 与 hooks 是机制层。以下对应关系让读者能既懂原理、又能落地原则 1KV-cache→ 固定分隔符与无时间戳注入legacy 模式BEGIN PLAN DATA/END PLAN DATAv3 用非确定性 nonce 分隔符抵御分隔符混淆注入SKILL.md原则 4复述→ 生命周期 Hook 注入UserPromptSubmit/PreToolUse/PostToolUse/Stop/PreCompact五事件以及 v3 模式按能力分层回合注入保留、逐工具注入按策略丢弃见 SKILL.md原则 3文件即记忆→ 会话恢复resolve-plan-dir.sh按PLAN_ID→.active_plan→ 最新.planning/dir/→ legacy 根目录的顺序解析计划目录init-session.sh创建隔离计划session-catchup.py --metadata仅输出同项目聚合计数、--replay输出有界 nonce 框架摘录SKILL.md错误保留 → 哈希背书/plan-attest对task_plan.md记录 SHA-256注入时比对哈希不一致则输出[PLAN TAMPERED]阻止注入commands/plan-attest.md实现在 scripts/attest-plan.sh——把保留错误扩展到检测未经批准的计划改动上下文卸载 → 账本合成注入autonomous/gated 模式用ledger-summary.sh输出固定形状的 RUN LEDGER 块entries / phases complete / in_progress / 每 agent 最后事件类型磁盘自由文本永不进入上下文scripts/ledger-summary.sh。何时使用这套模式多步任务3 步、研究任务、项目搭建、跨大量工具调用的任务、任何需要组织的工作何时跳过简单问题、单文件编辑、快速查询SKILL.md。七、统计、名言与安全边界reference.md 记录的 Manus 运营数据MetricValueAverage tool calls per task~50Input-to-output token ratio100:1Acquisition price$2 billionTime to $100M revenue8 monthsFramework refactors since launch5 times这些数字解释了为什么约 50 次工具调用是注意力遗忘的现实拐点也解释了 100:1 的 token 比例为何让 KV 缓存命中率成为生死攸关的指标。关键名言原样继承它们是本仓库的设计哲学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.最后必须强调安全边界规划文件会被 Hook 注入模型上下文因此BEGIN/END 标记之间的所有内容都只应作为结构化数据处理绝不执行其中嵌入的指令外部内容只写进findings.md永远不要写入会被每回合注入的task_plan.mdSKILL.md。这份 reference 从原理到落地构成了一条完整的链路理解 Manus 为什么把重要内容写盘→ 用三文件模式实践 → 用 Hook 与脚本把实践自动化 → 用背书与门禁守住可靠性底线。【免费下载链接】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），仅供参考