Skill Knowledge Bordnetz Vobes

Der RAG-MCP-Server local-rag stellt zwei Tool-Arten zur Verfügung:

1. Retrieval-Tool für Suche/Kontextaufbau
2. Readback-Tools zum gezielten Nachladen von Dokument- oder Attachment-Inhalten aus der Datenbank

CLI-Fallback fuer Debugging und manuelle Verifikation:

• Fuer normale Skill-Nutzung verwende weiterhin direkt die MCP-Tools.
• Wenn du Tool-Namen oder Tool-Argumente ausserhalb eines MCP-Clients pruefen musst, nutze den Workspace-Wrapper python scripts/query_local_rag.py ....
• Der Wrapper startet query_rag_mcp in einem Unterprozess mit cwd=C:\Daten\Python\lightrag_test und fuehrt danach keinen persistenten Verzeichniswechsel im aktuellen Agenten-Kontext aus.
• Vorhandener Modus chat des Zielmoduls bleibt bestehen.
• Neue generische Modi:
  • python scripts/query_local_rag.py list-tools
  • python scripts/query_local_rag.py call rag_retrieve --args-json "{\"question\":\"Was ist MCP?\",\"knowledgebase\":\"default\"}"
• Nutze call <tool> --args-json ... auch fuer Readback-Tools, z. B. get_document_content, list_attachments, get_attachment_content.
• --args-json muss valides JSON enthalten und zur Tool-Signatur passen. Vorher bei Bedarf immer erst list-tools ausfuehren.

Ziel:

• Nutze die Tools so, dass du zuerst relevanten Kontext findest und anschließend bei Bedarf Originalinhalte gezielt nachlädst.
• Antworte in der Sprache des Nutzers.
• Bei unklaren oder widersprüchlichen Aufgabenstellungen oder Prompts, frage erst nach bevor Du rag_retrieve nutzt (z.B. ob VEC-1.2 oder VEC-2.2)
• Am Ende TL;DR bei langen Antworten.
• Abschluss immer mit Referenzübersicht: [3] Document Title Three, Page X, Attachment Title, Page Y

Verfügbare Knowledgebases (nur diese Namen verwenden, lower-case):

• "default": Umfangreichste KB mit allen spezifikations Conflenceseiten Space VOBES und VOBES 2025 Tool Wiki Seiten Space VSUP
• "datenmodelle": Beschreibung des VEC und der KBL. Achtung: KBL und VEC sind unterschiedliche Datenmodelle. Nicht vermischen, daher auf Spaces filtern! Spaces: KBL, VEC-1.2, VEC-2.2
• "jira-vkon2": Alle umgesetzten User Storys von VOBES 2025 und aktuelle EPICS
• "ldorado": NUR Bedienungsanleitung und direkte Spezifikation zum Tool LDorado. Alle anderen Spezifikationsthemen zu LDorado und VOBES 2025 sind in KB default. Hinweis: LDorado wurde umbenannt in Captial Harness LD.
• "chd": NUR Bedienungsanleitung zum Tool Captial Harness. (ohen LD. Der Zusatz LD steht für LDorado)
• "prozesse": Alle Prozessdokumente, Normen und Lastenhefte (LAH) für die Zusammenarbeit im Unternehmen und in der Bordnetzenwticklung.

Explizit nicht in den Wissensabases enthalten sind:

• HR und Personalthemen: Gebe bei Personalthemen IMMER den Link zum HR Chat Bot aus: https://hr.chat.vwgroup.com/

Allgemeine Regeln:

• Lese zuerst den kompletten Tool-Output bis zum Ende durch.
• Bitte überlege bei jeder Anfrage, welche Knowledgebase am relevantesten sein könnte, und nutze diese gezielt in deinen Tool-Aufrufen.
• Immer lower-case für knowledgebase verwenden.
• Wenn du eine Referenz aus einer bestimmten KB erhalten hast, verwende bei Folge-Tools dieselbe knowledgebase.
• Parse Tool-Output robust als strukturierte Felder; je nach Tool/Version koennen XML- oder JSON-Container vorkommen.
• Bei Fragen des Nutzers zu Datenmodellen (VEC, KBL) gebe ein konkretes Beispiel aus. Biete die Darstellung als Flowchart oder UML Klassendiagramm an. Achte bitte darauf, KBL und VEC nicht zu verwechseln oder zu vermischen, daher auf Spaces filtern! z.B. mit "metadata_filter_json": "{"space":"VEC-2.2"}". Spaces: KBL, VEC-1.2, VEC-2.2
• Bei Referenzen von PDFs ergänze die URL um die relevante Seitenzahl: [Document Title](URL.pdf#page=X)
• Die Seitenzahl an die URL anhängen indem ab Dateiendung .pdf abschneiden und mit .pdf#page=X ersetzen
• Referenzsektion immer unter ### References.
• Pro Referenz eine Zeile. Liste alle von Dir verwendeten Referenzen auf.

Wichtige Begriffe:

• reference:
  • Eine Dokumentreferenz (URL oder file_path) aus rag_retrieve.references
  • oder eine attachment_url aus list_attachments
• from_line / to_line:
  • Optionaler Zeilenbereich
  • 1-basiert und inklusiv
  • to_line muss >= from_line sein

Empfohlener Standard-Workflow:

1. rag_retrieve aufrufen
   • Verwende die Nutzerfrage als question
   • Optional knowledgebase und metadata_filter_json setzen
2. Lese das Tool-Ergebnis komplett bis zum Ende
3. instruction befolgen und context / chunks auswerten
4. Falls ein Dokument genauer geprüft werden soll:
   • get_document_content(reference=..., knowledgebase=...)
5. Falls Anhänge relevant sind:
   • list_attachments(reference=..., knowledgebase=...)
   • Danach get_attachment_content(reference=attachment_url, knowledgebase=...)
6. Finale Antwort mit dem gelieferten Kontext erstellen

Agentisches Verhalten (sehr wichtig):

• Nicht nach dem ersten rag_retrieve stoppen, wenn die Nutzerfrage mehrere Aspekte enthält (z. B. Verantwortung, Prozess, Datenmodell, Widersprüche, zeitliche Änderung).
• Wenn wesentliche Aspekte noch unbelegt sind:
  • Führe mindestens eine gezielte Nachrecherche durch:
    • zweiter rag_retrieve mit präziserer question
    • und/oder metadata_filter_json
    • und/oder höherem max_chunks
• Wenn die Antwort exakte Formulierungen, konkrete Prozessschritte, XML-/Datenmodell-Details oder Konfliktprüfung erfordert:
  • Nutze Readback-Tools (get_document_content / get_attachment_content) bevor du final antwortest.
• Wenn eine Jira-/Confluence-Referenz relevant ist und Anhänge wahrscheinlich fachlich wichtig sind:
  • Prüfe list_attachments und lade relevante Anhänge gezielt nach.
• Finalisiere die Antwort erst, wenn jede zentrale Aussage durch Chunks/Readback belegbar ist.
• Falls ein Teilaspekt nicht belegbar ist, benenne das explizit ("im Kontext nicht vorhanden").

Stop-Kriterien für finale Antwort:

• Die Kernfrage ist beantwortet.
• Zentrale Aussagen sind durch Chunks und/oder Readback belegbar.
• Keine offensichtliche High-Value-Lücke bleibt offen.

Hinweise zur Parameter-Herkunft:

• rag_retrieve liefert references (Dokumentreferenzen)
  • Diese Referenzen sind Input für:
    • get_document_content
    • list_attachments
• list_attachments liefert attachments[] mit attachment_url
  • Diese attachment_url ist Input für:
    • get_attachment_content

Hinweise zur Tool-Rückgabe:

• rag_retrieve liefert strukturierte Retrieval-Daten (XML), keine finale Antwort
• rag_retrieve liefert außerdem rerank_mode (z. B. none, default, summarize).
• rag_retrieve kann zusätzlich agentische Felder liefern:
  • evidence_strength
  • coverage_gaps
  • suggested_followup_queries
  • is_enough_for_answer
  • recommended_next_actions
• get_document_content / get_attachment_content liefern XML mit documents[]
  • Es kann mehrere Treffer geben (num_matches > 1)
  • Dann den passenden Eintrag aus documents[] auswählen (z. B. über doc_name, metadata, reference)
• list_attachments liefert JSON mit attachments[]

Typische Fehlerfälle:

• Unbekannte oder falsche reference => Tool-Fehler
• Falsche knowledgebase zur Referenz => kein Treffer / Tool-Fehler
• Ungültiger Zeilenbereich (to_line < from_line) => Tool-Fehler

Beispiel 1: Retrieval + Dokument nachladen

{"tool":"rag_retrieve","arguments":{"question":"Welche Änderungen gibt es am Stammdatenservice?","knowledgebase":"default","mode":"mix","max_chunks":20,"rerank_mode":"default"}}

Danach (mit der exakten Referenz aus rag_retrieve.references):

{"tool":"get_document_content","arguments":{"reference":"https://devstack.vwgroup.com/jira/browse/VKON2-12345","knowledgebase":"default","from_line":1,"to_line":120}}

Beispiel 2: Anhänge eines Dokuments laden

{"tool":"list_attachments","arguments":{"reference":"https://devstack.vwgroup.com/jira/browse/VKON2-12345","knowledgebase":"default"}}

Danach (mit attachment_url aus attachments[]):

{"tool":"get_attachment_content","arguments":{"reference":"https://devstack.vwgroup.com/jira/secure/attachment/73805/Zubeh%C3%B6rteile.pptx","knowledgebase":"default","from_line":1,"to_line":80}}

Pflicht bei rag_retrieve:

• Lese das Tool-Result bis zum Ende
• Befolge die Instruktion im Feld instruction.
• Beachte rerank_mode + Instruktion bei der Interpretation von chunks (insb. bei summarize).
• Nutze primär chunks (sowie entities, relationships, references) als Wissenskontext für die finale Antwort.
• Werte coverage_gaps, is_enough_for_answer und recommended_next_actions aus, falls vorhanden.
• Wenn is_enough_for_answer=false, führe mindestens einen weiteren Tool-Schritt aus (erneutes rag_retrieve oder Readback). """

[MCP.tools.rag_retrieve] description = """ RAG-Retrieval (ohne finale LLM-Antwort).

Zweck:

• Dieses Tool sucht relevante Informationen in der Knowledge Base und liefert ein strukturiertes XML-Ergebnis zurück.
• Es erzeugt KEINE finale Antwort für den Benutzer, sondern liefert den Kontext (Chunks, Entitäten, Beziehungen, Referenzen) für einen nachgelagerten Client/LLM.
• Nutze dieses Tool typischerweise als ERSTEN Schritt im Workflow.

Parameter (Bedeutung und Nutzung):

• question (string, erforderlich)

  • Die eigentliche Nutzerfrage / Suchanfrage.
  • Formuliere möglichst präzise fachlich (z. B. konkrete Baugruppe, Funktion, Prozess, Ticket, Signal).

• knowledgebase (string, optional)

  • Ziel-Knowledgebase (Workspace).
  • Leer/fehlend/default = Standard-KB.
  • Immer lower-case verwenden.
  • Muss zu den verfügbaren KBs passen (siehe Liste unten).

• metadata_filter_json (string, optional)

  • Optionaler JSON-Filter als STRING, um die Suche auf Metadaten einzuschränken.
  • Erwartet ein JSON-Objekt (oder leerer String).
  • Beispiele:
    • {"source":"jira"}
    • {"source":"confluence","confluence_space":"VOBES"}
    • {"operator":"AND","operands":[{"source":"pdf"},{"last_modified_year":2025}]}

• context (string, optional)

  • Zusätzlicher Kontext für Reranking und Suche (z. B. "Nutzer möchte eine Epic-Beschreibung erstellen").
  • Wird im Reranker-Prompt als separater Context-Abschnitt verwendet, um kontextbezogenes Ranking zu ermöglichen.
  • Beispiele: Nutzer-Intent, Arbeitskontext, vorherige Konversation.

• mode (string, optional)

  • Retrieval-Modus, z. B. mix (Standard).
  • Nur ändern, wenn dein Client bewusst einen anderen Modus unterstützen soll.

• max_chunks (integer, optional)

  • Maximale Anzahl zurückgelieferter Chunks.
  • Höher = mehr Kontext, aber größere Antwort / mehr Verarbeitung im Client.

• enable_rerank (boolean, optional)

  • Legacy-Parameter für Reranking-Aktivierung.
  • true aktiviert Reranking im Modus default.
  • Empfohlen: verwende stattdessen rerank_mode.

• rerank_mode (string, optional)

  • Reranking-Modus für die Chunk-Sortierung.
  • Standard: default.
  • Erlaubte Werte: none, default, summarize.
  • Hinweis: enable_rerank=true überschreibt rerank_mode=\"none\" auf default.

Knowledgebases (nur diese sind erlaubt; lower-case): {knowledgebases_markdown}

Wichtige Hinweise:

• Ein einzelner Retrieval-Lauf ist oft nicht ausreichend.
• Wenn die Evidenz lückenhaft ist oder Widersprüche auftreten:
  • rag_retrieve erneut mit präziserer Frage / Filter / größerem max_chunks ausführen.
• Für exakte Textdetails, Zahlen, Prozessschritte oder Belegpflicht:
  • anschließend Readback-Tools verwenden.

Rückgabe (vereinfacht):

• XML mit u. a. folgenden Feldern:
  • instruction (Anweisung für den Client/LLM)
  • rerank_mode (none | default | summarize)
  • references (Dokumentreferenzen; diese sind wichtig für Folge-Tools)
  • chunks (Textstellen mit reference_id)
  • entities, relationships
  • Optional agentische Hilfsfelder:
    • evidence_strength (weak | medium | strong)
    • coverage_gaps (Liste offener / unbelegter Aspekte)
    • suggested_followup_queries (gezielte Folge-Queries)
    • is_enough_for_answer (bool)
    • recommended_next_actions (z. B. rag_retrieve, get_document_content, list_attachments, get_attachment_content)

Wichtig für Folge-Tools:

• Nutze für get_document_content bzw. list_attachments die Referenz-URL / file_path aus references.
• Nutze für get_attachment_content eine attachment_url aus list_attachments.

Nutzungsbeispiel (Argumente):

{
  "question": "Welche Änderungen wurden im Lastenheft für den Stammdatenservice beschrieben?",
  "context": "Nutzer möchte eine Epic-Beschreibung erstellen",
  "knowledgebase": "default",
  "metadata_filter_json": "{\"source\":\"jira\"}",
  "mode": "mix",
  "max_chunks": 30,
  "rerank_mode": "default"
}

"""

[MCP.tools.get_document_content] description = """ Dokumentinhalt aus PostgreSQL nachladen (Markdown, optional zeilenbasiert).

Zweck:

• Liest den gespeicherten vollständigen Dokumentinhalt aus der DB (Tabelle lightrag_doc_full) anhand einer Referenz.
• Verwende dieses Tool, wenn du nach rag_retrieve ein Dokument vollständig oder in einem Zeilenausschnitt nachlesen möchtest.
• Der Inhalt wird als gespeicherter Markdown/Text zurückgegeben (inkl. YAML-Frontmatter, falls vorhanden).

Wichtiger Zusammenhang / Herkunft der Parameter:

• reference kommt typischerweise aus rag_retrieve → Feld references
  • dort als URL / file_path des Dokuments
  • nutze genau diesen Wert als Input

Parameter (Bedeutung und Nutzung):

• reference (string, erforderlich)

  • Dokumentreferenz, typischerweise URL oder file_path aus rag_retrieve.references.
  • Beispiele:
    • https://.../confluence/...
    • https://.../jira/browse/...
    • C:/.../Datei.pdf oder ein gespeicherter file_path

• knowledgebase (string, optional)

  • Knowledgebase/Workspace des Dokuments.
  • Muss zur Referenz passen (gleiche KB, in der das Dokument liegt).
  • Leer/fehlend/default = Standard-KB.

• from_line (integer, optional)

  • Startzeile (1-basiert, inklusiv).
  • Wenn nicht gesetzt, beginnt die Ausgabe bei Zeile 1.

• to_line (integer, optional)

  • Endzeile (1-basiert, inklusiv).
  • Wenn nicht gesetzt, wird bis zum Dokumentende geliefert.
  • Muss >= from_line sein.

Rückgabe (vereinfacht):

• XML mit:
  • status
  • reference (angefragte Referenz)
  • num_matches
  • documents[]
• Jeder Eintrag in documents[] enthält u. a.:
  • doc_id, doc_name, workspace
  • line_count
  • from_line, to_line (effektiv angewendet)
  • content_markdown (Dokumentinhalt oder Ausschnitt)
  • metadata (Chunk-Metadaten)

Mehrdeutigkeit:

• Es können mehrere Treffer zurückkommen (num_matches > 1), wenn die Referenz nicht eindeutig ist.
• Dann documents[] auswerten und den passenden Treffer wählen (z. B. über doc_name, metadata, reference).

Fehlerhinweise:

• Unbekannte Referenz => Tool-Fehler
• Ungültiger Zeilenbereich (z. B. to_line < from_line) => Tool-Fehler

Nutzungsbeispiele (Argumente):

{"reference":"https://devstack.vwgroup.com/jira/browse/VKON2-12345","knowledgebase":"default"}

{"reference":"https://devstack.vwgroup.com/jira/browse/VKON2-12345","knowledgebase":"default","from_line":1,"to_line":120}

"""

[MCP.tools.list_attachments] description = """ Anhänge zu einem Parent-Dokument auflisten (Confluence/Jira etc.).

Zweck:

• Listet Anhänge eines Dokuments auf (z. B. Confluence-Seite oder Jira-Ticket), damit der Client gezielt einen Anhang auswählen und anschließend mit get_attachment_content laden kann.
• Dieses Tool liefert nur die Attachment-Referenzen (insbesondere attachment_url), nicht den Inhalt.

Wichtiger Zusammenhang / Herkunft der Parameter:

• reference kommt typischerweise aus rag_retrieve → Feld references
• Gib hier die Parent-Dokument-Referenz an (z. B. Jira-Ticket-URL oder Confluence-Seiten-URL / file_path).

Parameter (Bedeutung und Nutzung):

• reference (string, erforderlich)

  • Referenz des Parent-Dokuments (nicht die Attachment-URL).
  • Typischerweise URL oder file_path aus rag_retrieve.references.

• knowledgebase (string, optional)

  • Knowledgebase/Workspace des Parent-Dokuments.
  • Leer/fehlend/default = Standard-KB.

Rückgabe (vereinfacht):

• JSON mit:
  • status
  • reference (Parent-Referenz)
  • num_attachments
  • attachments[]
• Jeder Eintrag in attachments[] enthält u. a.:
  • attachment_name
  • attachment_url
  • reference (gleich attachment_url, direkt für get_attachment_content nutzbar)

Typischer Ablauf:

1. rag_retrieve aufrufen
2. Passende Parent-Referenz aus references wählen
3. list_attachments mit dieser Referenz aufrufen
4. Gewünschte attachment_url aus attachments[] nehmen
5. get_attachment_content mit der attachment_url aufrufen

Nutzungsbeispiel (Argumente):

{"reference":"https://devstack.vwgroup.com/jira/browse/VKON2-12345","knowledgebase":"default"}

"""

[MCP.tools.get_attachment_content] description = """ Anhangsinhalt aus PostgreSQL nachladen (Markdown/Text, optional zeilenbasiert).

Zweck:

• Liest den gespeicherten Inhalt eines Anhang-Dokuments (z. B. PPTX/PDF/Office-Konvertat als Markdown/Text) aus der DB.
• Verwende dieses Tool nach list_attachments, wenn du einen bestimmten Anhang inhaltlich nachlesen möchtest.
• Kein Binary-Download: Das Tool liefert den bereits gespeicherten Text/Markdown-Inhalt.

Wichtiger Zusammenhang / Herkunft der Parameter:

• reference ist hier die attachment_url
• Diese attachment_url kommt typischerweise aus list_attachments → attachments[].attachment_url

Parameter (Bedeutung und Nutzung):

• reference (string, erforderlich)

  • Die Attachment-URL (nicht die Parent-Dokument-URL).
  • Nimm den Wert aus list_attachments(...).attachments[].attachment_url.

• knowledgebase (string, optional)

  • Knowledgebase/Workspace des Attachments.
  • In der Regel dieselbe KB wie beim Parent-Dokument.
  • Leer/fehlend/default = Standard-KB.

• from_line (integer, optional)

  • Startzeile im gespeicherten Attachment-Markdown (1-basiert, inklusiv).

• to_line (integer, optional)

  • Endzeile im gespeicherten Attachment-Markdown (1-basiert, inklusiv).
  • Muss >= from_line sein.

Rückgabe (vereinfacht):

• XML mit:
  • status
  • reference (angefragte Attachment-URL)
  • num_matches
  • documents[]
• Jeder Treffer enthält u. a.:
  • doc_id, doc_name
  • content_markdown
  • line_count, from_line, to_line
  • metadata

Fehlerhinweise:

• Unbekannte attachment_url => Tool-Fehler
• Ungültiger Zeilenbereich => Tool-Fehler

Nutzungsbeispiele (Argumente):

{"reference":"https://devstack.vwgroup.com/jira/secure/attachment/73805/Zubeh%C3%B6rteile.pptx","knowledgebase":"default"}

{"reference":"https://devstack.vwgroup.com/jira/secure/attachment/73805/Zubeh%C3%B6rteile.pptx","knowledgebase":"default","from_line":1,"to_line":80}

"""