错误处理规范

版本：基线 1.0（2026-06-12）。依据：PRD §1.4 产品原则 3/4、§3.5 状态机、§5 非功能需求（健壮性）；story-repo-spec 0.6 不变量 4、§10。

1. 总原则

1.1 永不带堆栈崩溃：任何面向作者的执行路径都禁止抛出未捕获异常。所有可预见的失败必须落入"修复确认"或人话提示兜底。

1.2 宁停勿崩：无法安全继续时必须停下并说明状态，禁止带着不一致状态继续执行。

1.3 可靠性来自自愈，不来自门禁：能自动修复的先修复再报告；hook 语义必须是 ask，禁止 deny（v6 #113 教训）。

1.4 系统适应作者，不报错拒绝：作者手改源文件是合法操作。检测到未入账手改必须提议补登，禁止报错、禁止拒绝启动。

级别	示例	必须采取的处理
可自愈	`books.jsonl` 缺失/损坏；全角标点等结构性 YAML 错误	自动修复（扫描重建 / 预修复），只报不问
需作者确认	源文件解析失败且涉及内容语义	修复确认：定位到行、提议保留作者意图的修复、作者确认后执行
需作者决策	git 异常（半提交/冲突/锁文件/网盘冲突副本）	启动时 git 健康检查捕获，每种配自动修复或人话指引
环境性	Node 版本不足、不在工作目录启动	人话提示该做什么（升级 Node / 回工作目录），禁止英文报错

3.1 定稿必须原子：一次 git commit 要么完成，要么工作区原样保留，禁止中间态。所有多文件写入操作必须遵循同一模式——先全部准备好，再一次提交。

3.2 中断恢复：状态机启动时必须能识别"工作区有未完成流程"并从中断的阶段继续，禁止要求作者重来。

3.3 多文件写入的原子边界（实现在 src/storage/atomic.js 的 writeAtomicBatch）：

定稿/建书/卷复盘/修复落盘等多文件写入：全部先写 .tmp 再 rename，任一失败删全部 .tmp、原文件不动。"要么全成要么原样"。
审稿报告（事实审查/编辑审/审稿单 + 原始 raw）：同上原子批。
缓存重建多表写入：走数据库事务（BEGIN/COMMIT/ROLLBACK，见数据规范 §5），不走文件 rename。
豁免：工作区内纯临时单文件草稿（如 细纲.md）无原子要求。

3.4 定稿回滚范围必须收窄到本次写入文件集合（written），逐文件 restore（已跟踪）+ clean（未跟踪新文件），禁止对整棵 定稿/+大纲/ 子树 restore/clean，以免误伤同子树其他章的未登记手改。

4.1 必须全中文、自然流畅；禁止出现堆栈、错误码、英文术语，也不强求口语化。

4.2 必须说清三件事：发生了什么、影响是什么、作者现在该做什么（或系统已替作者做了什么）。

4.3 提醒与错误必须区分："悬了太久"等账面提醒不是错误，禁止用错误语气呈现。

5.1 CLI 退出码：0 = 命令成功；1 = 命令失败（已落入人话提示，非堆栈崩溃）。bin/webnovel-writer.js 统一用 process.exitCode，禁止 process.exit(n) 硬退（except 版本门槛/--version 早退）。

5.2 所有面向作者的执行路径返回 { ok: boolean, error: string } 结构化结果，禁止抛未捕获异常（总原则 §1.1）。{ok:false} 携带中文 error，调用方据 ok 决定退出码。

5.3 git.clean / git.restore 等回滚操作必须内部 try/catch 吞错（尽力而为，不破坏 {ok,error} 契约），残余不一致由 git 健康检查兜底。