electron-rare/le-mystere-professeur-zacus

Files

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

2.4 KiB

Raw Permalink Blame History

Quickstart

Vue canonique

Source de vérité: game/scenarios/zacus_v2.yaml
Studio auteur: frontend-scratch-v2/
Runtime portable: Zacus Runtime 3
Cible terrain principale: hardware/firmware sur freenove_esp32s3
Shell d'orchestration: tools/dev/zacus.sh

Valider le contenu

bash tools/setup/install_validators.sh
bash tools/test/run_content_checks.sh --install-missing

Checks inclus:

validation scénario
compilation Runtime 3
simulation Runtime 3
validation runtime bundle
validation audio
validation printables
export Markdown

Compiler le runtime portable

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/verify_runtime3_pivots.py game/scenarios/zacus_v2.yaml
python3 -m unittest discover -s tests/runtime3 -p 'test_*.py'
python3 tools/scenario/export_runtime3_firmware_bundle.py game/scenarios/zacus_v2.yaml

Ou via le shell canonique:

./tools/dev/zacus.sh runtime3-compile
./tools/dev/zacus.sh runtime3-simulate
./tools/dev/zacus.sh runtime3-verify
./tools/dev/zacus.sh runtime3-test
./tools/dev/zacus.sh frontend-test

Les artefacts sont écrits sous artifacts/runtime3/<timestamp>/. Le bundle firmware canonique est écrit dans hardware/firmware/data/story/runtime3/DEFAULT.json.

Démarrer le studio React + Blockly

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

Pour un build local:

./tools/dev/zacus.sh frontend-build

Générer la documentation

python3 -m pip install --user --break-system-packages -r tools/requirements/docs.txt
python3 -m mkdocs build --strict

Ou:

./tools/dev/zacus.sh docs-build

Valider le firmware

cd hardware/firmware
pio run -e freenove_esp32s3
pio run -e esp8266_oled

Chemin mono-carte recommandé:

cd hardware/firmware
ZACUS_ENV="freenove_esp32s3" ./tools/dev/run_matrix_and_smoke.sh

Utiliser le shell Zacus

./tools/dev/zacus.sh content-checks
./tools/dev/zacus.sh ports
./tools/dev/zacus.sh artifacts-summary
./tools/dev/zacus.sh menu

Le menu utilise gum si disponible et repasse en mode texte sinon.

Où regarder ensuite

docs/architecture/index.md
plans/master-plan.md
todos/master.md
hardware/firmware/docs/AGENT_TODO.md

2.4 KiB Raw Permalink Blame History