用途
openspec-archive-change 用于在实验性工作流中归档一个已完成的变更。当用户希望在实施完成后最终确定并归档某个变更时,可使用该技能。
主要能力
- 引导用户选择要归档的变更(若未提供变更名,则从可用变更中提示选择)。
- 检查工件(artifacts)完成状态,解析 openspec status --change "<name>" --json 的输出,识别 schemaName 与各工件的状态。
- 检查任务完成状态,读取任务文件(通常为 tasks.md),统计未完成任务(- [ ])与已完成任务(- [x])。
- 评估增量规格(delta specs)同步状态,比较 openspec/changes/<name>/specs/ 下的增量规格与 openspec/specs/<capability>/spec.md 中的主规格,判断将应用的变更(新增、修改、删除、重命名)。
- 执行归档:创建归档目录(mkdir -p openspec/changes/archive),生成目标名称 YYYY-MM-DD-<change-name>,检查目标是否已存在,若不存在则将变更目录移动到归档目录(mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>)。
- 显示归档完成摘要,包括变更名、所用 schema、归档位置、规格是否已同步,以及关于未完成工件/任务的警告说明。
使用方式
- 若未提供变更名,运行 openspec list --json 获取可用变更,使用 AskUserQuestion 工具让用户选择。仅显示活跃变更(未归档的),如可用则包含每个变更所用的 schema。重要:不要猜测或自动选择变更,始终让用户选择。
- 运行 openspec status --change "<name>" --json 检查工件完成状态。若存在未完成工件,显示警告列出未完成工件,并使用 AskUserQuestion 工具确认用户是否继续。用户确认后继续。
- 读取任务文件(通常为 tasks.md)检查未完成任务。若发现未完成任务,显示未完成任务数量警告,并使用 AskUserQuestion 工具确认用户是否继续。用户确认后继续。若不存在任务文件,则跳过任务相关警告直接继续。
- 检查 openspec/changes/<name>/specs/ 下是否存在增量规格。若不存在,跳过同步提示直接继续。若存在,将每个增量规格与其对应的主规格(openspec/specs/<capability>/spec.md)比较,确定将应用的变更(新增、修改、删除、重命名),在提示前显示合并摘要。提示选项:若需要变更,提供“立即同步(推荐)”与“不同步直接归档”;若已同步,提供“立即归档”“仍然同步”“取消”。若用户选择同步,执行 /opsx:sync 逻辑(使用 openspec-sync-specs 技能)。无论选择如何,都继续归档。
- 执行归档:创建归档目录(若不存在),使用当前日期生成目标名称 YYYY-MM-DD-<change-name>,检查目标是否已存在。若已存在,报错并建议重命名现有归档或使用不同日期;若不存在,将变更目录移动到归档目录。
- 显示归档完成摘要,包括变更名、所用 schema、归档位置、规格是否已同步(如适用),以及关于任何警告(未完成工件/任务)的说明。
成功输出示例:
Archive Complete
Change: <change-name> Schema: <schema-name> Archived to: openspec/changes/archive/YYYY-MM-DD-<name>/ Specs: ✓ Synced to main specs(或“No delta specs”或“Sync skipped”)
All artifacts complete. All tasks complete.
适用场景
- 用户希望在变更实施完成后最终确定并归档该变更。
- 需要检查工件与任务完成状态,并在存在未完成项时获得警告与确认。
- 需要评估增量规格与主规格的同步状态,并决定是否同步后再归档。
限制与注意事项
- 若未提供变更名,必须提示用户选择,不得猜测或自动选择。
- 使用工件图(openspec status --json)进行完成检查。
- 不要因警告而阻止归档,只需告知并确认。
- 移动到归档时保留 .openspec.yaml(随目录一起移动)。
- 显示清晰的操作摘要。
- 若请求同步,使用 openspec-sync-specs 方法(代理驱动)。
- 若存在增量规格,始终运行同步评估并在提示前显示合并摘要。
- 关于收费、价格、平台支持等具体信息,资料中暂未提供。