框架定义：当 AI 生成界面时，设计意图在偏离。Schema-As-Code 把设计规范写成代码格式，在语义层建立一套机器可读的约束契约，让 AI 在生成界面之前，先知道"这个场景下必须表达什么语义、不能突破什么边界"。框架不替代任何设计工具或 AI 工具，而是所有 AI 工具的上游约束层——AI 负责生成，规则负责把关。
本文定位：本文是阶段二 Contract 语义契约化（Semantic Contractualization）的核心机制专题。阶段二由三部分组成：语义字典（上游·元规则）→ YAML 契约（中游·实例）→ 编译管线（下游·执行），契约库提供组织级管理。阶段一 Guard 结构化诊断的核心路径是 Token → Field → Snapshot → Pattern，回答"怎么发现语义断层"；阶段二的核心路径是 YAML 契约 → 编译管线 → 消费格式，回答"怎么把修复规则翻译成机器可执行的约束"。本文聚焦编译管线：如何把设计意图从 YAML 翻译为 4 种角色可直接消费的机器约束。
快速阅读：《阶段一 Guard：组件语义快照与模式诊断》[《阶段二 Contract：设计师作为"语义翻译者"》](YAML 契约 → 编译管线 → 消费格式，回答"怎么把修复规则翻译成机器可执行的约束"。本文聚焦编译管线：如何把设计意图从 YAML 翻译为 4 种角色可直接消费的机器约束。)《把设计规范写成代码格式，是所有 AI 工具的上游约束方法论》（方法论总纲与开源仓库）。
一、编译管线全景：四个阶段与一条流水线
Schema-As-Code 治理框架不是一套分散的文档，而是一条结构化编译流水线。每个阶段的上游产出，自动成为下游的输入，最终确保设计意图从"人脑中的想法"到"机器执行的约束"不丢失、不漂移。
编译管线的核心机制：
- 阶段一 Guard 结构化诊断：产出模式库，6 个跨产品的通用漂移模式
- 阶段二 Contract（语义字典）：定义覆盖层与绑定，元规则注册表
- 阶段二 Contract（YAML 契约）：将模式写成 YAML 契约，机器可读的设计意图定义
- 阶段二 Contract（编译管线）：将 YAML 编译为 4 种消费格式——Prompt 前缀、JSON Schema、Checklist、CI 规则
- 阶段三 Verify 验证闭环：让各角色消费这些格式，确保语义一致性落地
本文聚焦阶段二的编译管线。它与阶段一的"结构化诊断"是同一层级的方法论设计：诊断回答"怎么发现断层"，编译管线回答"怎么把修复规则变成机器约束"。
二、阶段一回顾：结构化诊断与模式库（上游输入）
2.1 设计路径：Token → 字段 → 快照 → 模式
编译管线的上游，是阶段一通过结构化诊断产出的模式库。详见《组件语义快照：我观察 AI 产品界面时用的 6 字段记录法》。诊断路径如下：
- Token 层：识别界面中最小语义单元，如 "Critical"、"严重"、"确认"
- Field 层：将 Token 聚合为语义字段，回答"这个界面缺少什么语义定义"
- Snapshot 层：用 6 字段结构化记录法固化单个实例
- Pattern 层：对快照聚类，提炼出 6 个跨产品通用模式
2.2 结构化的跨产品一致性记录方式
6 个漂移模式不是"截图收集"，而是一套结构化的跨产品一致性记录方式。每个模式用同一张表格记录：症状描述、根因分析、通用场景分类、以及跨产品的一致性证据。详见《6 个漂移模式：AI 生成界面的语义断层证据库》。
以下以 ERR-001（错误状态，后果差异未分级）为例，展示这套记录方式：
| 记录维度 | ERR-001 内容 |
|---|---|
| 症状描述 | 同一产品内多种错误状态（流式中断、网络故障、限流提示、服务异常）共用红色视觉语言，文案只描述现象（如"Error in message stream"），不说明后果严重程度，用户无法判断"这是刷新一下就好，还是对话已经丢了"。 |
| 根因分析 | 系统层面缺少 error_severity 语义令牌。前端只接收 isError=true 的布尔值，不接收错误性质（致命/抖动/限流/降级），因此只能统一渲染为红色。 |
| 通用场景分类 | ① 流式输出中断（对话上下文可能丢失）；② 网络层故障（系统可自动恢复）；③ 限流/流控（用户可自助恢复）；④ 服务端兜底（部分功能可用） |
| 跨产品一致性证据 | 国内外主流 AI 对话产品（包括通用型 LLM 助手、企业级 AI 客服、垂直领域 AI 应用）均存在此现象：流式输出中断、网络错误、请求频率限制、服务端异常等场景共用同一种红色视觉表达，未按后果严重程度分级。 |
2.3 诊断方法：三层判定模型
阶段一用于从"症状"到"根因"的诊断逻辑，详见《结构化诊断：三层判定模型与模式匹配机制》。三层判定模型提供了一套可复用的诊断流程：组件类型识别 → 语义缺失判定 → 视觉表达校验。该模型是阶段一到阶段二的桥梁：诊断出模式后，即可进入 YAML 契约编写。
2.4 模式总表：6 个漂移模式（按组件类型分类）
| 模式 ID | 组件类型 | 漂移模式 | 缺失的语义令牌 | 通用场景 |
|---|---|---|---|---|
| ERR-001 | 错误状态 | 后果差异未分级 | error_severity | 流式中断、网络故障、限流提示、服务异常等场景共用同一种视觉表达 |
| PRO-001 | 过程状态 | 认知阶段未显化 | process_phase | AI 生成内容时显示"搜索中/阅读中/总结中"，用户无法判断可信度阶段 |
| BND-001 | 边界动作 | 权利差异未区分 | boundary_action | AI 拒绝请求时，"拒绝继续"和"终止会话"在界面上无区分 |
| ACT-001 | 操作按钮 | 高危操作未约束 | destructive_action | 删除/转账/清空等不可逆操作按钮被做成普通样式，无二次确认 |
| ALR-001 | 告警状态 | 文案语义降级 | synonym_firewall | 告警级别词（如 Critical）被 LLM 降级为低情绪权重同义词 |
| INF-001 | 信息状态 | 状态权重未对齐 | info_weight | 系统通知与安全警告视觉权重相同，重要提示被淹没 |
模式库的价值：结构化的跨产品一致性证据。
三、阶段二：YAML 契约，设计意图的身份证（编译输入）
编译管线的直接输入，是阶段二产出的 YAML 语义契约。详见《YAML 契约格式》。
一份 YAML 契约由 7 个顶层字段组成，每个字段回答一个核心问题（intent_id"我是谁" / description"解决什么问题" / version"哪个版本" / semantic_domain"属于哪个语义域" / applicable_products"在哪些产品生效" / semantic_tokens"定义了什么语义" / immutable_boundaries"画了什么红线"）。
**YAML 契约是编译管线的唯一输入源。**所有下游消费格式（Prompt 前缀、JSON Schema、Checklist、CI 规则）都从这份 YAML 编译而来。
契约库的价值：当契约数量从 1 份增长到 20 份、50 份时，需要像管理代码一样管理契约——Git 版本、Diff 对比、分支并行、依赖追踪。编译管线消费契约库中的 YAML，输出消费格式。详见《契约库：让设计规范像代码一样管理》。
四、阶段二：编译管线，从契约到消费格式（本文主线）
4.1 编译管线的定义：语义翻译器
定义：编译管线是一条自动翻译流水线。输入为 YAML 语义契约，输出为 4 种消费格式，使语义约束在 AI 生成内容前即被注入，规范变更后自动同步至所有下游工具。
核心定位：不是代码编译器（不生成二进制），而是语义翻译器，将人类可读的设计意图翻译为机器可读的约束规则。
类比：设计 Token 工具（Style Dictionary）将 JSON Token 编译为 CSS 变量、iOS 颜色、Android 资源。编译管线将 YAML 契约编译为 Prompt 前缀、JSON Schema、Checklist、CI 规则。
4.2 编译的输入：YAML 哪些字段参与翻译
| YAML 字段 | 是否编译 | 编译去向 | 说明 |
|---|---|---|---|
intent_id | ✅ | 所有消费格式的标识头 | 版本追溯与问题归因 |
description | ✅ | Checklist 的说明文字 | 走查人员理解上下文 |
version | ✅ | 所有消费格式的版本声明 | 防止下游使用过期规则 |
semantic_domain / applicable_products | ✅ | Prompt 前缀的范围声明 | 避免规则误用 |
semantic_tokens | ✅ | Prompt 核心内容 + JSON Schema 枚举 | 语义级别与视觉映射 |
immutable_boundaries | ✅ | Prompt 阻断规则 + CI 阻断条件 | 安全红线 |
llm_constraints | ✅ | Prompt 强制指令 + Checklist 检查项 | 可执行的约束 |
| 注释/元数据 | ❌ | 仅供人类阅读 | 机器不消费 |
4.3 编译的输出：4 种消费格式
格式一：Prompt 前缀（供 AI 编程工具 / AI 原型工具消费）
编译逻辑：semantic_tokens 各级别 → Bullet list；immutable_boundaries → "绝对不能"条款；llm_constraints → "必须/禁止"指令。
# 基于 ERR-001 v1.0.0 编译的语义约束
在生成错误状态界面时，必须遵守以下规则：
## 错误级别与视觉映射
- 致命错误（Fatal）：必须使用红色脉冲 + 八边形警告图标 + 提供刷新/导出历史按钮
- 网络抖动（Transient）：必须使用灰色加载动画 + 显示自动重试进度 + 禁止用红色
- 限流提示（Retryable）：必须使用黄色提示 + 显示剩余等待时间 + 提供升级入口
- 降级错误（Degraded）：必须使用蓝色提示 + 说明哪些功能仍可用 + 提供继续生成按钮
## 不可突破的红线
- 绝对不能：把致命错误做成普通文字提示（没有背景色）
- 绝对不能：把限流提示做成红色（避免用户恐慌）
- 绝对不能：省略二次确认（仅针对高危操作）
## 对 AI 的强制要求
- 必须：在致命错误文案中说明"对话上下文可能已丢失"
- 必须：在限流提示中显示具体倒计时（如"42 分钟后重试"）
- 禁止：仅显示"出错了"等模糊文案
- 禁止：显示纯技术错误码（如 500 Internal Error）
格式二：JSON Schema（供结构校验 / 运行时校验消费）
编译逻辑：semantic_tokens 字段定义 → enum 约束、type 定义、必填检查。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ErrorStateComponent",
"description": "基于 ERR-001 v1.0.0 编译",
"type": "object",
"required": ["error_severity", "recovery_action", "user_message"],
"properties": {
"error_severity": { "type": "string", "enum": ["fatal", "transient", "retryable", "degraded"] },
"color_token": { "type": "string", "enum": ["status.critical", "status.neutral", "status.warning", "status.info"] },
"recovery_action": { "type": "array", "minItems": 1 },
"user_message": { "type": "string", "minLength": 10 }
}
}
格式三：Checklist（供设计师 / DesignOps 人工走查消费）
编译逻辑：llm_constraints → 勾选项；immutable_boundaries → 阻断项。
## 错误状态组件走查清单（基于 ERR-001 v1.0.0）
### 语义分级检查
- [ ] 错误状态是否按级别区分了颜色？（红/灰/黄/蓝）
- [ ] 致命错误是否使用了脉冲动画？
- [ ] 限流提示是否显示了具体倒计时？
- [ ] 降级错误是否说明了哪些功能仍可用？
### 文案检查
- [ ] 致命错误文案是否说明了"对话可能已丢失"？
- [ ] 是否禁止了仅显示"出错了"等模糊文案？
- [ ] 是否禁止了显示纯技术错误码（如 500）？
### 红线检查（违反即阻断）
- [ ] 是否把致命错误做成了普通文字？（绝对不能）
- [ ] 是否把限流提示做成了红色？（绝对不能）
- [ ] 是否遗漏了二次确认？（绝对不能，仅针对高危操作）
格式四：CI 规则（供自动化流水线消费）
编译逻辑：immutable_boundaries.violation_action: block → CI 阻断规则；semantic_tokens 枚举 → 静态检查允许值列表。
# .github/workflows/semantic-guard.yml
# 基于 ERR-001 v1.0.0 编译
name: Semantic Guard
on: [pull_request]
jobs:
semantic-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Check Error State Severity
run: |
if grep -r "severity=\"error\"" src/; then
echo "阻断：发现未分级的错误状态"
exit 1
fi
- name: Check Destructive Action Confirmation
run: |
if grep -r "destructive" src/ | grep -v "confirm"; then
echo "阻断：发现高危操作缺少二次确认"
exit 1
fi
4.4 编译映射规则：同一语义，四种表达
| YAML 源字段 | Prompt 前缀（给 AI 看） | JSON Schema（给机器看） | Checklist（给人看） | CI 规则（给流水线看） |
|---|---|---|---|---|
semantic_tokens.fatal.color_token | "致命错误必须使用红色脉冲样式" | severity: {enum: ["critical"]} | "[ ] 错误状态是否按级别区分颜色？" | if (severity !== "critical") fail() |
immutable_boundaries.rule | "绝对不能：[规则内容]" | required: ["confirmation_dialog"] | "[ ] 是否违反不可突破红线？" | block_on: ["destructive_without_confirm"] |
llm_constraints | "必须：[约束内容]" | minLength: 1 | "[ ] AI 输出是否满足所有强制要求？" | assert: constraints_passed |
设计原则：
- 信息分层：AI 看自然语言，机器看结构化代码，人看勾选项，同一语义，不同表达。
- 字段裁剪：Prompt 前缀不携带版本号（AI 不消费），Checklist 不携带底层语法（设计师不消费）。
- 语义一致：
fatal在四种格式中指向同一语义实体，仅表达方式适配消费方。
4.5 版本管理与自动同步：规范变更的闭环
问题：YAML 从 v1.0.0 升级到 v1.1.0（新增 degraded 级别），下游 Prompt 前缀仍为 v1.0.0，AI 不知道有第四级。
编译管线的解法：设计师提交 YAML 新版本 → Git 钩子触发编译管线 → 自动生成 4 种格式的新版本 → 自动通知下游（前端换 Prompt 前缀、DesignOps 换 Checklist、CI 规则下次提交生效）。每个产出文件头部嵌入版本声明：
# 基于 ERR-001 v1.1.0 编译
# 编译时间：2026-07-13
# 源文件：contracts/ERR-001.yaml
# 如有变更，请联系语义翻译设计师
4.6 编译验证：三层验证机制
| 验证层 | 验证对象 | 方法 | 输出 |
|---|---|---|---|
| 结构验证 | 编译后的 JSON Schema 是否合法 | Schema Validator | 结构合法性报告 |
| 语义验证 | Prompt 前缀是否被 AI 正确理解 | 测试用例集（输入已知错误文案，验证 AI 输出是否符合约束） | 语义准确性报告 |
| 一致性验证 | 四种格式是否表达同一语义 | 交叉比对（同一 fatal 在四种格式中的语义等价性） | 一致性报告 |
编译报告样例：
编译报告：ERR-001 v1.1.0
━━━━━━━━━━━━━━━━━━━━━━
✅ 结构验证通过
✅ 语义验证通过（10/10 测试用例）
✅ 一致性验证通过
输出文件：
📄 prompt-prefixes/ERR-001-v1.1.0.md
📄 json-schemas/ERR-001-v1.1.0.json
📄 checklists/ERR-001-v1.1.0.md
📄 ci-rules/ERR-001-v1.1.0.yml
五、阶段三预告：验证闭环与角色消费
编译管线的最终价值，是让各角色消费编译后的格式，确保语义一致性在组织内落地。
| 角色 | 消费什么 | 专题内容 |
|---|---|---|
| 设计师 / 产品经理 | 语义字典 + Checklist | 设计前查语义字典；走查时逐项核对 |
| 前端 / AI 工程师 | Prompt 前缀 + JSON Schema + CI 规则 | 在代码里接入语义校验，拦截语义漂移 |
| DesignOps | 契约库 + 编译报告 | 管理规范版本变更，确保全组织同步 |
| 管理层 / PM | 验证报告（通过率 / 拦截率 / ROI） | 量化语义治理的投入产出，推动组织采纳 |
角色专题不是重复编译管线的内容，而是回答"编译后的产物到了我手里，我怎么用它"。
六、编译管线的经济推演：从"人盯"到"机查"的成本结构
本节基于行业典型 AI 产品团队的通用推演模型，非真实生产数据。
核心假设：一个拥有多产品线的组织，每月发生数次设计规范变更，AI 生成内容已占日常产出的一定比例。
投入：
- 一次性：搭建编译管线约需数人天（写脚本、配 Git 钩子、定义首份 YAML）
- 持续性：设计师维护 YAML 契约（比写传统规范文档多约 20% 时间），每月少量时间维护编译配置
产出（三个维度的质变）：
- 规范同步从"周"变成"天"：以前改一次规范，需要人工通知、开会同步、逐个产品确认，周期以周计。现在改一份 YAML，Git 提交后自动编译、自动分发，周期以天计。
- 语义返工从"人眼抽查"变成"机器全检"：以前走查靠人眼，覆盖率受限于时间和人力，大量语义漂移上线后才被用户发现。现在机器按 YAML 规则自动检查全部产出，语义错误在生成前被拦截。
- 设计规范从"文档"变成"资产"：以前规范写在语雀/Confluence，更新后靠@全员通知，版本混乱、遗漏频发。现在规范以 YAML 形态存在 Git 仓库，Diff 可见、版本可追溯、变更可回滚，成为组织可复用的数字资产。
推演结论：编译管线的投入是一次性的（数人天），但产出是持续性的，每次规范变更、每个新增产品、每轮 AI 生成，都在复用同一套规则。随着 AI 生成内容占比提升，边际成本趋近于零，边际收益持续放大。这不是"多买了一套工具"，而是把语义一致性的保障方式从线性人力投入转变为指数级机器杠杆。
七、结语：语义翻译设计师的独立赛道
设计师的传统角色正在经历结构性转移：
- 视觉生产层：AI 已能生成符合设计规范的代码（DevUI HMC、v0、Claude Design），"画图-还原"的价值链被压缩。
- 语义定义层：AI 无法自主判断"这个场景下必须表达什么语义、不能突破什么边界"，这是人类的决策领域。
编译管线是语义翻译设计师的核心产出物：它不是设计稿，而是一条规则流水线；它让设计规范从"文档"变成"代码"，从"人读"变成"机读"；它让设计师从"视觉生产者"变成"语义规则的定义者与翻译者"。
组织为什么需要语义翻译设计师：不是因为其能产出更精美的界面，而是因为其能建立设计意图在概率性界面时代的防稀释机制——通过编译管线，将设计意图从人类大脑中的隐性知识，转化为机器可消费的显性约束，确保 AI 生成内容在任何工具、任何框架、任何产品中的语义一致性。
这就是语义翻译设计师的独立赛道：不为 AI 工具定义"长什么样"，而为 AI 工具定义"这意味着什么"。编译管线是这一赛道的核心基础设施。
下一步：契约引用的覆盖层从哪里来
编译管线能校验"契约引用是否合法"，前提是有一份全组织唯一的覆盖层注册表。下一篇是阶段二的收尾篇，定义语义字典：覆盖层模型、三层结构（覆盖层目录 / 语义重绑定 / 场景映射）与治理机制。详见下一篇《语义字典：设计系统组件的语义覆盖层》。
附录：编译管线产出物清单
| 产出物 | 格式 | 消费方 | 生成来源字段 |
|---|---|---|---|
| Prompt 前缀 | .md | Claude Code / Cursor / Copilot / v0 | immutable_boundaries + 各级 llm_constraints + semantic_tokens |
| JSON Schema | .json | 前端 Props 校验 | semantic_tokens 结构与枚举 |
| Checklist | .md | 设计师 / DesignOps 走查 | llm_constraints → 勾选项；immutable_boundaries → 阻断项 |
| CI 规则 | .js / .yml | ESLint / CI 流水线 | violation_action: block 的边界规则化 |
同步保证：4 种格式全部由编译管线从同一份 YAML 产出，文件头部嵌入版本声明（源契约、版本、编译时间）；手工修改衍生格式在 CI 中被拒绝。
