企业官网建设流程全解析

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-Cache）

"KV-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 的变化都会使整段缓存失效。

具体实现纪律有三条：

1. 保持 prompt 前缀稳定（单 token 变化即可使缓存失效）；
2. 系统提示词中不要放时间戳；
3. 上下文采用 append-only 追加式，并使用确定性序列化。

这条原则在 planning-with-files 中被落实得非常彻底。legacy 模式下注入内容固定以===BEGIN PLAN DATA===/===END PLAN DATA===包裹（SKILL.md）；v3 的 autonomous/gated 模式进一步用ledger-summary.sh合成"固定形状、KV-cache 稳定"的运行账本块——脚本头部注释明确写道：输出只来自机器账本与计划状态计数，磁盘上的自由文本不进入模型上下文，且没有任何时间戳，因此注入块在构造上就是 KV-cache 稳定的（scripts/ledger-summary.sh）。

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

不要动态移除工具（这同样会破坏 KV-cache），而是使用logit masking（逻辑掩码）在推理层屏蔽工具。

最佳实践：为动作使用一致的前缀（如browser_、shell_、file_），便于统一掩码。这与"append-only、前缀稳定"的原则一脉相承——工具列表保持静态，只是概率被屏蔽。

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

"Markdown 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 Recitation）

"Creates and updates todo.md throughout tasks to push global plan into model's 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.md）；
• The 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 In）

"Leave the wrong turns in the context."

为什么：

• 带堆栈追踪的失败动作能让模型隐式更新信念；
• 减少错误重复；
• 错误恢复"是真正的 Agent 行为最清晰的信号之一"。

这条原则在 SKILL.md 中被放大成两条硬规则：Rule 5: Log ALL Errors（每个错误都必须记入计划文件，附错误表格模板 Error/Attempt/Resolution）与Rule 6: Never Repeat Failures（if 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 带偏（Don't Get Few-Shotted）

"Uniformity 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.md（scripts/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 Loop）

reference.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 的 ITERATE；progress.md在断点处记录（对应"log what's done"）则服务于步骤 7 的交付与后续恢复。

2026 年的更新澄清了循环中的一条历史约束（详见下节）：现代宿主（Claude Code、Codex CLI）支持并行工具调用与子 agent，因此"每回合一个工具调用"不再是硬约束——协调点从"一次一个调用"转移到磁盘上持久的 markdown 计划，并行调用与子 agent 通过它共享状态（SKILL.md）。

四、Manus 创建的文件类型与三文件模式

reference.md 给出 Manus 在任务中创建的文件清单：

planning-with-files 把这三类 markdown 文件直接做成可复用的模板，安装后存放在skills/planning-with-files/templates/下：

• templates/task_plan.md—— 任务的路由图：Goal、Next Step、Current Phase、3～7 个可验证的 Phase（状态只用pending/in_progress/complete）、Key Questions、Decisions Made、Errors Encountered；
• templates/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）回答了"何时读、何时写"：

（见 SKILL.md）

五、关键约束与 2026 更新

reference.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 是机制层。以下对应关系让读者能"既懂原理、又能落地"：

• 原则 1（KV-cache）→ 固定分隔符与无时间戳注入：legacy 模式===BEGIN PLAN DATA===/===END PLAN DATA===；v3 用非确定性 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 运营数据：

这些数字解释了为什么约 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.md（SKILL.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