故障排查¶
先记录系统、架构、应用版本、发生时间和界面错误码。日志和截图应移除 API Key、配对二维码及课堂敏感内容。
| 现象 | 检查与恢复 |
|---|---|
| 本地服务断开 | 保留界面提示的未保存文字，点击「恢复本地服务」；仍失败时检查用户数据目录权限和完整安装包 |
| 麦克风启动失败 | 检测设备，检查系统麦克风权限和输入设备；可切换文本模式保留课堂，不强杀其他音频应用 |
| 模型下载失败 | 检查可用磁盘和下载源连通性，使用重试；只有摘要校验与加载检查成功才会标记安装完成 |
| 模型进程退出 | 检查可用内存及安装状态，重新准备模型；同一实例清理不会按端口杀其他服务 |
| BYOK 鉴权或限额错误 | 在对应服务商检查 Key、地区、模型权限和余额，重新保存后用连接测试验证 |
| 笔记生成中断 | 原文仍可查看/导出；重试或缩小问题，不能把不完整流保存为成功笔记 |
| 资料解析失败 | 检查格式和大小，将旧 Office 格式转换后重新上传；扫描 PDF 先 OCR；损坏文件重新导出 |
| 旧数据未导入 | 确认选择的是旧 data/，查看跳过项；保留原件，不通过手工修改新数据库解决 |
| 微信历史损坏/存储满 | 健康记录仍可浏览；先复制或分享可恢复内容，再按界面提示处理对应记录 |
开发时优先用合成文本复现，再定位 API、音频、模型或原生边界。真实进程退出只操作自己创建并持有的 PID；不要按进程名或固定端口清理。