YAML 契约模板的核心就是固定 7 个顶层字段,把人类口头、文档里的 “绝对不能” 这类定性约束,翻译成机器可以读取、校验、自动执行的标准化规则,不再依靠人工评审记忆,编译后可直接用于 AI 生成安检、CI 流水线校验、设计规范自动走查。过去很多约束都是写在文档里的自然语言,只能靠人阅读、人工检查,很容易理解偏差、落地遗漏,规则变更之后版本混乱;这套 YAML 契约把约束拆成固定 7 个字段,每条红线独立成契约条目,机器可以自动校验字段完整性、语义令牌、适用范围,触发违规时执行阻断、告警等动作。落地使用的时候,先梳理业务红线,提炼一条 “绝对不能” 约束,依次填充 7 个字段,编写 YAML 文本,提交到契约仓库,由编译管线自动解析,接入 AI 生成或研发流水线,触发自动校验,后续迭代只需要修改版本号,就能更新机器规则。
一、YAML 契约 7 个核心字段说明
| 字段名 | 作用 | 填写说明 | 缺失影响 |
|---|---|---|---|
| intent_id | 契约唯一标识 | 格式推荐领域缩写 + 编号,如 SAFE-001 | 违规时无法定位是哪一条规则 |
| description | 规则描述 | 写清楚现象、根因、风险后果,一句话说明约束目标 | 机器无法理解规则业务含义 |
| version | 版本号 | 遵循 SemVer 主。次. 修订,变更必须升级版本 | 下游系统继续使用旧规则,出现版本不一致 |
| semantic_domain | 语义域 | 标记这条约束所属领域,如安全边界、交互规范 | 规则被错误分发到无关业务 |
| applicable_products | 适用产品范围 | 列表形式填写生效产品 / 模块,限定生效边界 | 规则误伤不适用的产品场景 |
| semantic_tokens | 语义令牌 | 绑定规范里预定义的语义标签,统一术语 | 同含义规则用词不统一,机器无法识别 |
| immutable_boundaries | 不可变红线边界 | 填写禁止行为、判定条件、违规动作,也就是 “绝对不能” 的主体规则 | 缺少核心约束,契约没有执行效力 |
二、YAML 契约示例(安全约束场景)
intent_id: SAFE-001
description: 高危删除操作不能绕过二次确认弹窗,防止误删造成数据丢失
version: 1.0.0
semantic_domain: safety_boundary
applicable_products:
- 后台管理平台
- 知识库系统
semantic_tokens:
- action.destructive
- confirm.dialog
immutable_boundaries:
rule: 绝对不能在无二次确认弹窗情况下执行删除
violation_action: block
三、YAML 契约完整落地步骤
- 梳理业务红线:把文档、需求里的 “绝对不能”、硬性禁止条款单独提取出来,拆成单条约束。
- 填充 7 字段:依次填写 intent_id、描述、版本、语义域、适用产品、语义令牌、不可变边界。
- 语法与字段校验:提交契约文件,由机器校验必填字段完整性、YAML 语法、版本格式。
- 编译解析:将 YAML 契约编译为 Prompt 约束、JSON Schema、CI 校验规则、自动化走查脚本。
- 接入执行管线:对接 AI 生成网关、前端构建流水线、设计走查工具,实时校验是否触发红线。
- 迭代管理:规则修改时升级 version 版本,提交更新,自动同步到所有下游执行系统。
四、YAML 契约适用场景与局限
适用场景
- AI 大模型输出安检:约束 AI 不能输出违规内容,把安全红线写成契约自动校验。
- 设计系统规范:界面交互硬性规则,自动走查 UI 是否违反约束。
- 研发 CI 流水线:高危操作、接口规范校验,违规直接阻断发布。
- Agent 智能体边界管控:定义智能体绝对禁止执行的操作。
局限
- 只能处理可形式化描述的规则,复杂主观类业务判断很难写成 YAML 契约。
- 需要配套语义令牌体系,前期需要维护令牌字典,有一定建设成本。
- 契约只能校验显式定义的红线,无法自动发现未定义的新型风险。
五、YAML 契约和普通文档约束对比
| 类型 | 可读性 | 执行方式 | 版本管理 | 落地效果 |
|---|---|---|---|---|
| 自然语言文档约束 | 人可读,机器不可读 | 人工评审检查 | 版本混乱,容易过期 | 容易漏检、理解不一致 |
| YAML 契约 7 字段模板 | 人机双读 | 机器自动校验、阻断 | 版本号管控,变更可追溯 | 标准化,自动拦截,减少人工成本 |
【常见问题】
问题 1:YAML 契约模板的 7 个字段,核心作用是什么?
回答 1:YAML 契约模板 7 个字段用来把 “绝对不能” 这类自然语言红线,标准化为机器可读的规则,让系统可以自动校验、拦截违规行为,解决文档约束只能靠人工检查的痛点。
问题 2:YAML 契约 7 字段里 immutable_boundaries 字段是做什么的?
回答 2:immutable_boundaries 代表不可变红线边界,用来填写禁止行为、判定条件和违规处置动作,也就是契约里 “绝对不能” 的核心业务规则。
问题 3:编写 YAML 契约,每一条约束都必须全部填满 7 个字段吗?
回答 3:是的,这套模板中 7 个都是必填字段,缺少任意字段会在校验阶段直接失败,保证每一条机器规则信息完整,不会出现规则缺失、定位困难的问题。
问题 4:YAML 契约编译之后,可以输出哪些类型的执行规则?
回答 4:YAML 契约编译后,可输出 Prompt 约束、JSON Schema、CI 流水线校验规则、UI 自动化走查脚本,用于 AI 生成、前端发布、设计规范检查等场景。
【数据来源】
[2026-11-06](YAML 契约的模板:用 7 个字段,把 "绝对不能" 变成机器执行的规则)人人都是产品经理
[2026-11-05](约束显化:通过意图协议将 LLM 不可突破边界转化为机器可读契约)火山引擎开发者社区
[2026-11-03](YAML 契约格式与语义规范体系详解)InfoQ
[2026-10-28](AI 生成约束的工程实践,YAML 契约落地案例)腾讯云开发者社区
【免责声明】
本文 YAML 契约模板相关内容为公开技术文章整理,这套 7 字段契约体系属于一套自定义语义规范,非通用行业强制标准;规则编译、自动拦截效果取决于配套管线实现,落地前需要结合自身业务场景做适配验证。
