Developer Guide · 15
Testing & Debugging
15.1 Backend Debugging
- API docs: http://localhost:8000/docs (Swagger UI)
- Log level:
LOG_LEVELenvironment variable +main.py::logging.basicConfig(level=logging.INFO) - WeChat logs: requires
logging.basicConfig(level=logging.INFO), otherwisewechat.*logs won't output - Langfuse tracing: after enabling, view Agent execution chain in Langfuse UI (v3 SDK reads from env automatically)
- Sandbox diagnostics:
script_runner.get_script_runtime_stats()returns current active/pending script counts
15.2 Frontend Debugging
- Vite HMR:
npm run devsupports hot module replacement - React DevTools: install in browser
- Network: inspect SSE connections (
Accept: text/event-stream) and API requests
15.3 Common Debugging Scenarios
| Symptom | Investigation |
|---|---|
| SSE not working | Vite proxy config, Accept header, Express proxy buffer |
| Agent hangs | POST /api/chat/stop, check backend logs, get_script_runtime_stats() |
| File operation errors | path_security logs, safe_join boundary |
| WeChat messages not delivering | wechat.* logs, iLink connection status, context_token expiry |
WeChat shows literal <<FILE:>> | Check if delivery.py::extract_media_tags was called |
| Scheduled task not running | scheduler.py 30s loop logs, tz_offset_hours field |
| Inbox not triggering WeChat | _main_loop injected, Admin WeChat connected |
| Script "queue busy" | SCRIPT_CONCURRENCY env var + SCRIPT_QUEUE_TIMEOUT |
| Tauri startup reports pycryptodome error | \\?\ extended prefix (see §12.5.1) |