GuardrailSpec YAML 字段手册#
English | 简体中文
GuardrailSpec 定义一类操作需要完成的检查及证据。它是一份 YAML 策略文档, 不是可执行的规则语言。外部 Agent 或集成方观察真实系统,为每个 Check 提交 结论和证据;OpenGuardrail 服务依据该 Run 冻结的 Spec 校验提交内容,但不独立 证明观测为真。执行工具需要在操作前核验权威决策、已接受的证据及当前操作。 参见核心概念和 Run 与提交。
本文对应 guardrail.open/v1alpha1。当前版本接受的字段与约束以
OpenAPI 契约和
Spec 校验代码为准。
可直接使用的完整示例#
将下面内容保存为 file-cleanup.yaml:
apiVersion: guardrail.open/v1alpha1
kind: GuardrailSpec
metadata:
name: file-cleanup
spec:
description: Check a proposed cleanup of temporary files
instructions: Inspect the exact files and submit current observations for every check.
validForSeconds: 60
checks:
- id: temporary-only
displayName: Temporary files only
description: Protect business files from deletion
instructions: Confirm that every target is an existing temporary file in the intended workspace.
criteria:
pass: Every target is an existing temporary file in the intended workspace
block: At least one target is a protected business file
unknown: Target identity or current file state cannot be verified
evidenceRequirements:
- id: files
description: Workspace identity, exact targets and observed file metadata
appliesToVerdicts: [PASS, BLOCKED, UNKNOWN]
这份 Spec 本身不会检查或删除文件;文件清理 Demo 提供了外部观测与执行逻辑,并使用一份包含两个 Check 的 Spec。 Recovery Spec也是一份完整的简短样例。
字段与约束#
字段名与枚举值区分大小写。下表标为必填的字段必须出现;文本不能只有空白字符, 长度按 Unicode 字符计算。未知字段会被拒绝。
| 路径 | 必填 | 含义与约束 |
|---|---|---|
apiVersion |
是 | 固定为 guardrail.open/v1alpha1。 |
kind |
是 | 固定为 GuardrailSpec。 |
metadata.name |
是 | Spec 标识符:1–63 个小写字母、数字或连字符;以字母开头,以字母或数字结尾。 |
spec.description |
是 | Spec 的用途,最多 1,024 字符。 |
spec.instructions |
是 | 对评估方的整体指引,最多 8,000 字符。 |
spec.validForSeconds |
否 | 终态决策的有效秒数:Run 正常完成(FINISHED)时从完成时起算;Run 过期(EXPIRED)时从逻辑截止时间起算。十进制整数,范围 1 至 9007199254740991,默认 3600;不能加引号或前导零。 |
spec.checks |
是 | 1–20 个 Check;同一 Spec 中的 Check ID 不可重复。 |
spec.checks[].id |
是 | Check 标识符,格式与 metadata.name 相同。 |
spec.checks[].displayName |
是 | 给人看的检查名称,最多 128 字符。 |
spec.checks[].description |
是 | 检查覆盖的事项,最多 1,024 字符。 |
spec.checks[].instructions |
是 | 评估方如何调查该检查,最多 8,000 字符。 |
spec.checks[].criteria.pass |
是 | 该检查何时可以报 PASS,最多 2,048 字符。 |
spec.checks[].criteria.block |
是 | 该检查何时应报 BLOCKED,最多 2,048 字符。 |
spec.checks[].criteria.unknown |
是 | 无法核实时何时报 UNKNOWN,最多 2,048 字符。 |
spec.checks[].evidenceRequirements |
是 | 1–20 条证据要求;同一 Check 内的要求 ID 不可重复。 |
spec.checks[].evidenceRequirements[].id |
是 | 证据要求标识符,格式与 metadata.name 相同。 |
spec.checks[].evidenceRequirements[].description |
是 | 需要何种观测,最多 1,024 字符。 |
spec.checks[].evidenceRequirements[].appliesToVerdicts |
是 | 从 [PASS, BLOCKED, UNKNOWN] 中选 1–3 个不重复的值。提交所列结论时必须提供这条证据;其他结论不能附带它。 |
标识符的完整格式为 ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$。
criteria 是给评估方的文字判定标准,服务不会执行这些文字。
最终 Submission 必须覆盖全部 Check 及其适用证据:全部 PASS 得到
PASS / ALLOW;有任一 BLOCKED 得到 BLOCKED / DENY;否则有
UNKNOWN 则得到 UNKNOWN / DENY。提交格式详见 Run 与提交。
YAML 与 Scene 的边界#
- 文件只能包含一份 UTF-8 YAML 文档,最多 64 KiB、4,096 个节点、嵌套深度 16。
不接受重复键、锚点、别名、自定义标签、未知字段或隐式标量类型转换。
除
spec.validForSeconds外,标量必须是 YAML 字符串;可能被解析成布尔值 或数字的文字应加引号。 sceneKey、runTtlSeconds、Project key 和每次操作的changeSet都不是 GuardrailSpec 字段。Scene 有自己的稳定 key 和 Run 截止时间;spec.validForSeconds控制的是 Run 进入终态后的决策有效期。 调用方在创建每个 Run 时提交changeSet。- 已发布的 Revision 不可修改。发布时校验和规范化 YAML,并生成内容 digest; Run 会冻结选中的 Revision 和 digest。注释与排版不构成策略检查。
发布与使用#
启动服务并使用管理员 CLI 会话,从仓库根目录发布 YAML:
guardrailctl scene apply --key file-cleanup --name 'File cleanup' \
--spec ./file-cleanup.yaml --publish
首次执行会创建 Scene、默认 Policy 及生效 Revision;内容未变化的重复发布会 复用现有 Revision。发布会修改服务状态,试写时请使用隔离服务。 用于创建和读取 Run 的 Project key 不能发布 Spec。Draft 审查、生效版本和 凭据见场景与 Spec,完整本地流程见入门指南。
常见错误#
| 写法 | 问题 | 正确做法 |
|---|---|---|
在 YAML 中写 sceneKey 或 runTtlSeconds |
两者属于 Scene,不属于 Spec。 | 用 scene apply --key 选择 Scene;另行配置 Run 截止时间。 |
在 Check 中写 requirement: SQL must have WHERE |
requirement 不是现有字段。 |
填写 description、instructions、三个 criteria 值及 evidenceRequirements。 |
只在 criteria 里写通过条件 |
文本不会自动检查系统或证明观测为真。 | 由外部集成采集证据,并随适用结论提交。 |
validForSeconds: "300" 或 validForSeconds: 0300 |
唯一的数字字段不能加引号或前导零。 | 使用 validForSeconds: 300。 |
拿到 ALLOW 就执行任意后续操作 |
决策关联特定 Run、被冻结的上下文及有效期。 | 执行前回读权威 Run 和已接受的 Submission,并核对操作身份、证据及当前状态。 |