用途:在 OpenSpec 实验工作流中归档一个已完成的变更(change),通常在实现完成后使用。需用户指定变更名;若未指定,应从对话上下文推断,模糊时必须提示用户从可用变更中选择,不要猜测或自动选择。
主要能力:查询可用变更与状态,检查制品(artifacts)与任务完成情况,评估 delta 规格与主规格的同步状态,执行同步后进行校验,最后将变更目录移动到归档目录。
使用方式:多存储(store)场景先运行 openspec store list --json 获取已注册的 store id,并在读取或写入规格与变更的命令(new change、status、instructions、list、show、validate、archive、doctor、context)上追加 --store <id>;其他命令不接受该标志,命令提示中已带的标志应保留到后续命令。无 store 时命令作用于最近的本地 openspec/ 根目录。若未提供变更名,运行 openspec list --json 并用 AskUserQuestion 让用户选择,只显示未归档的活动变更。随后运行 openspec status --change "<name>" --json 检查制品完成状态,解析 schemaName、planningHome、changeRoot、artifactPaths、actionContext 与 artifacts;存在未完成制品时警告并确认。再读取 tasks.md 统计 - [ ] 与 - [x] 数量,存在未完成任务时警告并确认;无任务文件则跳过该警告。
同步评估:用 artifactPaths.specs.existingOutputPaths 判断是否存在 delta 规格。若有,与 <planningHome.root>/openspec/specs/<capability>/spec.md 逐一比较,汇总将要应用的增、改、删、改名,然后提示选择:需要变更时可选“Sync now (recommended)”或“Archive without syncing”;已同步时可选“Archive now”“Sync anyway”“Cancel”。选择 Cancel 则停止;选择不同步或直接归档则进入归档;选择同步则以内联方式运行 openspec-sync-specs 工作流(智能合并)并等待完成,不得放到后台任务,否则归档会移走 changeRoot。随后对每个带 delta 规格的能力重新校验:ADDED 需求存在,MODIFIED 需求带 delta 中的场景与描述且其他场景完整,REMOVED 需求消失,RENAMED 需求以新名存在、旧名不存在。同步失败或校验不符时报告差异并停止,不归档。
归档与限制:在 planningHome.changesDir 下创建 archive 目录:mkdir -p "<planningHome.changesDir>/archive";用当前日期生成 YYYY-MM-DD-<change-name>,若目标已存在则报错并建议改名或换日期,否则 mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"。移动时保留 .openspec.yaml。成功后输出变更名、schema、归档位置、规格是否同步及警告信息。不要因警告阻塞归档,仅提示并确认;绝不在规格同步仍在进行时归档。费用、平台与具体代理实现细节暂未提供。