/docs
Jev 使用指南
Jev 用一份 state 对照一组带类型的问题做评估,返回结构化答案:可直接用于代码分支的类型化取值与概率分布。下面是完整用法。
概览
Jev 是 TypeSafe 的旗舰模型,也是第一个 System One 模型;JevStation 则是围绕它构建的工作台。大语言模型是为「给人读的文字」而训练的,所以当你需要模型给出代码要用的判断时,本质是在把文本生成硬掰成结构化输出,再把结果解析回来。Jev 反过来:你发送一份 state 和一组带类型的问题,它直接返回类型化答案 —— 不生成文本,不需要解析,也没有散文要揣摩。
快速开始
在试验台里三步跑完一次评估,然后用你自己的代码调用同一个模型。
放入 state
打开试验台,粘贴任何需要 Jev 判断的内容:一张工单、一条评论、一份需求文档,或一条 JSON 记录。试验台调用的契约与你的代码完全一致。
编写问题
每个判断写一个问题,可以在同一次调用里混用 Choice、Score 与 Noul。所有问题都针对同一份 state 评估。
读取答案
答案按你命名的 id 返回,附带各自的概率分布;Choice 与 Score 还会给出置信度。
从代码调用
试验台调用的契约与你的代码一致 —— 在那里设计好问题集,再从你的后端调用。对应接口是 `POST /api/v1/systemone`,使用你在「设置」里创建的 API Key 认证(`Authorization: Bearer sk_…`),每次调用消耗与试验台相同的点数。如果你想绕过 JevStation 的计量直接对接模型,请使用 TypeSafe 官方 API。
在 AI 智能体中使用 Jev
在用 AI 编程助手?复制一份完整的接入说明——端点、鉴权、请求与答案结构、错误码、费用和验证步骤——粘贴给 Claude Code、Cursor 或其他助手即可。
MCP 服务器
同样的评估也以 MCP 工具的形式提供(Streamable HTTP),用你的 API Key 鉴权,扣点方式与 HTTP API 完全相同。工具:jev_decide、jev_run_question_set、jev_list_question_sets、jev_route_model、jev_guard_tool_call、jev_moderate 和 jev_get_credits。在 Claude Code 中:
claude mcp add --transport http jevstation https://jevstation.com/api/mcp \
--header "Authorization: Bearer $JEVSTATION_API_KEY"Agent Skills
三个 Skill 教智能体如何调用 Jev、设计问题集,以及把 Jev 用作防护。安装到 ~/.claude/skills:
curl -fsSL https://jevstation.com/skills/install.sh | sh想先看看内容再运行?脚本只会下载 /skills/jev-api/SKILL.md、/skills/jev-question-design/SKILL.md 和 /skills/jev-guardrails/SKILL.md 三个文件。
指南:开源项目中的 Jev
六个独立 GitHub 项目,每篇都有创建 JevStation API Key 并调用 Jev 的分步指南(英文)。这些项目与 JevStation 无关。
问题类型
TypeSafe 提供三种 AI 原语。每一种问的问题不同,返回的答案类型也不同。
| 问题类型 | 用途 | 返回 |
|---|---|---|
| Choice | 从你定义的选项列表中选出一个 | choice、probabilities、confidence |
| Score | 按有序的评分档位给 state 打分 | score、probabilities、confidence |
| Noul | 这句话成立吗? | noul(0–1) |
原子化提问,在代码里组合
System One 模型最适合回答具体、边界清晰的问题 —— 就像一个懂行的人拿到足够上下文后几秒钟内能做出的判断。如果一个问题需要长链条推理,或者同时权衡多个独立因素,就把它拆开:每个因素单独提问,再用你自己的公式把答案组合起来。这样以后调整优先级只是改代码里的系数,而不是重写提示词。所有问题并行且相互独立地评估,因此多问几个几乎不增加等待时间,也不会互相串味。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| state | string | object | array | ✓ | 要评估的内容。纯文本用字符串;对话记录、业务记录或应用当前状态等结构化数据用对象或数组。 |
| model | string (optional) | ✓ | 可选。指定回答的决策模型:jev(默认,TypeSafe)、clef-flash 或 clef(Cloudflare)、pplx-decider(Perplexity Decider)、luna-decisions(OpenAI GPT-6 Luna Decisions)、ms-decision-1(Microsoft-Decision-1)、d1-ultra 或 d1(Liquid AI)。Clef 和 d1-ultra 消耗双倍点数。也接受 typesafe/jev-latest 这类上游 ID;其他值会返回错误,不会回退到 Jev。 |
| questions | map<string, Question> | ✓ | 带类型问题的映射表。键由你命名,对应的答案会用同一个键返回;键只是标签,不会发送给模型。Choice 至少需要两个选项,Score 至少需要两个有序档位。 |
| question_set_id | string (optional) | ✓ | 可选,用来代替 questions。填你在试验台保存的问题集 id,只能引用自己的问题集。questions 和 question_set_id 二选一,不能同时传。 |
每个问题对象都包含 instructions(要判断或评分什么),并各自补充 criteria:Choice 是选项映射,Score 是有序档位数组,Noul 是可选的 true/false 说明。
答案
每个问题返回一个答案,键与你传入的 id 一致。Choice 与 Score 的答案带有由概率分布推导出的置信度;Noul 只返回概率。
choice概率最高的选项、每个选项对应的概率,以及置信度。
score按概率加权得到的分数(可能落在档位之间)、把每个档位编号映射回描述的 legend,以及置信度。
noul答案为「是」的概率,0(否)到 1(是)。Noul 不提供置信度。
每个响应还会通过 usage.input_tokens 与 usage.output_tokens 报告本次请求的 token 用量。
置信度
概率分布的形状就说明了模型的确定程度:集中在一个结果上代表有把握,分散在多个结果上则相反。confidence 把这个形状压缩成 0 到 1 的单个数字,方便你直接设阈值,不必自己算。一个实用的起步做法是分三段:
自动执行。模型判断明确,无需人工介入即可继续。
谨慎推进。先请用户确认、标记待复核,或补充更多信息。
不要执行。转交人工、请求澄清,或改用其他系统兜底。
阈值划在哪里取决于风险:破坏性操作的阈值应当高于只读操作。
完整示例
一次调用、三个问题、一份响应 —— 不需要任何 SDK。
const res = await fetch("https://jevstation.com/api/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.JEVSTATION_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
state: "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
questions: {
department: {
type: "choice",
instructions: "Which team should handle this?",
criteria: {
billing: "Payments, invoicing, refunds",
technical: "Bugs, outages, integrations",
sales: "Pricing, upgrades, new accounts",
},
},
frustration: {
type: "score",
instructions: "How frustrated is the customer?",
criteria: ["Calm", "Frustrated", "Very angry"],
},
is_urgent: {
type: "noul",
instructions: "Does this convey urgency?",
},
},
}),
});
const { data } = await res.json();
data.answers.department.choice; // "billing"
data.answers.department.confidence; // 0.59
data.answers.frustration.score; // 1.04
data.answers.is_urgent.noul; // 0.99
data.credits.charged; // 1
data.credits.remaining; // 4,996curl -X POST https://jevstation.com/api/v1/systemone \
-H "Authorization: Bearer $JEVSTATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Payouts have been failing for 3 days.",
"questions": {
"is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
}
}'说明与限制
- 一次评估就是一次往返:Jev 返回的是答案而不是 token 流,因此要么拿到完整结果,要么干净地失败。
- 问题变多只增加输入 token,几乎不增加等待时间 —— 它们针对同一份 state 并行评估。
- 每次运行都会消耗点数:标准评估 1 点,state 超过 8,000 字符或问题超过 5 个后为 3 点。Clef 两档都翻倍(2 点和 6 点),Jev 与 Clef-flash 不变。余额在调用模型前检查,失败或取消的运行会自动返还。
- 评估记录按登录用户隔离,任何账号都无法读取他人的记录。
- 服务商凭据由运营方在后台配置,永远不会下发到浏览器。
- 遇到 429 或 529 时请按指数退避重试;客户端 SDK 已内置该策略。