maxgfr/ultradoc

ultradoc — Antworten aus der Quelle, nicht aus dem Gedächtnis

ultradoc beantwortet ultrapräzise Fragen zu einem Open-Source-Projekt, indem es fundierte Beweise abruft und darüber nachdenkt. Die deterministische Engine (scripts/ultradoc.mjs, kein externes Abhängigkeitsmanagement) erledigt die Suche und Indizierung mit Code; Ihre Aufgabe ist es, die abgerufenen Beweise zu lesen und eine präzise, zitierte Antwort zu schreiben. Jede Behauptung muss auf eine echte Quelle verweisen. Das wird durchgesetzt: ultradoc check schlägt fehl, wenn ein Zitat nicht zu abgerufenen Beweisen aufgelöst werden kann.

Die Kernregel: Antworten Sie nicht aus Ihrem eigenen Wissen über die Bibliothek. Ihre Trainingsdaten sind veraltet und halluzinieren APIs. Antworten Sie nur aus den Beweisen, die ultradoc aus dem tatsächlichen Repository, Issues, PRs, Docs und dem Web abruft. Wenn die Beweise es nicht abdecken, sagen Sie das und rufen Sie weitere ab – raten Sie nie.

Das Skript

Ein gebündeltes, abhängigkeitsfreies Bündel: node scripts/ultradoc.mjs <Befehl>. Kein npm install, keine API-Keys. Führen Sie --help für die volle Oberfläche aus. Wichtige Befehle:

• ask --repo <URL|Pfad> --q "<Frage>" [--sources ...] [--package <p>] [--semantic] [--docs-url <u>] Klonen (beliebige Git-URL, zwischengespeichert in /tmp/ultradoc/<slug>), indizieren, aus allen ausgewählten Quellen abrufen und ein Beweisdossier (EVIDENCE.md, evidence.json, meta.json) in einen Ausführungsordner schreiben – dauerhaft neben dem Klon unter <clone>/.ultradoc/runs/<id> (ein stabiles, auf einen Commit festgelegtes Zuhause, das über mehrere Fragen hinweg wiederverwendet wird), es sei denn, Sie übergeben --out. Standardquellen: code,issues,prs,docs (fügen Sie web,so hinzu, wenn das Repository allein die Frage nicht beantwortet; fügen Sie releases,history für „Wann wurde X hinzugefügt/geändert“-Fragen und discussions für Community-F&A hinzu – benötigt die gh CLI). In einem Monorepo schränkt --package <Name|Verzeichnis> den Code-/Dokumentationsabruf auf ein Arbeitsbereichspaket ein.
• code|issues|prs|docs|releases|history|discussions|so --repo <...> --q "..." – in EINE Quelle eintauchen, Beweise auf der Standardausgabe ausgeben (kein Dossier). Verwenden Sie diese, um einen dünnen Bereich zu erweitern. history führt Git-Pickaxe (log -S/-G) auf dem Klon aus – der erste Aufruf bei einem entfernten Repository ruft die vollständige Historie einmal ab.
• web --repo <...> [--q "..."] [--url <u,...>] – schlüssellose Web-Entdeckung (SearXNG → DuckDuckGo → Ihre WebSearch) + Abruf/Extraktion. Übergeben Sie --url, um eine bestimmte Seite zu untermauern, die Sie mit Ihrer eigenen WebSearch gefunden haben.
• overview --repo <...> [--refresh] – einmalig eine zwischengespeicherte Markdown-Übersicht des Repositorys generieren: was es ist, seine Arbeitsbereichspakete, Layout, öffentliche API und Dokumentationskarte. Neben dem Klon zwischengespeichert und wiederverwendet, solange der Commit unverändert ist – lesen Sie es, um sich ohne erneute Indizierung über mehrere Fragen hinweg zu orientieren. Es ist eine Navigationskarte, KEINE zitierfähigen Beweise.
• doc --repo <...> [--package <p>] [--sources ...] – ein fundiertes Referenzdokument erstellen: eine deterministische Abschnittsgliederung (Überblick, Installation, öffentliche API/pro Paket, Konfiguration, Architektur), ein abgerufenes Dossier pro Abschnitt, zusammengeführt in einer einzigen evidence.json, und eine DOC.todo.md-Arbeitsliste. Sie schreiben die zitierte Prosa in DOC.md; check validiert sie wie eine Antwort. Dauerhaft unter <clone>/.ultradoc/doc/ gespeichert. Siehe „Dokumentation generieren“ unten.
• check --run <Dossier-Verzeichnis> – die Zitate von ANSWER.md (oder einer doc-Ausführung DOC.md) gegen das evidence.json des Dossiers validieren. Exit-Code ungleich Null ⇒ nicht fundiert. --answer <Datei> validiert eine bestimmte Datei.
• index --repo <...> – den Strukturindex erstellen/ausgeben (Debugging/Inspektion); listet entdeckte Arbeitsbereichspakete für ein Monorepo auf.
• semantic up|down|status – optionales lokales Vektor-Backend (siehe unten).

Arbeitsablauf

Sie besitzen diese Aufgabe von Anfang bis Ende: geben Sie eine fundierte, zitierte Antwort zurück und geben Sie niemals ein halb abgerufenes Dossier zurück. Aber die Abruf- und Verifizierungsarbeit besteht aus einer Reihe unabhängiger, nahezu kostenloser Aufrufe – parallelisieren Sie sie, wenn Ihre Umgebung es kann (bündeln Sie die unabhängigen Bohrungen in einer Nachricht; verteilen Sie sie an Unteragenten oder einen Workflow, falls verfügbar) und führen Sie sie andernfalls inline aus. Iterieren Sie in Runden, bis die Beweise vollständig sind; kehren Sie nicht eher zurück, bis sie es sind. Siehe references/orchestration.md.

1. Ziel auflösen. Identifizieren Sie das Projekt und die genaue Frage. Wenn Sie nur einen Namen haben, finden Sie die kanonische Repository-URL (verwenden Sie Ihre WebSearch oder fragen Sie den Benutzer bei Unklarheit). Notieren Sie sich die Version/den Branch, die/den der Benutzer angibt (--ref).

   Mehrere Fragen zum selben Repository? Führen Sie overview --repo <URL> einmal aus und lesen Sie das zwischengespeicherte OVERVIEW.md, das es ausgibt: Es kartiert das Repository (Pakete, Layout, öffentliche API, Dokumentation), sodass Folgefragen denselben Klon+Index wiederverwenden, anstatt sich von Grund auf neu zu orientieren. Zitieren Sie es nie – es ist Navigation, keine Beweise.

   Monorepo? Wenn ask/index/overview Arbeitsbereichspakete meldet (z. B. socialgouv/code-du-travail-numerique → @cdt/frontend, @socialgouv/modeles-social, …), wählen Sie das Paket, dessen Name/Verzeichnis mit dem Teilsystem übereinstimmt, auf das sich die Frage bezieht, und fügen Sie --package <Name|Verzeichnis> hinzu, damit der Abruf nicht in den anderen Paketen untergeht. Wenn kein Paketname offensichtlich passt, führen Sie zuerst einen uneingeschränkten ask aus, sehen Sie, in welchem Paket die Top-Treffer clusterieren, und führen Sie dann erneut eingeschränkt darauf aus. Ein unbekannter Paketname schlägt laut fehl und listet auf, was existiert.

2. Abrufen. Denken Sie zuerst wie ein Entwickler und leiten Sie 2–3 Abfragevarianten für die Frage ab – die Engine sucht wörtlich, also ist die Formulierung wichtig:

   • die natürlichsprachliche Formulierung („Retry-Backoff“),
   • die Bezeichnerformen, die die Codebasis wahrscheinlich verwendet (retryBackoff, retry_backoff, MAX_RETRIES),
   • die wörtliche Fehlermeldung, Option oder Flag-Name, wenn der Benutzer eine zitiert hat.

   Mehrteilige Frage? Teilen Sie sie jetzt in Unterfragen auf – jede benötigt ihre eigenen Beweise oder eine explizite „Unbekannt“-Angabe am Ende. Verfolgen Sie die Abdeckung pro Unterfrage.

   Die Engine beugt bereits Pluralformen und Akzente („retries“/„retry“, „délai“/„delai“), zerlegt Bezeichner in Untertokens und boostet Dateien, die nach einem Schlüsselwort benannt sind – verwenden Sie Ihre Varianten also für Synonyme und Bezeichner („heartbeat“ vs. ping, „pool“ vs. connectionLimit), nicht für Beugungen desselben Wortes. Und wissen Sie, wann die lexikalische Suche dünn sein wird: Sie benötigt Wörter, die wörtlich im Repository vorkommen. Für konzeptionelle Fragen oder „Warum wurde es so entworfen“-Fragen beginnen Sie mit docs, discussions, web (oder --semantic), anstatt zu erwarten, dass code die Antwort trägt.

   Führen Sie ask mit der besten Variante und den passenden Quellen aus:

   node scripts/ultradoc.mjs ask --repo <URL> --q "<präzise Frage>" --sources code,issues,prs,docs
   

   ultradoc erkennt automatisch die offizielle Dokumentations-URL des Projekts aus seinen eigenen README/Manifesten (und priorisiert den kanonischen docs/-Baum im Repository), untermauert dann dagegen – übergeben Sie --docs-url <URL> nur zum Überschreiben. Fügen Sie web,so hinzu, wenn die Frage konzeptionell ist oder das Repository spärlich ist; fügen Sie releases,history hinzu, wenn es darum geht, wann/warum/welche Version sich etwas geändert hat. Der Befehl gibt den Dossier-Pfad aus. Behandeln Sie dann die verbleibenden Varianten × Drill-Quellen als Fan-Out – geben Sie diese unabhängigen Bohrungen als parallele Aufrufe in einer Nachricht aus (oder einen Unteragenten pro Zelle). Siehe references/orchestration.md.

3. Das Dossier lesen. Öffnen Sie EVIDENCE.md im Ausführungsordner. Jedes Element hat eine ID ([E1], [E2], …), einen Herkunfts-ref und einen Ausschnitt. Dies sind Ihre Beweise – lesen Sie den tatsächlichen Code/Issue/PR/Dokumentationstext.

4. Auf Lücken eintauchen. Eine Unterfrage ist dünn, wenn sie weniger als ~2 themenrelevante Elemente hat oder kein Element tatsächlich das angefragte Symbol/Verhalten enthält. Warten Sie nicht, bis ein Dossier dünn aussieht, um die Varianten zu bohren – führen Sie die Variantenbohrungen von Anfang an parallel aus (Bohrungen sind nahezu kostenlos: der Klon und der Index sind zwischengespeichert). Verteilen Sie sie auf die Quellen:

   • code --repo <...> --q "<Symbol oder Verhalten>" um weitere Codebereiche zu ziehen.
   • issues/prs um verwandte Diskussionen und laufende Änderungen zu lesen.
   • releases (Changelog + Release Notes) und history (Git-Pickaxe) wenn die Frage wann/warum/welche Version sich etwas geändert hat.
   • discussions für Community-F&A und Design-Threads (benötigt die gh CLI).
   • web (oder Ihre WebSearch → web --url <u>) für externe Referenzen. Folgen Sie references/retrieval-playbook.md für die Iteration und references/orchestration.md für die parallele Ausführung der Bohrungen.

   Triage vor dem Schreiben. Der Abruf ist recall-orientiert, daher enthält das Dossier themenfremde Elemente, die nur Schlüsselwörter teilen. Der Test: Ein Element ist für die Frage nur relevant, wenn sein Ausschnitt das angefragte Symbol/Verhalten nennt oder denselben Mechanismus beschreibt – das Teilen eines Schlüsselworts reicht nicht. Listen Sie auf, welche Beweis-IDs diesen Test bestehen, und ignorieren Sie den Rest – ein themenfremdes Element darf nicht zitiert werden, nur weil es existiert. Wenn nach der Triage weniger als ~2 Elemente die Kernbehauptung stützen, rufen Sie weitere ab.

   Erneute Abfrage statt erneutem Lesen. Wenn die Top-3-Code-Elemente themenfremd sind, lesen Sie nicht weiter die Liste hinunter – führen Sie erneut code --q mit der nächsten Bezeichner-förmigen Variante aus Schritt 2 aus. Zwei themenfremde Dossiers hintereinander bedeuten, dass die Wortwahl falsch ist, nicht, dass das Repository die Antwort nicht enthält.

   Schleife bis zur Erschöpfung. Bohren Sie in Runden (max. ~3). Hören Sie auf, wenn eine Runde keine neuen themenrelevanten Beweise zutage fördert oder wenn jede Unterfrage ≥2 unterstützende Elemente hat – dann triagieren und schreiben. Eine Unterfrage, die nach dem Limit noch nicht gestützt ist, ist eine explizite Unbekannte, niemals aus dem Gedächtnis gefüllt.

5. Die Antwort schreiben. Erstellen Sie ANSWER.md im selben Ausführungsordner. Seien Sie präzise und kurz. Zitieren Sie jede Tatsachenbehauptung mit der Beweis-ID, auf die sie sich stützt, z. B. Wiederholungen verwenden exponentiellen Backoff mit Jitter [E1], und PR #79 schreibt dies um [E7]. Siehe references/citation-format.md. Heften Sie die Antwort an den Commit, der in meta.json angezeigt wird, wenn die Version wichtig ist. Decken Sie jede Unterfrage aus Schritt 2 ab; kennzeichnen Sie alles, was die Beweise nicht klären, als explizite Unbekannte – füllen Sie es nicht aus dem Gedächtnis.

6. Validieren (zwei Ebenen).

   • Strukturell: node scripts/ultradoc.mjs check --run <Dossier-Verzeichnis>. Es schlägt bei jedem Zitat fehl, das nicht zu Beweisen aufgelöst werden kann, oder bei einer Antwort ohne Zitate. Korrigieren und erneut ausführen, bis es besteht.
   • Semantisch (adversariale Unterstützungsprüfung): node scripts/ultradoc.mjs verify --run <Dossier-Verzeichnis> schreibt eine Behauptungs↔Beweis-Arbeitsliste (VERIFY.todo.json + VERIFY.md). Beurteilen Sie jedes Paar als Skeptiker: Standardmäßig unsupported/refuted, es sei denn, der zitierte Ausschnitt untermauert die Behauptung wörtlich, und setzen Sie das Urteil auf supported · partial · refuted · unsupported (+ kurze Notiz). Führen Sie einen Skeptiker pro Paar aus – verteilen Sie es an Unteragenten, wenn verfügbar (jeder gibt sein Urteil zurück), andernfalls entscheiden Sie jedes Paar inline – und sammeln Sie jedes Urteil in einer einzigen verdicts.json (siehe references/orchestration.md), dann:

     node scripts/ultradoc.mjs verify --apply verdicts.json --run <Dossier-Verzeichnis>
     node scripts/ultradoc.mjs check  --semantic --run <Dossier-Verzeichnis>
     

     Dies schlägt bei verwaisten/unbelegten (strukturell) und bei jeder widerlegten oder nicht unterstützten Behauptung fehl – schließt die Lücke, wo ein Zitat aufgelöst wird, aber die Behauptung nicht tatsächlich stützt. Korrigieren Sie die Behauptung (neu zitieren, abschwächen, fallen lassen oder ein besseres Element abrufen) und verifizieren Sie erneut, bis es besteht. Überprüfen Sie sich auch selbst mit references/answer-rubric.md auf Vollständigkeit/Aktualität/Unbekannte.

7. Präsentieren. Geben Sie dem Benutzer die fundierte Antwort mit ihren Zitaten und Links (Datei:Zeile, Issue/PR-Nummern, Doc/SO/Web-URLs aus den Beweisen) und den Commit, gegen den sie verifiziert wurde.

Dokumentation generieren

Wenn der Benutzer eine gesamte Projekt- (oder gesamte Paket-) Dokumentation und nicht nur eine Antwort wünscht, verwenden Sie doc – es ist dieselbe fundierte Schleife, die über eine Abschnittsgliederung verteilt ist:

1. Gerüst erstellen. node scripts/ultradoc.mjs doc --repo <URL> [--package <p>]. Die Engine erstellt eine deterministische Gliederung (Überblick, Installation/Verwendung, öffentliche API oder ein Abschnitt pro Arbeitsbereichspaket, Konfiguration, Architektur), ruft ein Dossier pro Abschnitt ab, führt sie in einer evidence.json mit globalen [E#]-IDs zusammen und schreibt DOC.todo.md (die Arbeitsliste pro Abschnitt) + DOC.plan.json. Fügen Sie --sources code,docs,issues,prs hinzu, um Abschnitte auf mehr als Code+Docs zu stützen. Es wird dauerhaft unter <clone>/.ultradoc/doc/ gespeichert.
2. Jeden Abschnitt schreiben. Lesen Sie DOC.todo.md und EVIDENCE.md, schreiben Sie dann DOC.md im Ausführungsordner: ein Abschnitt pro Gliederungseintrag, jede Behauptung mit [E#] zitiert. Ein Abschnitt, dessen Beweise dünn sind, ist eine Fan-Out-Einheit – bohren Sie ihn (code|docs|issues …) oder markieren Sie die Lücke als explizite Unbekannte; schreiben Sie nie aus dem Gedächtnis. Die Arbeit pro Abschnitt parallelisiert sich – siehe references/orchestration.md.
3. Validieren & präsentieren. node scripts/ultradoc.mjs check --run <doc-verzeichnis> (und verify + check --semantic für die Unterstützungsprüfung, genau wie in Schritt 6 – beide erkennen DOC.md automatisch). Korrigieren, bis es fundiert ist, dann DOC.md präsentieren, das auf seinen Commit festgelegt ist.

Optionaler semantischer Modus (vollständig lokal, kein API-Key)

Der deterministische Tier-1-Suchmodus (ripgrep + Symbolindex) ist die Standardeinstellung und benötigt nichts. Für vage, konzeptionelle Fragen können Sie die lokale semantische Suche aktivieren:

node scripts/ultradoc.mjs semantic up      # docker compose: Qdrant + Ollama (+ SearXNG)
node scripts/ultradoc.mjs ask --repo <URL> --q "…" --semantic

Alles läuft in lokalen Docker-Containern – kein Schlüssel, keine Daten verlassen die Maschine. Wenn der Stack nicht läuft, protokolliert --semantic einen Hinweis und fällt auf Tier 1 zurück. Siehe references/semantic-setup.md.

Referenzen

• references/orchestration.md – wie man Abrufbohrungen und Verifizierung über Aufrufe/Unteragenten parallelisiert, mit den Rückgabe- und Urteils-Sammelverträgen und dem sequentiellen Fallback.
• references/retrieval-playbook.md – wie man Quellen auswählt und iteriert, um eine vollständige Antwort zu erhalten.
• references/citation-format.md – die Zitiergrammatik, die check durchsetzt.
• references/answer-rubric.md – die semantische Selbstüberprüfung vor der Präsentation.
• references/provider-apis.md – wie Issues/PRs pro Host schlüssellos abgerufen werden.