OKF-Bundle-Plugin

Das @docmd/plugin-okf-Plugin baut während der statischen Kompilierung ein Open Knowledge Format-Wissens-Bundle (OKF). OKF ist eine offene, herstellerneutrale Spezifikation zur Strukturierung von Dokumentationsmetadaten, Konzeptgraphen und Domainkontexten für KI-Agenten und LLM-Tool-Ketten.

Das Plugin ist standardmäßig aktiviert. OKF-Bundles werden bei jeder Site-Kompilierung in site/okf/ platziert.

Architektur-Übersicht

OKF formalisiert die Wissensarchitektur in eine portable Verzeichnisstruktur, die YAML-Manifeste, Markdown-Konzeptdateien und visuelle kraftgesteuerte Graph-Assets enthält.

Designprinzipien

1. Minimale strukturelle Anforderungen: Jeder Konzepteintrag erfordert lediglich ein type-Feld.
2. Produzent-/Konsument-Unabhängigkeit: Von Menschen verfasste Markdown-Dateien werden in Standard-Schemas kompiliert, die von beliebigen LLM-Frameworks abgefragt werden können.
3. Herstellerneutralität: Unabhängig von spezifischen Cloud-Anbietern, Modell-Hosts oder Vektordatenbank-Engines.

Generierte Ausgabe-Assets

Die Kompilierung erzeugt den folgenden Verzeichnisbaum:

site/okf/
├── okf.yaml  # Manifest-Zusammenfassungsdatei
├── index.md  # Nach Typ gruppierter Konzeptkatalog
├── graph/  # Interaktive Graph-Assets (wenn graph: true)
│   ├── index.html  # Kraftgesteuerter Graph-Visualisierer
│   ├── graph.json  # Graphknoten und Kanten
│   ├── graph.js  # Eigenständige Graph-Laufzeit
│   └── graph.css  # Themenbewusstes Styling
├── concepts/
│   └── <slug>.md  # Einzelne Konzept-Markdown-Dateien
└── _meta/
    ├── bundle.json  # JSON-Spiegel von okf.yaml
    └── lint-report.txt  # Build-Linting-Berichte

Standard-Build-Verhalten

Das OKF-Plugin wird während der Kompilierung automatisch geladen:

• Standard-Locale-Bereich: Gibt Konzepte für die Primärsprache im Bundle-Stammverzeichnis aus.
• Automatische Typ-Inferenz: Klassifiziert Pfade unter /api/, /guides/, /reference/, /concepts/, /runbooks/, /datasets/, /metrics/ und /tables/ in typisierte Konzepte.
• Wörtliches Markdown: Kopiert Seiteninhalte und Frontmatter in Konzeptdateien.

Deaktivieren

Deaktivieren Sie die OKF-Bundle-Generierung in docmd.config.json:

{
  "plugins": {
    "okf": false
  }
}

Alternativ setzen Sie enabled: false:

{
  "plugins": {
    "okf": {
      "enabled": false
    }
  }
}

Konfigurationsoptionen

Konfigurieren Sie OKF-Bundle-Parameter in docmd.config.json:

Globales Konfigurationsbeispiel

{
  "plugins": {
    "okf": {
      "outputDir": "knowledge",
      "defaultType": "concept",
      "graph": true
    }
  }
}

Mehrsprachige Ordnerstrategie

{
  "plugins": {
    "okf": {
      "localeStrategy": "folders"
    }
  }
}

Ausgabeverzeichnisstruktur:

site/okf/  # Standard-Locale (Stammverzeichnis)
├── okf.yaml
├── index.md
└── concepts/

site/okf/de/  # Deutsche Locale (verschachtelt)
├── okf.yaml
└── concepts/

Ausschluss von Seiten aus OKF

Schließen Sie bestimmte Seiten mithilfe von Frontmatter-Flags aus:

---
title: "Interne Betriebsnotiz"
okf: false # Schließt die Seite ausschließlich aus OKF-Bundles aus
---

Um eine Seite global über Sitemaps, Suche, LLM-Dateien und OKF hinweg auszuschließen, setzen Sie noindex: true.

Auflösung des Konzepttyps

Das Plugin bestimmt Konzepttypen in folgender Reihenfolge:

1. frontmatter.okf.type, Verschachtelte explizite Deklaration.
2. frontmatter.type, Explizite Deklaration auf oberster Ebene.
3. frontmatter.okfType, Älterer Alias.
4. Pfad-Präfix-Inferenz: Automatische Zuordnung für /guides/, /api/, /reference/, /concepts/ usw.
5. defaultType-Fallback ('concept').

Konzept-Metadaten & Tag-Auflösung

Das OKF-Plugin extrahiert Metadaten direkt aus dem Frontmatter jeder Seite in site/okf/okf.yaml und site/okf/_meta/bundle.json:

• Konzept-Beschreibungen: Das description-Frontmatter wird in jeden Konzepteintrag in okf.yaml und bundle.json übernommen, sodass KI-Agenten Zusammenfassungen prüfen können, ohne jede einzelne Markdown-Datei zu öffnen.
• Tag-Extraktion aus tags und keywords: Tags werden aus beiden Frontmatter-Eigenschaften (tags und keywords) bezogen. Es werden sowohl String-Arrays (["api", "auth"]) als auch kommagetrennte Strings ("api, auth") unterstützt, inklusive automatischer Deduplizierung (ohne Beachtung von Groß-/Kleinschreibung).