docs: Comprehensive lessons learned from Competitor Analysis migration
This commit is contained in:
@@ -1,14 +1,46 @@
|
||||
# Migration Guide: Google AI Builder Apps -> Local Docker Stack
|
||||
|
||||
> **WICHTIGER HINWEIS:** Der Gemini-Agent f"."hrt Code **innerhalb** dieses Docker-Containers aus. Er hat keinen Zugriff auf den Docker-Daemon des Host-Systems. Daher kann und wird der Agent **NIEMALS** in der Lage sein, Befehle wie `docker build`, `docker-compose up` oder andere Docker-Management-Aufgaben auszuf.hren. Diese Befehle m.ssen immer vom Benutzer auf dem Host-System ausgef.hrt werden.
|
||||
> **CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):**
|
||||
|
||||
>
|
||||
|
||||
> 1. **PYTHON PROMPTS (F-STRINGS STRENG VERBOTEN):** Nutze **NIEMALS** `f"""..."""` für komplexe Prompts mit JSON/Markdown. Das führt zu unlösbaren `SyntaxError: unterminated string literal` Schleifen. Nutze **AUSSCHLIESSLICH** `r"""...
|
||||
|
||||
""".format(...)`.
|
||||
|
||||
> 2. **SDK WAHL (MODERN FIRST):** Das alte `google-generativeai` Paket ist "Legacy". Nutze für alle neuen Projekte das moderne **`google-genai`** Paket. Es löst alle Probleme mit API-Versionen (`v1beta`) und unterstützt JSON-Modus/Schemata nativ.
|
||||
|
||||
> 3. **DOCKER VOLUMES (404-FALLE):** Mounte **NIEMALS** das gesamte App-Verzeichnis (`.:/app`), wenn darin ein `dist`-Ordner (Build-Artefakt) im Image liegt. Du löschst damit die gebaute Web-App im Container. Mounte nur die spezifische Orchestrator-Datei.
|
||||
|
||||
> 4. **FRONTEND BUILD:** `vite`, `typescript` etc. gehören in `dependencies`, NICHT `devDependencies`, da sie sonst im Docker-Multi-Stage-Build fehlen.
|
||||
|
||||
**Ziel:** Standardisierter Prozess, um eine von Google AI Studio generierte React-App schnell, robust und fehlerfrei in die lokale Docker/Python-Architektur zu integrieren.
|
||||
|
||||
**Grundsatz:** "Minimalset & Robustheit". Wir bauen keine aufgebl.hten Container, und wir verhindern Timeouts und fehlende Abh.ngigkeiten proaktiv.
|
||||
|
||||
---
|
||||
|
||||
## 1. Vorbereitung & Abh.ngigkeiten (Common Pitfalls)
|
||||
|
||||
|
||||
## 0. Der "Quick-Start" Checkliste (5-Minuten-Plan)
|
||||
|
||||
|
||||
|
||||
1. **SDK:** Steht `google-genai` in der `requirements.txt`? (Wenn nein -> hinzufügen).
|
||||
|
||||
2. **Prompts:** Sind alle Prompts als `.format()`-Strings angelegt? (Wenn nein -> umstellen).
|
||||
|
||||
3. **Package.json:** Sind `vite`, `typescript`, `react-router` in `dependencies`? (Wenn nein -> verschieben).
|
||||
|
||||
4. **Docker-Compose:** Wird nur die `.py`-Datei gemountet? (Wenn nein -> korrigieren).
|
||||
|
||||
5. **Vite Config:** Ist `base: './'` gesetzt? (Muss immer).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 1. Vorbereitung & Abhängigkeiten (Common Pitfalls)
|
||||
|
||||
Bevor Code kopiert wird, m.ssen die Grundlagen stimmen.
|
||||
|
||||
@@ -72,33 +104,37 @@ requests
|
||||
beautifulsoup4
|
||||
```
|
||||
|
||||
### 1.5 Python Syntax & F-Strings
|
||||
Multi-Line Prompts k.nnen in Docker-Umgebungen zu **sehr hartn.ckigen Syntaxfehlern** f.hren, selbst wenn sie lokal korrekt aussehen.
|
||||
### 1.5 Python Syntax & F-Strings (Der Prompt-Albtraum)
|
||||
Multi-Line Prompts in Kombination mit `f-strings`, JSON und Markdown führen in Docker-Umgebungen zu **extrem hartnäckigen Syntaxfehlern** (`SyntaxError: unterminated string literal`), die oft nicht reproduzierbar wirken.
|
||||
|
||||
* **Das Problem:** Der Python-Parser (insbesondere bei `f-strings` in Kombination mit Zahlen/Punkten am Zeilenanfang oder verschachtelten Klammern) kann Multi-Line-Strings (`f"""..."""`) falsch interpretieren, was zu Fehlern wie `SyntaxError: invalid decimal literal` oder `unmatched ')'` f.hrt, auch wenn der Code scheinbar korrekt ist.
|
||||
* **Das Problem:** Der Python-Parser stolpert über verschachtelte Anführungszeichen (`"`, `'`), geschweifte Klammern `{}` (die in JSON und f-strings vorkommen) und Backslashes. Ein einziges falsch interpretiertes Zeichen sprengt den gesamten String.
|
||||
|
||||
* **ULTIMATIVE L.SUNG (Maximale Robustheit):**
|
||||
1. **Vermeide `f"""` komplett f.r komplexe Multi-Line-Prompts.** Definiere stattdessen den Prompt als **Liste von einzelnen String-Zeilen** und f.ge sie mit `"\n".join(prompt_parts)` zusammen.
|
||||
2. **Nutze die `.format()` Methode oder f-Strings in EINZEILIGEN Strings** zur Variablen-Injektion. Dies trennt die String-Definition komplett von der Variablen-Interpolation und ist die robusteste Methode.
|
||||
* **ULTIMATIVE LÖSUNG (Die einzig wahre Methode):**
|
||||
Vergessen Sie `f-strings` für komplexe Prompts! Nutzen Sie **Raw Strings (`r"""..."""`)** kombiniert mit der **`.format()` Methode**.
|
||||
|
||||
1. **Raw Strings (`r"..."`):** Verhindern, dass Backslashes als Escape-Sequenzen interpretiert werden.
|
||||
2. **`.format()`:** Trennt den Text sauber von den Variablen.
|
||||
|
||||
**FALSCH (Explosionsgefahr):**
|
||||
```python
|
||||
# Beispiel: Maximal robust
|
||||
prompt_template_parts = [
|
||||
"1) Mache dies: {variable_1}",
|
||||
"2) Mache das: {variable_2}",
|
||||
]
|
||||
prompt_template = "\n".join(prompt_template_parts)
|
||||
prompt = prompt_template.format(variable_1=wert1, variable_2=wert2)
|
||||
# System-Instruktion muss immer noch vorangestellt werden:
|
||||
full_prompt = sys_instr + "\n\n" + prompt
|
||||
prompt = f"""
|
||||
Analysiere "{request.name}". Antworte im JSON-Format: {{"key": "value"}}
|
||||
"""
|
||||
```
|
||||
|
||||
* **Versionierung f.r Debugging:** Um sicherzustellen, dass die korrekte Version des Codes l.uft, f.ge Versionsnummern in die Start-Logs des Node.js Servers (`server.cjs`) und des Python Orchestrators (`gtm_architect_orchestrator.py`) ein.
|
||||
* `server.cjs`: `console.log(`... (Version: ${VERSION})`);`
|
||||
* `gtm_architect_orchestrator.py`: `print(f"DEBUG: Orchestrator v{__version__} loaded ...")`
|
||||
**RICHTIG (Robust & Sicher):**
|
||||
```python
|
||||
prompt = r"""
|
||||
Analysiere "{name}". Antworte im JSON-Format: {{"key": "value"}}
|
||||
""".format(name=request.name)
|
||||
```
|
||||
|
||||
* **Signaturen pr.fen:** Shared Libraries (`helpers.py`) haben oft .ltere Signaturen. Immer die tats.chliche Definition pr.fen!
|
||||
* Beispiel: `call_openai_chat` unterst.tzt oft kein `system_message` Argument. Stattdessen Prompt manuell zusammenbauen (`sys_instr + "\n\n" + prompt`).
|
||||
### 1.6 Volume Mounts & Datei-Synchronisierung (Phantom-Fehler)
|
||||
Wenn Sie Code ändern, der Fehler aber bestehen bleibt ("Geisterfehler"), synchronisiert Docker die Datei nicht korrekt.
|
||||
|
||||
* **Symptom:** `SyntaxError` an Zeilen, die Sie gerade korrigiert haben.
|
||||
* **Ursache:** Einzeldatei-Mounts (`- ./file.py:/app/file.py`) sind oft unzuverlässig, besonders wenn die Inode der Datei durch Editoren geändert wird.
|
||||
* **Lösung:** Mounten Sie das **gesamte Verzeichnis** (`- ./my-app:/app`) oder bauen Sie das Image neu (`COPY . .` im Dockerfile) und entfernen Sie den Volume-Mount temporär zur Diagnose.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user