326 lines
18 KiB
Markdown
326 lines
18 KiB
Markdown
# Implementation Plan: Knowledge Management System
|
||
|
||
## Overview
|
||
|
||
Implementierung des vereinheitlichten Knowledge Management Systems als Erweiterung des bestehenden Monorepo-CLI. Die Umsetzung erfolgt inkrementell: zuerst die Kerninfrastruktur (Datenmodelle, Routing, Konfiguration), dann die Ingestion-Pipeline, Source-Strategien, Enrichment, Integrationen und abschließend die CLI-Schnittstelle.
|
||
|
||
**Sprache:** Python (konsistent mit dem bestehenden Monorepo-CLI)
|
||
**Pfade:**
|
||
- Ingestion-Pipeline: `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/`
|
||
- Source-Strategien: `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/`
|
||
- Integrationen: `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/`
|
||
- CLI: `shared/tools/monorepo-cli/src/monorepo/knowledge/cli.py`
|
||
- Knowledge-Ordner: `bahn/knowledge/`, `dhive/knowledge/`, `privat/knowledge/`
|
||
|
||
## Tasks
|
||
|
||
- [x] 1. Projekt-Struktur und Knowledge-Ordner anlegen
|
||
- [x] 1.1 Erstelle die Knowledge-Ordner-Struktur für alle drei Kontexte
|
||
- Erstelle `bahn/knowledge/`, `dhive/knowledge/`, `privat/knowledge/` mit Unterordnern: `inbox/`, `meetings/`, `decisions/`, `projects/`, `people/`, `references/`, `links/`
|
||
- Erstelle eine `index.md` pro Unterordner als Platzhalter-Inhaltsverzeichnis
|
||
- Erstelle eine leere `_index.yaml` und `sources.yaml` pro Kontext-Knowledge-Folder
|
||
- _Requirements: 1.1, 1.2, 1.6, 12.1_
|
||
|
||
- [x] 1.2 Erstelle die Modul-Struktur für die Ingestion-Pipeline
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/__init__.py`
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/__init__.py`
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/__init__.py`
|
||
- Erstelle leere Module: `pipeline.py`, `router.py`, `enrichment.py`, `capture.py`, `config.py`, `git_integration.py` im ingestion-Ordner
|
||
- _Requirements: 2.1_
|
||
|
||
- [x] 2. Datenmodelle und Konfiguration
|
||
- [x] 2.1 Erweitere ArtifactMetadata um Knowledge-Management-Felder
|
||
- Erweitere die bestehende `ArtifactMetadata`-Klasse in `artifact.py` um: `source` (dict), `category` (str), `people` (list), `projects` (list), `enrichment_pending` (bool), `ocr_failed` (bool), `fetch_failed` (bool)
|
||
- Stelle Rückwärtskompatibilität sicher (alle neuen Felder sind optional mit Defaults)
|
||
- Passe `parse`/`write`-Funktionen an, damit Round-Trip für erweiterte Felder funktioniert
|
||
- _Requirements: 1.5, 16.6_
|
||
|
||
- [x] 2.2 Property-Test: Artifact Serialization Round-Trip
|
||
- **Property 1: Artifact Serialization Round-Trip**
|
||
- **Validates: Requirements 16.6, 1.5**
|
||
|
||
- [x] 2.3 Implementiere SourceConfig und sources.yaml-Parsing
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/config.py`
|
||
- Implementiere `SourceConfig`-Dataclass mit Feldern: type, name, params, target_folder, sync_frequency, enabled
|
||
- Implementiere `load_sources_config(path: Path) -> list[SourceConfig]` zum Parsen der YAML-Datei
|
||
- Implementiere Umgebungsvariablen-Auflösung für `${VAR_NAME}`-Patterns in Werten
|
||
- Implementiere Validierung: fehlende Pflichtfelder, nicht auflösbare Env-Vars → Fehler
|
||
- _Requirements: 12.1, 12.2, 12.4, 12.6_
|
||
|
||
- [x] 2.4 Property-Test: Environment Variable Resolution
|
||
- **Property 21: Environment Variable Resolution in Config**
|
||
- **Validates: Requirements 12.4, 12.6**
|
||
|
||
- [x] 3. Context Router
|
||
- [x] 3.1 Implementiere ContextRouter
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/router.py`
|
||
- Implementiere `determine_context(source_config, cwd)` – leitet Kontext aus SourceConfig oder Arbeitsverzeichnis ab
|
||
- Implementiere `resolve_target_path(context, category, filename)` – berechnet `{root}/{context}/knowledge/{category}/{filename}`
|
||
- Implementiere Kategorie-zu-Ordner-Mapping: meeting→meetings/, decision→decisions/, project→projects/, reference→references/, link→links/, inbox→inbox/, unbekannt→inbox/
|
||
- _Requirements: 1.4, 2.3, 3.2, 3.5, 9.6_
|
||
|
||
- [x] 3.2 Property-Tests: Context Routing und Category Mapping
|
||
- **Property 2: Context Derivation from Path**
|
||
- **Property 6: Context Routing Determinism**
|
||
- **Property 8: Category to Folder Mapping**
|
||
- **Validates: Requirements 1.4, 2.3, 3.2, 3.5, 9.6**
|
||
|
||
- [x] 4. Checkpoint – Basis-Infrastruktur
|
||
- Ensure all tests pass, ask the user if questions arise.
|
||
|
||
- [x] 5. Quick Capture und Inbox
|
||
- [x] 5.1 Implementiere QuickCapture
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/capture.py`
|
||
- Implementiere `capture(input_text, context, tags)` – erzeugt Markdown-Datei in `{context}/knowledge/inbox/`
|
||
- Implementiere `_detect_input_type(input_text)` – erkennt ob Input eine URL, ein Dateipfad oder Freitext ist
|
||
- Implementiere `_generate_filename(title)` – erzeugt `YYYY-MM-DD-HH-MM-title-slug.md`
|
||
- Erzeuge minimales Frontmatter: title, created, source, type: inbox
|
||
- Gib den Dateipfad des erstellten Artefakts zurück
|
||
- _Requirements: 3.1, 3.2, 3.3, 3.7, 8.3_
|
||
|
||
- [x] 5.2 Property-Tests: Quick Capture
|
||
- **Property 7: Filename Pattern from Title**
|
||
- **Property 11: URL Detection in Quick Capture**
|
||
- **Validates: Requirements 3.3, 8.3**
|
||
|
||
- [x] 6. Source Strategies – Base und Markdown
|
||
- [x] 6.1 Implementiere SourceStrategy ABC und MarkdownSource
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/base.py` mit `SourceStrategy` ABC (extract, supports_incremental)
|
||
- Erstelle `ExtractionResult`-Dataclass und `SourceError`-Dataclass
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/markdown.py`
|
||
- Implementiere MarkdownSource: liest .md/.txt-Dateien, extrahiert bestehendes Frontmatter
|
||
- Unterstütze inkrementelle Verarbeitung via Content-Hash
|
||
- _Requirements: 2.2, 2.4, 2.7, 4.1_
|
||
|
||
- [x] 6.2 Property-Test: File Extension Format Detection
|
||
- **Property 9: File Extension Format Detection**
|
||
- **Validates: Requirements 4.7**
|
||
|
||
- [x] 6.3 Implementiere PDF- und OCR-Source
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/pdf.py`
|
||
- Implementiere PDF-Text-Extraktion (eingebetteter Text via PyPDF2 oder pdfplumber)
|
||
- Implementiere OCR-Fallback für gescannte Seiten (Kiro Vision als primärer Provider)
|
||
- Setze `ocr_failed: true` falls OCR fehlschlägt
|
||
- Behalte Referenz auf Originaldatei in `source.file`
|
||
- _Requirements: 4.2, 4.3, 4.4, 4.5, 4.6_
|
||
|
||
- [x] 6.4 Property-Test: Image Source File Reference
|
||
- **Property 10: Image Source File Reference Preservation**
|
||
- **Validates: Requirements 4.5**
|
||
|
||
- [x] 7. Source Strategies – Externe Quellen
|
||
- [x] 7.1 Implementiere Confluence-Source
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/confluence.py`
|
||
- Implementiere Confluence REST-API-Anbindung (Seiten, Bäume, FAQ-Spaces)
|
||
- Extrahiere Seiteninhalte als Markdown, reichere Frontmatter an (URL, Space, Titel, Last-Modified)
|
||
- Unterstütze inkrementelle Updates via Versions-Nummer
|
||
- Behandle API-Fehler graceful (skip source, log error)
|
||
- _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7_
|
||
|
||
- [x] 7.2 Implementiere Jira-Source
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/jira.py`
|
||
- Implementiere JQL-basierte Issue-Extraktion
|
||
- Stelle Issue als Markdown zusammen (Summary, Description, Kommentare, Status)
|
||
- Reichere Frontmatter an (Issue-Key, Projekt, Status, Assignee, Reporter, URL)
|
||
- Unterstütze inkrementelle Updates via `updated`-Feld
|
||
- _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.7_
|
||
|
||
- [x] 7.3 Implementiere Email- und Chat-Source
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/email.py`
|
||
- Implementiere .eml/.msg-Parsing (Absender, Empfänger, Betreff, Datum, Body)
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/chat.py`
|
||
- Implementiere Chat-Export-Parsing (Text/JSON)
|
||
- Verarbeite Anhänge als separate Artefakte mit Link im Eltern-Artefakt
|
||
- _Requirements: 7.1, 7.2, 7.3, 7.5, 7.6_
|
||
|
||
- [x] 7.4 Implementiere Link-Source und LinkRegistry
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/link.py`
|
||
- Implementiere `LinkRegistry`: save_link, search_links, _fetch_metadata, _find_existing
|
||
- Speichere Links als Artefakte vom Typ `link` in `links/`
|
||
- Implementiere URL-Deduplication mit Tag-Merging
|
||
- Implementiere Suche über URL, Titel, Tags
|
||
- Setze `fetch_failed: true` falls URL nicht erreichbar
|
||
- _Requirements: 8.1, 8.2, 8.4, 8.5, 8.6, 8.7_
|
||
|
||
- [x] 7.5 Property-Tests: Link Registry
|
||
- **Property 12: Link Artifact Structure**
|
||
- **Property 13: Link Deduplication with Tag Merging**
|
||
- **Property 14: Link Search Completeness**
|
||
- **Validates: Requirements 8.1, 8.2, 8.6, 8.7**
|
||
|
||
- [x] 7.6 Implementiere Wissensdatenbank-Source
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/wissensdatenbank.py`
|
||
- Implementiere Adapter für `bahn/wissensdatenbank/output/`
|
||
- Führe Artefakte als Read-Only-Referenzen im Index (`source: wissensdatenbank`)
|
||
- Lasse Originaldateien unverändert (kein Google-OKF-Reformat)
|
||
- _Requirements: 13.1, 13.2, 13.3, 13.4, 13.5_
|
||
|
||
- [x] 8. Checkpoint – Source Strategies
|
||
- Ensure all tests pass, ask the user if questions arise.
|
||
|
||
- [x] 9. Enrichment Agent
|
||
- [x] 9.1 Implementiere EnrichmentAgent
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/enrichment.py`
|
||
- Implementiere `enrich(content, source_type)` → EnrichmentResult (title, category, tags, people, projects, action_items, confidence)
|
||
- Implementiere `classify_relevance(content)` → float
|
||
- Implementiere Kiro-first Provider-Strategie (kein API-Key nötig im Normalfall)
|
||
- Implementiere Konfidenz-Schwelle: nur Entitäten ≥ 0.7 in Ausgabe
|
||
- Generiere Wiki-Links: `[[people/vorname-nachname]]`, `[[projects/projekt-slug]]`
|
||
- Generiere `## Action Items`-Abschnitt aus erkannten ActionItems
|
||
- Setze `enrichment_pending: true` falls Provider nicht erreichbar
|
||
- _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.7_
|
||
|
||
- [x] 9.2 Property-Tests: Enrichment
|
||
- **Property 15: Wiki-Link Format for Entities**
|
||
- **Property 16: Confidence Threshold Filtering**
|
||
- **Property 17: Action Items Section Generation**
|
||
- **Validates: Requirements 9.2, 9.4, 9.5**
|
||
|
||
- [x] 10. Ingestion Pipeline Orchestrator
|
||
- [x] 10.1 Implementiere IngestionPipeline
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/pipeline.py`
|
||
- Implementiere `run()`: load config → extract (via Strategies) → enrich → store → index → commit
|
||
- Implementiere `process_inbox()`: verarbeite alle Dateien in `{context}/knowledge/inbox/`
|
||
- Implementiere inkrementelle Verarbeitung via Content-Hash (skip unchanged)
|
||
- Implementiere Fail-Forward: einzelne Source-Fehler loggen, Rest weiterverarbeiten
|
||
- Aktualisiere `_index.yaml` nach jedem Durchlauf
|
||
- Aktualisiere `index.md` pro Unterordner (OKF-Konformität)
|
||
- Gib `IngestionResult` zurück (processed, updated, skipped, errors, tasks_created, commit_sha)
|
||
- _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6, 3.4, 3.5, 3.6, 12.3_
|
||
|
||
- [x] 10.2 Property-Tests: Ingestion Pipeline
|
||
- **Property 3: Idempotent Ingestion via Content Hash**
|
||
- **Property 4: Error Resilience – Partial Source Failure**
|
||
- **Property 5: Index Completeness After Ingestion**
|
||
- **Property 24: Ingestion Produces Valid Artifacts**
|
||
- **Validates: Requirements 2.2, 2.4, 2.5, 2.6**
|
||
|
||
- [x] 11. Integrationen
|
||
- [x] 11.1 Implementiere OrgMyLife-Integration
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/orgmylife.py`
|
||
- Implementiere `create_tasks(artifact_id, action_items, source_path)` → list[TaskMapping]
|
||
- Implementiere Deduplication via `.task-mapping.yaml` (Hash-basiert)
|
||
- Erstelle Tasks nur für neue Action-Items (nicht bereits gemappte)
|
||
- Setze Deadline falls im ActionItem erkannt
|
||
- Behandle API-Fehler graceful (Warnung loggen, weiter)
|
||
- _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6_
|
||
|
||
- [x] 11.2 Property-Test: Task Deduplication
|
||
- **Property 18: Task Deduplication via Mapping**
|
||
- **Validates: Requirements 10.5, 10.6**
|
||
|
||
- [x] 11.3 Implementiere Git-Auto-Commit-Integration
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/git_integration.py`
|
||
- Implementiere Commit-Message-Generierung im Format `knowledge({context}): {action} {count} artifacts from {source}`
|
||
- Implementiere `auto_commit(context, action, count, source, paths)` – staged + committed
|
||
- Respektiere `--no-commit`-Flag und `git.auto_commit`-Config
|
||
- Behandle Git-Fehler graceful (Warnung, Dateien bleiben)
|
||
- _Requirements: 16.1, 16.2, 16.3, 16.4, 16.5_
|
||
|
||
- [x] 11.4 Property-Test: Git Commit Message Format
|
||
- **Property 23: Git Commit Message Format**
|
||
- **Validates: Requirements 16.2**
|
||
|
||
- [x] 11.5 Implementiere Kiro-Client-Integration
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/kiro_client.py`
|
||
- Implementiere Wrapper für Kiro AI-Agent als LLM-Provider (Enrichment + OCR)
|
||
- Implementiere Fallback-Logik: Kiro nicht verfügbar → `enrichment_pending: true`
|
||
- _Requirements: 9.3, 9.7_
|
||
|
||
- [x] 12. Checkpoint – Pipeline und Integrationen
|
||
- Ensure all tests pass, ask the user if questions arise.
|
||
|
||
- [x] 13. Suche und Federation
|
||
- [x] 13.1 Erweitere die Suche um Knowledge-Folder-Support
|
||
- Erweitere `store.py` um kontextübergreifende Suche über alle `_index.yaml`-Dateien
|
||
- Implementiere Scope-Filterung (nur autorisierte Kontexte in Ergebnissen)
|
||
- Implementiere Agent-Context-Injection: max. 10 relevante Artefakt-Pfade, sortiert nach Relevanz
|
||
- Implementiere Progressive-Disclosure: Schicht 1 (Index) für Relevanz, Schicht 2 (Datei) bei Bedarf
|
||
- _Requirements: 11.1, 11.2, 11.3, 11.5, 11.6_
|
||
|
||
- [x] 13.2 Property-Tests: Suche
|
||
- **Property 19: Scope-Filtered Search Isolation**
|
||
- **Property 20: Context Injection Result Limit**
|
||
- **Validates: Requirements 11.5, 11.6**
|
||
|
||
- [x] 13.3 Implementiere Federation-Sync-Filter
|
||
- Erweitere die bestehende Federation-Logik um Knowledge-Ordner-Behandlung
|
||
- Exkludiere Artefakte mit `shareable: false` aus der Sync-Liste
|
||
- Exkludiere ctx-guard-markierte sensible Artefakte
|
||
- Stelle sicher, dass keine kontextübergreifenden Links in Team-Repos gelangen
|
||
- _Requirements: 14.1, 14.2, 14.3, 14.4, 14.5_
|
||
|
||
- [x] 13.4 Property-Test: Federation Sync Exclusion
|
||
- **Property 22: Federation Sync Exclusion**
|
||
- **Validates: Requirements 14.4**
|
||
|
||
- [x] 14. CLI-Schnittstelle
|
||
- [x] 14.1 Implementiere das knowledge-Subcommand
|
||
- Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/cli.py`
|
||
- Registriere als Subcommand-Gruppe unter dem Monorepo-CLI
|
||
- Implementiere `knowledge capture <text|url|path> [--context CTX] [--tags TAG,TAG]`
|
||
- Implementiere `knowledge ingest [--context CTX] [--dry-run] [--verbose] [--no-commit]`
|
||
- Implementiere `knowledge search <query> [--context CTX] [--limit N]`
|
||
- Implementiere `knowledge status [--context CTX]`
|
||
- Implementiere `knowledge link <url> [--title TITLE] [--tags TAG,TAG] [--context CTX]`
|
||
- Implementiere Hilfe-Ausgabe bei Aufruf ohne Argumente
|
||
- Leite Kontext aus `--context`-Flag oder CWD ab
|
||
- _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6, 15.7_
|
||
|
||
- [x] 14.2 Unit-Tests: CLI-Argument-Parsing
|
||
- Teste alle Subcommands mit verschiedenen Flag-Kombinationen
|
||
- Teste Kontext-Ableitung aus CWD
|
||
- Teste Hilfe-Ausgabe
|
||
- _Requirements: 15.2, 15.3, 15.7_
|
||
|
||
- [x] 15. End-to-End-Wiring und Integration
|
||
- [x] 15.1 Verdrahte alle Komponenten im Pipeline-Orchestrator
|
||
- Verbinde CLI → Router → Pipeline → Sources → Enrichment → Store → Index → Git
|
||
- Stelle sicher, dass `knowledge ingest` den vollständigen Workflow durchläuft
|
||
- Stelle sicher, dass `knowledge capture` → Inbox → nächster `ingest`-Durchlauf → Kategorisierung funktioniert
|
||
- Verbinde OrgMyLife-Integration (Task-Erstellung bei Action-Items)
|
||
- Aktualisiere `__init__.py` aller Module mit korrekten Exports
|
||
- _Requirements: 2.1, 2.2, 2.3, 3.4, 10.1_
|
||
|
||
- [x] 15.2 Integration-Tests: Full Pipeline E2E
|
||
- Teste vollständigen Pipeline-Durchlauf mit Fixture-Daten
|
||
- Teste Quick Capture → Inbox → Ingest → Kategorisierung
|
||
- Teste Confluence- und Jira-Source mit gemockten API-Responses
|
||
- _Requirements: 2.2, 2.3, 5.1, 6.1_
|
||
|
||
- [x] 16. Final Checkpoint – Alle Tests bestehen
|
||
- Ensure all tests pass, ask the user if questions arise.
|
||
|
||
## Notes
|
||
|
||
- Tasks mit `*` markiert sind optional und können für ein schnelleres MVP übersprungen werden
|
||
- Jede Task referenziert spezifische Requirements für Nachvollziehbarkeit
|
||
- Checkpoints sichern inkrementelle Validierung
|
||
- Property-Tests validieren universelle Korrektheitseigenschaften aus dem Design-Dokument
|
||
- Unit-Tests validieren spezifische Beispiele und Edge Cases
|
||
- Die bestehenden Module in `shared/tools/monorepo-cli/src/monorepo/knowledge/` (artifact.py, etl.py, index.py, store.py) werden wiederverwendet und erweitert – nicht neu geschrieben
|
||
- Kiro ist der primäre LLM/OCR-Provider; LiteLLM und Tesseract sind optionale Alternativen für CI/Batch
|
||
|
||
## Task Dependency Graph
|
||
|
||
```json
|
||
{
|
||
"waves": [
|
||
{ "id": 0, "tasks": ["1.1", "1.2"] },
|
||
{ "id": 1, "tasks": ["2.1", "2.3"] },
|
||
{ "id": 2, "tasks": ["2.2", "2.4", "3.1"] },
|
||
{ "id": 3, "tasks": ["3.2", "5.1"] },
|
||
{ "id": 4, "tasks": ["5.2", "6.1"] },
|
||
{ "id": 5, "tasks": ["6.2", "6.3", "7.4", "7.6"] },
|
||
{ "id": 6, "tasks": ["6.4", "7.1", "7.2", "7.3", "7.5"] },
|
||
{ "id": 7, "tasks": ["9.1"] },
|
||
{ "id": 8, "tasks": ["9.2", "10.1"] },
|
||
{ "id": 9, "tasks": ["10.2", "11.1", "11.3", "11.5"] },
|
||
{ "id": 10, "tasks": ["11.2", "11.4", "13.1", "13.3"] },
|
||
{ "id": 11, "tasks": ["13.2", "13.4", "14.1"] },
|
||
{ "id": 12, "tasks": ["14.2", "15.1"] },
|
||
{ "id": 13, "tasks": ["15.2"] }
|
||
]
|
||
}
|
||
```
|