常见报错
磁盘空间不足、文件只读、只读介质、文件被占用、项目已在另一窗口打开、库缺失、AI 与更新报错的处理。
按应用里实际出现的提示整理。每条都写清触发条件、处理办法，以及这一步失败会不会影响已有正文。
写入文件失败（重试 3 次后仍无法替换，原文未改动）
保存时会重试三次，仍无法替换目标文件才报这条；提示后半句会跟一个具体原因，例如「（文件正被其他程序独占，请先关闭占用它的程序）」「（目标文件被其他程序独占，或只读、没有写权限；请关闭占用它的程序或去掉只读属性）」「（磁盘空间不足，请清理后重试）」「（路径不存在，请检查目录是否被移动或删除）」。找不到已知原因时只显示「（原文未改动）：未知原因」。
- 先按括号里的原因处理：关闭可能占用文件的程序，或去掉只读属性。
- 处理后按 Ctrl + S 重试。
- 提示里写明「原文未改动」：磁盘上的内容还是上一次成功保存的版本，编辑框里的文字仍在，不会因为这次失败被清空。
目标文件被其他程序独占，或只读、没有写权限
这是系统错误码 5 的话术。关闭占用该文件的程序，或去掉文件/目录的只读属性；也可以把整个项目复制到当前用户可写的目录后再打开。
磁盘空间不足，请清理后重试
保存、生成快照或打包备份时可能出现，对应系统错误码 28/112。先清理项目所在磁盘，再重试。
- 保存失败时原文不变，编辑框内容保留。
- 快照写入中途失败，未完成的快照目录会被清理；如果连清理都因空间不足失败，下次打开项目时会统一清扫。
- 备份失败时不会动已有备份，按保留份数清理最旧备份的逻辑也只在成功打包后执行。
该项目位于只读介质（…），无法写入，已拒绝进入编辑
完整提示是「该项目位于只读介质（卷名），无法写入，已拒绝进入编辑：请关闭写保护，或把项目复制到可写磁盘后再打开。」写保护的 U 盘会显示「（…，写保护）」。应用会拒绝进入可编辑状态，避免你以为内容存上了、实际没有落盘。
项目已在另一个窗口打开，当前窗口为只读模式；关闭另一个窗口后重新打开即可编辑
同一个项目被另一个应用窗口持有写锁时会以只读方式打开，提示原文就是上面这一整句。关闭另一个窗口后重新打开本项目即可编辑。两个窗口同时写同一批文件会互相覆盖，所以这里不做「都能写」的妥协。
项目库缺失（.novel/novel.db 不存在）
完整提示是「项目库缺失（.novel/novel.db 不存在），manuscript 下仍有 N 个正文文件（约 N 字）。请选择：从最近备份恢复，或扫描正文重建索引。」正文 .md 文件本身不受影响。
- 从所选备份恢复：先核对备份里的正文与当前正文的差异，再决定「从所选备份恢复（正文已核对一致）」或「仅恢复结构索引（正文不动）」。
- 扫描正文重建索引：只读取
manuscript/下的 .md 重建卷、章、场景与字数，不改动任何正文文件；进入项目后会常驻标注「索引来自重建（时间）：卷/章/场景标题取自目录名与文件名，字数为文件实测。」 - 没有可用备份时（
.novel/backups与.novel/db-backups均为空），弹窗会直接说明只能扫描正文重建。
新建项目时的校验提示
- 「书名不能为空」「书名过长，上限 64 字」「书名不能包含字符 X」：按提示改书名。
- 「目录……已经是一个项目」：所选父目录下已有同名项目，换一个父目录或书名。
- 「目录……非空，无法作为新项目根」：新建项目要求目标目录为空或不存在同名项目目录。
任务「续写」尚未配置可用的默认模型
完整提示是「任务「续写」尚未配置可用的默认模型，且全局默认模型也不可用。请到 设置 → 模型与供应商 添加供应商、填入模型并选择默认模型。」按提示配好供应商、模型 ID 与默认模型后再生成。详见 AI 配置与故障排查。
AI 请求失败：401 / 403 / 404 / 超时 / 429 / 返回内容无法解析
- 401 / 403：密钥无效、过期或没有该模型的权限，重新填密钥并确认账号可用。
- 404：Base URL 或模型 ID 不对；兼容接口的地址通常以
/v1结尾，模型 ID 要与供应商文档一致。 - 超时：网络不通、代理阻断或供应商响应过慢，换网络重试。
- 429：触发了供应商的速率或额度限制，稍后再试或换模型。
- 无法解析：返回格式与所选类型不匹配，核对供应商类型（OpenAI 兼容 / Anthropic 兼容 / 其他）。
以上失败都只影响本次生成：已生成的候选保留，正文不会被写入半截内容。
快照校验失败，拒绝恢复
恢复前会校验快照清单与文件内容，文件缺失或 hash 不符时拒绝恢复，避免用不完整的快照覆盖当前正文。可以先用「校验全部」定位是哪一版快照不完整，再选择其他版本或从备份恢复。
更新服务不可达 / 更新清单不可用 / 更新包验签失败
- 更新服务不可达：检查网络、代理与 DNS；不影响当前版本继续使用，也可从站内下载新版本覆盖安装。
- 更新清单不可用：清单地址返回异常，稍后点「检查更新」再试。
- 更新包验签失败，已拒绝安装：下载到的包与清单签名不匹配，应用不会覆盖当前程序；删除下载缓存后重试，或从站内手动下载。