SuperAPI AI 工具集

openspec-archive-change

部署与运维

查看项目

更新于 10-20 10:05

技能介绍

用途

openspec-archive-change 用于在实验性工作流中归档一个已完成的变更。它适用于变更实现完成之后,用户希望正式收尾并归档该变更的场景。

主要能力

  1. 变更选择:如果未提供变更名称,技能会运行 openspec list --json 获取可用变更,并通过 AskUserQuestion 工具让用户选择;只显示尚未归档的活动变更,并尽可能列出每个变更所用的 schema。资料明确要求不得猜测或自动选择变更,必须由用户选择。
  2. 产出物完成状态检查:运行 openspec status --change "<name>" --json,解析 schemaName、planningHome、changeRoot、artifactPaths、actionContext 及各 artifact 的状态。若存在未完成的产出物,则显示警告并请用户确认是否继续。若状态显示 actionContext.mode: "workspace-planning",则说明当前切片不支持 workspace 归档,应立即停止,不将 workspace 变更移入仓库本地归档,也不编辑关联仓库。
  3. 任务完成状态检查:读取任务文件(通常是 tasks.md),统计 - [ ](未完成)与 - [x](已完成)的任务数量;若存在未完成任务,显示数量警告并请用户确认。若没有任务文件,则跳过该警告直接继续。
  4. delta spec 同步评估:通过 status JSON 中的 artifactPaths.specs.existingOutputPaths 检查是否存在 delta spec。若存在,则与 openspec/specs/<capability>/spec.md 对应的主规范逐项比较,判断将要应用的增加、修改、删除、重命名等变化,并在提示前展示汇总。提供选项:需要变更时为“立即同步(推荐)”或“不同步直接归档”;已同步时为“立即归档”“仍然同步”或“取消”。若用户选择同步,则通过 Task 工具调用 openspec-sync-specs。无论选择如何,都会继续归档。
  5. 执行归档:在 planningHome.changesDir 下创建 archive 目录(如不存在),以当前日期生成 YYYY-MM-DD-<change-name> 目标名;若目标已存在则报错并建议重命名现有归档或更换日期;否则将 changeRoot 移动到该归档目录。.openspec.yaml 会随目录一起移动而被保留。
  6. 输出摘要:成功后显示归档完成摘要,包括变更名称、使用的 schema、归档位置(由 planningHome.changesDir/YYYY-MM-DD-<name>/ 推导)、规范是否已同步,以及未完成产出物/任务相关的警告说明。

使用方式

调用该技能时可选择性提供变更名称;未提供时由技能提示选择。归档流程按上述步骤依次执行,涉及的命令包括 openspec list --json、openspec status --change "<name>" --json、mkdir -p "<planningHome.changesDir>/archive" 与 mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"。

适用场景

适用于采用 OpenSpec 规范驱动工作流、需要在变更实现完成后进行收尾归档的团队与个人开发者,尤其是希望同时核对产出物、任务完成度并处理规范同步的情况。

限制与注意事项

  • 未提供变更名称时必须由用户选择,不得自动猜测。
  • workspace-planning 模式下不支持归档,遇到即停止。
  • 未完成的产出物或任务不会阻止归档,只会给出警告并要求确认。
  • 归档目标目录已存在时会直接失败。
  • 关于收费、价格、平台支持范围等信息,资料暂未提供。