快速开始#
首批机器上线后,让你的 AI 编程助手按 Spec 依次排查监控、日志和告警,再决定下一批能否继续发布。观看 30 秒回放
跑一遍首批检查#
在你的 AI 编程助手(如 Claude Code、Cursor、Codex、Antigravity 等)中打开包含 examples/agent-demo/first_batch.py 的仓库目录(需提前备好 Make、Python 3.9+ 及 go.mod 指定的 Go 版本),直接发送下面这句话:
用 $open-guardrail-demo 跑一遍首批检查,告诉我下一批能不能发。
Agent 会自动拉起本地临时服务,按 Spec 排查首批实例的监控、日志与告警,并在对话中给出排查过程和最终裁决。默认模拟数据里,订单 order-42 已扣款但状态仍停留在 pending,预期结果为 BLOCKED / DENY(全程无需登录控制台)。
检查完成后,Agent 会生成一个本地 JSON 报告链接,里面保留了服务端诊断记录与采信的观测证据;哪怕随后关掉临时服务、清理了临时库和凭据,这份报告依然可以随时打开回看。如果想在 Web 控制台查看详情,在启动时告诉它开启即可。
评估流程#
点击流程图可以查看完整 SVG。策略、评估和决策模型见核心概念。
前置条件#
从源码运行需要:
go.mod指定的 Go 工具链。- 执行
make build所需的 Make。 - 只有运行下述本地 Demo 时,才需要 Python 3.9+。
在源码根目录运行命令。构建服务和 CLI 不需要 Node.js 或 Docker。
如果使用预览版二进制归档,先完成归档校验,再从解压根目录执行命令。用 ./open-guardrail 和 ./guardrailctl 替换源码构建的 ./bin/ 路径;运行二进制不需要 Go、Node.js 或 Python。
可选:不用模型运行文件清理#
准备好 Python 3.9+ 后,在源码或归档根目录运行下列命令。从源码运行还需要 Go:
python3 examples/cleanup-demo/demo.py
脚本会从源码构建命令,或使用归档中的二进制,并使用自动生成的临时密码启动本地服务和受控文件清理工具。首次从源码构建可能下载 Go 依赖。Demo 需要 Python 3.9+;发布组装和维护者验证脚本另需 Python 3.12+。
先打开终端输出的 Demo URL。清理任务和 Run 详情不需要登录。保留默认选择,点击 Run cleanup task(运行清理任务):
- Runner 请求删除全部四个示例文件,包括受保护的订单和配置文件,服务记录一个
BLOCKED / DENYRun。 - Runner 将请求缩小为两个临时文件,提交新评估,服务记录一个
PASS / ALLOWRun。 - 删除工具重新读取 Run 和已接受证据,核验身份与有效期,只删除批准的临时文件。
- 在页面检查两个 Run。恢复文件、修改选择或批次上限,再次运行以比较实际结果。
Runner 是不使用模型的预定义代码,服务调用和文件操作均真实执行。Demo 指南说明执行核验与限制。需要在常规 UI 查看同一批记录时,打开输出的 Console URL,使用 demo 和输出路径 console-login.json 中的自动生成密码(或通过 --prompt-password 自行设置的密码)登录,选择 Runs。
检查记录时保持终端开启。Ctrl-C 停止服务,移除临时数据和凭据。原始 Recovery 契约自检命令为 python3 examples/agent-demo/smoke.py,默认立即退出并清理;加上 --keep-running 可保留记录供浏览器查看,直到按 Ctrl-C。需要持久数据或自己的策略时,使用下述操作流程。
自动化启动清理 Demo 时,--password-stdin 从标准输入读取设置的密码。不要把密码放在命令参数或提交到仓库的脚本中。仅限源码使用的 make demo 等价于上面的交互命令。
手动创建并检查一个 Run#
1. 启动服务#
在源码目录执行:
make build
./bin/open-guardrail serve
保持终端开启。默认监听 127.0.0.1:8080,SQLite 数据保存在相对于启动目录的 ./data/guardrail.db。
打开 http://127.0.0.1:8080,创建名为 admin 的管理员并自行设置密码。初始化后自动登录浏览器,没有默认密码。
无引导令牌的本地初始化要求直接回环连接。远程或容器部署见 Docker 部署及管理员初始化。
2. 登录 CLI#
在同一源码根目录打开第二个终端:
guardrail_cli=./bin/guardrailctl
export OPEN_GUARDRAIL_URL=http://127.0.0.1:8080
umask 077
guardrail_demo_dir=$(mktemp -d)
export OPEN_GUARDRAIL_SESSION_FILE="$guardrail_demo_dir/session.json"
"$guardrail_cli" status
"$guardrail_cli" auth login --username admin
使用解压二进制归档时,将 guardrail_cli 改为 ./guardrailctl。在隐藏提示中输入管理员密码。浏览器和 CLI 会话相互独立。示例将 CLI 会话和机器凭据保存在源码树以外的私有临时目录。
3. 发布示例策略#
"$guardrail_cli" scene apply --key recovery --name Recovery \
--spec ./examples/policies/recovery.yaml --publish
"$guardrail_cli" auth create-key --expires-in 1h \
--result-file "$guardrail_demo_dir/project-key.json"
策略要求一项 readiness 检查和 health 证据。命令发布并激活该修订;临时 Project 密钥有效期为一小时。
策略编辑和发布见场景与策略。
4. 创建 Run#
创建合成变更描述,然后创建一次评估:
cat > "$guardrail_demo_dir/change-set.json" <<'JSON'
{
"application": "example-service",
"environment": "local",
"operation": "recovery"
}
JSON
guardrail_demo_operation="quickstart-$(date +%s)-$$"
"$guardrail_cli" run create \
--key-file "$guardrail_demo_dir/project-key.json" \
--scene recovery \
--change-set "$guardrail_demo_dir/change-set.json" \
--operation-id "$guardrail_demo_operation-create" \
--submission-credential-file "$guardrail_demo_dir/run-credential.json"
命令输出 status: "OPEN" 的 Run 对象。将其顶层 id 复制到以下变量,替换示例值:
guardrail_demo_run_id=run_REPLACE_WITH_RETURNED_ID
Run 冻结策略修订、调用方定义的 changeSet 和截止时间。提交凭据私密保存,CLI 不打印令牌。
在 Run 截止前完成下一步。创建结果不确定时,保留相同操作 ID,先检查状态再重试。初始凭据只返回一次,见凭据恢复。
5. 提交合成的通过评估#
提交一份使用合成观测、结论为通过的评估,时间戳在执行时生成:
cat > "$guardrail_demo_dir/submission.json" <<JSON
{
"baseSubmissionNo": 0,
"finishRun": true,
"verdict": "PASS",
"summary": "Synthetic local recovery assessment",
"checks": [
{
"checkId": "readiness",
"verdict": "PASS",
"summary": "Synthetic health observation is healthy",
"evidence": [
{
"requirementId": "health",
"observedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"querySummary": "Read a synthetic local health observation",
"resultSummary": "Example service is healthy; no real service was queried"
}
]
}
]
}
JSON
"$guardrail_cli" run submit \
--submission-credential-file "$guardrail_demo_dir/run-credential.json" \
--submission "$guardrail_demo_dir/submission.json" \
--operation-id "$guardrail_demo_operation-submit" \
"$guardrail_demo_run_id"
"$guardrail_cli" run get \
--key-file "$guardrail_demo_dir/project-key.json" \
"$guardrail_demo_run_id"
返回的 Run 应具有 status: "FINISHED"、result: "PASS"、decision: "ALLOW",以及最终 Submission ID 和决策过期时间。
6. 检查记录#
在浏览器打开 Runs,选择返回的 Run ID,检查冻结的策略引用、评估上下文、提交证据及决策。
真实集成必须核验权威 Run、决策有效期及其依赖的观测。见 Run 与 Submission及集成方案。
问题排查#
| 现象 | 下一步 |
|---|---|
| Python 版本错误 | 检查 python3 --version,Demo 使用 Python 3.9+。原生二进制和手动流程不需要 Python。 |
| 缺少 Go 或构建失败 | 源码需要 go.mod 指定的 Go 版本,并能访问公开依赖。运行 make build 查看编译诊断,或使用原生归档。 |
| 服务退出或未就绪 | 清理 Demo 报告安全的错误分类,并尽可能提供命令退出码。从源码运行 ./bin/open-guardrail serve,或从归档运行 ./open-guardrail serve 查看启动诊断,检查数据目录、原生二进制和端口。 |
| Demo 地址返回 403 | 精确打开输出的 http://127.0.0.1:<port>,清理 Demo 不接受 localhost 或其他主机名。 |
| 来不及打开 Runs,Recovery 自检就退出 | 运行 python3 examples/agent-demo/smoke.py --keep-running 并保持终端开启。默认 Recovery 自检会清理临时记录,清理 Demo 则会持续运行。 |
| 浏览器登录失败 | 使用 demo 和输出路径 console-login.json 中的自动生成密码(或通过 --prompt-password / smoke.py --keep-running 自行设置的密码)。手动流程的 admin 账号及已有服务与其相互独立。 |
| 隐藏密码提示要求终端 | 交互运行,或在自动化中传 --password-stdin。查看 Recovery 自检的临时记录还需 --keep-running。 |
Demo 不会在终端打印密码本身(默认仅输出 console-login.json 凭据文件路径),也不会输出捕获到的含凭据命令内容。报告问题时提供步骤、退出码、版本和平台,密码、会话文件和机器凭据文件应保密。
清理或继续探索#
服务数据持久保存在 ./data。Ctrl-C 停止服务后,从同一目录重启可保留管理员、策略和 Run。需要明确存储位置时,使用 --data-dir /path/to/persistent/data。
先撤销本流程创建的那一把 Project 密钥。在管理员 CLI 会话仍有效时,检查不含秘密的元数据:
"$guardrail_cli" auth list-keys --page-size 20
根据签发时间、角色和权限范围识别本流程的密钥。私有凭据文件也记录相同的非秘密 keyId,需要时只在本地比较该字段,不展示或分享令牌。如果密钥位于下一页,用 --after CURSOR 跟随 nextAfter。不要撤销其他集成正在使用的密钥。
用选中密钥的 id 替换示例 ID,再执行撤销:
guardrail_demo_key_id=key_REPLACE_WITH_DEMO_KEY_ID
"$guardrail_cli" auth revoke-key --key-id "$guardrail_demo_key_id"
撤销成功后,在第二个终端、变量仍已设置的情况下,删除临时 CLI 会话及文件。撤销失败时,保留会话和凭据文件,直到问题解决。
"$guardrail_cli" auth logout
rm -f "$guardrail_demo_dir/session.json" \
"$guardrail_demo_dir/project-key.json" \
"$guardrail_demo_dir/run-credential.json" \
"$guardrail_demo_dir/change-set.json" \
"$guardrail_demo_dir/submission.json"
rmdir "$guardrail_demo_dir"
unset OPEN_GUARDRAIL_SESSION_FILE
删除机器密钥文件不等于撤销密钥。撤销和秘密轮换已经实现;撤销立即阻止后续密钥认证,但不取消已通过认证的请求。有效期、轮换和恢复规则见 Project 机器密钥。请在本地评估服务上使用本流程。
接下来可以体验 Agent 驱动的示例,配置 PostgreSQL 或远程访问,或阅读贡献指南。
