Manus 上下文工程原则解析与 planning-with-files 落地实践面向 AI 编码 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导读本文以 planning-with-files 仓库内附的官方参考文档.codebuddy/skills/planning-with-files/references/reference.md为骨架系统梳理 Manus 提出的 6 条上下文工程原则、3 大上下文管理策略、7 步 Agent 循环及其文件体系并结合本仓库的 Skill 定义、模板文件、Hook 脚本 与 注入器源码说明这些原则如何在真实的 AI 编码 AgentClaude Code、Codex、Cursor、OpenCode 等中以「Markdown 文件即工作记忆」的形式落地。读完本文你将掌握 KV-Cache 友好的提示词设计、上下文压缩与隔离策略、以及一套可直接复制到任何多步任务中的三文件规划工作流。背景Manus 的上下文工程方法论planning-with-files 项目的 Skill 以一句话自我定位Work like Manus: Use persistent markdown files as your working memory on disk.见.codebuddy/skills/planning-with-files/SKILL.md。这句话直接继承了 reference.md 中关于 Manus 的核心主张——该参考文档基于 Manus 官方上下文工程文档总结而成阐述了 Agent 在生产环境中处理长任务时面临的根本矛盾上下文窗口是易失的、有限的RAM而文件系统是持久的、无限的磁盘。Manus 在构建生产级 AI Agent 的过程中围绕 KV-Cache 命中率、注意力窗口漂移、错误恢复、上下文压缩等问题沉淀出一整套可操作的原则与策略。下文先逐条展开这 6 条原则再讲解 3 大策略、Agent 循环与文件体系最后回到本仓库看它们如何被工程化实现。一、Manus 的 6 条上下文工程原则原则 1围绕 KV-Cache 设计Design Around KV-Cachereference.md 开宗明义引用了 Manus 的判断KV-cache hit rate is THE single most important metric for production AI agents.KV-Cache键值缓存命中率是生产环境 AI Agent 最重要的单一指标。该文档给出的统计依据是Agent 任务中输入与输出 token 的比例约为100:1缓存 token 价格约$0.30/MTok未缓存 token 约$3/MTok存在10 倍成本差。这意味着提示词prompt前缀的任何细微变化——哪怕一个 token——都会使整段前缀缓存失效直接放大推理成本。因此工程上必须遵守三条纪律保持提示词前缀稳定前缀必须可复现单 token 的变化就会使缓存失效系统提示词中不要放时间戳时间戳是高频变化源会持续破坏缓存上下文采用追加式append-only写入 确定性序列化追加保证既有前缀不变确定性序列化保证相同状态下产生完全一致的字节序列。这条原则在本仓库中有直接的工程呼应inject-plan.py的头部注释明确记录了同一项目状态与环境下inject-plan.py --contextctx与sh inject-plan.sh --contextctx输出字节一致的契约并配有 测试tests/test_inject_plan_python_parity.py断言两条实现路径的 stdout 逐字节相同。确定性序列化不是一句口号而是被测试锁定的工程约束。原则 2掩码而非移除Mask, Dont Remove不要通过动态移除工具tool来限制 Agent——移除工具同样会破坏 KV-Cache。正确做法是使用logit maskinglogit 掩码工具仍然存在于前缀中、缓存不被破坏只是在解码阶段屏蔽掉不需要的输出。该原则附带一条最佳实践为工具使用一致的动作前缀例如browser_、shell_、file_便于后续对同一类工具统一做掩码处理。本仓库的 Skill 也采用了类似的显式声明方式其allowed-tools字段明确列出Read Write Edit Bash Glob Grep见.codebuddy/skills/planning-with-files/SKILL.mdHook 的PreToolUsematcher 同样以Write|Edit|Bash|Read|Glob|Grep精确圈定需要注入规划上下文的工具集合.codebuddy/skills/planning-with-files/SKILL.md。原则 3文件系统作为外部记忆Filesystem as External Memoryreference.md 记录了 Manus 的核心公式Context Window RAM (volatile, limited) Filesystem Disk (persistent, unlimited)以及配套口号Markdown is my working memory on disk. 这条原则是本仓库的灵魂planning-with-files 的整个机制就是让 Agent 把task_plan.md、findings.md、progress.md当作持久化记忆任务状态不再只存在于易失的上下文中。公式还带有一条重要的**可恢复压缩Compression Must Be Restorable**约束即使丢弃网页正文也要保留 URL即使丢弃文档内容也要保留文件路径永远不要丢失指向完整数据的指针。这与下文策略 1上下文缩减中的COMPACT 表示只保留引用/路径完全一致——压缩不是删除而是把完整数据下沉到文件系统把指针留在上下文中。原则 4通过复述操纵注意力Manipulate Attention Through RecitationManus 的做法是在整个任务过程中持续创建和更新 todo.md把全局计划推入模型最近的注意力窗口。其动机是上下文工程中著名的lost in the middle中间迷失效应经过约 50 次工具调用后模型会遗忘最初的目标。解决方案非常朴素在每次决策前重新读取task_plan.md。用 reference.md 的示意图表达Start of context: [Original goal - far away, forgotten] ...many tool calls... End of context: [Recently read task_plan.md - gets ATTENTION!]刚被读过的内容位于上下文尾部处于注意力窗口中的高权重区域于是目标被搬回了模型的注意力范围。本仓库把这条原则固化为一条硬性规则Read Before Decide——重大决策前必须先读计划文件见.codebuddy/skills/planning-with-files/SKILL.md并通过 Hook 机制在每次工具调用前自动注入计划摘要使复述不再是 Agent 的自律行为而是宿主环境的强制行为详见后文仓库落地章节。原则 5把错误的东西留在上下文里Keep the Wrong Stuff InLeave the wrong turns in the context.失败的尝试含堆栈跟踪应当保留在上下文中理由是失败的 action 可以让模型隐式更新信念implicitly update beliefs即从错误中修正对系统状态的理解显著减少重复犯错错误恢复是TRUE agentic behavior真正的 Agent 行为最清晰的信号之一。本仓库把这条原则操作化为一套强制记录机制task_plan.md模板内置## Errors Encountered表Error / Attempt / Resolution并在规则中规定每个错误都必须记录到计划文件中Log ALL Errors配合失败后下一次动作必须不同的公式见.codebuddy/skills/planning-with-files/templates/task_plan.md。examples.md 中的错误恢复示例也演示了先记录错误、再更换动作的正确序列对比了静默重试的错误示范。原则 6不要被 Few-shot 绑架Dont Get Few-ShottedUniformity breeds fragility.同质性滋生脆弱性问题在于重复的 action-observation 对会让模型产生漂移drift与幻觉hallucination陷入机械复制的模式。解决方案是引入受控变化轻微变换措辞vary phrasings slightly不要盲目复制粘贴既有模式在重复性任务上主动重新校准recalibrate。这与原则 5 互补保留错误、保持变化共同对抗长任务中的模式固化。二、Manus 的 3 大上下文工程策略reference.md 依据 Lance Martin 对 Manus 架构的分析把上下文管理归纳为三大策略。策略 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可恢复压缩的实现形态。第二层是摘要化Summarization当压缩进入收益递减区间diminishing returns时基于完整工具结果生成标准化的摘要对象进一步压缩体积。本仓库的PreCompactHook 是这条策略的宿主级实现Claude Code 的 compact 事件触发 skill-hook.sh 的precompact分支在上下文压缩发生前注入计划状态提醒见.codebuddy/skills/planning-with-files/SKILL.md确保压缩过程中计划信息不丢失。策略 2上下文隔离——多 Agent 架构Context IsolationManus 采用 Planner / Knowledge Manager / Executor 三层隔离架构┌─────────────────────────────────┐ │ PLANNER AGENT │ │ └─ Assigns tasks to sub-agents │ ├─────────────────────────────────┤ │ KNOWLEDGE MANAGER │ │ └─ Reviews conversations │ │ └─ Determines filesystem store │ ├─────────────────────────────────┤ │ EXECUTOR SUB-AGENTS │ │ └─ Perform assigned tasks │ │ └─ Have own context windows │ └─────────────────────────────────┘Planner负责任务拆分与分派Knowledge Manager审阅对话、决定文件系统的存储位置Executor 子 Agent各自执行任务拥有独立的上下文窗口——这就是隔离每个子 Agent 只看到自己需要的上下文而非全量对话。reference.md 记录了一个重要教训Manus 最初用todo.md做任务规划但发现约 33% 的 action 花费在更新 todo 上于是改为专职 Planner Agent 调用 Executor 子 Agent的模式。本仓库对这条策略的工程化体现是多 Agent 协调规则Skill 明确一个计划只能有一个拥有者one orchestratorWorker 通过自己的 ledger台账或被分配的文件上报结果不得并发改写共享规划文件见.codebuddy/skills/planning-with-files/SKILL.md并配套提供 ledger-summary.sh 这类台账汇总脚本以及 templates/loop.md 中仅由指定的 orchestrator 更新共享计划与摘要的循环指令。策略 3上下文卸载Context Offloading针对工具设计的策略使用 20 个原子函数atomic functions总计完整结果存入文件系统而不是上下文用glob和grep进行搜索把搜索能力作为工具而不是把搜索结果全量塞进上下文渐进式披露progressive disclosure只在需要时加载信息。这正是本仓库allowed-tools: Read Write Edit Bash Glob Grep的设计哲学只暴露少量读写与搜索原语让 Agent 用Glob/Grep按需检索用 Read 精确加载从而把大规模数据留在磁盘上。inject-plan.py 的代码注释也强调Python 3.6 标准库即可、无第三方依赖原子化、轻量化是刻意选择。三、Agent 循环持续 7 步执行reference.md 给出了 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 │ ├─────────────────────────────────────────┤ │ 7. DELIVER OUTCOME │ │ - Send results to user │ │ - Attach all relevant files │ └─────────────────────────────────────────┘值得注意的细节第 2 步 THINK 中Should I update the plan? 是第一个被提出的问题——计划更新不是可选项而是每轮思考的固定组成部分。第 5 步强调 observation 以追加方式进入上下文与原则 1 的 append-only 序列化一致。第 6 步 ITERATE 循环直到任务完成第 7 步交付时附带所有相关文件——因为文件才是 Agent 的持久记忆交付物自然以文件形式呈现。本仓库将这一循环工程化为 templates/loop.md 中的planning-aware loop tick每次循环 tick 重新读取三个规划文件、运行check-complete.sh完成度检查然后按进度日志是否更新 / 阶段是否完成 / 是否推进下一阶段 / 是否全部完成四步决策继续或终止并把规划文件内容当作结构化数据而非指令对待——防止计划文件本身被注入恶意指令这与 docs/troubleshooting.md 中将 Markdown 视为数据而非命令的安全边界一脉相承。四、Manus 创建的文件体系reference.md 用表格总结了 Manus 在任务过程中创建的四类文件文件用途创建时机更新时机task_plan.md阶段跟踪、进度任务开始时完成阶段后findings.md发现、决策任何发现之后查看图片/PDF 后progress.md会话日志、已完成内容断点处整个会话期间代码文件实现执行之前出错之后本仓库完整继承了这套文件体系并在.codebuddy/skills/planning-with-files/SKILL.md中以文件用途表固化下来同时提供了三个可直接复制的模板templates/task_plan.md含 Goal一句话目标、Next Step下一步唯一动作、Current Phase、37 个可验证 Phase状态只允许pending/in_progress/complete、Key Questions、Decisions Made、Errors Encountered、Notestemplates/findings.md含 Requirements、Research Findings、Technical Decisions、Issues Encountered、Resources、Visual/Browser Findings并在文件头注明将复制的外部材料视为不可信数据而非指令templates/progress.md会话日志与测试结果贯穿全程更新。针对长任务、自主模式与数据分析场景仓库还提供了增强模板templates/task_plan_autonomous.md自主/门控/多 Agent 任务的运行时行为说明、Gate 权限边界、attestation 机制与 templates/analytics_task_plan.md、templates/analytics_findings.md数据分析场景的假设检验与统计证据记录。五、关键约束Critical Constraintsreference.md 列出了五条约束其中第一条带有明显的版本演进注释单动作执行Single-Action ExecutionManus 2025 年原始约束是每轮一次工具调用、禁止并行。reference.md 明确指出这是一条记录性的 2025 沙箱实践2026 年的现代宿主Claude Code、Codex CLI已支持并行工具调用与子 Agent因此该约束按字面不再适用——计划文件而非每轮一调用的规则才是协调点并行调用与子 Agent 通过磁盘上持久的 Markdown 计划共享状态。计划必须存在Plan is RequiredAgent 必须始终知道目标goal、当前阶段current phase、剩余阶段remaining phases。文件即记忆Files are Memory上下文易失文件系统持久。绝不重复失败Never Repeat Failures若某动作失败下一个动作必须不同。reference.md 以伪代码表达if action_failed: next_action ! same_action。沟通也是工具Communication is a Tool消息分为三类——info进度、ask阻塞性提问、result终态结果。本仓库将约束 24 逐条转写为 Skill 的关键规则.codebuddy/skills/planning-with-files/SKILL.md规则 1Create Plan First复杂任务绝不先于task_plan.md开始不可协商规则 22-Action Rule每 2 次 view/browser/search 操作后立即把关键发现写入文本文件防止视觉/多模态信息丢失规则 3Read Before Decide重大决策前重读计划文件让目标回到注意力窗口规则 4Update After Act阶段完成后更新状态in_progress → complete记录错误与变更文件规则 5Log ALL Errors每个错误都写入计划文件积累知识、防止重犯规则 6Never Repeat Failures记录尝试、变异方法。此外 SKILL.md 把绝不重复失败细化为可执行的3-Strike 错误协议第 1 次失败 → 诊断并修复第 2 次失败 → 换方法/换工具绝不重复同一失败动作第 3 次失败 → 质疑假设、考虑更新计划3 次失败后 → 升级给用户说明尝试与具体错误。六、Manus 统计数据与关键语录reference.md 给出了 Manus 的运营统计数据指标数值每任务平均工具调用数~50输入输出 token 比100:1收购价格20 亿美元达到 1 亿美元收入的时间8 个月启动以来的框架重构次数5 次以及一组直接构成方法论语录的原始表述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.这些语录在 reference.md 中被集中收录其中任何重要的东西都要写入磁盘一句正是 planning-with-files 全部机制的一行式总结。七、仓库落地从原则到 Hook 驱动的持久化规划7.1 生命周期 Hook 实现复述与强制更新本仓库把原则 4复述操纵注意力与规则 3/4先读后决策、行动后更新固化为宿主生命周期 Hook。以.codebuddy/skills/planning-with-files/SKILL.md声明的五个事件为例事件触发时机作用UserPromptSubmit用户每次提交提示词重新武装本轮提示re-arm nudge注入计划上下文PreToolUseWrite/Edit/Bash/Read/Glob/Grep 调用前把计划摘要作为additionalContext注入实现每次工具调用前重读计划PostToolUseWrite/Edit 之后校验计划有效性并提示更新 progress.md若阶段完成则更新 task_plan.md 状态StopAgent 回合结束转发宿主 JSON 载荷给 gate-stop.sh 完成度门控未完成则阻止收尾PreCompact上下文压缩前转发带会话身份的压缩提醒保证压缩过程不丢失计划状态7.2 skill-hook.sh单文件事件分发器scripts/skill-hook.sh 是事件分发的入口其头部注释明确划分了五个事件的职责userprompt重新武装 nudge 并原样保留注入器输出pretool将注入器输出序列化为 PreToolUse 的additionalContextposttool校验有效计划后每轮提示一次通过按 session/agent/prompt 派生的 turn marker 去重precompact转发压缩提醒stop校验选择后保留 stdin 供完成度门控使用。实现上它有一个显著的工程细节优先使用inject-plan.py快路径。脚本通过纯 stat 调用不做 fork在 PATH 中定位 CPython 3并以python -I -B方式运行注入器-I防止项目目录进入sys.path、-B防止在 Skill 目录写字节码失败时才回退到参考实现inject-plan.sh。这是对原则 1 的另一种贯彻在 Git Bash/Windows 环境下一次事件分发从约 130 次 fork约 712 秒、超时被丢弃优化到单进程约 60ms使计划注入在 Hook 超时阈值内稳定送达模型见 inject-plan.py 的动机说明。7.3 模板 脚本把方法论变成可执行工作流完整的落地闭环还包括初始化、状态恢复与完成度校验三个环节的脚本配套全部位于.codebuddy/skills/planning-with-files/scripts/init-session.sh/init-session.ps1按模板初始化全部规划文件打印PLAN_ID用于多任务固定resolve-plan-dir.sh/resolve-plan-dir.ps1依据PLAN_ID与PWF_PLAN_ROOT解析任务所属计划目录——这是恢复项目状态的第一步恢复时从选定目录读取三个规划文件根目录task_plan.md不得覆盖已选定的命名计划docs/quickstart.md 对多任务隔离给出了init-session backend-refactor/set-active-plan/ 并发会话设置独立PLAN_ID的操作示例check-complete.sh/check-complete.ps1校验全部阶段是否complete作为完成度门控的依据session-catchup.py仅在用户明确要求时以--metadata仅输出同项目会话的聚合计数或--replay受限、带 nonce 框架的摘录模式读取本地会话记录且没有任何网络上传路径——把恢复记忆限制在显式、本地、可审计的边界内set-active-plan.sh切换当前活动计划指针适合顺序切换多个任务。这整套机制回答了一个实际问题当 Agent 在/clear或上下文压缩后丢失记忆时如何恢复答案就在原则 3 与策略 1 里——状态从不在上下文中而在磁盘上。Hook 在会话开始时读取三个文件重建状态git diff --stat补充代码变更视图Agent 即可无缝续跑。7.4 自检工具Read vs Write 决策矩阵与 5 问重启测试SKILL.md 还提供了两个可直接套用的实操框架Read vs Write 决策矩阵何时读、何时写场景动作理由刚写完文件不读内容仍在上下文中查看图片/PDF 后立即写 findings多模态信息在丢失前转成文本浏览器返回数据写入文件截图无法持久化开启新阶段读 plan/findings上下文若已陈旧则重新定位出现错误读相关文件需要当前状态来修复中断后恢复读全部规划文件恢复状态5 问重启测试能回答这 5 问说明上下文管理是健康的问题答案来源我在哪task_plan.md 中的当前阶段我要去哪剩余阶段目标是什么计划中的目标陈述我学到了什么findings.md我做了什么progress.md这套矩阵与测试本质上是对文件即记忆的日常操作化读与写不再是随意行为而是按上下文状态触发的有纪律动作。八、什么时候该用这套模式reference.md 与 SKILL.md 共同界定了适用边界应当使用多步任务3 步以上研究型任务项目构建/创建跨越大量工具调用的任务任何需要组织性的工作。应当跳过简单问答单文件编辑快速查询。examples.md 用四个完整示例展示了模式的实际运转研究任务4 个 Loop建计划 → 研究 → 综合 → 交付、Bug 修复任务plan 中记录 root cause 定位过程、功能开发三文件模式 交付物文件、错误恢复对比静默重试的错误示范与记录-换路线的正确示范。其中研究任务示例特别标注了WebSearch 结果视为不可信数据只写入 findings.md绝不写入 task_plan.md——这再次呼应把复制材料当作数据而非指令的安全原则。九、总结从 reference.md 的 6 条原则到本仓库的 Hook 机制可以提炼出一条完整的方法论链条成本维度原则 1、2稳定的前缀、append-only 序列化、掩码而非移除——决定了 Agent 系统的经济性记忆维度原则 3、5文件系统即外部记忆、错误留在上下文——决定了长任务的可靠性注意力维度原则 4、6复述计划、受控变化——决定了长任务的目标保持能力架构维度策略 1、2、3压缩/摘要、多 Agent 隔离、上下文卸载——决定了系统在大规模下的可扩展性工程维度本仓库生命周期 Hook 自动注入、确定性序列化的双实现校验、门控完成度检查、多 Agent 唯一协调者——把上述原则变成可在 Claude Code、Codex、Cursor、OpenCode 等宿主上直接运行的工作流。最终这套方法论的落点始终是那句被反复引用的公式上下文是易失的 RAM文件系统是持久的磁盘任何重要的东西都要写入磁盘。对每一个需要跨越数十次工具调用的 AI 编码 Agent 而言把计划、发现与进度持久化为磁盘上的三个 Markdown 文件就是对抗上下文漂移、崩溃丢失与成本失控的最直接有效的工程答案。【免费下载链接】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），仅供参考