Kommandozeilenreferenz

Aufruf

probe init [--repo PATH] [--language go|typescript|javascript|python|rust]
probe lint [--base main] [--head HEAD] [--ci] [flags]
probe review [--base main] [--reviewer=false] [--ci] [flags]
probe review [flags] BASE..HEAD
probe plan --intent-file FILE [--base main] [--ci]
probe review --plan .probe/PLAN.json [flags]
probe report [--input .probe/confidence-report.json] [--out DIR] [--format LIST] [--report-url URL]
probe version

• lint analysiert eine Änderung statisch. Es führt niemals Code aus dem Repository aus und ruft niemals einen KI-Anbieter auf.
• review ergänzt Prüfungen in einer Docker-Sandbox, die optionalen Nachweisstufen (geänderte Baseline-Tests, betroffene Tests, differenzielles Fuzzing, Mutation, Vorbereitung der Abhängigkeiten) und, wenn ein Modell konfiguriert ist, eine KI-Untersuchung.
• plan fordert beim konfigurierten Anbieter einen Implementierungsplan an, bevor Code geschrieben wird, bewertet ihn mit festen Regeln und macht daraus einen Vertrag, gegen den lint --plan und review --plan den Diff prüfen.
• Nur committete Dateien werden analysiert; nicht committete Änderungen und nicht versionierte Dateien werden ignoriert.
• Berichte werden standardmäßig nach .probe/ im Repository geschrieben. Die Konsolenausgabe bleibt kurz.
• Flags akzeptieren einen oder zwei Bindestriche (-ci oder --ci). Boolesche Werte werden mit --ci oder --ci=true gesetzt und mit --checks=false zurückgesetzt. Ein Wert wird als --base main oder --base=main angegeben.
• Führen Sie probe <command> --help aus, um die Flags eines Befehls zu sehen.

Revisionen wählen

Beide Seiten eines Vergleichs werden zu unveränderlichen Commit-IDs aufgelöst, die im Bericht festgehalten werden. Umbenennungen, Löschungen, Binärdateien und Änderungen des Dateityps werden berücksichtigt.

Ein Bereich kann vor oder nach den Flags stehen: probe review main..HEAD --ci und probe review --ci main..HEAD sind gleichwertig. Es wird höchstens ein Bereich akzeptiert. Jede Revision, die Git versteht, funktioniert: Branches, Tags, origin/main, HEAD~3 oder eine Commit-ID. CI-Jobs benötigen genügend Historie, um die Basis aufzulösen (zum Beispiel fetch-depth: 0).

Die vertrauenswürdige Policy wird immer aus dem Basis-Branch gelesen, niemals aus der zu prüfenden Änderung, sodass ein Pull Request seine eigenen Regeln nicht lockern kann.

probe lint

Statische Analyse einer Änderung: Git-Vergleich, Risikosignale und ein Bericht. Kein Docker, kein Anbieteraufruf, keine Ausführung von Repository-Code. Unbedenklich auf nicht vertrauenswürdigen Branches.

probe lint HEAD~1..HEAD                 # the last commit
probe lint --base origin/main --ci      # this branch as a pull request, for CI
probe lint --base main --format json    # JSON report only
probe lint --base main --plan .probe/PLAN.json   # scope drift against an approved plan

probe review

Alles, was lint tut, plus die Befehle test, typecheck, build und coverage der Policy in Wegwerf-Docker-Containern, plus eine KI-Untersuchung, wenn ein Modell konfiguriert ist. Erfordert Docker mit Linux-Containern und ein vorab geladenes sandbox.image.

probe review --base main --ci                        # typical pull request run
probe review HEAD~1..HEAD --reviewer=false           # checks only, no provider
probe review --base main --checks=false --reviewer=false   # static only, like lint
probe review --base main --intent-file PR.md         # give acceptance criteria
probe review --base main --impacted-tests --base-tests --ci   # run tests on both revisions
probe review --base main --format markdown,json,sarif,pr-comment --report-url "$RUN_URL"

Die Vorbereitung der Abhängigkeiten läuft zuerst, wenn die Policy ein prepare-Objekt enthält. Danach laufen die Prüfungen in der Reihenfolge test, typecheck, build, dann coverage, gefolgt von den Nachweisstufen und dem Reviewer. Jeder Container läuft ohne Root, mit schreibgeschütztem Root-Dateisystem und Quellcode-Mount, ohne zusätzliche Capabilities, standardmäßig ohne Netzwerk und mit den CPU-, Speicher-, PID- und Zeitlimits der Sandbox-Policy. Der Docker-Socket, Ihr Arbeits-Checkout und API-Schlüssel werden niemals eingebunden. Fehlen Docker oder das Image, endet der Lauf mit Exit-Code 4; es gibt nie ein Ausweichen auf Ihren Host.

probe plan

Bevor die Änderung geschrieben wird: Der konfigurierte Anbieter simuliert schreibgeschützt, wie er einen Intent auf dem Basis-Commit umsetzen würde, und reicht einen strukturierten Plan ein (Dateien, Symbole, Abhängigkeiten, Schritte). Probe bewertet ihn mit festen Regeln und schreibt PLAN.json und PLAN.md. Das Modell erstellt den Plan; es beurteilt nie dessen Risiko. Nichts wird verändert oder ausgeführt.

Die Werkzeuge des Planers sind schreibgeschützt und arbeiten auf einem Snapshot des Basis-Commits: list_files, read_file, search_code und die indexgestützten find_references, inspect_symbol und find_callers, dann einmal submit_plan. Die Bewertung markiert vier Kategorien, allein anhand des Plans und des Basis-Commits:

Exit-Codes: 0; 2 mit --ci, wenn eine Kategorie markiert ist; 3 Bedienung oder Konfiguration; 4 Anbieterfehler oder kein akzeptierter Plan.

Abweichung vom Umfang: --plan

lint --plan und review --plan lesen den Vertrag des Plans und vergleichen den tatsächlichen Diff damit. Jede Abweichung im Diff wird außerdem zu einem plan_drift-Signal. Der Abschnitt ist drifted, wenn ein Eintrag mittel oder höher ist.

probe plan --intent-file task.md --ci                     # 1. plan; exit 2: a human validates it
# 2. an agent implements the plan
probe review --base origin/main --plan .probe/PLAN.json --ci   # 3-4. exit 0: merge; exit 2: review

Das Plan-Gate

review --plan endet mit einer Entscheidung, plan_drift.decision, die auf stdout und oben im Abschnitt „Plan Conformance“ ausgegeben wird. Mit --ci ist sie der Exit-Code.

Den in PLAN.json gespeicherten Flags und dem Vertrag wird nie vertraut: Der Vertrag wird aus dem Vorschlag neu abgeleitet, sodass ein bearbeiteter Plan den Umfang nicht unbewertet erweitern kann, und probe report berechnet die Entscheidung aus dem gespeicherten Bericht neu. Das Gate ist eine Prozessentscheidung, kein Urteil über die Korrektheit. Ein Plan, der nichts meldet, beweist nicht, dass die Änderung sicher ist, und die Abweichungsprüfung kontrolliert nicht, ob die Änderung den Intent umsetzt. Siehe Pläne vor der Änderung und das CI-Rezept.

probe init

Eine erste .probe.json für das Projekt schreiben. Eine vorhandene Datei wird nicht überschrieben. Prüfen Sie die Befehle und das Image und committen Sie die Datei dann in Ihren Basis-Branch.

probe report

Einen gespeicherten JSON-Bericht neu ausgeben, zum Beispiel um Markdown neu zu erzeugen oder in der CI SARIF zu erstellen. Nichts wird erneut ausgeführt, und die Neuausgabe authentifiziert die enthaltenen Nachweise nicht; jeder Status wird aus den aufgezeichneten Prüfungen neu abgeleitet, sodass ein bearbeiteter Bericht korrigiert statt übernommen wird.

probe version und Hilfe

Exit-Codes

Kein Code bedeutet „freigegeben“. Eine 0 besagt, dass nichts reproduziert wurde, nicht, dass die Änderung korrekt ist.

Umgebungsvariablen

Der KI-Anbieter gehört zur Bereitstellung, nicht zum Repository, daher können diese Einstellungen aus der Umgebung kommen. Sonst nichts: Image, Befehle, Budgets und sensible Pfade werden immer von der vertrauenswürdigen Policy bestimmt.

Eine leere Variable gilt als nicht gesetzt. Schlüsseldateien werden vollständig gelesen, umgebende Leerzeichen entfernt, sie sind auf 8 KiB begrenzt und müssen eine einzige Zeile enthalten. Wenn der Reviewer läuft, nennt das Protokoll die Herkunft jedes Werts, nie den Wert selbst. Wer diese Umgebung kontrolliert, bestimmt, wohin geschwärzter Quellcode gesendet wird: Halten Sie sie aus Jobs heraus, die nicht vertrauenswürdigen Code aus Forks ausführen.

Ausgabedateien

Fügen Sie .probe/ zu .gitignore hinzu. Die Konsole gibt eine Zusammenfassung aus: geänderte Dateien und Zeilen, Anzahl der Signale und reproduzierten Probleme, den fokussierten Review-Umfang und die Ausführung der geänderten Zeilen.

Risikosignale

Signale sind Gründe, genauer hinzusehen, keine bestätigten Defekte. Go-Dateien werden syntaxbewusst analysiert; TypeScript/JavaScript, Python, Rust und andere Sprachen nutzen gekennzeichnete Textheuristiken. Signale auf denselben Zeilen werden im Bericht zu einem Review-Bereich zusammengefasst. Signale auf Dateiebene (sensitive_path, dependency_change, migration_change, infrastructure_change, binary_change, file_deleted, file_type_change, large_change, branch_growth, no_test_change, prepare_input_changed, plan_drift) betreffen die Datei, nicht eine Zeile: Der Bericht führt sie unter der Datei als ganze Datei auf, und das JSON kennzeichnet sie mit "scope": "file". Ihre line verortet sie nur auf der ersten geänderten Zeile der Datei.

Auswirkungsanalyse

Mit --impact (Standard) erstellen lint und review auf dem Host einen statischen Index des Kandidaten-Commits aus committeten Git-Objekten, ohne Repository-Code auszuführen. Für jede geänderte Funktion listet er die Stellen in unverändertem Code, die sie aufrufen, und die vorhandenen Tests, die sie innerhalb von 3 Aufrufen erreichen, fügt niedrige impacted_caller-Signale hinzu und speist die Werkzeuge find_references, inspect_symbol und find_callers des Reviewers.

Jede Antwort ist eine Näherung: Ein aufgeführter Aufrufer ist eine Stelle zum Prüfen, und ein fehlender Aufrufer beweist nicht, dass es keinen gibt. --impacted-tests führt nur erreichende Go-Tests aus. Siehe Auswirkungsanalyse.

Sprachen

Policy-Datei: .probe.json

Die Policy bestimmt, welche Befehle in welchem Image mit welchen Limits laufen und ob ein KI-Anbieter verwendet wird. Sie wird aus .probe.json im Basis-Branch gelesen oder aus --config PATH. Gibt es keine, gelten die eingebauten Standardwerte für die erkannte Sprache. Weggelassene Schlüssel erhalten die unten gezeigten Standardwerte.

Die Datei muss ein einzelnes JSON-Objekt von höchstens 1 MiB sein. Unbekannte Schlüssel, unbekannte Befehlsnamen und doppelte Schlüssel werden mit Exit-Code 3 abgelehnt, sodass ein älteres Binary einen Schlüssel ablehnt, den es nicht kennt.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "PROBE_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".probe.json"]
}

commands

Jeder Befehl ist ein argv-Array, kein Shell-String: ["npm", "test"], niemals "npm test". Höchstens 128 Argumente; konfigurieren Sie nur die Prüfungen, die Ihr Projekt bietet.

sandbox

reviewer

sensitive_paths

Globs von Pfaden, die bei einer Änderung immer ein hohes sensitive_path-Signal auslösen. Pfade sind relativ zum Repository-Stamm und verwenden Schrägstriche; * passt innerhalb eines Pfadsegments, ** über Segmente hinweg. Absolute Pfade, Backslashes und .. werden abgelehnt.

fuzz v0.4

Schickt dieselben Seed-Eingaben durch jede geänderte Go-Funktion auf Paketebene und jede geänderte exportierte TS/JS-Funktion (mit unveränderter Signatur), auf Baseline und Kandidat, und vergleicht, was die beiden Revisionen aufgezeichnet haben. Eine Funktion mit diverged ist eine Beobachtung, nie ein Defekt: Sie fordert ein Review an (Exit-Code 2 mit --ci) und erzeugt nie Exit-Code 1. {} aktiviert es mit den Standardwerten.

mutation v0.4

Nimmt kleine deterministische Änderungen an den hinzugefügten Zeilen geänderter Go-Dateien (ohne Tests) vor und führt die Tests des Pakets einmal pro Mutante aus. Eine Mutante, die kein Test bemerkt, wird zu einem mittleren surviving_mutant-Signal; es wird kein Score berechnet. Alle vier Schlüssel sind erforderlich.

"mutation": {
  "command": ["go", "test", "-json", "-count=1", "-failfast", "{package}"],
  "max_mutants": 20, "timeout_seconds": 60, "max_runtime_seconds": 300
}

prepare v0.4

Lässt die vertrauenswürdige Policy des Basis-Branches die Abhängigkeitsschicht bauen: Bevor Kandidaten-Code läuft, wird ihr Befehl einmal in einem begrenzten Container auf den aus dem Basis-Commit exportierten Abhängigkeitsdateien ausgeführt, und der Container wird zum lokalen Image jeder Prüfung. Ein späteres Review mit derselben Basis und denselben Eingaben verwendet es wieder. Entsteht kein Image, endet das Review mit Exit-Code 4; es weicht nie auf das unvorbereitete Image aus.

"prepare": { "command": ["go", "mod", "download"], "inputs": ["go.mod", "go.sum"], "network": true }

Standardwerte je Sprache

Von probe init geschrieben und verwendet, wenn der Basis-Branch keine Policy hat. Die Standard-Images für Node.js, Python und Rust enthalten Ihre Abhängigkeiten nicht: Bauen Sie ein Image, das sie enthält, oder fügen Sie ein prepare-Objekt hinzu, und passen Sie die Befehle an.

KI-Reviewer

Optional. Wenn ein Modell konfiguriert ist, lässt review es die Änderung mit begrenzten Werkzeugen untersuchen: geschwärzte Dateien und Diffs lesen, Quellcode durchsuchen, Referenzen und Aufrufer im statischen Index nachschlagen, vorhandene Prüfungen ausführen sowie temporäre Tests auf Basis und Kandidat anlegen und ausführen. Es hat keine Shell und keinen URL-Abruf. Seine Aussagen bleiben Hypothesen, bis ein Test einen Unterschied reproduziert.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "PROBE_API_KEY"
  }
}

export PROBE_API_KEY=…                       # from your shell or CI secret store
probe review --base main --config .probe.json   # try it before committing
probe review --base main --reviewer=false            # turn it off for one run

• Nur die vertrauenswürdige Policy, --config oder die Umgebung der Bereitstellung können den Reviewer aktivieren; ein Pull Request kann es nicht.
• Begrenzter, geschwärzter Quellcode-Kontext wird an den Anbieter gesendet. Das Maskieren von Secrets erfolgt nach bestem Bemühen; verwenden Sie einen lokalen Anbieter (zum Beispiel http://127.0.0.1:1234/v1), wenn der Quellcode lokal bleiben muss.
• API-Schlüssel gelangen nie in Test-Container. lint ruft nie einen Anbieter auf.
• Bei Anbieterfehlern und erschöpften Budgets bleiben die deterministischen Ergebnisse erhalten, und die Untersuchung wird als unvollständig markiert; mit --ci erfordert das ein menschliches Review.