mxchen-xyz/knowledge-graph-skill-zh

Wissensgraph-Batch-Generator

📌 Versionsgeschichte

Version	Datum	Änderungen
2.2.0	2026-09-02	Praxis-Upgrade für große Projekte：① Upgrade-Strategie für Rohkarten – bei Rückmeldungen wie „zu viel fehlt/Regeln zu einfach“ wird ein vollständiges Upgrade ausgelöst, paralleles Verteilen von Unter-Agenten pro Domäne + Haupt-Agent überwacht Ergebnisse (grep auf verbleibende Fehlmeldungen); bei Agent-Stillstand übernimmt Haupt-Agent die Ergänzung; ② Mermaid-Knoten-Label verbieten Klammern (häufigste Ursache für Renderfehler) und Batch-Regex-Fix-Skript; ③ Unter-Agenten machen oft Fehler bei relativen Pfaden über Module hinweg (../..-Ebenen); Endkontrolle muss Bidirectional-Link-Prüfung durchführen; ④ Aktualisierung der Statistik-Rückschreibung nach Upgrade und README
2.1.0	2026-09-01	Wichtige Reparatur der Obsidian-Wiki-Link-Pfadnorm：Obsidians [[...]]-Wiki-Links unterstützen keine ../-relativen Pfade (../ wird als Notizname interpretiert, was zu nicht anklickbaren Links führt). Alle Links wurden auf vollständige Pfade vom Wissensdatenbank-Stammverzeichnis aus geändert (`[[Domäne/Modul/Funktion.md
2.0.0	2026-08-24	Reparatur der Obsidian-Bidirectional-Link-Kompatibilität：Fünfter Batch-Qualitätsprüfung ergänzt um „keine Punktnotation + relative Pfadauflösung pro Link“. Die generierte Wissensdatenbank ist nun in Obsidian korrekt navigierbar
1.0.0	Erstversion	Grundlegende Fähigkeit der 5-Batch-Strategie (L1+L2-Gerüst → L3-Modulindizes → Kernfunktionskarten → restliche Funktionsrohlinge → globale Qualitätsprüfung)

Überblick

Wissensengineering für große Projekte. Wenn ein Projekt bereits vollständigen Code/Dokumentation hat, mehr als 50 Funktionsknoten umfasst und eine vollständige Wissensdatenbank mit Hunderten von Knoten auf einmal erstellt werden muss, erfolgt die Generierung effizient in Batches, um eine Überlastung der einmaligen Ausgabe zu vermeiden. Alle Dateiinhalte müssen den Vorlagen-Spezifikationen im Skill business-knowledge-graph-generator (references/templates.md) folgen.

Wann verwenden

• Projekte mit mehr als 50 Funktionen
• Vorhandene vollständige Projektverzeichnisstruktur + Kerncode-Dateiinhalte (können in Batches bereitgestellt werden)
• Erstellung einer vollständigen Wissensdatenbank mit Hunderten von Knoten auf einmal

Eingabeanforderung: Bereitstellung der vollständigen Projektverzeichnisstruktur + Kerncode-Dateiinhalte (kann in Batches erfolgen).

Batch-Verarbeitungsstrategie

Wenn die Anzahl der Funktionen 50 übersteigt, erfolgt die Verarbeitung in 5 Batches in der folgenden Reihenfolge:

Erster Batch: L1 + L2-Gerüst (globale Struktur) – voraussichtlich 6–20 Dateien

1. Generiere knowledge/_index.md (L1-Gesamtansicht)
2. Generiere <Domäne>/_index.md für jede Domäne (L2-Domänenansicht)
3. Qualitätsprüfung: Bestätige, dass alle Domänen und Module abgedeckt sind, keine Lücken

Zweiter Batch: L3-Modulindizes (Funktionsliste) – voraussichtlich 20–50 Dateien

1. Generiere <Domäne>/<Modul>/_index.md für jedes Modul (L3-Modulansicht)
2. Qualitätsprüfung: Bestätige, dass die Funktionsliste jedes Moduls vollständig ist, alle Funktionen benannt sind

Dritter Batch: Hochpriorisierte Funktionskarten (Kernprozesse) – voraussichtlich 20–30 Dateien

1. Identifiziere die Kernfunktionen des Systems (die 20% am häufigsten genutzten Funktionen, z. B. Login, Bestellung, Zahlung)
2. Generiere vollständige L4-Karten für diese Funktionen (mit Prozess, Regeln, Ereignissen, Abhängigkeiten, Code-Standorten)
3. Qualitätsprüfung: Kernprozesse enthalten Ausnahmepfade, Code-Standorte sind auf Zeilenebene genau

Vierter Batch: Restliche Funktionsrohlinge – voraussichtlich 50–200+ Dateien

1. Generiere minimale Karten für die restlichen Funktionen (mindestens Frontmatter + Funktionsbeschreibung + Basisregeln)
2. Markiere mit Status: ergänzungsbedürftig für spätere manuelle Vervollständigung
3. Qualitätsprüfung: Alle Funktionen haben eine entsprechende .md-Datei, keine Funktion fehlt

Fünfter Batch: Globale Qualitätsprüfung und Indexaktualisierung

1. Überprüfe, dass alle Bidirectional-Links Obsidian-kompatible relative Pfade verwenden ([[../Modul/Funktion.md|Alias]]), keine Punktnotation wie [[Domäne.Modul.Funktion]]
2. Durchlaufe die Prüfung: Jeder Link muss – relativ zur aktuellen Datei aufgelöst – auf eine vorhandene .md-Zieldatei verweisen
3. Markiere alle schwebenden Links, erstelle eine Reparaturliste
4. Aktualisiere die Statistikzahlen (Modulanzahl, Funktionsanzahl) in den _index.md-Dateien jeder Ebene
5. Generiere knowledge/README.md mit Nutzungshinweisen

Prioritätsregeln

Priorität	Kriterium	Beispiel-Funktionen
Kern	Wird von >80% der Nutzer täglich verwendet, sicherheitsrelevant	Login, Bestellung, Zahlung, Rückerstattung
Wichtig	Wird von 30%–80% der Nutzer täglich verwendet, datenverwaltungsrelevant	Bestellabfrage, Logistikverfolgung, Info-Änderung
Allgemein	Admin-Backend-Funktionen, seltene Aktionen, Konfigurationen	Produktkategorien-Verwaltung, Log-Abfrage, Berichtserstellung

Ausgabeanforderungen

1. Ausgabe in Batches, nach jedem Batch Fortschritt melden und auf Benutzerbestätigung warten, bevor der nächste Batch startet
2. Bei jedem Batch die Liste der generierten Dateien auflisten
3. Nach Abschluss des dritten Batches (Kernfunktionen) pausieren und auf Benutzerangabe des nächsten Schwerpunktbereichs warten
4. Alle Dateiinhalte müssen den Vorlagen-Spezifikationen in business-knowledge-graph-generator/references/templates.md folgen

Batch-Berichtsformat

## Batch X abgeschlossen ✅

**Generierte Dateien**: XX
**Betroffene Domänen**: DomäneA, DomäneB
**Dateiliste**:

- knowledge/DomäneA/_index.md
- knowledge/DomäneA/ModulA/_index.md
- ...

**Nächster Batch**: Generierung von Kernfunktionskarten im Bereich XXX

Bitte bestätigen, um fortzufahren?

Hinweise

• Batch-Auslieferung: Wenn das Projekt über 100 Funktionen hat, zuerst L1- und L2-Gerüst, dann schrittweise zu L3, schließlich L4-Karten im Batch
• Code-Lesebegrenzung: Wenn zu viele Codedateien vorhanden sind, den Benutzer bitten, zunächst 5–10 Schlüsseldateien des Kernmoduls bereitzustellen; der Rest kann nach Verzeichnisstruktur beschrieben werden
• Manuelle Ergänzung: Das Skill generiert 80% des Inhalts (Struktur, Prozesse, Regelrahmen), aber historische Stolperfallen und Verantwortliche müssen vom Benutzer manuell ergänzt werden

Praxiserfahrungen (aus Projekt Jetlinks, 01.09.2026)

1. Obsidian-Links müssen Wissensdatenbank-Stammpfad ohne .md-Endung verwenden (am wichtigsten): Obsidians Wiki-Links unterstützen keine ../-relativen Pfade (../ wird als Notizname interpretiert) und unterstützen keine .md-Endung ([[Note.md]] wird als Notiz namens „Note.md“ statt „Note“ interpretiert, was zu nicht anklickbaren Links führt). Alle Links einheitlich als [[Domäne/Modul/Funktion|Alias]] (vom knowledge/-Stammverzeichnis ausgehend, ohne .md) schreiben. In Mermaid-Diagrammen nur Textknoten (A[Funktion] --> B[Funktion]), [[...]]-Syntax verboten.
2. 429-Ratenbegrenzung bei Unter-Agenten: Bei großflächiger Erkundung/Generierung können Unter-Agenten Ratenbegrenzungen (429) auslösen; dann auf Hauptsitzung herabstufen: zuerst mit Glob/Grep alle @RequestMapping und HTTP-Methodenannotationen aller Controller lokalisieren (bis auf Zeilenebene genau), dann Datei für Datei schreiben.
3. Qualitätsprüfungsskripte müssen Codeblöcke überspringen: In L4-Karten werden „Link-Norm“-Beispiele oft in Backtick-Codeblöcken geschrieben. Das Qualitätsprüfungs-Regex muss zuerst `...` und mermaid -Blockinhalte entfernen, sonst werden Beispiele fälschlich als schwebende Links gemeldet.
4. Funktionsanzahl-Rückschreibmechanismus: Die Modulfunktionsanzahl in L2-Indizes ist eine Schätzung; nach L3-Generierung wird der tatsächliche Wert verwendet. Im fünften Batch werden die L2-Statistikspalten und die L1-Größenstatistik automatisch zurückgeschrieben.
5. Batch-Generierung mit Skript: Der vierte Batch (Rohkarten, 100+ Dateien) wird mit einem Python-Skript erstellt, das aus der L3-Indextabelle Funktionsname/Typ/Beschreibung per Regex extrahiert und massenweise schreibt, um konsistente Namen und Links zu gewährleisten. Das ist effizienter und weniger fehleranfällig als manuelles Schreiben Datei für Datei.

Praxiserfahrungen (aus vollständigem Upgrade großer Projekte, 02.09.2026)

6. Vollständiges Upgrade von Rohkarten, nicht auf Benennung warten: Unzufriedenheit des Benutzers mit „zu viel fehlt/zu einfache Regeln“ löst ein vollständiges Upgrade aus. Nach Domänen unterteilt, alle auf vollständigen Karten-Detaillierungsgrad hochgestuft (siehe "L4-Karten-Detaillierungsstandard" im Business-Skill).
7. Parallele Unter-Agenten pro Domäne + Haupt-Agent-Überwachung: Pro Domäne ein Unter-Agent (Prompt mit eingebautem Vorlagenbeispiel + Mermaid-Eiserner-Regel + Code-Untersuchungsanforderung). Haupt-Agent prüft regelmäßig mit grep -rl "Status: ergänzungsbedürftig" <Domäne> | wc -l die verbleibende Anzahl. Wenn ein Agent stillsteht (keine neuen Dateien für eine Weile), übernimmt der Haupt-Agent direkt die Ergänzung, anstatt untätig zu warten.
8. Mermaid-Knoten-Label verbieten Klammern (häufigste Ursache für Renderfehler): In Flowchart-Knoten [..]/{..} führen () (z. B. A[Foo(x)]) zu Parse-Fehlern wie „Expecting SQE, DOUBLECIRCLEEND...“. Funktionssignaturparameter entfernen oder durch Leerzeichen trennen. Massenreparatur: Regex scannt nur Mermaid-Blöcke und ersetzt [label(args)] durch [label args] (Klammern entfernt, Kommas durch Leerzeichen ersetzt).
9. Unsachgemäße relative Pfade bei Unter-Agenten über Module hinweg: Unter-Agenten machen häufige Fehler bei der Berechnung von ../..-Ebenen für modulübergreifende Links (z. B. von Transaktionsverwaltung/Transaktionsprotokoll/ zu Marktdaten/Aktienverwaltung/ sollte ../../Marktdaten/Aktienverwaltung/_index.md sein, nicht ../Aktienverwaltung/). Die Endkontrolle muss ein Bidirectional-Link-Prüfskript ausführen, um die defekte Linkliste zu erstellen und jede Reparatur durchzuführen.
10. Dreifache Endkontrolle: Nach Abschluss des Upgrades: ① Bidirectional-Link-Vollständigkeitsskript (alle .md-Dateien durchgehen, [[...]]-relative Pfade auflösen und Ziel existiert prüfen) ② Mermaid-Klammern-Scan ③ Verbleibende „ergänzungsbedürftig“-Zählung (grep -rl "Status: ergänzungsbedürftig" | wc -l sollte 0 sein); README-Statistik nach Abschluss aktualisieren und ausliefern.

Anleitung für Batch-Upgrade von Rohkarten

Wenn knowledge/ bereits viele zu aktualisierende Rohkarten enthält:

1. Verbleibende zählen: grep -rl "Status: ergänzungsbedürftig" knowledge/*/ | wc -l   (nach Domäne detailliert)
2. Nach Domäne parallele Unter-Agenten verteilen (jeder Prompt muss enthalten: absoluten Pfad zum Vorlagenbeispiel, Mermaid-Eiserne-Regel,
   Code-Untersuchungsanforderung „mindestens 1–2 echte Funktionsnamen + Zeilennummern; falls nicht auffindbar, als ‚zu lokalisieren‘ markieren, nicht erfinden“, Ausgabeberichtsformat)
3. Haupt-Agent regelmäßig prüfen: find auf zuletzt geänderte Dateien / grep verbleibende „ergänzungsbedürftig“-Anzahl; bei Stillstand übernehmen
4. Endkontrolle: Bidirectional-Link-Prüfskript + Mermaid-Klammern-Scan + verbleibende „ergänzungsbedürftig“-Zählung auf null setzen
5. README-Statistik und _index-Statistikzahlen aller Ebenen aktualisieren

Ressourcen

• business-knowledge-graph-generator/references/templates.md: L1–L4 Vorlagen-Spezifikationen (müssen befolgt werden)