从观察到契约：Semantic Pipeline 的三阶段工作流
本文是 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 生成结果
设计师不需要写代码，只需要确认"这个契约表达的意思对不对"。
| 维度 | 内容 |
|---|---|
| 日常工具 | Figma、语雀 |
| 使用场景 | 走查发现某个组件体验不对 |
| 操作路径 | 打开 Semantic Pipeline → 回答 3 个问题 → 匹配模式 |
| 得到什么 | 模式定义 + 同类证据 + 改造方案 |
6.2 DesignOps
- 阶段二：审核契约变更，通过 Git Diff 同步到所有下游工具
- 阶段三：监控验证数据，量化语义一致性指标
DesignOps 是契约的版本管理者，确保规范变更能被所有消费方自动感知。
| 维度 | 内容 |
|---|---|
| 日常工具 | GitHub、Notion |
| 使用场景 | 规范要更新，不知道怎么同步到所有 AI 产品 |
| 操作路径 | 把规范变更写成 YAML → Git Diff 自动触发影响面分析 |
| 得到什么 | 规范同步从 2 周 → 0.5 天 |
6.3 前端工程师
- 阶段二：复制 Prompt 前缀，贴到 AI 编程工具（Claude Code / Cursor）的指令里
- 阶段三：查看 CI 校验结果，修复机器标记的语义违规
前端工程师不需要理解语义理论，只需要知道"在指令前贴这段规则，AI 就不会生成错误的语义"。
| 维度 | 内容 |
|---|---|
| 日常工具 | VS Code、Cursor、Claude Code |
| 使用场景 | AI 生成的代码语义错误多，返工率高 |
| 操作路径 | 在 Prompt 里贴一段规则前缀（从契约库复制） |
| 得到什么 | 语义返工率从 30% → 5% |
6.4 AI 产品 PM
- 阶段三：收集验证数据，计算语义返工率、线上语义事故占比
- 反馈：用数据驱动契约迭代，识别哪些模式需要优先修复
AI 产品 PM 用数据回答"约束显化是否真的有 ROI"。
| 维度 | 内容 |
|---|---|
| 日常工具 | 飞书、Jira |
| 使用场景 | 要上线 AI 功能，担心体验不一致 |
| 操作路径 | 用验证工具跑一遍产品的错误状态 |
| 得到什么 | 风险清单 + 契约模板 |
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 原生｜广州 / 深圳