Skip to main content
关于 Native 的适用场景、四阶段工作流、可恢复状态、内容快照和验证范围的常见问题。

​
基础概念

Native 面向 Fable 5、GPT-5.6 等强编码模型。它保留需求澄清、完整目标规格、状态、验证证据和归档，但让模型按仓库事实和风险选择计划、测试、调试与审查方法。Classic 面向需要更明确过程约束的模型，通过 OpenSpec 与 Superpowers 提供 open、design、build、verify、archive 五阶段治理。选择哪一套由项目配置决定，不由 Comet 根据任务大小临时猜测。详见 Native 工作流。
不依赖。Native 的需求产物、状态机、Guard、恢复和验证协议都由 Comet 自己提供。日常仍统一调用 /comet；它读取 .comet/config.yaml 的 default_workflow 后进入项目选定的永久入口。
Native 用 Shape、Build、Verify、Archive 约束必须完成的结果，而不固定模型采用哪套实现方法。Shape 负责需求与共享理解，Build 负责实现，Verify 负责证据，Archive 负责更新 canonical spec 并封存 change。阶段更少不代表可以跳过需求或验证。Runtime 仍会检查 brief、完整目标规格、用户确认、implementation scope 和验证证据。

​
Shape 与需求澄清

sequential 每轮只问一个最上游决定，适合前一个答案会改变后续问题的需求。batch 会一次提出当前前置条件都已确定的问题，适合各决定相对独立的需求。两种模式都会把答案立即写入 brief，并在进入 Build 前要求用户确认完整共享理解。配置方式见 Native 配置。
单个答案正确，不代表组合后的范围、非目标、默认行为和验收标准没有矛盾。最终确认把用户批准绑定到当时的 brief 与完整目标规格。之后如果 contract 发生变化，旧确认会失效，Native 会重新请求确认。
告诉 Agent 哪些行为需要改变，然后再次调用 /comet。Native 会根据当前 phase、contract 和项目快照决定退回 Build 还是 Shape。不要手工修改 comet-state.yaml 的 phase、approval 或 hash。

​
状态与恢复

再次输入 /comet 继续。Native 从 change 文件、Runtime 状态和当前仓库事实恢复，不依赖原聊天记录。你也可以先运行：
多个 active change 同时存在时，Runtime 会要求明确目标，不会把写入猜到另一个 change。
comet status 用于查看项目有哪些 active change。comet native status <change> --details 展开 phase、阻塞原因、下一动作和有界详情。comet native doctor <change> 检查损坏状态、事务残留和可修复问题；只有明确需要时再使用 --repair。
Brief、完整目标规格和验证报告是用户可读产物，但应让 /comet 在对应阶段协调修改。comet-state.yaml、run-state.json、trajectory、锁、hash、snapshot evidence 和 .comet/current-change.json 都是 Runtime 管理的机器状态，不要手改。

​
内容快照与实现范围

创建 change 时，Native 对纳入范围内的真实文件内容做流式 SHA-256，生成 baseline-manifest.json。它回答“开始实现时项目是什么状态”。Build、Verify 和 check 会创建 current snapshot，回答“同一范围现在是什么状态”。Runtime 比较两者，结合模型提交的项目相对路径形成 implementation scope，并判断验证证据是否仍对应当前实现。
native.snapshot.include 定义这次 change 可以观察的项目路径；exclude 从已纳入路径中剔除明确不属于实现或验证范围的内容。文件必须至少匹配一个 include，并且不能匹配任何 exclude。因此 exclude 最终优先。它们不是随手减少扫描量的隐藏开关，而是会写入 baseline 的可审计范围策略。
Pattern 必须是项目相对路径，使用 /：
  • * 匹配单个目录层级内的任意字符；
  • ** 可以跨越多个目录层级；
  • ? 匹配一个非 / 字符；
  • 不允许绝对路径、反斜杠、空 pattern 或 ..；
  • 不支持用 !pattern 表示排除，请把排除项写进 exclude。
例如 packages/*/src/** 会纳入每个直接子 package 的 src，但不会自动纳入其测试、根锁文件或共享配置。
在 Git 项目中，Git provider 枚举 tracked 与未被 ignore 的 untracked 文件；.gitignore 影响哪些未跟踪文件进入候选集合。exclude 则是 Native change 的显式范围策略，会和 policy hash 一起固化到 baseline。两者用途不同：.gitignore 是仓库级版本控制约定，exclude 是一次 change 的审计边界。即使目录通常被 Git ignore，对大型生成物或数据目录写出明确 exclude，仍能让非 Git provider 和后来维护者理解你的范围意图。
普通项目优先使用完整范围，让 Native 自动观察所有有效项目文件：
这套默认值最不容易遗漏共享配置、测试或锁文件。只有遇到明确的范围或预算问题时再收窄。
同时纳入目标应用、它依赖的共享 package、相关测试和根级构建身份文件：
不要只 include 当前准备修改的源码目录。如果构建、测试或运行时依赖共享 package、根配置或锁文件，也必须纳入。
如果大型数据、生成物和缓存不属于交付范围，可以明确排除，并为剩余真实范围提高预算：
如果大文件本身属于实现或验证范围，应提高预算，不应通过 exclude 隐藏。排除源码、测试或交付所需配置会让 implementation scope 失真。
新建 change 时，Runtime 会规范化 include/exclude，并把 policy 与 policy hash 写入 baseline-manifest.json。后续 current snapshot 始终沿用这套 baseline policy。这能防止实现中途通过修改配置隐藏已经纳入的变化。项目配置的新 policy 只影响之后创建的 change；当前 snapshot 仍可以读取调整后的资源预算，以便在仓库增长后完成原范围。
先问文件是否属于实现或验证范围：
  • 属于范围：提高 max_files、max_total_bytes 或 max_duration_ms；
  • 不属于范围：添加明确的 exclude，并为新的 change 建立可审计 baseline；
  • 不确定：保持纳入，先检查 Runtime 报告的实际限制和受影响路径。
comet native new 在 baseline 不完整时会失败关闭并清理未完成 change，不会留下一个看似可用但范围不可信的 baseline。
不要只修改配置后继续当前 change，因为它的 baseline policy 已经固定。先让 Agent 明确新的实现边界，再创建能够覆盖完整依赖范围的新 baseline。若需求本身也变化，回到 Shape 更新 brief 和规格。

​
Build、Verify 与排障

Native 面向能够根据仓库风险选择方法的强模型，因此约束结果和证据，而不是规定唯一过程。模型仍必须运行与改动风险匹配的测试，记录真实命令与结果，并为每个 Acceptance ID 提供证据或诚实的跳过理由。
旧验证会变成 stale。Native 会受控退回 Build，基于同一 baseline policy 封印新的 implementation scope。只有 brief 或完整目标规格也变化时才重新请求用户确认；仅实现变化不会制造额外确认。
每个 Native change 有独立 baseline、完整目标规格和状态。并发修改造成 canonical spec 或实现基线冲突时，Runtime 会停止并要求 rebase、重新验证或由用户决定范围，不会静默覆盖另一项工作。详见 多 Change 与规格冲突。
先运行：
根据诊断处理预算不足、项目树持续变化、Git index 不稳定或事务残留。不要删除 baseline manifest、手改 omission/evidence，或把不完整快照写成通过。详见 验证证据与自主修复 和 恢复手册。
继续阅读：Native 配置、产物与状态、验证证据与自主修复 和 Native CLI。
最后修改于 2026年7月24日