开发者指南 · 15
测试与调试
15.1 后端调试
- API 文档：http://localhost:8000/docs（Swagger UI）
- 日志级别：
LOG_LEVEL环境变量 +main.py::logging.basicConfig(level=logging.INFO) - WeChat 日志：必须有
logging.basicConfig(level=logging.INFO)否则wechat.*日志不输出 - Langfuse 追踪：启用后可在 Langfuse UI 查看 Agent 执行链路（v3 SDK 自动从 env 读）
- 沙箱诊断：
script_runner.get_script_runtime_stats()返回当前 active/pending 脚本数
15.2 前端调试
- Vite HMR：
npm run dev支持热模块替换 - React DevTools：浏览器安装
- Network：检查 SSE 连接（
Accept: text/event-stream）和 API 请求
15.3 常见调试场景
| 症状 | 排查方向 |
|---|---|
| SSE 不通 | Vite proxy 配置、Accept header、Express 代理 buffer |
| Agent 卡死 | POST /api/chat/stop、查后端日志、get_script_runtime_stats() |
| 文件操作报错 | path_security 日志、safe_join 边界 |
| 微信消息不送达 | wechat.* 日志、iLink 连接状态、context_token 是否过期 |
微信看到 <<FILE:>> 字面 | delivery.py::extract_media_tags 是否被调用 |
| 定时任务不执行 | scheduler.py 30s 循环日志、tz_offset_hours 字段 |
| Inbox 不触发 WeChat | _main_loop 是否注入、Admin WeChat 是否已连接 |
| 脚本"队列繁忙" | SCRIPT_CONCURRENCY 环境变量 + SCRIPT_QUEUE_TIMEOUT |
| Tauri 启动报 pycryptodome | \\?\ 扩展前缀（见 §12.5.1） |