> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Native 常见问题

> 解答 Native 模式选择、需求澄清、状态恢复、内容快照、include/exclude、验证与冲突处理的常见问题。

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

## 基础概念

<AccordionGroup>
  <Accordion title="Native 和 Classic 应该怎么选">
    Native 面向 Fable 5、GPT-5.6 等强编码模型。它保留需求澄清、完整目标规格、状态、验证证据和归档，但让模型按仓库事实和风险选择计划、测试、调试与审查方法。

    Classic 面向需要更明确过程约束的模型，通过 OpenSpec 与 Superpowers 提供 open、design、build、verify、archive 五阶段治理。选择哪一套由项目配置决定，不由 Comet 根据任务大小临时猜测。详见 [Native 工作流](/zh/concepts/native-workflow)。
  </Accordion>

  <Accordion title="Native 是否依赖 OpenSpec、Superpowers 或其他外部 Skill">
    不依赖。Native 的需求产物、状态机、Guard、恢复和验证协议都由 Comet 自己提供。日常仍统一调用
    `/comet`；它读取 `.comet/config.yaml` 的 `default_workflow` 后进入项目选定的永久入口。
  </Accordion>

  <Accordion title="为什么 Native 只有四个阶段">
    Native 用 Shape、Build、Verify、Archive 约束必须完成的结果，而不固定模型采用哪套实现方法。Shape 负责需求与共享理解，Build 负责实现，Verify 负责证据，Archive 负责更新 canonical spec 并封存 change。

    阶段更少不代表可以跳过需求或验证。Runtime 仍会检查 brief、完整目标规格、用户确认、implementation scope 和验证证据。
  </Accordion>
</AccordionGroup>

## Shape 与需求澄清

<AccordionGroup>
  <Accordion title="Sequential 和 Batch 澄清模式有什么区别">
    `sequential` 每轮只问一个最上游决定，适合前一个答案会改变后续问题的需求。`batch` 会一次提出当前前置条件都已确定的问题，适合各决定相对独立的需求。

    两种模式都会把答案立即写入 brief，并在进入 Build 前要求用户确认完整共享理解。配置方式见 [Native 配置](/zh/native/configuration)。
  </Accordion>

  <Accordion title="为什么问题都回答完了还要确认共享理解">
    单个答案正确，不代表组合后的范围、非目标、默认行为和验收标准没有矛盾。最终确认把用户批准绑定到当时的
    brief 与完整目标规格。之后如果 contract 发生变化，旧确认会失效，Native 会重新请求确认。
  </Accordion>

  <Accordion title="实现过程中改变需求怎么办">
    告诉 Agent 哪些行为需要改变，然后再次调用 `/comet`。Native 会根据当前 phase、contract 和项目快照决定退回 Build 还是 Shape。不要手工修改 `comet-state.yaml` 的 phase、approval 或 hash。
  </Accordion>
</AccordionGroup>

## 状态与恢复

<AccordionGroup>
  <Accordion title="会话中断后如何继续">
    再次输入 `/comet 继续`。Native 从 change 文件、Runtime 状态和当前仓库事实恢复，不依赖原聊天记录。你也可以先运行：

    ```bash theme={null}
    comet status
    comet native status <change-name> --details
    ```

    多个 active change 同时存在时，Runtime 会要求明确目标，不会把写入猜到另一个 change。
  </Accordion>

  <Accordion title="status、status --details 和 doctor 分别什么时候用">
    `comet status` 用于查看项目有哪些 active change。`comet native status <change> --details` 展开 phase、阻塞原因、下一动作和有界详情。`comet native doctor <change>` 检查损坏状态、事务残留和可修复问题；只有明确需要时再使用 `--repair`。
  </Accordion>

  <Accordion title="哪些文件可以手工修改">
    Brief、完整目标规格和验证报告是用户可读产物，但应让 `/comet` 在对应阶段协调修改。`comet-state.yaml`、`run-state.json`、trajectory、锁、hash、snapshot evidence 和 `.comet/current-change.json` 都是 Runtime 管理的机器状态，不要手改。
  </Accordion>
</AccordionGroup>

## 内容快照与实现范围

<AccordionGroup>
  <Accordion title="baseline snapshot 和 current snapshot 分别是什么">
    创建 change 时，Native 对纳入范围内的真实文件内容做流式 SHA-256，生成 `baseline-manifest.json`。它回答“开始实现时项目是什么状态”。

    Build、Verify 和 check 会创建 current snapshot，回答“同一范围现在是什么状态”。Runtime 比较两者，结合模型提交的项目相对路径形成 implementation scope，并判断验证证据是否仍对应当前实现。
  </Accordion>

  <Accordion title="include 和 exclude 有什么作用">
    `native.snapshot.include` 定义这次 change 可以观察的项目路径；`exclude` 从已纳入路径中剔除明确不属于实现或验证范围的内容。

    文件必须至少匹配一个 `include`，并且不能匹配任何 `exclude`。因此 `exclude` 最终优先。它们不是随手减少扫描量的隐藏开关，而是会写入 baseline 的可审计范围策略。
  </Accordion>

  <Accordion title="glob 应该怎么写">
    Pattern 必须是项目相对路径，使用 `/`：

    * `*` 匹配单个目录层级内的任意字符；
    * `**` 可以跨越多个目录层级；
    * `?` 匹配一个非 `/` 字符；
    * 不允许绝对路径、反斜杠、空 pattern 或 `..`；
    * 不支持用 `!pattern` 表示排除，请把排除项写进 `exclude`。

    例如 `packages/*/src/**` 会纳入每个直接子 package 的 `src`，但不会自动纳入其测试、根锁文件或共享配置。
  </Accordion>

  <Accordion title=".gitignore 和 snapshot exclude 有什么区别">
    在 Git 项目中，Git provider 枚举 tracked 与未被 ignore 的 untracked 文件；`.gitignore` 影响哪些未跟踪文件进入候选集合。`exclude` 则是 Native change 的显式范围策略，会和 policy hash 一起固化到 baseline。

    两者用途不同：`.gitignore` 是仓库级版本控制约定，`exclude` 是一次 change 的审计边界。即使目录通常被 Git ignore，对大型生成物或数据目录写出明确 exclude，仍能让非 Git provider 和后来维护者理解你的范围意图。
  </Accordion>

  <Accordion title="普通项目怎么配置">
    普通项目优先使用完整范围，让 Native 自动观察所有有效项目文件：

    ```yaml theme={null}
    native:
      snapshot:
        include:
          - '**/*'
        exclude: []
        max_files: 10000
        max_total_bytes: 268435456
        max_duration_ms: 60000
    ```

    这套默认值最不容易遗漏共享配置、测试或锁文件。只有遇到明确的范围或预算问题时再收窄。
  </Accordion>

  <Accordion title="Monorepo 怎么配置">
    同时纳入目标应用、它依赖的共享 package、相关测试和根级构建身份文件：

    ```yaml theme={null}
    native:
      snapshot:
        include:
          - 'apps/web/**'
          - 'packages/ui/**'
          - 'packages/config/**'
          - 'package.json'
          - 'pnpm-lock.yaml'
          - 'pnpm-workspace.yaml'
        exclude:
          - 'apps/web/dist/**'
          - 'apps/web/coverage/**'
        max_files: 20000
        max_total_bytes: 536870912
        max_duration_ms: 90000
    ```

    不要只 include 当前准备修改的源码目录。如果构建、测试或运行时依赖共享 package、根配置或锁文件，也必须纳入。
  </Accordion>

  <Accordion title="大型仓库怎么配置">
    如果大型数据、生成物和缓存不属于交付范围，可以明确排除，并为剩余真实范围提高预算：

    ```yaml theme={null}
    native:
      snapshot:
        include:
          - '**/*'
        exclude:
          - 'data/generated/**'
          - 'artifacts/benchmarks/**'
          - 'dist/**'
          - 'coverage/**'
          - '.cache/**'
        max_files: 50000
        max_total_bytes: 1073741824
        max_duration_ms: 120000
    ```

    如果大文件本身属于实现或验证范围，应提高预算，不应通过 exclude 隐藏。排除源码、测试或交付所需配置会让 implementation scope 失真。
  </Accordion>

  <Accordion title="为什么修改配置没有改变已有 change 的范围">
    新建 change 时，Runtime 会规范化 include/exclude，并把 policy 与 policy hash 写入 `baseline-manifest.json`。后续 current snapshot 始终沿用这套 baseline policy。

    这能防止实现中途通过修改配置隐藏已经纳入的变化。项目配置的新 policy 只影响之后创建的 change；当前 snapshot 仍可以读取调整后的资源预算，以便在仓库增长后完成原范围。
  </Accordion>

  <Accordion title="snapshot 超预算时应该提高预算还是排除文件">
    先问文件是否属于实现或验证范围：

    * 属于范围：提高 `max_files`、`max_total_bytes` 或 `max_duration_ms`；
    * 不属于范围：添加明确的 exclude，并为新的 change 建立可审计 baseline；
    * 不确定：保持纳入，先检查 Runtime 报告的实际限制和受影响路径。

    `comet native new` 在 baseline 不完整时会失败关闭并清理未完成 change，不会留下一个看似可用但范围不可信的 baseline。
  </Accordion>

  <Accordion title="被 exclude 的文件后来变成实现依赖怎么办">
    不要只修改配置后继续当前 change，因为它的 baseline policy 已经固定。先让 Agent 明确新的实现边界，再创建能够覆盖完整依赖范围的新 baseline。若需求本身也变化，回到 Shape 更新 brief 和规格。
  </Accordion>
</AccordionGroup>

## Build、Verify 与排障

<AccordionGroup>
  <Accordion title="为什么 Native 不强制 TDD、固定计划或固定 review 方法">
    Native 面向能够根据仓库风险选择方法的强模型，因此约束结果和证据，而不是规定唯一过程。模型仍必须运行与改动风险匹配的测试，记录真实命令与结果，并为每个 Acceptance ID 提供证据或诚实的跳过理由。
  </Accordion>

  <Accordion title="Verify 中发现项目又变了会怎样">
    旧验证会变成 stale。Native 会受控退回 Build，基于同一 baseline policy 封印新的 implementation
    scope。只有 brief 或完整目标规格也变化时才重新请求用户确认；仅实现变化不会制造额外确认。
  </Accordion>

  <Accordion title="多个 change 修改同一文件怎么办">
    每个 Native change 有独立 baseline、完整目标规格和状态。并发修改造成 canonical spec
    或实现基线冲突时，Runtime 会停止并要求
    rebase、重新验证或由用户决定范围，不会静默覆盖另一项工作。详见 [多 Change
    与规格冲突](/zh/native/multi-change-and-conflicts)。
  </Accordion>

  <Accordion title="快照或状态异常时如何排查">
    先运行：

    ```bash theme={null}
    comet native status <change-name> --details
    comet native doctor <change-name>
    ```

    根据诊断处理预算不足、项目树持续变化、Git index 不稳定或事务残留。不要删除 baseline manifest、手改 omission/evidence，或把不完整快照写成通过。详见 [验证证据与自主修复](/zh/native/verification-and-repair) 和 [恢复手册](/zh/native/recovery-playbook)。
  </Accordion>
</AccordionGroup>

继续阅读：[Native 配置](/zh/native/configuration)、[产物与状态](/zh/native/artifacts-and-state)、[验证证据与自主修复](/zh/native/verification-and-repair) 和 [Native CLI](/zh/cli/native)。