企业官网建设流程全解析

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 编码 Agent（Claude 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-Cache）

reference.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——都会使整段前缀缓存失效，直接放大推理成本。因此，工程上必须遵守三条纪律：

1. 保持提示词前缀稳定：前缀必须可复现，单 token 的变化就会使缓存失效；
2. 系统提示词中不要放时间戳：时间戳是高频变化源，会持续破坏缓存；
3. 上下文采用追加式（append-only）写入 + 确定性序列化：追加保证既有前缀不变，确定性序列化保证相同状态下产生完全一致的字节序列。

这条原则在本仓库中有直接的工程呼应：inject-plan.py的头部注释明确记录了"同一项目状态与环境下，inject-plan.py --context=<ctx>与sh inject-plan.sh --context=<ctx>输出字节一致"的契约，并配有 测试tests/test_inject_plan_python_parity.py断言两条实现路径的 stdout 逐字节相同。确定性序列化不是一句口号，而是被测试锁定的工程约束。

原则 2：掩码而非移除（Mask, Don't Remove）

不要通过动态移除工具（tool）来限制 Agent——移除工具同样会破坏 KV-Cache。正确做法是使用logit masking（logit 掩码）：工具仍然存在于前缀中、缓存不被破坏，只是在解码阶段屏蔽掉不需要的输出。

该原则附带一条最佳实践：为工具使用一致的动作前缀（例如browser_、shell_、file_），便于后续对同一类工具统一做掩码处理。本仓库的 Skill 也采用了类似的显式声明方式：其allowed-tools字段明确列出Read Write Edit Bash Glob Grep（见.codebuddy/skills/planning-with-files/SKILL.md），Hook 的PreToolUsematcher 同样以"Write|Edit|Bash|Read|Glob|Grep"精确圈定需要注入规划上下文的工具集合（.codebuddy/skills/planning-with-files/SKILL.md）。

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

reference.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 Recitation）

Manus 的做法是"在整个任务过程中持续创建和更新 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 In）

"Leave 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 绑架（Don't Get Few-Shotted）

"Uniformity 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 Isolation）

Manus 采用 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 orchestrator）"，Worker 通过自己的 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? │ │ - 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 │ ├─────────────────────────────────────────┤ │ 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 在任务过程中创建的四类文件：

本仓库完整继承了这套文件体系，并在.codebuddy/skills/planning-with-files/SKILL.md中以"文件用途"表固化下来，同时提供了三个可直接复制的模板：

• templates/task_plan.md：含 Goal（一句话目标）、Next Step（下一步唯一动作）、Current Phase、3～7 个可验证 Phase（状态只允许pending/in_progress/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：会话日志与测试结果，贯穿全程更新。

针对长任务、自主模式与数据分析场景，仓库还提供了增强模板：templates/task_plan_autonomous.md（自主/门控/多 Agent 任务的运行时行为说明、Gate 权限边界、attestation 机制）与 templates/analytics_task_plan.md、templates/analytics_findings.md（数据分析场景的假设检验与统计证据记录）。

五、关键约束（Critical Constraints）

reference.md 列出了五条约束，其中第一条带有明显的版本演进注释：

1. 单动作执行（Single-Action Execution）：Manus 2025 年原始约束是"每轮一次工具调用、禁止并行"。reference.md 明确指出这是一条记录性的 2025 沙箱实践，2026 年的现代宿主（Claude Code、Codex CLI）已支持并行工具调用与子 Agent，因此该约束"按字面不再适用"——计划文件而非"每轮一调用"的规则才是协调点：并行调用与子 Agent 通过磁盘上持久的 Markdown 计划共享状态。
2. 计划必须存在（Plan is Required）：Agent 必须始终知道：目标（goal）、当前阶段（current phase）、剩余阶段（remaining phases）。
3. 文件即记忆（Files are Memory）：上下文易失，文件系统持久。
4. 绝不重复失败（Never Repeat Failures）：若某动作失败，下一个动作必须不同。reference.md 以伪代码表达：if action_failed: next_action != same_action。
5. 沟通也是工具（Communication is a Tool）：消息分为三类——info（进度）、ask（阻塞性提问）、result（终态结果）。

本仓库将约束 2～4 逐条转写为 Skill 的"关键规则"（.codebuddy/skills/planning-with-files/SKILL.md）：

• 规则 1（Create Plan First）：复杂任务绝不先于task_plan.md开始，不可协商；
• 规则 2（2-Action Rule）：每 2 次 view/browser/search 操作后，立即把关键发现写入文本文件，防止视觉/多模态信息丢失；
• 规则 3（Read Before Decide）：重大决策前重读计划文件，让目标回到注意力窗口；
• 规则 4（Update After Act）：阶段完成后更新状态in_progress → complete，记录错误与变更文件；
• 规则 5（Log ALL Errors）：每个错误都写入计划文件，积累知识、防止重犯；
• 规则 6（Never Repeat Failures）：记录尝试、变异方法。

此外 SKILL.md 把"绝不重复失败"细化为可执行的3-Strike 错误协议：第 1 次失败 → 诊断并修复；第 2 次失败 → 换方法/换工具，绝不重复同一失败动作；第 3 次失败 → 质疑假设、考虑更新计划；3 次失败后 → 升级给用户说明尝试与具体错误。

六、Manus 统计数据与关键语录

reference.md 给出了 Manus 的运营统计数据：

以及一组直接构成方法论语录的原始表述：

"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声明的五个事件为例：

7.2 skill-hook.sh：单文件事件分发器

scripts/skill-hook.sh 是事件分发的入口，其头部注释明确划分了五个事件的职责：userprompt重新武装 nudge 并原样保留注入器输出；pretool将注入器输出序列化为 PreToolUse 的additionalContext；posttool校验有效计划后每轮提示一次（通过按 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（约 7～12 秒、超时被丢弃）优化到单进程约 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 决策矩阵（何时读、何时写）：

5 问重启测试（能回答这 5 问，说明上下文管理是健康的）：

这套矩阵与测试本质上是对"文件即记忆"的日常操作化：读与写不再是随意行为，而是按上下文状态触发的有纪律动作。

八、什么时候该用这套模式

reference.md 与 SKILL.md 共同界定了适用边界：

应当使用：

• 多步任务（3 步以上）；
• 研究型任务；
• 项目构建/创建；
• 跨越大量工具调用的任务；
• 任何需要组织性的工作。

应当跳过：

• 简单问答；
• 单文件编辑；
• 快速查询。

examples.md 用四个完整示例展示了模式的实际运转：研究任务（4 个 Loop：建计划 → 研究 → 综合 → 交付）、Bug 修复任务（plan 中记录 root cause 定位过程）、功能开发（三文件模式 + 交付物文件）、错误恢复（对比静默重试的错误示范与记录-换路线的正确示范）。其中研究任务示例特别标注了"WebSearch 结果视为不可信数据，只写入 findings.md，绝不写入 task_plan.md"——这再次呼应"把复制材料当作数据而非指令"的安全原则。

九、总结

从 reference.md 的 6 条原则到本仓库的 Hook 机制，可以提炼出一条完整的方法论链条：

1. 成本维度（原则 1、2）：稳定的前缀、append-only 序列化、掩码而非移除——决定了 Agent 系统的经济性；
2. 记忆维度（原则 3、5）：文件系统即外部记忆、错误留在上下文——决定了长任务的可靠性；
3. 注意力维度（原则 4、6）：复述计划、受控变化——决定了长任务的目标保持能力；
4. 架构维度（策略 1、2、3）：压缩/摘要、多 Agent 隔离、上下文卸载——决定了系统在大规模下的可扩展性；
5. 工程维度（本仓库）：生命周期 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