---
name: openspec-bulk-archive-change
description: Archive multiple completed changes at once. Use when archiving several parallel changes.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.1.1"
---

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

该技能允许你批量归档变更,通过检查代码库来确定实际实现的内容,智能地处理 spec 冲突。

**输入**: 无需输入 (会提示选择)

**步骤**

1. **获取活跃的变更**

   运行 `openspec list --json` 获取所有活跃的变更。

   如果不存在活跃的变更,通知用户并停止。

2. **提示变更选择**

   使用 **AskUserQuestion 工具**进行多选,让用户选择变更:
   - 显示每个变更及其 schema
   - 包含"所有变更"选项
   - 允许任意数量的选择 (1+ 即可,2+ 是典型用例)

   **重要**: 不要自动选择。始终让用户选择。

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

   对于每个选定的变更,收集:

   a. **Artifact 状态** - 运行 `openspec status --change "<name>" --json`
      - 解析 `schemaName` 和 `artifacts` 列表
      - 注意哪些 artifacts 是 `done` 状态 vs 其他状态

   b. **任务完成度** - 读取 `openspec/changes/<name>/tasks.md`
      - 统计 `- [ ]` (未完成) vs `- [x]` (已完成)
      - 如果不存在任务文件,注明 "无任务"

   c. **Delta specs** - 检查 `openspec/changes/<name>/specs/` 目录
      - 列出存在哪些 capability specs
      - 对于每个,提取需求名称 (匹配 `### Requirement: <name>` 的行)

4. **检测 spec 冲突**

   建立 `capability -> [涉及它的变更]` 映射:

   ```
   auth -> [change-a, change-b]  <- 冲突 (2+ 个变更)
   api  -> [change-c]            <- 正常 (只有 1 个变更)
   ```

   当 2+ 个选定的变更对同一个 capability 有 delta specs 时,存在冲突。

5. **智能解决冲突**

   **对于每个冲突**,调查代码库:

   a. **读取 delta specs** 从每个冲突的变更中,了解每个声称添加/修改的内容

   b. **搜索代码库**寻找实现证据:
      - 寻找实现每个 delta spec 需求的代码
      - 检查相关的文件、函数或测试

   c. **确定解决方案**:
      - 如果只有一个变更实际实现了 -> 同步那个的 specs
      - 如果两者都实现了 -> 按时间顺序应用 (较旧的先,较新的覆盖)
      - 如果都未实现 -> 跳过 spec 同步,警告用户

   d. **记录解决方案**对于每个冲突:
      - 应用哪个变更的 specs
      - 以什么顺序 (如果两者都有)
      - 理由 (在代码库中找到了什么)

6. **显示综合状态表**

   显示总结所有变更的表格:

   ```
   | 变更                | Artifacts | 任务  | Specs   | 冲突      | 状态   |
   |--------------------|-----------|-------|---------|-----------|--------|
   | schema-management  | 完成      | 5/5   | 2 delta | 无        | 就绪   |
   | project-config     | 完成      | 3/3   | 1 delta | 无        | 就绪   |
   | add-oauth          | 完成      | 4/4   | 1 delta | auth (!)  | 就绪*  |
   | add-verify-skill   | 剩余 1    | 2/5   | 无      | 无        | 警告   |
   ```

   对于冲突,显示解决方案:
   ```
   * 冲突解决:
     - auth spec: 将应用 add-oauth 然后 add-jwt (两者都已实现,按时间顺序)
   ```

   对于未完成的变更,显示警告:
   ```
   警告:
   - add-verify-skill: 1 个未完成 artifact, 3 个未完成任务
   ```

7. **确认批量操作**

   使用 **AskUserQuestion 工具**进行单次确认:

   - "归档 N 个变更?" 根据状态提供选项
   - 选项可能包括:
     - "归档所有 N 个变更"
     - "仅归档 N 个就绪的变更 (跳过未完成的)"
     - "取消"

   如果有未完成的变更,明确说明它们将带警告归档。

8. **为每个确认的变更执行归档**

   按确定的顺序处理变更 (遵循冲突解决方案):

   a. **同步 specs** 如果存在 delta specs:
      - 使用 openspec-sync-specs 方法 (代理驱动的智能合并)
      - 对于冲突,按已解决的顺序应用
      - 跟踪是否完成同步

   b. **执行归档**:
      ```bash
      mkdir -p openspec/changes/archive
      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
      ```

   c. **跟踪结果**对于每个变更:
      - 成功: 成功归档
      - 失败: 归档期间出错 (记录错误)
      - 跳过: 用户选择不归档 (如果适用)

9. **显示摘要**

   显示最终结果:

   ```
   ## 批量归档完成

   已归档 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 (用户选择不归档未完成的)

   Spec 同步摘要:
   - 4 个 delta specs 同步到主 specs
   - 1 个冲突已解决 (auth: 按时间顺序应用两者)
   ```

   如果有任何失败:
   ```
   失败 1 个变更:
   - some-change: 归档目录已存在
   ```

**冲突解决示例**

示例 1: 只有一个已实现
```
冲突: specs/auth/spec.md 被 [add-oauth, add-jwt] 涉及

检查 add-oauth:
- Delta 添加了 "OAuth 提供者集成" 需求
- 搜索代码库... 找到 src/auth/oauth.ts 实现 OAuth 流程

检查 add-jwt:
- Delta 添加了 "JWT 令牌处理" 需求
- 搜索代码库... 未找到 JWT 实现

解决: 只有 add-oauth 已实现。将仅同步 add-oauth specs。
```

示例 2: 两者都已实现
```
冲突: specs/api/spec.md 被 [add-rest-api, add-graphql] 涉及

检查 add-rest-api (创建于 2026-01-10):
- Delta 添加了 "REST 端点" 需求
- 搜索代码库... 找到 src/api/rest.ts

检查 add-graphql (创建于 2026-01-15):
- Delta 添加了 "GraphQL Schema" 需求
- 搜索代码库... 找到 src/api/graphql.ts

解决: 两者都已实现。将先应用 add-rest-api specs,
然后应用 add-graphql specs (按时间顺序,较新的优先)。
```

**成功时的输出**

```
## 批量归档完成

已归档 N 个变更:
- <change-1> -> archive/YYYY-MM-DD-<change-1>/
- <change-2> -> archive/YYYY-MM-DD-<change-2>/

Spec 同步摘要:
- N 个 delta specs 同步到主 specs
- 无冲突 (或: M 个冲突已解决)
```

**部分成功时的输出**

```
## 批量归档完成 (部分)

已归档 N 个变更:
- <change-1> -> archive/YYYY-MM-DD-<change-1>/

跳过 M 个变更:
- <change-2> (用户选择不归档未完成的)

失败 K 个变更:
- <change-3>: 归档目录已存在
```

**无变更时的输出**

```
## 无变更可归档

未找到活跃的变更。使用 `/opsx-new` 创建新变更。
```

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