跳转到主要内容
所有验收项都通过、change 进入准备归档状态(Archive-ready)后,需要你决定这次归档怎么交付。是否需要这个决定、你会看到哪些选项,取决于创建 change 时选择的工作区。做选择前,Comet 会展示当前分支、目标分支、目录和每个选项的实际影响,你可以当场确认,也可以暂缓。 需要明确接受 Verifier 结果时,Comet 可以同时展示交付选项。你可以一次回复“接受当前结果,仅保留工作区”,或选择本地合并、推送、创建 PR。Agent 会将已选方式带入归档命令,不重复询问相同决定;新增交付操作或实际范围变化仍需确认。

归档前先做一次预检查

进入 Archive-ready 后,Runtime 会在 continuation 中给出预检查或已确认的归档命令。选择交付方式时,对应命令会带上 --finish;已经确认的归档可以在同一次命令中完成预检查和执行前复查,需要核对自定义提交说明时先运行 archive --dry-run。 预检查会同时检查归档内容、当前工作区和生成文件,并在不能继续时列出阻塞原因、涉及路径和下一条确认命令。--dry-run 不会归档、提交、合并或推送;只有预检查确认可以继续时,才执行 Runtime 返回的唯一确认命令。

项目提交规范

Comet 的内置 Git 提交会运行项目 Hook。Agent 会先检查仓库的提交说明规范;有格式要求时,用 --commit-message 设置归档提交说明,选择本地合并时还可以用 --merge-message 设置合并说明。两项参数都支持中文和多行内容,预览会显示实际说明,确认命令和重试会保留它们。用法见 Native 命令概览。

交付选项与工作区类型

创建 change 时,你可以继续使用当前目录,也可以让 Comet 创建分支或 worktree。进入 Archive 时,交付方式取决于这次选择:
  • current 工作区:change 直接在当前分支和目录里完成,归档时不需要选择交付方式。Comet 会展示当前分支和目录,说明归档不做任何 merge、push 或 PR;你确认后直接完成归档。
  • branch / worktree 隔离:change 运行在独立的分支和目录里,归档后是否要合并进目标分支、推送到远端或创建 PR,需要由你决定。Comet 会展示实际的 change 分支、目标分支和目录,把下面五个互斥选项作为一次决策提供。

五个交付选项

选择 A–D 时,Comet 用对应参数执行归档命令(--finish keep|merge|push|pull-request);选 E 则到此为止。整个决策路径如下:

每种选项执行后的 Git 状态

A–D 都会完成归档,并在 change 分支创建归档提交;区别在于归档提交之后的处理:
  • A 仅保留工作区:change 分支多一个归档提交,目标分支不变,分支和目录原样保留。本次归档不会移除保留的 worktree。
  • B 本地合并:change 分支上的归档提交本地合并进目标分支,远端不受影响。
  • C 归档并推送:归档提交随 change 分支一起推送到远端,目标分支不合并、不建 PR。
  • D 推送并创建 PR:推送 change 分支后,以目标分支为 base 创建 PR,之后的合并走 PR 流程。
  • E 暂缓归档:归档和交付都不执行,Git 侧没有任何改动。
选 A 保留的 worktree 不会在本次归档中移除;执行归档的 B、C、D 三个选项归档后,如果 worktree 没有未提交改动,Comet 会提议清理 worktree,由你确认。

归档前的最终确认

归档前是否需要额外一次明确决定,由 native.archive_confirmation 控制,默认是 automatic:
  • automatic:最终 Verify 通过后,Runtime 可以直接继续完成归档。自动归档不替你决定交付方式——使用 branch 或 worktree 时,你仍要在 A–E 里选一个。
  • required:最终 Verify 通过后,Runtime 会停在最终 Archive 候选上,等你就这一次归档做明确决定。中间修复轮次不会触发这个确认;选择暂不归档也会保留当前 active change。
设置见Native 配置 · 归档确认。 required 生效时,Comet 会停在这一步,等你明确同意这次归档;你确认后,它才会执行带 --confirmed 参数的真实归档命令。--dry-run 只预览归档结果,不写入确认。--confirmed 只在该 change 确实停在等待最终确认的 Archive-ready 时才会用到,修复过程中的中间轮次不会要求这个确认。如果等待期间需求或验收标准被修改,change 会先返回 Shape,之前的验证结果和归档批准都会失效。

暂缓归档后如何继续

选 E 之后,change 保持 active,工作区和所有已通过的结果继续保留。下次让 Agent 继续当前 change 时,Runtime 会读回已记录的状态和下一步,把 change 带回 Archive-ready,再展示一次同样的决定。 如果等待期间你修改了可见需求或验收标准,change 会先返回 Shape,重新确认并取得新的验证结果,再回到 Archive。旧的验证结果和归档批准不会沿用。

归档中断与并行 change 的处理

Archive 事务中途中断时,Runtime 会保留事务记录和可执行状态,从已经完成的步骤继续。具体恢复规则见恢复手册。 项目 Hook 拒绝提交或合并说明时,已封存的归档和未完成的 Git 收尾会分别保留。Agent 按项目规范修正尚未完成步骤的说明,再继续原事务,不重复已完成的提交或发布 Spec。恢复沿用原交付选择;需要新的决定时才询问。恢复完成前,Status 仍会显示交付待完成。 多个 active change 声明同一份 Spec 时,Archive 会先要求确定归档顺序,再进入这里的交付选择。排序规则见多 Change 并行与冲突控制。 继续阅读:Native 产物与状态、多 Change 并行与冲突控制 和 恢复手册。
最后修改于 2026年10月3日