66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
# 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.
|