从观察到契约：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.criticalmotion_token:pulse.red.urgenticon_token:alert.octagonuser_action:[refresh_page,export_history]transient:description:网络抖动系统可自动恢复visual_mapping:color_token:status.neutralmotion_token:spinnericon_token:loaderuser_action:[wait_auto_retry]retryable:description:用户可自助恢复的频率限制visual_mapping:color_token:status.warningmotion_token:noneicon_token:clockuser_action:[upgrade_plan,set_reminder]degraded:description:部分功能可用可继续生成visual_mapping:color_token:status.infomotion_token:noneicon_token:continueuser_action:[continue_generation]3.2 不可变边界Immutable Boundaries定义 AI 在该场景下绝对不能做的事。immutable_boundaries:-boundary_type:safetyrule:禁止将致命错误设计为灰色提示violation_action:block-boundary_type:safetyrule:禁止将限流错误设计为红色背景violation_action:block3.3 LLM 约束LLM Constraints定义 AI 在生成文案时必须遵守的规则。llm_constraints:-必须明确告知用户对话上下文可能已丢失-禁止仅显示出错了等模糊文案-必须提供恢复路径3.4 编译输出Compiled OutputsYAML 契约本身不直接作用于 AI 工具需要通过编译器转换为不同消费方可使用的格式输出格式消费方用途Prompt 前缀前端工程师 / AI 编程工具放在 Claude Code / Cursor 指令前约束 AI 生成Checklist设计师 / DesignOps走查时逐项核对CI 规则前端工程化代码提交时自动校验组件 PropsFigma 插件规则设计师画稿时实时标记语义违规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 原生广州 / 深圳