本文是 把设计规范写成代码格式（Schema-As-Code） 方法论的阶段衔接文档。在前两篇文章定义了观察方法（组件语义快照）和证据库（6 个漂移模式）的基础上，本文提出三阶段工作流，说明观察证据如何转化为机器可读的约束契约，以及如何验证契约的有效性。
本文基于 《组件语义快照与模式诊断：AI 生成界面的第一道检查》 中的概念继续展开。
一、为什么需要三阶段工作流
组件语义快照记录了界面层的语义漂移证据，漂移模式库归纳了这些证据的共性规律。但记录和归纳本身不解决实际问题——它们只是让问题可见。
要让问题可解，需要建立一条从"观察"到"约束"再到"验证"的完整链路。这条链路需要回答三个问题：
- 怎么发现？ 用什么方法捕获语义漂移？
- 怎么约束？ 用什么格式定义语义规则，让机器能读懂？
- 怎么验证？ 怎么证明约束生效了，漂移减少了？
三阶段工作流（Guard → Contract → Verify）就是围绕这三个问题设计的。每个阶段有明确的输入、处理和输出，阶段之间通过标准格式衔接。
二、阶段一：Guard（发现问题）
输入：AI 产品界面（错误状态、过程状态、操作按钮等组件）
处理：
- 使用组件语义快照（6 字段记录法）采集界面证据
- 通过诊断问卷（3 个问题）匹配漂移模式
- 将证据归档到模式库
输出：模式匹配结果（如 ERR-001、PRO-001）+ 结构化证据（YAML 格式快照）
阶段一的核心价值：让语义漂移从"感觉不对劲"变成"可被命名和引用的问题"。
阶段一的详细方法已在《组件语义快照：我观察 AI 产品界面时用的 6 字段记录法》中定义，阶段一的产出（6 个漂移模式）已在《6 个漂移模式：AI 生成界面的语义断层证据库》中归纳。本文不再重复，仅说明其作为阶段二输入的衔接关系。
三、阶段二：Contract（写契约）
输入：阶段一的模式匹配结果（如 ERR-001"后果差异未分级"）
处理：
将模式对应的缺失语义令牌，形式化为机器可读的约束契约。契约采用 YAML 格式，包含三个核心部分：
3.1 语义令牌定义（Semantic Tokens）
定义该组件类型下有哪些语义级别，每个级别的含义、视觉映射和用户行动。
以 ERR-001 为例：
semantic_tokens:
error_severity:
fatal:
description: "流式输出中断，对话上下文可能丢失"
visual_mapping:
color_token: "status.critical"
motion_token: "pulse.red.urgent"
icon_token: "alert.octagon"
user_action: ["refresh_page", "export_history"]
transient:
description: "网络抖动，系统可自动恢复"
visual_mapping:
color_token: "status.neutral"
motion_token: "spinner"
icon_token: "loader"
user_action: ["wait_auto_retry"]
retryable:
description: "用户可自助恢复的频率限制"
visual_mapping:
color_token: "status.warning"
motion_token: "none"
icon_token: "clock"
user_action: ["upgrade_plan", "set_reminder"]
degraded:
description: "部分功能可用，可继续生成"
visual_mapping:
color_token: "status.info"
motion_token: "none"
icon_token: "continue"
user_action: ["continue_generation"]
3.2 不可变边界（Immutable Boundaries）
定义 AI 在该场景下绝对不能做的事。
immutable_boundaries:
- boundary_type: "safety"
rule: "禁止将致命错误设计为灰色提示"
violation_action: "block"
- boundary_type: "safety"
rule: "禁止将限流错误设计为红色背景"
violation_action: "block"
3.3 LLM 约束（LLM Constraints）
定义 AI 在生成文案时必须遵守的规则。
llm_constraints:
- "必须明确告知用户对话上下文可能已丢失"
- "禁止仅显示'出错了'等模糊文案"
- "必须提供恢复路径"
3.4 编译输出（Compiled Outputs）
YAML 契约本身不直接作用于 AI 工具，需要通过编译器转换为不同消费方可使用的格式：
| 输出格式 | 消费方 | 用途 |
|---|---|---|
| Prompt 前缀 | 前端工程师 / AI 编程工具 | 放在 Claude Code / Cursor 指令前，约束 AI 生成 |
| Checklist | 设计师 / DesignOps | 走查时逐项核对 |
| CI 规则 | 前端工程化 | 代码提交时自动校验组件 Props |
| Figma 插件规则 | 设计师 | 画稿时实时标记语义违规 |
| JSON Schema | 后端 / API 校验 | 校验 AI 输出数据的结构合规性 |
阶段二的核心价值：把"设计意图"从人的大脑里，翻译成机器能查清单的规则。
四、阶段三：Verify（跑验证）
输入：阶段二生成的契约（YAML + 编译输出）
处理：
通过四层检查引擎，验证 AI 生成的内容是否符合契约约束。
4.1 四层检查
| 层级 | 检查什么 | 方法 |
|---|---|---|
| 语法检查 | 输出结构是否完整 | Schema 校验（字段齐全、类型正确） |
| 语义检查 | 语义令牌引用是否正确 | 关键词匹配、同义词防火墙 |
| 安全检查 | 是否触碰不可变边界 | 规则引擎判定（如"高危按钮不能是蓝色实心"） |
| 美感检查 | 信息密度是否在合理范围 | 文案长度、视觉权重比例 |
4.2 A/B 对比验证
验证的核心方法是有契约 vs 无契约的对比：
- 无契约组：让 AI 按默认方式生成组件，记录输出结果
- 有契约组：在 AI 指令前注入 Prompt 前缀（阶段二编译输出），记录输出结果
- 对比维度：语义准确率、用户行动明确率、返工率
4.3 验证闭环
验证结果反哺前两阶段：
- 如果验证通过 → 契约正式生效，归档到契约库
- 如果验证失败 → 回到阶段二修正契约，或回到阶段一补充证据
阶段三的核心价值：证明约束不是纸上谈兵，而是能实际减少语义漂移的可执行规则。
五、三阶段的数据流转
阶段一 Guard
├── 输入：AI 产品界面
├── 处理：组件语义快照 + 诊断问卷
├── 输出：模式匹配结果（ERR-001）+ 结构化证据
│
阶段二 Contract
├── 输入：模式匹配结果（ERR-001）
├── 处理：YAML 契约定义 + 编译输出
├── 输出：Prompt 前缀 / Checklist / CI 规则
│
阶段三 Verify
├── 输入：契约编译输出
├── 处理：四层检查 + A/B 对比
├── 输出：验证报告 + 改进建议
│
反馈回路
└── 验证失败 → 回到阶段二修正契约
└── 验证通过 → 契约生效，归档到库
每个阶段的输出都是下一个阶段的输入，标准格式是 YAML。这种设计使得：
- 阶段一的设计师不需要懂阶段三的校验逻辑
- 阶段三的前端工程师不需要懂阶段一的观察方法
- 但所有人都能通过 YAML 文件理解当前契约的状态
六、四个角色的工作流
三阶段工作流不是为单个人设计的，而是为四个角色提供协作界面：
6.1 设计师
- 阶段一：使用组件语义快照记录走查中发现的语义问题
- 阶段二：审核 YAML 契约中的语义定义是否符合设计意图
- 阶段三：使用 Checklist 验证 AI 生成结果
设计师不需要写代码，只需要确认"这个契约表达的意思对不对"。
6.2 前端工程师
- 阶段二：复制 Prompt 前缀，贴到 AI 编程工具（Claude Code / Cursor）的指令里
- 阶段三：查看 CI 校验结果，修复机器标记的语义违规
- 契约维护：当设计规范更新时，更新 YAML 文件并重新编译
前端工程师不需要理解语义理论，只需要知道"在指令前贴这段规则，AI 就不会生成错误的语义"。
6.3 DesignOps
- 阶段一：管理模式库的归档和分类
- 阶段二：审核契约变更，通过 Git Diff 同步到所有下游工具
- 阶段三：监控验证数据，量化语义一致性指标
DesignOps 是契约的版本管理者，确保规范变更能被所有消费方自动感知。
6.4 AI PM
- 阶段三：收集验证数据，计算语义返工率、线上语义事故占比
- 反馈：用数据驱动契约迭代，识别哪些模式需要优先修复
效能团队用数据回答"约束显化是否真的有 ROI"。
七、与现有工具的关系：不是替代，是叠加
三阶段工作流不替代任何现有工具，而是在它们的上游增加一层语义约束。
| 现有工具 | 解决什么 | 三阶段工作流补充什么 |
|---|---|---|
| v0 / Framer AI | 从自然语言生成可交互原型 | 在生成前注入语义约束，防止原型语义漂移 |
| Claude Code / Cursor | 从自然语言生成生产代码 | 在指令前注入 Prompt 前缀，约束代码语义 |
| DevUI HMC / Ant Design | 生成符合组件库的代码 | 在组件选择之上叠加语义场景约束 |
| DESIGN.md / Figma MCP | 视觉规范的机器可读化 | 在视觉规范之上叠加语义层 |
| LoongSuite / LangSmith | 运行时语义漂移观测 | 在设计时预防漂移，与运行时观测形成双轨闭环 |
关系逻辑：现有工具在形态层（视觉、代码、组件）竞争，三阶段工作流在语义层补位。YAML 语义契约可被任何工具消费——约束的不是"怎么写代码"，而是"这个场景下必须表达什么语义、不能突破什么边界"。
八、局限与下一步
8.1 当前局限
- 阶段一依赖人工观察：组件语义快照需要观察者具备语义敏感度，无法全自动采集。
- 阶段二契约未经验证：6 个模式的 YAML 契约目前基于归纳得出，尚未经过大规模产品验证。
- 阶段三验证工具不完整：四层检查引擎目前仅实现语义检查和部分安全检查，语法检查和美感检查仍需完善。
- 跨工具消费尚未打通：Prompt 前缀、CI 规则、Figma 插件等编译输出目前为手动复制，尚未实现自动注入。
8.2 下一步计划
- 短期：完善 6 个模式的 YAML 契约草案，提供可复制的 Prompt 前缀和 Checklist。
- 中期：搭建在线验证实验室，支持输入任意 AI 生成文案，自动跑四层检查并输出对比报告。
- 长期：与现有工具（Claude Code、Figma、DevUI HMC）建立消费接口，实现契约的自动编译和注入。
九、结语
Semantic Pipeline 的三阶段工作流（Guard → Contract → Verify）试图建立一条从"发现问题"到"约束问题"再到"验证约束"的完整链路。
它的核心假设是：语义一致性不能仅靠人眼保证，必须依赖机器可读的规则。 但规则的制定权仍属于人——设计师定义语义意图，工程师定义技术约束，机器负责执行和校验。
这条链路目前处于早期阶段。阶段一的方法（组件语义快照）和产出（6 个漂移模式）已初步验证，阶段二和阶段三的工具和流程仍需迭代。后续文章将发布具体的契约模板和验证工具，供实际工作流中使用。
Gap 期局限性声明
当前状态： 架构推演与最小可行原型阶段。YAML 规范、校验逻辑为定义层实现，尚未接入生产级 LLM API 或 CI 流水线。欢迎基于现有思路共建。
关于作者
魏雯，体验架构设计师。
专注于：AI 界面的语义治理。解决的核心问题：让 LLM 生成的界面不偏离设计规范。
10+ 年互联网设计经验。设计系统 / 体验工程 / AI 原生｜广州 / 深圳
