使用 jev-cli
jev-cli 让 Jev（一种“System One”评估模型）根据一组带类型的问题来评判一个共享的状态。它返回结构化的 JSON——一个选择、一个分数或一个概率，而不会返回文本。
当您的代码需要一个可以分支决策的依据时，请使用它。它比完整的 LLM 调用快得多且便宜得多（按输入 token 计费，输出 token 为零），因此检查一个差异、日志或支持记录中的十个属性成本很低。
不要用它来编写、总结、翻译或重写任何内容。它无法生成文本。
只需运行评估。无需先进行检查设置——当出现问题时，eval 会快速失败并返回一条可操作的消息和一个不同的退出代码，而 jev-cli doctor 是您此后（而非每次调用前）才使用的诊断工具。
运行评估
jev-cli eval --state <文本> --questions <JSON>
jev-cli eval -s "支持代理已全额退款 40 美元并道歉。" -q '{
"refunded": {"type": "boolean", "instructions": "是否已退款？"},
"tone": {"type": "choice", "instructions": "代理使用了什么语气？",
"criteria": {"warm": "友好且个人化", "curt": "简短或轻率"}},
"quality": {"type": "score", "instructions": "评估此事处理得如何。",
"criteria": ["差", "可接受", "优秀"]}
}'
{
"refunded": { "type": "boolean", "probability": 0.99 },
"tone": { "type": "choice", "choice": "warm", "probabilities": { "curt": 0.02, "warm": 0.98 } },
"quality": { "type": "score", "score": 1.78, "probabilities": { "0": 0, "1": 0.22, "2": 0.78 } }
}
这种内联形式适用于您自己编写的句子。对于已经存在于文件或命令输出中的任何内容，请接下来阅读传递输入——这是大多数调用者容易出错的地方。
传递输入：将内容保留在命令行之外
默认使用 --state-file / --questions-file，或通过管道输入 -。 内联 -s / -q 适用于您真正编写的短文本，而不适用于已经存在于某处的内容。
当代理作为调用者时，这一点比看起来更重要：
- 内联内容必须逐 token 生成。 将 50 KB 的差异粘贴到
-s中意味着生成约 15k 个输出 token——按输出费率计费，由于生成是串行的所以速度慢，并且是对已有内容的重新转录，这会导致静默截断和漂移。一个路径花费约 10 个 token，而管道则完全将内容排除在您的上下文窗口之外。 - Shell 会重写内联内容，有时会执行它。 在双引号中，
`cmd`是命令替换，${VAR}会展开。传递-s "const m = \echo hi`; const p = ${HOME}"会向模型发送const m = hi; const p = /Users/you`——反引号执行了。对于不受信任的输入（PR 差异、用户日志），这是一个命令执行表面，而不仅仅是内容损坏。在单引号中，内容中的一个撇号会直接破坏命令。
大小不是决定因素：~150 KB 可以正常通过 shell，而 Jev 自身的预算首先会限制。内容安全性和 token 成本才是原因。
# 最佳——内容从未进入模型上下文
git diff | jev-cli eval --state-file - --questions-file ./checks.json
# 良好——用命令准备，传递路径
git log -20 --oneline > /tmp/state.txt
jev-cli eval --state-file /tmp/state.txt --questions-file ./checks.json
# 尚可——您实际编写的短文本
jev-cli eval -s "代理已全额退款。" -q '{"r":{"type":"boolean","instructions":"已退款？"}}'
# 错误——重新转录已有的文件，通过 shell
jev-cli eval -s "$(cat huge-diff.txt)" -q ...
只有一个输入可以从 stdin 读取。当两者都很大时，将一个通过管道输入，另一个作为路径传递。跨调用重复使用问题文件，而不是重新发出。
当状态是 JSON 而不是纯文本时，添加 --state-json。
三种问题类型
每个问题都需要 instructions。instructions 和每个标准描述可以是字符串、JSON 对象或 JSON 数组——但不能是裸的数字或布尔值。
| 类型 | criteria | 答案 |
|---|---|---|
boolean | 可选 {"true": ..., "false": ...}，任一侧可省略 | {"type":"boolean","probability":0.98} |
choice | 必需。 选项名称 → 描述的对象（null 表示无） | {"type":"choice","choice":"warm","probabilities":{...}} |
score | 必需。 至少两个级别的数组，最低的在前 | {"type":"score","score":1.83,"probabilities":{...}} |
三件容易让人困惑的事情：
boolean给出 P(true)，而不是一个布尔值。0.98表示模型认为 98% 为真。它不是置信度，也未经过校准——请自行选择阈值。0.5表示“真假可能性相等”，不是“中等”。score是从0到criteria.length - 1的小数位置——概率加权平均值，而不是索引。对于渐变用score，而不是boolean。choice原样返回选项名称，因此将选项命名为您的代码将切换的值。其概率之和为 1，因此它恰好选择一个胜出者——对于“哪些适用，可能多个”，请为每个候选使用一个boolean。
硬限制
- 状态和问题共享约 32,000 个 token 的预算（约 150,000 个英文字符）。超出限制会失败，返回
{"error_type":"max_tokens_exceeded"}和 HTTP 400。 - 仅限文本。 状态必须是字符串、JSON 对象或文本数组。不支持图像、音频或视频。
因此，您不能将代码库、完整日志存档或大型语料库交给 Jev。请预构建一个紧凑的索引或摘录，然后进行评估。请参阅 references/patterns.md 了解如何构建。
在一次调用中询问所有内容
问题是并行且隔离地评估的——它们彼此不会看到。批处理几乎免费：TypeSafe 在一次请求中测量 13 个问题，结果显示比 13 个单独的请求便宜 11.5 倍，快 9.6 倍，且答案相同。他们的文档指出，编码代理比人类更容易陷入每次调用只问一个问题的习惯——不要这样做。
在一次请求中询问您可能需要的所有内容，并丢弃不使用的部分。仅在您确实无法在没有第一个答案的情况下构建时，才链接第二个请求。
读取结果
默认输出是裸答案对象，以您的问题 ID 为键，因此可以直接通过管道输入 jq：
jev-cli eval --state-file - -q "$CHECKS" | jq -e '.deploy_ok.probability > 0.9' >/dev/null && echo 健康
添加 --full 可获取使用量、警告和 providerMetadata——TypeSafe 在此报告 confidence 用于选择和分数答案，这与概率不同。添加 --compact 可获取单行 JSON。
退出代码和错误
eval 将错误写入 stderr 作为 JSON（{"error":{"code","message"}}），保持 stdout 干净。始终根据退出代码进行分支：
| 代码 | 含义 | 操作 |
|---|---|---|
0 | 成功 | 解析 stdout |
1 | 提供者或网络故障 | 重试一次；如果持续存在则报告 |
2 | 用法错误或无效问题 | 修复 JSON——消息中指明了有问题的问题 ID 和字段 |
3 | 缺少或被拒绝的凭据 | 将消息转发给用户；不要重试。见下文 |
代码 2 的消息如 questions.quality.criteria must list at least two ordered levels, but got 1 指向了需要修复的确切路径。
诊断故障
仅在调用实际失败时，且仅针对代码 1 和 3：
jev-cli doctor --offline # 配置、提供者、模型、密钥来源——无网络调用
jev-cli doctor # 以上所有，加上一个微型实时评估
代码 3 携带提供者自己的措辞，它们区分了需要不同修复的情况——缺少密钥、吊销的密钥、未设置计费的账户或计划无法访问的模型，这些情况读取起来都不同。传达该消息，而不是假设密钥是错误的，并且永远不要发明密钥。如果确实缺少一个，用户提供它：
jev-cli config set providers.vercel.apiKey <ai-gateway-key>
永远不要打印密钥——config list 会将其屏蔽，除非传递了 --show-secrets。
配置参考
配置位于 ~/.jev-cli/config.yaml（可通过 JEV_CLI_HOME 覆盖目录），权限为 0600。
jev-cli config path # 文件位置
jev-cli config list # 每个值，密钥已屏蔽
jev-cli config get providers.vercel.model
jev-cli config set providers.vercel.model typesafe-ai/jev
jev-cli config unset providers.vercel.baseURL
优先级为 CLI 标志 > 环境变量（JEV_CLI_API_KEY，然后是 AI_GATEWAY_API_KEY）> 配置文件。在 CI 中，设置 JEV_CLI_API_KEY 并完全跳过配置文件。
provider 目前仅接受 vercel（Vercel AI Gateway）。值 jev 保留给 TypeSafe 的官方 API，在实现之前会被拒绝。
进一步了解
- references/question-design.md——如何措辞问题和构建状态，以便答案可用：原子问题、拆分复合判断、单标签与多标签、在三种类型之间选择。
- references/patterns.md——更大问题的架构：推测性扇出、两阶段初选、在分类法和代码库上的层次分类、置信门控路由。
官方文档索引（代理可读）：https://docs.typesafe.ai/llms.txt