update .md
This commit is contained in:
team 1
709
COMMAND_REF.md
709
COMMAND_REF.md
@@ -1,449 +1,646 @@
|
||||
# RetrieX – CLI Command Reference
|
||||
# RetrieX v1.6.0 – CLI Command Reference
|
||||
|
||||
**Basis:** `rag.zip` (aktueller Code-Stand vom 2026-04-15)
|
||||
**Scope:** ausschließlich projektspezifische Symfony-Commands unter `src/Command`
|
||||
**Namespace-Konvention:** `mto:agent:*`
|
||||
Basis: aktueller `rag-inprogress.zip`-Stand der Version **1.6.0**.
|
||||
Scope: 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`.
|
||||
Diese Referenz ist gegen die real vorhandenen Command-Klassen im Paket abgeglichen.
|
||||
|
||||
---
|
||||
|
||||
## 1. Überblick
|
||||
|
||||
| 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:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den `AgentRunner` |
|
||||
| `mto:agent:eval:run` | Evaluation | Führt versionierte Eval-Cases aus |
|
||||
| `mto:agent:ingest:version` | Ingest | Startet den 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:system:rebuild` | System | Globaler Hard-Rebuild von Knowledge-, Vector- und optional Tag-Artefakten |
|
||||
| `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 | Testet Tag- und Chunk-Vector-Clients direkt |
|
||||
| `mto:agent:retrieval:test` | Retrieval Debug | Testet den realen hybriden Retrieval-Pfad mit Debugausgabe |
|
||||
| `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 Tag-NDJSON und Tag-Vektorindex |
|
||||
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für Shopware-Suche und optional Search Repair |
|
||||
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
|
||||
| `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
|
||||
| `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
|
||||
| `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core |
|
||||
| `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
|
||||
| `mto:agent:regression:test` | Config / Governance | Fuehrt Offline-Regression-Guards fuer stabile Pfade aus |
|
||||
| `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 |
|
||||
| `mto:agent:regression:test` | Config / Governance | Führt Offline-Regression-Guards für stabile Pfade aus |
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent / Chat
|
||||
|
||||
### `mto:agent:chat`
|
||||
|
||||
Interaktiver CLI-Chat mit dem Agenten.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:chat [user-id]
|
||||
php bin/console mto:agent:chat [user-id]
|
||||
```
|
||||
|
||||
**Argumente**
|
||||
- `user-id` optional, Default: `cli`
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- `user-id` optional, Default `cli`
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- 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**
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:chat
|
||||
bin/console mto:agent:chat admin-debug
|
||||
php bin/console mto:agent:chat
|
||||
php bin/console mto:agent:chat cli-debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Ingest / Jobs
|
||||
## 3. Evaluation
|
||||
|
||||
### `mto:agent:eval:run`
|
||||
|
||||
Führt versionierte Eval-Cases aus.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:eval:run [type] [--case=CASE_ID] [--json] [--no-write]
|
||||
```
|
||||
|
||||
**Argumente / Optionen**
|
||||
|
||||
- `type` optional, Default `retrieval`
|
||||
- `--case=CASE_ID` führt nur einen einzelnen Case aus
|
||||
- `--json` gibt den vollständigen Report als JSON aus
|
||||
- `--no-write` verhindert das Schreiben des Report-Files
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- lädt Cases über `EvalCaseLoader`
|
||||
- filtert optional auf eine Case-ID
|
||||
- führt Cases über `AgentEvalRunner` aus
|
||||
- schreibt standardmäßig einen Report über `EvalReportWriter`
|
||||
- Exit-Code ist fehlerhaft, wenn mindestens ein Case fehlschlägt
|
||||
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:eval:run
|
||||
php bin/console mto:agent:eval:run retrieval --case=water-hardness-lowest
|
||||
php bin/console mto:agent:eval:run retrieval --json --no-write
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Ingest / Jobs
|
||||
|
||||
### `mto:agent:ingest:version`
|
||||
|
||||
Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:ingest:version <versionId> <userId>
|
||||
php 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**
|
||||
**Reales Verhalten**
|
||||
|
||||
- lädt `DocumentVersion` und `User` aus Doctrine
|
||||
- bricht mit Fehler ab, wenn Version oder User nicht existieren
|
||||
- bricht 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> <userUuid>
|
||||
php 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 bereits existierenden `IngestJob` aus.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:ingest:run <jobId> [--dry-run]
|
||||
php bin/console mto:agent:ingest:run <jobId> [--dry-run]
|
||||
```
|
||||
|
||||
**Argumente / Optionen**
|
||||
- `jobId` erforderlich, UUID eines `IngestJob`
|
||||
- `--dry-run` optional, simuliert schwere Operationen ohne tatsächliche Ausführung
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
- `jobId` erforderlich, UUID eines `IngestJob`
|
||||
- `--dry-run` simuliert schwere Operationen ohne tatsächliche Ausführung
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- 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
|
||||
php bin/console mto:agent:ingest:run <jobUuid>
|
||||
php bin/console mto:agent:ingest:run <jobUuid> --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `mto:agent:system:rebuild`
|
||||
|
||||
Globaler Hard-Rebuild des Systems.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
|
||||
php 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`
|
||||
- `--hard` Pflicht-Sicherheitsschalter; ohne diese Option bricht das Kommando ab
|
||||
- `--no-tags` überspringt Tag-Rebuild
|
||||
- `--no-reload` überspringt Reload/Start des Vector-Service
|
||||
- `--no-health` überspringt abschließende Health-Checks
|
||||
- `--dry-run` simuliert Schritte ohne Schreiboperationen
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
1. erzeugt einen globalen Reindex-Job
|
||||
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
|
||||
3. exportiert optional Tags und baut `vector_tags.index` neu
|
||||
4. startet oder 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.
|
||||
```bash
|
||||
php bin/console mto:agent:system:rebuild --hard
|
||||
php bin/console mto:agent:system:rebuild --hard --dry-run
|
||||
php bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Vector / Retrieval
|
||||
## 5. Vector / Retrieval
|
||||
|
||||
### `mto:agent:vector:rebuild`
|
||||
Baut den Chunk-Vektorindex neu.
|
||||
|
||||
Baut den Chunk-Vektorindex aus `index.ndjson` neu.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:vector:rebuild
|
||||
php bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
**Reales Verhalten**
|
||||
|
||||
- schreibt `Rebuilding vector index...`
|
||||
- ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
|
||||
- schreibt anschließend `Done.`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `mto:agent:vector:control`
|
||||
|
||||
Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:vector:control [optionen]
|
||||
php bin/console mto:agent:vector:control [--install] [--start] [--stop] [--force] [--reload] [--status] [--foreground] [--port=8090] [--host=0.0.0.0]
|
||||
```
|
||||
|
||||
**Unterstützte Optionen**
|
||||
- `--install` installiert fehlende Python-Dependencies in `.venv`
|
||||
**Optionen**
|
||||
|
||||
- `--install` installiert fehlende Python-Abhängigkeiten 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
|
||||
- `--reload` triggert den `/reload`-Endpoint
|
||||
- `--status` gibt den aktuellen Status aus
|
||||
- `--foreground` startet im Vordergrund
|
||||
- `--port=8090` setzt den Port
|
||||
- `--host=0.0.0.0` setzt den Host
|
||||
|
||||
**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
|
||||
- `--port` setzt den Port, Default `8090`
|
||||
- `--host` setzt den Host, Default `0.0.0.0`
|
||||
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:vector:control --install
|
||||
bin/console mto:agent:vector:control --start
|
||||
bin/console mto:agent:vector:control --status
|
||||
bin/console mto:agent:vector:control --reload
|
||||
bin/console mto:agent:vector:control --stop --force
|
||||
php bin/console mto:agent:vector:control --install
|
||||
php bin/console mto:agent:vector:control --start
|
||||
php bin/console mto:agent:vector:control --status
|
||||
php bin/console mto:agent:vector:control --reload
|
||||
php bin/console mto:agent:vector:control --stop --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `mto:agent:vector:health`
|
||||
|
||||
Health-Check für Chunk-NDJSON und Chunk-Vektorindex.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:vector:health
|
||||
php bin/console mto:agent:vector:health
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
**Reales Verhalten**
|
||||
|
||||
- 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:vector:health
|
||||
```
|
||||
|
||||
---
|
||||
- gibt JSON aus
|
||||
- Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
|
||||
|
||||
### `mto:agent:test-vector`
|
||||
Debug-Kommando für einen realistischen Retrieval-Test.
|
||||
|
||||
Debug-Kommando für Tag- und Chunk-Vector-Clients.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:test-vector <prompt>
|
||||
php bin/console mto:agent:test-vector <prompt>
|
||||
```
|
||||
|
||||
**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
|
||||
- `prompt` erforderlich
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- führt Tag-Routing über `TagVectorSearchClient` aus
|
||||
- führt 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?"
|
||||
php bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
|
||||
```
|
||||
|
||||
### `mto:agent:retrieval:test`
|
||||
|
||||
Testet den realen hybriden Retrieval-Pfad mit Debugausgabe.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:retrieval:test <prompt> [--json] [--show-text]
|
||||
```
|
||||
|
||||
**Argumente / Optionen**
|
||||
|
||||
- `prompt` erforderlich
|
||||
- `--json` gibt das rohe Debugresultat als JSON aus
|
||||
- `--show-text` zeigt vollständige Chunktexte statt gekürzter Vorschau
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- ruft `NdjsonHybridRetriever->retrieveDebug($prompt)` auf
|
||||
- zeigt Pipeline Summary, Scope Candidates, Hit Counts, Boosts und ausgewählte Chunks
|
||||
- bricht bei leerem Prompt oder Retrieval-Exception mit Fehler ab
|
||||
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
|
||||
php bin/console mto:agent:retrieval:test "Testomat 808 SIO2" --json
|
||||
php bin/console mto:agent:retrieval:test "Indikatortyp 300" --show-text
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Tag-System
|
||||
## 6. Tag-System
|
||||
|
||||
### `mto:agent:tags:export`
|
||||
|
||||
Exportiert die Tag-Datenbasis nach `tags.ndjson`.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:tags:export
|
||||
php bin/console mto:agent:tags:export
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
**Reales Verhalten**
|
||||
|
||||
- ruft `TagNdjsonExporter->export()` auf
|
||||
- gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:tags:export
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `mto:agent:tags:rebuild`
|
||||
|
||||
Kompletter Neuaufbau des Tag-Retrievals.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:tags:rebuild
|
||||
php bin/console mto:agent:tags:rebuild
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
**Reales Verhalten**
|
||||
|
||||
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 Tag-Rebuild-Job mit File-Lock aus.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:tags:job:run [jobId] [--create]
|
||||
php 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`
|
||||
- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
|
||||
- `--create` erstellt und startet sofort einen neuen `TagRebuildJob`
|
||||
|
||||
**Regeln**
|
||||
|
||||
- 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>
|
||||
php bin/console mto:agent:tags:job:run --create
|
||||
php bin/console mto:agent:tags:job:run <jobUuid>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `mto:agent:tag:health`
|
||||
|
||||
Health-Check für das Tag-Retrieval.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:tag:health
|
||||
php bin/console mto:agent:tag:health [--summary]
|
||||
```
|
||||
|
||||
**Reales Verhalten im Code**
|
||||
**Optionen**
|
||||
|
||||
- `--summary` gibt eine lesbare Zusammenfassung statt JSON aus
|
||||
|
||||
**Reales Verhalten**
|
||||
|
||||
- ruft `TagVectorIndexHealthService->check()` auf
|
||||
- gibt den Report als JSON aus
|
||||
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
|
||||
- gibt JSON oder Summary aus
|
||||
- Exit-Code `0`, wenn der Status als gesund gilt; sonst `1`
|
||||
|
||||
**Beispiele**
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:tag:health
|
||||
php bin/console mto:agent:tag:health
|
||||
php bin/console mto:agent:tag:health --summary
|
||||
```
|
||||
|
||||
**Wichtige Korrektur zur alten Doku**
|
||||
Der reale Command-Name ist **`tag:health` (Singular)**, nicht `tags:health`.
|
||||
Wichtig: Der reale Command-Name ist `tag:health` im Singular.
|
||||
|
||||
---
|
||||
|
||||
## 6. Commerce / Shopware Debug
|
||||
## 7. Commerce / Shopware Debug
|
||||
|
||||
### `mto:agent:test:shop-search`
|
||||
Testkommando für die Shopware-Suche.
|
||||
|
||||
Testkommando für Shopware-Suche und optionalen Search-Repair-Test.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:test:shop-search [query]
|
||||
php bin/console mto:agent:test:shop-search [query] [--intent=INTENT] [--history=TEXT] [--repair]
|
||||
```
|
||||
|
||||
**Argumente**
|
||||
- `query` optional
|
||||
- Default im Code: `zeige mir testomat modelle wasserhärte unter 5000 euro`
|
||||
**Argumente / Optionen**
|
||||
|
||||
**Beabsichtigtes Verhalten**
|
||||
- ruft die Shop-Suche auf
|
||||
- gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus
|
||||
- `query` optional, Default `zeige mir testomat modelle wasserhärte unter 5000 euro`
|
||||
- `--intent` optional, Default `CommerceIntentLite::ADVISORY_PRODUCT_SEARCH`
|
||||
- `--history` optionaler Commerce-History-Kontext
|
||||
- `--repair` aktiviert zusätzlich die Search-Repair-Auswertung
|
||||
|
||||
**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.
|
||||
**Reales Verhalten**
|
||||
|
||||
- ruft `ShopSearchService->search($query, $intent, $history)` auf
|
||||
- gibt Treffer mit ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL, Description und Highlights aus
|
||||
- bei `--repair` werden Knowledge-Chunks geholt und `SearchRepairService->repair(...)` ausgeführt
|
||||
- zeigt dann verwendete Repair-Queries und finale gemergte Ergebnisse
|
||||
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator"
|
||||
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
|
||||
php bin/console mto:agent:test:shop-search "testomat lab cl" --intent=advisory_product_search
|
||||
php bin/console mto:agent:test:shop-search "was kostet der indikator" --history="Testomat 808 Indikatortyp 300"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. User-Management
|
||||
## 8. User-Management
|
||||
|
||||
### `mto:agent:user:create`
|
||||
|
||||
Interaktive Anlage eines Users.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:user:create
|
||||
php bin/console mto:agent:user:create
|
||||
```
|
||||
|
||||
**Interaktiver Ablauf**
|
||||
|
||||
1. E-Mail eingeben
|
||||
2. Passwort eingeben
|
||||
3. Rolle wählen
|
||||
3. Passwort wiederholen
|
||||
4. eine oder mehrere Rollen wählen
|
||||
5. Aktivstatus bestätigen
|
||||
|
||||
**Validierungen**
|
||||
|
||||
**Validierungen im Code**
|
||||
- E-Mail muss valide sein
|
||||
- User mit gleicher E-Mail darf nicht bereits existieren
|
||||
- E-Mail darf noch nicht existieren
|
||||
- Passwort muss mindestens 8 Zeichen lang sein
|
||||
- Passwortwiederholung muss übereinstimmen
|
||||
- mindestens eine Rolle muss gewählt werden
|
||||
|
||||
**Zuweisbare Rollen**
|
||||
|
||||
**Im Code auswählbare Rollen**
|
||||
- `ROLE_SUPER_ADMIN`
|
||||
- `ROLE_KNOWLEDGE_ADMIN`
|
||||
- `ROLE_EDITOR`
|
||||
- `ROLE_USER`
|
||||
- `ROLE_ADMIN_AREA`
|
||||
- `ROLE_CHAT_USER`
|
||||
|
||||
**Beispiel**
|
||||
```bash
|
||||
bin/console mto:agent:user:create
|
||||
```
|
||||
`ROLE_USER` wird als technische Basisrolle über die Hierarchie genutzt, ist aber nicht als fachliche Zielrolle in der Auswahl vorgesehen.
|
||||
|
||||
---
|
||||
|
||||
## 8. Typische Betriebsabläufe
|
||||
## 9. Config / Governance
|
||||
|
||||
### `mto:agent:config:validate`
|
||||
|
||||
Validiert die effektive RetrieX-Konfiguration.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:validate [--json]
|
||||
```
|
||||
|
||||
**Erwartung vor Merge/Deployment**
|
||||
|
||||
- Status `OK`
|
||||
- keine Errors
|
||||
|
||||
### `mto:agent:config:audit-source`
|
||||
|
||||
Auditiert YAML-backed Configuration gegen PHP-Defaults, Fallback-Accessors und Constructor-Defaults.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:audit-source [--details] [--json]
|
||||
```
|
||||
|
||||
**Optionen**
|
||||
|
||||
- `--details` zeigt reviewbare Detailzeilen
|
||||
- `--json` gibt maschinenlesbares JSON aus
|
||||
|
||||
### `mto:agent:config:audit-patterns`
|
||||
|
||||
Auditiert verbleibende Pattern-, Token- und Signalnutzung im PHP-Core.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
|
||||
```
|
||||
|
||||
**Zweck**
|
||||
|
||||
- findet konfigurierte Calls wie `preg_match`, `str_contains`, `in_array` usw.
|
||||
- markiert WARN-Funde bei Domain-Marker-Terms
|
||||
- bleibt revieworientiert und nicht selbst runtime-verändernd
|
||||
|
||||
**Beispiel**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:audit-patterns --details
|
||||
```
|
||||
|
||||
### `mto:agent:config:dump-effective`
|
||||
|
||||
Gibt die effektive RetrieX-Konfigurationsinventur aus.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:dump-effective [--summary]
|
||||
```
|
||||
|
||||
**Beispiele**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:dump-effective
|
||||
php bin/console mto:agent:config:dump-effective --summary
|
||||
```
|
||||
|
||||
### `mto:agent:regression:test`
|
||||
|
||||
Führt Offline-Regression-Guards für stabile Pfade aus.
|
||||
|
||||
**Signatur**
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:regression:test [--json]
|
||||
```
|
||||
|
||||
**Zweck**
|
||||
|
||||
- schützt regressionsempfindliche 1.4.x/1.5.x/1.6.0-Flows
|
||||
- prüft Konfigurationspfade, Tokens und Guardrail-Erwartungen
|
||||
- ist Pflichtcheck für Änderungen an YAML-, Prompt-, Retrieval-, Commerce- oder Agent-Logik
|
||||
|
||||
---
|
||||
|
||||
## 10. Typische Betriebsabläufe
|
||||
|
||||
### Manueller Ingest einer Version
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
|
||||
php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
|
||||
```
|
||||
|
||||
### Vorhandenen Ingest-Job ausführen
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:ingest:run <jobUuid>
|
||||
php bin/console mto:agent:ingest:run <jobUuid>
|
||||
```
|
||||
|
||||
### Nur Chunk-Vektorindex neu bauen
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:vector:rebuild
|
||||
php bin/console mto:agent:vector:rebuild
|
||||
```
|
||||
|
||||
### Gesamtsystem hart neu aufbauen
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:system:rebuild --hard
|
||||
php 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
|
||||
php bin/console mto:agent:vector:health
|
||||
php bin/console mto:agent:vector:control --status
|
||||
php bin/console mto:agent:vector:control --reload
|
||||
```
|
||||
|
||||
### Tag-Retrieval neu aufbauen
|
||||
|
||||
```bash
|
||||
bin/console mto:agent:tags:rebuild
|
||||
bin/console mto:agent:tag:health
|
||||
php bin/console mto:agent:tags:rebuild
|
||||
php bin/console mto:agent:tag:health --summary
|
||||
```
|
||||
|
||||
### Shopquery mit Repair testen
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
|
||||
```
|
||||
|
||||
### Config-Änderung prüfen
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:config:validate
|
||||
php bin/console mto:agent:config:audit-source --details
|
||||
php bin/console mto:agent:config:audit-patterns --details
|
||||
php bin/console mto:agent:regression:test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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/`.
|
||||
## 11. Wichtige Runtime-Dateien und Pfade
|
||||
|
||||
```text
|
||||
var/
|
||||
@@ -458,128 +655,52 @@ var/
|
||||
│ ├── 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`
|
||||
Herkunft im Code:
|
||||
|
||||
- `config/services.yaml` bindet `mto.knowledge.*` an `retriex.knowledge.*`.
|
||||
- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`.
|
||||
- `App\Service\LockService` verwendet `var/locks/ingest.lock`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Wichtige Abweichungen zur alten `COMMAND_REF.md`
|
||||
## 12. Wichtige Korrekturen gegenüber älteren Referenzen
|
||||
|
||||
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`
|
||||
1. Der aktuelle Stand enthält **21** projektspezifische Commands, nicht nur die älteren 18.
|
||||
2. `mto:agent:eval:run` ist Teil des aktuellen Command-Sets.
|
||||
3. `mto:agent:retrieval:test` testet den realen hybriden Retrieval-Pfad und ergänzt `mto:agent:test-vector`.
|
||||
4. `mto:agent:test:shop-search` ist im aktuellen Stand mit `query`, `--intent`, `--history` und `--repair` codekonform dokumentiert.
|
||||
5. `mto:agent:tag:health` unterstützt `--summary`.
|
||||
6. `mto:agent:user:create` kann mehrere Rollen auswählen und fragt Aktivstatus ab.
|
||||
7. Zuweisbare Rollen umfassen `ROLE_ADMIN_AREA` und `ROLE_CHAT_USER`.
|
||||
8. `mto:agent:ingest:version` braucht weiterhin zwei Pflichtargumente: `<versionId> <userId>`.
|
||||
9. Der globale Rebuild läuft über `mto:agent:system:rebuild --hard`.
|
||||
10. Runtime-Artefakte liegen überwiegend unter `var/knowledge/`.
|
||||
|
||||
---
|
||||
|
||||
## 13. Fazit
|
||||
|
||||
## 11. Config-Governance / YAML-only Guardrails
|
||||
Für den operativen Betrieb sind besonders relevant:
|
||||
|
||||
These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths.
|
||||
|
||||
### `mto:agent:config:validate`
|
||||
|
||||
Validates the effective RetrieX configuration.
|
||||
|
||||
**Signature**
|
||||
```bash
|
||||
bin/console mto:agent:config:validate [--json]
|
||||
```
|
||||
|
||||
**Expected result before merge**
|
||||
- status `OK`
|
||||
- no errors
|
||||
|
||||
### `mto:agent:config:audit-source`
|
||||
|
||||
Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.
|
||||
|
||||
**Signature**
|
||||
```bash
|
||||
bin/console mto:agent:config:audit-source [--details] [--json]
|
||||
```
|
||||
|
||||
**Expected result before merge**
|
||||
- no missing YAML mappings
|
||||
- no new undocumented PHP-only semantic constants
|
||||
- no constructor defaults without YAML/service-parameter mapping
|
||||
|
||||
Use `--details` for reviewable console output and `--json` for machine-readable CI output.
|
||||
|
||||
### `mto:agent:config:dump-effective`
|
||||
|
||||
Dumps the effective RetrieX configuration inventory.
|
||||
|
||||
**Signature**
|
||||
```bash
|
||||
bin/console mto:agent:config:dump-effective [--summary]
|
||||
```
|
||||
|
||||
Use `--summary` for a compact review view.
|
||||
|
||||
### `mto:agent:regression:test`
|
||||
|
||||
Runs offline regression guards for stable configuration paths.
|
||||
|
||||
**Signature**
|
||||
```bash
|
||||
bin/console mto:agent:regression:test [--json]
|
||||
```
|
||||
|
||||
**Expected result before merge**
|
||||
- status `OK`
|
||||
- all checks pass
|
||||
|
||||
This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.
|
||||
|
||||
---
|
||||
|
||||
## 12. Fazit
|
||||
|
||||
Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens **18 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
|
||||
|
||||
- `mto:agent:ingest:run`
|
||||
- `mto:agent:system:rebuild`
|
||||
- `mto:agent:vector:control`
|
||||
- `mto:agent:system:rebuild --hard`
|
||||
- `mto:agent:vector:control --status|--reload|--start`
|
||||
- `mto:agent:vector:health`
|
||||
- `mto:agent:tags:rebuild`
|
||||
- `mto:agent:tag:health`
|
||||
- `mto:agent:tag:health --summary`
|
||||
- `mto:agent:ingest:run`
|
||||
- `mto:agent:config:validate`
|
||||
- `mto:agent:regression:test`
|
||||
|
||||
### `mto:agent:config:audit-patterns`
|
||||
Für Entwicklung und Fehlersuche sind besonders hilfreich:
|
||||
|
||||
Audits remaining pattern-, token- and signal-sensitive calls in PHP core files for developer-policy review.
|
||||
|
||||
**Signature**
|
||||
```bash
|
||||
bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
|
||||
```
|
||||
|
||||
**Purpose**
|
||||
- finds configured calls such as `preg_match`, `str_contains`, `in_array` and related pattern/token helpers in configured source roots
|
||||
- raises WARN findings when configured domain marker terms are involved
|
||||
- keeps the command non-blocking and review-oriented; it does not change runtime behavior and does not activate strict validation
|
||||
|
||||
**Options**
|
||||
- `--details` renders reviewable warning rows
|
||||
- `--json` renders machine-readable audit output
|
||||
- `--all` includes lower-priority REVIEW findings in addition to WARN findings
|
||||
|
||||
**Expected use before merge**
|
||||
```bash
|
||||
bin/console mto:agent:config:audit-patterns --details
|
||||
```
|
||||
|
||||
Review WARN findings and move new semantic terms, product names, intent words, commerce signals or retrieval/follow-up patterns to YAML-backed configuration when they are not purely technical.
|
||||
- `mto:agent:chat`
|
||||
- `mto:agent:retrieval:test`
|
||||
- `mto:agent:test-vector`
|
||||
- `mto:agent:test:shop-search --repair`
|
||||
- `mto:agent:config:dump-effective --summary`
|
||||
- `mto:agent:config:audit-patterns --details`
|
||||
|
||||
Reference in New Issue
Block a user