当AI生成界面时，设计规范必须从文档变成机器可执行的代码。本文提出YAML契约作为设计意图的机器接口，通过编译生成Prompt前缀、JSON Schema、Checklist和CI规则四种格式，实现事前拦截而非事后走查，确保语义一致性与合规性。

如果你让AI生成一个”删除账户”按钮，它很可能给你一个蓝色实心按钮，用户一点，账户没了。这不是AI故意使坏，而是 约束显化设计规矩 在从人传到机器的过程中，层层丢失了。

前面三篇文章，我们一步一步解决了这个问题：

① 语义令牌表，先把”严重””Critical””致命”这些人话，翻译成机器能看懂的离散级别（就像给颜色编了色号）。

① 语义字典，把这些编了号的级别，统一收进一本”机器字典”里注册管理。不是谁想填什么就填什么，契约里的每个值必须先在这本字典里查得到，查不到的机器直接报错。

② 语义域，再定义”什么时候用什么级别”。同样是红色，告警场景用”致命”，通知场景用”提示”，场景错了，级别就对不上。

③ 约束显化（把规矩形式化到代码里），论证了为什么要形式化：以前设计规矩写在文档里，AI看不见；现在必须写成代码格式，AI生成前就能读到。

但形式化之后，一个新问题出现了：

就算团队决定写YAML契约规则文件，里面的每个值也是凭感觉编的。颜色级别填什么？场景填什么？这些值是设计师拍脑袋写的，还是查出来的？如果每个人填得都不一样，那规则文件本质上还是”文档换皮”，机器仍然不知道对不对。

当 语义规范体系 与 YAML 契约格式 已经定义了”怎么写”之后，YAML契约被机器读取、编译、执行时的真实形态，不是设计师看到的YAML文本，而是机器消费链路中的4种可执行格式。

一句话：规则文件不是“自由写作文”，而是“查字典填表格”。

1. 问题：规矩形式化为代码里了，机器怎么读？

行业现状中，设计规范以三种形态存在：自然语言文档供人阅读、设计稿供人查看、代码注释供人理解。这三种形态对机器都是不可执行的，机器读不懂“错误状态分四级”这句话，读不懂Figma里的红色背景条，读不懂代码里的 // 注释。

这导致三个系统性问题：

1. 规范是”死的”：设计师更新了规范，发在语雀文档里，前端可能看漏，AI工具完全不可见。规范更新后，下游没有任何自动同步机制；
2. 契约是”散的”：同一个”删除账户”的约束，设计师写在PRD里，前端写在代码注释里，AI工程师写在Prompt里，三份约束各自为政，版本不同步，语义互相矛盾；
3. 验证是”人眼的”：走查靠设计师截图圈问题，覆盖率20%，剩下80%的语义错误上线后才被用户投诉。机器没有”查规矩”的能力，只能靠人眼逐页核对。

6个漂移模式 中的 ERR-001错误状态后果差异未分级、BND-001边界动作权利差异未区分等，根因都是”规矩写在文档里，机器读不到”。语义令牌表定义了 status.critical，语义字典注册了它的唯一含义，语义域限定了它的使用范围，但如果没有YAML契约把这些定义编译成机器可执行的格式，令牌、字典、域都只是“纸面上的正确”。

2. 为什么自然语言守不住：规矩不可执行

设计规范文档用自然语言描述约束：”致命错误用红色脉冲，限流用黄色时钟，删除按钮必须二次确认”。但自然语言对机器是不可执行的：

• AI生成工具读不懂”必须二次确认”，它的训练语料里只有按钮的样式参数，没有”二次确认”的行为约束；
• 前端工程师看到的是代码注释 // 删除按钮要二次确认，但注释不参与编译，不会被校验，漏掉也不会报错；
• CI流水线只能校验代码语法和样式合规，无法校验”这个红色按钮是否匹配了正确的语义级别”；
• 验收走查依赖人的主观判断，”感觉这个红色不对”无法转化为可复现的机器规则。

语义令牌表已经把”红色”编码为 status.critical，语义字典已经注册了它的唯一含义。但如果没有YAML契约作为”接口定义“，令牌和字典仍然是“定义层”的资产，无法进入“执行层”。YAML契约的作用，就是把“定义层的语义资产”翻译成“执行层的机器规则”，让机器可以读取、编译、校验、拦截。

3. 设计思路：契约是接口，编译即规则

本文的设计思路是三个递进命题：

1. 契约是接口定义：YAML契约不是”设计规范的另一种写法”，而是”设计意图的机器接口“。定义了”机器在生成界面时，必须遵守什么、禁止做什么、违反后怎么处理”；
2. 编译即规则：一份YAML契约被机器读取后，不是”被看懂”，而是被编译为4种可执行的机器格式，Prompt 前缀给AI编程工具、JSON Schema给结构校验器、Checklist给设计师走查、CI规则给自动化流水线。同一组语义约束，在不同工具链中以不同格式执行同一规则；
3. 机器拦截现场：当AI试图生成违规内容时，机器不是”提示建议”，而是”直接阻断”，返回错误码、给出修正建议、阻止代码合并。契约不是文档，是机器执行的拦截规则。

3.1 契约不是“另一种文档格式”

以前设计规范写在语雀/Confluence 里，更新后 @ 全员通知。现在YAML契约放在Git仓库里，改一次，编译管线自动把变更同步到所有消费方。

对比：

为什么这样做：把规范从“给人看的文档”变成“给机器执行的代码”。

3.2 一份契约，四种机器形态

设计师写一份YAML契约，机器自动把它编译成四种东西，给四种不同的工具用。

编译链路：

设计师写 YAML 契约 → 编译管线读取 → 输出4种格式：

1. Prompt 前缀 → 注入 Claude Code / Cursor 上下文
2. JSON Schema → 供 CI 流水线校验组件 Props
3. Checklist → 供设计师走查时逐项核对
4. CI 规则 → 供 GitHub Actions / ESLint 自动拦截

为什么这样做：设计师只写一次，四种消费方自动拿到自己需要的东西。不用设计师给工程师写一遍、给运维写一遍、给测试写一遍。

3.3 机器拦截现场：违规即阻断

以前AI生成违规内容，走查时才发现，人工修正。现在机器在生成前即校验，违规直接阻断，返回错误码和修正建议。

拦截流程：

AI 生成器输出内容 → 编译管线加载YAML契约 → 四层校验：

• 语法推演：JSON 结构是否完整？
• 语义推演：语义令牌引用是否正确？
• 安全推演：是否违反不可变边界？
• 美感推演：文案长度、信息密度是否合规？

→ 任一校验失败 → 返回错误码 + 修正建议 → 阻断合并

→ 全部通过 → 输出合规内容 → 允许合并

为什么这样做：把“事后走查”变成“事前拦截”。错误在生成阶段就无法成立，不会流入生产环境。

3.4 契约引用字典，不自创语义

YAML契约中的 semantic_domain、semantic_tokens 等字段，必须引用语义字典中已注册的定义，不可自创。字典没有的，先走字典变更流程注册，再引用。

查表路径：

YAML 契约加载 → 编译管线解析 → 逐条核对引用：

• semantic_domain 是否在字典覆盖层目录中？
• semantic_tokens 是否在字典语义绑定中？
• 跨层引用是否违反跨层禁止规则？→ 非法引用 → 返回 dictionary-reference-not-found → 阻断→ 合法引用 → 继续编译 → 输出 4 种格式

为什么这样做：防止“契约自创语义”。所有语义必须在字典中先注册、后引用，确保组织级语义一致性。

3.5 四条思路的依赖关系

依赖关系：语义令牌表（离散值）→ 语义字典（注册表）→ 语义域（覆盖层）→ YAML 契约（接口定义）→ 编译管线（执行层）→ 四种机器形态（消费层）

4. 本文的核心命题

“形式化为代码的规矩，在机器世界里长什么样”必须翻译成可验证的框架设计。本文回答三个命题：

一、调整前：四个角色的真实反馈

在没有YAML契约之前，设计意图的传递处于“人传人”状态。用各角色自己的话说：

设计师的真实反馈：“规范写在语雀里，前端说没看到，AI工程师说没空看。”

“错误状态分四级”供人阅读，但前端在写代码时不会打开语雀查文档，AI工程师在写Prompt时也不会翻阅设计规范。规范更新后，@ 全员通知，但消息淹没在群里，没人记得看。规范是”死的”，它存在，但不被执行。

前端的真实反馈：“代码注释里写了’要二次确认’，但注释不参与编译，漏掉也不会报错。”

// 删除按钮要二次确认 ，这是一条给人类阅读的提醒，不是给机器执行的规则。CI流水线不会检查”这个按钮有没有二次确认”，代码审查时也可能看漏。注释是”散的”，它存在，但不可校验。

AI工程师的真实反馈：“Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心。”

AI工程师在Prompt里手动粘贴设计规范，但 Prompt 长度有限，规范写不全；不同工程师贴的规范版本不同，有的贴v1.0，有的贴v1.2；AI对自然语言规范的理解是概率性的，”必须二次确认”可能被理解为”建议二次确认”。Prompt是”软的”，它存在，但不可强制执行。

DesignOps 的真实反馈：”规范更新了，怎么知道哪些产品没改？只能一个个去问。”

规范从v1.0升级到v1.1，DesignOps需要 @ 10个前端负责人，开3场同步会，2周后走查发现3个产品没改对。规范同步靠人肉广播，遗漏率指数增长。

汇总成一张表：

四条反馈指向同一个根因：设计意图没有“机器接口”。它要么飘在文档里、靠人阅读，要么写在注释里、靠人理解，要么贴在Prompt里、靠概率执行，机器拿不到、读不懂、执行不了。

二、把意图形式化为机器可校验的契约

将设计意图转化为机器可执行的格式，是软件工程中屡试不爽的成熟方法论。

• OpenAPI/Swagger主张接口即契约，前后端依赖同一份机器可消费的契约文件协作。这与我的YAML契约逻辑一致：设计意图本身即是机器可消费的契约文件，AI按契约生成界面，CI按契约校验输出。
• Protobuf/gRPC将接口定义直接代码化，由Git原生管理版本。我的YAML契约管线同理，它相当于“界面语义的.proto”，被编译成Prompt/JSON Schema/Checklist/CI等不同产物，供不同工具链消费。
• GraphQL将类型定义为契约，编译期即可拦截错误。这与我的“四层推演机制”异曲同工，语义错误在生成前置阶段就被拦截，不流入生产。

工业界虽有类似尝试（如W3C DTCG定义了机器可读的Design Tokens），但我是在其之上扩展了语义约束层。行业现状往往只是“换名”（如color-red-500改名color-danger），缺乏行为约束与机器拦截能力。这恰恰反证了YAML契约的核心价值：它不只是换个名字，而是将“必须做什么、禁止做什么、违规怎么处理”固化为机器可执行的规则。

三、关键设计：查字典写约定书

3.1 契约是什么

YAML契约是设计意图的机器接口：它定义了”在某个语义域的边界内，某个组件必须表达什么语义、禁止做什么、违反后怎么处理”。契约不定义新的语义，语义在语义字典中注册；契约只引用字典中的已定义项，把引用组合成“场景级的约束实例”。

3.2 完整示例：ERR-001 契约的机器消费链路

以 ERR-001（错误状态后果差异未分级）的契约为例，展示从YAML文本到四种机器形态的完整编译链路。

YAML契约原文（设计师写的）：

【演示环境：编译管线：从唯一事实来源到四种机器形态】

3.3 机器形态 1：Prompt前缀（给AI编程工具）

编译产物：机器把YAML契约编译成一段Prompt前缀，自动注入到 Claude Code / Cursor 的上下文。

Prompt前缀文本（机器编译产出）：

3.4 机器形态 2：JSON Schema（给结构校验器）

编译产物：机器把YAML契约编译成JSON Schema，供CI流水线校验组件Props。

JSON Schema片段（机器编译产出）：

3.5 机器形态 3：Checklist（给设计师走查）

编译产物：机器把YAML契约编译成可打印的走查清单。

Checklist表格（机器编译产物）：

3.6 机器形态 4：CI规则（给自动化流水线）

编译产物：机器把YAML契约编译成 GitHub Actions / ESLint 规则。

CI规则片段（机器编译产物）：

3.7 机器拦截现场：当AI试图生成违规内容

场景：AI工程师让 Claude Code 生成一个限流提示。

未注入契约时：

• AI输出：“请求过于频繁，系统出现严重错误”（红色背景）
• 结果：用户恐慌性刷新，其实等30秒就好
• 问题：AI把 retryable 级别做成了 fatal 级别的视觉

注入契约后：

• 机器先查 ERR-001.yaml → 匹配到 retryable 级别
• 机器拦截：llm_constraints 禁止用“严重”描述限流，禁止用红色背景
• 机器返回修正建议：“请使用黄色提示 + 时钟图标 + 倒计时文案”
• AI重新生成：“请求过于频繁，请在42秒后重试”（黄色提示 + 倒计时）

拦截日志：

3.8 依赖关系

依赖关系：语义令牌表（离散值）→ 语义字典（注册表）→ 语义域（覆盖层）→ YAML 契约（接口定义）→ 编译管线（执行层）→ 四种机器形态（消费层）

四、架构层概念：设计背景

契约是接口，不是实现。YAML契约只定义“必须做什么、禁止做什么”，不定义“怎么实现”。具体实现由前端框架、AI工具、设计系统各自决定，契约只约束语义，不约束技术选型。

编译管线是翻译器。 编译管线读取YAML契约，查询语义字典，展开语义令牌，输出四种机器格式。它是”定义层”到”执行层”的翻译器，把设计师的意图翻译成机器可执行的规则。

四种形态是消费面。 Prompt前缀给AI工程师用，JSON Schema给前端用，Checklist给设计师用，CI规则给DevOps用。同一组语义约束，在不同角色面前呈现为不同的“使用界面”。

在全景中的位置。 YAML契约位于建设层的中游（接口层）：语义字典（上游·元规则）→ YAML契约（中游·接口）→ 编译管线（下游·执行）→ 四种机器形态（消费层）。契约不确定，编译管线没有输入，四种形态无法生成。

面向不同读者群时，YAML契约有两套叫法：设计意图的接口定义 ≈ 机器可执行的契约；编译即规则 ≈ 契约被机器消费时的形态。两套术语指向同一份YAML文件。

五、这些坑怎么被解掉

回到开头的四条真实反馈，看契约就位后它们各自的解法路径。

踩过的坑 1：”规范写在语雀里，前端说没看到，AI工程师说没空看”

症状复盘：规范更新后，@ 全员通知，但消息淹没在群里，没人记得看。规范是”死的”。

根因：规范以自然语言文档形态存在，机器不可见，无法自动同步。

关联机制：④ YAML 契约（编译管线）+ ① 语义字典（版本治理）

解法路径：规范写成YAML契约，放在Git仓库里。设计师提交变更 → Git Diff自动触发影响面分析 → 编译管线重新编译四种格式 → 所有消费方自动更新。前端和 AI 工程师不需要”看文档”，他们使用的Prompt前缀和 JSON Schema自动跟着更新。

验证方式：规范从v1.0升级到v1.1，下游四种消费格式在5分钟内同步更新，无需人工通知。

踩过的坑 2：”代码注释里写了’要二次确认’，但注释不参与编译”

症状复盘：// 删除按钮要二次确认 ，注释是给人看的，机器不校验，漏掉也不会报错。

根因：约束以注释形态存在，不可执行、不可校验。

关联机制：④ YAML 契约（JSON Schema 编译产物）+ 字典引用的机器防线

解法路径：约束写成YAML契约，编译为JSON Schema。前端组件的Props必须匹配Schema，缺少二次确认即被CI阻断，PR无法合并。

验证方式：前端提交代码时，CI自动校验组件Props是否符合契约，违规即阻断，无需人工走查。

踩过的坑 3：”Prompt里写了一大段设计规范，但AI还是把删除按钮做成了蓝色实心”

症状复盘：AI工程师在Prompt里手动粘贴规范，但规范写不全、版本不同、理解概率性。

根因：Prompt是自然语言约束，不可强制执行，理解是概率性的。

关联机制：④ YAML 契约（Prompt 前缀编译产物）+ 前端与AI工程师

解法路径：契约编译为Prompt前缀，自动注入AI上下文。AI生成时先加载约束，再生成内容，约束不是“建议”，是“前置条件”。

验证方式：同一Prompt，注入契约前AI生成蓝色实心按钮；注入契约后AI生成红色空心按钮 + 二次确认。

踩过的坑 4：”规范更新了，怎么知道哪些产品没改？只能一个个去问”

症状复盘：DesignOps人肉广播，2周后走查发现3个产品没改对。

根因：规范同步没有自动机制，依赖人工跟踪。

关联机制：④ YAML 契约（Git 版本管理）+ DesignOps

解法路径：YAML契约放在Git仓库里，版本管理、Diff追溯、影响面分析都是Git的原生能力。DesignOps提交变更后，Git Diff自动显示影响了哪些契约、哪些消费格式、哪些产品。

验证方式：规范变更后，影响面分析报告在10分钟内自动生成，列出所有受影响的产品和文件。

六、调整后：工具界面层的呈现状态

七、一句话总结（给不同角色）

给设计师：

“你以前写’错误状态分四级’在语雀文档里，前端可能看漏。现在你写一份YAML契约，机器自动把它变成 Prompt前缀、JSON Schema、Checklist、CI规则，四种人自动拿到自己需要的东西，不用你发四遍通知。”

给前端：

“你不需要在代码注释里写’要二次确认’，注释不参与编译。现在契约编译成JSON Schema，你的组件Props必须符合Schema，缺少二次确认CI直接阻断，PR合不进去。”

给 AI 工程师：

“你不需要在Prompt里手动粘贴设计规范，规范写不全、版本还乱。现在契约自动编译成Prompt前缀，注入你的AI上下文，AI生成前先加载约束，不会再把删除按钮做成蓝色实心。”

给 DesignOps：

“你不需要@全员开会同步规范，改一次YAML契约，Git Diff自动告诉你影响了哪些产品、哪些文件。规范同步从2周降到5分钟。”

给管理层：

“以前规范是’死的’，写在文档里，机器读不到。现在规范是’活的’，写成YAML，机器自动编译、自动校验、自动同步。语义一致性从’人盯’变成’机查’，返工率从30%降到5%。”

边界声明

YAML契约不定义新的语义（那是语义字典的职责），不约束视觉值的具体色值（那是 Design Token 层的职责），也不约束”契约被不被正确引用”（消费纪律在角色侧，见角色专题 ①｜设计师与产品经理）。当前量化收益均为数据模型推演，待生产数据验证。

附录：

【演示环境：编译管线：从唯一事实来源到四种机器形态】：

https://2436041978-ops.github.io/semantic-pipeline/mechanism/03-yaml-contract/yaml-contract.html

③ 约束显化：把隐含的语义假设变成显式规则：

https://www.yuque.com/u222739/why7ts/rdzgmhsxst8wea6b

① 语义令牌表：把语义概念编码成离散枚举：

https://www.yuque.com/u222739/why7ts/ahgd86ugl61h6dy3

① 语义字典：组织级语义注册表，契约的唯一信源：

https://www.yuque.com/u222739/why7ts/mr4mqy0cnkl8gmab

② 语义域：组件是空容器，语义由场景定义：

https://www.yuque.com/u222739/why7ts/qxep0yb6b98uwkng

③ 约束显化：把隐含的语义假设变成显式规则：

https://www.yuque.com/u222739/why7ts/rdzgmhsxst8wea6b

语义规范体系：YAML 里写的不是颜色值，是语义令牌：

https://www.yuque.com/u222739/why7ts/ugxdg4go2t7tlf9l

YAML 契约格式：理解了语义规范体系后，怎么写语义规则：

https://www.yuque.com/u222739/why7ts/orfwe0f15ga79wdg

6 个漂移模式：AI 生成界面的语义断层证据库：

https://www.yuque.com/u222739/why7ts/rwlzmucm3lgxzm10

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

https://www.yuque.com/u222739/why7ts/cn0l4ewmwvzeqsdo

编译管线是语义一致性的”机器翻译层”：

https://www.yuque.com/u222739/why7ts/yvrpvhwawyb9b54u

① 语义字典引用的机制防线：三层验证，证明语义可被机器执行：

https://www.yuque.com/u222739/why7ts/dxsrr7dt1b32clzq

角色专题 ② ｜前端与 AI 工程师：

https://www.yuque.com/u222739/why7ts/pspi1r6iypclto8x

角色专题 ①｜设计师与产品经理：

https://www.yuque.com/u222739/why7ts/nlwd1q32ny08n317