企业官网建设流程全解析

从 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-files

Manus 上下文工程原则（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 上下文工程原理"备忘录，其源头是 Manus（2025 年 12 月被 Meta 以 20 亿美元收购的 AI Agent 公司）官方发布的上下文工程文档。它回答了生产环境中 AI Agent 最棘手的一类问题：当上下文窗口是易失、有限的内存（RAM）时，Agent 如何依靠文件系统这块持久、无限的磁盘（Disk）来完成长任务？

整份文档可以分为四个层次：

1. 6 条底层原则——关于 KV-Cache、注意力、记忆与失败处理的第一性原理；
2. 3 大工程策略——上下文缩减、隔离、卸载的架构手段；
3. 7 步 Agent 循环——Agent 单次行动的统一执行框架；
4. 配套约束、统计与金句——可操作的行为规则与经验数据。

下文将逐层展开，并在每一节末尾以"仓库实现印证"的形式，指出本仓库中对应落地这些原则的源码与配置。

一、6 条 Manus 上下文工程原则

原则 1：围绕 KV-Cache 设计（Design Around KV-Cache）

"KV-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, Don't 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 Memory）

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

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

"Leave 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 guard，v3.10.0）在检测到已完成的 phase 数量回退时，会打印一条提示"指明丢失了多少工作并指向git diff"——它不阻塞、只是留痕，正是"保留错误痕迹供模型更新信念"的又一个例证。

原则 6：不要被少样本范式固化（Don't Get Few-Shotted）

"Uniformity breeds fragility."（千篇一律孕育脆弱性。）

问题：重复的动作-观察（action-observation）配对会导致模型漂移与幻觉——一旦成功路径高度同质，模型就变成"背诵"而非"推理"。

解决方案：引入受控的变化（controlled variation）：

• 略微变化措辞；
• 不要盲目复制粘贴既有模式；
• 在重复性任务上主动重新校准（recalibrate）。

仓库实现印证：本仓库的PWF_INJECT=smart（结构感知注入，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"规则也要求任务扩展时新增 phase（Phase 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 -20），v3 模式则注入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 Loop：7 步执行循环

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 │ │ - 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.sh）；Stop钩子则接入完成门控（gate-stop）——但注意，门控只在 gated 模式、存在 in_progress 阶段且满足 5 项条件时才会请求继续（见下文的"Gate decision table"），这保证了第 7 步交付前计划必须是完整的。此外，templates/loop.md 提供了规划感知的循环 tick 模板：每个 tick 重读三个规划文件、运行 check-complete、在无进展时追加 progress.md 条目，把第 6 步"ITERATE"变成可由/loop驱动的持续进程。

四、Manus 创建的文件类型：三件套 + 代码文件

参考文档给出了 Manus 在任务中创建的完整文件清单：

仓库实现印证：本仓库完整继承了这套三件套，并在 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 Required）：Agent 必须始终知道：目标、当前阶段、剩余阶段。对应 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 公开数据，用于理解其规模与权衡）：

三条最常被引用的经验语录（引用自参考文档）：

"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."

七、从原则到工程：本仓库的落地机制速览

把上面的原则映射到本仓库的实现面，可以得到一张完整的对应表：

两条值得单独说明的加固机制

哈希背书（Attestation，v2.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 Mode，v3）：gate 是"终止判定器"（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_ID=2026-09-10-backend-refactor # 2. 把当前终端钉到该计划（hooks 只认这份计划） export PLAN_ID=2026-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