> 本文是阶段二《设计师作为"语义翻译者"》的基础设施专题，回答 YAML 语义契约在组织内如何被管理、被追踪、被同步。
> 
> 阶段二的核心判断是：传统设计规范以文档形态存在（PDF、语雀、Figma 注释），版本不可追溯、变更不可同步、影响不可分析。Schema-As-Code 的解法是将设计意图形式化为 YAML 语义契约，但形式化本身不足以解决规模化问题——契约需要像代码一样被管理。
> 
> 本文回答契约库怎么建。它不是设计师本地的零散文件，而是组织级的语义规范仓库，具备版本管理、Git 同步、影响面分析与权限控制四项核心能力。
> 
> 阶段一：[组件语义快照与模式诊断：AI 生成界面的第一道检查](https://mp.weixin.qq.com/s?__biz=MzY5NDM1Mjc4MA==&mid=2247484325&idx=1&sn=ef801233864574d19070a41e2fabe5da&scene=21#wechat_redirect)
> 阶段二：[设计师作为"语义翻译者" 当AI生成界面时我怎么用规则锁住设计意图](https://mp.weixin.qq.com/s/7mzdawzA0wtyWYt_WXJlXw)
> 方法论总纲与开源仓库：[把设计规范写成代码格式，是所有 AI 工具的上游约束方法论](https://mp.weixin.qq.com/s?__biz=MzY5NDM1Mjc4MA==&mid=2247484402&idx=1&sn=606e559ac9996e2ae43bbe5995aaa0b4&scene=21#wechat_redirect)

---

## 一、问题：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 契约格式：理解了语义规范体系后怎么写语义规则》](https://cloud.tencent.com/developer/article/2706441)。

### 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 自动生成影响面报告

**变更记录样例**：

```markdown
# 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`）：

| 版本号变化 | 含义 | 示例 |
|-----------|------|------|
| `MAJOR` 升级（如 1.0.0 → 2.0.0） | 破坏性变更：删除语义级别、修改已有级别的含义 | 删除 `fatal` 级别，或将其改为 `critical` |
| `MINOR` 升级（如 1.0.0 → 1.1.0） | 新增功能：增加语义级别、增加约束字段 | 新增 `degraded` 级别 |
| `PATCH` 升级（如 1.0.0 → 1.0.1） | 修复：文案修正、示例更新、不影响语义 | 修正 `description` 中的错别字 |

**版本声明（嵌入每个契约文件头部）**：

```yaml
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 影响面分析：改了契约，下游怎么知道

契约库的核心价值之一：变更后自动分析影响范围。

**影响面分析维度**：

| 维度 | 分析内容 | 输出 |
|------|---------|------|
| **产品维度** | 哪些产品消费了这份契约？ | 产品列表（如 ChatGPT、文心一言、Kimi） |
| **工具维度** | 哪些下游工具需要更新？ | 工具列表（如 Claude Code、v0、Figma 插件） |
| **团队维度** | 哪些团队需要同步？ | 团队列表（如前端团队、AI 工程团队、设计团队） |
| **版本维度** | 当前消费的是哪个版本？是否需要升级？ | 版本对比报告 |

**影响面分析报告样例**：

```markdown
## 影响面分析：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 权限控制：谁可以改，谁可以审，谁可以看

| 角色 | 权限 | 说明 |
|------|------|------|
| **语义翻译设计师** | 创建、修改契约 | 负责编写和更新 YAML 契约 |
| **设计系统负责人** | 评审、批准 | 负责语义定义的准确性和一致性 |
| **前端 TL** | 确认影响范围 | 负责评估技术实现成本 |
| **DesignOps** | 合并、发布 | 负责变更的同步和通知 |
| **设计师（普通）** | 查看、评论 | 可以查看契约和 Changeset，但不能修改 |
| **前端工程师** | 查看、消费 | 可以查看编译后的消费格式，但不能修改源文件 |

---

## 五、契约库与编译管线的关系

**契约库是编译管线的"源文件仓库"，编译管线是契约库的"翻译引擎"。**

| 维度 | 契约库 | 编译管线 |
|------|--------|---------|
| **定位** | 管理 YAML 源文件 | 翻译 YAML 为消费格式 |
| **核心能力** | 版本管理、Git 同步、影响面分析、权限控制 | 字段映射、格式转换、多目标输出、版本同步 |
| **输入** | 设计师写的 YAML 契约 | 契约库 `contracts/` 目录下的 YAML 文件 |
| **输出** | 版本化的 YAML 文件 + Changeset | Prompt 前缀、JSON Schema、Checklist、CI 规则 |
| **类比** | 代码仓库（Git） | CI/CD 流水线（GitHub Actions） |

**工作流**：

```
设计师修改 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 阶段二《设计师作为"语义翻译者"》的基础设施专题。下一篇：《从契约到消费格式：编译管线》。*

![640.png](https://developer.qcloudimg.com/http-save/yehe-12505371/96a5ed46326cdfb9c0424c2c0aa60187.png)


本文是阶段二《设计师作为"语义翻译者"》的基础设施专题，回答 YAML 语义契约在组织内如何被管理、被追踪、被同步。  阶段二的核心判断是：传统设计规范以文档形态存在（PDF、语雀、Figma 注释），版本不可追溯、变更不可同步、影响不可分析。Schema-As-Code 的解法是将设计意图形式化为 YAML 语义契约，但形式化本身不足以解决规模化问题——契约需要像代码一样被管理。  本文回答契约库怎么建。它不是设计师本地的零散文件，而是组织级的语义规范仓库，具备版本管理、Git 同步、影响面分析与权限控制四项核心能力。  阶段一：组件语义快照与模式诊断：AI 生成界面的第一道检查 阶段二：设计师作为"语义翻译者" 当AI生成界面时我怎么用规则锁住设计意图 方法论总纲与开源仓库：把设计规范写成代码格式，是所有 AI 工具的上游约束方法论

契约库：让设计规范像代码一样管理

本文是Schema-As-Code阶段二的基础设施专题，详解如何将YAML语义契约构建为组织级契约库：通过Git版本管理、自动化编译、影响面分析与细粒度权限控制，让设计规范真正具备代码级可追溯、可同步、可验证能力。

编程语言

架构设计

本文探讨如何通过YAML语义契约管理设计规范，提出建立组织级契约库的解决方案。契约库采用Git仓库形式，具备版本管理、Git同步、影响面分析和权限控制四项核心能力，将设计规范从文档形态转变为可追溯、可同步的代码形态，实现设计意图的规模化治理。

代码解释

防火墙

AI编程

DeepSeek

ChatGPT

JSON

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

契约库：让设计规范像代码一样管理-腾讯云开发者社区-腾讯云

契约库：让设计规范像代码一样管理

契约库：让设计规范像代码一样管理

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐