# 作者友好体验层设计:工程内核 + 作者外壳

- 日期：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 结构化数据 + 校验）—— 影响可测试性，留待实现计划定夺。
- **开放问题：可自动处理白名单具体含哪些错误码** —— 最低优先级，进入第三期前基于错误目录真实条目逐条评定，宁缺毋滥。