Merge commit 'cfaf67010017eab368216aded483a64126dbcb2e' as 'bahn/wissensdatenbank'

2026-06-30 21:19:25 +02:00
parent be3da80cdc cfaf670100
commit 7b6ba4a280
4724 changed files with 667022 additions and 0 deletions
@@ -0,0 +1,65 @@
+# AGENTS.md – Leitfaden fuer KI-Agenten & Beitragende
+
+Kurzanleitung, um in diesem Repo sicher und konsistent zu arbeiten.
+
+## Was ist das hier?
+
+ETL-Pipeline fuer LLM/RAG: holt Wissen aus Confluence, Webseiten und PDFs,
+klassifiziert es nach **Scope** (intern/extern/allgemein) und **Domaene/Tool**,
+filtert vertrauliche Inhalte und gibt nur geprueftes Wissen frei.
+
+Verbindliche Architektur & Wissensfluss: **`.kiro/steering/architecture.md`**
+(bei Aenderungen am Fluss dort die Diagramme mitpflegen).
+
+## Projektstruktur
+
+```
+config/tools.yaml      Tool-Katalog (manuell gepflegt; Strategien/Scopes/Optionen)
+config/general.yaml    Allgemeines, tool-uebergreifendes Wissen (scope: allgemein)
+config/filter_rules.json  Blacklist + Redaction
+src/connectors/        Extract: confluence, web_crawler (crawler+sitemap), pdf_parser
+src/transformers/      md_converter, tagger, content_filter
+src/review/            Review-Gate (Routing approved/pending)
+src/main.py            Orchestrator
+src/site.py            GitLab-Pages-Seite -> public/ (Uebersicht, Hilfe, Chatbot, Wissensquellen)
+scripts/bootstrap_tools.py  EINMALIG: Tool-Katalog aus Support-Seite erzeugen
+tests/                 pytest (offline, kein Netz)
+```
+
+## Lokale Workflows
+
+```bash
+source .venv/bin/activate
+ruff check src tests scripts        # Lint (muss gruen sein)
+python -m pytest -q                 # Tests (muss gruen sein)
+python -m src.main --config config/tools.yaml --data output --staging staging   # ETL-Lauf
+python -m src.site --data output --staging staging --out public   # Pages-Vorschau (lokal)
+```
+
+Confluence braucht `CONFLUENCE_URL` + `CONFLUENCE_TOKEN` (PAT, Bearer) als Env.
+
+## Goldene Regeln (MUST)
+
+1. **Keine Secrets in Git/Code.** Tokens nur als Env-/CI-Variablen. `gitleaks` in CI.
+2. **Nur freigegebenes Wissen verlaesst die Pipeline** (`review_status: approved`).
+3. **`scope` ist Pflicht** an jedem Dokument; im Zweifel `intern` (restriktiv).
+4. **Output-Struktur** ist `output/processed/<scope>/<domaene>[/<tool>]` – nicht aendern,
+   ohne `architecture.md`, README und Tests anzupassen.
+5. **`config/tools.yaml` wird manuell gepflegt** (Bootstrap nur einmalig).
+6. Nach Codeaenderungen: `ruff` + `pytest` gruen, dann erst committen.
+
+## Scope-Klassifikation (intern vs. extern)
+
+- **Keine Trennung innerhalb einer Seite.** Klassifiziert wird pro Tool/Quelle.
+- **Tool-`scope`** in `tools.yaml`: `intern` | `extern` | `allgemein` | `mixed`
+  (mixed = Quellen mit unterschiedlichem Scope; im Zweifel zwei Seiten).
+- **Source-`scope`**: `intern` | `extern` | `allgemein` | `"intern,extern"`
+  (letzteres nutzt die ganze Seite fuer beide Scopes, dupliziert).
+- Quellen ohne eigenen Scope erben den Tool-Scope (mixed => intern).
+- Allgemeines Wissen steht in **`config/general.yaml`**.
+
+## Vorsicht bei Confluence-Schreibzugriffen
+
+Das Skript-Muster kann Confluence-Seiten anlegen/aendern (z.B. Option-A-Template).
+Solche Schreibzugriffe sind **additiv oder versioniert/revertierbar** zu halten und
+vorher anzukuendigen. Niemals Inhalte ungefragt loeschen.