252 lines
27 KiB
Markdown
252 lines
27 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
Dieses Dokument beschreibt die Anforderungen für ein vereinheitlichtes persönliches Wissensmanagement-System, das in die bestehende Monorepo-Struktur integriert wird. Das System ersetzt die nicht funktionierende NoteGraph-App und baut auf dem bereits implementierten Knowledge Store (ETL-Pipeline, YAML-Index, Scope-basierte Suche) sowie der NoteGraph-Ingestion-Pipeline (OCR, LLM-Enrichment, Entity-Detection) auf.
|
||
|
||
**Kernziel:** Wissen aus allen drei Arbeitskontexten (bahn, dhive, privat) erfassen, organisieren und für den AI-Orchestrator nutzbar machen – mit Quellen wie Markdown-Notizen, handschriftlichen Aufzeichnungen (reMarkable), Confluence, Jira, E-Mails, Chat-Exporten und Web-Links.
|
||
|
||
**Architekturentscheidungen:**
|
||
- Jeder Kontext erhält einen eigenen `knowledge/`-Ordner (kontextlokale Ablage)
|
||
- Eine gemeinsame Ingestion-Pipeline im shared-Bereich mit kontextbasiertem Routing
|
||
- Die bahn/wissensdatenbank bleibt als Upstream-Quelle bestehen; bahn/knowledge/ enthält zusätzlich persönliches Bahn-Wissen
|
||
- Workflow: Quick Capture → Inbox → Verarbeitung → Organisation
|
||
- **Google Open Knowledge Format (OKF)** als verbindliches Strukturprinzip für alle eigenen Wissensartefakte (privat, dhive, persönliches bahn-Wissen): ein Konzept pro Datei, Markdown mit YAML-Frontmatter, Cross-Links als Graph-Kanten, `index.md` pro Verzeichnis. Die Wissensdatenbank (Upstream DB-InfraGO) ist davon ausgenommen und behält ihr bestehendes Format.
|
||
|
||
## Glossary
|
||
|
||
- **Knowledge_Management_System**: Das Gesamtsystem zur Erfassung, Verarbeitung, Organisation und Abfrage von persönlichem Wissen über alle Arbeitskontexte hinweg
|
||
- **Kontext_Knowledge_Folder**: Der kontextspezifische Ordner (`bahn/knowledge/`, `dhive/knowledge/`, `privat/knowledge/`) zur lokalen Ablage verarbeiteter Wissensartefakte
|
||
- **Ingestion_Pipeline**: Die gemeinsame Verarbeitungspipeline im shared-Bereich, die Rohdaten aus verschiedenen Quellen in strukturierte Wissensartefakte transformiert
|
||
- **Inbox**: Der Eingangsordner pro Kontext (`{context}/knowledge/inbox/`), in dem unverarbeitete Rohdaten und Quick-Captures landen
|
||
- **Quellstrategie**: Ein austauschbarer Adapter, der eine bestimmte Quelle (Confluence, Jira, E-Mail, Markdown, etc.) anbindet und Rohdaten extrahiert
|
||
- **Wissensartefakt**: Eine strukturierte Markdown-Datei mit YAML-Frontmatter, die ein einzelnes Wissenselement repräsentiert (Notiz, Meeting-Protokoll, Entscheidung, Referenz, Link)
|
||
- **YAML_Index**: Der maschinenlesbare Index pro Kontext-Knowledge-Folder, der kompakte Metadaten aller Artefakte enthält (Progressive Disclosure Schicht 1)
|
||
- **Enrichment_Agent**: Die LLM-gestützte Komponente, die Rohdaten analysiert, Entitäten erkennt, Tags generiert und Artefakte kategorisiert
|
||
- **Quick_Capture**: Der vereinfachte Erfassungsmechanismus für schnelle Notizen, Links oder Ideen ohne manuelle Metadaten-Eingabe
|
||
- **Kontext_Router**: Die Komponente, die eingehende Daten anhand von Quelltyp und Konfiguration dem richtigen Arbeitskontext zuordnet
|
||
- **Link_Registry**: Die Verwaltung gespeicherter Web-Links als Referenzmaterial mit Tags und Kontext-Zuordnung
|
||
- **Federation_Sync**: Der Mechanismus, der kontextlokales Wissen mit dem jeweiligen Team-Repo synchronisiert
|
||
- **OCR_Engine**: Die Komponente zur Texterkennung aus Bildern und gescannten PDFs (reMarkable-Exporte, Whiteboard-Fotos)
|
||
- **Wissensdatenbank**: Die bestehende ETL-Pipeline in `bahn/wissensdatenbank/` für DB-InfraGO-Wissen (Confluence, Web, PDFs)
|
||
- **Google_OKF**: Das Google Open Knowledge Format – ein Strukturprinzip für Wissensartefakte: ein Konzept pro Datei, Markdown mit YAML-Frontmatter, Cross-Links als Graph-Kanten, `index.md` pro Verzeichnis für Inhaltsübersichten. Verbindlich für alle eigenen Artefakte (privat, dhive, persönliches bahn-Wissen); nicht verbindlich für Upstream-Wissensdatenbank-Artefakte
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: Kontextlokale Wissensordner-Struktur
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich in jedem Arbeitskontext einen dedizierten Knowledge-Ordner haben, damit mein Wissen kontextnah organisiert ist und die Sicherheitsgrenzen des Monorepos automatisch greifen.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Knowledge_Management_System SHALL für jeden Arbeitskontext (bahn, dhive, privat) einen eigenen Kontext_Knowledge_Folder unter `{context}/knowledge/` bereitstellen
|
||
2. THE Kontext_Knowledge_Folder SHALL folgende Unterordner enthalten: `inbox/`, `meetings/`, `decisions/`, `projects/`, `people/`, `references/`, `links/`
|
||
3. THE Kontext_Knowledge_Folder SHALL einen eigenen YAML_Index (`_index.yaml`) bereitstellen, der alle lokalen Artefakte mit kompakten Metadaten (Titel, Tags, Typ, Erstelldatum, Content-Hash, Verknüpfungen) indexiert
|
||
4. WHEN ein Wissensartefakt in einem Kontext_Knowledge_Folder erstellt wird, THE Knowledge_Management_System SHALL den Quellkontext automatisch aus dem Dateipfad ableiten und im YAML-Frontmatter als `source_context` eintragen
|
||
5. THE Kontext_Knowledge_Folder SHALL die bestehende Artefakt-Struktur des Knowledge Store verwenden: Markdown-Dateien mit YAML-Frontmatter (mindestens type, title, tags, source_context, created, content_hash, links)
|
||
6. THE Kontext_Knowledge_Folder SHALL dem Google_OKF folgen: ein Konzept pro Datei, Cross-Links als Graph-Kanten im Frontmatter, und eine `index.md`-Datei pro Unterordner, die als Inhaltsverzeichnis dient und bei jedem Ingestion-Durchlauf aktualisiert wird
|
||
7. WHILE der bestehende Knowledge Store im shared-Bereich existiert, THE Knowledge_Management_System SHALL die Kontext_Knowledge_Folder als primäre Ablageorte verwenden und den shared Knowledge Store als übergreifenden Suchindex beibehalten
|
||
|
||
### Requirement 2: Gemeinsame Ingestion-Pipeline mit Kontext-Routing
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich eine einheitliche Verarbeitungspipeline für alle Quellen haben, die eingehende Daten automatisch dem richtigen Kontext zuordnet, damit ich nicht für jeden Kontext separate Tools betreiben muss.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Ingestion_Pipeline SHALL als gemeinsames Modul im shared-Bereich (`shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/`) implementiert werden
|
||
2. THE Ingestion_Pipeline SHALL Rohdaten aus einer konfigurierbaren Menge von Quellstrategien entgegennehmen und in strukturierte Wissensartefakte transformieren
|
||
3. WHEN Rohdaten verarbeitet werden, THE Kontext_Router SHALL den Zielkontext anhand der Quellkonfiguration bestimmen und das resultierende Artefakt im entsprechenden Kontext_Knowledge_Folder ablegen
|
||
4. THE Ingestion_Pipeline SHALL inkrementelle Verarbeitung über Content-Hashes unterstützen, wobei nur neue oder geänderte Inhalte verarbeitet werden
|
||
5. WHEN die Verarbeitung einer einzelnen Quelle fehlschlägt, THE Ingestion_Pipeline SHALL den Fehler mit Quellidentifikator und Zeitstempel protokollieren und mit den verbleibenden Quellen fortfahren
|
||
6. THE Ingestion_Pipeline SHALL nach jedem Verarbeitungsdurchlauf den YAML_Index des betroffenen Kontext_Knowledge_Folders aktualisieren, sodass neue Artefakte sofort auffindbar sind
|
||
7. THE Ingestion_Pipeline SHALL die bestehenden ETL-Quellstrategien der Wissensdatenbank wiederverwenden können (confluence_page, confluence_tree, crawler, sitemap, gitlab_md, file, pdf)
|
||
|
||
### Requirement 3: Quick Capture und Inbox-Workflow
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich schnell Notizen, Links und Ideen erfassen können, die später automatisch verarbeitet und eingeordnet werden, damit ich im Arbeitsfluss bleibe und nichts verloren geht.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Quick_Capture SHALL eine CLI-Schnittstelle bereitstellen (`knowledge capture`), die einen Freitext, eine URL oder einen Dateipfad entgegennimmt und als Rohartefakt in der Inbox des angegebenen Kontexts ablegt
|
||
2. WHEN kein Kontext explizit angegeben wird, THE Quick_Capture SHALL den Kontext aus dem aktuellen Arbeitsverzeichnis ableiten
|
||
3. THE Quick_Capture SHALL das erfasste Element mit minimalem Frontmatter (title, created, source, type: inbox) als Markdown-Datei im Format `YYYY-MM-DD-HH-MM-title-slug.md` in `{context}/knowledge/inbox/` ablegen
|
||
4. THE Inbox SHALL einen Drop-Folder-Mechanismus bereitstellen, der neue Dateien im Inbox-Ordner automatisch erkennt und zur Verarbeitung durch die Ingestion_Pipeline einreiht
|
||
5. WHEN ein Inbox-Element von der Ingestion_Pipeline verarbeitet wird, THE Enrichment_Agent SHALL das Element analysieren, kategorisieren und in den passenden Unterordner des Kontext_Knowledge_Folders verschieben (meetings, decisions, projects, references)
|
||
6. IF der Enrichment_Agent keine klare Kategorie bestimmen kann, THEN THE Ingestion_Pipeline SHALL das Artefakt im `inbox/`-Ordner belassen und mit dem Tag `unclassified` versehen
|
||
7. WHEN ein Quick_Capture ein erfolgreich abgelegt wird, THE Quick_Capture SHALL den Dateipfad des erstellten Artefakts auf der Konsole ausgeben
|
||
|
||
### Requirement 4: Multi-Source-Ingestion – Markdown und Dateien
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich Markdown-Dateien, PDFs und Bilder (reMarkable-Exporte, Whiteboard-Fotos) als Wissensquellen importieren können, damit meine handschriftlichen Notizen und Dokumente durchsuchbar werden.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN eine Markdown-Datei als Quelle bereitgestellt wird, THE Ingestion_Pipeline SHALL den Inhalt inklusive bestehendem Frontmatter einlesen und als Wissensartefakt verarbeiten
|
||
2. WHEN eine Bilddatei (PNG, JPG, JPEG) als Quelle bereitgestellt wird, THE OCR_Engine SHALL den Text mittels OCR extrahieren und der Ingestion_Pipeline als Rohtext übergeben
|
||
3. WHEN eine PDF-Datei als Quelle bereitgestellt wird, THE Ingestion_Pipeline SHALL eingebetteten Text direkt extrahieren und für gescannte Seiten die OCR_Engine einsetzen
|
||
4. THE OCR_Engine SHALL für die Sprachkombination Deutsch und Englisch (`deu+eng`) konfiguriert sein
|
||
5. WHEN der Enrichment_Agent ein Bild-basiertes Artefakt verarbeitet, THE Enrichment_Agent SHALL eine Referenz auf die Originaldatei im Frontmatter-Feld `source.file` beibehalten
|
||
6. IF die OCR_Engine keinen lesbaren Text aus einem Bild extrahieren kann, THEN THE Ingestion_Pipeline SHALL das Artefakt mit leerem Textinhalt erstellen und im Frontmatter das Feld `ocr_failed: true` setzen
|
||
7. THE Ingestion_Pipeline SHALL die Dateiformat-Erkennung anhand der Dateiendung vornehmen und folgende Formate unterstützen: `.md`, `.txt`, `.pdf`, `.png`, `.jpg`, `.jpeg`, `.docx`
|
||
|
||
### Requirement 5: Multi-Source-Ingestion – Confluence
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich Confluence-Seiten und -Bäume als Wissensquellen einbinden, damit relevantes Team-Wissen aus Confluence automatisch in meinem persönlichen Wissensspeicher verfügbar ist.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Ingestion_Pipeline SHALL eine Quellstrategie für Confluence bereitstellen, die einzelne Seiten, Seitenbäume und FAQ-Spaces importieren kann
|
||
2. WHEN eine Confluence-Quelle konfiguriert wird, THE Quellstrategie SHALL die Confluence-REST-API verwenden und Seiteninhalte als Markdown extrahieren
|
||
3. THE Quellstrategie SHALL pro Kontext eine separate Confluence-Instanz-Konfiguration unterstützen (bahn: DB-Confluence, dhive: dhive-Confluence)
|
||
4. WHEN eine Confluence-Seite aktualisiert wurde (erkannt über Versions-Nummer oder Last-Modified), THE Ingestion_Pipeline SHALL das zugehörige Artefakt inkrementell aktualisieren
|
||
5. THE Quellstrategie SHALL das Confluence-Seiten-Frontmatter mit Quell-URL, Space-Key, Seitentitel und letztem Aktualisierungsdatum anreichern
|
||
6. WHEN eine Confluence-Seite Anhänge enthält, THE Quellstrategie SHALL Anhänge als Referenz-Links im Artefakt vermerken
|
||
7. IF die Confluence-API nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL den Fehler protokollieren und den Verarbeitungsdurchlauf für diese Quelle überspringen, ohne bestehende Artefakte zu löschen
|
||
|
||
### Requirement 6: Multi-Source-Ingestion – Jira
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich Jira-Issues und deren Kommentare als Wissensartefakte importieren, damit Entscheidungen und Diskussionen aus Jira-Tickets in meinem Wissensspeicher auffindbar sind.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Ingestion_Pipeline SHALL eine Quellstrategie für Jira bereitstellen, die Issues anhand von JQL-Filtern importiert
|
||
2. WHEN ein Jira-Issue importiert wird, THE Quellstrategie SHALL Summary, Description, Kommentare und Status als strukturiertes Markdown-Artefakt zusammenstellen
|
||
3. THE Quellstrategie SHALL das Artefakt-Frontmatter mit Issue-Key, Projekt, Status, Assignee, Reporter und Jira-URL anreichern
|
||
4. WHEN ein Jira-Issue seit dem letzten Import aktualisiert wurde (erkannt über `updated`-Feld), THE Ingestion_Pipeline SHALL das zugehörige Artefakt inkrementell aktualisieren
|
||
5. THE Quellstrategie SHALL konfigurierbare JQL-Filter pro Kontext unterstützen (z.B. `project = ACV2 AND updatedDate > -7d` für bahn)
|
||
6. WHEN Jira-Kommentare Action-Items enthalten (erkannt über den Enrichment_Agent), THE Ingestion_Pipeline SHALL diese als TODO-Einträge im Artefakt markieren
|
||
7. IF die Jira-API nicht erreichbar ist oder die Authentifizierung fehlschlägt, THEN THE Ingestion_Pipeline SHALL den Fehler mit API-Endpunkt protokollieren und den Verarbeitungsdurchlauf für diese Quelle überspringen
|
||
|
||
### Requirement 7: Multi-Source-Ingestion – E-Mail und Chat
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich relevante E-Mail-Threads und Chat-Nachrichten als Wissensartefakte importieren, damit wichtige Informationen aus der Kommunikation nicht verloren gehen.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Ingestion_Pipeline SHALL eine Quellstrategie für E-Mails bereitstellen, die exportierte E-Mail-Dateien (`.eml`, `.msg`) oder Ordner mit E-Mails verarbeitet
|
||
2. WHEN eine E-Mail verarbeitet wird, THE Quellstrategie SHALL Absender, Empfänger, Betreff, Datum und Body als strukturiertes Markdown-Artefakt zusammenstellen
|
||
3. THE Ingestion_Pipeline SHALL eine Quellstrategie für Chat-Exporte bereitstellen, die Textdateien oder JSON-Exporte aus Chat-Systemen verarbeitet
|
||
4. WHEN der Enrichment_Agent eine E-Mail oder Chat-Nachricht analysiert, THE Enrichment_Agent SHALL explizit nach Action-Items, Entscheidungen und Deadlines suchen
|
||
5. THE Quellstrategie SHALL das Artefakt-Frontmatter mit Absender, Empfänger-Liste, Datum und Thread-Referenz anreichern
|
||
6. WHEN eine E-Mail Anhänge enthält, THE Quellstrategie SHALL Anhänge als separate Artefakte verarbeiten und über Links im Eltern-Artefakt referenzieren
|
||
7. IF eine E-Mail oder Chat-Nachricht keine verwertbare Information enthält (vom Enrichment_Agent als irrelevant klassifiziert), THEN THE Ingestion_Pipeline SHALL das Element überspringen und im Verarbeitungsprotokoll als `skipped: low-relevance` vermerken
|
||
|
||
### Requirement 8: Link-Management
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich Web-Links als Referenzmaterial speichern und taggen können, damit ich wichtige Ressourcen pro Kontext organisiert wiederfinde.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Link_Registry SHALL Web-Links als Wissensartefakte vom Typ `link` im `links/`-Unterordner des jeweiligen Kontext_Knowledge_Folders speichern
|
||
2. WHEN ein Link gespeichert wird, THE Link_Registry SHALL die URL, einen optionalen Titel, Tags und den Speicherzeitpunkt im YAML-Frontmatter erfassen
|
||
3. THE Quick_Capture SHALL URLs automatisch erkennen und als Link-Artefakte behandeln, wenn der eingegebene Text eine gültige HTTP(S)-URL ist
|
||
4. WHEN ein Link-Artefakt erstellt wird, THE Ingestion_Pipeline SHALL versuchen den Seitentitel und eine Kurzbeschreibung von der Ziel-URL zu extrahieren (via HTTP-Request auf die Seite)
|
||
5. IF die Ziel-URL nicht erreichbar ist, THEN THE Link_Registry SHALL den Link dennoch speichern, mit dem vom Nutzer angegebenen Titel und dem Frontmatter-Feld `fetch_failed: true`
|
||
6. THE Link_Registry SHALL eine Suche über gespeicherte Links nach URL, Titel und Tags unterstützen
|
||
7. THE Link_Registry SHALL duplikate URLs innerhalb eines Kontexts erkennen und bei erneutem Speichern die Tags des bestehenden Artefakts ergänzen statt ein neues Artefakt zu erstellen
|
||
|
||
### Requirement 9: LLM-gestützte Anreicherung und Kategorisierung
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich, dass importierte Inhalte automatisch mit Tags, Kategorien und erkannten Entitäten angereichert werden, damit ich weniger manuelle Metadaten-Pflege betreiben muss.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN ein Rohartefakt verarbeitet wird, THE Enrichment_Agent SHALL den Inhalt analysieren und folgende Metadaten generieren: Titel (sofern nicht vorhanden), Kategorie (meeting, decision, project, reference, inbox), Tags, erkannte Personen und Projekte
|
||
2. THE Enrichment_Agent SHALL erkannte Personen als Wiki-Links im Format `[[people/vorname-nachname]]` und Projekte als `[[projects/projekt-slug]]` in den Artefakt-Body einfügen
|
||
3. THE Enrichment_Agent SHALL die modell-agnostische LLM-Schicht (LiteLLM) verwenden und über Umgebungsvariablen (`LLM_PROVIDER`, `LLM_MODEL`) konfigurierbar sein
|
||
4. WHEN der Enrichment_Agent Action-Items im Text erkennt, THE Enrichment_Agent SHALL diese in einem `## Action Items`-Abschnitt am Ende des Artefakts zusammenfassen
|
||
5. THE Enrichment_Agent SHALL Entitäten nur mit einer Konfidenz von 0.7 oder höher in die Ausgabe übernehmen
|
||
6. WHEN der Enrichment_Agent ein Artefakt kategorisiert hat, THE Ingestion_Pipeline SHALL die Zielordner-Zuordnung aus der Kategorie ableiten (meeting → meetings/, decision → decisions/, project → projects/, link → links/, default → inbox/)
|
||
7. IF der LLM-Provider nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL das Artefakt mit minimalen Metadaten (Titel aus Dateiname, Kategorie `inbox`) im Inbox-Ordner ablegen und im Frontmatter `enrichment_pending: true` setzen
|
||
|
||
### Requirement 10: OrgMyLife-Integration und Action-Item-Extraktion
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich, dass erkannte Action-Items automatisch als Tasks in OrgMyLife erstellt werden, damit Aufgaben aus Meetings und E-Mails nicht verloren gehen.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN der Enrichment_Agent Action-Items in einem Artefakt erkennt, THE Ingestion_Pipeline SHALL optional für jedes Action-Item einen Task in OrgMyLife erstellen (steuerbar über Konfigurationsflag `create_tasks`)
|
||
2. WHEN ein OrgMyLife-Task erstellt wird, THE Ingestion_Pipeline SHALL den Task-Titel auf die Action-Item-Beschreibung setzen und im Feld `source_url` einen Verweis auf das Quell-Artefakt hinterlegen
|
||
3. WHEN ein Action-Item eine erkannte Deadline enthält, THE Ingestion_Pipeline SHALL das Fälligkeitsdatum im OrgMyLife-Task setzen
|
||
4. IF die OrgMyLife-API nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL eine Warnung protokollieren und die Verarbeitung ohne Task-Erstellung fortsetzen
|
||
5. THE Ingestion_Pipeline SHALL bereits erstellte Tasks nicht duplizieren, indem sie eine Mapping-Datei (`{context}/knowledge/.task-mapping.yaml`) führt, die Artefakt-ID und Action-Item-Hash auf OrgMyLife-Task-IDs abbildet
|
||
6. WHEN ein Artefakt erneut verarbeitet wird und neue Action-Items enthält, THE Ingestion_Pipeline SHALL nur für bisher nicht erfasste Action-Items neue Tasks erstellen
|
||
|
||
### Requirement 11: Kontextübergreifende Suche und Agent-Context-Injection
|
||
|
||
**User Story:** Als Wissensarbeiter und als AI-Orchestrator möchte ich relevantes Wissen aus dem aktiven Kontext in Agenten-Prompts injizieren, damit der Agent fundierte Antworten auf Basis meines persönlichen Wissens geben kann.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Knowledge_Management_System SHALL eine einheitliche Suchschnittstelle bereitstellen, die über alle Kontext_Knowledge_Folder und den shared Knowledge Store sucht, gefiltert nach autorisierten Scopes
|
||
2. WHEN der AI-Orchestrator einen Task-Prompt zusammenstellt, THE Knowledge_Management_System SHALL die relevantesten Artefakte aus dem YAML_Index des aktiven Kontexts identifizieren und deren Pfade als Kontextinformation bereitstellen
|
||
3. THE Knowledge_Management_System SHALL die Suche über den Progressive-Disclosure-Ansatz realisieren: Schicht 1 (YAML_Index mit kompakten Metadaten) für schnelle Relevanzprüfung, Schicht 2 (vollständiges Dokument) nur bei Bedarf
|
||
4. WHEN eine Suchanfrage gestellt wird, THE Knowledge_Management_System SHALL Ergebnisse innerhalb von 5 Sekunden zurückgeben und bei Timeout-Überschreitung Teilergebnisse mit einer `partial_results`-Markierung liefern
|
||
5. THE Knowledge_Management_System SHALL die Sicherheitsgrenzen des ctx-guard-Systems respektieren und ausschließlich Artefakte aus autorisierten Kontexten in Suchergebnissen und Agent-Prompts berücksichtigen
|
||
6. WHEN der AI-Orchestrator Kontext injiziert, THE Knowledge_Management_System SHALL maximal 10 relevante Artefakt-Pfade pro Anfrage zurückliefern, sortiert nach Relevanz-Score
|
||
|
||
### Requirement 12: Quellkonfiguration pro Kontext
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich pro Kontext definieren, welche Quellen regelmäßig importiert werden sollen, damit der Wissensimport automatisiert und kontextspezifisch abläuft.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Knowledge_Management_System SHALL eine Konfigurationsdatei pro Kontext bereitstellen (`{context}/knowledge/sources.yaml`), die alle aktiven Quellstrategien mit ihren Parametern definiert
|
||
2. THE Konfigurationsdatei SHALL pro Quellstrategie folgende Felder unterstützen: Typ (confluence, jira, email, file, link), Verbindungsparameter, Filterkriterien, Sync-Frequenz und Zielordner
|
||
3. WHEN die Ingestion_Pipeline gestartet wird, THE Ingestion_Pipeline SHALL alle in der `sources.yaml` des angegebenen Kontexts konfigurierten Quellen sequentiell verarbeiten
|
||
4. THE Konfigurationsdatei SHALL Secrets über Umgebungsvariablen-Referenzen einbinden (z.B. `api_key: ${JIRA_API_TOKEN}`) statt Klartext-Credentials zu enthalten
|
||
5. WHEN eine neue Quellstrategie zur Konfiguration hinzugefügt wird, THE Ingestion_Pipeline SHALL beim nächsten Durchlauf einen vollständigen Initial-Import dieser Quelle durchführen
|
||
6. THE Knowledge_Management_System SHALL eine Validierung der `sources.yaml` bereitstellen, die fehlende Pflichtfelder und nicht-auflösbare Umgebungsvariablen vor dem Start der Verarbeitung erkennt
|
||
|
||
### Requirement 13: Wissensdatenbank-Integration (bahn-Kontext)
|
||
|
||
**User Story:** Als Wissensarbeiter im bahn-Kontext möchte ich, dass die bestehende Wissensdatenbank als Upstream-Quelle in mein Knowledge-System einfließt, damit ich DB-InfraGO-Wissen zusammen mit meinen persönlichen bahn-Notizen durchsuchen kann.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Knowledge_Management_System SHALL die Wissensdatenbank (`bahn/wissensdatenbank/output/`) als Quellstrategie vom Typ `wissensdatenbank` für den bahn-Kontext einbinden
|
||
2. WHEN die Wissensdatenbank aktualisiert wird (via Upstream-Sync), THE Ingestion_Pipeline SHALL geänderte Artefakte im bahn/knowledge/ YAML_Index aktualisieren, ohne die Originaldateien in `bahn/wissensdatenbank/` zu verändern
|
||
3. THE Quellstrategie SHALL Artefakte aus der Wissensdatenbank als Read-Only-Referenzen im bahn-Knowledge-Index führen, mit dem Frontmatter-Feld `source: wissensdatenbank` und einer Referenz auf den Originalpfad
|
||
4. THE Quellstrategie SHALL Wissensdatenbank-Artefakte in ihrem Originalformat belassen und NICHT dem Google_OKF-Strukturprinzip unterwerfen (kein Splitting in Ein-Konzept-pro-Datei, keine erzwungene index.md-Generierung für Wissensdatenbank-Inhalte)
|
||
5. THE Knowledge_Management_System SHALL persönliche bahn-Notizen (Meetings, Entscheidungen) separat von Wissensdatenbank-Artefakten im bahn/knowledge/ ablegen, wobei persönliche Artefakte dem Google_OKF folgen und beide über den YAML_Index durchsuchbar sind
|
||
6. WHEN ein Wissensdatenbank-Artefakt und ein persönliches bahn-Artefakt thematisch verknüpft sind, THE Knowledge_Management_System SHALL bidirektionale Links zwischen beiden im YAML_Index unterstützen
|
||
|
||
### Requirement 14: Federation und Team-Repo-Synchronisation
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich, dass mein kontextlokales Wissen über die bestehende Föderationsstruktur mit dem jeweiligen Team-Repo synchronisiert wird, damit relevantes Wissen auch im Team-Kontext verfügbar ist.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN der Kontext_Knowledge_Folder eines Kontexts aktualisiert wird, THE Federation_Sync SHALL die Änderungen im Rahmen der regulären Team-Repo-Synchronisation (gemäß monorepo-consolidation Req 10) mit dem zugehörigen Team-Repo synchronisieren
|
||
2. THE Federation_Sync SHALL die bestehende `team-repos.yaml`-Konfiguration respektieren und den Knowledge-Ordner als Teil des Kontextordners behandeln (keine separate Sync-Konfiguration nötig)
|
||
3. WHILE Artefakte synchronisiert werden, THE Knowledge_Management_System SHALL sicherstellen, dass keine kontextübergreifenden Links oder Referenzen auf andere Kontexte in das Team-Repo gelangen
|
||
4. THE Knowledge_Management_System SHALL Artefakte mit dem Frontmatter-Feld `shareable: false` von der Federation-Synchronisation ausschließen
|
||
5. IF ein Artefakt sensible Inhalte enthält (erkannt über den bestehenden ctx-guard-Mechanismus), THEN THE Federation_Sync SHALL das Artefakt von der Synchronisation ausschließen und dies im Sync-Protokoll vermerken
|
||
|
||
### Requirement 15: CLI-Schnittstelle
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich alle Knowledge-Management-Operationen über eine konsistente CLI-Schnittstelle ausführen, damit ich Wissen effizient von der Kommandozeile aus verwalten kann.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Knowledge_Management_System SHALL eine CLI-Schnittstelle als Unterkommando des Monorepo-CLI bereitstellen (`monorepo knowledge` oder `knowledge`)
|
||
2. THE CLI SHALL folgende Unterkommandos unterstützen: `capture` (Quick-Capture), `ingest` (Pipeline-Durchlauf starten), `search` (Suche über Knowledge-Index), `status` (Übersicht über Inbox-Elemente und letzte Verarbeitung)
|
||
3. THE CLI SHALL den aktiven Kontext über das Flag `--context` oder automatisch aus dem aktuellen Arbeitsverzeichnis ableiten
|
||
4. WHEN das Unterkommando `ingest` ausgeführt wird, THE CLI SHALL die `sources.yaml` des aktiven Kontexts laden und alle konfigurierten Quellen verarbeiten
|
||
5. THE CLI SHALL die Flags `--dry-run` (Vorschau ohne Schreiboperationen), `--verbose` (detaillierte Ausgabe) und `--no-commit` (Git-Commit überspringen) unterstützen
|
||
6. WHEN das Unterkommando `search` mit einem Suchbegriff ausgeführt wird, THE CLI SHALL die Ergebnisse mit Titel, Typ, Tags und Dateipfad auf der Konsole ausgeben
|
||
7. WHEN das CLI ohne Argumente aufgerufen wird, THE CLI SHALL eine Hilfe-Nachricht mit verfügbaren Unterkommandos und Beispielen anzeigen
|
||
|
||
### Requirement 16: Git-Integration und Versionierung
|
||
|
||
**User Story:** Als Wissensarbeiter möchte ich, dass alle Wissensänderungen automatisch versioniert werden, damit ich die Historie meines Wissensspeichers nachvollziehen und bei Bedarf zurückspringen kann.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN die Ingestion_Pipeline neue oder aktualisierte Artefakte erzeugt, THE Knowledge_Management_System SHALL diese automatisch mit einer beschreibenden Commit-Message in Git committen
|
||
2. THE Knowledge_Management_System SHALL die Commit-Message im Format `knowledge({context}): {action} {count} artifacts from {source}` generieren (z.B. `knowledge(bahn): ingest 3 artifacts from confluence`)
|
||
3. WHEN der Quick_Capture ein neues Artefakt erstellt, THE Knowledge_Management_System SHALL einen separaten Commit mit der Message `knowledge({context}): capture "{title}"` erzeugen
|
||
4. WHEN das Flag `--no-commit` gesetzt ist, THE Knowledge_Management_System SHALL keine Git-Commits erzeugen
|
||
5. IF ein Git-Commit fehlschlägt, THEN THE Knowledge_Management_System SHALL eine Warnung protokollieren, die erstellten Dateien beibehalten und die Verarbeitung fortsetzen
|
||
6. FOR ALL gültige Artefakt-Inhalte, das Schreiben in eine Markdown-Datei mit YAML-Frontmatter und anschließendes Einlesen SHALL ein identisches ArtifactMetadata-Objekt reproduzieren (Round-Trip-Eigenschaft)
|