当设计规范遇上版本控制，YAML 语义契约正在重构设计系统的协作范式。本文深入解析如何将设计意图形式化为可追踪的代码化契约，并建立组织级的语义规范仓库，实现版本管理、Git 同步、影响面分析与权限控制四大核心能力，彻底改变传统文档式设计规范的局限。

本文是阶段二《设计师作为”语义翻译者”》的基础设施专题，回答 YAML 语义契约在组织内如何被管理、被追踪、被同步。

阶段二的核心判断是：传统设计规范以文档形态存在（PDF、语雀、Figma 注释），版本不可追溯、变更不可同步、影响不可分析。Schema-As-Code 的解法是将设计意图形式化为 YAML 语义契约，但形式化本身不足以解决规模化问题——契约需要像代码一样被管理。

本文回答契约库怎么建。它不是设计师本地的零散文件，而是组织级的语义规范仓库，具备版本管理、Git 同步、影响面分析与权限控制四项核心能力。

阶段一：组件语义快照与模式诊断：AI 生成界面的第一道检查

阶段二：设计师作为”语义翻译者” 当AI生成界面时我怎么用规则锁住设计意图

方法论总纲与开源仓库：把设计规范写成代码格式，是所有 AI 工具的上游约束方法论

一、问题：YAML 写完后放在哪里

设计师写好了 ERR-001.yaml，接下来面临四个问题：

1. 版本问题：这份契约是 v1.0.0 还是 v1.1.0？改了什么？为什么改？
2. 同步问题：5 个产品都在用这份契约，改了之后怎么通知所有前端？
3. 追溯问题：三个月前为什么把”严重”加入同义词防火墙？谁决定的？
4. 权限问题：谁可以修改契约？谁可以审批？谁只能查看？

传统设计规范的答案是：发在语雀文档里，@全员，开会同步。但语雀文档不具备版本管理、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 阶段二《设计师作为”语义翻译者”》的基础设施专题。下一篇：《从契约到消费格式：编译管线》。