Files
esp32-server/docs/engineering-log/2026-10-03-phase1-skeleton.md
Macky 52d9ecfb70 docs: handoff + engineering log (Phase 1 complete)
- docs/HANDOFF.md: resume steps for the 5060 Ti voice-server
- docs/engineering-log.md + dated entry, test-evidence
- git diff --check clean
2026-10-03 11:57:28 +07:00

2.5 KiB

2026-10-03 — Phase 1 skeleton complete (first push)

Plan status

Phase 1 = complete (testable skeleton). Phase 2+ pending on voice-server.

What was built

Full repo structure per plan: app/ (main, config, xiaozhi/, audio/, stt/, tts/, hermes/, security/, metrics/, gpu/), tests/, config.yaml, requirements.txt, README.md, docs/.

Key decisions

  • All backends mock by default in config.yaml → bridge boots and tests green on CPU-only Mac; real backends lazy-imported, activated by config on voice-server (CON-002 verified: no GPU/audio libs in sys.modules at import).
  • Voice profile guard (app/hermes/__init__.py::VoiceProfile) asserts reasoning == "none" and tools == ["session_search"] at startup → bad config fails boot, not conversation (AC-004).
  • History ownership: Session.run_turn is the single push site for conversation history (a double-push bug found+fixed during test authoring).
  • Chunker (app/tts/__init__.py::chunk_text): split class is [.!?。!?\u0e3f] ONLY — Thai vowel/tone marks (U+0E40/41/48) are NOT split points (initial implementation split on them and would have broken every word; caught in review). Delimiter stays attached to its fragment for TTS intonation. 60-char hard cap; ≤4-char micro-fragments merged.

Evidence

  • pytest -q → 18 passed (0.13s) — protocol, config, auth, chunker, barge-in queue, latency, voice-profile guard, GPU planner, VAD, e2e mock spoken turn, app import + live WS handshake+turn.
  • python -c "import app.main" → OK.
  • chunk_text("สวัสดี. แล้วไง? ครับ") → ["สวัสดี.", "แล้วไง?", "ครับ"] (direct call).
  • sys.modules scan after import → no torch/typhoon/whisper/jait/opus/numpy (CON-002).
  • See docs/test-evidence/2026-10-03-phase1-pytest.txt.

Risks / open

  • # FIRMWARE protocol constants (hello_version=1, frame_ms=20, Opus 16 kHz mono) are PoC assumptions — must verify against real Xiaozhi firmware before Phase 2 (CON-004).
  • openai_http Hermes transport implemented but untested live (mock is the tested path).
  • VAD end-of-speech silence-gap logic is PoC (one utterance = one binary message in tests).

Next action (voice-server)

  1. venv + pip install -r requirements.txt
  2. Protocol verification against real firmware (CON-004) — first and blocking
  3. Wire typhoon_endpoint, jaitts_endpoint, Hermes openai_http base_url/api_key
  4. Real device tokens in config.yaml
  5. Cloudflare tunnel hostname → 127.0.0.1:8765