设计规范遇上版本控制，YAML语义契约如何实现？
--91likeyou---
本文是阶段二《设计师作为”语义翻译者”》的基础设施专题，回答 YAML 语义契约在组织内如何被管理、被追踪、被同步。
阶段二的核心判断是：传统设计规范以文档形态存在（PDF、语雀、Figma 注释），版本不可追溯、变更不可同步、影响不可分析。Schema-As-Code 的解法是将设计意图形式化为 YAML 语义契约，但形式化本身不足以解决规模化问题——契约需要像代码一样被管理。
本文回答契约库怎么建。它不是设计师本地的零散文件，而是组织级的语义规范仓库，具备版本管理、Git 同步、影响面分析与权限控制四项核心能力。
阶段一：组件语义快照与模式诊断：AI 生成界面的第一道检查
阶段二：设计师作为”语义翻译者” 当AI生成界面时我怎么用规则锁住设计意图
方法论总纲与开源仓库：把设计规范写成代码格式，是所有 AI 工具的上游约束方法论
一、问题：YAML 写完后放在哪里
设计师写好了 ERR-001.yaml，接下来面临四个问题：
传统设计规范的答案是：发在语雀文档里，@全员，开会同步。但语雀文档不具备版本管理、Diff 对比、自动通知、权限控制四项能力——它面向”人”阅读，不面向”机器”消费。
YAML 契约如果也放在语雀里，会面临同样的困境：形式化了，但管理没有跟上。
二、核心判断：契约需要像代码一样被管理
代码仓库（Git）解决了什么问题？
- 版本可追溯（git log 看历史）
- 变更可审查（Pull Request 评审）
- 影响可分析（代码搜索、依赖分析）
- 权限可控制（谁可以 push、谁可以 merge）
设计规范同样需要这四项能力。契约库的本质，就是把设计规范从“文档”变成“代码”，从“人读”变成“机读+人审”。
Schema-As-Code 不是只写一份 YAML 文件，而是建立一套组织级的语义规范仓库——契约库。
三、契约库的整体架构
契约库是一个 Git 仓库，目录结构如下：
contract-library/ # 契约库根目录
├── contracts/ # 契约文件（核心）
│ ├── ERR-001.yaml # 错误状态语义契约
│ ├── ACT-001.yaml # 高危操作语义契约
│ ├── PRO-001.yaml # 过程状态语义契约
│ └── BND-001.yaml # 边界动作语义契约
│
├── schema/ # 结构校验规则
│ └── intent-schema.json # YAML 必须符合的格式标准
│
├── snapshots/ # 版本快照
│ ├── v1.0.0/ # 每个版本一个文件夹
│ │ └── ERR-001.yaml
│ └── v1.1.0/
│ └── ERR-001.yaml
│
├── changesets/ # 变更记录
│ └── 2024-06-01-ERR-001-update.md # 每次改了什么，为什么改
│
└── compiled/ # 编译输出（自动生成）
├── prompt-prefixes/ # 供 AI 编程工具消费的 Prompt 前缀
│ └── ERR-001-prompt.md
├── json-schemas/ # 供前端校验消费的 JSON Schema
│ └── ERR-001-schema.json
├── ci-rules/ # 供 CI 流水线消费的校验规则
│ └── ERR-001-eslint.js
└── checklists/ # 供设计师走查用的清单
└── ERR-001-checklist.md
3.1 contracts/：契约文件（核心）
存放所有 YAML 语义契约。每份契约对应一个漂移模式（如 ERR-001、ACT-001）。
命名规则：{模式ID}.yaml，如 ERR-001.yaml、ACT-001.yaml。
文件内容：包含 6 个顶层字段（intent_id、description、version、applicable_products、semantic_tokens、immutable_boundaries、llm_constraints）。
详见《YAML 契约格式：理解了语义规范体系后怎么写语义规则》。
3.2 schema/：结构校验规则
存放 intent-schema.json，定义 YAML 契约必须满足的格式标准。类似 JSON Schema 对 JSON 的约束，确保所有契约文件结构一致、字段完整。
作用：
- 设计师提交 YAML 时，自动校验字段是否缺失
- 防止 semantic_tokens 写错层级、防止 immutable_boundaries 遗漏 violation_action
确保契约库内的所有文件遵循同一套结构标准
3.3 snapshots/：版本快照
每个版本（v1.0.0、v1.1.0）对应一个独立文件夹，存放该版本下所有契约文件的完整快照。
作用：
- 版本可追溯：随时回滚到任意历史版本
- 版本可对比：git diff v1.0.0 v1.1.0 看变更内容
- 版本可锁定：下游工具可以明确声明“我消费的是 v1.0.0”
3.4 changesets/：变更记录
每次契约变更，必须附带一份变更说明（Changeset），记录：
- 改了什么（What）
- 为什么改（Why）
- 影响哪些产品（Impact）
- 谁审批的（Approver）
作用：
- 三个月后回溯：为什么把“严重”加入同义词防火墙？
- 变更可审计：所有修改都有记录、有审批、有责任人
- 影响可分析：根据 Changeset 自动生成影响面报告
变更记录样例：
# Changeset: ERR-001 v1.0.0 → v1.1.0
## 变更内容
– 新增 `degraded` 错误级别（部分功能可用）
– 修改 `retryable` 的视觉映射：从”黄色提示”改为”黄色提示 + 倒计时”
## 变更原因
– 用户反馈：限流提示没有倒计时，不知道等多久
– 产品需求：降级错误需要明确说明”哪些功能仍可用”
## 影响范围
– 适用产品：ChatGPT、文心一言、通义千问、Kimi、豆包、DeepSeek
– 下游消费方：Prompt 前缀、JSON Schema、Checklist、CI 规则
– 预计影响：前端需更新组件 Props 枚举值
## 审批人
– 提交：@体验架构设计师
– 审批：@设计系统负责人
– 合并：@DesignOps
3.5 compiled/：编译输出（自动生成）
存放编译管线自动生成的消费格式。此目录下的所有文件不应手动修改，由编译管线根据 contracts/ 内的 YAML 契约自动生成。
子目录：
- prompt-prefixes/：供 AI 编程工具消费的 Prompt 前缀
- json-schemas/：供前端校验消费的 JSON Schema
- ci-rules/：供 CI 流水线消费的校验规则
- checklists/：供设计师走查消费的清单
作用：
- 契约变更后，编译管线自动更新此目录
- 下游工具从此目录取消费格式，不直接读取 contracts/
确保下游消费的是”已编译、已验证”的产出物
四、契约库的四项核心能力
4.1 版本管理：Semantic Versioning
契约版本遵循语义化版本规范（MAJOR.MINOR.PATCH）：
版本声明（嵌入每个契约文件头部）：
intent_id: “ERR-001”
version: “1.1.0”
last_updated: “2026-07-13”
changelog_ref: “changesets/2026-07-13-ERR-001-degraded.md”
4.2 Git 同步：Diff 即通知，MR 即评审
契约库以 Git 仓库形态存在，遵循代码开发的工作流：
设计师修改 ERR-001.yaml
↓
git checkout -b feature/ERR-001-degraded
↓
修改 YAML + 编写 Changeset
↓
git commit -m “feat(ERR-001): add degraded severity level”
↓
提交 Merge Request
↓
@设计系统负责人 评审
↓
@前端 TL 确认影响范围
↓
@DesignOps 审批合并
↓
合并到 main 分支
↓
自动触发编译管线
↓
生成新的消费格式 + 通知下游
与代码仓库的区别：
- 代码仓库的 MR 评审的是“代码逻辑”
- 契约库的 MR 评审的是“语义定义”——这个新增的语义级别是否合理？是否与其他契约冲突？
4.3 影响面分析：改了契约，下游怎么知道
契约库的核心价值之一：变更后自动分析影响范围。
影响面分析维度：
影响面分析报告样例：
## 影响面分析：ERR-001 v1.0.0 → v1.1.0
### 变更摘要
– 新增 `degraded` 错误级别
### 影响产品（6 个）
– ChatGPT：当前消费 v1.0.0，需升级至 v1.1.0
– 文心一言：当前消费 v1.0.0，需升级至 v1.1.0
– 通义千问：当前消费 v1.0.0，需升级至 v1.1.0
– Kimi：当前消费 v1.0.0，需升级至 v1.1.0
– 豆包：当前消费 v1.0.0，需升级至 v1.1.0
– DeepSeek：当前消费 v1.0.0，需升级至 v1.1.0
### 影响团队（3 个）
– 前端团队：需更新组件 Props 枚举值（新增 `degraded`）
– AI 工程团队：需更新 Prompt 前缀（新增降级错误描述）
– 设计团队：需更新走查 Checklist（新增降级错误检查项）
### 建议行动
1. 前端团队：在下次迭代中更新 `ErrorState` 组件
2. AI 工程团队：替换 Prompt 前缀为 v1.1.0 版本
3. 设计团队：使用新版 Checklist 进行走查
4.4 权限控制：谁可以改，谁可以审，谁可以看
五、契约库与编译管线的关系
契约库是编译管线的”源文件仓库”，编译管线是契约库的”翻译引擎”。
工作流：
设计师修改 contracts/ERR-001.yaml
↓
提交 MR，经过评审和审批
↓
合并到 main 分支
↓
触发编译管线
↓
读取 contracts/ERR-001.yaml（源文件）
↓
编译为 compiled/ 下的 4 种消费格式
↓
通知下游工具：Prompt 前缀已更新、JSON Schema 已更新
没有契约库，编译管线无法工作：编译管线需要知道编译哪些文件、版本号是什么、变更历史是什么——这些信息都来自契约库。
没有编译管线，契约库价值减半：契约库管理了 YAML 文件，但如果 YAML 不能自动翻译成下游工具能消费的格式，设计师仍然需要手动同步，规模化不可行。
六、结语：契约库是语义治理的基础设施
Schema-As-Code 不是只写一份 YAML 文件，而是建立一套组织级的语义规范基础设施。
- YAML 契约是原子：定义了”这个场景下必须表达什么语义”。
- 契约库是仓库：管理了这些原子的版本、变更、影响、权限。
- 编译管线是引擎：将原子翻译为不同角色能消费的格式。
三者缺一不可：
- 没有 YAML，契约库是空的；
- 没有契约库，编译管线是无源的；
- 没有编译管线，YAML 是死的。
契约库的核心价值，不是让设计师多写一份文件，而是让设计规范从“文档”变成“代码”，从“人读”变成“机读+人审”，从“一次性”变成“可持续”。
当设计规范像代码一样被管理时，规范变更不再是”发文档、@全员、开会”，而是”提交 MR、评审、合并、自动下发”。
这就是语义翻译设计师在组织内的基础设施能力：不是产出更精美的界面，而是建立设计意图在概率性界面时代的防稀释机制。
本文是 Schema-As-Code 阶段二《设计师作为”语义翻译者”》的基础设施专题。下一篇：《从契约到消费格式：编译管线》。
题图来自Unsplash，基于CC0协议
🔥 热词：#契约百科 · #契约官网 · #契约是啥 · #看一下契约 · #契约仓库的定义 · #契约规则是什么意思 · #契约功能 · #契约包括哪些内容