openspec-archive-change 是 OpenSpec 实验性工作流中的归档步骤技能,用途是在一个变更实现完成后,对其进行最终检查并归档。
用途 当用户希望完成并归档一个已完成的变更时使用。调用时可选择性指定变更名称;若未指定,技能会尝试从对话上下文中推断,若只有一个活动变更则自动选择,若存在歧义则列出可用活动变更并提示用户选择。选定后会公告“Using change: <name>”并说明如何覆盖选择。
主要能力
- Store 选择:若用户指定 store(本机注册的独立 OpenSpec 仓库)或工作位于某个 store 中,可先运行 openspec store list --json 获取已注册 store id,再对读取或写入 specs、changes 的命令追加 --store <id>,选定后在该工作流余下步骤中保持粘性。
- 加载归档输入:运行 openspec instructions archive --change "<name>" --json 获取可选上下文与操作指引;该查询为咨询性质,失败或不支持时不阻塞归档。
- 产物完成检查:通过 openspec status --change "<name>" --json 解析 schemaName、路径上下文与各 artifact 状态;若有未完成且未跳过的产物,列出警告并请求用户确认。
- 任务完成检查:读取 tasks.md,统计未完成(- [ ])与已完成(- [x])任务;存在未完成任务时警告并请求确认;无任务文件则跳过该警告。
- delta 规格同步评估:以状态 JSON 中的 artifactPaths.specs.existingOutputPaths 作为唯一 delta 规格来源,与对应主规格比较,汇总将要应用的增删改重命名,并提示用户选择“立即同步(推荐)/不同步直接归档”或“立即归档/仍然同步/取消”。
- 同步与验证:选择同步时先运行 openspec instructions specs --change "<name>" --json 获取规格规则快照,要求成功返回后才写入主规格;然后内联运行 openspec-sync-specs 工作流完成智能合并,并再次逐项验证每个 delta 能力是否已同步(新增、修改、删除、重命名均需符合预期,能力退役时主规格应被删除)。验证不通过则报告差异并停止,不执行归档。
- 执行归档:在 changesDir 下创建 archive 目录,目标名在变更名不带 YYYY-MM-DD- 前缀时加上当前日期前缀,避免重复叠加日期;检查目标是否已存在,不存在则将 changeRoot 移动到 archive/<target-name>,.openspec.yaml 随目录一起移动。
- 输出摘要:展示变更名、所用 schema、归档位置、规格是否已同步以及任何警告。
使用方式 以技能调用形式触发,按步骤执行上述 CLI 命令与用户确认流程。命令示例中的 --store、--change 等标志需按实际选定值追加。
适用场景 适用于 OpenSpec 变更实现完毕后的收尾归档,尤其是需要先合并 delta 规格到主规格、再移动变更目录的场景;也适用于只是检查产物与任务状态并带警告归档的场景。
限制 归档不会被警告阻塞,但会请求用户确认;同步请求必须内联执行并等待完成,绝不能在规格同步仍在进行时归档;运行时上下文与操作指引仅作为提示级输入,不得逐字写入输出文件;产物规则仅约束被写入的规格内容,不构成归档指引。