S
Schema-As-Code
Semantic Pipeline Contract Library Validation Toolkit
API GitHub
Schema-As-Code 工程实现 · 三阶段流水线

Schema-As-Code

Schema-As-Code 是一条三阶段流水线：发现问题（Guard）→ 写契约（Contract）→ 证明有效（Verify）。
不是三个工具，是一个工作流。让 AI 生成的内容在到达视觉层和工程层之前，先过一遍语义审查。

🔍
ALL
Error
Process
Boundary
Action
Alert
ACT-001
Destructive
高危操作风险未约束
AI 把不可逆操作做成普通按钮，没有二次确认
危险操作：红色空心 + 二次确认
产品实例
通用
ERR-001
Error
错误状态后果差异未分级
多种错误共用红色，用户无法判断后果严重程度
⚠️ 消息流中断
⏳ 网络连接不稳定
⏱️ 请求频率已达上限
产品实例
ChatGPT
文心一言
通义千问
ALR-001
Synonym
告警文案语义降级
AI 把 Critical 写成严重，情绪权重降低
严重 → Critical
同义词拦截：禁止情绪权重降级
产品实例
通用
PRO-001
Process
过程状态认知阶段未显化
Searching/Reading 模糊，用户不知道 AI 在干什么
正在检索信息 65%
Searching → Reading → Wrapping up
产品实例
Perplexity
BND-001
Boundary
边界动作权利差异未区分
拒绝和终止混为一谈，用户不知道权利还在不在
Claude has ended this chat
会话已终止，上下文已清空
产品实例
Claude
ACT-001
Destructive
高危操作确认强度不足
不可逆操作，必须输入账户名确认
删除账户
此操作不可恢复。请输入账户名确认。
产品实例
通用
/ ERR-001
E
ERR-001 Error

错误状态后果差异未分级

多种错误共用红色，用户无法判断后果严重程度

语义断层地图

/ ERR-001
E
ERR-001 Error

错误状态后果差异未分级

多种错误共用红色，用户无法判断后果严重程度

语义断层地图

The Pipeline
一条语义偏差怎么走完全程
How one semantic drift flows through three stages
01
🔍
发现问题
Semantic Guard · 扫描
输入组件描述或语义快照，自动匹配已知模式。发现"意思跑偏"的真实证据：截图、用户抱怨、组件对比。
→ 匹配到 ERR-001 / ACT-001 / PRO-001
➡️
02
📝
解决问题
Contract Library · 写契约
从模式库复制 YAML 契约，定义"这个场景下不能做什么"。机器可读、Git 管理、Diff 可见、版本可追溯。
→ 生成 YAML + Prompt 前缀 + Checklist
➡️
03
✅
证明有效
Validation Toolkit · 跑验证
跑单元/集成/回归三级测试，对比"有契约"和"无契约"的生成结果。算返工率、算用户投诉量。
→ 返工率 30% → 5%
Impact
组织经济学价值
不是"理念先进"，是"今天能省多少返工时间"
5%
语义返工率
↓ 从 30%
0.5天
规范同步时间
↓ 从 2 人周
100%
走查覆盖率
↑ 从 20%
5
已验证模式
持续扩展中
/ API
API
搜索接口规范
供 Figma 插件 / Cursor 扩展 / CI 脚本调用
GET /api/v1/guard/search

输入自然语言描述，返回匹配的模式列表及置信度。

Request
GET /api/v1/guard/search?q=系统报错红色提示&limit=3 Query Parameters: q string required 自然语言描述或组件语义快照 JSON limit number optional 返回结果数量，默认 5 threshold number optional 置信度阈值，默认 0.7
Response
{ "matches": [ { "id": "ERR-001", "name": "错误状态后果差异未分级", "confidence": 0.95, "component_type": "Error", "symptom": "多种错误共用红色", "root_cause": "缺少 error_severity 语义令牌", "contract_url": "https://.../contract/ERR-001.yaml", "evidence": [ { "product": "ChatGPT", "screenshot": "..." }, { "product": "文心一言", "screenshot": "..." } ] } ], "total": 1, "query": "系统报错红色提示" }
POST /api/v1/guard/snapshot

输入组件语义快照 JSON，返回结构化诊断结果。

Request
POST /api/v1/guard/snapshot Content-Type: application/json { "component_type": "Alert", "visual": { "color": "red", "background": "solid" }, "copy": { "title": "Error", "description": "Something went wrong" }, "context": "system_error" }
Response
{ "match": { "id": "ERR-001", "confidence": 0.92 }, "diagnosis": { "severity": "high", "issue": "多种错误共用红色，未区分后果严重程度", "suggested_action": "补充 error_severity 语义令牌，定义 fatal/transient/retryable/degraded 四级" } }
/ Contract Library

Contract Library

浏览所有语义契约，一键复制 YAML / Prompt 前缀 / Checklist

/ Validation Toolkit

Validation Toolkit

三层验证工具：语义分级器 · JSON 输入 · 快照模板

输入任意错误文案，自动诊断语义分级并给出约束建议

快速测试：

语义术语表

界面语义 + 全链路语义治理的核心词汇集

🔍

界面语义术语（13 项）

颜色/文案背后的意思
（Semantic Token）
组件在特定场景下必须表达的语义含义，超越视觉样式。与 Design Token 的区别：Design Token 管"长什么样"，Semantic Token 管"意味着什么"。
归属：契约库 · 使用：定义 color_token + semantic_domain 映射
设计意图的约定书
（Intent Contract）
把设计师对某个场景下"应该表达什么"的意图，写成机器可读的 YAML 规则文件。是设计师与 AI 之间的正式契约。
归属：契约库 · 使用：每份 YAML 文件即为一个 Intent Contract
绝对不能碰的红线
（Immutable Boundary）
在特定场景下 AI 绝对不能突破的语义边界。一旦触发，直接阻断生成，不进入下游。
归属：契约库 · 使用：immutable_boundaries 字段下的每条规则
同义词拦截器
（Synonym Firewall）
在特定场景下禁止 AI 使用某些同义词替换标准语义令牌的机制。如禁止用"严重"替代"Critical"。
归属：契约库 · 使用：synonym_firewall 字段下的 prohibited 列表
意思跑偏了
（Semantic Drift）
AI 生成内容时，语义含义偏离设计意图的现象。不是 Bug，是概率性生成的内禀属性。
归属：模式库 · 使用：记录的所有"漂移表现"均属 Semantic Drift
按规矩设计
（Constraint-Based Design）
不告诉 AI "怎么做"，而是声明"不能做什么"。AI 在规则边界内自由发挥。
归属：契约库 · 使用：整体设计方法论
把设计想法写成机器能懂的格式
（Design Intent Formalization）
将设计师大脑中的直觉（"这个场景下不能这样做"）翻译成机器可读的语义契约（YAML）。
归属：模式库 → 契约库 · 使用：根因字段推导后生成 YAML
能直接跑的设计规范
（Executable Design Spec）
规范不再是 PDF/语雀文档，而是 Git 仓库里的 YAML 文件。Diff 可见、版本可追溯、可编译为下游约束。
归属：契约库 · 使用：DesignOps 将规范从文档迁移到代码格式
四层检查引擎
（Four-Layer Inference Engine）
验证工具集的核心算法，分四级检查：语法推演（结构）→ 语义推演（令牌引用）→ 安全推演（禁止模式）→ 美感推演（信息密度）。
归属：验证工具集 · 使用：每条验证规则的执行逻辑
文本格式的规则文件
（YAML）
一种人类可读、机器可解析的文本格式，用于编写语义契约。比 JSON 更适合写规则，比 Markdown 更适合机器消费。
归属：契约库 · 使用：所有契约文件的格式标准
放在 AI 指令前面的规则
（Prompt Prefix）
从契约库中提取的、贴在 AI 编程助手（Claude Code / Cursor）指令前面的约束文本。让 AI 生成时自动遵守规矩。
归属：契约库 · 使用：前端使用契约库时的消费方式
把设计规范写成代码格式
（Schema-As-Code）
将设计规范从文档形态转化为代码形态（YAML），使其具备版本管理、Diff 对比、自动编译、CI 校验等代码级能力。
归属：全部 · 使用：整套方法论的总称
约束即代码
（Constraint as Code）
将"不能做什么"的约束写成代码格式的规则文件，机器可直接执行，无需人工解释。
归属：契约库 · 使用：契约库的核心原则

全链路语义术语

语义漂移
（Semantic Drift）
发生在所有层级。界面层是漂移的"显影剂"——后端漂移再隐蔽，最终通过组件暴露。
全链路通用
语义治理
（Semantic Governance）
对语义定义、语义流转、语义呈现的全链路管理。覆盖数据层 → 业务层 → 策略层 → 知识层 → 界面层。
全链路通用
语义审计
（Semantic Audit）
定期检查"词、标签、信号是否还代表决策者认为的意思"。阿里云提出的"约束基建"核心能力。
全链路通用 · 界面层实现：验证工具集
活的定义
（Living Definition）
有明确 owner、有 review 周期、有版本管理的语义定义。契约库中的 YAML 文件即"活的定义"。
全链路通用
语义拦截
（Semantic Interception）
在内容呈现给用户之前，拦截语义漂移。界面层的核心能力。四层检查引擎即拦截机制。
界面层核心能力
语义反哺
（Semantic Feedback）
界面层发现异常时，向上游层级反馈，驱动后端治理。界面层不是孤立存在，是"下游显影 + 上游告警"的双向节点。
界面层 → 后端层

洞察

界面层语义治理的研究与观察

模式专题
当 AI 生成界面时，设计意图在偏离
我们观察了 8 类 AI 产品，发现它们共享同一套组件语义偏差模式。错误状态后果差异未分级、过程状态认知阶段未显化、边界动作权利差异未区分——这些不是某个产品的 Bug，是概率性生成的内禀属性。
技术背书
阿里云约束基建与 Schema-As-Code 的互补
阿里云在《构建可审计、可进化的 AI Agent 底座》中提出"约束基建"是 AI 可信底座。这与 Schema-As-Code 的核心理念一致：可审计、可进化、约束基建。区别与互补：阿里云做后端 Agent 的约束基建，Schema-As-Code 做前端界面的约束基建。
组织经济
语义不一致的隐性成本
前端 30% 返工时间修语义错误、规范同步 2 人周、用户投诉"看不懂报错"无法归因。约束基建把"设计意图"从人脑中的直觉，变成团队可复用的规则资产。一次定义，全域生效。

资源

模式专题、YAML 模板、Prompt 前缀、验证工具下载

ERR-001 模式专题
错误状态语义设计完整专题：组件手册依据、语义属性矩阵、漂移模式清单、跨产品证据、契约规则、验证用例。
ACT-001 模式专题
高危操作语义设计完整专题：Button + Modal 组件语义约束、destructive_action 定义、Prompt 前缀模板。
YAML 契约模板包
5 个模式的完整 YAML 契约文件：ERR-001 / PRO-001 / BND-001 / ACT-001 / ALR-001。
Prompt 前缀模板包
给 Claude Code / Cursor 使用的 Prompt 前缀模板，覆盖 5 个组件类型的语义约束。
验证工具集
单元测试 / 集成测试 / 回归测试用例清单，以及通过率数据模板。
语义术语表
界面语义 + 全链路语义术语的完整对照表，团队内部对齐和对外沟通使用。
Overview Pipeline Impact API 术语表 洞察 工具 订阅 资源 GitHub
Semantic Pipeline · Schema-As-Code 工程实现 · 不是替代任何工具，是所有 AI 工具的上游约束
ACT-001 高危操作风险未约束

语义断层地图

设计意图

高危操作，不可逆，必须二次确认

设计稿表现

红色空心"删除账户" + 二次确认弹窗

工程实现（断裂）

蓝色实心"确认"按钮

❌ 缺少二次确认

模式诊断

组件类型：Button + Modal
根因：缺少 destructive_action 语义约束
产品实例：通用（所有 AI 生成高危操作的场景）
semantic_domain: destructive
visual_mapping:
  Button: { type: "primary", danger: true, ghost: true }
  Modal: { type: "confirm", okType: "danger" }
llm_constraints:
  - "禁止蓝色实心按钮"
  - "必须包含二次确认弹窗"
  - "文案必须说明'此操作不可恢复'"

6

单元测试用例

2

集成测试用例

3

回归测试案例

通过准则

  • • 单元测试：100% 通过
  • • 集成测试：100% 通过
  • • 回归测试：100% 通过