.openspec.yaml 是 change 目录中的元数据文件。它很小，但作用非常明确：告诉 OpenSpec 这个 change 采用什么工作流 schema，以及创建时间等生命周期信息。它不是需求文档，也不是运行时配置，更不能存放 API Key、数据库地址或产品参数。

📷 [图片 token=RZi8blpxJooS5AxMKG6c9SEEnDg（未能下载，见飞书原文）]

在 OncallAgent 中长什么样

主案例 2026-07-11-limit-qwen-embedding-batch-size 的内容只有两行：

schema: spec-driven
created: 2026-07-11

schema: spec-driven 表示该变更使用规范驱动的产物图。工具不会只凭文件名猜流程，而会按 schema 解释有哪些 artifact、它们怎样依赖、什么时候达到 apply-ready。created 保存创建日期，归档后文件仍随整个目录保留，为历史追溯提供时间信息。

📷 [图片 token=FwnpbPacioYm2Mx62fRc71konZd（未能下载，见飞书原文）]

schema 到底决定了什么

默认 spec-driven schema 的核心依赖可以理解为：

proposal            无前置依赖
specs               依赖 proposal
design              依赖 proposal
tasks               依赖 specs + design

因此工具先知道 proposal 可创建；proposal 完成后，specs 与 design 都解锁；两者完成后，tasks 才解锁。这个依赖图比“固定执行四条命令”更灵活，因为 OpenSpec 可以支持其他 schema。自定义 schema 可能增加研究、测试计划、迁移计划等产物，也可能针对小型维护任务缩短流程。

📷 [图片 token=VqL5bFNLooMJgjxuIvQcY13fnsg（未能下载，见飞书原文）]

OncallAgent 当前仓库中的 OpenSpec Skills 会先运行 openspec status --change <name> --json，读取 schemaName、artifacts、applyRequires、artifactPaths 和 actionContext，再决定下一步，而不是把路径和顺序硬编码在业务逻辑中。

📷 [图片 token=KjnDbPdQComSNlxp0WFcvn8YndD（未能下载，见飞书原文）]

为什么元数据必须与业务内容分开

业务内容会被人审查和修改，例如 proposal 的范围可能缩小，design 的决策可能调整，tasks 可能重新拆分。schema 与创建时间属于工具解释 change 所需的控制信息。如果把二者混在 proposal 中，工具需要从自然语言猜流程；如果把需求写进 YAML，又会让审查者在多个格式间来回寻找。

📷 [图片 token=OVgbbW4RWoujEpxABHDc7ABHnRH（未能下载，见飞书原文）]

这种分离与 OncallAgent 自身的分层思想一致：共享契约描述协议，业务代码实现行为，项目 JSON 配置负责运行参数，OpenSpec 元数据负责变更工作流。每个文件只承担一种稳定职责，边界越清晰，Codex 越不容易在错误位置修改内容。

📷 [图片 token=NLDCbPbOYoaHW2xcuv0cFIy2nke（未能下载，见飞书原文）]

创建、继续和归档时怎样使用

创建 change 时，openspec new change "<name>" 会建立脚手架和元数据。随后 openspec status 根据 schema 告诉 Agent 哪个 artifact ready、哪个 blocked。openspec instructions <artifact-id> 再提供该 artifact 的模板、规则、依赖和目标路径。

归档时，整个 change 目录被移动到带日期的 archive 路径，.openspec.yaml 一起保留。它不会被 OncallAgent 的 VitePress wiki-sync 聚合页 include，因为面向读者的页面重点是 proposal、design、tasks 和 delta specs；但元数据仍是归档审计的一部分。

📷 [图片 token=QIrbbWnkpo8rFHxaZACcvrQlnzc（未能下载，见飞书原文）]

常见错误

**把 YAML 当项目配置。**OpenSpec schema 不控制 FastAPI、Vue、Milvus、模型或 MCP 的运行参数。OncallAgent 的运行配置来自被 Git 忽略的项目 JSON，而不是这个文件。

**手工改 schema 却不检查 artifact。**改变 schema 可能改变产物图和模板，不能只改一行名字。应先查看可用 schema 和状态，再决定是否迁移。

**删除归档中的元数据。**即使 VitePress 页面不展示它，也应与其他 artifact 一起保留，避免历史 change 失去工作流上下文。

📷 [图片 token=SpUebanTdoQaZJxvREpcmpgMntg（未能下载，见飞书原文）]

面试表达

.openspec.yaml 不是需求，它是变更的工作流元数据。我们用它固定 schema 和创建信息，OpenSpec 再根据 schema 计算 artifact 的依赖和 ready 状态。业务内容放在 Markdown，控制信息放在 YAML，归档时两者一起保留，所以既方便人审查，也方便工具确定性执行。