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

日期：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. 约束与红线

两条贯穿全程的原则：

对作者隐去 ≠ 放松校验，也 ≠ 静默。 所有 gate 照常跑、照常拦，事实链正确性零妥协。系统自动处理过的事（如投影补跑）必须在最终报告说明，绝不静默；区别只在「默认不主动展示工程细节、不为过程性小事打断作者」。
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 的异常分类（已自动处理 / 建议确认 / 必须处理）：

可自动处理（不打扰作者，但必须说明） —— 仅限幂等、可重试、不碰作者内容的过程性错误（投影失败→retry、合同缺失→重 emit）。过程中不打断作者，最终报告如实说明处理了什么、是否影响结果，细节写日志。绝不静默。
请作者决策（浮出 + 给有限选项） —— 涉及内容取舍或不可逆（审查 blocking 改不动、commit 因 missed_nodes 被 rejected）→ 人话说清 + 2-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 评审对齐）：

术语表单一事实源
Error Catalog
Review Author View
Next-Step Advisor
过程提示规范
user_report helper
断点续跑 / run ledger
可自动处理白名单（最克制，最后做）

12. 风险与开放问题

风险：翻译层与工程内核漂移。 工程新增错误码/产物字段时，错误目录与作者视图需同步；靠「未命中即诚实降级」兜底，但需把同步纳入发布校验。
风险：进度精简掩盖真实卡顿。 默认不主动展示工程细节后，须保证失败信号一定浮出、自动处理一定写报告（由 §9 不静默探针保证）。
开放问题：术语对照表的载体（纯 markdown 规范 vs 结构化数据 + 校验）—— 影响可测试性，留待实现计划定夺。
开放问题：可自动处理白名单具体含哪些错误码 —— 最低优先级，进入第三期前基于错误目录真实条目逐条评定，宁缺毋滥。

2026-06-07-author-friendly-experience-design.md 17 KB Histórico Raw