框架定义：当 AI 生成界面时，设计意图在偏离。Schema-As-Code 把设计规范写成代码格式，在语义层建立一套机器可读的约束契约，让 AI 在生成界面之前，先知道"这个场景下必须表达什么语义、不能突破什么边界"。框架不替代任何设计工具或 AI 工具，而是所有 AI 工具的上游约束层——AI 负责生成，规则负责把关。
本文定位：本文是阶段一 Guard 结构化诊断（Structured Diagnosis）的总结篇。阶段一回答"怎么发现语义断层"，核心路径是 Token（语义单元）→ Field（语义字段）→ Snapshot（语义快照）→ Pattern（漂移模式）。本文核心回答三个问题：① 怎么观察 AI 产品的语义漂移（方法论定义）；② 观察到了什么（证据库展示，简化版）；③ 这些观察怎么变成可执行的契约（技术架构论证，简化版）。阅读时间约 15 分钟，文末附下一阶段预告。
阶段一总结：从观察到模式
摘要
AI 正在从"辅助设计"走向"直接生成界面"。当界面从"人画"变成"AI 生成"，一个新的问题出现了：AI 生成的界面，意思对不对？
同样的红色按钮，在这个场景下是"删除"，在那个场景下是"保存"，AI 可能分不清楚。同样的 "Critical" 一词，在告警场景下被替换为"严重"、情绪权重被随机降级，用户可能低估风险。
这不是某个产品的设计缺陷，而是概率性生成带来的固有特性：AI 没有"语义权重"的概念，它只有"概率最接近"。
本文提出组件语义快照（Component Snapshot）作为观察方法，通过 6 个标准字段记录界面证据，归纳出 6 个漂移模式（模式库 v0.1），为阶段二 Contract 语义契约化（Semantic Contractualization）提供第一手素材。
1. 观察方法：组件语义快照
1.1 为什么不是普通截图？
普通截图只有像素信息，没有语义信息。一张某 AI 产品的报错截图，三个月后回看，你可能已经忘了：这是"什么类型"的组件？用户"怎么困惑"的？在"什么场景"下触发的？
组件语义快照是一种结构化的界面记录方法。在截图之上增加 6 个标准字段，让任何人在任何时间看到这张快照时，都能立刻理解问题全貌。关键设计判断：界面层是语义层的最终呈现面，但语义信息不能从界面像素中自动推导——一张红色的错误提示卡片，仅凭视觉无法判断它是"致命故障"还是"稍后再试"，因此必须有一种结构化格式，在记录视觉素材的同时锚定语义上下文。
1.2 6 个标准字段（v1.0 冻结，只增不减）
详细记录规范与字段释义见：《组件语义快照：我观察 AI 产品界面时用的 6 字段记录法》
| 字段 | 说明 | 示例 |
|---|---|---|
snapshot_id | 快照唯一编号（领域缩写-YYYYMMDD-三位序号） | ERR-20250608-001 |
product | 产品名称 | 某 AI 对话产品 A |
component_type | 组件类型（六大类型） | 错误状态 / 过程状态 / 边界动作 / 操作按钮 / 告警状态 / 信息状态 |
visual_record | 界面视觉素材（含语义标注） | 标注框圈出语义漂移发生的位置 |
user_confusion | 用户困惑描述（原话或注明依据的推断） | "看到红色就刷新，结果只是限流" |
context | 触发场景 | 高峰期快速发送 5 条消息后触发 |
1.3 完整示例
snapshot_id: ERR-20250608-001
product: 某 AI 对话产品 A
component_type: 错误状态
visual_record: [标注框圈出：4 种错误共用红色背景/文字——语义漂移发生的位置]
user_confusion: "看到红色就刷新，结果只是限流。红色让我以为系统崩了。"
context: 高峰期快速发送 5 条消息后触发
匹配模式: ERR-001（后果差异未分级）
更多快照模板与记录示例见：《组件语义快照》
2. 产品观察：8 类 AI 产品的语义漂移证据（简化版）
通过对 8 类 AI 产品的界面观察，发现语义漂移不是个案，是行业共性问题。
| 产品类型 | 代表产品方向 | 观察到的漂移现象 |
|---|---|---|
| 通用对话 | 国内外主流 AI 对话产品 | 错误状态共用红色，用户分不清后果 |
| 搜索增强 | 搜索类 AI 产品 | 过程状态标签模糊，用户不知道 AI 在干什么 |
| 代码生成 | AI 编程助手 | 高危操作按钮样式不统一，缺少二次确认 |
| 设计生成 | AI 原型工具 | 组件语义场景错位，告警按钮做成普通样式 |
| 企业组件 | 企业级组件库 | 组件用对了，但语义场景用错了 |
| 设计系统 | 设计规范工具 | 设计令牌只管颜色，不管场景语义 |
| 可观测性 | AI 观测平台 | 事后能发现漂移，但事前无法预防 |
| 多模态 | 文生视频/图产品 | 跨模态语义映射缺失，风格控制困难 |
说明：完整证据库（含截图、用户反馈、触发场景）见模式库详情页。本文仅展示归纳结论。
3. 组件分类与模式库：从证据到规律
3.1 6 大组件类型
语义漂移不是随机发生的，它集中在 6 类高频交互组件上——分类依据是用户交互路径而非视觉形态（详见：《组件语义分类与漂移模式匹配：从观察到归类的结构化规范》）（错误状态和告警状态都可能用红色，但用户的困惑不同，语义缺失不同）：
| 组件类型 | 用户核心困惑 | 典型漂移 |
|---|---|---|
| 错误状态 | "这有多严重？我该做什么？" | 多种错误共用同一种视觉 |
| 过程状态 | "AI 现在是在查资料还是在生成？" | 阶段标签模糊，认知不可见 |
| 边界动作 | "我的操作权限还在吗？" | 拒绝和终止表达混淆 |
| 操作按钮 | "点了会出大事吗？" | 高危操作做成普通样式 |
| 告警状态 | "这个词有多严重？" | 文案语义降级（如 Critical 被替换为"严重"） |
| 信息状态 | "这条信息我该在意吗？" | 全部信息同等权重，重要信息被淹没 |
3.2 6 个漂移模式（模式库 v0.1）
| 模式 ID | 组件类型 | 模式名称 | 根因 |
|---|---|---|---|
| ERR-001 | 错误状态 | 后果差异未分级 | 缺少 error_severity 语义令牌 |
| PRO-001 | 过程状态 | 认知阶段未显化 | 缺少 process_phase 语义令牌 |
| BND-001 | 边界动作 | 权利差异未区分 | 缺少 boundary_action 语义令牌 |
| ACT-001 | 操作按钮 | 高危操作未约束 | 缺少 destructive_action 语义令牌 |
| ALR-001 | 告警状态 | 文案语义降级 | 缺少 synonym_firewall 语义令牌 |
| INF-001 | 信息状态 | 状态权重未对齐 | 缺少 info_weight 语义令牌 |
完整模式证据库（含截图、用户反馈、触发场景）见：《6 个漂移模式：AI 生成界面的语义断层证据库》
说明：每个模式的完整证据（快照、用户反馈、YAML 契约）见模式库独立页面。每个模式节点的证据链包含 5 个标准字段：症状、根因、场景示例、快照证据、诊断报告。
4. 诊断机制：三层判定模型
组件语义快照积累到一定数量后，需要建立结构化的归类机制，将分散的界面记录转化为可追踪的模式节点。我将其定义为三层判定模型，每一层处理不同维度的语义信息，逐层收敛，最终输出模式匹配结果。
4.1 第一层：组件类型识别（Component Type Classification）
输入：单张组件语义快照（含 visual_record、context 字段）
判定逻辑：根据界面的交互路径，而非视觉形态，确定其归属的组件类型：
| 判定条件 | 组件类型 |
|---|---|
| 用户遭遇系统异常，操作被迫中断 | 错误状态 |
| AI 执行多步任务，用户等待过程中可见 | 过程状态 |
| 系统对请求作出拒绝、终止或升级审核响应 | 边界动作 |
| 用户主动发起，触发系统状态变更 | 操作按钮 |
| 系统主动推送，提示用户注意风险或状态变化 | 告警状态 |
| 用户接收通知与状态提示，无需立即行动 | 信息状态 |
边界处理：若单张快照同时满足多个组件类型的判定条件（如操作按钮触发后引发边界动作），标记为复合类型，后续需叠加应用多个组件类型的语义约束。
输出：component_type 标签（单值或复合值）
4.2 第二层：语义缺失判定（Semantic Deficiency Detection）
输入：已标注 component_type 的快照 + user_confusion 字段
判定逻辑：提取 user_confusion 中的语义关键词，匹配预设的语义缺失模式：
| 语义关键词特征 | 语义缺失类型 | 对应模式 ID |
|---|---|---|
| "不知道多严重""不知道该做什么""后果不明" | 后果差异未分级 | ERR-001 |
| "不知道在干什么""检索还是生成""可信度不明" | 认知阶段未显化 | PRO-001 |
| "上下文还在吗""还能继续吗""权利不明" | 权利差异未区分 | BND-001 |
| "点了会出大事吗""能撤销吗""风险不明" | 高危操作未约束 | ACT-001 |
| "这个词严重程度如何""是否被降级" | 文案语义降级 | ALR-001 |
| "要立即处理吗""会自己消失吗""忽略会怎样" | 状态权重未对齐 | INF-001 |
判定规则：关键词匹配采用包含逻辑而非精确匹配。单张快照的 user_confusion 可能同时触发多个语义缺失类型，此时按优先级排序（安全类 > 认知类 > 效率类），取最高优先级作为主导缺失类型，其余标记为关联缺失。
输出：semantic_deficiency 标签（主导类型 + 关联类型列表）
4.3 第三层：视觉表达校验（Visual Expression Validation）
输入：已标注 component_type 和 semantic_deficiency 的快照 + visual_record 字段
判定逻辑：对当前界面的视觉表达进行结构化校验，记录与语义级别不匹配的视觉映射：
| 校验项 | 校验内容 | 记录格式 |
|---|---|---|
| 颜色映射 | 颜色是否与语义级别匹配 | color_token: 实际值 → 预期值 |
| 文案精度 | 是否使用模糊词汇或禁止同义词 | text_precision: 实际文案 → 标准文案 |
| 行动完整性 | 是否提供与后果级别匹配的用户行动 | action_completeness: 缺失行动列表 |
示例：一张被标记为 ERR-001（后果差异未分级）的快照，visual_record 显示"限流错误使用了红色背景"，则记录为：
color_mapping_mismatch:
actual: "status.critical"（红色）
expected: "status.warning"（黄色）
severity_level: "retryable"
输出：visual_validation_report（含映射不匹配项、缺失项、冗余项）——这份视觉-语义映射差异记录，直接成为阶段二契约草稿的输入。
4.4 输出与归档
三层判定完成后，系统自动生成诊断报告，包含以下字段：
| 字段 | 来源 | 说明 |
|---|---|---|
matched_pattern | 第二层输出 | 主导模式 ID（如 ERR-001） |
confidence_score | 三层交叉验证 | 基于关键词匹配度 + 视觉校验一致性计算 |
missing_token | 模式库定义 | 该模式对应的缺失语义令牌（如 error_severity） |
visual_validation_report | 第三层输出 | 映射不匹配项、缺失项、冗余项 |
archive_path | 系统生成 | 该快照在模式库中的存储路径 |
next_action | 规则引擎判定 | "补充已有模式证据" 或 "触发新模式创建" |
归档规则：
confidence_score >= 0.85→ 自动归档到对应模式节点0.60 <= confidence_score < 0.85→ 标记为"待人工复核"confidence_score < 0.60→ 标记为"待归类"，触发新模式创建流程
三层判定模型的完整判定逻辑、规则引擎实现与置信度计算详见：《结构化诊断：三层判定模型与模式匹配机制》
机制说明：三层判定模型不是一次性问卷，而是可嵌入持续集成流程的自动化判定逻辑。实现现状：第一层组件类型识别基于规则引擎运行（准确率约 90%）；第二层语义缺失判定基于规则引擎运行（约 85%）；第三层中颜色映射已自动化（基于像素值），文案精度为半自动（OCR + NLP 辅助），行动完整性需人工复核。
5. 技术架构：从观察到契约的流转（简化版）
5.1 核心流转：Code-Text-Code（详见：《从观察到契约：Semantic Pipeline 的三阶段工作流》）
观察到的界面证据（截图/文本）→ 写成结构化文本（YAML 契约）→ 编译为机器可执行的产物（Prompt 前缀 / JSON Schema / Checklist / CI 规则 4 种消费格式）。
5.2 分工架构：AI 生成 + 规则把关
- AI 负责生成：发挥创造力，快速产出界面
- 契约负责把关：守住语义边界，防止语义漂移
5.3 四层推演引擎
生成结果的校验由四层推演引擎执行——语法层（结构是否合法）→ 语义层（令牌是否按契约表达）→ 安全层（是否触碰不可变边界）→ 美感层（视觉权重与语义权重一致性），逐层校验、逐层短路，失败定位到具体契约条款。
说明：完整技术架构（语义字典 → YAML 契约 → 编译管线，契约库提供组织级管理）见工程实现文档。本文仅保留核心流转逻辑。
6. 可运行代码示例：简单的语义分级器
以下是一段可直接运行的 Python 脚本，演示如何用规则对 AI 产品的错误文案进行语义分级（脚本与运行结果示例见语雀原文）。
说明：这是一个极简的规则引擎示例，用于演示"语义分级"的核心逻辑。演示环境的语义分级器已按此逻辑上线（模式库 Web：输入场景 → 输出应用的语义级别）；生产级实现需要更复杂的规则匹配和置信度计算。
7. 工程实现：Semantic Pipeline（简化版）
7.1 三阶段衔接
| 阶段 | 做什么 | 产出 |
|---|---|---|
| 阶段一 Guard 结构化诊断 | 组件语义快照 + 三层判定模型 | 模式匹配结果 + 诊断报告 |
| 阶段二 Contract 语义契约化 | YAML 契约 + 编译管线 | Prompt 前缀 / JSON Schema / Checklist / CI 规则 |
| 阶段三 Verify 验证闭环 | 四层推演 + 对比验证 | 验证报告 + 改进建议 |
7.2 消费方工作流（简化）（详见：《从观察到契约：Semantic Pipeline 的三阶段工作流》）
| 角色 | 怎么用 |
|---|---|
| 设计师 | 查字典 / 语义分级器定基线 → 按编译产物 Checklist 走查，结论注明契约版本号 |
| 前端 | 复制 Prompt 前缀 → 贴到 AI 指令里 → 生成符合语义的代码 |
| DesignOps | 改 YAML → Git 提交 → 编译管线自动重编译 → 下游自动同步 |
| AI 产品 PM | 收集验证数据，计算语义返工率、投诉归因分布 |
8. 定位：不是替代，是叠加（简化版）
现有工具（AI 原型工具、AI 编程助手、企业组件库）解决"怎么写代码"。Schema-As-Code 解决"这个场景下必须表达什么语义、不能突破什么边界"。
关系：Schema-As-Code 是所有形态层工具的上游约束层——组件库是底层（Underlay），语义覆盖层在组件之上加盖业务语义。
9. 组织价值（简化版）
| 指标 | 以前 | 以后 | 依据 |
|---|---|---|---|
| 语义返工率 | 30%（前端修 AI 语义错误） | 5% | 机器预拦截，人只处理例外 |
| 单次语义返工成本 | 50 分钟（发现 10 + 沟通 15 + 重生成 20 + 走查 5） | 5 分钟 | 发现与对齐由规则承担 |
| 规范同步时间 | 2 周（人工同步） | 0.5 天（Git Diff 自动） | 契约即代码 |
| 走查覆盖率 | 20%（人眼抽查） | 100%（CI 全量校验） | 机器走查 |
| 投诉归因 | 无法归因 | 可归因到模式 ID | 模式库索引 |
口径声明：以上数字均为数据模型推演，不是实测数据。接入生产环境后按此模型采集真实数据，验证或修正假设。
10. 下一阶段预告：从观察到契约
阶段一 Guard 结构化诊断（本文）解决了"发现问题"：
- ✅ 有了观察方法（组件语义快照 6 字段）
- ✅ 有了证据库（6 个漂移模式，模式库 v0.1）
- ✅ 有了诊断机制（三层判定模型）与工具（模式库 Web：语义分级器 / JSON 输入 / 快照模板）
- ✅ 有了可运行代码（语义分级器示例）
三阶段工作流的完整技术架构与消费方分工详见：《从观察到契约：Semantic Pipeline 的三阶段工作流》
阶段二 Contract 语义契约化（Semantic Contractualization）解决"写出契约"：
- 契约库（Contract Library）：浏览全部 YAML 契约，一键复制 4 种编译产物（Prompt 前缀 / JSON Schema / Checklist / CI 规则）
- 语义令牌与字典：Design Token 之上叠加语义令牌，让颜色携带场景语义；字典作为注册表保证全组织引用同一份定义
- 语义域：组件的语义边界——同一组件在不同域下语义不同，跨域引用机器拦截
阶段三 Verify 验证闭环（Validation Closure）解决"持续有效证明"：
- 四层推演引擎：语法 / 语义 / 安全 / 美感逐层校验；对抗用例对比验证，看有契约 vs 无契约的生成差异
- 在线分级器：输入错误文案，自动匹配 Fatal / Transient / Retryable / Degraded 分级
- 验证仪表盘：契约消费追踪 + 拦截归因，设计时约束 + 运行时归因，双轨闭环
下一步：记录你的第一张快照
阶段一的方法论已经完整展开。如果你也想开始观察自己产品的语义漂移——打开你的 AI 产品，触发一个错误状态，按本文的 6 字段格式记录第一张快照。第二张会比第一张快 10 倍。具体的字段定义与记录规范，详见下一篇《组件语义快照：我观察 AI 产品界面时用的 6 字段记录法》。
附录：阶段一资产速查表
| 资产 | 内容 | 版本口径 |
|---|---|---|
| 组件语义快照 | 6 字段结构化记录 | v1.0 冻结，只增不减 |
| 漂移模式库 | 6 个模式（ERR / PRO / BND / ACT / ALR / INF） | 模式库 v0.1 |
| 三层判定模型 | 组件类型识别 → 语义缺失判定 → 视觉表达校验 | 第一、二层规则引擎已实现 |
| 诊断报告 | matched_pattern / confidence_score / missing_token / visual_validation_report / archive_path / next_action | 归档阈值 0.85 / 0.60 |
| 模式库 Web | 语义分级器 / JSON 输入 / 快照模板 | 演示环境已上线 |
