use-jev-cli

Verwendung von jev-cli

jev-cli fordert Jev, ein "System One"-Evaluierungsmodell, auf, einen gemeinsamen Zustand anhand eines Satzes typisierter Fragen zu beurteilen. Es gibt strukturiertes JSON zurück – eine Auswahl, eine Bewertung oder eine Wahrscheinlichkeit – niemals Prosa.

Greifen Sie darauf zurück, wenn Sie eine Entscheidung benötigen, von der Ihr Code abzweigen kann. Es ist weitaus schneller und günstiger als ein vollständiger LLM-Aufruf (abgerechnet pro Eingabe-Token, ohne Ausgabe-Token), daher ist die Überprüfung von zehn Eigenschaften eines Diffs, eines Logs oder eines Support-Transkripts günstig.

Verwenden Sie es nicht, um etwas zu schreiben, zusammenzufassen, zu übersetzen oder umzuschreiben. Es kann keinen Text erzeugen.

Führen Sie einfach die Evaluierung durch. Es ist keine vorherige Einrichtungsprüfung erforderlich – eval scheitert schnell mit einer umsetzbaren Nachricht und einem eindeutigen Exit-Code, wenn etwas nicht stimmt, und jev-cli doctor ist das Diagnosewerkzeug, das Sie dann verwenden, nicht vor jedem Aufruf.

Durchführen einer Evaluierung

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

jev-cli eval -s "Der Support-Mitarbeiter hat eine vollständige Rückerstattung von 40 $ gewährt und sich entschuldigt." -q '{
  "refunded": {"type": "boolean", "instructions": "Wurde eine Rückerstattung gewährt?"},
  "tone":     {"type": "choice",  "instructions": "Welchen Ton hat der Mitarbeiter verwendet?",
               "criteria": {"warm": "freundlich und persönlich", "curt": "kurz angebunden oder abweisend"}},
  "quality":  {"type": "score",   "instructions": "Bewerten Sie, wie gut dies gehandhabt wurde.",
               "criteria": ["schlecht", "akzeptabel", "ausgezeichnet"]}
}'

{
  "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 } }
}

Diese Inline-Form ist für einen Satz geeignet, den Sie selbst schreiben. Für alles, was bereits in einer Datei oder in der Ausgabe eines Befehls existiert, lesen Sie als Nächstes Eingabe übergeben – es ist das, was die meisten Aufrufer falsch machen.

Eingabe übergeben: Inhalt aus der Befehlszeile heraushalten

Verwenden Sie standardmäßig --state-file / --questions-file oder eine Pipe in -. Inline -s / -q ist für kurzen Text gedacht, den Sie tatsächlich verfassen, nicht für Inhalt, der bereits irgendwo existiert.

Dies ist wichtiger, wenn ein Agent der Aufrufer ist, als es scheint:

1. Inline-Inhalt muss Token für Token generiert werden. Das Einfügen eines 50 KB großen Diffs in -s bedeutet, ~15k Ausgabe-Token zu emittieren – zu Ausgabepreisen abgerechnet, langsam, weil die Generierung seriell ist, und eine erneute Transkription von Inhalt, den Sie bereits haben, was zu stiller Kürzung und Drift führt. Ein Pfad kostet ~10 Token, und eine Pipe hält den Inhalt vollständig aus Ihrem Kontextfenster heraus.
2. Die Shell schreibt Inline-Inhalt um, manchmal indem sie ihn ausführt. In doppelten Anführungszeichen ist `cmd` eine Befehlsersetzung und ${VAR} wird expandiert. Das Übergeben von -s "const m = `echo hi`; const p = ${HOME}" sendet an das Modell const m = hi; const p = /Users/you – der Backtick wurde ausgeführt. Bei nicht vertrauenswürdiger Eingabe (ein PR-Diff, ein Benutzer-Log) ist dies eine Befehlsausführungsoberfläche, nicht nur eine Beschädigung. In einfachen Anführungszeichen bricht ein Apostroph im Inhalt den Befehl vollständig.

Die Größe ist nicht der entscheidende Faktor: ~150 KB werden von der Shell problemlos verarbeitet, und Jevs eigenes Budget ist zuerst bindend. Die Sicherheit des Inhalts und die Token-Kosten sind die Gründe.

# Am besten – Inhalt gelangt nie in den Modellkontext
git diff | jev-cli eval --state-file - --questions-file ./checks.json

# Gut – mit einem Befehl vorbereiten, Pfade übergeben
git log -20 --oneline > /tmp/state.txt
jev-cli eval --state-file /tmp/state.txt --questions-file ./checks.json

# In Ordnung – kurzer Text, den Sie tatsächlich schreiben
jev-cli eval -s "Der Mitarbeiter hat eine vollständige Rückerstattung gewährt." -q '{"r":{"type":"boolean","instructions":"Rückerstattet?"}}'

# Falsch – erneute Transkription einer Datei, die Sie bereits haben, durch die Shell
jev-cli eval -s "$(cat huge-diff.txt)" -q ...

Nur eine Eingabe kann stdin lesen. Wenn beide groß sind, pipen Sie eine und übergeben Sie die andere als Pfad. Verwenden Sie eine Fragenliste über mehrere Aufrufe hinweg wieder, anstatt sie erneut auszugeben.

Fügen Sie --state-json hinzu, wenn der Zustand JSON und nicht Klartext ist.

Die drei Fragetypen

Jede Frage benötigt instructions. instructions und jede Kriterienbeschreibung können ein String, ein JSON-Objekt oder ein JSON-Array sein – aber niemals eine bloße Zahl oder boolescher Wert.

Typ	criteria	Antwort
boolean	Optional {"true": ..., "false": ...}, jede Seite weglassbar	{"type":"boolean","probability":0.98}
choice	Erforderlich. Objekt von Optionsname → Beschreibung (null für keine)	{"type":"choice","choice":"warm","probabilities":{...}}
score	Erforderlich. Array von mindestens zwei Stufen, niedrigste zuerst	{"type":"score","score":1.83,"probabilities":{...}}

Drei Dinge, die Leute stolpern lassen:

• boolean gibt P(wahr), keinen booleschen Wert. 0.98 bedeutet, dass das Modell zu 98 % auf wahr setzt. Es ist keine Konfidenz und nicht kalibriert – wählen Sie Ihren eigenen Schwellenwert. 0.5 bedeutet "gleich wahrscheinlich wahr oder falsch", nicht "mittel".
• score ist eine gebrochene Position von 0 bis criteria.length - 1 – der wahrscheinlichkeitsgewichtete Mittelwert, kein Index. Verwenden Sie es, nicht boolean, für Abstufungen.
• choice gibt den Optionsnamen wörtlich zurück, benennen Sie also Optionen als die Werte, auf die Ihr Code umschalten wird. Seine Wahrscheinlichkeiten summieren sich zu 1, sodass es genau einen Gewinner auswählt – für "welche davon treffen zu, möglicherweise mehrere", verwenden Sie stattdessen ein boolean pro Kandidat.

Harte Grenzen

• Zustand und Fragen teilen sich ein Budget von ~32.000 Token (~150.000 Zeichen Englisch). Eine Überschreitung schlägt fehl mit {"error_type":"max_tokens_exceeded"} und HTTP 400.
• Nur Text. Der Zustand muss ein String, ein JSON-Objekt oder ein Array von Text sein. Keine Bilder, Audio oder Video.

Sie können Jev daher keine Codebasis, ein vollständiges Log-Archiv oder ein großes Korpus übergeben. Erstellen Sie vorab einen kompakten Index oder Auszug und werten Sie diesen aus. Siehe references/patterns.md für Informationen zur Strukturierung.

Alles in einem Aufruf fragen

Fragen werden parallel und isoliert ausgewertet – sie sehen sich nie gegenseitig. Das Bündeln ist fast kostenlos: TypeSafe misst 13 Fragen in einer Anfrage als 11,5x günstiger und 9,6x schneller als 13 separate Anfragen, mit identischen Antworten. Die Dokumentation stellt fest, dass Coding-Agenten mehr in die Gewohnheit verfallen, eine Frage pro Aufruf zu stellen als Menschen – tun Sie das nicht.

Fragen Sie alles, was Sie brauchen könnten, in einer einzigen Anfrage und verwerfen Sie, was Sie nicht verwenden. Verketten Sie eine zweite Anfrage nur, wenn Sie sie ohne die erste Antwort nicht erstellen können.

Lesen des Ergebnisses

Die Standardausgabe ist das reine Antwortobjekt, das nach Ihren Frage-IDs benannt ist, sodass es direkt in jq gepiped werden kann:

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

Fügen Sie --full für Nutzung, Warnungen und providerMetadata hinzu – wo TypeSafe confidence für Auswahl- und Bewertungsantworten meldet, was getrennt von den Wahrscheinlichkeiten ist. Fügen Sie --compact für einzeiliges JSON hinzu.

Exit-Codes und Fehler

eval schreibt Fehler nach stderr als JSON ({"error":{"code","message"}}), wobei stdout sauber bleibt. Verzweigen Sie immer basierend auf dem Exit-Code:

Code	Bedeutung	Was zu tun ist
0	Erfolg	stdout parsen
1	Provider- oder Netzwerkfehler	Einmal wiederholen; falls bestehend melden
2	Falsche Verwendung oder ungültige Fragen	JSON korrigieren – die Nachricht nennt die fehlerhafte Frage-ID und das Feld
3	Fehlende oder abgelehnte Anmeldeinformationen	Nachricht an den Benutzer weiterleiten; nicht wiederholen. Siehe unten

Eine Nachricht mit Code 2 wie questions.quality.criteria must list at least two ordered levels, but got 1 zeigt den genauen zu korrigierenden Pfad.

Diagnose eines Fehlers

Nur wenn ein Aufruf tatsächlich fehlschlägt, und nur für Codes 1 und 3:

jev-cli doctor --offline   # Konfiguration, Provider, Modell, Schlüsselquelle – kein Netzwerkaufruf
jev-cli doctor             # das Obige, plus eine winzige Live-Evaluierung

Code 3 enthält die eigenen Worte des Providers, und sie unterscheiden Fälle, die unterschiedliche Korrekturen benötigen – ein fehlender Schlüssel, ein widerrufener Schlüssel, ein Konto ohne eingerichtete Abrechnung oder ein Modell, das der Tarif nicht erreichen kann, lesen sich alle anders. Leiten Sie diese Nachricht weiter, anstatt anzunehmen, dass der Schlüssel falsch ist, und erfinden Sie niemals einen Schlüssel. Wenn einer tatsächlich fehlt, stellt der Benutzer ihn bereit:

jev-cli config set providers.vercel.apiKey <ai-gateway-key>

Geben Sie niemals einen Schlüssel zurück – config list maskiert sie, es sei denn, --show-secrets wird übergeben.

Konfigurationsreferenz

Die Konfiguration befindet sich in ~/.jev-cli/config.yaml (überschreiben Sie das Verzeichnis mit JEV_CLI_HOME), geschrieben 0600.

jev-cli config path                       # wo die Datei ist
jev-cli config list                       # alle Werte, Schlüssel maskiert
jev-cli config get providers.vercel.model
jev-cli config set providers.vercel.model typesafe-ai/jev
jev-cli config unset providers.vercel.baseURL

Die Rangfolge ist CLI-Flag > Umgebung (JEV_CLI_API_KEY, dann AI_GATEWAY_API_KEY) > Konfigurationsdatei. Setzen Sie in CI JEV_CLI_API_KEY und überspringen Sie die Konfigurationsdatei vollständig.

provider akzeptiert derzeit nur vercel (Vercel AI Gateway). Der Wert jev ist für die offizielle API von TypeSafe reserviert und wird zurückgewiesen, bis er implementiert ist.

Weiterführendes

• references/question-design.md – wie man Fragen formuliert und den Zustand strukturiert, damit die Antworten nutzbar sind: atomare Fragen, Aufteilen zusammengesetzter Urteile, Einzel- vs. Mehrfachlabel, Auswahl zwischen den drei Typen.
• references/patterns.md – Architekturen für größere Probleme: spekulative Verzweigung, zweistufige Vorauswahl, hierarchische Klassifikation über Taxonomien und Codebasen, konfidenzgesteuertes Routing.

Offizielles Docs-Index (agentenlesbar): https://docs.typesafe.ai/llms.txt