SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场comet-archive

comet-archive

通用与其它

查看项目

更新于 10-15 15:11

技能介绍

Comet Classic 工作流的第五阶段：归档（Archive）。

用途

用于归档并交付一个已通过验证的 Classic 变更。当用户调用 /comet-archive，或 Classic Runtime 进入 Archive 阶段、恢复交付时使用。完整路径为：头脑风暴 → delta spec → 实现 → 验证 → 主 spec 合并 → 设计文档标注 → 归档。

前置条件

验证已通过，第四阶段已完成；归档或所选交付动作尚未完成（恢复不要求 branch_status 保持 pending）；<classic-change-dir>/.comet.yaml 记录 verify_result: pass。

使用方式

  1. 设定输出语言：使用本次调用入口结果中的 configuration.language，用于归档摘要与完成消息，不单独查询语言。

  2. 校验入口状态：使用 comet CLI 执行 comet state select <change-name> 与 comet state check <name> archive --json。若上一阶段的守卫已返回本阶段状态，则从该状态与 agent.continuation 继续，不重复 select/check；仅在恢复、工作区变更或外部状态变更后执行入口检查。若因 bound_branch 与当前分支不一致而返回 BLOCKED 或分支绑定 ERROR，则按 decision-point.md 暂停，只提供两个选择：回到绑定分支并重跑入口检查，或在用户明确确认由当前分支接管后执行 comet state rebind <change-name> 并重跑入口检查；不得自行切换或重绑分支。

  3. 请用户确认归档与交付：若缺少有效授权或交付目标已变化，按 decision-point.md 暂停并请用户确认。在提问前展示简短摘要，包括变更名称、验证报告路径与结论、当前分支/工作区及各未提交变更归属、不可逆的归档动作（将 delta 合并进主 spec、标注设计文档/计划、将变更移入归档目录），以及归档提交的处理方式。对 Git 协调根，提供单选：A 仅本地归档不推送；B 确认归档并立即推送；C 确认归档、推送并创建 PR；D 调整或重新验证（执行 comet state transition <change-name> archive-reopen 回到 verify 并调用 /comet-verify）；E 暂不归档（保留未归档变更与 phase: archive、branch_status: pending）。若协调根不在 Git 内、产品代码位于独立子仓库，则请用户选择仅归档文档或 D/E。只有用户选择 A/B/C 或明确确认仅归档文档后，才通过 Runtime 保存为 JSON 并确认归档：comet state delivery <change-name> --file <json-path> 与 comet state transition <change-name> archive-confirm。Git 交付 JSON 含 action（A=local、B=push、C=pr）、targetBranch 及可选 remote、commit、prUrl；仅归档文档的 JSON 只含 action: archive-only。targetBranch 是接收归档提交的绑定分支，不是 PR 基分支。示例：{"action": "push", "targetBranch": "<confirmed-bound-branch>", "remote": "<confirmed-remote>"}。输入文件应存放在变更目录之外（如仓库根目录 delivery-input.json），用后删除，绝不可放在变更目录内，尤其不能是 <change-dir>/.comet/delivery.json（那是 Runtime 的交付记录）。归档提交确认后，将实际 commit 加入同一完整记录；action 为 pr 时在创建 PR 后加入实际 prUrl。归档提交后，变更目录必须与该提交保持字节一致，不得增删改其中文件，否则完整性检查失败。

  4. 执行归档：comet archive "<change-name>"。脚本会自动校验入口状态（phase=archive、verify_result=pass、archive_confirmation=confirmed、archived=false），归档前更新设计文档元数据（archived-with、status）与计划元数据（archived-with），调用 OpenSpec archive 合并 delta 到主 spec 并移动变更，检查主 spec 无仅含 delta 的章节标题，更新 OpenSpec 归档目录中的 archived 状态并协调待恢复元数据。非零退出码应报告并停止，零退出码表示归档完成。可用 --dry-run 预览。

  5. 提交归档变更：归档会移动文件并合并 spec，但不提交。预期未提交变更包括：变更从 <classic-change-dir>/ 移动到 <classic-archive-root>/YYYY-MM-DD-<name>/；主 spec 含合并后的 delta；设计文档/计划含归档元数据。确认交付仍记录有效授权后，写入兼容字段并运行最终归档守卫（第二条命令需在第一条成功后执行）：comet state set <change-name> branch_status handled && comet guard <change-name> archive。handled 仅为旧版兼容字段，不授权本地/推送/PR，也不证明这些动作成功。归档后读取 git status --short，与 dirty-worktree 下收集的归属记录核对，只暂存明确属于本次变更的路径（原变更路径、脚本报告的实际归档路径、含 branch_status: handled 的归档 .comet.yaml、本次 delta 改动的主 spec、当前设计文档/计划的归档元数据），使用明确 pathspec 并检查暂存差异，不暂存整个仓库或包含用户既有编辑。按项目格式与语言撰写提交信息后执行：git add -- <individually-verified-archive-paths...>、git diff --cached --stat、git commit -m "<archive message following project conventions>"。提交失败或暂存差异含无关路径则停止。

  6. 交付归档提交并完成：提交成功后通过 state delivery --file 记录实际 commit，再由 Runtime 校验归档提交与目标，只执行已授权未完成的动作；记录失败则停止交付，不再提交。A（本地归档）不执行远程操作，提交保留在绑定分支；B（归档并推送）推送绑定分支一次；C（归档、推送并创建 PR）推送绑定分支一次，再通过配置的 GitHub 集成创建 PR。推送或 PR 调用后用 delivery --verify 检查实际远程分支与 PR；PR 创建成功后通过 delivery --file 记录实际 prUrl 并保留 action、target、commit。超时或响应不确定时先检查实际结果再重试。本地需 Runtime 确认归档提交存在；推送还需远程包含该提交；PR 还需匹配的 PR 与目标。仅填写 commit/prUrl 不算交付成功。仅归档文档路径下：archive 命令会设置 branch_status 为 handled，并记录归档目录内每个文件的 SHA-256 摘要（含最终完整性检查后主 spec 的快照），运行 comet guard <change-name> archive 与 comet state delivery <change-name> --verify，仅当 verification.status 为 complete 且归档目录、主 spec 快照与凭证仍可用时才清除当前选择；该路径跳过 Git 提交、推送与 PR，各子仓库自行提供交付证据。归档文件增删改会使验证变为 needsVerification，应恢复或修复文档，而非覆盖已封存的凭证。

退出条件

归档脚本退出码 0；<classic-archive-root>/YYYY-MM-DD-<change-name>/ 存在；归档 .comet.yaml 记录 archived: true；唯一归档提交在归档状态含 branch_status: handled（archive-only 则含于文件摘要凭证）；comet guard <change-name> archive 通过；归档提交按确认方式处理（A 本地保留、B 推送成功、C 推送并有 PR；archive-only 由 Runtime 校验本地文档凭证）；所选处理完成后清除当前选择。脚本会将 <classic-change-dir>/ 移动到 <classic-archive-root>/YYYY-MM-DD-<name>/，comet guard <change-name> archive 会由原始变更名解析实际归档目录，不要手动构造带日期的目录。

完成后

Comet Classic 工作流完成。新的 Classic 工作用 /comet-classic 或 /comet-open 开始。上下文压缩后恢复：按 context-recovery.md 以 phase archive 恢复，读取已保存的交付记录而非从对话回忆 A/B/C；在 Runtime 检查归档目录、提交、远程与 PR 后，只继续缺失的动作，local 不执行远程操作。若旧变更仅有 handled、缺少授权、目标变化或分支关系与记录不同，应停止并请求明确确认，不要自动推断授权或修复分支关系。

限制

不得自行切换或重绑分支；未获授权前不得运行 archive-confirm 或 archive；不得凭 branch_status: handled 推断归档、推送或 PR 授权；不得编造 commit/prUrl；不得绕过或盲目重试 Git hooks；Archive 阶段不得调用 Superpowers finishing-a-development-branch，也不提供本地合并、分支切换/删除、rebase 或其他分支拓扑变更。