OpenSpec 变更归档实战:基于 openspec-archive-change Skill 的完整工作流解析

原创2026-10-05 23:07:281,767 阅读
文章标签:后端音视频

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 或其他)。

这一阶段有两个分支处理:

  1. 工作区规划模式:若状态显示 actionContext.mode: "workspace-planning",则说明该变更处于工作区级规划切片中。此时应向用户解释"本切片不支持工作区归档",并 STOP——不允许把工作区变更挪进仓库本地归档,也不允许编辑关联的仓库。
  2. 存在未完成 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,执行两项工作:

  1. 逐条对比:将每个 delta spec 与对应的主规格(openspec/specs/<capability>/spec.md)比较,确定将被应用的变更内容(adds 新增、modifications 修改、removals 删除、renames 重命名);
  2. 汇总展示:在询问用户前,先展示一份合并摘要。

询问选项分两种场景:

  • 若确实需要同步:提供 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 条:

  1. Always prompt for change selection if not provided:未提供变更名时,必须询问选择,杜绝擅自猜测;
  2. Use artifact graph (openspec status --json) for completion checking:完成度检查必须以 artifact 图为依据,而不是主观判断;
  3. Don't block archive on warnings - just inform and confirm:警告不阻断归档,只需告知并取得确认;
  4. Preserve .openspec.yaml when moving to archive:归档时保留 .openspec.yaml(它随目录移动,无需单独处理);
  5. Show clear summary of what happened:结束时给出清晰的操作摘要;
  6. If sync is requested, use openspec-sync-specs approach (agent-driven):同步动作必须走 openspec-sync-specs 的 agent 驱动路径(即第四步的 Task 工具调用);
  7. If delta specs exist, always run the sync assessment and show the combined summary before prompting:只要存在 delta specs,就必须先完成同步评估并展示合并摘要,再向用户提问。

综合来看,护栏的核心精神是**"可确认、可追溯、不擅自做主"**:选择靠用户确认,完成度靠命令输出佐证,同步靠显式评估,归档结果靠摘要记录。

五、仓库实证:以 identity-client 变更走查归档全流程

结合本仓库的 identity-client 变更,将六步流程落到真实文件上:

  1. 选择变更:openspec list --json 应能列出 openspec/changes/identity-client 等活跃变更;用户选定 identity-client;
  2. artifact 检查:运行 openspec status --change "identity-client" --json,其 delta spec 位于 specs/identity-client/spec.md,当前需求均以 ## ADDED Requirements 声明,尚无 MODIFIED 增量;
  3. 任务检查:读取 tasks.md,统计 - [ ] 未完成任务数(当前 12 条全部未完成),向用户展示警告并确认;
  4. 同步评估:将 delta spec 与 openspec/specs/identity/spec.md 对比——前者新增的"轻量客户端包""全量表面覆盖""按请求转发 token"等需求,需要被合并进主规格的 Requirement 集合;展示合并摘要后询问同步选项;
  5. 执行归档:mkdir -p openspec/changes/archive 后,mv openspec/changes/identity-client openspec/changes/archive/2026-10-05-identity-client(日期随实际归档日变化);
  6. 输出摘要:按 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 实验工作流中,从"实现完成"到"规格落库"的关键一环。

登录后查看全文
fonoster