使用 jev-cli
jev-cli 要求Jev，一個「System One」評估模型，根據一組帶有型別的問題來評判一個共享的狀態。它會回傳結構化的 JSON — 一個選擇、一個分數或一個機率 — 絕不產生散文。
當你需要一個你的程式碼可以根據其進行分支的決策時，就使用它。它比完整的 LLM 呼叫要快得多且便宜得多（按輸入 token 計費，輸出 token 為零），因此檢查一個 diff、一個日誌或一個支援對話記錄的十個屬性是很便宜的。
不要用它來撰寫、摘要、翻譯或改寫任何東西。它無法產生文字。
只需執行評估。無需事先進行設定檢查 — 當出現問題時，eval 會快速失敗並附上可操作的訊息和不同的 exit code，而 jev-cli doctor 是你在那時才需要使用的診斷工具，而不是在每次呼叫之前。
執行評估
jev-cli eval --state <text> --questions <json>
jev-cli eval -s "The support agent issued a full refund of \$40 and apologized." -q '{
"refunded": {"type": "boolean", "instructions": "Was a refund issued?"},
"tone": {"type": "choice", "instructions": "What tone did the agent use?",
"criteria": {"warm": "friendly and personal", "curt": "terse or dismissive"}},
"quality": {"type": "score", "instructions": "Rate how well this was handled.",
"criteria": ["poor", "acceptable", "excellent"]}
}'
{
"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 適用於你真正在撰寫的短文，而不是已經存在的內容。
當呼叫者是 agent 時，這比看起來更重要：
- 內聯內容必須逐 token 產生。 將一個 50 KB 的 diff 貼入
-s意味著發射約 15k 個輸出 token — 按輸出費率計費，由於產生是序列化的而速度慢，並且是對你已有內容的重新轉錄，這會引發靜默截斷和漂移。一個路徑花費約 10 個 token，而管道則完全將內容保留在你的上下文窗口之外。 - Shell 會重新改寫內聯內容，有時是透過執行它。 在雙引號中，
`cmd`是命令替換，${VAR}會擴展。傳遞-s "const m = `echo hi`; const p = ${HOME}"會向模型發送const m = hi; const p = /Users/you— 反引號執行了。對於不受信任的輸入（一個 PR diff、一個用戶日誌），這是一個命令執行攻擊面，而不僅僅是資料損壞。在單引號中，內容中的一個撇號會直接破壞命令。
大小不是決定因素：約 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 "The agent issued a full refund." -q '{"r":{"type":"boolean","instructions":"Refunded?"}}'
# 錯誤 — 重新轉錄你已有的檔案，透過 shell
jev-cli eval -s "$(cat huge-diff.txt)" -q ...
只有一個輸入可以讀取 stdin。當兩者都很大時，將其中一個透過管道傳遞，另一個作為路徑傳遞。跨呼叫重複使用 questions 檔案，而不是重新發出它。
當狀態是 JSON 而非純文字時，加上 --state-json。
三種問題型別
每個問題都需要 instructions。instructions 和每個 criteria 描述可以是字串、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% 的機率認為是 true。這不是信心水準，也未經校正 — 請自行選擇閾值。0.5表示「真或假的可能性相同」，不是「中等」。score是一個分數位置，範圍從0到criteria.length - 1— 這是機率加權平均值，不是索引。對於漸進等級，請使用它，而不是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 倍，且答案相同。他們的文件指出，編碼 agent 比人類更容易陷入每次呼叫一個問題的習慣 — 不要這樣做。
在一次請求中詢問你可能需要的所有內容，並丟棄你不使用的部分。只有當你確實無法在沒有第一個答案的情況下建構第二個請求時，才鏈接第二個請求。
讀取結果
預設輸出是純粹的答案物件，以你的問題 ID 為鍵，因此可以直接透過管道傳入 jq：
jev-cli eval --state-file - -q "$CHECKS" | jq -e '.deploy_ok.probability > 0.9' >/dev/null && echo healthy
加上 --full 以取得使用情況、警告和 providerMetadata — TypeSafe 在其中報告 choice 和 score 答案的 confidence，這與機率是分開的。加上 --compact 以取得單行 JSON。
Exit code 與錯誤
eval 會將錯誤寫入 stderr 為 JSON（{"error":{"code","message"}}），保持 stdout 乾淨。務必根據 exit code 進行分支：
| 代碼 | 含義 | 處理方式 |
|---|---|---|
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 — 針對更大問題的架構：推測性扇出、兩階段篩選、基於分類法和程式碼庫的分層分類、信心門控路由。
官方文件索引（agent 可讀取）：https://docs.typesafe.ai/llms.txt