本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.5 · SDK 2.6.9。 英文原文

目标保证

状态：当前 范围：目标验收检查与源新鲜度 最近审阅：2026-09-14 负责人：AX Code 运行时维护者

目标规划器产生的代码变更计划会声明可执行的验收 检查。每项检查都会写明它所覆盖的结果、确切命令、用途 以及预期环境。当代理运行 verify_project 并带上该检查的 goalCheck 标识时，AX Code 会记录执行证据。

{ "goalCheck": "invoice-parity" }

该命令来自冻结的目标计划。代理不能通过这次调用把它换成 另一条命令。现有的 bash 权限仍然适用。 完成目标要求每一项已声明检查的最近一次尝试都通过，并且 目标、会话、工作区、契约和源内容相匹配。验收文字 说明结果；它不能代替已执行的检查。普通的 shell 运行，以及 被完全跳过的检查，都不能提供这份证据。

没有保证的旧目标计划保留其原先的完成规则。需要新契约时，请清除并 重建旧目标；就地编辑其冻结要求 会导致契约不匹配。分叉会保留契约，但需要 在新会话中重新运行检查。

准备迁移项目

请提供带修订标识的权威遗留源或导出、一份有界的 覆盖清单，以及在断言无法被验证时会失败的检查脚本。 把注释和更早的迁移实现当作需要调查的线索。 把已批准的行为变更与遗留行为对等要求分开记录。

为所请求变更实际影响的层次选择检查：

脚本必须在执行检查之前断言目标身份。把 凭据放在项目现有的凭据机制中，绝不要放进计划文本、 命令或目标描述。检查应当在断言失败、环境缺失或跳过了必需断言时返回非零退出码。避免用包装脚本 掩盖失败。AX Code 无法从成功的进程退出推断出断言。

对于大型迁移，把工作组织成有界的业务流程批次，并维护 一份把表单、依赖、遗留引用和验收检查联系起来的清单。 同时报告已接受的批次和剩余覆盖。通过一个批次并不 等于完成整个迁移。

计划记录什么

规划器提供一个 assurance 对象。这个示意片段假定 项目拥有所引用的源导出和检查脚本：

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

所有验收 id 都必须被覆盖。命令从工作区根目录执行。 保证对象与验收契约一起冻结。代理在其持续的 目标上下文中收到已验证的范围、源引用、检查 id 和已声明目标。缺失或被改动的契约会产生恢复提示。生成的 对话摘要仍然可能出错；已声明的引用和目标标签 是要求，不是被独立观察到的事实。

用来衡量此目标改变了什么的 Git 范围必须使用 {BASELINE} 作为 之前状态。规划器会把该占位符改写为提交计划时捕获的 HEAD SHA，因此位于 origin/main 之前就已存在的提交，或 脏工作树，不能使目标变得无法完成。远程跟踪引用 （origin/main、@{u}、refs/remotes/…）会被拒绝作为该之前状态， 除非目标本身点名了该远程。把已经分叉或脏的 路径记在风险下；不要冻结一项已经失败的门禁检查，除非 目标就是修复该失败。

新鲜度与限制

Git 源指纹包含已声明 sourcePaths 之内、已跟踪文件以及未被忽略的未跟踪 文件的实际字节。显式文件路径也包括被忽略的 配置文件；目录路径仍遵守 Git 忽略规则。可变的目标计划检查清单被排除；它们的冻结要求通过 契约摘要来检查。非 Git 项目会递归地为已声明的 sourcePaths 计算指纹，包括缺失路径。把每一个相关源、配置 文件和检查脚本都纳入该范围。

指纹计算限制为 20,000 个条目和 128 MiB 的文件内容。链接的 源、嵌套的 Git 仓库、特殊文件、逃逸路径、正在变化的文件以及 无法读取的内容都不能产生新鲜证据。这类失败会阻止有保证的 完成。检查输出产物应放到被忽略的位置，以免生成 报告改变正在被验证的源。

未被显式点名的忽略文件、源范围之外的依赖、数据库和部署 都需要在项目命令中作出断言。回执记录的是其 执行时刻的一次观察；它不能证明外部状态此后保持不变。更改配置、数据库或部署之后，请重新运行 受影响的检查。AX Code 不会自动发现全部遗留行为，也不会认证迁移对等。

规划何时运行

规划在两个界面上都是选择加入的。/goal <objective> 与 create_goal 在没有 assure 时会立即启动目标：它不携带冻结的验收 标准，完成与否由工作计划（待办事项）加上 最后一次变更之后通过的验证来判断。/goal --assure <objective> 与 create_goal 在带有 assure: true 时会先运行计划写入器，这才使 下方那些已执行检查的回执成为完成要求。

没有契约的目标会在它出现的每一处这样标明（/goal view、目标 对话框、控制消息），因此你永远不必去推断它的完成门禁。当被替换的目标拥有有效 契约时，/goal replace 会保留保证。

规划上下文与模型选择

目标规划通过 /goal 和 create_goal 工具继承所选的会话模型。兼容的调用方变体会被保留。只读写入器 会收到最近的原始用户要求与附件引用， 记录预算为 16 KiB。过大的记录会停止纳入更早的记录并给出提示，因此更早的 要求不能悄然替换一条被省略的纠正；内联 媒体内容不会被当作已检查的证据。对于只存在于媒体中的要求，请提供可检查的源 文件。

进展与阻碍

get_goal 包含当前检查状态（已通过、已失败、已过期、运行中或缺失） 以及最近的工具证据 ID。完成门禁仍然要求当前成功的 回执。被阻碍的更新需要阻碍种类、原因、所需的外部变更、 原始证据 ID，以及确认没有剩余的独立工作。阻碍 原因是有可检查记录支持的模型声明，并不是对外部服务仍然不可用的认证。

反复产生不了新的成功工具证据的已结束回合会收到 恢复指导，然后在披露未完成工作的情况下暂停目标。新的研究 结果即使没有源编辑也可以算数；重写待办和重复的相同结果 则不算。这是有界启发式，不是语义进展的证明。/goal resume 会开始另一次尝试。为更早目标生成的工具调用不能终止 其替代目标。工具创建的目标要等模型 在下一步收到创建结果之后，才能用于状态更新。

修订现有计划

使用 /goal revise <correction> 显式修订一个活动、已暂停或被阻碍的 冻结目标。已完成的工作和已耗尽的预算需要一个新目标。先前的 计划和摘要保持完整。修订后的计划获得新的身份，以及一条本地 准备好的修订记录，把两份摘要和这次纠正联系起来。当前 目标身份决定实际安装的是哪一个候选；失败的并发 候选可能留在磁盘上供检查。旧回执留在 历史中，不能满足新修订。token 预算和累计用量会结转； 修订不会授予新的花费预算。

修订会取消当前运行，并在准备新计划时暂停目标。 如果规划失败，先前的契约仍可恢复；先前被阻碍的 目标会保持该状态。规划期间的用户暂停或取消会阻止 激活。并发替换 会阻止该候选接管。模型工具不能悄然修订冻结 要求。请审阅所得计划及其验收标准；仅有一条可执行 命令，并不能确定其断言覆盖了纠正后的请求。

审阅结果与随后的源变更

非空的审阅日志并不能确定审阅成功。对于必需的外部 审阅者，请使用项目自有的检查来验证实际退出码、 终端完成情况、源或差异身份，以及最终发现或明确的 无发现裁决。仅有警告的日志、不完整的推理和超时都必须失败。 把失败的尝试单独保留以便诊断。

新的代码变更提交会拒绝已识别的简单文件存在性检查和查看 检查。这是狭窄的准入防护，不是对任意 shell 命令的语义证明。现有冻结契约保留其模式和摘要；检查点 会在较旧的检查有此弱点时发出警告。

目标检查的新鲜度还会为当前目标期间、成功的 文件编辑工具所报告的已解析文件路径计算指纹，包括每一个 multiedit 结果 以及原始源列表中被省略的路径。之后对这些文件的编辑会使更早的回执失效。 冻结的契约和摘要不变。这种跟踪使用文件工具结果 元数据；它不会推断任意 shell 副作用或测试覆盖。 现有的文件系统包含、链接、大小和文件数限制仍然适用。

检查输出和目标检查点会披露额外路径。如果冻结的测试 命令省略了必要的回归，请请求 /goal revise <correction> 并运行 修订后的检查。把文件纳入指纹只能证明新鲜度，不能证明 某项测试行使了该文件。在规划开放式缺陷清扫时，优先使用有界的源目录，以及 包含新回归的测试命令。

观察到的文件路径会对工作区别名做规范化。外部临时文件不会变成工作区源输入；检查点会披露外部内容未被计算指纹。必需的外部状态仍然需要项目自有的验证。

提交范围证据

非空的 git log <baseline>..HEAD -- <paths> 只能证明某次提交 匹配该过滤器。它不能排除该提交中的无关文件，或 其他提交。新的代码变更计划会拒绝已识别的、独立的、非空且 按路径过滤的 Git 日志断言；较旧的冻结检查会收到修订指导，而不会 改变其摘要或读取时验证。

请使用项目自有的验证器：它检查基线祖先，要求范围非空， 并在不使用路径过滤器的情况下检查每一次提交中的每条已更改路径。 纳入已删除文件和重命名的两侧，显式处理合并提交， 并单独验证任何必需的分支或消息属性。使用 /goal revise 来加强现有契约；不要编辑冻结要求。

计划大小与完整重新提交

渲染后的计划，包括 Markdown 和保证 JSON，必须放进 8,192 个 UTF-8 字节以内。目标是低于 7,168 字节。如果提交超过上限，请缩短 重复文字并重新提交完整对象，包括 kind 和所有 必需字段。保留验收 id 和检查；运行时不会 截断要求，也不会提高读取器上限来接受过大的计划。

本地 CLI 动画审阅回执

仓库自有的 packages/ax-code/script/verify-cli-review-receipts.ts 会检查 round-* 产物，回执根由 --root 选定。每一轮 都需要 revision.txt，并且 grok、claude 和 codex 各自都需要 exit.txt， 其中带有 0，以及 stdout.jsonl（Grok 文本事件）或 stdout.txt（Claude/Codex）中的一份最终裁决。把失败的尝试保留在已完成轮次 目录之外；不要把失败变成退出码为零的回执。

dispositions.json 包含一个 findings 数组。每个条目都写明 round、 cli、id、status（fixed 或 rejected），以及非空白的 evidence。标记为已修复的 条目还需要一个 regression 对象，其中包含字面仓库 路径 file，位于 packages/ax-code/test/cli/tui/ 之下，以及确切的 Vitest fullName。重复的处置或含糊的多重裁决都会失败。

验证器使用已安装的 Vitest 运行这些文件，并把全局重试 默认值设为零（单个测试选项可以覆盖该默认值）， 然后检查每个被引用的断言恰好通过一次。缺失、跳过、 失败或含糊的断言都会使验证失败。这证明那些被引用的 测试通过了，而不是证明它们的断言在语义上覆盖了该发现。被拒绝的 处置仍然是已记录的判断。最终一轮必须匹配当前 HEAD； 标记为已修复的发现需要更新的修订和审阅轮次。未提交的 核心包源、测试或配置变更会阻止验证。把 无关的本地 ax-code.json 配置排除在提交之外。

对于本仓库，vitest run --dir test/cli/tui 在扫描 TUI 目录时保留普通通道的 排除项。分组运行器仍可用 AX_TEST_FILES 选择确切 文件；选择目录并不会禁用排除项。