前端与 AI 工程师：把语义约束写进 AI 的生成上下文

AI生成代码的"伪正确"已被广泛讨论：能通过编译、看起来专业、业务逻辑却是错的。这条讨论通常止步于代码逻辑，但同构的问题发生在界面语义层：AI把"余额不足"生成红色报警，TypeScript编译通过、组件来自组件库、色值符合规范，语法层面找不到任何错，用户却已经收到了错误的信号。代码侧有类型系统与测试兜底，界面语义侧此前没有任何机器可执行的校验。Schema-As-Code要补的正是这一层。

框架定义：当AI生成界面时，设计意图在偏离。Schema-As-Code在语义层建立一套机器可读的约束契约（机器可执行的规则文件），让AI在生成界面之前，先知道"这个场景下必须表达什么语义、不能突破什么边界"。框架不替代任何设计工具或AI工具，而是所有AI工具的上游约束层，AI负责生成，规则负责把关。

本文定位：以前端与AI工程师为入口，呈现该角色在框架中的完整消费路径，验证框架在真实工程链路中的可用性。后续将从DesignOps、语义翻译设计师、管理层各自的入口进入同一框架；框架交付件、案例库与落地验证另篇呈现。

一、角色定位：语义约束的工程执行面

1.1 角色定义

前端与AI工程师是编译产物的第一消费者与工程接入者：前端工程师实现组件、接入校验规则；AI工程师在生成任务中注入语义约束。二者不编写YAML契约，该工作由语义翻译设计师完成；工程师消费编译管线产出的Prompt前缀、JSON Schema与CI规则，让语义约束在代码生成与合入环节自动生效。

• 前端工程师：负责组件实现，按契约接入校验规则，产出符合语义约束的代码。
• AI工程师：负责生成任务接入，在Prompt中注入语义约束，产出符合语义约束的AI输出。

1.2 角色痛点：三个反复发生的场景

以下三个场景在AI参与代码生产的团队中反复出现。它们不是个例，而是框架阶段一经跨产品观察验证过的语义漂移（UI层的 silent failure：无报错、渲染成功、输出错误）模式在工程侧的投影（括号内为模式编号，证据链见第二章）。

痛点1：AI生成界面视觉对了语义错了 验收缺少判定依据

定义："伪正确"在界面侧的表现为AI生成的界面"看起来对、用起来错"。组件合规、色值通过、编译没报错，但QA报回bug：AI把"余额不足"写成红色报警，用户以为账户被盗。代码没"错"，它只是不知道"余额不足"在你们产品里是retryable而非critical。

例子：四种错误状态：流式中断、网络抖动、限流、服务降级。后果完全不同，却共用同一种红色。对照规范挑不出毛病，但用户无法判断"对话已丢失"还是"等三十秒就好"。

根因：走查结论停留在"感觉不对"。缺少一份可引用的语义判定标准，这个知识躺在设计师脑子里，不在任何机器可读的地方。视觉走查回答"是否符合规范"，回答不了"是否表达了正确的语义"。

痛点2：语义零校验 漂移上线后才暴露

定义：生成到上线的链路里，语法有TS检查、逻辑有单元测试、样式有走查，唯独语义没有任何机器校验。规则躺在设计规范文档里，不在任何可执行的拦截点。

例子："删除账户"被AI生成成普通蓝色按钮，无二次确认，一次误触永久丢失。生成时不校验、提交时不拦截、上线后靠用户投诉发现。

根因：语义规则只做到"文档正确"，没做到"机器可执行"。缺少生成前注入、交付前拦截的三层防线，返工成本从"改一行"膨胀为"定位 + 沟通 + 修改 + 复验"的完整循环。

痛点3：规范更新了AI不知道 每次生成都要人工复述

定义："规范漂移"在AI生成侧的表现，团队更新了语义规范，AI的训练语料和提示词上下文仍停留在旧版本。工程师对齐了，AI继续按旧习惯生成。

例子：团队刚把"错误状态分四级"发下去，AI仍然全红输出。工程师不得不在每次生成任务里手工复述"fatal 红脉冲、transient灰、retryable黄、degraded蓝"，重复、易漏、不可追溯。

根因：规范以文档形式存在，未被编译为AI可消费的机器指令。AI没有"查字典"的环节，规范更新到不了生成上下文。

痛点的共同本质：三个场景都不是代码质量问题，而是工程链路里"语义"这一层没有机器可执行的载体，约束停留在文档与口头，生成、校验、合入三个环节全部裸奔。

1.3 解决思路：从痛点到三项资产

三个痛点的解法指向同一结论：工程师需要的不是更多的规范文档，而是三项可直接接入工具链的资产：

• Prompt前缀：生成前注入AI上下文的契约约束文本
• JSON Schema：开发中校验组件Props的机器规则
• CI规则：提交时流水线静态检查，违反即阻断

这三项资产覆盖三个场景：Prompt前缀解决"生成时无约束"，JSON Schema与CI规则补上"校验环节缺失"，"契约变更 → 自动重编译"保证AI消费的永远是最新规范。

为什么现有工具给不了？设计规范文档供人阅读，但人会看漏、看错版本，AI 工具完全读不懂。组件库定义了"按钮有哪些参数"，不定义"这个场景该用哪个参数"。ESLint检查代码风格，不检查"限流提示用了红色"是否合法。人工Review受限于 Reviewer的设计认知，标准因人而异。

概括：现有工具保障"代码写得对"，不保障"代码表达的语义对"。

Schema-As-Code：补齐缺失的语义层

Schema-As-Code（把设计规范写成代码格式）是填补这一空缺的语义治理工程框架。它以三阶段工作流产出上述三项资产：

1. 诊断：用结构化方法把界面语义偏差归类为6个通用模式
2. 契约：把语义定义写成YAML文件（机器可读、可校验），并通过编译管线自动翻译成Prompt前缀、JSON Schema、CI规则等消费格式
3. 验证：各角色在工作流中消费这些资产，验证语义一致性

前端与AI工程师的角色：守好三道关口。生成前注入Prompt前缀（把约束写进AI 的生成上下文），开发中JSON Schema校验（非法Props在编辑器/构建期报错），提交时CI规则拦截（红线阻断、警告放行）。

Schema-As-Code不替代现有工具（组件库、TypeScript、ESLint、单元测试与人工Review），而是作为它们的上游约束层存在：AI仍负责生成，规则负责把关；现有工具回答"代码是否写得对"，语义资产回答"代码表达的语义对不对"。

1.4 责任范围

该角色在框架中的核心动作：

• 消费Prompt前缀（编译管线产出）：生成任务前注入语义分级、红线与文案约束。
• 消费JSON Schema（编译管线产出）：组件Props的级别枚举、必填字段、文案长度校验。
• 消费CI规则（编译管线产出）：PR环节的红线拦截与警告记录。
• 反馈误报与漏报：误报按模式ID归因上报，漏报按6字段快照格式回流模式库。

1.5 不承担责任

YAML契约编写、语义字典维护、编译管线配置，分别由语义翻译设计师与 DesignOps负责，不在本文讨论范围。

二、语义治理的资产链路：三项资产从何而来

本章以工程师的工作场景提出三个问题，语义偏差如何被发现、语义规律如何写成规则、规则如何变成工具链可接入的产物，串联阶段一与阶段二的完整设计。每个环节仅作概述，完整方法详见对应文档。

2.1 语义偏差如何被结构化地发现（阶段一：观察与诊断）

场景：AI生成界面在视觉与语法层面通常挑不出错，但语义表达可能与场景不匹配，多种错误共用同一种红色，高危操作与普通按钮样式相同。这类偏差不作用于像素、不抛出异常，Code Review与视觉走查都无法覆盖，需要一套结构化的观察与诊断方法。阶段一《组件语义快照与模式诊断》建立了这套方法（详见《阶段一：组件语义快照与模式诊断：AI 生成界面的第一道检查》）。

第一步：组件语义快照6字段记录法（语义问题的结构化"现场记录"）。在界面视觉素材之上，强制记录6个标准字段，锚定该界面的语义上下文：

snapshot_id: SNAP-202506-001        # 快照唯一编号，供模式库归档与版本管理
product: 某 AI 对话产品              # 漂移发生的产品，支持跨产品对比
component_type: 错误状态             # 组件类型，决定后续匹配的模式分支
visual_record: 界面素材 + 语义标注框  # 标注语义漂移发生的区域
user_confusion: "看到红色就刷新，结果只是限流"  # 用户困惑，语义断层的直接证据
context: 高峰期快速发送 5 条消息后触发            # 触发场景，支持复现

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

第二步：语义分类与漂移模式匹配。 快照按组件类型归类，与模式库中的既有模式匹配，将分散的界面记录转化为可追踪的模式节点。详见《组件语义分类与漂移模式匹配：从观察到归类的结构化规范》。

第三步：结构化诊断 三层判定模型（三级分类器：组件类型 → 语义缺失 → 视觉校验）。每张快照经三层判定逐层收敛，输出模式ID与置信度：

第一层 组件类型识别 → 第二层 语义缺失判定 → 第三层 视觉表达校验
                          ↓
   输出：matched_pattern（如 ERR-001）+ confidence_score + 归档路径

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

诊断结论：6个漂移模式。 全部观察最终归纳为6个经过跨产品验证的语义漂移模式，构成模式库：

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

从观察到契约。 诊断结果指明"缺什么规则"，经Semantic Pipeline的三阶段工作流（Guard → Contract → Verify）进入规则显化环节。详见《从观察到契约：Semantic Pipeline 的三阶段工作流》。

2.2 语义规律如何转化为机器可读的规则（阶段二：契约与编译）

场景：以文档形式存在的设计规范，读者只有人，人可能看漏、看错版本，AI工具则完全不可见。阶段二的核心是将设计意图翻译为机器可读的语义契约。方法论背景详见《把设计规范写成代码格式，是所有 AI 工具的上游约束方法论》，完整阐述见《阶段二：设计师作为"语义翻译者"：当 AI 生成界面时，我怎么用规则锁住设计意图》。

语义规范体系。 契约的内容不是色值与文案，而是语义令牌（Semantic Tokens，颜色的"类型标注"）：Design Token定义"颜色是什么"，语义令牌定义"颜色代表什么"同一个红色，在系统故障场景为 status.critical，在高危操作场景为 action.destructive。详见《语义规范体系》。

YAML 契约格式。 每条契约由7个字段构成：

intent_id: ERR-001                  # 我是谁：契约唯一标识
description: 错误状态后果差异未分级   # 我解决什么问题
version: 1.1.0                      # 我是哪个版本：变更触发重编译
applicable_products: [...]          # 我在哪些产品生效：防止规则误用
semantic_tokens:                    # 我定义了什么语义：级别 × 视觉 × 行动
  error_severity:
    fatal:
      visual_mapping: {
    color_token: status.critical, motion_token: pulse.red.urgent }
      user_action: [refresh_page, export_history]
immutable_boundaries: [...]         # 我画了什么红线：绝对禁止项
llm_constraints: [...]              # 我对 AI 的强制要求：必须包含、禁止省略

详见《YAML 契约格式》。

契约库。 契约以Git仓库管理：版本可追溯、变更可回滚、修改走PR审批，设计规范像代码一样管理。详见《契约库：让设计规范像代码一样管理》。

2.3 机器可读的规则如何转化为工程可消费的产物（编译管线）

场景：YAML契约面向规则维护者，工程师不应在每次任务前阅读契约原文。编译管线是语义一致性的"机器翻译层"（一份契约 → 四种消费格式的自动翻译器），将同一份契约自动编译为四种消费格式，分发给不同角色：

                     ┌─→ Prompt 前缀    —— 前端与 AI 工程师（本文消费）
 YAML 契约 ──编译管线──┼─→ JSON Schema   —— 组件 Props 校验（本文消费）
                     ├─→ 走查 Checklist —— 设计师与产品经理
                     └─→ CI 规则        —— 流水线自动拦截（本文消费）

面向工程师的资产为其中三项：Prompt前缀（生成前注入）、JSON Schema（开发中校验）、CI 规则（提交时拦截）。详见《编译管线是语义一致性的"机器翻译层"》。

至此三项资产就绪。以下章节阐述前端与AI工程师的消费路径。

三、消费路径：Prompt 前缀、JSON Schema 与 CI 规则的使用场景

三项资产是框架验证闭环Verify阶段面向前端与AI工程师的交付面。本章阐述三项资产的具体消费方式。

3.1 Prompt 前缀（生成前注入）

资产来源：由编译管线根据YAML契约自动编译生成，契约中的 semantic_tokens 编译为分级要求、immutable_boundaries 编译为红线、llm_constraints 编译为文案约束，头部嵌入"基于【契约ID + 版本号】编译"的版本声明。

使用场景：AI生成任务前的约束注入

AI工程师（或任何使用AI生成界面的工程师）在发起生成任务时，将对应组件的前缀完整粘贴到任务描述之前：

# Prompt 前缀（基于 ERR-001 v1.0.0 编译）

## 语义分级（必须遵守）
- fatal（对话/数据可能丢失）：status.critical 红 + 脉冲动画 + 恢复路径（刷新/导出历史）
- transient（短暂故障）：灰色 + 时钟 + 自动重试，禁止红色
- retryable（限流）：黄色 + 倒计时秒数，禁止红色
- degraded（降级）：蓝色 + 说明哪些功能仍可用

## 红线（违反即不合格）
- 禁止把致命错误做成普通文字
- 禁止限流提示使用红色
- 禁止省略恢复路径

## 文案约束
- 致命错误必须说明"对话可能已丢失"
- 禁止仅显示"出错了"或纯技术错误码

效果对照（同一生成任务，注入前后）：

版本同步：契约变更后编译管线自动重编译前缀并换版，工程师只需确认任务中注入的前缀头部版本与契约库最新版一致，规范更新由此到达AI，无需人工复述。

3.2 JSON Schema（开发中校验）

资产来源：同一份契约编译出的组件Props校验规则，可接入编辑器（实时提示）或构建流程（编译期报错）。

使用场景：组件实现的语义校验

前端工程师实现错误状态组件时，Props必须满足契约编译出的Schema：

{
   
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ErrorStateBanner（基于 ERR-001 v1.0.0 编译）",
  "type": "object",
  "required": ["error_severity", "recovery_action", "user_message"],
  "properties": {
   
    "error_severity": {
   
      "enum": ["fatal", "transient", "retryable", "degraded"],
      "description": "语义分级必填，禁止缺省"
    },
    "recovery_action": {
   
      "type": "array",
      "minItems": 1,
      "description": "fatal 级必须提供恢复路径"
    },
    "user_message": {
   
      "type": "string",
      "minLength": 10,
      "description": "禁止仅显示\"出错了\"等模糊文案"
    }
  }
}

写成 <ErrorStateBanner severity="critical" /> 会在编辑器直接报错：critical 不在枚举内（应为 fatal）、缺少 recovery_action——语义错误在写代码的瞬间暴露，而不是等到走查。

3.3 CI 规则（提交时拦截）

资产来源：同一份契约中的 immutable_boundaries 编译为拦截规则，接入 PR 流水线。

使用场景：合入前的红线拦截

# .github/workflows/semantic-guard.yml（基于 ERR-001 v1.0.0 编译）
# error 级：违反 immutable_boundaries，阻断合入
#   - 致命错误使用普通文字样式
#   - 限流提示使用红色
#   - 高危操作缺少二次确认
# warning 级：记录不阻断，供规则迭代
#   - 语义分级字段缺失
#   - 模糊文案（"出错了" / 纯技术错误码）

拦截纪律：

• error级只拦红线：致命错误做成普通文字、限流用红色、高危操作缺二次确认，必须修改，不可协商。
• warning级一律放行：只记录，不阻断PR；避免误报堵死流水线导致规则被绕过。
• 误报处理：按模式ID归因上报（附契约版本与用例），规则随评审迭代；绕过提交会让拦截记录失去意义。

版本同步：每份规则头部嵌入"基于 ERR-001 v1.0.0 编译"声明，契约变更后自动换版，拦截记录可按版本追溯。

三项资产的生成机制，详见《编译管线是语义一致性的"机器翻译层"》。

四、对比：引入语义治理前后的工程链路

以下三个核心工程节点，展示引入 Schema-As-Code 前后的状态差异：

五、协作关系：上游输入、下游输出与反馈回流

5.1 上游输入

该角色从以下角色获取输入：

5.2 下游输出

该角色向以下角色交付输出：

5.3 协作示例

场景：语义翻译设计师发布"账户注销"契约 v1.2.0（补充"注销后30天内可恢复"与"永久删除"的子类语义）。

1. 契约变更：YAML契约 v1.2.0 合入契约库 → Git钩子触发编译管线 → Prompt前缀 / JSON Schema / CI规则自动编译出新版本，头部嵌入"基于 v1.2.0"声明。模式库详见《 6 个漂移模式：AI 生成界面的语义断层证据库》。
2. DesignOps按影响面报告发出变更通知（涉及 3 个产品线、12 处引用）。
3. AI工程师 生成注销流程组件时注入新版前缀 → AI输出自动区分"可恢复注销"（警示色 + 倒计时说明）与"永久删除"（action.destructive + 输入账户名二次确认）。
4. 前端工程师 提交PR → CI按新版规则拦截一处"永久删除未配二次确认"（error 级）→ 修复后合入。
5. 设计师 按新版Checklist验收通过，结论注明"基于 v1.2.0"——全链路可追溯。

该角色的误报与漏报反馈是框架验证闭环Verify阶段闭环的组成部分：反馈经模式库归档、契约更新、重新编译后，以新版前缀与规则的形式回到所有消费方手中。

六、语义治理框架全景：三阶段与机制网络

前端与AI工程师的消费路径位于框架的验证闭环Verify阶段。框架全景分三层呈现。

6.1 三阶段全景

6.2 资产流转

flowchart LR
    subgraph S1["阶段一 Guard · 发现问题"]
        A["组件语义快照<br/>6 字段记录"] --> B["三层判定模型"]
        B --> C["模式库<br/>6 个漂移模式"]
    end
    subgraph S2["阶段二 Contract · 写出规则"]
        D["YAML 契约<br/>契约库 Git 管理"] --> E["编译管线"]
    end
    subgraph S3["阶段三 Verify · 验证闭环"]
        F["语义字典 + 走查 Checklist<br/>→ 设计师与产品经理（角色 1）"]
        G["Prompt 前缀 / JSON Schema / CI 规则<br/>→ 前端与 AI 工程师（本文）"]
    end
    C --> D
    E --> F
    E --> G
    G -->|"误报与漏报按模式 ID 回流"| C

6.3 机制映射：本角色在框架网络中的触点

Schema-As-Code由9个机制主题构成一张相互衔接的网络，一张网不是三条线。本角色触及其中5个节点：

6.4 角色价值

前端与AI工程师在框架中的核心价值，是让语义约束在工具链中自动生效：生成前注入前缀，让AI生成即合规；开发中接入Schema，让非法语义在编辑器暴露；提交时跑CI，让红线在合入前拦截；误报漏报按模式ID回流，让规则持续变准。

该角色是语义一致性的最后一道机器防线，人工走查在前，机器拦截在后；这一环失守，语义漂移就只能靠用户投诉发现。

七、一页纸速查：当前环节该做什么

日常快速查阅：Semantic Pipeline · 语义审查流水线

示例：生成前 → 打开Prompt 前缀 → 查语义分级与红线 → 输出注入约束的生成任务。