theo.guardrails.policies— 创建和管理策略。theo.guardrails.presets— 只读的预设模板。theo.guardrails.executions— 追溯审计日志。theo.keys.getGuardrailPolicy/setGuardrailPolicy— 将策略绑定到某个密钥。
严格的可选启用约定
策略仅在通过theo.keys.setGuardrailPolicy() 显式绑定到某个 API 密钥时才会生效。未绑定的密钥永远不会触发护栏——不存在自动的组织级或用户级默认回退。创建策略(或从预设生成策略)不会自动绑定它。
策略
列出
获取
创建
scope: "team" 需要一个有效的组织以及团队配置权限。通过 Idempotency-Key 请求头实现幂等。
更新
rules 会替换整个规则集。
删除
会级联移除所有指向该策略的密钥绑定——此前绑定的密钥将回归严格可选启用的默认状态(即不执行任何护栏检查)。测试(重放提示词)
针对该策略重放一个固定的提示词(以及可选的模型输出),并返回裁定链路——供仪表盘的测试台使用,无需消耗一次真正的补全调用。绑定关系
列出当前绑定到某个策略的活跃(未撤销)密钥。在生产环境依赖某个策略之前,可用它来确认该策略正在预期的密钥上生效。预设
仪表盘在空状态下提供的只读蓝图。目前上线的四个预设分别是pii-safe、strict-json、cost-conscious 和 enterprise-default。
从预设创建策略,本质上就是一次普通的 policies.create() 调用,只是用预设的 rules 作为初始值:
执行记录(审计日志)
记录每一次护栏评估的只追加日志。个人调用方只能看到自己的记录;团队调用方可以看到当前活跃组织所拥有的策略下所有成员的记录。记录保留 90 天。密钥绑定
错误处理
当输入阶段触发deny 裁定时,SDK 会抛出一个与 REST 响应体结构一致的结构化错误:
done 之前以 error 类型的 SSE 事件发出。完整的错误分类见错误处理。
类型
SDK 为每一种数据结构都导出了对应的类型:GuardrailPolicySummary— 完整的策略记录行。GuardrailRuleInput— 单条规则(guardrail_id、phase、verdict,可选的config、enabled、rule_order)。GuardrailId—"pii_redactor" | "prompt_injection" | "json_repair" | "max_length" | "profanity"。GuardrailPhase—"input" | "output"。GuardrailVerdict—"flag" | "redact" | "truncate" | "repair" | "deny"。GuardrailPolicyPreset—presets.list()返回的预设模板。GuardrailPolicyBinding— 绑定关系端点返回的单条记录。GuardrailPolicyTestResult—policies.test()返回的裁定链路。GuardrailExecutionRecord— 执行记录审计日志中的单条记录。
