OpenSpec 变更归档实战:基于 openspec-archive-change Skill 的完整工作流解析
OpenSpec 变更归档实战:基于 openspec-archive-change Skill 的完整工作流解析
导读
本文围绕 Fonoster 仓库中的 OpenSpec 实验工作流,深入解析 openspec-archive-change 技能(Skill)的定义与执行逻辑。该技能用于在功能变更实现完成后将其归档到 archive 目录,是变更从"实现中"走向"已交付"的收尾环节。读完本文,你将掌握归档前的三项检查(artifact 完成度、任务完成度、delta spec 同步状态)、归档的执行命令与命名规范,以及全套护栏规则,并能结合仓库内真实的变更示例(如 identity-client)理解这一流程在实践中的落点。
一、背景:OpenSpec 变更驱动流程与归档环节
Fonoster 是一个开源的、可编程的电信平台(MIT 协议),采用 TypeScript monorepo 组织(mods/*),各服务通过单个 gRPC apiserver 与语音/电信基础设施(Asterisk/ARI、NATS、InfluxDB)组合。与此同时,仓库中维护着一套 OpenSpec 变更驱动的工作流资产,位于 openspec 目录:
- openspec/config.yaml:定义项目上下文(模块地图、变更动机、约定),其"约定"一节明确要求规格增量遵循 OpenSpec 格式,即
## ADDED/MODIFIED Requirements、### Requirement: …、#### Scenario: …搭配 WHEN/THEN/AND 句型; - openspec/specs/identity/spec.md:已固化的主规格(main spec),记录 Identity 模块的既定行为;
- openspec/changes:当前进行中的变更集,本仓库包含 5 个变更:
asterisk-answering-machine-detection(Asterisk 应答机检测)identity-client(轻量级 Identity 客户端包)identity-multi-product(多产品 Realm 隔离)identity-standalone-service(独立 Identity 服务)voice-audio-filters(语音音频滤镜)
每个变更目录都是一个完整的 "change root",内部通常包含 proposal.md(Why / What Changes / Capabilities / Impact)、tasks.md(勾选式任务清单)、specs/<capability>/spec.md(delta 规格,只描述新增/修改的需求增量),以及可选的 design.md。
在这些变更中,openspec-archive-change 技能扮演的角色是:当变更实现完成后,将其从"进行中"状态转为归档状态。它由 OpenSpec 官方生成(generatedBy: "1.4.1"),依赖 OpenSpec CLI(compatibility: Requires openspec CLI),以 MIT 许可发布。
二、Skill 文件结构:frontmatter、步骤与护栏
该技能文件的物理位置是 .claude/skills/openspec-archive-change/SKILL.md,其结构分为三层:
1. YAML frontmatter(元数据头)
| 字段 | 值 | 含义 |
|---|---|---|
name |
openspec-archive-change |
技能标识,供 Agent 按名调用 |
description |
Archive a completed change in the experimental workflow... | 触发条件描述:用户想"finalize and archive a change after implementation is complete"时使用 |
license |
MIT | 技能本身的开源许可 |
compatibility |
Requires openspec CLI | 运行前提:需要安装 OpenSpec 命令行工具 |
metadata.author |
openspec | 作者 |
metadata.version |
1.0 | 技能版本 |
metadata.generatedBy |
1.4.1 | 生成该技能的 OpenSpec 版本 |
2. 主体指令:定义输入(可选变更名,缺省时尝试从对话上下文推断,模糊时必须向用户询问)、六步执行流程、成功输出模板。
3. Guardrails(护栏规则):列出不可逾越的行为边界,例如"未提供变更名时必须先询问选择""不得擅自猜测或自动选择变更"。
从结构上可以推断:这类 SKILL.md 是为 Agent 设计的程序性操作手册,每一步都带有明确的工具调用意图(运行 CLI、使用 AskUserQuestion、使用 Task/Skill 工具),与仓库中 openspec/changes 的目录结构一一对应。
三、归档流程六步详解
3.1 第一步:选择待归档变更
输入:用户可选地指定变更名。若未提供,Agent 应尝试从对话上下文推断;若上下文含糊不清,必须向用户询问可用的变更列表。
具体操作:
openspec list --json
该命令输出当前所有可用变更。随后使用 AskUserQuestion 工具让用户选择,并遵守两条约束:
- 只展示活跃变更(尚未归档的);
- 若可用,附上每个变更所使用的 schema(工作流类型)。
关键约定(IMPORTANT):不要猜测或自动选择一个变更——必须始终让用户自己选择。这一步的意义在于归档是不可逆的收尾动作,选错对象会带来连锁影响。
3.2 第二步:检查 artifact 完成状态
确定变更后,运行状态查询:
openspec status --change "<name>" --json
解析返回的 JSON,重点读取以下字段:
schemaName:当前变更使用的工作流;planningHome、changeRoot、artifactPaths、actionContext:路径与作用域上下文;artifacts:artifact 列表及其状态(done或其他)。
这一阶段有两个分支处理:
- 工作区规划模式:若状态显示
actionContext.mode: "workspace-planning",则说明该变更处于工作区级规划切片中。此时应向用户解释"本切片不支持工作区归档",并 STOP——不允许把工作区变更挪进仓库本地归档,也不允许编辑关联的仓库。 - 存在未完成 artifact:若任一 artifact 的状态不是
done,则显示警告(列出未完成的 artifact),用 AskUserQuestion 向用户确认是否继续;用户确认后才可继续。
这一步的本质是以 artifact 图(artifact graph)为完成度依据,而非凭 Agent 的主观判断——这正是护栏规则"Use artifact graph (openspec status --json) for completion checking"的含义。
3.3 第三步:检查任务完成状态
读取任务文件(通常为 tasks.md,如仓库中的 tasks.md),统计:
- 标记为
- [ ](未完成)的任务数; - 标记为
- [x](已完成)的任务数。
若发现未完成任务:
- 显示警告,说明未完成任务的数量;
- 用 AskUserQuestion 向用户确认是否继续归档;
- 用户确认后才继续。
若任务文件不存在:直接继续,不产生任务相关警告。
仓库中的 identity-client/tasks.md 即是典型样例:包含 3 个分组(Proto 与代码生成、轻量客户端包、验证)、共 12 条任务,当前全部为 - [ ] 未完成状态。对照归档技能,这样的变更在归档时会触发"存在未完成任务"的警告与用户确认环节。
3.4 第四步:评估 delta spec 同步状态
使用状态 JSON 中的 artifactPaths.specs.existingOutputPaths 查找 delta 规格。若不存在任何 delta spec,则直接继续,不进行同步询问。
若存在 delta specs,执行两项工作:
- 逐条对比:将每个 delta spec 与对应的主规格(
openspec/specs/<capability>/spec.md)比较,确定将被应用的变更内容(adds 新增、modifications 修改、removals 删除、renames 重命名); - 汇总展示:在询问用户前,先展示一份合并摘要。
询问选项分两种场景:
- 若确实需要同步:提供
Sync now (recommended)(立即同步,推荐)与Archive without syncing(不同步直接归档); - 若已经同步过:提供
Archive now(直接归档)、Sync anyway(仍然同步)、Cancel(取消)。
若用户选择同步,则通过 Task 工具(subagent_type: "general-purpose")下发子任务,提示词模板为:
Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>
无论用户做何选择,归档动作都会照常执行。
以本仓库为例,identity-client 变更的 delta spec 位于 openspec/changes/identity-client/specs/identity-client/spec.md,其内容为 ## ADDED Requirements 加三个需求(轻量端点可配置客户端、全量 Identity 表面覆盖、按请求转发 token),每个需求下挂 #### Scenario: 与 WHEN/THEN/AND 场景。而对应的主规格是 openspec/specs/identity/spec.md(记录用户/工作区、RBAC、三类 JWT、token 交换、刷新轮换、公钥验证等既有行为)。同步动作即是将前者中的新增需求合并进后者。这与 openspec/config.yaml 中"Spec deltas follow OpenSpec format"的约定完全吻合。
3.5 第五步:执行归档
归档动作分两步,目标位置是 planningHome.changesDir 下的 archive 目录:
mkdir -p "<planningHome.changesDir>/archive"
归档目标的命名规则为 YYYY-MM-DD-<change-name>(当天日期 + 变更名)。之后:
mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
碰撞检查:若目标已存在,则报错失败,建议重命名现有归档或改用其他日期;若不存在,才执行移动。
在本仓库中,planningHome.changesDir 即 openspec/changes(由 openspec/config.yaml 的位置可推断),因此归档将落到 openspec/changes/archive/ 下。例如若今日归档 identity-client,将生成 openspec/changes/archive/2026-10-05-identity-client/。注意 mv 移动的是整个 changeRoot 目录,因此 proposal.md、tasks.md、specs/、design.md 以及 .openspec.yaml(配置随目录一并移动)都会完整保留在归档中。
3.6 第六步:展示归档摘要
归档完成后,输出以下格式的成功摘要:
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
All artifacts complete. All tasks complete.
摘要需包含:变更名、所用 schema、归档位置、规格是否已同步(三种表述:✓ Synced to main specs / No delta specs / Sync skipped),并注明任何警告(未完成的 artifact/任务)。其中"All artifacts complete. All tasks complete."一句应基于第二步与第三步的真实检查结果输出,不可凭空断言。
四、护栏规则(Guardrails)解析
技能末尾的护栏是流程安全性的最后防线,共 7 条:
- Always prompt for change selection if not provided:未提供变更名时,必须询问选择,杜绝擅自猜测;
- Use artifact graph (openspec status --json) for completion checking:完成度检查必须以 artifact 图为依据,而不是主观判断;
- Don't block archive on warnings - just inform and confirm:警告不阻断归档,只需告知并取得确认;
- Preserve .openspec.yaml when moving to archive:归档时保留
.openspec.yaml(它随目录移动,无需单独处理); - Show clear summary of what happened:结束时给出清晰的操作摘要;
- If sync is requested, use openspec-sync-specs approach (agent-driven):同步动作必须走
openspec-sync-specs的 agent 驱动路径(即第四步的 Task 工具调用); - If delta specs exist, always run the sync assessment and show the combined summary before prompting:只要存在 delta specs,就必须先完成同步评估并展示合并摘要,再向用户提问。
综合来看,护栏的核心精神是**"可确认、可追溯、不擅自做主"**:选择靠用户确认,完成度靠命令输出佐证,同步靠显式评估,归档结果靠摘要记录。
五、仓库实证:以 identity-client 变更走查归档全流程
结合本仓库的 identity-client 变更,将六步流程落到真实文件上:
- 选择变更:
openspec list --json应能列出 openspec/changes/identity-client 等活跃变更;用户选定identity-client; - artifact 检查:运行
openspec status --change "identity-client" --json,其 delta spec 位于 specs/identity-client/spec.md,当前需求均以## ADDED Requirements声明,尚无MODIFIED增量; - 任务检查:读取 tasks.md,统计
- [ ]未完成任务数(当前 12 条全部未完成),向用户展示警告并确认; - 同步评估:将 delta spec 与 openspec/specs/identity/spec.md 对比——前者新增的"轻量客户端包""全量表面覆盖""按请求转发 token"等需求,需要被合并进主规格的 Requirement 集合;展示合并摘要后询问同步选项;
- 执行归档:
mkdir -p openspec/changes/archive后,mv openspec/changes/identity-client openspec/changes/archive/2026-10-05-identity-client(日期随实际归档日变化); - 输出摘要:按 3.6 节的模板输出,注明 schema(
identity-client变更对应的 schema)、归档路径与规格同步情况。
这一走查展示了归档流程与仓库 OpenSpec 资产之间的精确对应关系:planningHome 对应 openspec/,changesDir 对应 openspec/changes/,artifactPaths.specs.existingOutputPaths 对应 openspec/changes/<change>/specs/,主规格对应 openspec/specs/<capability>/spec.md。
六、边界情形与注意事项
- 工作区规划模式:
actionContext.mode: "workspace-planning"时,归档不被支持,流程必须停止——工作区变更不应被搬入仓库本地归档,也不应编辑关联仓库; - 同名碰撞:归档目标已存在(例如同一天对同一变更重复归档)时直接报错,通过重命名旧归档或改用日期解决,不可覆盖;
- 任务文件缺失:某些变更可能没有
tasks.md,此时跳过任务警告,直接继续; - 无 delta specs:某些变更可能只有 proposal 而无规格增量,此时跳过同步询问,归档摘要中规格字段写作
No delta specs; - 警告不阻断:未完成的 artifact 或任务只触发"告知 + 确认",只要用户确认即可归档——流程设计上不把警告升级为硬性失败;
- 只读仓库提示:本文所述流程面向可写工作区中的 OpenSpec 项目;在只读镜像仓库中仅用于理解工作流与文档检索,不应对仓库内容执行移动操作。
通过以上六个步骤与七条护栏,openspec-archive-change 技能把"变更完成后的归档"变成了一条可审计、可复现、用户全程可控的标准化路径——这正是 OpenSpec 实验工作流中,从"实现完成"到"规格落库"的关键一环。