8 spezialisierte Agenten arbeiten zusammen, um aus einer Codebase einen vollstandigen Knowledge Graph zu erzeugen.
Der project-scannerDer erste Agent in der Verstehen-Pipeline. Er wird einmal aufgerufen und liefert die Grundlage fur alle nachfolgenden Agenten. ist der erste Agent, der lauft. Er scannt das gesamte Projektverzeichnis, erkennt Programmiersprachen anhand der Dateiendungen, identifiziert Frameworks uber Konfigurationsdateien (package.json, Cargo.toml, etc.) und erstellt ein vollstandiges Datei-Inventar.
Sein Output ist ein JSON-Objekt mit drei Hauptbereichen: files (alle relevanten Dateien mit Pfad, LOC, Sprache), languages (erkannte Sprachen mit Dateianzahl), und frameworks (erkannte Frameworks mit Version).
// project-scanner Output (Auszug)
{
"files": [
{
"path": "src/index.ts",
"loc": 142,
"language": "TypeScript",
"imports": ["./config", "express"]
}
],
"languages": {
"TypeScript": { "files": 47, "loc": 8350 },
"JSON": { "files": 12, "loc": 890 }
},
"frameworks": {
"Express": "4.18.2",
"React": "18.2.0"
}
}
Was liefert der Scanner? Ein vollstandiges Inventar aller Code-Dateien mit Pfaden, Zeilenanzahlen, erkannten Sprachen und externen Imports. Dazu eine Zusammenfassung der erkannten Sprachen und Frameworks.
Diese Daten werden fur zwei Zwecke genutzt: (1) Der Orchestrator ladt die passenden Sprach- und Framework-Addenda, (2) die Dateien werden in Batches von 20-30 Stuck fur den file-analyzer aufgeteilt.
Der file-analyzerDer einzige Agent, der parallel in mehreren Instanzen lauft. Bis zu 5 Instanzen verarbeiten gleichzeitig unterschiedliche Datei-Batches. Jede Instanz erhalt nur ihren Batch + die Sprach-Addenda. ist der arbeitsintensivste Agent. Er wird bis zu funfmal parallel aufgerufen, wobei jede Instanz einen Batch von 20-30 Dateien analysiert. Fur jede Datei extrahiert er Nodes (Funktionen, Klassen, Interfaces, Exports) und Edges (Imports, Aufrufe, Vererbung).
Jeder Batch-Output enthalt einen Teil-Graphen mit Nodes und Edges. Der assemble-reviewer fuhrt diese Teil-Graphen spater zusammen und lost dabei Konflikte (z.B. doppelte Node-IDs, unaufgeloste Cross-Batch-Referenzen).
// Node-Type-Definitionen (aus graph-reviewer.md)
const STRUCTURAL_NODE_TYPES = [
"file", // Quelldatei
"function", // Funktion / Methode
"class", // Klasse
"interface", // Interface / Trait
"module", // ES-Modul / Package
"component", // UI-Komponente
"type", // Type Alias / Enum
"config", // Konfigurationsdatei
"test", // Testdatei
"route", // API-Route / Endpoint
"middleware", // Middleware
"schema", // DB-Schema / Migration
"constant" // Konstante / Enum-Wert
];
const DOMAIN_NODE_TYPES = [
"concept", // Fachdomanen-Konzept
"process", // Geschaftsprozess
"entity" // Domanen-Entitat
];Der architecture-analyzerAnalysiert den assemblierten Graph und identifiziert architektonische Schichten. Jeder Node wird genau einem Layer zugeordnet. Die Layer-Struktur wird im finalen Graph als eigenes Feld gespeichert. erhalt den zusammengesetzten Graph und identifiziert 3 bis 10 logische Architektur-Layer. Typische Layer sind: Core/Domain, Infrastructure, API/Routes, Frontend/UI, Database, Configuration, Tests.
Jede Datei (jeder file-Node) wird genau einem Layer zugeordnet. Die Zuordnung basiert auf Pfad-Mustern (z.B. src/api/ → API-Layer), Import-Graphen (Dateien, die nur von anderen importiert werden, sind oft Core) und Framework-Konventionen (z.B. React-Komponenten → UI-Layer).
// Layer-Zuordnung Output (Auszug)
{
"layers": [
{
"name": "Core",
"description": "Business logic and domain models",
"nodes": ["src/models/user.ts", "src/services/auth.ts"],
"color": "#000099"
},
{
"name": "API",
"description": "REST endpoints and middleware",
"nodes": ["src/routes/users.ts", "src/middleware/auth.ts"],
"color": "#FE8F11"
}
]
}Der tour-builderErstellt eine geordnete Sequenz von Nodes, die einen logischen Einstiegspunkt bietet. Beginnt typischerweise beim Haupteinstiegspunkt (main, index) und folgt den wichtigsten Abhangigkeitsketten. analysiert den Graph und erstellt einen geordneten Lernpfad — die guided_tour. Statt alle Knoten unsortiert zu zeigen, fuhrt er den Lernenden Schritt fur Schritt durch die Codebase, beginnend beim Einstiegspunkt und aufsteigend in der Komplexitat.
// guided_tour Output (Auszug)
{
"guided_tour": {
"title": "Express API — Guided Tour",
"steps": [
{
"order": 1,
"node_id": "src/index.ts",
"title": "Einstiegspunkt",
"description": "Server-Setup und Middleware-Kette",
"why": "Hier startet alles — der Express-Server wird konfiguriert"
},
{
"order": 2,
"node_id": "src/config.ts",
"title": "Konfiguration",
"description": "Umgebungsvariablen und DB-Verbindung",
"why": "Wichtig zum Verstandnis aller Defaults"
}
]
}
}Der Lernpfad enthalt typischerweise 8-15 Stationen, die zusammen etwa 80% der Kernfunktionalitat abdecken. Jede Station hat eine Erklarung, warum sie wichtig ist (why-Feld), was den Unterschied zu einer reinen Dateiauflistung ausmacht.
Der graph-reviewerDer letzte Agent in der Analyse-Pipeline. Er pruft den gesamten Graph auf Schema-Konformitat, referentielle Integritat und Vollstandigkeit. Fehler werden entweder automatisch repariert oder als Warnings reportet. ist der Qualitats-Wachter. Er pruft den finalen Graph gegen das Schema in drei Dimensionen: Schema-Validierung (erlaubte Node- und Edge-Typen), referentielle Integritat (jede Edge verweist auf existierende Nodes), und Vollstandigkeit (jede Datei aus dem Inventar hat mindestens einen Node).
// graph-reviewer Validierungsregeln
const EDGE_TYPES = [
"imports", "exports", "calls",
"contains", "implements", "extends",
"uses", "tests", "configures",
"depends_on", "renders", "routes_to",
"middleware", "validates", "transforms",
// ... 29 Typen insgesamt (26 struct + 3 domain)
];
// Validierungschecks
function validateGraph(graph) {
const errors = [];
// 1. Schema: Nur erlaubte Typen
graph.edges.forEach(e => {
if (!EDGE_TYPES.includes(e.type))
errors.push(`Unknown edge type: ${e.type}`);
});
// 2. Referentielle Integritat
graph.edges.forEach(e => {
if (!graph.nodes.find(n => n.id === e.source))
errors.push(`Dangling source: ${e.source}`);
});
// 3. Vollstandigkeit
inventory.forEach(f => {
if (!graph.nodes.find(n => n.id === f.path))
errors.push(`Missing node for: ${f.path}`);
});
return errors;
}
Drei Validierungsdimensionen:
1. Schema-Validierung: Jeder Node muss einen der 16 erlaubten Typen haben, jede Edge einen der 29 erlaubten Typen. Unbekannte Typen werden als Fehler gemeldet.
2. Referentielle Integritat: Jede Edge verweist auf eine source und ein target. Beide mussen als Nodes existieren. "Dangling References" werden repariert oder entfernt.
3. Vollstandigkeit: Jede Datei aus dem Inventar muss mindestens einen Knoten im Graph haben. Fehlende Dateien deuten auf ubersprungene Batches hin.