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

本文是Schema-As-Code治理框架的关键设计，与阶段一"结构化诊断"方法论平行。 阶段一（结构化诊断）的核心路径是Token → 字段 → 快照 → 模式，回答"怎么发现语义断层"；阶段二（语义契约）的核心路径是YAML契约 → 编译管线 → 消费格式，回答"怎么把修复规则翻译成机器可执行的约束"。阶段二由三部分组成：语义契约、编译管线、语义字典与操作手册。 本文聚焦阶段二（语义契约）的编译管线的核心机制：如何把设计意图从YAML翻译为不同角色可直接消费的机器约束。

快速阅读：

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

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

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

1. 编译管线全景 四个阶段与一条流水线

Schema-As-Code治理框架不是一套分散的文档，而是一条结构化编译流水线。

每个阶段的上游产出，自动成为下游的输入，最终确保设计意图从"人脑中的想法"到"机器执行的约束"不丢失、不漂移。

编译管线的核心机制：

• 阶段一（结构化诊断）产出模式库，6个跨产品的通用漂移模式
• 阶段二（语义契约）将模式写成YAML契约，机器可读的设计意图定义
• 阶段二（编译管线）将YAML编译为4种消费格式，Prompt前缀、JSON Schema、Checklist、CI规则
• 阶段二（语义字典与操作手册）提供配套资产，术语定义、使用指南、最佳实践
• 阶段三（验证闭环）让5类角色消费这些格式，确保语义一致性落地

本文聚焦阶段二的编译管线。

与阶段一的"结构化诊断"是同一层级的方法论设计：诊断回答"怎么发现断层"，编译管线回答"怎么把修复规则变成机器约束"。

理解这一点，才能理解编译管线在治理框架中的核心位置。

2. 阶段一回顾 结构化诊断与模式库（上游输入）

2.1 设计路径：Token → 字段 → 快照 → 模式

编译管线的上游，是阶段一通过结构化诊断产出的模式库。

详见：组件语义快照：我观察AI产品界面时用的6字段记录法

诊断路径如下：

Token（语义单元）
  ↓ 聚合为
Field（语义字段）：error_severity / process_phase / boundary_action
  ↓ 实例化为
Snapshot（语义快照）：6 字段记录法记录单个界面
  ↓ 聚类为
Pattern（漂移模式）：跨产品、跨场景的通用语义断层类型

Token 层：识别界面中最小语义单元 如 "Critical"、"严重"、"确认"。 Field 层：将Token聚合为语义字段，回答"这个界面缺少什么语义定义"。 Snapshot 层：用结构化记录法（组件类型、语义字段、视觉表达、文案、用户行动、上下文）固化单个实例。 Pattern 层：对20+个快照聚类，提炼出6个跨产品通用模式。

2.2 结构化的跨产品一致性记录方式

6个漂移模式是一套结构化的跨产品一致性记录方式。

每个模式用同一张表格记录：症状描述、根因分析、通用场景分类、以及跨产品的一致性证据。

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

以 ERR-001（错误状态 后果差异未分级） 为例：

2.3 诊断方法：三层判定模型

阶段一用于从"症状"到"根因"的诊断逻辑

详见结构化诊断：三层判定模型与模式匹配机制

三层判定模型提供了一套可复用的诊断流程：

• 第一层：症状层，观察界面现象（颜色、文案、用户行动）
• 第二层：字段层，判断缺少哪个语义字段。
• 第三层：根因层，定位系统缺失的语义令牌定义。

该模型是阶段一到阶段二的桥梁：诊断出模式后，即可进入YAML契约编写。

2.4 模式总表：6 个漂移模式（按组件类型分类）

模式库的价值：结构化的跨产品一致性证据。

3. 阶段二 YAML 契约设计意图的身份证（编译输入）

编译管线的直接输入，是阶段二第一部分产出的YAML语义契约。

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

一份YAML契约由6个顶层字段组成，回答6个核心问题：

intent_id:          "我是谁？"              → 契约唯一标识，如 ERR-001
description:        "我解决什么问题？"       → 一句话说明语义问题
version:            "我是哪个版本？"         → 语义版本，变更触发重编译
applicable_products: "我在哪些产品生效？"    → 防止规则误用
semantic_tokens:     "我定义了什么语义？"     → 核心：级别、视觉、行动
immutable_boundaries: "我画了什么红线？"       → 绝对不能做什么
llm_constraints:     "我对 AI 有什么强制要求？" → 必须包含什么、禁止省略什么

YAML契约是编译管线的唯一输入源。

所有下游消费格式（Prompt前缀、JSON Schema、Checklist、CI规则）都从这份YAML编译而来。

契约库的价值：当契约数量从1份增长到20份、50份时，需要像管理代码一样管理契约，Git版本、Diff对比、分支并行、依赖追踪。编译管线消费契约库中的YAML，输出消费格式。

详见《契约库：让设计规范像代码一样管理》。

4. 阶段二：编译管线，从契约到消费格式（本文主线）

4.1 编译管线的定义：语义翻译器

定义：编译管线是一条自动翻译流水线。输入为YAML语义契约，输出为4种消费格式，使语义约束在AI生成内容前即被注入，规范变更后自动同步至所有下游工具。

核心定位：不是代码编译器（不生成二进制），而是语义翻译器，将人类可读的设计意图翻译为机器可读的约束规则。

类比：设计Token工具（Style Dictionary）将JSON Token编译为CSS变量、iOS颜色、Android资源。

编译管线将YAML契约编译为Prompt前缀、JSON Schema、Checklist、CI规则。

4.2 编译的输入：YAML 哪些字段参与翻译

4.3 编译的输出：4种消费格式

格式一：Prompt前缀（供AI编程工具 / AI原型工具消费）

编译逻辑：

• semantic_tokens 各级别 → Bullet list
• immutable_boundaries → "绝对不能"条款
• llm_constraints → "必须/禁止"指令

输出样例（基于 ERR-001 编译）：

# 基于 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": ["severity_level", "recovery_action", "user_message"],
  "properties": {
    "severity_level": {
      "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 编译映射规则：同一语义，四种表达

设计原则：

1. 信息分层：AI看自然语言，机器看结构化代码，人看勾选项，同一语义，不同表达。
2. 字段裁剪：Prompt前缀不携带版本号（AI不消费），Checklist不携带底层语法（设计师不消费）。
3. 语义一致：fatal 在四种格式中指向同一语义实体，仅表达方式适配消费方。

4.5 版本管理与自动同步：规范变更的闭环

问题：YAML从v1.0.0升级到v1.1.0（新增 degraded 级别），下游Prompt前缀仍为 v1.0.0，AI不知道有第四级。

编译管线的解法：

设计师提交 YAML v1.1.0
    ↓
Git 钩子触发编译管线
    ↓
自动生成 4 种格式的新版本
    ↓
自动通知下游：
    - 前端：Prompt 前缀已更新，请替换
    - 设计Ops：Checklist 已更新
    - 工程师：CI 规则已更新，下次提交生效

版本声明（嵌入每个产出文件头部）：

# 基于 ERR-001 v1.1.0 编译
# 编译时间：2026-07-13
# 源文件：intent/ERR-001.yaml
# 如有变更，请联系语义翻译设计师

4.6 编译验证：三层验证机制

编译报告样例：

编译报告：ERR-001 v1.1.0
━━━━━━━━━━━━━━━━━━━━━━
✅ 结构验证通过
✅ 语义验证通过（10/10 测试用例）
✅ 一致性验证通过

输出文件：
  📄 prompt-prefix/ERR-001-v1.1.0.md
  📄 json-schema/ERR-001-v1.1.0.json
  📄 checklist/ERR-001-v1.1.0.md
  📄 ci-rules/ERR-001-v1.1.0.yml

5. 阶段二 预告：语义字典与操作手册

编译管线的第三个配套资产，是语义字典与操作手册。

语义字典：统一术语定义，确保组织内所有人对"致命错误""语义降级""同义词防火墙"等概念的理解一致。

操作手册：为每个角色提供使用指南，设计师怎么写YAML、前端怎么贴Prompt前缀、DesignOps怎么管理版本变更。

这两者是编译管线的配套资产，不是独立阶段。它们让编译管线的产出物从"可用"变成"易用"。

6. 阶段三预告：验证闭环与角色消费

编译管线的最终价值，是让5类角色消费编译后的格式确保语义一致性在组织内落地。

角色专题回答"编译后的产物到了我手里，我怎么用它"。

7. 编译管线的经济推演 从"人盯"到"机查"的成本结构

本节基于行业典型AI产品团队的通用推演模型，非真实生产数据。

核心假设：一个拥有多产品线的组织，每月发生数次设计规范变更，AI生成内容已占日常产出的一定比例。

投入：

• 一次性：搭建编译管线约需数人天（写脚本、配Git钩子、定义首份YAML）
• 持续性：设计师维护YAML契约（比写传统规范文档多约20%时间），每月少量时间维护编译配置

产出（三个维度的质变）：

1. 规范同步从"周"变成"天" 以前改一次规范，需要人工通知、开会同步、逐个产品确认，周期以周计。现在改一份YAML，Git提交后自动编译、自动分发，周期以天计。
2. 语义返工从"人眼抽查"变成"机器全检" 以前走查靠人眼，覆盖率受限于时间和人力，大量语义漂移上线后才被用户发现。现在机器按YAML规则自动检查全部产出，语义错误在生成前被拦截。
3. 设计规范从"文档"变成"资产" 以前规范写在语雀/Confluence，更新后靠@全员通知，版本混乱、遗漏频发。现在规范以YAML形态存在Git仓库，Diff可见、版本可追溯、变更可回滚，成为组织可复用的数字资产。

推演结论： 编译管线的投入是一次性的（数人天），但产出是持续性的，每次规范变更、每个新增产品、每轮AI生成，都在复用同一套规则。随着AI生成内容占比提升，边际成本趋近于零，边际收益持续放大。

这不是"多买了一套工具"，而是把语义一致性的保障方式从线性人力投入转变为指数级机器杠杆。

8. 结语：语义翻译设计师的独立赛道

设计师的传统角色正在经历结构性转移：

• 视觉生产层：AI已能生成符合设计规范的代码，"画图-还原"的价值链被压缩。
• 语义定义层：AI无法自主判断"这个场景下必须表达什么语义、不能突破什么边界"，这是人类的决策领域。

编译管线是语义翻译设计师的核心产出物：

• 它不是设计稿，而是一条规则流水线；
• 它让设计规范从"文档"变成"代码"，从"人读"变成"机读"；
• 它让设计师从"视觉生产者"变成"语义规则的定义者与翻译者"。

组织为什么需要语义翻译设计师：

不是因为其能产出更精美的界面，而是因为其能建立设计意图在概率性界面时代的防稀释机制，通过编译管线，将设计意图从人类大脑中的隐性知识，转化为机器可消费的显性约束，确保 AI 生成内容在任何工具、任何框架、任何产品中的语义一致性。

这就是语义翻译设计师的独立赛道：

不为AI工具定义"长什么样"，而为AI工具定义"这意味着什么"。

编译管线是这一赛道的核心基础设施。

本文是 Schema-As-Code 治理框架阶段二《编译管线》的关键设计文章。阶段二由三部分组成：语义契约、编译管线、语义字典与操作手册。本文聚焦编译管线的核心机制。后续将发布《语义字典与操作手册》，然后进入阶段三《验证闭环》的五个角色专题。