electron-rare/le-mystere-professeur-zacus
1
0
Fork 0
Code Issues 1 Pull Requests 2 Actions 1 Packages Projects Releases Wiki Activity
Files
20aed903babbe48f6f252810bd48e92008f79384
le-mystere-professeur-zacus/README.md
T
L'électron rare 20aed903ba feat: AI integration — voice pipeline, hints engine, MCP server, analytics, security 
- Voice pipeline: ESP32 WebSocket client → voice bridge → LLM → Piper TTS (Tower :8001)
- Hints engine: 3 puzzles (LA_440, LEFOU_PIANO, QR_FINALE), anti-cheat, 3 hint levels
- MCP hardware server: 6 tools (puzzle, audio, LED, camera, scenario, status), stdio transport
- Analytics: ESP32 module + 6 web endpoints + Dashboard UI with chat interface
- Security: auth middleware (Bearer NVS), rate limiting, input validation on 30 endpoints
- Frontend: code-split (1.1MB → 210KB initial), ErrorBoundary, API timeout, WS reconnect
- Tests: 24 Python + 38 TypeScript + 18 MCP = 80 project tests (+ 19 mascarade)
- Specs: AI_INTEGRATION_SPEC, MCP_HARDWARE_SERVER_SPEC, QA_TEST_MATRIX_SPEC
- Docs: SECURITY, DEPLOYMENT_RUNBOOK, voice pipeline guide, AI architecture map
- 6 AI agent definitions (.github/agents/ai_*.md)
- TUI orchestration script (tools/dev/zacus_tui.py)
- Docker compose TTS for Tower + KXKM-AI
- CHANGELOG, README, mkdocs.yml updated
- Cycle detection (DFS) in runtime3 validator
- Sprint plan: plans/SPRINT_AI_INTEGRATION.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 13:52:45 +01:00

3.7 KiB
Raw Blame History

Le Mystere du Professeur Zacus

Zacus est en refonte vers un produit hybride unique:

  • un jeu terrain fiable sur carte Freenove ESP32-S3,
  • un studio auteur moderne en React + Blockly,
  • un runtime portable "Zacus Runtime 3" compile depuis le YAML canonique.

Canon actuel

  • Source narrative: game/scenarios/zacus_v2.yaml
  • Studio auteur: frontend-scratch-v2/
  • Runtime portable: tools/scenario/compile_runtime3.py + tools/scenario/simulate_runtime3.py
  • Cible hardware principale: hardware/firmware avec freenove_esp32s3
  • Plans et memoire: memory/, plans/, todos/
  • Architecture et cartes Mermaid: docs/architecture/

Démarrage rapide

1. Bootstrap validation

bash tools/setup/install_validators.sh
bash tools/test/run_content_checks.sh

2. Compiler et simuler Runtime 3

python3 tools/scenario/compile_runtime3.py game/scenarios/zacus_v2.yaml
python3 tools/scenario/simulate_runtime3.py game/scenarios/zacus_v2.yaml
python3 tools/scenario/export_runtime3_firmware_bundle.py game/scenarios/zacus_v2.yaml

3. Démarrer le studio React + Blockly

cd frontend-scratch-v2
npm install
npm test
VITE_STORY_API_BASE=http://<esp_ip>:8080 npm run dev

4. Utiliser le shell canonique

./tools/dev/zacus.sh content-checks
./tools/dev/zacus.sh runtime3-compile
make runtime3-verify
make runtime3-test
./tools/dev/zacus.sh frontend-test
./tools/dev/zacus.sh frontend-build
./tools/dev/zacus.sh menu

Cartographie du dépôt

  • game/: scénarios YAML canoniques.
  • audio/: manifestes audio et assets associés.
  • printables/: manifestes et exports imprimables.
  • kit-maitre-du-jeu/: matériel MJ et déroulé terrain.
  • frontend-scratch-v2/: studio auteur React + Blockly.
  • hardware/firmware/: firmware, APIs device, scripts terrain.
  • tools/: validateurs, compilateur/simulateur Runtime 3, shells d'automatisation.
  • docs/: quickstart, architecture, benchmark OSS et runbooks.
  • memory/, plans/, todos/: pilotage de la refonte.

AI Integration

Le projet intègre une couche IA pour enrichir l'expérience terrain :

  • Voice pipeline : wake word (ESP-SR) → ASR → LLM → TTS (Piper / XTTS-v2) → speaker. Scaffold prêt, voir docs/voice/VOICE_PIPELINE_GUIDE.md.
  • Vision : détection d'objets via ESP-DL pour indices contextuels.
  • LLM hints : le Professeur Zacus répond aux joueurs via mascarade.
  • TUI dev : script interactif d'orchestration → python3 tools/dev/zacus_tui.py

Analyse complète : docs/AI_INTEGRATION_ANALYSIS.md

Sécurité & Déploiement

Statut du projet

  • Runtime 3 : compilateur + simulateur + export firmware bundle OK
  • Studio auteur : React 19 + Blockly, 18 tests passing
  • Firmware : sécurité P0 intégrée (HMAC, rate limit, safe OTA)
  • Voice pipeline : scaffold ESP-SR prêt, TTS Docker validé
  • Specs : ZACUS_RUNTIME_3_SPEC.md, STORY_DESIGNER_SCRATCH_LIKE_SPEC.md

Documentation à lire

  • docs/QUICKSTART.md
  • docs/architecture/index.md
  • docs/AI_INTEGRATION_ANALYSIS.md
  • specs/ZACUS_RUNTIME_3_SPEC.md
  • specs/STORY_DESIGNER_SCRATCH_LIKE_SPEC.md
  • docs/benchmark-oss.md

Notes de refonte

  • Le YAML reste la source de vérité pendant la migration.
  • Le Runtime 3 devient le contrat portable entre studio, simulateur et firmware.
  • hardware/firmware/esp32/ reste en lecture seule.
  • Les chemins legacy ne doivent être supprimés qu'après preuve de remplacement.

Licences

  • Code: MIT (LICENSE)
  • Contenu créatif: CC BY-NC 4.0 (LICENSE-CONTENT.md)
Reference in New Issue View Git Blame Copy Permalink