用途:在 OpenSpec 的实验工作流中完成变更的最终归档,适用于实现已结束、需要定稿并归档的变更。
主要能力:选择并宣告目标变更;通过 openspec instructions archive --change "<name>" --json 读取可选上下文;用 openspec status --change "<name>" --json 检查产物与任务完成度;对比 delta 规格与主规格并给出同步摘要;执行归档移动并输出摘要。
必要用法:若使用已注册的 store,先运行 openspec store list --json 获取 id,并在读取或写入 specs、changes 的命令上追加 --store <id>;命令包括 new change、status、instructions、list、show、validate、archive、doctor、context、view。未指定 store 时作用于最近的本地 openspec/ 根目录。归档时先确认变更名,必要时用 openspec list --json 列出活动变更;创建归档目录 mkdir -p "<planningHome.changesDir>/archive",目标名若无 YYYY-MM-DD- 前缀则加上当前日期,再用 mv 移动 changeRoot。
同步与校验:存在 delta 规格时先评估同步状态并展示合并摘要,用户选择同步后需运行 openspec instructions specs --change "<name>" --json,成功后才写入主规格;同步须内联执行并等待完成,随后逐项复核每个 capability 的 ADDED、MODIFIED、REMOVED、RENAMED 结果,不匹配则停止归档。
限制:产物或任务未完成只警告并请求确认,不阻塞归档;instructions archive 查询为可选,失败应继续;规格规则仅约束所写主规格,不作为归档指导;不得在同步进行中归档;归档保留 .openspec.yaml;不要将运行时上下文、操作指导或规则文本原样写入输出文件。