open-spaces 上线清单:Jev 生产部署前必须核查的 10 条安全与可靠性规则
open-spaces 上线清单:Jev 生产部署前必须核查的 10 条安全与可靠性规则
如果你正准备把 Jev 接入生产系统,open-spaces 这份开源用例仓库沉淀的 10 条安全与可靠性规则值得逐条核对:从 API Key 管理、置信度阈值,到副作用隔离与上线前评测,覆盖了 AI 决策模型最容易出问题的环节。本文按"规则 + 仓库出处"的方式整理,方便你在 Jev 生产部署前快速完成安全自检。
📖 先搞清楚:Jev 与 open-spaces 是什么
Jev 是 TypeSafe 推出的第一个 System One 决策模型:你给它一段状态(文本或 JSON)加上一组限定答案空间的问题,它返回类型化答案、概率分布和置信度,供普通代码分支判断——而不是生成一段自由文本。
open-spaces 则是围绕 Jev 建设的开源用例集合:官方事实速查表、31 个落地场景、核心模式说明,以及可直接运行的 Python / TypeScript 示例与离线测试。其中最有参考价值的是三块材料:
| 模块 | 作用 |
|---|---|
| examples/python/decision_policies.py | 纯策略代码:置信度门控、加权评分、RAG 证据过滤,不依赖 SDK,可离线测试 |
| examples/python/workflows.py | 支持工单分诊、护栏问题集、语义重排等工作流适配器 |
| tests/test_decision_policies.py | 无需 API Key 的离线单元测试,锁定关键安全行为 |
一个贯穿全部 10 条规则的设计原则是:模型只负责回答判断,阈值、授权和副作用永远归代码管。
🛡️ 10 条规则逐条核查
以下 10 条来自 README.md 的 Safety and reliability checklist,每条都附带仓库中的可验证出处。
规则 1:API Key 只留在服务端 🔒
把 TYPESAFE_API_KEY 只放在服务端环境变量中,并限制哪些服务有权限调用决策端点。前端、移动端和 CI 日志中都不应出现明文 Key——示例代码统一通过 SDK 从环境读取 Key(见 examples/python/quickstart.py),这个模式可以直接照抄。
规则 2:选项集永远留一个兜底出口
使用 Choice 时,只要选项列表可能不完整,就必须加入 other、unknown 或 review 选项。仓库里的工单分诊问题始终包含 "other": "None of the options clearly fits."(见 examples/python/workflows.py),这就是标准做法。
规则 3:阈值按动作和风险分级,禁止全局一个数 ⚙️
同一个系统里,"查看余额"和"批准转账"绝不能共用一个置信度阈值。仓库的 gate_action 策略做了示范:低风险动作在置信度 0.60 即可执行;approve_transfer 则要求高于 0.90 才能免确认——实现见 decision_policies.py,对应测试在 tests/test_decision_policies.py。
规则 4:低置信度必须是一级分支
置信度不足时不要"凑合"用最高概率选项,而是走显式的 human_review 分支。示例中未知动作(如 delete_account)无论置信度多高都会安全地落入人工复核,这条"未知即安全"的行为由 离线测试 锁定,防止将来重构时悄悄破坏。
规则 5:状态、问题、策略代码一起版本化
State schema、问题指令、选项标准(criteria)与策略代码是一个整体,必须一起纳入版本管理。任何一边单独改动,历史决策的语义就不可复现了。这也是仓库对贡献者的硬性要求,参见 CONTRIBUTING.md 的证据清单。
规则 6:记录响应里返回的真实模型版本
请求发送的可能是 jev-latest 这类别名,但别名会移动。审计日志必须记录响应里实际返回的版本化模型 ID,而不是请求中的别名。README 的事实速查表对此有明确提示(calibration guidance 一行)。
规则 7:存档完整概率分布,别只存最终标签
只存胜出标签,事后既无法审计也无法校准。Choice 和 Score 都会返回每个选项的概率——把这些分布完整落库,是后续阈值调优与事故回溯的基础。RAG 场景的完整判断依据(含注入风险概率)可参考 rag_decision 策略。
规则 8:为限流和过载设计重试
TypeSafe 当前列出的限额约 1,200 请求/分钟,且会动态变化(Quick facts)。接入时直接使用 SDK 对 429、529 的默认重试行为;若走裸 HTTP 调用,则必须自行实现指数退避。
规则 9:副作用放在显式第二步
"判断"与"执行"拆成两步:先检查、审批,再由代码显式触发转账、删除等副作用。仓库的 RAG 证据门禁是典型例子——注入风险概率达到 0.20 即拒绝,即使相关性再高也不放行,该"注入风险优先"策略由 测试用例 保证。
规则 10:用代表性案例做上线前评测 🧪
用你自己的真实数据评测,且必须包含四类硬骨头:模糊输入、对抗性文本、缺失字段、领域外输入。护栏类问题(越狱检测、敏感数据、策略违规)可直接复用 workflows.py 中的 guardrail_questions 作为起步问题集,再按业务补充。
✅ 上线前 5 分钟自检表
| # | 核查项 | 关键行为 |
|---|---|---|
| 1 | Key 管理 | Key 仅存服务端,限制可调用方 |
| 2 | 选项兜底 | Choice 含 other/review 出口 |
| 3 | 阈值分级 | 每个动作有独立风险阈值 |
| 4 | 低置信分支 | 不确定时走人工复核 |
| 5 | 版本化 | state / 问题 / 策略代码同版本管理 |
| 6 | 模型版本 | 日志记录响应返回的真实版本 |
| 7 | 概率存档 | 存完整分布,不存单标签 |
| 8 | 重试策略 | 处理 429/529,指数退避 |
| 9 | 副作用隔离 | 判断与执行为显式两步 |
| 10 | 上线评测 | 覆盖模糊/对抗/缺失/越界输入 |
📚 延伸阅读
- docs/jev-use-case-playbook.md — 面向实现的用例手册,含分诊、护栏、评分等完整架构
- docs/coding-agent-use-cases.md — 编码代理与 Agent harness 场景模式
- examples/typescript/quickstart.ts — TypeScript SDK 用法
- docs/repository-metadata.md — 仓库主题与描述元数据
💡 建议把本文 10 条规则直接搬进你的上线评审单:每条都对应仓库里一个可运行、可测试的代码出处,评审时让同事指着文件逐条确认,比泛泛讨论"AI 安全"有效得多。