use-jev-cli

jev-cli の使用

jev-cli は、「システム 1」評価モデルである Jev に、共有されたステートを一連の型付き質問に対して判断するように依頼します。構造化されたJSON（選択、スコア、または確率）を返し、散文（プローズ）は返しません。

コードが分岐できる判断が必要な場合に使用します。フルLLM呼び出しよりもはるかに高速で低コスト（入力トークンあたりの料金で、出力トークンはゼロ）であるため、差分、ログ、サポートトランスクリプトの10のプロパティをチェックするのも安価です。

書き込み、要約、翻訳、書き換えには使用しないでください。テキストを生成できません。

評価を実行するだけです。最初に実行するセットアップチェックはありません。何か問題がある場合、evalはアクション可能なメッセージと明確な終了コードで即座に失敗し、jev-cli doctorはそのときに使用する診断ツールであり、すべての呼び出しの前に行うものではありません。

評価の実行

jev-cli eval --state <text> --questions <json>

jev-cli eval -s "サポート担当者は\$40の全額返金を発行し、謝罪しました。" -q '{
  "refunded": {"type": "boolean", "instructions": "返金は発行されましたか？"},
  "tone":     {"type": "choice",  "instructions": "担当者はどのような口調を使用しましたか？",
               "criteria": {"warm": "フレンドリーで個人的", "curt": "簡潔または否定的"}},
  "quality":  {"type": "score",   "instructions": "この対応がどれほど適切だったかを評価してください。",
               "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は、実際に自分で作成している短いテキストのためであり、すでにどこかに存在するコンテンツのためではありません。

これは、エージェントが呼び出し元である場合に見た目以上に重要です。

1. インラインコンテンツはトークンごとに生成する必要があります。 50 KBの差分を-sに貼り付けることは、約15kの出力トークンを出力することを意味します。これは出力レートで課金され、生成がシリアルであるため遅く、すでに保持しているコンテンツの再転写であり、暗黙の切り詰めやドリフトを招きます。パスのコストは約10トークンであり、パイプはコンテキストウィンドウからコンテンツを完全に排除します。
2. シェルはインラインコンテンツを書き換え、場合によっては実行します。 二重引用符内では、`cmd`はコマンド置換であり、${VAR}は展開されます。-s "const m = `echo hi`; const p = ${HOME}"を渡すと、モデルにはconst m = hi; const p = /Users/youが送信されます。バッククォートが実行されたのです。信頼できない入力（PRの差分、ユーザーログ）では、これは単なる破損ではなく、コマンド実行の対象となります。一重引用符では、コンテンツ内のアポストロフィがコマンドを完全に破壊します。

サイズが決定要因ではありません。約150 KBはシェルを問題なく通過し、Jev自身の予算が最初に制限されます。コンテンツの安全性とトークンコストが理由です。

# ベスト — コンテンツがモデルコンテキストに入らない
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":"返金されましたか？"}}'

# 間違い — すでに持っているファイルをシェル経由で再転写している
jev-cli eval -s "$(cat huge-diff.txt)" -q ...

一度に1つの入力のみがstdinを読み取れます。両方が大きい場合は、一方をパイプし、もう一方をパスとして渡します。質問ファイルを再出力するのではなく、呼び出し間で再利用します。

ステートがプレーンテキストではなくJSONの場合は、--state-jsonを追加します。

3つの質問タイプ

すべての質問にはinstructionsが必要です。instructionsと各基準の説明は、文字列、JSONオブジェクト、またはJSON配列のいずれかですが、裸の数値やブール値であってはなりません。

タイプ	criteria	回答
boolean	オプション。{"true": ..., "false": ...}、どちらかの側は省略可能	{"type":"boolean","probability":0.98}
choice	必須。 オプション名 → 説明のオブジェクト（nullはなし）	{"type":"choice","choice":"warm","probabilities":{...}}
score	必須。 少なくとも2つのレベルの配列、最低を先頭に	{"type":"score","score":1.83,"probabilities":{...}}

人々がつまずく3つのこと：

• booleanはP(true)を返し、ブール値ではありません。 0.98は、モデルがtrueに98%を置いていることを意味します。これは信頼度でも較正済みでもありません。独自のしきい値を選択してください。0.5は「trueとfalseの可能性が等しい」ことを意味し、「中程度」ではありません。
• scoreは0からcriteria.length - 1までの小数位置です。確率加重平均であり、インデックスではありません。段階的な評価には、booleanではなくこれを使用してください。
• choiceはオプション名をそのまま返します。そのため、コードがスイッチする値としてオプションに名前を付けてください。その確率は合計が1になるため、正確に1つの勝者を選択します。「これらのうちどれが該当するか、複数の可能性がある」場合は、代わりに候補ごとに1つのbooleanを使用してください。

ハード制限

• ステートと質問で約32,000トークンの予算を共有します（英語で約150,000文字）。超過すると{"error_type":"max_tokens_exceeded"}とHTTP 400で失敗します。
• テキストのみ。 ステートは文字列、JSONオブジェクト、またはテキストの配列である必要があります。画像、音声、動画は不可。

したがって、コードベース、完全なログアーカイブ、または大規模なコーパスをJevに渡すことはできません。コンパクトなインデックスまたは抜粋を事前に構築し、それを評価します。その構造化方法については、references/patterns.mdを参照してください。

すべてを1回の呼び出しで尋ねる

質問は並行して独立して評価されます。互いに認識することはありません。バッチ処理はほぼ無料です。TypeSafeでは、1回のリクエストで13の質問を測定したところ、13回の個別リクエストと比較して11.5倍安く、9.6倍高速で、回答は同一でした。彼らのドキュメントでは、コーディングエージェントは人間よりも1回の呼び出しで1つの質問をする習慣に陥りやすいと指摘しています。そうしないでください。

必要になる可能性のあるすべての質問を1回のリクエストで尋ね、使用しないものは破棄してください。最初の回答なしでは構築できない場合にのみ、2番目のリクエストを連鎖させてください。

結果の読み取り

デフォルトの出力は、質問IDをキーとするベアの回答オブジェクトであるため、jqに直接パイプできます。

jev-cli eval --state-file - -q "$CHECKS" | jq -e '.deploy_ok.probability > 0.9' >/dev/null && echo healthy

使用量、警告、およびproviderMetadataを表示するには--fullを追加します。TypeSafeは、choiceおよびscoreの回答に対してconfidenceを報告しますが、これは確率とは別のものです。単一行JSONの場合は--compactを追加します。

終了コードとエラー

evalはエラーをstderrにJSONとして書き込みます（{"error":{"code","message"}}）。stdoutはクリーンに保たれます。常に終了コードで分岐してください。

コード	意味	対処法
0	成功	stdoutを解析
1	プロバイダーまたはネットワーク障害	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             # 上記に加え、1つの小さなライブ評価

コード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 — 回答が使用可能になるように質問を表現し、ステートを構造化する方法：アトミックな質問、複合判断の分割、シングルラベル vs マルチラベル、3つのタイプ間の選択。
• references/patterns.md — より大きな問題のためのアーキテクチャ：投機的ファンアウト、2段階の一次選考、分類体系とコードベースに対する階層的分類、信頼度ゲート付きルーティング。

公式ドキュメントインデックス（エージェント読み取り可能）：https://docs.typesafe.ai/llms.txt