YAML契約模板：用7個欄位把「絕對不能」變成機器可執行的規則

简介： 7个字段把"绝对不能"变成机器执行的规则：意图编号、版本、描述、语义域、适用产品、语义令牌、机器约束与不可变边界。写法是查字典填表格，值必须引用语义字典已注册项，自创被入库安检拦下。每条边界带违反动作，分阻断与警告两级，编译后变成指令前缀、类型规则、走查清单与拦截规则四种形态。

开篇 30 秒

设计规范的问题在于人传人：语雀文档、代码注释、Prompt里的规矩，对机器都是死的。《YAML契约》有位读者把这个判断说得很准，"真正难的不是格式，而是让团队接受查字典填表格"。

这个模板正面接住这个难题：用7个字段，把一条语义规则写成机器可校验、可编译、可追踪的契约。它不是文档，是接口，编译之后，它会变成AI生成工具的Prompt前缀、前端的JSON Schema、设计师的走查Checklist、流水线的CI规则。

规则不再靠谁的记性，也不再靠谁今天有没有看群。

一、模板本体

intent_id: ""            # 契约唯一标识
description: ""          # 这条契约在管什么
version: ""              # 语义化版本号
semantic_domain: ""      # 所属语义域
applicable_products: []  # 适用的产品/范围
semantic_tokens: {}      # 引用的语义令牌（只能引用字典已注册项）
immutable_boundaries: [] # 不可突破的边界（负向约束）

7个字段全部冻结：字段名、含义、顺序不要动。机器靠它们做格式校验和编译。

二、逐字段：起草要点 + 评审要点

这份模板有双重用途：起草时它是规范，评审时它是尺子，同一把尺子，量自己也量别人。

三个字段各带一层展开：

version，版本信任是校验规则的地基：当前版本由 Git 作为权威时钟、审批链作为人工共识来定义，不靠管理员手动点发布（版本信任机制的三假设论证，见《契约的机器防线》）。

semantic_tokens，注册纪律分两种状态（draft机制来自《语义字典》：

"字典里查不到就先随手写一个"，是这个体系最危险的苗头。

semantic_tokens:
  error_severity: fatal        # status: registered，组织级共识
  error_severity_warning_draft: # status: draft，某产品试点
    status: draft
    product: "某创新产品"
    review_date: "2026-09-01"  # 到期必须转正或清退

immutable_boundaries，机器是"合规即正确"，人是"意图即正确"：笼统要求"必须有确认"，机器会字面满足、语义偏离。《把 1 条"绝对不能"翻译成机器规则》里"按钮文案不能为『确认』"那个细节，堵的就是这个缝。

三、完整示例：ERR-001 错误分级契约

对应漂移模式 ERR-001（后果差异未分级）：LLM生成告警/错误文案时，Critical被同义词降级为"严重"（漂移现场见《字段层差异》）。

intent_id: contract.err001.error_severity
description: 错误状态必须按用户后果分级表达，禁止同义词降级
version: 1.0.0
semantic_domain: feedback.error_state
applicable_products: [ai_assistant, web_console]

semantic_tokens:
  error_severity:
    fatal:                # 已注册：用户数据/进度损失，必须立即处理
      description: 不可恢复，用户必须立即处理
      visual_mapping: { color_token: "color.feedback.fatal", motion_token: "motion.none", icon_token: "icon.error.blocking" }
      user_action: 提供损失补救路径（如导出已编辑内容）
    transient:            # 已注册：稍候自动恢复，无需用户操作
      description: 暂时性故障，稍后自动恢复
      visual_mapping: { color_token: "color.feedback.transient", motion_token: "motion.pulse", icon_token: "icon.error.passive" }
      user_action: 告知等待时长，禁止弹窗阻断
    retryable:            # 已注册：操作失败，用户重试可成功
      description: 操作未完成，用户重试即可
      visual_mapping: { color_token: "color.feedback.retryable", motion_token: "motion.none", icon_token: "icon.error.action" }
      user_action: 提供一键重试
    degraded:             # 已注册：功能降格可用，核心路径不断
      description: 部分功能暂不可用，其余正常
      visual_mapping: { color_token: "color.feedback.degraded", motion_token: "motion.none", icon_token: "icon.error.degraded" }
      user_action: 说明受影响范围

immutable_boundaries:
  - 禁止将 fatal 级状态以"出了点小问题""稍后再试"等中性/降级文案表达
  - 禁止跨层绑定：fatal 不得使用成功态或提示态的颜色、图标、动效
  - 禁止缺少 user_action 的错误状态（机器无法回答"用户该做什么"即违规）
  - 禁止在同一份界面中混用两个 severity 令牌的视觉映射

评审这条契约时，三个硬要求对应核查：格式（7字段完整）、语义（四个令牌均 registered，无自创）、证据（关联模式卡片ERR-001后果差异未分级及其快照证据链）。

四、框架设计背景：

YAML契约不是一份格式更好的规范文档，而是 把设计规范写成代码格式（Schema-As-Code） 框架里"设计意图的接口定义" 。要理解为什么必须是7个字段、为什么评审要恒定执行同一把尺子，需要先看到它在整条流水线中的位置。

4.1 三阶段全景

****把设计规范写成代码格式（Schema-As-Code） 不是一套理论，是一条可执行的三阶段流水线（Semantic Pipeline）：

4.2 契约横跨三个阶段

• Guard 阶段：契约从诊断来。设计师提交的6字段快照，经三层判定归档为模式卡片，模式卡片就是契约的出生证明，没有模式背书的契约是想象需求。
• Contract 阶段：契约是唯一的"源"。四种编译产物全部由它派生、禁止手改；契约升级即触发重编译，下游四处同步换版。手改契约是唯一的规则变更入口。
• Verify 阶段：契约是被验证的对象。消费追踪挂在契约版本上（谁在消费、沉默了没有），对抗用例的断言与契约条款同源生成，验证的所有读数，最终都回答"这份契约写得对不对"。

4.3 回到开篇的问题

为什么文档约束不了AI？ 因为自然语言规范对机器不可执行：AI生成工具不读语雀文档，CI不拦文档条款，版本改了无人对账。约束只有落地为代码形态、进入生成链路，才真正存在（从"文档约束"到"工程资产"的完整论证，见《约束显化》）。

为什么是7个字段？ 它们是"一条规则能被机器执行"的最小完备集，标识、意图、版本、域、范围、语义定义、边界，少一个，编译产物就有一类无法生成；多一个，就属于执行细节而非接口定义。

为什么评审这么严格？ 因为契约是编译的源：源头宽一寸，四种产物就歪一丈。退回不是拒绝，是翻译能力的第一道把关。

五、操作流程：一条契约从原料到规则生效

先看人机分工的总图。这条流程不是"你多了一套表格要填"，而是"机器自动跑编译和分发，你只在语义判断点上出手" ：

┌───────────────────────────────────────────────────────┐
│  机器自动跑                                            │
│  ├─ 编译前置校验：字段完整性、引用合法性，不过即拦截    │
│  ├─ 自动编译：1 份契约 → 4 种消费格式                  │
│  ├─ 自动分发与对账：产物送达消费方，版本过期告警        │
│  ├─ 消费追踪：加载次数、拦截次数持续采集                │
│  └─ 沉默标记：30 天零消费自动标记沉默规则               │
├───────────────────────────────────────────────────────┤
│  人做决策（你在这里）                                   │
│  ├─ 验收：上游快照按三条硬要求放行或退回                │
│  ├─ 起草：把模式卡片翻译成 7 字段契约                   │
│  ├─ 评审：语义保真判断——机器不能判断"对不对"            │
│  ├─ 抽样：四种产物语义一致性的人工确认                  │
│  └─ 归因：沉默规则是"没分发到"还是"规则本身有问题"      │
└───────────────────────────────────────────────────────┘

Step 1：验收，上游快照过三条硬要求

不满足就退回，退回时说明缺什么。这个动作本身就在训练组织内的翻译能力。

Step 2：起草，把模式卡片翻译成7字段

先查字典，再写契约：所有 semantic_tokens 必须引用字典已注册项（《语义令牌表》）；需要的令牌还没注册，先走draft通道注册，再回来起草。

无工具时：用文本编辑器手写YAML，人工对照自检清单校验。

Step 3：提交，机器自动跑前置校验

编译前置校验5项机器安检（机制见《编译前置校验》）：全部通过 → 自动入库；任何一项失败 → 阻断并返回具体错误项，你回到对应字段修正。正常流程不需要人盯，人只在异常时介入。

Step 4：评审，语义保真的人工确认

机器能管结构、语法和交叉比对，但这条规则"对不对"，要人签字：它是否真实对应模式卡片里的漂移证据？边界条款是否可判定？诊断结论的签字权在人，不在机器。

Step 5：编译分发，机器自动跑，产物到四方

一句取舍请守住：标准恒定，消费侧不适靠修订规则细节吸收，不靠放松标准。

Step 6：抽样与追踪，确认翻译没有失真

编译之后有一个动作不能省：从已确认的契约里抽一个语义点，到四种格式里各找一处表达，核对严格程度是否一致（方法见《对1个语义点做四格式抽样》）。最隐蔽的分叉是措辞弱化，Checklist把"禁止"写成了"建议"。看到分叉就写成反馈，否则下次编译原样产出。

追踪侧： 消费点接入强制登记、加载自动上报，注册表的第一死因是变成死文件（双重闭环的设计见《契约消费追踪双重闭环验证》）。沉默规则由机器标记，归因由人做：是没分发到，还是规则本身有问题。

关键认知：翻译能力属于工作流节点，不属于岗位。组织初期，验收、起草、评审、抽样可能都是你一个人完成的，同一个人走完所有节点，但节点之间的输入输出契约一个不少。这不是效率问题，是标准问题（完整论述见《编译工作流中的上下游要求》）。

六、你在体系里的位置：翻译能力的承担节点

你是评审者，也是生产者：上游的快照由你验收，契约由你起草或评审，编译产物由你抽样确认。组织里唯一同时看见上游输入和下游消费的人，就是你。

这个位置不属于某个编制，它由三类动作定义：

你的上游：设计师、产品经理、任何发现问题的人，他们交6字段快照，你按三条硬要求验收。

你的下游：AI工程师、前端工程师、设计师/DesignOps、前端团队，他们消费四种编译产物，反馈回流到你这里。

你的核心动作只有四个：验收 → 起草/评审 → 抽样 → 归因。

七、交付标准与自检

评审通过不等于规则生效。一条规则的完整生命周期是：被发现 → 被翻译 → 被评审 → 被编译 → 被消费 → 被证明一直在工作。 你负责的是中间三段，但验收标准是最后一段。

提交评审前自检清单（7条，全勾再走）：

• 7 个字段完整，字段名与冻结模板一致
• intent_id 全局唯一且可读
• semantic_tokens 全部来自字典已注册项（draft 项带 status/review_date）
• immutable_boundaries 每条都可机器判定，无"尽量/建议"类措辞
• 关联至少 1 个真实产品实例或模式卡片证据链
• 版本号遵守版本纪律
• 一个契约只管一个语义域

评审他人提交的契约时，同一张清单，标准的及格线由你恒定执行，不因起草人是谁而改变。

八、最小可行：一个人的翻译闭环

翻译能力的生长只改"谁在节点上"，不改"节点的及格线"。

九、常见误会

"7个字段会不会表达不了复杂规则？"

表达不了的时候，先怀疑是契约粒度错了：一个契约只管一个语义域、一条漂移模式。拆成多条，而不是塞满一条。粒度错的契约比字段少更危险。

"字典里还没有我要引用的令牌，先写进去行不行？"

不行，这是三条硬要求里的语义硬要求。正确姿势：先把令牌注册进字典（试点用 draft 状态 + review_date），再来起草契约。字典永远可以晚于场景半步，但引用纪律不能破。

"边界写严了，下游抱怨阻断太多怎么办？"

先核对两件事：拦截分级用对了吗（该 WARN 的别 BLOCK）？约束可执行吗？都确认之后，记住那句取舍，标准恒定，消费侧不适靠修订规则细节吸收，不靠放松标准。治理的信用，恰恰建立在这种不舒服上。

"我评审通过就算规则生效了吗？"

不是。评审通过只走到"规则被正确翻译"，它还要被编译、被消费、被追踪。消费率长期为零的契约是沉睡规则，标准再严，没人消费等于没写。

结语

契约入库、编译跑通、四种产物分发的那个瞬间，规则就开始自己上班了，不靠记性，不靠群公告，不靠谁的自觉。

但"自己上班"有个前提：有人恒定执行及格线。起草时的每一组自问，评审时的每一条核查，都是在给这套自动运转的系统上发条。你守住的不是一份模板，是这套体系治理信用的来源。

规则流向的下一站，由下游角色接住：前端挂载产物、DesignOps运营追踪，他们的视角，在各自的角色专题里。而再往后，是这套体系在真实组织里的完整证明。

模板字段为冻结 v1.0.0。第一条契约评审通过的那天，值得记录，那是"规则自己上班"的第一天。

1920.png.png