YAML 契约格式：领会语义规范体系后怎样编写语义规则

一、YAML 契约的整体结构

一份 YAML 契约由 6 个顶层字段组成。你可以把它理解成一份"设计意图的身份证"——每个字段回答一个特定的问题。

intent_id:"我是谁？"description:"我解决什么问题？"version:"我是哪个版本？"applicable_products: "我在哪些产品里生效？"semantic_tokens: "我定义了什么语义？"immutable_boundaries: "我画了什么红线？"llm_constraints: "我对 AI 有什么强制要求？"

下面逐个拆解。

二、字段 1：intent_id —— 契约的身份证号

设计意图

每个契约都需要一个唯一标识，就像设计稿的编号一样。当你和前端、AI 工程师沟通时，说"ERR-001"比说"那个错误状态分级的东西"要精确得多。

命名规范

intent_id: "ERR-001"# 格式：[领域缩写]-[三位序号]# ERR = Error（错误状态）# PRO = Process（过程状态）# BND = Boundary（边界动作）# ACT = Action（操作按钮）# ALR = Alert（告警状态）

常见错误

❌ 用自然语言命名：intent_id: "错误状态分级"——不方便引用和版本管理

✅ 用结构化编号：intent_id: "ERR-001"——精确、可排序、可检索

三、字段 2：description —— 一句话说清契约解决什么问题

设计意图

description 是给人类看的摘要。当你打开一份契约文件，第一眼就要知道"这份契约是干嘛的"。

写法

description: "错误状态后果差异未分级：系统无法区分致命错误、网络抖动、限流提示和降级错误，导致用户无法判断后果严重程度。"

好 description 的标准

• 包含问题现象（用户看到什么）
• 包含根因（系统缺了什么）
• 包含后果（用户因此遇到什么困扰）

❌ 不好的写法：description: "错误状态规范"——太笼统，不知道解决什么问题

✅ 好的写法：见上方示例——现象 + 根因 + 后果，一目了然

四、字段 3：version —— 语义版本号

设计意图

设计规范会迭代，YAML 契约也会迭代。version 字段让你知道"这份契约是第几版"，和代码的版本管理一样重要。

语义化版本规范

version: "1.0.0"# 格式：主版本.次版本.修订号# 主版本：破坏性变更（如删除某个 severity 级别）# 次版本：功能新增（如增加新的 visual_mapping）# 修订号：bug 修复（如文案微调）

版本变更示例

# v1.0.0：初始版本，包含 fatal/transient/retryable 三级# v1.1.0：新增 degraded 级别（次版本升级）# v1.1.1：修正 fatal 的文案描述（修订号升级）# v2.0.0：删除 retryable 级别，合并到 transient（主版本升级，破坏性变更）

五、字段 4：applicable_products —— 契约在哪些产品里生效

设计意图

不同产品可能有不同的设计规范。applicable_products 定义了这份契约的生效范围，避免"一刀切"。

写法

applicable_products:- "ChatGPT"- "文心一言"- "通义千问"- "Kimi"- "豆包"- "DeepSeek"# 不生效的产品：Claude（因为 Claude 的错误状态设计不同）

作用域控制

# 全局生效（所有产品）applicable_products:- "*"# 特定产品生效applicable_products:- "ChatGPT"- "Kimi"# 排除特定产品applicable_products:- "*"excluded_products:- "Claude"# Claude 有自己的错误状态规范

六、字段 5：semantic_tokens —— 契约的核心：语义令牌定义

设计意图

这是 YAML 契约最重要的字段。semantic_tokens 定义了"这个场景下有哪些语义级别，每个级别映射到什么视觉、文案和行动"。

结构拆解

semantic_tokens:[语义令牌组名]: # 如 error_severity、process_phase[级别名]: # 如 fatal、transient、retryabledescription: "..."# 这个级别的含义visual_mapping: {...} # 视觉映射（颜色、动效、图标）user_action: [...] # 用户行动（按钮、操作）llm_constraints: [...] # 针对这个级别的 LLM 强制约束

ERR-001 完整示例

semantic_tokens:error_severity:# 语义令牌组：错误严重程度fatal: # 级别 1：致命错误description: "系统级故障，对话上下文可能丢失"visual_mapping:# 视觉映射color_token: "status.critical"# 颜色令牌：致命状态motion_token: "pulse.red.urgent"# 动效令牌：红色脉冲icon_token: "alert.octagon" # 图标令牌：八边形警告background: "red.500/10" # 背景：10% 透明度红色user_action: # 用户行动- label: "刷新页面"# 主行动：刷新action: "refresh"priority: 1# 优先级：1（最高）- label: "导出历史"# 次行动：导出action: "export_history"priority: 2llm_constraints: # LLM 强制约束- "必须明确告知用户对话上下文可能已丢失"- "禁止仅显示'出错了'等模糊文案"- "必须提供恢复路径（刷新或导出）"transient: # 级别 2：网络抖动description: "网络层故障，系统可自动恢复"visual_mapping:color_token: "status.neutral" # 颜色令牌：中性状态motion_token: "spinner" # 动效令牌：加载动画icon_token: "loader"# 图标令牌：加载图标background: "neutral.800"# 背景：深灰色user_action:- label: "等待自动恢复"# 主行动：等待action: "wait"priority: 1- label: "手动重试"# 次行动：重试action: "retry"priority: 2llm_constraints:- "必须显示自动重试进度"- "禁止使用红色背景（避免情绪过载）"- "必须说明预计恢复时间"retryable: # 级别 3：限流/流控description: "请求频率已达上限，用户可自助恢复"visual_mapping:color_token: "status.warning" # 颜色令牌：警告状态motion_token: "none"# 动效：无（不需要紧急感）icon_token: "clock" # 图标令牌：时钟background: "amber.500/10" # 背景：10% 透明度黄色user_action:- label: "等待倒计时"# 主行动：等待action: "wait_countdown"countdown_field: "retry_after"# 倒计时字段名priority: 1- label: "升级套餐"# 次行动：升级action: "upgrade"priority: 2llm_constraints:- "必须显示剩余等待时间（秒/分钟）"- "必须提供升级/扩容路径"- "禁止使用红色（避免用户恐慌）"degraded:# 级别 4：部分可用description: "部分功能可用，可继续生成"visual_mapping:color_token: "status.info"# 颜色令牌：信息状态motion_token: "none"# 动效：无icon_token: "info.circle" # 图标令牌：信息圆圈background: "blue.500/10"# 背景：10% 透明度蓝色user_action:- label: "继续生成"# 主行动：继续action: "continue"priority: 1- label: "简化问题重试"# 次行动：简化重试action: "retry_simplified"priority: 2llm_constraints:- "必须说明哪些功能仍然可用"- "必须提供替代方案（如简化问题）"- "禁止显示纯技术错误码（如 500 Internal Error）"

关键设计原则

七、字段 6：immutable_boundaries —— 不可突破的红线

设计意图

有些规则是"绝对不能违反"的，比如高危操作必须二次确认。immutable_boundaries 定义了这些红线，一旦违反，系统直接阻断。

结构

immutable_boundaries:- boundary_type: "safety" # 边界类型：安全constraint_rule_ref: "rules/destructive-action.yaml"# 引用的规则文件violation_action: "block"# 违反时的动作：阻断- boundary_type: "compliance"# 边界类型：合规constraint_rule_ref: "rules/data-retention.yaml"violation_action: "escalate" # 违反时的动作：升级人工审核

ERR-001 示例

immutable_boundaries:- boundary_type: "safety"rule: "禁止直接执行删除操作而不显示二次确认"violation_action: "block"# 如果 AI 生成的代码里没有二次确认，直接阻断，不允许进入生产环境- boundary_type: "semantic"rule: "禁止将 fatal 错误显示为静态灰色（必须用红色脉冲）"violation_action: "block"# 如果 fatal 错误用了灰色静态背景，直接阻断

与 semantic_tokens 的区别

八、字段 7：llm_constraints —— 对 AI 的强制要求

设计意图

LLM 在生成内容时可能会"自由发挥"，比如把 Critical 写成"严重"，或者漏掉二次确认。llm_constraints 是给 AI 的"强制指令"——不是建议，是必须遵守。

写法

llm_constraints:- "必须明确告知用户对话上下文可能已丢失"# 信息完整性约束- "禁止仅显示'出错了'等模糊文案"# 文案精度约束- "必须提供恢复路径（刷新或导出）"# 行动完整性约束- "禁止将 fatal 错误显示为静态灰色" # 视觉映射约束- "禁止在 retryable 场景使用红色背景" # 场景匹配约束

约束的三种类型

九、完整契约示例：ERR-001（从头到尾）

# 契约文件：intent/err-001.yaml# 作者：设计师 [姓名]# 创建日期：2026-06-30# 最后更新：2026-06-30# 变更记录：v1.0.0 初始版本，包含 fatal/transient/retryable/degraded 四级intent_id: "ERR-001"description: "错误状态后果差异未分级：系统无法区分致命错误、网络抖动、限流提示和降级错误，导致用户无法判断后果严重程度。"version: "1.0.0"applicable_products:- "ChatGPT"- "文心一言"- "通义千问"- "Kimi"- "豆包"- "DeepSeek"semantic_tokens:error_severity:fatal:description: "系统级故障，对话上下文可能丢失"visual_mapping:color_token: "status.critical"motion_token: "pulse.red.urgent"icon_token: "alert.octagon"background: "red.500/10"user_action:- label: "刷新页面"action: "refresh"priority: 1- label: "导出历史"action: "export_history"priority: 2llm_constraints:- "必须明确告知用户对话上下文可能已丢失"- "禁止仅显示'出错了'等模糊文案"- "必须提供恢复路径"transient:description: "网络抖动，系统可自动恢复"visual_mapping:color_token: "status.neutral"motion_token: "spinner"icon_token: "loader"background: "neutral.800"user_action:- label: "等待自动恢复"action: "wait"priority: 1- label: "手动重试"action: "retry"priority: 2llm_constraints:- "必须显示自动重试进度"- "禁止使用红色背景"- "必须说明预计恢复时间"retryable:description: "请求频率已达上限"visual_mapping:color_token: "status.warning"motion_token: "none"icon_token: "clock"background: "amber.500/10"user_action:- label: "等待倒计时"action: "wait_countdown"countdown_field: "retry_after"priority: 1- label: "升级套餐"action: "upgrade"priority: 2llm_constraints:- "必须显示剩余等待时间"- "必须提供升级路径"- "禁止使用红色"degraded:description: "部分功能可用"visual_mapping:color_token: "status.info"motion_token: "none"icon_token: "info.circle"background: "blue.500/10"user_action:- label: "继续生成"action: "continue"priority: 1- label: "简化问题重试"action: "retry_simplified"priority: 2llm_constraints:- "必须说明哪些功能仍然可用"- "必须提供替代方案"- "禁止显示纯技术错误码"immutable_boundaries:- boundary_type: "safety"rule: "禁止直接执行删除操作而不显示二次确认"violation_action: "block"- boundary_type: "semantic"rule: "禁止将 fatal 错误显示为静态灰色"violation_action: "block"

十、写作检查清单：写完一份契约后对照

- [ ] intent_id 是否符合命名规范（领域缩写-三位序号）？- [ ] description 是否包含现象 + 根因 + 后果？- [ ] version 是否使用语义化版本（主.次.修）？- [ ] applicable_products 是否明确了生效范围？- [ ] semantic_tokens 是否每个级别都有 visual_mapping + user_action + llm_constraints？- [ ] visual_mapping 是否使用了语义令牌（color_token）而非写死色值（color: #EF4444）？- [ ] user_action 是否与后果严重程度匹配（fatal→刷新/导出，transient→等待/重试）？- [ ] llm_constraints 是否每条都可被机器校验（有明确的"必须/禁止/只能"）？- [ ] immutable_boundaries 是否定义了不可突破的红线？- [ ] 是否包含变更记录和作者信息？

十一、常见错误与修正

错误 1：写死色值，不用语义令牌

❌ 错误写法：

visual_mapping:color: "#EF4444"# 写死色值，设计系统更新时契约失效

✅ 正确写法：

visual_mapping:color_token: "status.critical"# 语义令牌，设计系统更新时映射关系自动同步

错误 2：用户行动与后果不匹配

❌ 错误写法：

# fatal 错误（对话已丢）只给"重试"按钮user_action:- label: "重试"action: "retry"

✅ 正确写法：

# fatal 错误需要"刷新"或"导出"，因为对话已丢，重试无效user_action:- label: "刷新页面"action: "refresh"- label: "导出历史"action: "export_history"

错误 3：LLM 约束不可执行

❌ 错误写法：

llm_constraints:- "文案要友好一点"# 无法机器校验，什么叫"友好"？

✅ 正确写法：

llm_constraints:- "禁止仅显示'出错了'等模糊文案"# 可机器校验：检查文案是否包含"出错了"- "必须包含后果说明"# 可机器校验：检查文案是否包含"可能已丢失"等后果词

十二、下一步：写完后怎么编译

写完 YAML 契约后，下一步是编译为消费格式。详见下一章《从契约到消费格式：编译》。

一份 ERR-001.yaml 会编译为：

• Prompt 前缀：供 Claude Code / Cursor 使用
• JSON Schema：供结构校验使用
• Checklist：供设计师人工走查使用
• CI 规则：供自动化流水线使用