ultraindex – Erstelle und navigiere eine KI-analysierte Enzyklopädie eines gesamten Repos
Bei einem riesigen Repo ist der Kontext gefüllt, bevor man findet, was zählt.
ultraindex behebt das mit einer Aufgabenteilung: Die deterministische,
zero-dependency Engine (node scripts/ultraindex.mjs <command> – kein
npm install, keine API-Schlüssel, --help für die vollständige Oberfläche) erledigt
die mechanische Arbeit – das Projekt scannen, den Link-Graphen bauen, die
Enzyklopädie anlegen; du erledigst das Verstehen – fundierte, zitierte
Analyse – und navigierst später das Ergebnis, statt das Repo zu lesen.
Die Kernregeln:
- Die Engine besitzt die Code-Ansicht und den Graphen (
ui:gen-Bereiche) – bei jedem Build neu generiert; niemals von Hand bearbeiten.- Du besitzt die Fachansicht (
ui:human-Bereiche).builderhält deine Prosa über Neubuilds und Umbenennungen hinweg.- Analysiere auf Basis von Belegen, nicht aus dem Gedächtnis. Schreibe Analyse nur aus dem echten Quellcode, den
dossierdir zeigt, zitiere ihn[datei:zeile], undcheckschlägt fehl bei jedem Zitat, das nicht aufgelöst werden kann – also rate nicht.- Lade das Minimum. Lies einen Eintrag (oder ein
dossier) auf einmal – das ist das beabsichtigte Muster und genau das, was ein per-Modul-Anreicherungs-Subagent tut. Lade niemalsgraph.jsonoder das gesamteencyclopedia/-Verzeichnis in den Kontext – das widerspricht dem Zweck.
Die meisten Befehle akzeptieren --json – bevorzuge ihn immer dann, wenn du
auf das Ergebnis verzweigst, anstatt es als Text zu lesen.
Routenauswahl nach Situation
Ermittle, in welcher Situation du dich befindest, in dieser Reihenfolge, und lies die passende Referenz für den detaillierten Workflow:
-
Noch kein Index – kein
.ultraindex/oderdocs/ultraindex/im Repo-Root (suche nachgraph.jsondarin). Erstelle ihn, dann reichere die Top-Module an: lies references/generate.md. -
Index existiert – zuerst Frische prüfen.
node scripts/ultraindex.mjs check --out <index-verz> --json. Wenn er veraltet oder defekt ist, führebuilderneut aus (deine Prosa bleibt erhalten), dann fahre fort. Wenn nur für die Aufgabe irrelevante Dateien geändert wurden, kannst du fortfahren und es vermerken. -
Der Benutzer hat eine Aufgabe oder Frage („wo ist X“, „wie funktioniert Z“, „welche Dateien muss ich ändern“) – navigiere durch den Index, öffne nur die Dateien, auf die er verweist, begründe Antworten mit verifizierten Zitaten: lies references/navigate.md.
-
Die Antwort muss hohe Sicherheit bieten (Audit, Sicherheit, eine korrektheitskritische Behauptung), oder der Benutzer bittet dich, eine Antwort zu überprüfen/beurteilen – nachdem
check --answerbestanden hat (Zitate sind auflösbar), eskalieren zur semantischen Verify-Stufe, damit jedes zitierte Excerpt nachweist, dass es die Behauptung stützt, nicht nur existiert: lies references/verify.md. -
Der Benutzer hat gebeten, zu indizieren/analysieren/dokumentieren, oder
status --jsonzeigt nicht angereicherte Hubs an und du hast Budget – führe die statusgesteuerte Anreicherungsschleife aus (dossier → zitierte Analyse schreiben → prüfen). Bei einem großen Repo parallelisieren: ein Subagent pro Modul aus der Warteschlange, falls dein Host Subagents unterstützt – lies references/generate.md. -
findfindet immer noch nichts, oder der Benutzer wünscht semantische/bessere Suche – richte die optionale Embedding-Ebene ein (docker compose,embed, hybridefind): lies references/semantic.md.
Ein typischer erster Besuch verkettet 1 → 5 → 3; ein Wiederholungsbesuch ist normalerweise 2 → 3; eine Antwort mit hoher Sicherheit fügt → 4 hinzu.
Befehlsübersicht
build --repo <verz> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid]– Scanne und (neu) schreibe den Index. Idempotent; erhält angereicherte Prosa. Inkrementell (verwendet Extraktion unveränderter Dateien wieder); warnt, wenn--max-filesabschneidet.--out docs/ultraindexfür einen committed, PR-prüfbaren Index.map [--module <slug>] [--json]– Zeige INDEX.md (oder einen Eintrag, oder die Modultabelle).find "<abfrage>" [--k <n>]– Bewerte Module, zeige die exakten zu öffnenden Dateien an. Standardmäßig lexikalisch (mit IDF-Termgewichtung); hybrid (+ semantisch), wenn vectors.json existiert.neighbors <datei|modul> [--depth <n>]– Was verlinkt zu / von ihm.symbols "<name>" [--json]– Wo ein Symbol definiert ist (Datei:Zeile, Art, zugehöriges Modul) und welche Dateien darauf verweisen. Unscharfsuche nach Identifikator-Tokens.impact <datei|modul> [--depth <n>] [--json]– Die reverse Abhängigkeitshülle: alles, was das Ziel importiert oder verwendet. „Was passiert, wenn ich das ändere.“status– Die Arbeitswarteschlange der Anreicherung, in der exakten Reihenfolge zum Anreichern.dossier <slug>– Ein Informationspaket eines Moduls (echter Quellcode + Nachbarn; ein reines Dokumentations-/Konfigurationsmodul, z. B.root, zeigt keinen Code – reichere es an, indem du stattdessen seine README/Konfiguration zitierst).ask "<frage>"– Stelle fundierte Belege zusammen, um zu antworten.check [--answer <datei>] [--semantic]– Veralterung + Integrität + Fundierung (Zitate müssen auflösbar sein). Exit-Code ungleich Null ⇒ veraltet, defekt oder unbegründet.--semanticbezieht auch die Verify-Stufe ein (schlägt fehl für eine Behauptung, deren zitiertes Excerpt sie widerlegt, oder die vollständig beurteilt ist, ohne Stützung); es reduziert das Urteil aus den rohenverdicts[]und liest jedes beurteilte Excerpt erneut aus dem Live-Repo – eine manipulierte Zusammenfassung oder abweichende Quelle schlägt fehl, nie bestanden.verify --answer <datei> [--apply <verdicts.json>] [--max-verify <n>]– Die Hochsicherheits-Stufe übercheck --answerhinaus: Erstelle eine Behauptung↔Zitat-Arbeitsliste zur adversarischen Stützungsprüfung, dann--applyreduziert deine Urteile zu einem Bestehen/Nichtbestehen-Gatter. Siehe references/verify.md.embed [--force]– Baue/aktualisiere vectors.json für die semantischefind(benötigt einen Anbieter – siehe references/semantic.md).
Umfangshinweise
- Keine Schlüssel, kein Netzwerk, deterministisch (die optionale semantische Schicht ist
die eine Ausnahme, und sie fällt auf lexikalische Suche zurück, wenn ihr Anbieter fehlt). Zwei
Builds eines unveränderten Repos sind byte-identisch, außer
manifest.json'sbuiltAt-Provenienz-Zeitstempel;vectors.jsonist ebenfalls ausgenommen (seine Floats hängen vom Anbieter ab). - AST-genaue Symbole via committed Tree-Sitter-Grammatiken für JS/TS/TSX,
Python, Go, Rust, Java, C, C++, C#, Ruby, PHP – echte Verschachtelung, präzise Arten,
strukturelle Exports. Andere Sprachen fallen auf Regex-Extraktoren zurück (dennoch
durchsuchbar). Die Grammatik-WASMs werden im Bundle mitgeliefert, daher gibt es auch
kein
npm installzur Nutzungszeit des Skills (die Installation ist schwerer – ~17 MiB WASM). - Import-Kanten für JS/TS (tsconfig
paths, packageexports-Maps), Python, Go (Multi-Modul +replace), Rust (mod/use), Java (Packages), C/C++ (#include "..."), Ruby (require_relative/require), PHP (Composer PSR-4 + relativesrequire), C# (using→namespace). Plus konservative Code→Code-use-Kanten, wenn eine Datei ein eindeutiges exportiertes Symbol einer anderen Datei referenziert, ohne sie zu importieren. Übrige Sprachen erhalten keine Import-Kanten. Yarn PnP's virtuelles Dateisystem ist nicht im Scope (Workspace-Namen werden dennoch aufgelöst). - Hängende Kanten bedeuten normalerweise, dass das Repo selbst defekte Imports oder veraltete Dokumentationslinks hat – das ist ein zu meldender Befund, nicht zu überdecken.