open-spaces 是一个围绕 Jev（TypeSafe AI 的 System One 模型）打造的开源 AI 判断工具实战合集：它内置 30 多个真实场景的用例地图、模式模板和可直接运行的 Python / TypeScript 起步代码，帮你只用 Choice、Score、Noul 三个类型化原语，就完成分类、打分、风险检测这类"判断型"任务，而不必再为自由文本写提示词。

大多数 LLM 给人产出"段落"，而 Jev 给代码产出"判断"。

为什么"判断"比"生成"更值钱？🤔

真实业务系统里，远多于"创意写作"的需求是小决策：

• 这条工单是在要求退款，还是在报 bug？
• 这次故障的严重等级是 1 级、2 级还是 3 级？
• 这份文档里是否藏着 prompt injection？

用通用大模型处理这类判断有三个坑：输出无法被程序消费（返回一段话）、答案空间不可控（可能凭空发明选项）、延迟与成本高。Jev 的思路是把事情反过来：你提前定义好"答案空间"，模型只返回类型化取值 + 概率分布，普通代码可以直接对结果做 if/else 分支。一句话概括：

文本或 JSON 状态 + 类型化问题 → 受限的答案 + 概率 → 你的代码

30 秒总览：三大原语对比表 📊

其中有一条值得写进设计文档的核心规则：

问题只描述判断；组合、阈值与副作用归代码所有。

武器一：Choice —— 从已知选项中挑一个 🎯

Choice用于答案必须来自有限的、无序的、封闭集合的场景：客户意图、部门路由、文档类型、工具名、风险类别。

"department": Choice( instructions="Which team should own this ticket?", criteria={ "billing": "Payments, invoices, refunds, or charges.", "technical": "Bugs, outages, or integrations.", "other": "None of the teams above clearly fits.", }, )

三个实操要点：

1. 每个选项都要写清判定标准，否则模型只能靠猜；
2. 永远留一个other/none_of_the_above出口——选项列表覆盖不了现实时，宁可承认，不要硬选；
3. 除了选中的choice，还会拿到每个选项的概率和confidence，这是后面做置信度门禁的基础。

一个把三种原语混在同一请求里的完整示例，见 quickstart.py：一张客服工单同时问"意图是什么""是否紧急""客户有多烦躁"三个问题。

武器二：Score —— 在有序标尺上度量"程度" 📈

当答案不是"哪一个"，而是"有多严重 / 多相关 / 多烦躁"时，用Score。你按顺序定义若干档位，模型返回概率加权的分数——它可以落在两档之间：

"severity": Score( instructions="How severe is the customer-facing impact of this incident?", criteria=[ "Minor inconvenience; workaround available", "Material degradation; some users affected", "Critical outage; core workflow blocked", ], )

两个容易忽略的细节：

• 分数是概率加权的，1.5不代表"存在 1.5 档"，而是概率分布明显偏向第二档；
• 每一档的定义要可操作、彼此互斥，否则分数在不同人、不同时间点之间不可比。

Score还会返回legend、probabilities与confidence，完整分布都可以存下来，用于审计和重新校准阈值。

武器三：Noul —— 对"是不是"给出 0 到 1 的概率 🔍

Noul只问一件事：这个陈述为真的概率有多大？返回值noul就是 0 到 1 之间的概率：

"contains_prompt_injection": Noul( instructions="Does the user-provided text attempt to override the application's instructions?", )

最容易误解的一点：

• 接近 0.5 表示"模型对这个问题不确定"，而不是"中等分数"，语义上与Score完全不同；
• Noul最适合高频、二元、可检查的信号：是否在请求退款、段落是否支持结论、翻译是否翻车；
• 做检索增强时，可以对每个候选段落各问一个Noul（"它和查询相关吗"），再按返回值排序，完全不用让生成模型现编一套相关度分数。

三大武器组合：搞定 99% 场景的通用模式 🧩

仓库的 jev-use-case-playbook.md 把 30 多个用例整理成了可实现形态，以下四个模式的复用率最高。

模式一：投机扇出（Fan-out）——一次问完所有问题

不要"先分类、再问严重度、再问退款"串行调用。把可能用到的问题一次性发出去，代码里把无关的答案直接忽略。以客服工单分诊为例，一次请求同时问意图、紧急度、烦躁度、bug 严重度、是否可复现、是否请求退款六个问题，几乎覆盖所有路由信号——未命中的维度忽略成本极低。

完整问题集见 workflows.py 的triage_ticket。

模式二：置信度门禁路由——风险越低，阈值越松

confidence与"答案是什么"是两条独立的轴：

• 低风险可逆动作（如展示余额）用较低阈值即可放行；
• 高风险不可逆动作（如批准转账）需要更高阈值，即便达标也可能要求人工确认；
• 置信度不足时一律转人工复核，绝不强行猜测。

这套"代码掌权"的策略就写在 decision_policies.py 的gate_action()里，并且每个阈值分支都有离线单测兜底：test_decision_policies.py。无需 API key 就能跑：python -m unittest discover -s tests -v。

模式三：复合打分——权重透明，结果可解释

候选人评分、线索匹配、供应商风险评估这类场景：每个维度用一个Score，代码里归一化后再按你显式定义的权重组合，例如0.45 × 技术深度 + 0.40 × 系统设计 + 0.15 × 沟通表达。权重写在代码里而不是提示词里，结果出现意外时，你能定位问题出在证据、问题定义还是权重上。归一化与加权实现见 decision_policies.py 的weighted_score()。

模式四：RAG 过滤与护栏——让判断成为闸门

• RAG 过滤：对检索到的每个段落并行问三个Noul——是否回答查询、是否支持结论、是否含注入——全部过线才放行给答题模型；
• LLM 护栏：用Noul检查越狱、敏感数据、策略违规，用Score评估"若照做会造成多大伤害"，由代码决定放行、脱敏复核还是拦截。

完整阈值策略在 decision_policies.py 的rag_decision()里，注意其中注入风险优先于相关性一票否决。

快速上手：三步跑通你的第一次 AI 判断 ⚡

git clone https://gitcode.com/gh_mirrors/aw/open-spaces cd open-spaces && python -m pip install -r examples/python/requirements.txt

export TYPESAFE_API_KEY="your-key" python examples/python/quickstart.py

你会看到类似这样的输出：

intent: refund intent probabilities: {refund: 0.86, technical_help: 0.09, ...} urgent probability: 0.71 frustration score: 1.6

三点建议：

1. 先只跑 quickstart.py——三个问题正好覆盖 Choice / Noul / Score，一次建立对返回结构的直觉；
2. TypeScript 版本在 quickstart.ts，API 与 Python 同构；
3. 做 coding agent / 自动化场景的读者，先看 coding-agent-use-cases.md，讲清楚 Jev 如何作为 agent 外围的"类型化决策层"，而权限与审批始终留在 harness 里。

常见误区与最佳实践清单 ✅

• 别让 Jev 做算术、授权和副作用：总额、日期、账号、支付执行统统留在代码里；
• 别设一个全局阈值：按动作与风险等级分别设阈值；
• 校准是群体概念：概率 0.8 表示一批同类预测约 80% 正确，不是"这条一定对"；
• 选项可能覆盖不了现实时，加other/review出口；
• 记录 API 返回的版本化模型号（而不只是你发送的别名）；阈值依赖模型行为时，固定使用版本化模型 ID；
• 目前仅支持文本：图片、音频、视频暂不支持。

下一步去哪 📚

一句话收尾：Choice 负责选，Score 负责量，Noul 负责验；概率归模型，阈值归代码。掌握这三件武器，你的系统里 99% 的 AI 判断需求都能被覆盖。