new mds
This commit is contained in:
team 1
558
COMMAND_REF.md
558
COMMAND_REF.md
@@ -1,294 +1,492 @@
|
||||
# RAG System – CLI Command Reference
|
||||
**Projektstand: rag.zip (aktueller Code-Stand)**
|
||||
Namespace-Konvention: `mto:agent:*`
|
||||
# RetrieX – CLI Command Reference
|
||||
|
||||
Diese Dokumentation beschreibt alle verfügbaren Symfony-Console-Commands des Systems inklusive Zweck, Einsatzszenario und typischer Aufrufe.
|
||||
**Basis:** `rag.zip` (aktueller Code-Stand vom 2026-04-15)
|
||||
**Scope:** ausschließlich projektspezifische Symfony-Commands unter `src/Command`
|
||||
**Namespace-Konvention:** `mto:agent:*`
|
||||
|
||||
Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die veraltete Fassung der bisherigen `COMMAND_REF.md`.
|
||||
|
||||
---
|
||||
|
||||
# 1. Agent / Chat
|
||||
## 1. Überblick
|
||||
|
||||
## `mto:agent:chat`
|
||||
| Command | Bereich | Kurzbeschreibung |
|
||||
|---|---|---|
|
||||
| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den AgentRunner |
|
||||
| `mto:agent:ingest:version` | Ingest | Startet einen Ingest für eine konkrete Dokumentversion |
|
||||
| `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
|
||||
| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload |
|
||||
| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
|
||||
| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
|
||||
| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
|
||||
| `mto:agent:test-vector` | Debug | Führt Tag-Routing und Chunk-Retrieval für einen Testprompt aus |
|
||||
| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
|
||||
| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
|
||||
| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
|
||||
| `mto:agent:tag:health` | Tags | Konsistenzcheck für `tags.ndjson` und Tag-Vektorindex |
|
||||
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für die Shopware-Suche |
|
||||
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent / Chat
|
||||
|
||||
### `mto:agent:chat`
|
||||
Interaktiver CLI-Chat mit dem Agenten.
|
||||
|
||||
**Zweck**
|
||||
- Direkter Zugriff auf AgentRunner
|
||||
- Streaming-Ausgabe im Terminal
|
||||
- Nutzt vollständige Retrieval- und Prompt-Logik
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:chat [user-id]
|
||||
```
|
||||
|
||||
**Start**
|
||||
**Argumente**
|
||||
- `user-id` optional, Default: `cli`
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- startet eine Terminal-Schleife mit `Question` → `Answer`
|
||||
- ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf
|
||||
- streamt Tokens direkt ins Terminal
|
||||
- beendet sich bei EOF, leerer Eingabe oder `exit`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:chat
|
||||
bin/console mto:agent:chat admin-debug
|
||||
```
|
||||
|
||||
**Eigenschaften**
|
||||
- Streaming-first
|
||||
- Think-Suppression wird im AgentRunner gesteuert
|
||||
- Voller Kontext + Retrieval aktiv
|
||||
|
||||
---
|
||||
|
||||
# 2. Dokument-Ingest
|
||||
## 3. Ingest / Jobs
|
||||
|
||||
## `mto:agent:ingest:version`
|
||||
Ingest einer konkreten Dokumentversion.
|
||||
### `mto:agent:ingest:version`
|
||||
Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.
|
||||
|
||||
**Zweck**
|
||||
- Chunking
|
||||
- NDJSON-Append / Compaction
|
||||
- Vollständiger FAISS-Rebuild
|
||||
- index_meta.json Update
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:ingest:version <versionId> <userId>
|
||||
```
|
||||
|
||||
**Argumente**
|
||||
- `versionId` erforderlich, UUID einer `DocumentVersion`
|
||||
- `userId` erforderlich, UUID des auslösenden Users
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- lädt `DocumentVersion` und `User` aus Doctrine
|
||||
- bricht mit Fehler ab, wenn Version oder User nicht existieren
|
||||
- ruft `IngestOrchestrator->runForVersion($version, $user)` auf
|
||||
- gibt nach Abschluss die erzeugte Job-ID aus
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:ingest:version <documentVersionUuid>
|
||||
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
|
||||
```
|
||||
|
||||
**Wichtige Korrektur zur alten Doku**
|
||||
Die bisherige Referenz dokumentierte nur einen Parameter. Im aktuellen Code sind **zwei Pflichtargumente** erforderlich.
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:ingest:run`
|
||||
Führt einen einzelnen IngestJob aus.
|
||||
### `mto:agent:ingest:run`
|
||||
Führt einen bereits existierenden `IngestJob` aus.
|
||||
|
||||
**Zweck**
|
||||
- Job-basierte Verarbeitung (QUEUE → RUNNING → COMPLETED/FAILED)
|
||||
- Wird intern bei Aktivierung einer Dokumentversion verwendet
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:ingest:run <jobId> [--dry-run]
|
||||
```
|
||||
|
||||
**Beispiel**
|
||||
**Argumente / Optionen**
|
||||
- `jobId` erforderlich, UUID eines `IngestJob`
|
||||
- `--dry-run` optional, simuliert schwere Operationen ohne tatsächliche Ausführung
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- lädt den Job aus der Datenbank
|
||||
- bricht mit Fehler ab, wenn der Job nicht gefunden wird
|
||||
- beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`)
|
||||
- ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf
|
||||
|
||||
**Beispiele**
|
||||
```bash
|
||||
bin/console mto:agent:ingest:run <jobUuid>
|
||||
bin/console mto:agent:ingest:run <jobUuid> --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:vector:rebuild`
|
||||
Erzwingt vollständigen Vector-Rebuild aus `index.ndjson`.
|
||||
### `mto:agent:system:rebuild`
|
||||
Globaler Hard-Rebuild des Systems.
|
||||
|
||||
**Zweck**
|
||||
- FAISS komplett neu aufbauen
|
||||
- Kein Re-Chunking
|
||||
- Reine Vektor-Neuerstellung
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
|
||||
```
|
||||
|
||||
**Optionen**
|
||||
- `--hard` **Pflicht-Sicherheitsschalter**; ohne diese Option bricht das Kommando ab
|
||||
- `--no-tags` überspringt den Tag-Rebuild
|
||||
- `--no-reload` überspringt Reload/Start des Vector-Service
|
||||
- `--no-health` überspringt den abschließenden Health-Check
|
||||
- `--dry-run` simuliert den Reindex ohne Schreiboperationen
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
1. erzeugt einen neuen `IngestJob` vom Typ `GLOBAL_REINDEX`
|
||||
2. führt den globalen Reindex über den Orchestrator aus
|
||||
3. exportiert optional `tags.ndjson` und baut `vector_tags.index` neu
|
||||
4. startet bzw. reloadet optional den Python-Vector-Service
|
||||
5. führt optional Chunk- und Tag-Health-Checks aus
|
||||
|
||||
**Beispiele**
|
||||
```bash
|
||||
bin/console mto:agent:system:rebuild --hard
|
||||
bin/console mto:agent:system:rebuild --hard --dry-run
|
||||
bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
|
||||
```
|
||||
|
||||
**Hinweis**
|
||||
Dieses Kommando ist aktuell der zentrale Produktions-Entry-Point für einen vollständigen Neuaufbau des Retrieval-Stacks.
|
||||
|
||||
---
|
||||
|
||||
## 4. Vector / Retrieval
|
||||
|
||||
### `mto:agent:vector:rebuild`
|
||||
Baut den Chunk-Vektorindex neu.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- schreibt `Rebuilding vector index...`
|
||||
- ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
|
||||
- schreibt anschließend `Done.`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 3. Vector Service (Python / FastAPI)
|
||||
### `mto:agent:vector:control`
|
||||
Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.
|
||||
|
||||
## `mto:agent:vector:control`
|
||||
Steuert den persistenten Python-Vector-Service.
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:vector:control [optionen]
|
||||
```
|
||||
|
||||
**Beschreibung**
|
||||
Production-sicheres Management des uvicorn-FastAPI-Dienstes.
|
||||
**Unterstützte Optionen**
|
||||
- `--install` installiert fehlende Python-Dependencies in `.venv`
|
||||
- `--start` startet den Service, falls er nicht läuft
|
||||
- `--stop` stoppt den Service anhand der PID-Datei
|
||||
- `--force` erzwingt einen Hard-Stop
|
||||
- `--reload` triggert den `/reload`-Endpoint des Service
|
||||
- `--status` gibt den aktuellen Status aus
|
||||
- `--foreground` startet im Vordergrund
|
||||
- `--port=8090` setzt den Port
|
||||
- `--host=0.0.0.0` setzt den Host
|
||||
|
||||
### Optionen
|
||||
**Reales Verhalten im Code**
|
||||
- baut einen Prozessaufruf gegen `.venv/bin/python python/vector/vector_control.py`
|
||||
- reicht gesetzte Optionen durch
|
||||
- hängt immer `--port` und `--host` an
|
||||
- gibt `stdout` des Python-Skripts direkt aus
|
||||
|
||||
| Option | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `--install` | Fehlende Python-Dependencies installieren |
|
||||
| `--start` | Service starten |
|
||||
| `--stop` | Service stoppen |
|
||||
| `--force` | Hard-Stop (SIGKILL) |
|
||||
| `--reload` | /reload Trigger |
|
||||
| `--status` | Status anzeigen |
|
||||
| `--foreground` | Vordergrundstart |
|
||||
| `--port=8090` | Port |
|
||||
| `--host=0.0.0.0` | Host |
|
||||
|
||||
### Beispiele
|
||||
|
||||
Installieren:
|
||||
**Beispiele**
|
||||
```bash
|
||||
bin/console mto:agent:vector:control --install
|
||||
```
|
||||
|
||||
Starten:
|
||||
```bash
|
||||
bin/console mto:agent:vector:control --start
|
||||
```
|
||||
|
||||
Status:
|
||||
```bash
|
||||
bin/console mto:agent:vector:control --status
|
||||
```
|
||||
|
||||
Reload:
|
||||
```bash
|
||||
bin/console mto:agent:vector:control --reload
|
||||
bin/console mto:agent:vector:control --stop --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:vector:health`
|
||||
Gesundheitscheck von:
|
||||
|
||||
- index.ndjson
|
||||
- vector.index
|
||||
- index_meta.json
|
||||
- Embedding-Dimensionen
|
||||
- Konsistenz
|
||||
### `mto:agent:vector:health`
|
||||
Health-Check für Chunk-NDJSON und Chunk-Vektorindex.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:vector:health
|
||||
```
|
||||
|
||||
Ausgabe erfolgt als JSON.
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:test-vector`
|
||||
Testet direkte Vector-Suche.
|
||||
**Reales Verhalten im Code**
|
||||
- ruft `VectorIndexHealthService->check()` auf
|
||||
- gibt den Report als JSON aus
|
||||
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:test-vector "Suchanfrage"
|
||||
bin/console mto:agent:vector:health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 4. Tag-System
|
||||
### `mto:agent:test-vector`
|
||||
Debug-Kommando für einen realistischen Retrieval-Test.
|
||||
|
||||
## `mto:agent:tags:export`
|
||||
Exportiert alle Tags in `tags.ndjson`.
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:test-vector <prompt>
|
||||
```
|
||||
|
||||
**Zweck**
|
||||
- Grundlage für tag-basiertes Routing
|
||||
- Keine Vector-Erstellung
|
||||
**Argumente**
|
||||
- `prompt` erforderlich, Testanfrage für das Retrieval
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- führt zuerst Tag-Routing über `TagVectorSearchClient` aus
|
||||
- führt danach Chunk-Retrieval über `VectorSearchClient` aus
|
||||
- misst Tag-, Chunk- und Gesamtdauer
|
||||
- gibt beide Result-Sets als JSON aus
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Tag-System
|
||||
|
||||
### `mto:agent:tags:export`
|
||||
Exportiert die Tag-Datenbasis nach `tags.ndjson`.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:tags:export
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- ruft `TagNdjsonExporter->export()` auf
|
||||
- gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:tags:export
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:tags:rebuild`
|
||||
Vollständiger Tag-Rebuild:
|
||||
### `mto:agent:tags:rebuild`
|
||||
Kompletter Neuaufbau des Tag-Retrievals.
|
||||
|
||||
1. Export `tags.ndjson`
|
||||
2. Erstellen von `vector_tags.index`
|
||||
3. index_meta.json Update
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:tags:rebuild
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
1. exportiert `tags.ndjson`
|
||||
2. baut `vector_tags.index`
|
||||
3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:tags:rebuild
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `mto:agent:tags:job:run`
|
||||
Führt einen einzelnen TagRebuildJob aus.
|
||||
|
||||
**Mit Lock-Mechanismus.**
|
||||
### `mto:agent:tags:job:run`
|
||||
Führt einen Tag-Rebuild-Job mit File-Lock aus.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:tags:job:run [jobId] [--create]
|
||||
```
|
||||
|
||||
**Argumente / Optionen**
|
||||
- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
|
||||
- `--create` optional, erstellt und startet sofort einen neuen `TagRebuildJob`
|
||||
|
||||
**Regeln im Code**
|
||||
- entweder `jobId` **oder** `--create`
|
||||
- beides zusammen ist ungültig
|
||||
- keines von beiden ist ebenfalls ungültig
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- markiert den Job auf `RUNNING`
|
||||
- sperrt parallel laufende Tag-Rebuilds per File-Lock
|
||||
- exportiert `tags.ndjson`
|
||||
- baut `vector_tags.index`
|
||||
- markiert den Job bei Erfolg als `COMPLETED`, sonst als `FAILED`
|
||||
|
||||
**Beispiele**
|
||||
```bash
|
||||
bin/console mto:agent:tags:job:run --create
|
||||
bin/console mto:agent:tags:job:run <jobUuid>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. User-Management
|
||||
### `mto:agent:tag:health`
|
||||
Health-Check für das Tag-Retrieval.
|
||||
|
||||
## `mto:agent:user:create`
|
||||
Erstellt einen neuen Admin-User.
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:tag:health
|
||||
```
|
||||
|
||||
Interaktiver Ablauf:
|
||||
- E-Mail
|
||||
- Passwort
|
||||
- Rollenwahl
|
||||
**Reales Verhalten im Code**
|
||||
- ruft `TagVectorIndexHealthService->check()` auf
|
||||
- gibt den Report als JSON aus
|
||||
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:tag:health
|
||||
```
|
||||
|
||||
**Wichtige Korrektur zur alten Doku**
|
||||
Der reale Command-Name ist **`tag:health` (Singular)**, nicht `tags:health`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Commerce / Shopware Debug
|
||||
|
||||
### `mto:agent:test:shop-search`
|
||||
Testkommando für die Shopware-Suche.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:test:shop-search [query]
|
||||
```
|
||||
|
||||
**Argumente**
|
||||
- `query` optional
|
||||
- Default im Code: `zeige mir testomat modelle wasserhärte unter 5000 euro`
|
||||
|
||||
**Beabsichtigtes Verhalten**
|
||||
- ruft die Shop-Suche auf
|
||||
- gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus
|
||||
|
||||
**Wichtiger Code-Hinweis**
|
||||
Im aktuellen Stand von `rag.zip` ruft das Command `ShopSearchService->search($query)` mit **einem** Argument auf, die Service-Signatur erwartet aber **zwei** Argumente (`string $originalPrompt, string $commerceIntent`). Das Kommando ist daher im aktuellen Codebestand sehr wahrscheinlich **nicht lauffähig**, solange diese Signaturabweichung nicht behoben wird.
|
||||
|
||||
---
|
||||
|
||||
## 7. User-Management
|
||||
|
||||
### `mto:agent:user:create`
|
||||
Interaktive Anlage eines Users.
|
||||
|
||||
**Signatur**
|
||||
```bash
|
||||
bin/console mto:agent:user:create
|
||||
```
|
||||
|
||||
**Interaktiver Ablauf**
|
||||
1. E-Mail eingeben
|
||||
2. Passwort eingeben
|
||||
3. Rolle wählen
|
||||
|
||||
**Validierungen im Code**
|
||||
- E-Mail muss valide sein
|
||||
- User mit gleicher E-Mail darf nicht bereits existieren
|
||||
- Passwort muss mindestens 8 Zeichen lang sein
|
||||
|
||||
**Im Code auswählbare Rollen**
|
||||
- `ROLE_SUPER_ADMIN`
|
||||
- `ROLE_KNOWLEDGE_ADMIN`
|
||||
- `ROLE_EDITOR`
|
||||
- `ROLE_USER`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:user:create
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. Architektur-Zusammenhang der Commands
|
||||
## 8. Typische Betriebsabläufe
|
||||
|
||||
| Bereich | Command-Typ |
|
||||
|----------|------------|
|
||||
| Dokumente | ingest:version |
|
||||
| Jobs | ingest:run |
|
||||
| Vector Index | vector:rebuild |
|
||||
| Vector Service | vector:control |
|
||||
| Vector Health | vector:health |
|
||||
| Tag Export | tags:export |
|
||||
| Tag Rebuild | tags:rebuild |
|
||||
| Tag Job | tags:job:run |
|
||||
| Agent CLI | chat |
|
||||
| User | user:create |
|
||||
### Manueller Ingest einer Version
|
||||
```bash
|
||||
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 7. Typischer Produktions-Workflow
|
||||
|
||||
### 1️⃣ Dokument aktivieren
|
||||
→ erzeugt IngestJob
|
||||
|
||||
### 2️⃣ Job ausführen
|
||||
### Vorhandenen Ingest-Job ausführen
|
||||
```bash
|
||||
bin/console mto:agent:ingest:run <jobUuid>
|
||||
```
|
||||
|
||||
### 3️⃣ Vector-Service prüfen
|
||||
### Nur Chunk-Vektorindex neu bauen
|
||||
```bash
|
||||
bin/console mto:agent:vector:health
|
||||
bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
### 4️⃣ Optional: Service reload
|
||||
### Gesamtsystem hart neu aufbauen
|
||||
```bash
|
||||
bin/console mto:agent:system:rebuild --hard
|
||||
```
|
||||
|
||||
### Vector-Service prüfen und reloaden
|
||||
```bash
|
||||
bin/console mto:agent:vector:health
|
||||
bin/console mto:agent:vector:control --reload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 8. System-Ebenen
|
||||
|
||||
| Ebene | Technologie |
|
||||
|--------|------------|
|
||||
| Symfony | PHP / Doctrine |
|
||||
| Retrieval | NDJSON + FAISS |
|
||||
| Vector Service | Python FastAPI |
|
||||
| Persistence | index.ndjson |
|
||||
| Governance | index_meta.json |
|
||||
| Streaming | SSE |
|
||||
| CLI | Symfony Console |
|
||||
|
||||
---
|
||||
|
||||
# 9. Wichtige Dateien (Runtime)
|
||||
|
||||
```
|
||||
var/
|
||||
├── run/
|
||||
│ └── vector.pid
|
||||
├── index.ndjson
|
||||
├── index_meta.json
|
||||
├── vector.index
|
||||
└── vector_tags.index
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 10. Sicherheit & Locks
|
||||
|
||||
- IngestFlow schützt mit LockService
|
||||
- Tag-Rebuild verwendet File-Lock
|
||||
- Vector-Service PID-basiert
|
||||
- Global Rebuild atomar via `.tmp` + rename()
|
||||
|
||||
---
|
||||
|
||||
# 11. Empfohlene Admin-Checks
|
||||
|
||||
Regelmäßig ausführen:
|
||||
|
||||
### Tag-Retrieval neu aufbauen
|
||||
```bash
|
||||
bin/console mto:agent:vector:health
|
||||
bin/console mto:agent:tags:rebuild
|
||||
bin/console mto:agent:tag:health
|
||||
```
|
||||
|
||||
Bei Änderungen am Embedding-Modell:
|
||||
→ vollständiger Rebuild
|
||||
|
||||
---
|
||||
|
||||
# Ende der Command-Dokumentation
|
||||
System-Stand: rag.zip (aktueller Projektzustand)
|
||||
## 9. Wichtige Runtime-Dateien und Pfade
|
||||
|
||||
Die bisherige Doku nannte teilweise veraltete Pfade unter `var/`. Im aktuellen Code liegen die Knowledge-Artefakte primär unter `var/knowledge/`.
|
||||
|
||||
```text
|
||||
var/
|
||||
├── knowledge/
|
||||
│ ├── index.ndjson
|
||||
│ ├── index_meta.json
|
||||
│ ├── index_runtime.json
|
||||
│ ├── vector.index
|
||||
│ ├── vector.index.meta.json
|
||||
│ ├── tags.ndjson
|
||||
│ ├── vector_tags.index
|
||||
│ ├── vector_tags.index.meta.json
|
||||
│ ├── uploads/
|
||||
│ └── locks/
|
||||
│ └── tag_rebuild.lock
|
||||
├── run/
|
||||
│ └── vector_service.pid
|
||||
└── locks/
|
||||
└── ingest.lock
|
||||
```
|
||||
|
||||
**Herkunft im Code**
|
||||
- `config/services.yaml` definiert `mto.knowledge.root = %mto.root%/var/knowledge`
|
||||
- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`
|
||||
- `App\Service\LockService` verwendet aktuell `var/locks/ingest.lock`
|
||||
|
||||
---
|
||||
|
||||
## 10. Wichtige Abweichungen zur alten `COMMAND_REF.md`
|
||||
|
||||
Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche Korrekturen:
|
||||
|
||||
1. `mto:agent:system:rebuild` fehlte vollständig
|
||||
2. `mto:agent:test:shop-search` fehlte vollständig
|
||||
3. `mto:agent:tag:health` fehlte und war zudem leicht falsch benannt
|
||||
4. `mto:agent:ingest:version` braucht aktuell **`<versionId> <userId>`**
|
||||
5. Runtime-Dateien liegen nicht nur unter `var/`, sondern überwiegend unter `var/knowledge/`
|
||||
6. der globale Rebuild läuft heute über `mto:agent:system:rebuild --hard`, nicht über ein dokumentiertes `ingest:global`
|
||||
|
||||
---
|
||||
|
||||
## 11. Fazit
|
||||
|
||||
Der aktuelle Custom-CLI-Umfang des Systems besteht aus **14 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
|
||||
|
||||
- `mto:agent:ingest:run`
|
||||
- `mto:agent:system:rebuild`
|
||||
- `mto:agent:vector:control`
|
||||
- `mto:agent:vector:health`
|
||||
- `mto:agent:tags:rebuild`
|
||||
- `mto:agent:tag:health`
|
||||
|
||||
Reference in New Issue
Block a user