/docs/cli-cicd/

Automatisierung mit CLI und CI/CD

Ein OKF-Bundle ist ein Verzeichnis aus Markdown-Dateien. Damit wird Wissenspflege zu normaler Software-Arbeit: Pull Requests, zeilengenaue Diffs, Review, CI-Gates. Alles, was für Quellcode gilt, gilt auch hier. Diese Seite zeigt die reale dreistufige Pipeline, mit der aus beliebigen Websites OKF-v0.2-Bundles werden, dazu den Git-Workflow und ein Konformanz-Gate für CI.

Die Pipeline in drei Stufen

[ Website / Blog / Sitemap ]
        │  1. blog_scraper.py
        ▼
[ HTML gesammelt, bereinigt, zu Markdown ]
        │  2. transform_to_okf.py
        ▼
[ OKF-v0.2-Frontmatter: Typen, Tags, Provenance, Trust ]
        │  3. build_data_json.py
        ▼
[ okf.md + llms.txt + INDEX.md + okf_data.json ]

Voraussetzung ist Python 3.10 oder neuer und eine Handvoll Bibliotheken:

python3 -m venv venv
source venv/bin/activate
pip install requests beautifulsoup4 html2text trafilatura lxml

Stufe 1 – Scrapen (`blog_scraper.py`)

Das Skript läuft Paginierungen, Archive, Sitemaps und einzelne Links ab und extrahiert nur den Haupttext eines Artikels, ohne Werbung, Sidebars und Footer. Trafilatura ist der präzise Hauptextraktor, html2text der Fallback, wenn Trafilatura leer zurückkommt. Jeder Artikel landet als .md unter domain/kategorie/.

# Variante A: von Hub-URLs mit Auto-Discovery interner Artikel
python3 blog_scraper.py --urls "https://example.com/blog/" --output-dir articles_output --threads 10

# Variante B: aus einer Linkliste
python3 blog_scraper.py --url-file my_urls.txt --output-dir articles_output --threads 15

Stufe 2 – Transformieren (`transform_to_okf.py`)

Diese Stufe bringt jede Datei auf das OKF-v0.2-Profil. Sie leitet den Typ aus Titel und URL ab (Guide, Tool, CaseStudy, Article), erzeugt Tags aus dem Themenfeld, zieht eine RAG-taugliche Beschreibung aus dem ersten echten Absatz und ergänzt die Vertrauensschicht: generated, verified, status, stale_after, sources.

python3 transform_to_okf.py

Das Ergebnis je Datei ist genau der Frontmatter aus dem Frontmatter-Schema – maschinell erzeugt, aber gültiges v0.2.

Stufe 3 – Kompilieren (`build_data_json.py`)

Die dritte Stufe fasst alle Konzepte in okf_data.json zusammen: die Datenbasis für Websuche, den D3-Wissensgraphen und den RAG-Assistenten. Parallel entstehen okf.md als Master-Index und llms.txt als Wegweiser für KI-Crawler.

python3 build_data_json.py
cp okf_data.json public/

Ein Detail, das Stufe 2 und 3 teilen: Die Aggregatdateien okf.md, INDEX.md, README.md werden nie als eigene Konzepte gelesen. Sie sind Navigation.

Der Git-native Workflow

Legen Sie articles_output/ in ein Repository. Jede Änderung an einem Konzept ist ein Commit, jede Ergänzung ein Pull Request. Weil resource, generated, verified und die Links im Klartext stehen, zeigt ein Diff exakt, was sich am Wissen geändert hat, nicht nur dass sich etwas geändert hat. Die Vertrauensfelder machen dabei sichtbar, ob eine Änderung von Hand oder aus der Pipeline kam.

Ein Bundle einem Nutzer zuweisen (Admin-CLI)

Für den Betrieb gibt es ein serverseitiges Skript, das ein fertiges Bundle direkt der privaten, verschlüsselten Ablage eines Nutzers zuweist, ohne dessen Monatslimit zu belasten. Der Nutzer muss sich vorher einmal angemeldet haben, damit seine Google-Kennung in der Datenbank steht.

node scripts/ingest.js <email> <pfad-zur-okf-datei>

Das Skript verschlüsselt das Bundle unter dem Per-User-Schlüssel des Empfängers und legt nur den Chiffretext auf S3 ab – dieselbe Mechanik, die jeder Upload nutzt, beschrieben unter Verschlüsselung.

Konformanz in CI prüfen

Der wertvollste Automatisierungsschritt ist ein Gate, das ein Bundle prüft, bevor es gemergt wird. Weil die Basis-Konformanz nur drei harte Regeln kennt, reicht Standard-Tooling. Die Regeln stehen auf der Validator-Seite: parsebarer YAML-Frontmatter, ein nicht-leeres type je Konzept, korrekt behandelte reservierte Dateien.

Ein GitHub-Actions-Workflow, der bei jedem Pull Request prüft, hat im Kern diese Form (illustrativ; die Prüflogik richten Sie nach Ihren Regeln ein):

name: okf-conformance
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - name: Frontmatter und type prüfen
        run: |
          # Jede nicht-reservierte .md muss gültigen Frontmatter
          # mit nicht-leerem type haben. Fehler => Exit-Code != 0.
          python scripts/check_okf.py ./articles_output

Das Prüfskript läuft die .md-Dateien ab, überspringt okf.md, INDEX.md, README.md, parst den Block zwischen den ersten beiden ----Zeilen als YAML und prüft type. Weiche Punkte – fehlende Beschreibung, fehlendes generated, kaputte Links – melden Sie als Warnung, ohne den Build zu brechen. Die Spec verlangt ausdrücklich, dass Konsumenten deswegen nichts ablehnen.

Als Artefakt veröffentlichen

Nach dem grünen Gate ist die Weitergabe ein Kopiervorgang: ein Tarball zum Download, okf_data.json plus llms.txt auf einem statischen Server, oder ein Upload in den OKF Knowledge Hub für Bibliothek, Graph und RAG. Der Hub-Upload läuft heute über die angemeldete Weboberfläche oder das Admin-Skript oben, nicht über eine öffentliche Schreib-API.

Weiter im Thema

Die Konformanzregeln stehen auf der Validator-Seite, das Zielschema im Frontmatter-Schema. Den Prompt, mit dem ein Modell Stufe 2 übernimmt, finden Sie unter Prompt-Vorlagen.

Pipeline nach dem realen OKF_AUTOMATION_GUIDE und den Skripten blog_scraper.py, transform_to_okf.py, build_data_json.py, scripts/ingest.js dieses Projekts. CI-Beispiel illustrativ. / Pipeline per this project's real OKF_AUTOMATION_GUIDE and the scripts. CI example is illustrative.