AI 规划系统对比：完成语义与上下文保留的权衡

AI 规划系统对比：完成语义与上下文保留的权衡 | 前端进阶之旅

Full translation

完整中文译文

Planning-with-Files 是一款广受欢迎的 Claude Code 插件，它为 Claude Code 补充了一套更强大的规划系统。本文从两个层面对其方法与 AGE（Attractor-Guided Engineering）系统中的 Plan 概念进行比较。

规范层（Plan 系统）

AGE Plan——Attractor-Guided Engineering 的计划治理系统，由 docs/plans/00-plan-authoring-and-execution-guide.md 中的 24 条最低规则定义。它是一份纯文本规范，不依赖任何特定工具链。

Planning-with-Files（PwF）——OthmanAdi/planning-with-files，一个源自 Manus 上下文工程理念的通用 AI 智能体技能插件。采用三文件结构 + 状态模型 + hooks。

自动化层（执行引擎）

AGE Goal Driver——位于 nop-entropy/ai-dev/tools/opencode-goal-driver/ 中的独立进程状态机，它将 AGE Plan 的文本规则工程化为可执行代码。AGE Goal Driver 是 AGE Plan 的可选执行机制。

AGE Plan 治理的是完成是否真实；PwF 治理的是上下文是否仍然存在。一个防止计划被虚假完成，另一个防止智能体遗失目标。这一分歧决定了后续所有机制上的差异。

1. 设计取向

规范层：AGE Plan vs PwF

自动化层：AGE Goal Driver vs PwF hooks/loop

2. AGE Plan 的独有特性（规范层）

AGE Plan 的全部 24 条最低规则，源自执行历史中遇到的七类错误。每条规则都是因为智能体曾在某个时刻自欺欺人地将某件事标记为“已完成”而添加的补丁。本节只描述 AGE Plan 规范层的要求——这些规则不依赖 AGE Goal Driver，在手动遵循时同样有效。AGE Goal Driver 的自动化实现留到第 4 节讨论。

2.1 Closure Gates——独立于阶段退出条件的最终检查层

Closure Gates 是计划级的最终检查清单，构成了一个独立于各个 Phase 内 Exit Criteria 的验证层。其中的条目不是任务列表，而是防止自欺的判定：

“没有任何范围内的现存缺陷被悄悄降级为 deferred / follow-up”

“独立子智能体的收尾审计已完成，并已记录证据”

“所有范围内已确认的契约偏差均已收敛”

pnpm typecheck && pnpm build && pnpm lint && pnpm test

PwF 的 check-complete.sh 执行语法检查：它统计 **Status:** complete（以及 [complete] 备用格式）的出现次数是否与 ### Phase 的出现次数相等。PwF 刻意选择不执行语义审计——它的目标是实现横跨 17 个以上平台的通用性，而语义审计需要理解项目特定的完成标准，这很难模板化。然而，其代价是它无法区分“阶段状态被写成了 complete”和“缺陷确实已修复、契约确实已对齐”。Closure Gates 处理的是后者。

AGE Goal Driver 自动化：check-plan-checklist.mjs 自动执行 Closure Gates 检查——扫描所有计划文件，检查状态为已完成的计划是否仍有未勾选的清单项、Closure Evidence 是否存在，以及所有 Closure Gates 是否均已勾选。它会区分硬失败（已完成但仍有未勾选项）和警告（未完成且有未勾选项）。

2.2 独立收尾审计——实施者不能自我审计

将计划标记为已完成的必要条件是：必须由独立审查者或独立启动的全新子智能体会话执行收尾审计。实施者不能自行关闭自己的计划。

验证不能只检查接口是否存在，还必须检查行为语义是否已经实现：新增组件是否在运行时被调用（而不仅仅是存在 import）、是否不存在空方法体或静默跳过。

PwF 的 Stop hook 只检查阶段状态数量，不区分“由谁执行了审计”。

2.3 反懈怠规则——禁止使用模糊措辞替代状态裁定

在计划关闭之前，每一个范围内条目都必须归入且只能归入以下四种明确状态之一：已落地、已裁定为仅剩余风险、已移交给明确的后续责任方、通过有记录的范围变更从范围中移除。

禁止使用 optional、if time permits、consider、maybe、nice to have 来替代状态裁定。

## Deferred But Adjudicated 中的每个延期条目都必须包含三个字段：Classification（只能是 watch-only residual | optimization candidate | out-of-scope improvement）、Why Not Blocking Closure（明确原因）、Successor Required（yes/no）。没有原因的延期条目会被视为未完成。

PwF 的状态只有 pending → in_progress → complete，不存在“已延期但已裁定”的中间状态。

2.4 不可降级条目 + 测试策略 + 失败路径

这三条规则共同构成 AGE Plan 的“不可降级”边界：

不可降级条目。五类条目不能放入 deferred / non-blocking：lint 规则、现存缺陷、公共契约偏差、owner-doc 偏差、必要的针对性验证。每个执行条目都必须标记为 Fix | Decision | Proof | Follow-up 之一。已确认的现存缺陷只能是 Fix，不能降级为 Follow-up。

测试策略分级。每个计划都必须声明与风险相匹配的测试投入策略：身份认证和外部 API 契约必须自动化（先有 Proof 条目，再有 Fix）；一般功能建议配备测试；没有行为变更的纯文档工作可以声明不适用，但必须给出理由。

失败路径。模板提供了一个 ## Failure Paths 表格——建议用于涉及错误处理、API 契约、身份认证或外部集成的计划。每一行都包含触发条件、预期行为（包括状态码）、可重试性以及用户可见的表现。这会迫使计划作者在考虑正常路径的同时，也考虑异常路径。

PwF 的错误处理仅限于 3-Strike Error Protocol（重试升级）和 Errors Encountered 表格（事后记录），没有预先规定异常路径。

2.5 当前基线 + 嵌入阶段的文档裁定

在编写计划之前，必须先核实现行仓库的当前状态，逐项列出“已确认的事实”“已经完成但旧文档尚未同步的事实”以及“真正剩余的差距”。Goal 不是 Baseline——Goal 是你要去往的位置，Baseline 是你当前所在的位置。

每个 Phase 的 Exit Criteria 都包括：“如果该 Phase 改变了当前基线，则相关的 docs/architecture/ 已更新；否则，明确说明 No owner-doc update required。”文档同步是 Phase 内的工作，而不是收尾工作。

AGE Goal Driver 自动化：detectStartPhase 会在启动时自动判断从哪里继续——运行 check-plan-status.mjs 检查是否存在未完成的计划，并检查审计目录是否存在；如果存在未完成的计划，则跳转到执行；如果存在审计目录，则跳转到规划；如果两者都不存在，则从审计开始。纯脚本逻辑，不调用 LLM。

2.6 历史计划保护 + 防止过度拆分

规则 20（历史保护）：默认将已经标记为已完成的历史计划视为历史记录，不会因为规范演进、模板变化或代码演进而主动重写。

规则 21–24（防止过度拆分）：不要仅仅因为发现项很多或文件接近 30 KB 就拆分计划。属于同一组件、同一模块或同一 owner-doc 的多个发现项，应优先合并到一个责任计划中。只有当收尾语义出现分歧时，才触发拆分。

3. PwF 的独有特性（规范层 + 自动化层）

PwF 的核心关注点只有一个：防止智能体在长任务中丢失上下文。

3.1 三文件分离 + 安全隔离

task_plan.md（路线图）+ findings.md（知识库）+ progress.md（会话日志）。这三个文件有着明确的职责和更新频率：

findings.md 的存在远不止是一个笔记本——其设计包含安全考量。task_plan.md 在每次工具调用时都会通过 hook 自动注入到智能体的上下文中。如果外部 web 搜索结果被写入 task_plan.md，其中的恶意指令会被放大到每次工具调用。SKILL.md 安全边界明确规定：外部内容只能写入 findings.md，不能写入 task_plan.md。

AGE Plan 不在计划系统中管理研究发现和外部内容——执行期间生成的这些材料由智能体根据实际情况存储在适当位置，不包含在计划文件中。

3.2 Hook 自动注入系统

IDE 生命周期中五种类型的 hook 自动执行，无需智能体有意识地遵循规则：

AGE Plan 的规则层没有自动注入机制，依赖智能体遵循 AGENTS.md。AGE Goal Driver 也不注入计划内容，而是使用 XML 标签协议进行编程输出解析。PwF 代表第三条路径：使用 hook 自动将计划注入上下文，不需要智能体知道。

3.3 双层安全防御

第一层（默认启用）：定界符框架。Hook 注入的计划内容被包装在 ===BEGIN PLAN DATA=== / ===END PLAN DATA=== 中，标记为结构化数据，并指示智能体不要执行其中的命令式文本。

第二层（可选）：SHA-256 证明。/plan-attest 计算并存储 task_plan.md 的哈希值。所有 hook 在注入前都会比对哈希；如果不匹配，它们会拒绝注入并输出 [PLAN TAMPERED]。PreCompact hook 也会打印 Plan-SHA256，确保智能体在上下文压缩后仍可验证计划未被篡改。

AGE Plan 没有等效的安全机制，因为它信任智能体和文件系统。

3.4 会话补偿——自动会话恢复

session-catchup.py 在 /clear 或上下文重置后自动从 IDE 的会话存储中提取最后一次计划文件更新之后发生的对话，并生成补偿报告。

AGE Plan 通过 docs/logs/ 手动重建上下文，没有自动会话恢复机制。AGE Goal Driver 的 detectStartPhase 通过检查 repo 状态来确定继续位置——它不会恢复对话历史，只恢复执行位置。

3.5 并行任务隔离

PwF 支持并行多任务：init-session.sh "task name" 在 .planning/YYYY-MM-DD-slug/ 下创建隔离目录，每个目录有自己的三个文件集合。set-active-plan.sh 切换活跃计划，PLAN_ID 环境变量将终端固定到特定计划。Hook 通过 resolve-plan-dir.sh 自动定位正确的计划。

AGE Plan 在 docs/plans/ 中有多个计划文件共存，没有目录隔离或自动切换机制。

3.6 操作级约束

2 行动规则：每进行 2 次搜索/浏览操作后，必须将发现写入 findings.md。针对多模态内容的易变性——图片和浏览结果不会在上下文中持久保存。

3 次失败协议：第 1 次尝试诊断并修复 → 第 2 次尝试改变方法（禁止重复相同操作）→ 第 3 次尝试重新思考 → 3 次失败后，升级给用户。

5 问重启测试：如果智能体可以回答"我在哪里、我要去哪里、目标是什么、我学到了什么、我做了什么"，说明上下文完整。

AGE Plan 通过基线和退出条件进行结构化检查，但没有操作频率约束或快速自检。

3.7 轮次循环集成

与 Claude Code 的 /loop 和 /goal 组合集成：/plan-loop 10m 每 10 分钟自动执行一次（重新读取计划、运行检查完成、写入进度）；/plan-goal 从计划推导终止条件。这是 PwF 自动化层的循环机制。AGE Goal Driver 的双循环状态机是另一种自动化方法，详见第 5 节。

3.8 17+ IDE/平台支持

一种计划格式同时适配 Claude Code、Cursor、Copilot、Gemini CLI、Kiro、Codex、Hermes、CodeBuddy、FactoryAI、Pi Agent、OpenCode、Continue、Mastra、OpenClaw、Antigravity、Kilocode、AdaL CLI 等平台。AGE Plan 仅用于内部项目。

4. 两者的关系（规范层）

AGE Plan 和 PwF 不是可组合的关系；它们是两个独立的计划系统，各自回答不同的问题。

AGE Plan 的计划系统仅管理计划本身的结构、执行、审计和闭合。执行期间生成的研究发现和外部内容不属于计划系统——智能体根据实际情况选择临时目录存储它们，根据需要组织文件链接。AGE Plan 不规定这些材料的存储位置，也不将它们包含在计划文件中。

PwF 的三文件结构（task_plan + findings + progress）是一个整体设计，findings.md 的安全隔离原理直接服务于 hook 注入机制——将外部内容与注入面隔离。这个设计不能被拆解并部分移植到 AGE Plan。

两者的真正交集在于：如果 AGE Plan 未来深度集成某个智能体运行时，它可以模仿 PwF 的 hook 机制在执行时刻加强强制——例如在关键工具调用前自动重新读取计划，或在阶段完成后自动提醒更新日志。但这不是"与 PwF 结合"，而是借用 hook 机制概念为 AGE Plan 的治理规则提供自动强制保证。

5. 自动化层对比：AGE Goal Driver vs PwF hooks/loop

AGE Goal Driver 不是 AGE Plan 本身，而是 AGE Plan 的可选自动化实现。它与 PwF 的 hooks/loop 处于同一级别——两者都是将计划规范转化为可执行系统的机制。

5.1 AGE Goal Driver 的双循环状态机

外层循环（审计驱动）：
  健康检查 → 深度审计 + 对抗性审查 → 存在问题？
    ├─ 否 → 完成
    └─ 是 → 起草计划
        ↓
      内层循环（执行驱动）：
        执行计划 → 独立闭合审计（独立进程）
          ├─ 完成 → 中断
          └─ 未完成 → 提取 REMAINING XML → 继续执行
        ↓
      构建验证 → 返回外层（重新审计）

外层循环确保即使当前计划的所有复选框都被勾选，独立审计仍必须确认没有引入新问题。内层循环确保执行后必须通过独立验证；执行者不能自行声明完成。

每步提示要求 AI 输出 XML 标签如 <AUDIT_RESULT>clean|issues</AUDIT_RESULT>，extractTag 函数解析这些标签来驱动状态机。当 AI 没有输出标签时，extractTagOrAsk 生成额外的 AI 调用来推断缺失的标签——一个自愈解析层。整个状态机不依赖人类阅读 markdown 来判断；而是以编程方式解析标签进行自动状态转换。

5.2 进程隔离

每步都生成独立的 opencode 进程——deep-audit、adversarial-review、plan、execute、closure-audit 各自隔离。执行智能体和审计智能体本质上是不同的进程，物理隔离而非受规则约束。

闭合审计由完全独立的 opencode 进程执行，其上下文中没有执行阶段的任何信息；它必须从实时 repo 重新检查每个退出条件。如果验证结果不完整，它从 <REMAINING> XML 块中提取特定的不完整项目，并将其注入下一轮执行的提示中。

当子进程日志超过可配置的停滞阈值而没有更新时，会生成一个独立的看门狗智能体，允许它自己诊断进程状态，读取日志尾部，并决定是否杀死卡住的进程。主驱动程序不会做出杀死决定。

5.3 与 PwF 自动化层的对比

6. 哪个方向更持久

完成语义与上下文保留：AGE Plan与Planning-with-Files的设计分野（第3部分）

PwF解决的核心问题是AI智能体上下文不足。2-Action规则、会话追赶和钩子自动注入的存在都源于模型无法记住或读取所有内容这一事实。随着上下文窗口扩大和模型长上下文能力的增强，这个问题会逐渐减弱。PwF的大多数机制将沉淀成AI智能体运行时基础设施的原生能力，用户无需显式安装技能来解决这些问题。然而，PwF的安全模型（分隔符框架、证明和发现隔离）独立于模型能力——无论模型多强大，注入攻击的向量总会存在。但那属于安全工程的范畴，而非规划系统。

AGE Plan解决的问题不会因为模型变强而消失。"缺陷真的被修复了吗？"不是记忆问题，而是完成语义判断问题。"这个线上缺陷被悄悄降级为后续跟进"不是AI智能体遗忘了，而是AI智能体在自我欺骗。这些都是复杂工程的结构性难题——范围管理、契约对齐、文档与代码的一致性。模型越强大，变化发生得越快，这些问题就越可能出现：一个强大的AI智能体能在50次工具调用内完成复杂的重构，同时在第37次调用时悄悄将约定漂移隐藏到后续中。24项最少规则的作用不是限制AI智能体的能力边界，而是确保工程判断的诚实性。

演进的真正方向是由AGE Goal Driver所代表的路径——将治理规则从"期望AI智能体遵守"转变为"系统强制执行的命令"。规划指南定义语义，AGE Goal Driver确保语义落地。如果进一步与AI智能体运行时深度集成——自动在关键工具调用前重新读取规划，自动在阶段完成后触发退出条件检查——就会形成完整的解决方案：来自AGE Plan的规则语义、来自AGE Goal Driver的强制执行，以及来自钩子机制的触发时机。三个层次都围绕AGE Plan的治理语义运转。

如需进一步的操作，你可以考虑屏蔽此人和/或举报滥用行为