故障排查
这篇文档提供按问题定位的排查路径。处理任何可能影响数据的操作前，请先备份。
先判断问题类型
遇到异常时，先把问题归到一个类别：
- 模型问题：连接失败、超时、供应商报错、输出格式不稳定。
- 任务问题：任务卡住、失败、等待恢复、重复执行。
- 知识库问题：文档无法索引、检索不到、召回内容不相关。
- 数据问题：小说打不开、内容缺失、状态不一致。
- 前端问题：页面没有刷新、按钮不可点、入口找不到。
分类后再看对应入口，排查会更快。
查看任务状态
长任务优先看任务中心。任务中心会展示排队、运行、完成、失败和可恢复状态。
建议记录：
- 任务名称。
- 关联小说。
- 最近一次状态。
- 错误信息。
- 是否有重试或恢复按钮。
如果任务仍在运行，不要重复点击多个入口发起同类任务。先确认后台是否正在处理。
查看导演跟进
自动导演相关问题优先看导演跟进。它会告诉你系统停在方向选择、设定准备、章节计划、章节执行还是恢复节点。
常见处理方式：
- 等待你确认候选：选择一个方向或方案。
- 缺少基础信息：回到小说页补充。
- 任务失败但可重试：从恢复入口继续。
- 需要重新规划：按提示回到上一级计划。
局部章节质量问题通常可以记录为质量债务，不一定要停止整本书。
模型问题排查
模型错误按这个顺序处理：
- 在系统设置里测试连接。
- 确认 API Key、Base URL 和模型名称。
- 检查供应商额度、并发限制和网络。
- 换一个更稳定的模型执行同类任务。
- 如果结构化输出失败，优先把审核、修复、拆书任务路由到更遵循格式的模型。
不要用硬编码关键词绕过 AI 任务判断。产品主链的意图识别、规划和路由应依赖结构化 AI 输出。
知识库问题排查
知识库不命中时，按顺序检查：
- 文档是否上传成功。
- 索引任务是否完成。
- Qdrant 是否可连接。
- 检索设置是否过窄。
- 当前问题是否真的需要该文档。
如果文档内容很长，可以在文档标题、摘要或关键段落里明确写出设定名、角色名、地点名和主题词，方便召回。
数据备份建议
在执行数据清理、迁移、数据库重置或手动删除前，必须先备份。
最低备份要求：
- 复制数据库文件到明确路径。
- 检查备份文件存在且大小正常。
- 记录备份时间和来源目录。
更稳妥的做法是再导出小说内容，并保留任务错误截图或日志。
页面显示问题
如果页面状态看起来不一致：
- 刷新页面。
- 回到首页或小说列表重新进入。
- 检查任务中心是否有后台任务仍在运行。
- 查看导演跟进是否显示等待确认。
- 记录入口、操作步骤和错误截图。
不要只凭单个页面判断任务是否失败。后台任务、导演跟进和小说页可能展示同一流程的不同侧面。
提交问题时提供什么
如果需要向维护者反馈，建议提供：
- 应用版本或源码分支。
- 操作入口和步骤。
- 关联小说是否为新建项目。
- 任务中心状态和错误信息。
- 模型供应商和任务类型。
- 是否配置 Qdrant。
- 日志或截图。
信息越完整，越容易判断是模型、任务、知识库、数据还是页面问题。