OpenSpec 批量归档实战：PeerBanHelper 仓库 OPSX 工作流中的 Bulk Archive 全解析

• 网络安全
• 后端

本文基于 PeerBanHelper 仓库中 OPSX 实验工作流的核心操作命令文档，系统讲解如何用openspecCLI 与 Agent 协作，在一次操作中批量归档多个已完成变更（change），并妥善处理多个变更之间的 spec 冲突。读完本文，你将掌握从"列出活动变更"到"智能解析冲突、同步 delta spec、执行归档、输出汇总"的完整批量归档方案，并理解其与单条归档、spec 同步等命令的协作关系。

背景：OPSX 工作流与批量归档的定位

PeerBanHelper 仓库的 .claude/commands/opsx/ 目录下维护着一组以/opsx:*形式触发的 Claude Code 命令，用于支撑一套实验性（experimental）的 OpenSpec 规范驱动开发工作流。与之配套的 .claude/skills/ 目录存放了功能等价的 skill 定义（如openspec-bulk-archive-change、openspec-sync-specs、openspec-archive-change等），二者共享同一套步骤与守则。仓库根目录的 openspec/config.yaml 声明了工作流采用的 schema 为spec-driven，并预留了context（项目背景）与rules（按 artifact 类型的规则）两个可选配置位。

在 OpenSpec 规范驱动流程中，一次变更（change）从openspec new change "<name>"创建开始，依次产出 proposal、specs、design、tasks 等 artifact，经 apply（实现）与 verify（校验）后最终归档。当多个变更并行开发并先后完成时，逐条执行/opsx:archive效率低下，此时便需要批量归档（Bulk Archive）：一次操作归档多条变更，并对"多个变更同时改动同一 capability 规范"的情况做智能化冲突解析。

本文讲解的核心命令文档为 .claude/commands/opsx/bulk-archive.md，其对应 skill 定义为 .claude/skills/openspec-bulk-archive-change/SKILL.md。

一、批量归档的整体流程概览

批量归档命令不需要任何输入参数，Agent 会通过交互提问引导用户逐步完成。整个操作分为 9 个阶段：

该命令允许归档任意数量的变更（1 个即可运行，2 个及以上是典型使用场景），且绝不自动选择——每一步选择权都在用户手中。

二、第 1–2 步：列出活动变更并让用户选择

流程的第一步是获取当前所有活动变更：

openspec list --json

如果不存在任何活动变更，Agent 应当告知用户并立即停止，输出参考模板：

## No Changes to Archive No active changes found. Use `/opsx:new` to create a new change.

当存在活动变更时，Agent 使用AskUserQuestion 工具以多选方式让用户挑选要归档的变更：

• 每个变更要展示其使用的 schema；
• 提供"全部变更（All changes）"选项；
• 允许任意数量的选择（1 个以上即可，2 个及以上是典型场景）。

重要约束：IMPORTANT: Do NOT auto-select. Always let the user choose.——即使用户只提到一个变更，也不能跳过选择直接归档。这与单条归档命令 .claude/commands/opsx/archive.md 的"不得猜测或自动选择"守则一脉相承。

三、第 3 步：批量校验——为每个选中变更收集三类状态

选定变更后，Agent 需要为每一个被选中的变更收集三类信息，作为后续冲突检测与状态汇总的依据。

a. Artifact 完成状态

openspec status --change "<name>" --json

解析 JSON 中的两个关键字段：

• schemaName：该变更使用的工作流 schema（如spec-driven、tdd）；
• artifacts：artifact 列表及其状态，需要标记哪些为done、哪些处于其他状态（ready/blocked等）。

从openspec status的用法可以看出，它与 .claude/commands/opsx/new.md 中"展示 artifact 状态"、.claude/commands/opsx/apply.md 中"解析 schema 与 artifact"使用的是同一个命令形态，是整条 OPSX 工作流中读取变更状态的统一入口。

b. 任务完成度

读取变更目录下的任务清单：

openspec/changes/<name>/tasks.md

统计清单中的任务完成情况：

• - [ ]计为未完成；
• - [x]计为已完成；
• 如果 tasks 文件不存在，记为 "No tasks"（无任务，不产生任务相关警告）。

c. Delta spec 清单

检查变更目录下的 delta spec 子目录：

openspec/changes/<name>/specs/

• 列出存在哪些 capability 的 delta spec；
• 对每个 delta spec，提取需求名称——即匹配### Requirement: <name>的行。

这里的 delta spec 目录结构与 .claude/skills/openspec-sync-specs/SKILL.md 描述的openspec/changes/<name>/specs/<capability>/spec.md布局一致，是后续冲突检测和 spec 同步的共同数据来源。

四、第 4 步：检测 spec 冲突

将收集到的 delta spec 信息汇总，构建一张"能力 → 改动它的变更"映射表：

auth -> [change-a, change-b] <- CONFLICT (2+ changes) api -> [change-c] <- OK (only 1 change)

冲突判据：当2 个及以上被选中的变更针对同一个 capability提供了 delta spec 时，即判定为冲突。只有 1 个变更触碰的能力（如示例中的api）不构成冲突。

这一步的意义在于尽早暴露问题：如果两个变更分别向同一个主规范（main spec）添加/修改了需求，直接先后归档会导致后一个覆盖前一个，丢失信息。

五、第 5 步：Agent 化冲突解析

对于每个检测到的冲突，Agent 需要"动手调查代码库"来判定实际实现情况，而不是机械合并：

1. 读取 delta spec：阅读每个冲突变更的 delta spec，理解各自声称添加/修改了哪些需求；
2. 检索代码库实现证据：搜索与各 delta spec 需求对应的实现代码，查找相关文件、函数或测试；
3. 确定解析策略，按以下优先级判定：
   • 只有一个变更实际实现了 → 只同步该变更的 spec；
   • 两个都实现了 → 按时间先后顺序应用（旧的在前、新的在后覆盖）；
   • 两个都未实现→ 跳过 spec 同步，并向用户发出警告；
4. 记录解析结论：对每个冲突记录——应用哪个变更的 spec、应用顺序（若两者都实现）、以及代码库中查到的依据（rationale）。

示例 1：只有一个变更实际实现

Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt] Checking add-oauth: - Delta adds "OAuth Provider Integration" requirement - Searching codebase... found src/auth/oauth.ts implementing OAuth flow Checking add-jwt: - Delta adds "JWT Token Handling" requirement - Searching codebase... no JWT implementation found Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.

示例 2：两个变更都已实现

Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql] Checking add-rest-api (created 2026-01-10): - Delta adds "REST Endpoints" requirement - Searching codebase... found src/api/rest.ts Checking add-graphql (created 2026-01-15): - Delta adds "GraphQL Schema" requirement - Searching codebase... found src/api/graphql.ts Resolution: Both implemented. Will apply add-rest-api specs first, then add-graphql specs (chronological order, newer takes precedence).

这一"以代码库证据为准"的解析思路，与 .claude/commands/opsx/verify.md 中"搜索代码库关键字评估需求是否已实现"的校验启发式一致，体现了 OPSX 工作流"用实现事实校正规范声明"的核心原则。

六、第 6 步：展示合并状态表

所有变更校验并解析完毕后，Agent 输出一张汇总表，让用户在确认前对全局一目了然：

| Change | Artifacts | Tasks | Specs | Conflicts | Status | |---------------------|-----------|-------|---------|-----------|--------| | schema-management | Done | 5/5 | 2 delta | None | Ready | | project-config | Done | 3/3 | 1 delta | None | Ready | | add-oauth | Done | 4/4 | 1 delta | auth (!) | Ready* | | add-verify-skill | 1 left | 2/5 | None | None | Warn |

对于存在冲突的变更，需要附上冲突解析结论：

* Conflict resolution: - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)

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

Warnings: - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks

注意add-oauth的Ready*星号标记：该变更本身可归档，但需要按解析顺序处理 spec；而add-verify-skill因存在未完成的 artifact 与任务，状态降级为Warn。

七、第 7 步：单次确认批量操作

状态表展示后，Agent 使用AskUserQuestion 工具发起一次统一确认，而不是逐条询问。选项基于状态动态生成：

• "归档全部 N 个变更（Archive all N changes）"
• "只归档 N 个就绪变更，跳过未完成的（Archive only N ready changes）"
• "取消（Cancel）"

如果存在未完成变更，需要明确告知用户：它们会被连同警告一起归档（"they'll be archived with warnings"），而不是静默处理。

八、第 8 步：执行归档

确认后，Agent 按冲突解析确定的顺序逐个处理变更，每个变更经历两个子步骤：

a. 同步 spec（如存在 delta spec）

如果变更存在 delta spec，先执行 spec 同步——采用openspec-sync-specs的Agent 驱动智能合并方式（详见 .claude/skills/openspec-sync-specs/SKILL.md 与 .claude/commands/opsx/sync.md）：

• 读取openspec/changes/<name>/specs/<capability>/spec.md中的## ADDED / MODIFIED / REMOVED / RENAMED Requirements分区；
• 对应修改主规范openspec/specs/<capability>/spec.md；
• 智能合并的精髓在于部分更新：新增一个 scenario 时无需复制既有 scenario，delta 表达的是"意图（intent）"而非整文件替换；
• 对于冲突场景，按解析后的顺序应用（先旧后新）。

b. 执行归档

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

归档目录目标命名使用当前日期：YYYY-MM-DD-<变更名>。移动目录时会一并保留.openspec.yaml（它随目录一起移动）。

c. 记录每个变更的结果

每个变更都要跟踪三类结果之一：

• Success：归档成功；
• Failed：归档过程出错（记录错误原因）；
• Skipped：用户选择不归档该变更（如跳过未完成的变更）。

失败隔离原则：如果某个变更的归档目标目录已存在，该变更标记失败，但继续处理其余变更，不中断整个批次。

九、第 9 步：输出最终汇总

归档完成后，按实际情况输出对应模板。

全部成功

## Bulk Archive Complete Archived 3 changes: - 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/ Skipped 1 change: - add-verify-skill (user chose not to archive incomplete) Spec sync summary: - 4 delta specs synced to main specs - 1 conflict resolved (auth: applied both in chronological order)

部分成功

## Bulk Archive Complete (partial) Archived N changes: - <change-1> -> archive/YYYY-MM-DD-<change-1>/ Skipped M changes: - <change-2> (user chose not to archive incomplete) Failed K changes: - <change-3>: Archive directory already exists

存在失败

Failed 1 change: - some-change: Archive directory already exists

汇总中必须包含 spec 同步摘要（同步了多少 delta spec、解决了多少冲突），让用户确认规范已正确收敛到主规范。

十、Guardrails：批量归档的安全护栏

命令文档末尾给出了一组明确的执行守则，是 Agent 行为边界的权威约束：

结语：与单条归档的协作及当前仓库状态

批量归档是单条归档 .claude/commands/opsx/archive.md 的批处理升级版：单条命令在无参数时同样要求用户选择变更、校验 artifact 与任务、评估 delta spec 同步状态，并提供 "Sync now (recommended)" / "Archive without syncing" / "Archive now" / "Cancel" 等选项；批量版则把"状态校验"升级为"冲突检测与 Agent 化解析"，把"逐条确认"压缩为"单次确认"，从而在多变更并行落地的场景下显著提升效率。

从当前仓库的 openspec/config.yaml 看，项目仅声明了schema: spec-driven基础配置，openspec/changes/与openspec/specs/目录尚未创建任何内容，说明该实验工作流正处于就绪待用状态。若要在 PeerBanHelper 仓库启用完整流程，可依序参考 .claude/commands/opsx/new.md（创建变更）→ .claude/commands/opsx/apply.md（实现任务）→ .claude/commands/opsx/verify.md（实现校验）→ 本文所述 bulk-archive（批量归档）的完整链路。需要说明的是，该命令要求本地已安装openspecCLI（skill 元数据标注Requires openspec CLI），命令运行于 Claude Code 环境并依赖 AskUserQuestion 等交互工具。

扩展阅读（均为仓库内既有文件）：

• 命令定义：.claude/commands/opsx/bulk-archive.md
• Skill 定义：.claude/skills/openspec-bulk-archive-change/SKILL.md
• 单条归档：.claude/commands/opsx/archive.md、.claude/skills/openspec-archive-change/SKILL.md
• Spec 同步：.claude/commands/opsx/sync.md、.claude/skills/openspec-sync-specs/SKILL.md
• 工作流配置：openspec/config.yaml

• 网络安全
• 后端