docs: align author-friendly experience plan

docs/architecture/author-friendly-reporting-plan-2026-06-07.md

@@ -0,0 +1,1320 @@
+# 作者友好报告与异常可见性改造 Plan
+
+> 日期：2026-06-07
+> 状态：草案 v2 · 已对齐 `docs/superpowers/specs/2026-06-07-author-friendly-experience-design.md`
+> 范围：承接 spec 的「作者外壳 / 作者界面层」七组件，统一 `init / plan / write / review` 的最终汇报、subagent 返回协议、错误目录、审查作者视图、下一步建议、异常分类、耗时呈现与作者友好术语；先取消 token 统计
+> 核心原则：问题不静默、自动处理要说明、技术细节默认隐藏、最终报告面向作者而不是工程日志；工程内核不动
+> 实施方式：先用 Skill / Agent 契约固定行为，再用 runtime helper 收敛格式，避免只靠提示词导致输出漂移
+
+---
+
+## 0. 与产品 Spec 的对齐关系
+
+本计划是 `docs/superpowers/specs/2026-06-07-author-friendly-experience-design.md` 的工程落地计划，不再另起一套产品口径。
+
+分工如下：
+
+| 文档 | 负责什么 | 不负责什么 |
+|---|---|---|
+| 产品 spec | 定义「工程内核 + 作者外壳」分层、七个组件、错误恢复红线、分期价值 | 不展开具体文件、测试与施工顺序 |
+| 本 plan | 把七组件落到 Skill / Agent / runtime helper / 测试 / 文档 | 不重新定义产品目标，不放宽 spec 红线 |
+
+对齐后的共同边界：
+
+- Story System、`write-gate`、`chapter-commit`、projection、RAG 等工程内核不改语义、不降校验强度。
+- 作者默认看到里程碑、结论、影响和下一步；工程命令、JSON、schema、traceback 默认写入日志或技术详情。
+- 自动处理只限幂等、可重试、不碰作者内容的过程性问题；最终报告必须说明处理过什么，不能静默。
+- 不新增 UI、按钮、进度条、命令别名或自动修复大循环。
+
+七组件在本计划中的落点：
+
+| spec 组件 | 本 plan 落点 |
+|---|---|
+| 术语对照表 | §5 单一事实源；Phase 1 先落结构化词表 |
+| 进度播报规范 | §8 过程易用性；Phase 5A |
+| 错误→行动映射表 | §15 异常分类 + Phase 4 runtime helper；新增 `error_catalog.py` 与 `author_error_catalog.json` |
+| 审查作者视图 | §16 helper / `review_pipeline.py` 渲染；Phase 4 优先接 `review` |
+| 导航尾巴 | §4 三段式报告第三段；§20 推荐施工顺序中作为早期交付 |
+| 命令任务化 | §4 / §19 / §23 的下一步建议；只改提示语言，不新增别名 |
+| 可自动处理项 + 默认不展示工程细节 | §3.2-3.4、§11、§15、§21；第三期前只做说明和日志，不扩白名单 |
+
+## 1. 目标
+
+本计划把 `webnovel-writer` 的交付体验从“流程执行完以后由主 agent 自行总结”改成“每次都有稳定、可读、可信的作者回执”。
+
+核心交付：
+
+1. 统一最终报告规范：所有主 Skill 结尾都输出固定三段式报告，并以一句总状态开头。
+2. 全局作者友好约束：中文、少术语、不静默、自动处理要说明、技术细节按需展开。
+3. 阶段化报告模板：分别补强 `/webnovel-init`、`/webnovel-plan`、`/webnovel-write`、`/webnovel-review` 的最终汇报要求。
+4. Subagent 返回协议：主流程能汇总 `context-agent`、`reviewer`、`data-agent`、`deconstruction-agent` 的状态、问题、自动处理与耗时。
+5. 异常分类：所有问题归入“已自动处理 / 建议确认 / 必须处理”，重点暴露 subagent 失败、跳过、重试和输出不完整。
+6. 耗时可见：记录已耗时和关键步骤耗时；长时间无进展时说明可能原因和是否影响结果，不承诺固定完成时间。
+7. 术语翻译：工程词默认翻译成作者能理解的写作语义。
+8. Runtime helper：新增统一报告 helper，优先消费已有 `project-status`、`doctor`、`write-gate`、`review-pipeline`、`chapter-commit`、`projection_log` 等结构化输出。
+9. 过程易用性：在长流程执行中提供清晰进度、少打扰确认、可恢复状态和作者可理解的卡点说明。
+10. 断点续跑：重复执行同一主命令时，能识别已完成步骤，从最近可信断点继续，而不是要求作者记补跑命令。
+11. 交互式裁决：必须用户处理的问题优先给有限选项，减少“自己去改文件”的认知负担。
+12. 技术溯源：作者报告保持清爽，同时把工程细节写入本地日志，便于故障反馈和开发排查。
+13. 错误目录：把 runtime 错误码映射为作者能理解的原因、影响和下一步动作。
+14. 审查作者视图：在审查报告顶部提供一句结论和最多 3 条可执行修改建议。
+15. 下一步建议：每条主命令结束后给出任务化说明和可复制命令，不新增命令别名。
+
+---
+
+## 2. 背景
+
+当前项目底层流程已经比较完整：
+
+- `project-status` 能判断项目阶段和下一步。
+- `doctor` 能给阶段感知体检。
+- `write-gate` 已覆盖写前、提交前、提交后三个边界。
+- `review-pipeline` 能规范化审查结果、生成报告并落库。
+- `chapter-commit` 能生成写后事实并驱动 state / index / summary / memory / vector 投影。
+- `projection_log` 能定位投影状态。
+
+问题不在于缺少检查，而在于这些检查结果没有稳定地翻译给作者：
+
+1. 最终回复格式不稳定，作者每次要重新判断“到底完成了没有”。
+2. 技术细节、JSON、命令输出容易直接暴露，阅读负担偏重。
+3. 某些降级、跳过、重试或自动处理只存在于流程内部，最终汇报不一定说明。
+4. subagent 成败、输出完整性和耗时没有统一汇总。
+5. `init / plan / write / review` 四条主流程的成功标准清楚，但“如何交付给作者”的要求不够清楚。
+6. 长流程执行过程中，作者不一定知道当前做到哪一步、为什么在等、是否需要介入、能不能中断后继续。
+7. 偶发失败后，作者往往需要理解内部步骤和补跑命令，恢复成本偏高。
+8. 必须用户裁决的问题容易变成“报错退出 + 长解释”，没有被收敛成清晰选择。
+
+本轮改造不重写写作主链，不新增自动修复大循环；重点补“作者可理解的交付层”。
+
+---
+
+## 3. 设计原则
+
+### 3.0 Claude Code 能力边界
+
+所有改造必须基于 Claude Code 已有能力和本插件可实现的 runtime 能力，不编造宿主不存在的 UI、后台任务或交互机制。
+
+已可依赖的能力：
+
+- Skill 通过 `SKILL.md` 约束流程和最终输出。
+- 主流程可使用 Claude Code 的 `Agent` 工具调用已注册 subagent。
+- 主流程可使用 `AskUserQuestion` 做关键裁决，前提是该 Skill frontmatter 已允许并且宿主环境支持。
+- 主流程可通过 `Read` / `Write` / `Edit` / `Bash` 等工具读取、写入和运行本插件脚本。
+- 插件 runtime 可通过 Python CLI 读写 `.webnovel/`、`.story-system/`、日志和中间产物。
+
+不能假设的能力：
+
+- 不能假设 Claude Code 有实时进度条、图形化按钮、后台任务队列或终端内原生选择菜单。
+- 不能假设 subagent 会自动返回结构化元数据；需要通过 prompt 协议和主流程记录来实现。
+- 不能假设重复运行 Skill 会天然断点续跑；断点续跑必须由本插件 runtime 读取产物、run ledger 和 gate 结果实现。
+- 不能假设 AskUserQuestion 可以承担复杂表单；裁决选项应保持 2-3 个短选项。
+- 不能假设日志、耗时、恢复点会自动存在；这些必须由脚本或主流程显式记录。
+
+因此，本计划中的“过程提示”是主流程在关键节点输出短提示；“交互式裁决”是基于 `AskUserQuestion` 或普通对话提问的有限选择；“断点续跑”是插件 runtime 的文件与状态检查能力，不是 Claude Code 内置工作流引擎。
+
+### 3.1 作者友好，不工程炫技
+
+默认用作者能理解的中文表达，不直接输出 `subagent`、`artifact`、`projection`、`schema`、`runtime contract` 等工程词。
+
+必要时可以在问题详情中保留文件路径和命令，但默认先讲影响：
+
+```text
+“保存本章故事事实”失败，会影响后续查询本章发生过什么。
+```
+
+而不是：
+
+```text
+data-agent artifact schema_error: extraction_result missing accepted_events
+```
+
+### 3.2 问题不静默
+
+以下情况必须在最终报告中出现：
+
+- subagent 调用失败。
+- subagent 被用户模式选择跳过。
+- subagent 输出不完整。
+- reviewer 跳过或 `--minimal` 写 no-review artifact。
+- data-agent 三份结果缺失或 schema 不合格。
+- `write-gate` 任一阶段 failed。
+- `chapter-commit` rejected。
+- projection failed / pending / missing。
+- RAG 降级。
+- 备份失败。
+- 耗时异常。
+
+### 3.3 自动处理必须说明
+
+系统自动做过的事要简短说明，包括：
+
+- 自动补跑 projection。
+- 自动降级到关键词检索。
+- 自动应用白名单内的非阻断定点处理，例如格式整理或明确的错别字修正。
+- 自动覆盖旧的 no-review artifact。
+- 自动初始化 Git 或退回本地备份。
+
+说明不需要讲全部过程，只说明“处理了什么、是否影响结果”。
+
+### 3.4 技术细节默认隐藏
+
+最终报告优先给结论和影响。只有当用户需要处理时，再给路径、命令或错误类型。
+
+### 3.5 Runtime 优先，提示词兜底
+
+能由 runtime 确认的状态，不靠主 agent 口头判断。
+
+最终报告 helper 优先消费结构化数据：
+
+- `project-status --format json`
+- `doctor --format json`
+- `write-gate --format json`
+- `review-pipeline` payload
+- `chapter-commit` payload
+- `projection_log`
+- subagent run summary
+
+Skill 文档只规定“必须汇报什么”，不让每个 Skill 自己发明报告格式。
+
+### 3.6 过程易用性也是交付的一部分
+
+最终报告只能降低“结束后的不确定感”，不能解决执行过程中的焦虑。
+
+长流程必须让作者持续知道四件事：
+
+1. 当前在做哪一步。
+2. 这一步大概会产生什么。
+3. 是否需要作者做决定。
+4. 如果卡住，卡点是什么、会不会影响已有成果。
+
+过程提示应该短、少术语、少打扰。默认由系统继续推进，只有真正影响创作方向、事实一致性或文件安全时才打断用户。
+
+### 3.7 恢复应优先自动化
+
+“告诉作者怎么恢复”是底线，“作者重新执行同一个命令即可自动续跑”才是目标。
+
+主流程应逐步做到幂等：
+
+- 已完成且可信的产物不重复生成。
+- 失败后保留已有正文、审查报告和中间结果。
+- 再次执行同一命令时，先检查断点状态，再从最近失败步骤继续。
+- 只有产物过期、参数变更或用户明确要求重写时，才重新执行前置步骤。
+
+### 3.8 技术溯源不打扰作者
+
+作者默认看不到 JSON、schema、traceback 和完整命令日志。
+
+但系统需要保留本地溯源材料：
+
+- 用于开发者定位问题。
+- 用于用户反馈不可恢复故障。
+- 用于 runtime helper 判断断点和步骤状态。
+
+普通报告只给一条低干扰提示：
+
+```text
+如需反馈故障，可附上 .webnovel/logs/run_last.log。
+```
+
+---
+
+## 4. 统一最终报告规范
+
+所有主 Skill 最终输出统一为：
+
+```text
+总状态：已完成 / 部分完成 / 需要你处理 / 未完成。
+
+一、产生的文件与完成情况
+- ...
+
+二、过程中遇到的问题与异常耗时
+- 已自动处理：...
+- 建议确认：...
+- 必须处理：...
+- 耗时异常：...
+
+三、下一步建议
+- ...
+```
+
+状态含义：
+
+| 状态 | 含义 |
+|---|---|
+| 已完成 | 当前阶段产物齐全，关键检查通过，可以进入下一步 |
+| 部分完成 | 有主要产物，但存在跳过、降级、未完成项或非阻断问题 |
+| 需要你处理 | 当前结果可保存，但必须由用户确认、裁决或补充信息 |
+| 未完成 | 关键产物缺失或阻断失败，不能继续下一阶段 |
+
+---
+
+## 5. 术语翻译表（单一事实源）
+
+术语翻译不是每个 Skill 各写一份，而是作为 Author Layer 的单一事实源维护。
+
+首版采用结构化数据，便于 runtime helper 和 prompt integrity 测试复用：
+
+```text
+webnovel-writer/references/author_glossary.json
+```
+
+可选补一份面向文档阅读的 Markdown 摘要，但实现与测试只以 JSON 为准。
+
+维护规则：
+
+- Skill / Agent 文档可以引用术语，但不得自造不同译法。
+- `user_report.py`、`error_catalog.py`、审查作者视图都从同一术语表取作者友好表达。
+- 未登记的新工程词默认保留原词，并在报告中优先解释影响；后续再补词表，不临场硬翻。
+- 词表测试只检查关键术语是否存在、是否有作者解释，不锁死完整文案。
+
+| 工程词 | 作者友好表达 |
+|---|---|
+| subagent | 写作助手 / 审查助手 / 资料整理助手 / 拆书助手 |
+| context-agent | 写前准备 |
+| reviewer | 写作检查 |
+| data-agent | 保存本章故事事实 |
+| deconstruction-agent | 参考作品拆解 |
+| artifact | 中间结果文件 |
+| review_results | 写作检查结果 |
+| fulfillment_result | 本章目标完成情况 |
+| disambiguation_result | 待确认的人名/设定歧义 |
+| extraction_result | 本章新发生的故事事实 |
+| chapter-commit | 提交本章事实 |
+| projection | 更新故事资料 |
+| state / index / summary / memory / vector | 状态 / 索引 / 摘要 / 长期记忆 / 检索库 |
+| blocking issue | 会影响继续写作的问题 |
+| fallback | 临时降级读取 |
+| runtime contract | 本章写作要求 |
+| schema error | 中间结果格式不完整 |
+| pending | 等待确认 |
+| rejected | 本章事实未通过提交 |
+| accepted | 本章事实已通过提交 |
+
+---
+
+## 6. 修改范围
+
+### 6.1 Skill / Agent 文档
+
+- `webnovel-writer/skills/webnovel-init/SKILL.md`
+- `webnovel-writer/skills/webnovel-plan/SKILL.md`
+- `webnovel-writer/skills/webnovel-write/SKILL.md`
+- `webnovel-writer/skills/webnovel-review/SKILL.md`
+- `webnovel-writer/agents/context-agent.md`
+- `webnovel-writer/agents/reviewer.md`
+- `webnovel-writer/agents/data-agent.md`
+- `webnovel-writer/agents/deconstruction-agent.md`
+
+### 6.2 Runtime helper
+
+新增：
+
+- `webnovel-writer/references/author_glossary.json`
+- `webnovel-writer/references/author_error_catalog.json`
+- `webnovel-writer/scripts/data_modules/author_glossary.py`
+- `webnovel-writer/scripts/data_modules/error_catalog.py`
+- `webnovel-writer/scripts/data_modules/review_author_view.py`
+- `webnovel-writer/scripts/data_modules/user_report.py`
+- `webnovel-writer/scripts/data_modules/run_ledger.py`
+- `webnovel-writer/scripts/data_modules/run_logger.py`
+- `webnovel-writer/scripts/data_modules/tests/test_author_glossary.py`
+- `webnovel-writer/scripts/data_modules/tests/test_error_catalog.py`
+- `webnovel-writer/scripts/data_modules/tests/test_review_author_view.py`
+- `webnovel-writer/scripts/data_modules/tests/test_user_report.py`
+- `webnovel-writer/scripts/data_modules/tests/test_run_ledger.py`
+- `webnovel-writer/scripts/data_modules/tests/test_run_logger.py`
+
+修改：
+
+- `webnovel-writer/scripts/data_modules/webnovel.py`
+- `webnovel-writer/scripts/review_pipeline.py`
+- `webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py`
+- `webnovel-writer/skills/webnovel-write/SKILL.md`
+
+### 6.3 Prompt / behavior 测试
+
+修改或新增：
+
+- `webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py`
+- `webnovel-writer/evals/fixtures/behavior/fast.json`
+
+---
+
+## 7. 能力映射与实现边界
+
+| 易用性目标 | 可用 Claude Code 能力 | 插件需新增 / 修改 | 不依赖 |
+|---|---|---|---|
+| 过程提示 | 主流程自然语言输出 | Skill 增加关键节点提示要求 | 实时进度条 |
+| 开始前预期管理 | 主流程开头输出短说明 | Skill 增加流程概览模板 | 后台任务估时系统 |
+| 最终报告 | 主流程最终回复 | `user_report.py` 渲染 text/json | Claude Code 自动格式化 |
+| subagent 状态汇总 | `Agent` 调用 + 主流程记录 | `SubagentRun` 协议和主流程汇总 | subagent 自动 telemetry |
+| 异常分类 | 主流程读取 runtime JSON | `user_report.py` 分类逻辑 | 宿主自动错误分类 |
+| 耗时记录 | Bash / Python 计时或主流程记录 | run ledger / helper 记录步骤时间 | Claude Code 内置性能面板 |
+| 断点续跑 | Bash 运行 Python CLI，读写本地文件 | `run_ledger.py`、产物可信度检查、gate 复用 | Claude Code 内置 resume 引擎 |
+| 交互式裁决 | `AskUserQuestion` 或普通对话提问 | Skill 定义有限选项和处理分支 | 图形化按钮 / 复杂表单 |
+| 技术溯源 | Python 写本地日志 | `run_logger.py`、敏感信息过滤 | 宿主自动日志导出 |
+| 下一步命令 | 最终报告文本 | `user_report.py` 填入建议命令 | 一键按钮 |
+
+实现原则：
+
+1. 先用现有 Skill / Agent / Bash / Python CLI 能力落地。
+2. 任何需要 runtime 判断的能力，都必须有本地文件、JSON 或命令输出作为依据。
+3. 任何看起来像 UI 的体验，都只能表现为文本提示、有限提问或最终报告，除非未来另做 Dashboard 改造。
+4. 不把 Claude Code 未承诺的行为写成验收标准。
+
+---
+
+## 8. 过程易用性设计
+
+### 8.1 目标
+
+让作者在流程运行中不需要理解内部工程链路，也能知道：
+
+- 现在系统在做什么。
+- 这一步为什么必要。
+- 是否仍在推进。
+- 什么时候需要自己拍板。
+- 中途失败时已经完成了哪些部分，能从哪里继续。
+
+过程体验不是把每条命令都打印出来，而是把长流程拆成作者能理解的“当前动作”。
+
+### 8.2 开始前预期管理
+
+长流程开始前，先给作者一个短概览：
+
+```text
+开始写第 13 章。本次会经过：整理依据 -> 起草正文 -> 写作检查 -> 润色 -> 保存本章故事事实 -> 更新资料并备份。
+不同 API、模型和网络速度差异很大，本流程不承诺固定耗时；中途只有遇到创作裁决或事实冲突时才会问你。
+```
+
+预期管理必须包含：
+
+- 本次目标。
+- 主要步骤。
+- 不承诺固定耗时的说明。
+- 是否需要用户守在旁边。
+
+### 8.3 统一过程提示格式
+
+过程提示使用短句，不超过两行：
+
+```text
+正在整理本章写作依据：会读取章纲、最近剧情和未回收伏笔。
+```
+
+```text
+正在保存本章故事事实：这一步会更新摘要、角色状态和后续检索资料。
+```
+
+避免：
+
+```text
+Running write-gate --stage precommit and validating artifacts...
+```
+
+### 8.4 阶段名翻译
+
+| 内部步骤 | 过程提示名称 |
+|---|---|
+| preflight | 检查项目环境 |
+| placeholder-scan | 检查未补齐占位 |
+| story-system | 刷新本章写作要求 |
+| write-gate prewrite | 写前检查 |
+| context-agent | 整理写作依据 |
+| draft | 起草正文 |
+| reviewer | 写作检查 |
+| review-pipeline | 生成检查报告 |
+| polish | 润色与排版 |
+| data-agent | 保存本章故事事实 |
+| write-gate precommit | 提交前检查 |
+| chapter-commit | 提交本章事实 |
+| write-gate postcommit | 提交后确认 |
+| projections retry | 补跑故事资料更新 |
+| backup | 备份本章成果 |
+
+### 8.5 少打扰确认策略
+
+默认不打断作者，除非出现以下情况：
+
+| 必须询问 | 原因 |
+|---|---|
+| init 最终方案确认 | 会写入新书核心设定 |
+| 参考作品拆解质量不足但用户想采用 | 可能污染新书创意 |
+| plan 发现总纲 / 设定冲突 | 需要创作裁决 |
+| write 发现无法定点修复的 blocking issue | 会影响本章继续提交 |
+| data-agent 出现低置信度歧义且会影响事实入库 | 后续状态可能写错 |
+| commit rejected 后用户仍想继续 | 需要明确风险接受 |
+| 文件写入范围异常 | 可能污染其他章节或项目 |
+
+不应询问：
+
+- 普通非阻断审查问题，系统可在润色中处理。
+- RAG 降级但不影响当前写作。
+- projection retry 可以自动补跑。
+- 备份从 Git 降级到本地备份且成功。
+- 单纯耗时偏长但结果正常。
+
+### 8.6 长流程进度节点
+
+每个主 Skill 建议最多展示 3-6 个过程节点，不展示每个内部命令。
+
+`/webnovel-init`：
+
+1. 收集故事核心。
+2. 整理创意约束。
+3. 等待最终确认。
+4. 创建项目文件。
+5. 生成写作主链基础资料。
+6. 验证项目能否进入规划。
+
+`/webnovel-plan`：
+
+1. 读取总纲和已有剧情状态。
+2. 补齐设定基线。
+3. 规划卷节奏和时间线。
+4. 拆分章纲。
+5. 写回新增设定。
+6. 刷新写作要求。
+
+`/webnovel-write`：
+
+1. 检查写前条件。
+2. 整理写作依据。
+3. 起草正文。
+4. 写作检查与润色。
+5. 保存本章故事事实。
+6. 提交、更新资料并备份。
+
+`/webnovel-review`：
+
+1. 确认待审章节。
+2. 整理审查依据。
+3. 执行写作检查。
+4. 生成审查报告并落库。
+5. 如有阻断问题，等待用户裁决。
+
+### 8.7 卡住时的过程反馈
+
+流程卡住时不要只报错误，要说明三件事：
+
+1. 卡在哪一步。
+2. 已经完成了什么。
+3. 下一步怎么恢复。
+
+示例：
+
+```text
+卡在“保存本章故事事实”：正文和审查报告已经完成，但本章事实提取结果缺少摘要字段。
+我会重跑资料整理助手；如果仍失败，会保留正文和审查报告，不会提交不完整事实。
+```
+
+### 8.8 可恢复状态提示
+
+流程中断或失败后，最终报告和过程反馈都应说明恢复点：
+
+| 卡点 | 恢复建议 |
+|---|---|
+| context-agent 失败 | 补齐章纲 / 合同后重跑写章 |
+| 起草后 review 失败 | 保留正文，重跑写作检查 |
+| review 有 blocking | 定点修复或用户裁决后继续润色 |
+| data-agent artifact 缺失 | 重跑保存本章故事事实 |
+| precommit failed | 修复中间结果后重跑提交前检查 |
+| commit rejected | 修复 missed_nodes / pending / blocking 后重新提交 |
+| projection failed | 补跑 `projections retry` |
+| backup failed | 手动或重跑 backup，不影响已提交事实 |
+
+### 8.9 作者可控的详细程度
+
+后续可增加可选参数：
+
+```text
+--quiet      只显示关键确认和最终报告
+--verbose    显示过程节点、异常原因和关键命令
+```
+
+首版不强制实现参数，但 Skill 文档应遵循默认“简洁过程提示 + 详细最终报告”的体验。
+
+---
+
+## 9. 断点续跑设计
+
+### 9.1 目标
+
+让作者遇到偶发失败后，不需要理解内部补跑命令。重复执行同一主命令时，系统应自动识别已完成步骤，从最近可信断点继续。
+
+示例：
+
+```text
+检测到上一次第 13 章已完成“起草正文”和“写作检查”，但卡在“保存本章故事事实”。
+本次将从“保存本章故事事实”继续，不会重写正文。
+```
+
+### 9.2 断点状态来源
+
+优先复用现有产物和 gate：
+
+| 步骤 | 可信完成判据 |
+|---|---|
+| 写前检查 | `write-gate prewrite ok=true` 或当前重新运行通过 |
+| 写作依据 | `context-agent` 返回任务书且未过期 |
+| 正文起草 | 目标章节正文文件存在且非空 |
+| 写作检查 | `review_results.json` 标记目标章节，且 `review-pipeline` 已生成报告 |
+| 润色 | 正文修改时间晚于审查报告，且无 anti-ai 阻断记录 |
+| 保存事实 | 三份 data artifacts 存在且 `write-gate precommit` 通过 |
+| 提交事实 | commit 文件存在且 status accepted |
+| 更新资料 | `write-gate postcommit` 通过，projection 五项 done/skipped |
+| 备份 | backup 返回成功或存在本章备份记录 |
+
+### 9.3 Run Ledger
+
+首版可以不新增复杂状态机，但建议新增轻量运行账本：
+
+```text
+.webnovel/runs/write_ch0013.json
+.webnovel/logs/run_last.log
+```
+
+`write_ch0013.json` 保存机器可读进度：
+
+```json
+{
+  "schema_version": "webnovel-run-ledger/v1",
+  "command": "webnovel-write",
+  "chapter": 13,
+  "started_at": "",
+  "updated_at": "",
+  "steps": [
+    {"id": "draft", "label": "起草正文", "status": "done", "outputs": ["正文/第0013章.md"]},
+    {"id": "data", "label": "保存本章故事事实", "status": "failed", "problem": "API timeout"}
+  ]
+}
+```
+
+`run_last.log` 保存工程细节：
+
+- 命令。
+- JSON 输出摘要。
+- traceback。
+- subagent 原始异常。
+- 耗时。
+
+作者报告不直接展开 `run_last.log`，只在不可恢复故障时提示路径。
+
+### 9.4 幂等策略
+
+重复执行主命令时：
+
+1. 先解析 `PROJECT_ROOT`、章节号和模式参数。
+2. 读取 run ledger 和现有产物。
+3. 校验已完成步骤是否仍可信。
+4. 从第一个不可信或失败步骤继续。
+5. 若用户参数改变、正文被手动修改、章纲更新时间晚于正文，则提示是否重跑前置步骤。
+
+### 9.5 必须询问的续跑分支
+
+| 场景 | 处理 |
+|---|---|
+| 正文存在但本次用户要求重写 | 询问覆盖 / 另存 / 取消 |
+| 章纲更新晚于正文 | 询问沿用旧正文还是重新起草 |
+| 审查报告来自旧正文 | 自动重跑审查 |
+| commit 已 accepted，但用户再次执行写同章 | 询问是否重写本章或只查看状态 |
+| backup 失败但 commit 已完成 | 自动重跑 backup，不重写正文 |
+
+### 9.6 阶段落地
+
+第一阶段只做 `/webnovel-write` 的断点续跑，因为它步骤最长、失败点最多。
+
+后续再扩展：
+
+- `/webnovel-plan`：批次级续跑，失败批次重做，不覆盖整卷。
+- `/webnovel-init`：用户确认前问答态不强行续跑；生成阶段可按文件补齐。
+- `/webnovel-review`：按章节范围跳过已审且正文未变更的章节。
+
+---
+
+## 10. 交互式裁决设计
+
+### 10.1 目标
+
+遇到必须用户处理的问题时，优先给有限选项，而不是让作者自己理解错误并手改文件。
+
+### 10.2 裁决呈现格式
+
+```text
+需要你裁决：本章“沈照”的法宝与大纲冲突。
+
+大纲记录：青锋剑
+正文写成：紫金葫芦
+
+请选择处理方式：
+1. 坚持大纲：自动把正文相关段落改回“青锋剑”
+2. 采用新设定：保留“紫金葫芦”，并把设定变更写入故事资料
+3. 我手动处理：暂停流程，修改后继续
+```
+
+### 10.3 标准裁决类型
+
+| 类型 | 选项 |
+|---|---|
+| 设定冲突 | 坚持既有设定 / 采用新设定 / 手动处理 |
+| 时间线冲突 | 按时间线修正文 / 调整时间线 / 手动处理 |
+| 角色 OOC | 按角色卡修正文 / 更新角色变化理由 / 手动处理 |
+| 低置信度消歧 | 采用 A / 采用 B / 暂不入库 |
+| commit rejected | 修复后重提 / 接受风险但不提交 / 手动处理 |
+| 文件写入范围异常 | 取消写入 / 只保留安全文件 / 查看详情 |
+
+### 10.4 与 AskUserQuestion 的关系
+
+在 Claude Code 环境中，优先使用 `AskUserQuestion` 做关键裁决。
+
+选项必须短，并说明影响：
+
+- 推荐项放第一。
+- 每个选项说明会改什么。
+- 不出现“其他”作为固定选项；用户可自由补充。
+
+### 10.5 不做自动裁决的红线
+
+以下情况不能由系统擅自决定：
+
+- 改变主角长期能力路线。
+- 改变核心反派身份。
+- 改变卷末高潮结果。
+- 将参考作品内容写入新书 canon。
+- 覆盖用户手动编辑的正文。
+- 把 rejected commit 当作 accepted 继续推进。
+
+---
+
+## 11. 技术溯源与日志
+
+### 11.1 目标
+
+作者报告保持清爽，工程排查材料保留完整。
+
+### 11.2 日志位置
+
+建议：
+
+```text
+.webnovel/logs/run_last.log
+.webnovel/logs/runs/YYYYMMDD-HHMMSS-{command}.log
+```
+
+### 11.3 日志内容
+
+日志包含：
+
+- 命令与参数。
+- 解析后的项目根。
+- 每个过程节点开始 / 结束时间。
+- subagent run summary。
+- runtime JSON 输出摘要。
+- 异常 traceback。
+- 最终 `user-report --format json`。
+
+日志不应包含：
+
+- API key。
+- `.env` 原文。
+- 用户未确认写入的新书核心设定草稿，除非它已经作为本次运行输入出现。
+
+### 11.4 最终报告中的呈现
+
+只在以下情况展示日志路径：
+
+- 未完成。
+- 需要用户处理但问题不容易描述。
+- 用户使用 `--verbose`。
+
+示例：
+
+```text
+技术详情已保存：.webnovel/logs/run_last.log。反馈故障时可以附上它。
+```
+
+---
+
+## 12. Phase 0：基线审计
+
+### 12.1 目标
+
+先确认现有报告、gate 和 agent 输出边界，避免改造后不知道格式漂移来自哪里。
+
+### 12.2 工作项
+
+- [ ] 记录四个主 Skill 的当前最终输出要求。
+- [ ] 记录四个 agent 当前输出格式与写入责任。
+- [ ] 记录 `project-status`、`doctor`、`write-gate`、`review-pipeline`、`chapter-commit` 的 JSON 字段。
+- [ ] 记录现有错误码、repair 文案、gate failure 特征与 projection 状态，作为 `author_error_catalog.json` 初始素材。
+- [ ] 记录 `review-pipeline` 可用于作者视图的字段：总分、blocking 数、维度问题、建议项、报告路径。
+- [ ] 记录当前文档和 Skill 中已出现的工程词，和 §5 术语表做一次去重。
+- [ ] 确认现有测试中哪些是文案级断言，哪些能改为行为级断言。
+
+### 12.3 验收
+
+- 当前可复用的结构化数据源已列明。
+- 明确哪些问题只能由 prompt 记录，哪些可以由 runtime helper 读取。
+- `author_glossary.json` 与 `author_error_catalog.json` 的首批条目来源清楚，不靠实现时临场猜。
+
+---
+
+## 13. Phase 1：Skill 最终报告契约
+
+### 13.1 目标
+
+先用最小改动让四个主流程在最终回复中遵守统一格式。
+
+### 13.2 `/webnovel-init`
+
+必须汇报：
+
+- 项目目录。
+- `.webnovel/state.json`。
+- `设定集/世界观.md`、`设定集/力量体系.md`、`设定集/主角卡.md`、`设定集/反派设计.md`。
+- `大纲/总纲.md`。
+- `.webnovel/idea_bank.json`。
+- `.story-system/MASTER_SETTING.json`。
+- 是否使用参考作品拆解。
+- 用户确认前未写入 canon 的情况。
+- 缺失信息是否会影响后续 plan。
+
+工作项：
+
+- [ ] 在 `webnovel-init/SKILL.md` 增加“最终报告要求”段。
+- [ ] 将成功标准映射到“三段式报告”。
+- [ ] 明确参考作品拆解失败、输入不足或质量不过线时必须进入“建议确认 / 必须处理”。
+
+### 13.3 `/webnovel-plan`
+
+必须汇报：
+
+- `大纲/第{volume_id}卷-节拍表.md`。
+- `大纲/第{volume_id}卷-时间线.md`。
+- `大纲/第{volume_id}卷-详细大纲.md`。
+- 新增设定写回了哪些设定集文件。
+- `大纲/第{volume_id}卷-总纲写回.json`。
+- `master-outline-sync` 是否完成。
+- `update-state` 是否完成。
+- Story System 合同是否刷新。
+- 占位符、时间线、节点承接是否通过。
+
+工作项：
+
+- [ ] 在 `webnovel-plan/SKILL.md` 增加“最终报告要求”段。
+- [ ] 明确时间线回跳、BLOCKER、占位符残留必须报告。
+- [ ] 明确只重做失败批次时要说明自动处理内容。
+
+### 13.4 `/webnovel-write`
+
+必须汇报：
+
+- 正文文件路径。
+- 写作检查报告路径。
+- `.webnovel/tmp/review_results.json`。
+- `.webnovel/tmp/fulfillment_result.json`。
+- `.webnovel/tmp/disambiguation_result.json`。
+- `.webnovel/tmp/extraction_result.json`。
+- `.story-system/commits/chapter_{NNN}.commit.json`。
+- state / index / summary / memory / vector 更新状态。
+- 备份状态。
+- 是否可以继续写下一章。
+
+工作项：
+
+- [ ] 在 `webnovel-write/SKILL.md` 增加“最终报告要求”段。
+- [ ] 明确 `--fast` 和 `--minimal` 的跳过项必须说明。
+- [ ] 明确 `chapter-commit rejected` 时最终状态不得写“已完成”。
+- [ ] 明确 projection retry 发生时要说明已自动处理和结果。
+
+### 13.5 `/webnovel-review`
+
+必须汇报：
+
+- 审查报告文件。
+- `review_metrics.json`。
+- `review_metrics` 是否落库。
+- 阻断问题数量。
+- 用户裁决状态。
+- 如果无阻断，明确可以继续写作。
+
+工作项：
+
+- [ ] 在 `webnovel-review/SKILL.md` 增加“最终报告要求”段。
+- [ ] 明确 blocking 问题必须进入“必须处理”或“建议确认”。
+- [ ] 明确只保存报告、稍后处理时最终状态为“需要你处理”或“部分完成”。
+
+---
+
+## 14. Phase 2：Subagent 返回协议
+
+### 14.1 目标
+
+让主流程可以稳定汇总每个 subagent 的完成状态、问题、自动处理内容和耗时。
+
+### 14.2 统一协议
+
+主流程为每次 subagent 调用记录一份 `SubagentRun`：
+
+```json
+{
+  "name": "data-agent",
+  "user_label": "保存本章故事事实",
+  "status": "completed | partial | failed | skipped",
+  "problems": [],
+  "auto_handled": [],
+  "needs_user_action": false,
+  "duration_ms": 0,
+  "outputs": []
+}
+```
+
+字段说明：
+
+| 字段 | 含义 |
+|---|---|
+| `name` | agent 名称 |
+| `user_label` | 作者友好名称 |
+| `status` | 完成状态 |
+| `problems` | 遇到的问题 |
+| `auto_handled` | 自动处理内容 |
+| `needs_user_action` | 是否需要用户处理 |
+| `duration_ms` | 耗时 |
+| `outputs` | 产生或返回的关键产物 |
+
+### 14.3 工作项
+
+- [ ] `context-agent`：上下文不足、legacy fallback、伏笔数据缺失必须可被主流程记录。
+- [ ] `reviewer`：正文为空、读取状态失败、维度跳过必须写入 summary 或问题字段。
+- [ ] `data-agent`：三份 artifact 写入状态、长时间无进展、pending 消歧必须可被汇总。
+- [ ] `deconstruction-agent`：输入不足、质量不过线、降级 quick mode 必须可被汇总。
+- [ ] 主 Skill 调用 agent 后，必须记录 `SubagentRun` 供最终报告使用。
+
+### 14.4 验收
+
+- 写章流程最终报告能列出写前准备、写作检查、保存本章故事事实三个助手的状态。
+- 任一 agent 跳过、失败、输出不完整时，最终报告不会写成完全成功。
+
+---
+
+## 15. Phase 3：异常分类与耗时呈现
+
+### 15.1 异常分类
+
+所有问题归为三类：
+
+| 类型 | 定义 | 示例 |
+|---|---|---|
+| 已自动处理 | 系统已补跑、降级或完成白名单内定点处理，不需要用户处理 | projection retry 成功、RAG 降级但不影响结果 |
+| 建议确认 | 结果可用，但建议用户看一眼 | 参考拆解质量略低、某个角色命名有歧义但已采用 |
+| 必须处理 | 不处理会影响继续写作、提交或一致性 | blocking issue、正文缺失、commit rejected、projection failed |
+
+### 15.2 Error Catalog
+
+`author_error_catalog.json` 是错误到作者行动的映射表，供 `error_catalog.py` 和 `user_report.py` 共同使用。它不改变错误判定，只负责把已知错误翻译成：
+
+- 人话原因。
+- 对当前章节 / 后续写作的影响。
+- 下一步动作或可复制命令。
+- 严重度与异常分类。
+- 是否允许自动处理。
+
+未知错误必须诚实降级：
+
+```text
+这里遇到一个系统还没有登记过的问题。当前不会把它当成已完成；请先运行 /webnovel-doctor，或反馈时附上日志。
+```
+
+错误目录只做翻译和分类；自动处理白名单必须单独显式登记，且第三期前不扩大现有自动处理范围。
+
+### 15.3 耗时呈现
+
+默认只展示：
+
+- 已耗时。
+- 当前步骤是否仍在推进。
+- 长时间无进展时的可能原因。
+- 是否影响已完成结果。
+
+不设置固定耗时阈值。不同 API、模型、网络、章节长度和审查复杂度差异过大，固定阈值会误导作者。
+
+过程提示可以使用相对表达：
+
+```text
+“保存本章故事事实”已经运行了一段时间，可能是接口响应较慢或本章新增事实较多；当前不会影响已生成正文。
+```
+
+### 15.4 工作项
+
+- [ ] 在 Skill 最终报告要求中加入“异常分类”。
+- [ ] 新增 `author_error_catalog.json` 与 `error_catalog.py`。
+- [ ] 给 `mainline_ready=false`、`write-gate failed`、`chapter-commit rejected`、projection failed / pending、RAG 降级、artifact schema 不完整等场景建立首批条目。
+- [ ] 未命中错误码时降级到“诚实报错 + `/webnovel-doctor` + 日志路径”，不得崩溃或乱翻译。
+- [ ] 在 `data-agent.md` 中保留并规范“长时间无进展需说明原因和影响”。
+- [ ] 在 runtime helper 中实现耗时格式化。
+- [ ] 不做 token 统计，不在最终报告展示 token。
+
+### 15.5 验收
+
+- 最终报告不会把 warning、blocking、auto-handled 混在一起。
+- 已知错误能映射为作者可执行下一步，未知错误能诚实降级。
+- 长时间无进展的步骤必须有原因推测和影响判断。
+- token 不作为用户可见报告项。
+
+---
+
+## 16. Phase 4：Runtime 报告 Helper
+
+### 16.1 目标
+
+新增统一 helper，把结构化运行结果渲染成作者友好报告。
+
+本阶段同时落地 spec 的 Review Author View：在现有审查报告顶部增加作者视图，不改变 reviewer schema、不改变评分和 blocking 判定。
+
+作者视图格式：
+
+```text
+本章结论：✅可以继续 / ⚠️建议改 / ⛔必须先改
+
+最值得处理的 1-3 件事：
+- ...
+```
+
+生成规则：
+
+- `blocking_count > 0`：结论为“必须先改”，最多列 3 条 blocking 或高风险问题。
+- 无 blocking 但存在明显建议：结论为“建议改”，最多列 3 条对剧情、人物、节奏最有收益的建议。
+- 无 blocking 且建议较轻：结论为“可以继续”，只保留一句说明。
+- 技术指标、schema、原始 reviewer 维度放在下方报告细节，不放进顶部结论。
+
+### 16.2 CLI 形态
+
+新增：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" user-report \
+  --stage write \
+  --chapter {chapter_num} \
+  --format text
+```
+
+支持：
+
+```bash
+--stage init|plan|write|review
+--chapter N
+--volume N
+--format text|json
+```
+
+### 16.3 数据模型
+
+`user_report.py` 内部使用：
+
+```json
+{
+  "schema_version": "webnovel-user-report/v1",
+  "stage": "write",
+  "overall_status": "completed | partial | needs_user | failed",
+  "project_root": "",
+  "chapter": 0,
+  "volume": 0,
+  "files": [],
+  "issues": {
+    "auto_handled": [],
+    "needs_confirmation": [],
+    "must_handle": []
+  },
+  "timing": {
+    "total_ms": 0,
+    "steps": []
+  },
+  "next_actions": []
+}
+```
+
+### 16.4 数据来源
+
+| 阶段 | 数据来源 |
+|---|---|
+| init | 文件存在性、`project-status`、`.story-system/MASTER_SETTING.json` |
+| plan | 规划产物文件、`placeholder-scan`、`master-outline-sync` 输出、Story System 合同文件 |
+| write | `write-gate` 三阶段、review artifacts、commit payload、projection log、backup 输出、subagent runs |
+| review | `review_results.json`、`review_metrics.json`、报告文件、`review_metrics` 表 |
+
+### 16.5 工作项
+
+- [ ] 新增 `review_author_view.py`，从现有 review payload 渲染一句结论 + 最多 3 条可执行建议。
+- [ ] 在 `review_pipeline.py` 的报告渲染环节插入作者视图段，不改 reviewer schema。
+- [ ] 新增 `user_report.py`。
+- [ ] 新增 `webnovel.py user-report` 子命令。
+- [ ] 先实现 `write` 阶段报告，因为它最复杂、收益最大。
+- [ ] 同步实现 `review` 阶段报告，复用审查作者视图。
+- [ ] 最后实现 `init` 和 `plan`。
+- [ ] 给 helper 加单元测试，不依赖真实 LLM。
+
+### 16.6 验收
+
+- 审查报告顶部有一句作者可判读结论，且最多 3 条可执行建议。
+- 作者视图保留 blocking 数等关键事实，不把必须处理的问题写成“可以继续”。
+- `user-report --stage write --format json` 输出稳定 schema。
+- `user-report --stage write --format text` 输出三段式中文报告。
+- projection failed、commit rejected、missing artifact 等场景能被正确归类。
+- helper 输出不包含 token 统计。
+
+---
+
+## 17. Phase 5：断点续跑与交互验证
+
+### 17.1 Prompt integrity
+
+新增或调整断言：
+
+- [ ] 四个主 Skill 都包含过程提示要求。
+- [ ] 四个主 Skill 都包含“少打扰确认策略”。
+- [ ] `/webnovel-write` 的过程节点不超过 6 个作者可理解阶段。
+- [ ] 过程提示使用作者友好阶段名，不直接暴露工程命令作为主提示。
+- [ ] 卡住时必须说明卡点、已完成内容和恢复建议。
+- [ ] `/webnovel-write` 必须说明重复执行同一命令时可从可信断点继续。
+- [ ] 必须用户裁决的问题应优先给有限选项。
+- [ ] 技术详情默认写入 `.webnovel/logs/run_last.log`，不直接污染作者报告。
+
+### 17.2 Runtime tests
+
+新增：
+
+- [ ] `test_run_ledger_records_write_step_status`
+- [ ] `test_write_resume_skips_completed_draft_and_review`
+- [ ] `test_write_resume_rechecks_review_when_chapter_file_changed`
+- [ ] `test_write_resume_retries_backup_after_commit_done`
+- [ ] `test_run_log_redacts_env_values`
+- [ ] `test_user_report_includes_log_path_only_on_failure`
+
+首版如果暂不实现 run ledger，则这些测试先作为 Phase 5 待实现契约，不并入默认必过集合。
+
+### 17.3 Behavior eval
+
+新增：
+
+- [ ] `/webnovel-write` 执行过程中能说明当前处于写前检查、起草、审查、保存事实、提交备份中的哪一段。
+- [ ] RAG 降级不打断用户，但最终报告说明。
+- [ ] projection retry 自动补跑不询问用户，但过程提示说明正在补跑。
+- [ ] blocking issue 无法定点处理时才询问用户。
+- [ ] data-agent 输出不完整时说明已保留正文和审查报告，不提交不完整事实。
+- [ ] 同章重复运行 `/webnovel-write` 时，不重写已可信正文，自动从失败步骤继续。
+- [ ] 设定冲突类 blocking issue 使用有限选项裁决。
+- [ ] 不可恢复故障报告中给出 `.webnovel/logs/run_last.log`。
+
+### 17.4 验收
+
+- 作者在长流程中能判断“现在在做什么”。
+- 非关键问题不会频繁打断作者。
+- 关键创作裁决不会被系统擅自跳过。
+- 失败后能看到明确恢复点。
+- 偶发失败后，重复执行同一主命令可以从最近可信步骤继续。
+- 工程日志可用于排查，但默认不打扰作者。
+
+---
+
+## 18. Phase 6：测试与行为验证
+
+### 18.1 Prompt integrity
+
+新增或调整断言：
+
+- [ ] 四个主 Skill 都包含最终报告要求。
+- [ ] 四个主 Skill 都要求总状态 + 三段式报告。
+- [ ] `webnovel-write` 必须汇报正文、审查、data artifacts、commit、projection、backup。
+- [ ] `webnovel-review` 必须汇报审查报告、metrics 和 blocking 裁决。
+- [ ] Agent 协议中必须可汇总 status / problems / auto_handled / needs_user_action / duration。
+- [ ] 不要求具体措辞，只检查契约是否存在。
+
+### 18.2 Runtime tests
+
+新增：
+
+- [ ] `test_user_report.py::test_render_write_report_success`
+- [ ] `test_user_report.py::test_render_write_report_commit_rejected`
+- [ ] `test_user_report.py::test_render_write_report_projection_failed`
+- [ ] `test_user_report.py::test_render_review_report_blocking`
+- [ ] `test_webnovel_unified_cli.py` 覆盖 `user-report` 注册。
+
+### 18.3 Behavior eval
+
+在 fast eval 中补：
+
+- [ ] `/webnovel-write --minimal` 最终报告必须说明跳过写作检查。
+- [ ] data-agent 输出缺失时最终报告不能写“已完成”。
+- [ ] projection retry 成功时最终报告归入“已自动处理”。
+- [ ] reviewer 有 blocking 时最终报告归入“必须处理”。
+
+### 18.4 验证命令
+
+```bash
+python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py -q --no-cov
+python -m pytest webnovel-writer/scripts/data_modules/tests/test_user_report.py -q --no-cov
+python -m pytest webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py -q --no-cov
+python -X utf8 webnovel-writer/scripts/run_behavior_evals.py --format json
+```
+
+---
+
+## 19. Phase 7：文档与 README
+
+### 19.1 目标
+
+让用户知道每次命令结束后应该如何理解最终报告。
+
+### 19.2 修改范围
+
+- `README.md`
+- `docs/guides/commands.md`
+- `docs/operations/operations.md`
+
+### 19.3 工作项
+
+- [ ] 在 README 的写章工作流中补“最终报告怎么看”。
+- [ ] 在 README 或 commands 文档中补“执行过程中会看到哪些提示”。
+- [ ] 在 commands 文档中说明重复执行主命令会优先尝试断点续跑。
+- [ ] 在 commands 文档中说明四种总状态。
+- [ ] 在 operations 文档中说明哪些情况会询问用户，哪些会自动处理。
+- [ ] 在 operations 文档中说明 `.webnovel/logs/run_last.log` 的用途和敏感信息规则。
+- [ ] 在 operations 文档中说明异常分类和常见处理。
+- [ ] 不写 token 统计说明。
+
+### 19.4 验收
+
+- 用户能从文档理解“已完成 / 部分完成 / 需要你处理 / 未完成”的区别。
+- 用户能知道哪些问题可以忽略，哪些必须处理。
+- 用户知道遇到偶发失败后可以重新执行原命令。
+- 用户知道反馈故障时可以附日志，但平时不需要看日志。
+
+---
+
+## 20. 推荐施工顺序
+
+1. Phase 0：基线审计。
+2. Phase 1A：建立 `author_glossary.json`，四个主 Skill 引用同一术语口径。
+3. Phase 1B：先改四个主 Skill 的最终报告要求，并补“下一步建议”的任务化尾巴。
+4. Phase 3A：建立 `author_error_catalog.json` / `error_catalog.py`，固定异常分类与未知错误降级。
+5. Phase 4A：实现 `review_author_view.py`，在审查报告顶部给一句结论 + 最多 3 条建议。
+6. Phase 2：补 subagent 返回协议，保证主流程有素材可汇总。
+7. Phase 4B：实现 `user_report.py`，先接 `/webnovel-write` 和 `/webnovel-review`。
+8. Phase 5A：补过程提示、开始前预期、确认策略和恢复点。
+9. Phase 5B：实现 `/webnovel-write` 的 run ledger、日志和断点续跑。
+10. Phase 5C：把 blocking 类问题收敛为交互式裁决。
+11. Phase 6：补 prompt integrity、unit tests、behavior eval。
+12. Phase 7：更新 README / docs。
+
+原因：
+
+- 术语表和错误目录是 Author Layer 的单一事实源，先做能避免后续文案和 helper 各翻各的。
+- Skill 契约和下一步尾巴能立刻改善用户可见输出，且风险最低。
+- 审查作者视图是最短路径高收益改造，独立于写章主链，适合早交付。
+- runtime helper 解决长期一致性，但首版保持只读渲染，不改变写作链路。
+- run ledger、自动处理白名单和断点续跑风险更高，放到后面，并优先只覆盖 `/webnovel-write`。
+
+---
+
+## 21. 风险与控制
+
+| 风险 | 影响 | 控制 |
+|---|---|---|
+| 只改提示词导致格式漂移 | 不同 Skill 最终报告仍不一致 | Phase 4 增加 runtime helper |
+| 报告太长 | 作者不想看 | 默认只给三段式，技术细节只在必须处理时展开 |
+| 报告太短 | 问题被隐藏 | 明确不可静默场景 |
+| 工程词太多 | 作者读不懂 | 使用术语翻译表 |
+| helper 过早侵入主流程 | 引入新故障点 | 先做只读渲染，不改变写作链路 |
+| 耗时记录不准 | 误导用户 | 先记录步骤级粗粒度耗时，不做精确性能诊断 |
+| subagent 无法直接返回协议字段 | 主流程难汇总 | 主流程包一层 `SubagentRun`，不强迫 agent 改原始产物格式 |
+| token 统计取消后缺少成本感知 | 少一项工程指标 | token 只留内部观察，不做作者最终报告项 |
+| 过程提示太频繁 | 打断作者沉浸感 | 每个主流程最多展示 3-6 个过程节点 |
+| 该问不问 | 创作方向或事实状态被系统擅自决定 | 少打扰策略中列明必须询问场景 |
+| 不该问却问 | 作者被细碎技术问题打断 | 自动处理类问题默认不询问，只在最终报告说明 |
+| 卡住时只报错误 | 作者不知道成果是否丢失 | 卡住反馈必须包含已完成内容和恢复点 |
+| 断点续跑误判产物可信 | 用旧正文或旧审查继续提交 | 断点恢复必须检查文件更新时间、章节号、模式参数和 gate 状态 |
+| 自动续跑覆盖用户手改 | 用户创作被覆盖 | 检测到正文或章纲有新修改时必须询问 |
+| 交互式裁决选项过多 | 用户仍然困惑 | 每次只给 2-3 个明确选择 |
+| 日志泄露敏感信息 | API key 或私密配置外泄 | 日志写入前过滤 `.env`、API key、secret 类字段 |
+
+---
+
+## 22. Out of Scope
+
+本计划不包含：
+
+- 自动修复 / 自动重审所有 review blocking issue。
+- 新增多轮 reviewer 重审循环。
+- 改写 chapter commit 或 projection 主链。
+- Dashboard 前端大改版。
+- token 成本统计。
+- 自动生成 PR / git commit。
+- 重构所有 Skill 文案瘦身。
+- 实时进度条 UI。
+- Dashboard 流程进度可视化。
+- 完整事务型工作流引擎。
+- 跨所有 Skill 的全量断点续跑；首版优先 `/webnovel-write`。
+
+这些应单独规划。
+
+---
+
+## 23. 最小可落地版本
+
+如果要快速得到收益，建议先做最小版本：
+
+1. 建立 `author_glossary.json`，把术语翻译收成单一事实源。
+2. 建立 `author_error_catalog.json`，至少覆盖 `mainline_ready=false`、`write-gate failed`、`chapter-commit rejected`、projection failed / pending、RAG 降级、artifact schema 不完整；未知错误诚实降级到 `/webnovel-doctor`。
+3. 给四个主 Skill 增加最终报告要求：总状态 + 三段式报告 + 下一步建议。
+4. 给四个 agent 增加可汇总的状态 / 问题 / 自动处理 / 耗时协议。
+5. 在 `review_pipeline.py` 顶部增加审查作者视图：一句结论 + 最多 3 条可执行建议。
+6. 在 `webnovel-write` 的最终报告中强制汇报：
+   - 正文
+   - 审查报告
+   - data artifacts
+   - commit 状态
+   - projection 状态
+   - 备份状态
+   - 下一章是否可继续
+7. 暂不实现完整 `user_report.py`，但把 helper 作为下一阶段明确目标。
+8. 给 `/webnovel-write` 增加 6 个作者友好过程节点和卡住恢复说明。
+9. 在 `/webnovel-write` 中说明重复执行同一命令会尽量从失败步骤继续；实际 run ledger 作为下一阶段。
+10. 最终报告的下一步建议包含任务化说明和可复制命令。
+
+最小版本完成后，作者至少能稳定知道：
+
+- 文件有没有生成。
+- 本章能不能继续往下写。
+- 哪些问题系统已经处理。
+- 哪些问题必须自己确认。
+- 流程中当前走到哪一步。
+- 失败后从哪里恢复。
+- 下一步可以直接执行什么命令。
+
+---
+
+## 24. 最终效果
+
+完成后，作者看到的不是一串命令和 JSON，而是一份稳定交付单：
+
+```text
+总状态：已完成，可以继续写第 13 章。
+
+一、产生的文件与完成情况
+- 正文/第0012章-风雪夜归人.md：已生成并通过写作检查。
+- 审查报告/第12章审查报告.md：已生成，无阻断问题。
+- 本章故事事实：已保存，状态、摘要、长期记忆和检索库已更新。
+- 备份：已完成。
+
+二、过程中遇到的问题与异常耗时
+- 已自动处理：检索库更新较慢，系统已等待完成，不影响结果。
+- 建议确认：本章新增角色“沈照”已写入故事资料，建议你看一眼名字是否满意。
+- 必须处理：无。
+
+三、下一步建议
+- 可以继续执行：
+  /webnovel-write 13
+```
+
+这份报告的价值不是“更好看”，而是让作者每次都能安心判断：这一轮到底靠不靠谱，下一步能不能继续。

docs/superpowers/specs/2026-06-07-author-friendly-experience-design.md

@@ -0,0 +1,220 @@
+# 作者友好体验层设计:工程内核 + 作者外壳
+
+- 日期：2026-06-07
+- 状态：草案 v2 · 双向交叉验证后合并
+- 目标作者画像：**已在用 Claude Code、但非程序员的中文网文作者** —— 会敲 `/webnovel-write`，但被术语黑话、出错信息、长流程劝退
+- 选定方向：方向 C「面向作者重构」，以方向 B「作者呈现层」为地基分期落地
+- 定位与分工：本 spec 是**产品分层规格**（分层 / 组件职责 / 边界 / 红线）；配套的 `docs/architecture/author-friendly-reporting-plan-2026-06-07.md`（codex plan）是**工程落地计划**（Phase / 文件 / 测试 / 施工顺序）。两份互补、配套使用，非二选一。
+
+---
+
+## 1. 背景与问题
+
+`webnovel-writer` 有一条严谨的工程事实链：`Story System → 闸门(write-gate) → CHAPTER_COMMIT → 投影(projection)`，外加 RAG 与长期记忆。这条链保证「写到几百章仍不写崩」的一致性，是产品的核心价值。
+
+问题在于：**这条链把工程语言、工程过程、工程错误，原样喷给了写作者。** 作者实际接触的不是「设计精良的写作工具」，而是 `preflight`、`write-gate prewrite/precommit/postcommit`、`projection_status`、`CHAPTER_COMMIT accepted/rejected`、`mainline_ready=false` 这类面向开发者的输出。
+
+用户在四类痛点上明确表达了改善意愿（四项全选）：
+
+| 痛点 | 作者的真实体验 |
+|------|----------------|
+| 进度像黑箱 | 写一章时 Claude 刷一屏命令和 JSON，不知道在干嘛、是否正常、还要多久 |
+| 出错看不懂没法救 | 报错讲技术原因，不告诉作者「现在该敲哪条命令 / 改哪个文件」 |
+| 审查报告不好用 | 每章报告偏技术、偏长，难快速抓住「这章行不行、要不要改、改哪」 |
+| 术语劝退 | 合同 / 提交 / 投影 / 闸门 / commit accepted 等工程词贯穿全程，作者无对应心智模型，产生距离感 |
+
+## 2. 核心洞察
+
+这**不是四个独立问题，是同一个缺口的四个切面**：
+
+> 系统缺少一层**「作者界面层」** —— 把工程事实翻译成作者语言、把工程过程压缩成作者关心的进度、把工程错误映射成作者能执行的下一步、把审查产物渲染成作者能决策的结论。
+
+| 痛点 | 本质 | 该层补什么 |
+|------|------|------------|
+| 进度像黑箱 | 过程语言没翻译 | 把多步流水线压成作者里程碑 |
+| 出错没法救 | 错误没翻译 + 没给出路 | 错误码 → 人话 + 下一步行动；可重跑续跑 |
+| 审查报告不好用 | 结果没翻译 + 不可执行 | 一句结论 + 最多 3 条「怎么改」，技术细节按需展开 |
+| 术语劝退 | 概念没翻译 | 统一术语对照 |
+
+结论：方案的核心是**在工程链与作者之间补一层翻译/呈现，工程事实源一个字不动**。工程严谨不牺牲，作者那一侧完全换一张脸。
+
+## 3. 目标与非目标
+
+**目标**
+- 让目标作者在日常使用中，默认不直接接触工程语言、工程过程、工程错误。
+- 出错时作者总能拿到「人话 + 下一步该做什么」，且能靠重跑同一命令自动续跑。
+- 审查结论可在三秒内被作者判读并据以决策。
+- 全程术语统一、可理解。
+
+**非目标（YAGNI）**
+- 不改写工程内核（Story System / 闸门 / commit / 投影 / RAG）的任何逻辑或数据结构。
+- 不重命名现有 `/webnovel-*` 命令，不破坏现有用户习惯与既有文档。
+- 不为非技术作者降低一致性校验强度。
+- **不引入任何新 UI**（无折叠面板、无进度条、无按钮）。作者外壳只落到文本提示、Skill 规范、Python helper、日志文件。
+- 不做「自动修复大循环」（见 §8）。
+
+## 4. 约束与红线
+
+两条贯穿全程的原则：
+
+1. **对作者隐去 ≠ 放松校验，也 ≠ 静默。** 所有 gate 照常跑、照常拦，事实链正确性零妥协。系统自动处理过的事（如投影补跑）**必须在最终报告说明**，绝不静默；区别只在「默认不主动展示工程细节、不为过程性小事打断作者」。
+2. **C 以 B 为地基，分三期落地。** 每期独立交付价值、风险递增、可随时叫停，避免一次性大爆炸。
+
+> 关于「Claude Code 能力边界」：本设计不假设宿主有折叠 UI、进度条、后台任务或图形按钮。所有「隐去工程细节」都通过 **Skill 约束少输出 + Python helper 渲染精简报告** 实现，不是任何界面级折叠。
+
+## 5. 架构：工程内核 + 作者外壳
+
+三层。作者只跟最上层打交道，工程内核退到幕后。作者外壳**不是新程序/新界面**，而是 Skill 提示规范 + Python helper + 文本输出 + 日志这四样东西的合称。
+
+```
+┌─────────────────────────────────────────────┐
+│  作者外壳 (Author Shell)   ← 物理载体:Skill规范+helper+文本+日志 │
+│  · 导航尾巴:"接下来你可以…"                       │
+│  · 命令任务化(仅提示语言,不改命令名)               │
+│  · 可自动处理项:不打扰作者,但最终报告必说明          │
+│  · 工程细节默认不展示:作者看里程碑+结论,需要时给路径/命令 │
+├─────────────────────────────────────────────┤
+│  呈现/翻译层 (Author Layer)  ← 地基,零侵入          │
+│  · 进度播报规范  · 错误→行动映射表(catalog)        │
+│  · 审查作者视图  · 术语对照表                      │
+├─────────────────────────────────────────────┤
+│  工程内核 (Engine)  ← 一个字不动                   │
+│  Story System · 闸门 · commit · 投影 · RAG        │
+└─────────────────────────────────────────────┘
+```
+
+## 6. 组件设计
+
+七个职责单一、可独立交付的组件，按期归位。每个组件都明确了在 codex plan 里的工程落点。
+
+### 6.1 术语对照表（Glossary）· 第一期
+- **职责**：工程词 → 作者词 + 一句话作者解释的单一事实源；其余组件都引用它。
+- **消费**：无（自身是词库）。
+- **产出**：受控词汇表，例：合同→设定档案、提交/commit→入账存档、投影/projection→同步到各处、闸门/gate→自检关卡、`mainline_ready`→这本书的档案是否就绪。
+- **依赖**：无。是其他三件的底座。
+- **落地形态**：单一事实源文件（`references/author_glossary.md` 或结构化 `author_glossary.json`），SKILL prompt 与脚本输出统一引用，禁止各处自造译法。codex plan §5 已给出初始译表，并入本组件。
+
+### 6.2 进度播报规范（Progress Narration）· 第一期
+- **职责**：把写章流水线压成作者里程碑并定义措辞模板。
+- **消费**：写章流程当前所处步骤。
+- **产出**：作者只看见「查前情 → 写正文 → 体检 → 入账存档 → 完成」。
+- **依赖**：术语对照表。
+- **落地形态**：写入各多步命令的播报约定，规定每个里程碑何时报、报什么。**默认不主动展示工程命令与 JSON**（靠 Skill 约束少输出 + helper 渲染精简，非 UI 折叠）；**失败信息必须浮出**。对应 codex plan §8。
+
+### 6.3 错误→行动映射表（Error Catalog）· 第一期
+- **职责**：把已知错误映射为「人话描述 + 下一步行动 + 严重度」。本方案价值最高的组件（codex 评审认同应纳入）。
+- **消费**：`preflight` / `write-gate` / `doctor` 等产出的错误码或特征。
+- **产出**：例 `mainline_ready=false` → 「这本书还没建档，先运行 `/webnovel-init`」。
+- **依赖**：术语对照表。
+- **落地形态**：`error_catalog.py` + `author_error_catalog.json`；未命中条目时降级到「诚实报错 + 指向 `/webnovel-doctor`」，绝不崩溃或乱翻译。
+
+### 6.4 审查作者视图（Review Author View）· 第一期
+- **职责**：在现有审查报告之上渲染作者视图。
+- **消费**：`review-pipeline` 产出的 review_result（含 `blocking_count` 等）。
+- **产出**：报告顶部一句结论（✅过 / ⚠️建议改 / ⛔必须改）+ 最多 3 条「怎么改」可执行项，技术细节折在下面（按需展开，不是 UI 折叠，是排版分段）。
+- **依赖**：术语对照表；现有 review 产物结构。
+- **落地形态**：`review_pipeline.py` 报告渲染环节新增作者视图段，不改 reviewer schema、不改判定逻辑。
+
+### 6.5 导航尾巴（Next-Step Advisor）· 第二期
+- **职责**：回答「我现在该干嘛」。**决策：嵌进各命令收尾**，不新增独立入口命令（codex 评审认同此判断）。
+- **消费**：`project-status` 输出的 phase 与下一步。
+- **产出**：每条命令跑完追加统一格式提示，例「接下来可以**写下一章** `/webnovel-write 5`」。天然寄生在 codex plan 三段式报告的第三段「下一步建议」。
+- **依赖**：术语对照表；`project-status`。
+- **落地形态**：作为 `user_report.py` 的一部分，被各命令收尾调用，输出统一格式 + 可复制命令。
+
+### 6.6 命令任务化（Task Language）· 第二期
+- **职责**：用作者任务语言表达动作，降低「记 8 个命令名」的负担。
+- **消费**：导航尾巴的下一步建议。
+- **产出**：提示中以任务语言呈现（开新书 / 写下一章 / 看看这章怎么样 / 查个设定），并附原命令名。
+- **依赖**：导航尾巴；术语对照表。
+- **落地形态**：仅提示层映射，**保留 `/webnovel-*` 原命令名不动**，不做真实别名命令。
+
+### 6.7 可自动处理项 + 工程细节默认不展示（Auto-handled & Quiet）· 第三期
+- **职责**：保留系统已有的有限自动处理；默认不为过程性小事打扰作者；工程细节默认不主动展示。
+- **消费**：错误目录的分类；可重试的过程性错误信号。
+- **产出**：投影失败→自动 retry、合同缺失→重新 emit 等**继续保留**，但**过程不中断作者 + 最终报告必须说明处理了什么 + 细节写入日志**；默认只看里程碑与结论，需要时给路径/命令。
+- **依赖**：错误目录；进度播报规范；最终报告。
+- **落地形态**：在错误目录的「可自动处理」类目上挂动作，受 §8 边界约束。**不做自动修复大循环**；真正的「出错恢复」靠作者重跑 → 幂等续跑（见 §8，工程实现引 codex plan §9）。
+
+## 7. 数据流
+
+翻译层是**只读消费 + 重新渲染，绝不插进工程链的写路径**。
+
+```
+工程链照常产出事实产物
+(state.json / review_result.json / gate JSON / 错误码 / projection_log.jsonl)
+        │  (只读消费)
+        ▼
+翻译层  查 术语表 / 错误目录 / 审查视图规范  → 渲染成作者语言
+        │
+        ▼
+作者看到人话；他选择的"下一步"最终仍调用原工程命令
+```
+
+**事实源永远是工程产物，不是翻译产物。** 翻译错了改翻译层即可，底层数据从没动过 —— 这是「隐去但不放松校验」的技术保证，也使翻译层可被独立测试与替换。
+
+## 8. 错误处理与恢复边界
+
+错误分三类区别对待，对应 codex plan 的异常分类（已自动处理 / 建议确认 / 必须处理）：
+
+1. **可自动处理（不打扰作者，但必须说明）** —— 仅限幂等、可重试、不碰作者内容的过程性错误（投影失败→retry、合同缺失→重 emit）。过程中不打断作者，**最终报告如实说明处理了什么、是否影响结果**，细节写日志。**绝不静默。**
+2. **请作者决策（浮出 + 给有限选项）** —— 涉及内容取舍或不可逆（审查 blocking 改不动、commit 因 `missed_nodes` 被 rejected）→ 人话说清 + 2-3 个有限选项（接受 / 手改 / 放弃）。
+3. **诚实报错 + 求助路径** —— 环境依赖级（RAG key 没配、Python 依赖缺失）→ 说人话 + 指向 `/webnovel-doctor`。
+
+**出错恢复 = 重跑即续跑（吸收 codex plan §9）。** 作者不需记补跑命令；重跑同一条命令，系统据「可信完成判据」识别已完成步骤，从失败点续，不重写已有成果。首版只覆盖 `/webnovel-write`。
+
+**重跑必须停下问作者的边界（codex §9.5，完全认同）：**
+- 正文被手动改过 → 问：沿用还是重写（**绝不覆盖作者手改**）。
+- 章纲更新晚于正文 → 问：旧正文还是重起草。
+- 同章已 accepted 又重跑 → 问：重写还是只看状态。
+
+**红线**：绝不自动跳过校验、绝不把 rejected 伪装成 accepted、绝不吞掉影响事实正确性的错误、绝不静默修复（修了就要说）。**不做自动修复大循环**（自愈白名单极易膨胀成新故障点，风险/收益比最差，两边独立评审都否决）。
+
+## 9. 验证策略
+
+测行为、不测文案字面（与项目「测试是探针不是约束」取向一致）：
+
+- **忠实性探针**：同一工程产物，翻译输出必须保住关键事实（过/不过、缺哪些节点、blocking 数），不得篡改或丢失。
+- **错误目录覆盖**：未知错误码自动降级到「诚实报错」，不崩、不乱翻译。
+- **不静默探针**：自动处理过的事（如投影补跑）必须出现在最终报告，不得被吞掉。
+- **续跑边界探针**：正文被手改 / 章纲更新晚于正文 / 已 accepted 等场景，重跑必须停下问作者，不得擅自覆盖。
+
+## 10. 分期落地路线
+
+| 期 | 范围 | 交付物 | 退出条件 |
+|----|------|--------|----------|
+| 一（地基） | 翻译层四件套 | 术语对照表、进度播报规范、错误目录、审查作者视图 | 四件套上线且通过忠实性/覆盖探针；零侵入工程内核 |
+| 二（外壳上半） | 导航尾巴 + 命令任务化 | 各命令收尾统一「下一步」提示、任务语言映射 | 每条命令收尾给出正确下一步；原命令名不变 |
+| 三（外壳下半） | 可自动处理项说明 + 工程细节默认不展示 + 重跑续跑 | 自动处理项写进报告、默认精简呈现、`/webnovel-write` 重跑续跑 | 不静默/续跑边界探针全过；默认视图只见里程碑与结论 |
+
+每期独立交付、可随时叫停。该排序与 codex plan 的优先级一致（见 §11）。
+
+## 11. 双向交叉验证结论与合并方案
+
+**更正一处自我推测**：本 spec v1 第 11 节曾推测 codex plan「聚焦 reporting、范围更窄」。经读其全文，此推测**错误** —— codex plan 范围很广，断点续跑、subagent 返回协议、耗时呈现、脱敏日志均已覆盖，在这些面上比本 spec 更全、更可落地。
+
+**双向交叉验证（两份独立产出 + 互审）达成的共识：**
+
+- 一致点：工程内核不动、只做呈现层；术语翻译/过程提示/错误可理解/下一步建议是核心；问题不静默、不把 rejected 伪装 accepted；runtime/结构化数据驱动优先于纯 prompt；作者默认不看工程细节但保留排查日志。
+- 本 spec 更强：Error Catalog、Review Author View、Next-Step Advisor（嵌收尾）、命令任务化、分期更克制 —— codex 评审认同，建议纳入其 plan。
+- codex plan 更强（本 spec 已吸收）：统一最终报告三段式 + 四状态、断点续跑/run ledger、subagent 返回协议、耗时呈现、脱敏日志、Phase 0-7 可施工细度。
+- codex 指出并已在本 v2 修正的本 spec 风险：①「折叠」改为「默认不主动展示工程细节」（CC 无折叠 UI）；②「静默自愈」改为「可自动处理但必须说明」；③「作者外壳」钉死物理载体为 Skill 规范 + helper + 文本 + 日志，杜绝范围膨胀。
+
+**合并分工**：本 spec 定**产品分层**（分层 / 组件职责 / 边界 / 红线），codex plan 定**工程落地**（Phase / 文件 / 测试 / 施工顺序）。本 spec 七组件并入 codex plan 的落点见各组件「落地形态」。
+
+**合并后实施优先级（与 codex 评审对齐）：**
+1. 术语表单一事实源
+2. Error Catalog
+3. Review Author View
+4. Next-Step Advisor
+5. 过程提示规范
+6. `user_report` helper
+7. 断点续跑 / run ledger
+8. 可自动处理白名单（最克制，最后做）
+
+## 12. 风险与开放问题
+
+- **风险：翻译层与工程内核漂移。** 工程新增错误码/产物字段时，错误目录与作者视图需同步；靠「未命中即诚实降级」兜底，但需把同步纳入发布校验。
+- **风险：进度精简掩盖真实卡顿。** 默认不主动展示工程细节后，须保证失败信号一定浮出、自动处理一定写报告（由 §9 不静默探针保证）。
+- **开放问题：术语对照表的载体**（纯 markdown 规范 vs 结构化数据 + 校验）—— 影响可测试性，留待实现计划定夺。
+- **开放问题：可自动处理白名单具体含哪些错误码** —— 最低优先级，进入第三期前基于错误目录真实条目逐条评定，宁缺毋滥。