排错手册¶
启动阶段问题¶
症状：前端窗口打开了，但功能全部不可用¶
优先判断后端是否已启动：
- 访问 http://127.0.0.1:8765/api/health
- 如果不可访问，检查 dev.bat 或打包态启动日志
- 检查 8765 端口是否被旧进程占用
症状：打包态启动时出现空白壳或透明框¶
先检查窗口启动逻辑是否破坏了 splash 与主窗口的分流。当前项目对这一点较敏感，不要把多窗口判断和主应用 Hook 顺序混写。
ASR 相关问题¶
症状：转录内容碎、重复、前后覆盖异常¶
优先检查：
- 当前使用的是 local 还是 seed-asr
- 是否错误地把 partial 文本全部当成最终结果写盘
- 去重、句子合并和时间戳逻辑是否被改坏
症状：麦克风检测失败¶
优先检查：
- 系统麦克风权限
- 本机是否有默认输入设备
- PyAudio 是否正确安装
LLM 相关问题¶
症状：救场和总结全部返回错误¶
优先检查：
- LLM_BASE_URL 是否可访问
- LLM_API_KEY 是否有效
- LLM_MODEL 是否填写正确
- 当前网络环境是否阻断了请求
症状：模型能返回，但结果质量差¶
优先检查：
- 当前课堂资料是否为空
- 最近转录是否过短
- 课堂内容是否已被错误去重或压缩
打包问题¶
症状：build.ps1 在 PyInstaller 阶段失败¶
优先检查：
- api-service/.venv 是否存在
- pyinstaller 是否安装在该环境中
- 是否有依赖导入失败
症状：release 目录存在，但 exe 运行无响应¶
优先检查：
- backend 目录是否完整复制
- backend/.env 是否存在
- 主程序是否能拉起 class-assistant-backend.exe
- 端口是否被其它进程占用
文档问题¶
症状：mkdocs serve 失败¶
优先检查：
- 是否已安装 requirements-docs.txt
- 当前命令是否在仓库根目录执行
- mkdocs.yml 是否存在 YAML 缩进错误