openspec-bulk-archive-change

在单个操作中归档多个已完成的变更。

此技能允许您批量归档变更，通过检查代码库以确定实际实现了什么来智能处理规格说明冲突。

输入：无需要求（会提示选择）

步骤

获取活动变更

运行 openspec list --json 获取所有活动变更。

如果不存在活动变更，通知用户并停止。

提示变更选择

使用 AskUserQuestion 工具进行多选，让用户选择变更：

显示每个变更及其 Schema
包含"所有变更"选项
允许任意数量的选择（1+ 可用，2+ 是典型用例）

重要提示：不要自动选择。始终让用户选择。

批量验证 - 收集所有选定变更的状态

对于每个选定的变更，收集：

a. 产出物状态 - 运行 openspec status --change "<name>" --json

解析 schemaName 和 artifacts 列表
注意哪些产出物是 done 状态而非其他状态

b. 任务完成度 - 读取 openspec/changes/<name>/tasks.md

统计 - [ ] （未完成）与 - [x] （已完成）
如果不存在任务文件，标注为"无任务"

c. 增量规格说明 - 检查 openspec/changes/<name>/specs/ 目录

列出存在哪些能力规格说明
对于每个，提取需求名称（匹配 ### Requirement: <name> 的行）

检测规格说明冲突

构建 capability -> [涉及它的变更] 映射：

auth -> [change-a, change-b] <- 冲突（2+ 个变更） api -> [change-c] <- 正常（仅 1 个变更）

当 2+ 个选定的变更具有相同能力的增量规格说明时，存在冲突。

代理式解决冲突

对于每个冲突，调查代码库：

a. 读取增量规格说明从每个冲突的变更中了解每个声称添加/修改的内容

b. 搜索代码库寻找实现证据：

查找实现每个增量规格说明中需求的代码
检查相关文件、函数或测试

c. 确定解决方案：

如果只有一个变更实际实现 -> 同步该变更的规格说明
如果两者都实现 -> 按时间顺序应用（旧的先，新的覆盖）
如果两者都未实现 -> 跳过规格说明同步，警告用户

d. 记录解决方案对于每个冲突：

应用哪个变更的规格说明
按什么顺序（如果两者都有）
原理（在代码库中找到了什么）

显示合并状态表

显示汇总所有变更的表：

变更	产出物	任务	规格说明	冲突	状态
schema-management	完成	5/5	2 增量	无	就绪
project-config	完成	3/3	1 增量	无	就绪
add-oauth	完成	4/4	1 增量	auth (!)	就绪*
add-verify-skill	剩余 1	2/5	无	无	警告

对于冲突，显示解决方案：

冲突解决方案：
- auth 规格说明：将先应用 add-oauth 然后 add-jwt（两者都已实现，按时间顺序）

对于未完成的变更，显示警告：

警告：

add-verify-skill：1 个未完成产出物，3 个未完成任务

确认批量操作

使用 AskUserQuestion 工具进行单次确认：

"归档 N 个变更？"根据状态提供选项
选项可能包括：
"归档所有 N 个变更"
"仅归档 N 个就绪变更（跳过未完成的）"
"取消"

如果存在未完成的变更，请明确说明它们将带着警告被归档。

对每个确认的变更执行归档

按确定的顺序处理变更（遵循冲突解决方案）：

a. 如果存在增量规格说明则同步规格说明：

使用 openspec-sync-specs 方法（代理驱动的智能合并）
对于冲突，按已解决的顺序应用
跟踪是否已完成同步

b. 执行归档：

mkdir -p openspec/changes/archive mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

c. 跟踪每个变更的结果：

成功：成功归档
失败：归档期间出错（记录错误）
跳过：用户选择不归档（如适用）

显示摘要

显示最终结果：

批量归档完成

已归档 3 个变更：

schema-management-cli -> archive/2026-01-19-schema-management-cli/
project-config -> archive/2026-01-19-project-config/
add-oauth -> archive/2026-01-19-add-oauth/

跳过 1 个变更：

add-verify-skill（用户选择不归档未完成的）

规格说明同步摘要：

4 个增量规格说明已同步到主规格说明
1 个冲突已解决（auth：按时间顺序应用两者）

如果有任何失败：

失败 1 个变更：

冲突解决示例

示例 1：仅一个已实现

冲突：specs/auth/spec.md 被 [add-oauth, add-jwt] 涉及

检查 add-oauth：

增量添加"OAuth 提供商集成"需求
搜索代码库... 找到 src/auth/oauth.ts 实现 OAuth 流程

检查 add-jwt：

增量添加"JWT 令牌处理"需求
搜索代码库... 未找到 JWT 实现

解决方案：仅 add-oauth 已实现。将仅同步 add-oauth 规格说明。

示例 2：两者都已实现

冲突：specs/api/spec.md 被 [add-rest-api, add-graphql] 涉及

检查 add-rest-api（创建于 2026-01-10）：

增量添加"REST 端点"需求
搜索代码库... 找到 src/api/rest.ts

检查 add-graphql（创建于 2026-01-15）：

增量添加"GraphQL 架构"需求
搜索代码库... 找到 src/api/graphql.ts

解决方案：两者都已实现。将先应用 add-rest-api 规格说明，然后应用 add-graphql 规格说明（按时间顺序，较新的优先）。

成功时的输出

批量归档完成

已归档 N 个变更：

<change-1> -> archive/YYYY-MM-DD-<change-1>/
<change-2> -> archive/YYYY-MM-DD-<change-2>/

规格说明同步摘要：

N 个增量规格说明已同步到主规格说明
无冲突（或：M 个冲突已解决）

部分成功时的输出

批量归档完成（部分）

已归档 N 个变更：

<change-1> -> archive/YYYY-MM-DD-<change-1>/

跳过 M 个变更：

<change-2>（用户选择不归档未完成的）

失败 K 个变更：

没有变更时的输出

无需归档的变更

未找到活动变更。使用 /opsx:new 创建新变更。

防护措施

允许任意数量的变更（1+ 可以，2+ 是典型用例）
始终提示选择，永不自动选择
及早检测规格说明冲突并通过检查代码库解决
当两个变更都已实现时，按时间顺序应用规格说明
仅当实现缺失时跳过规格说明同步（警告用户）
在确认前显示清晰的每个变更状态
对整个批次使用单次确认
跟踪并报告所有结果（成功/跳过/失败）
移动到归档时保留 .openspec.yaml
归档目录目标使用当前日期：YYYY-MM-DD-
如果归档目标已存在，该变更失败但继续处理其他变更