Webnovel Writer · XuanRanL Fork
本 fork 与原项目 lingfengQAQ/webnovel-writer 已分叉为不同产品：
原项目走"轻量化 + 降 token + 单 reviewer 不评分"路线；本 fork 走"13-checker 评分硬卡 + 20 轮 RCA 加固 + 读者四件标尺（含 Round 20 爽感）"路线。
两者架构不可合并，本 fork 选择性吸收原项目精华（v6 之前的好东西），拒绝 v6 删评分 / 删 workflow_manager / 引入 story-system 投影等架构级改动。
1. 这个 fork 解决什么问题（核心定位）
读者追下一章只看 4 件事（Round 20 在原 3 件基础上加第 4 件）：
- 自然度：写得不像 AI（不是"缓缓开口、瞳孔微缩、心中一凛"）
- 画面感：场景具象、感官层次、节奏对（看得见、闻得到、节奏对）
- 追读力：情绪欠债 + 悬念 + 爽点节奏（想看下一章）
- 爽感强度（Round 20 新增）：金手指释放 / 主角胜利 / 反派受挫 / 标题承诺兑现（读完爽不爽）
所有功能必须直接映射到这 4 件之一——映射不到的不做（即使原项目有这功能）。这是本 fork 的取舍底线。
Round 20.x 8 道质量护栏（2026-04-25 → 2026-04-26 累计 4 批）
- A9 dimension floor block：任一维度 <60 → overall ≤70 fail critical（评分体系不再撒谎）
- reader-thrill-checker 6 子维度：金手指/胜利/反派/信息差/标题/节奏 → "读完爽不爽"系统化
- H26 hook_close 落库一致性：Phase G 不再漂移
- H25 连续 8 章无决策钩 P0：主角必须主动选择
- H27 polish sunk cost 警报：v3+polish≥2+5 项 80 一线 → 提示重写
- polish_cycle max-rounds=3 + deviation 出口：防 Ch1 v7 11 轮死循环
- dialogue_ratio_override 章型豁免：空间/独白章型合理低对话
- 大纲三计划 schema（golden_finger / conflict / title_promise）：标题方向硬绑定
详见 webnovel-writer/skills/webnovel-write/references/round20-quality-floor.md
实测兑现（基于《末世重生》Ch1-11 真实数据）
| 标尺 | baseline (Ch1-11 平均) | Round 19 期望（Ch12+） |
|---|
| reader-naturalness | 87.10 | ≥ 92（A + C + F + B 合力） |
| prose-quality | 88.27 | ≥ 91（H 加权） |
| reader-pull | 88.91 | 维持 + 钩子多样性 |
| reader-critic | 80.30 | ≥ 87（X1 谷底自动 block） |
| overall | 88.36 | ≥ 90 |
| polish 周期数 | 2-3 轮 | 1-2 轮（A 起草前预防） |
关键：Ch3=62 / Ch4=58 这种历史 reader-critic 谷底，Round 19 后自动触发 P0 block 不能 commit，必须 polish 重写到 ≥75。
2. Round 19 的 9 个核心 Phase（vs 原项目）
| Phase | 解决什么 | 来源 |
|---|
| A anti-ai-guide.md 起草前预防 | AI 8 倾向 + 本作 N1-N5 根因映射 | 原项目精华（v6 之前） + 本 fork 独有的 RCA 映射 |
| I Ch1 追读契约 9+3 rubric | 网文平台前 300 字弃读率（首句钩 critical / 第 1 段承诺 / 300 字内触发器） | 本 fork 独创 |
| X1 reader-critic <75 全卷 P0 阻止 | Ch3=62/Ch4=58 类首稿低分自动 block，必须 polish 至 ≥75 才能 commit | 本 fork 独创 |
| X1B 前 5 章写前自检 5 类 | 金手指时序 / 突兀编号 / 爽点兑现 / 伏笔节奏 / 读者卡点 | 本 fork 独创 |
| F 4 张项目本地私库 + 双向回灌 | 跨章 7-10 章重犯模式（polish 修不住的根因）从根源根治 | 本 fork 独创（最大杠杆 Phase） |
| H 画面感 3 子规则 | 场景首句视觉锚点 / 5+1 感官色谱（嗅觉强制） / 抽象动作改写 | 本 fork 独创 |
| B polish K/L/M/N + 4 句式 | 200+ 词库扩充 + 4 句式对应 N1/N2/N3/P4 根因 | 原项目精华 + 本 fork 句式硬卡 |
| E plan 跨卷感知 | 下卷规划读最近 N 章真实 hook_close + 钩子趋势 + 未解决伏笔 | 原项目思路 + 本 fork CLI |
| C reader-naturalness 5 子维度 | vocab/syntax/narrative/emotion/dialogue 定向反馈 + polish 定向修最低子维度 | 借鉴原项目 v5（不引入 v6 单 reviewer 整体） |
| G 章末钩子 4 分类 + H25 跨章 | 信息/情绪/决策/动作钩 + 连续 5 章同型 P1 warn | 本 fork 独创 |
永久拒绝合并的原项目 10 类改动（DO NOT MERGE）
详见 webnovel-writer/ROUND19_DO_NOT_MERGE.md：
- v6 单 reviewer.md 替代 13 checker
- workflow_manager 移除依赖 Claude Code /resume
- story-system 事件溯源 + projection writers
- vector_projection_writer + vectors.db
- dashboard 路由多页重建
- Token 整文件压缩替换
- v6 chapter_drafted/reviewed/committed 状态机
- SKILL.md 充分性闸门状态机
- 移除 golden_three_checker / Step 2B legacy
- Memory contract / scratchpad 大改
每条原因 + 替代路径见专门文档。未来 git fetch upstream 看到这 10 类直接跳过。
3. 跨项目可移植性（Round 19.1 P0-1 根治）
私库 CSV 改为项目本地 {project}/.webnovel/private-csv/，跨项目隔离：
- 写《画山海》不会被《末世重生》“陆沉/麦穗/印记”反例污染
- 每个项目专属反例 + fork 共享 schema seed
新项目接入流程见 webnovel-writer/MIGRATION_NEW_PROJECT.md，关键步骤：
webnovel-init 后 9 个 Phase 自动生效- 写完 Ch1-2 后跑 1 次
webnovel.py private-csv --table X --chapters 1-2 初始化项目本地私库
- Ch3+ writer 自动消费本项目专属私库
4. 快速开始
4.1 安装本 fork（推荐）
# 直接 clone（保留 18 轮 RCA 加固 + Round 19 全部）
git clone https://github.com/XuanRanL/webnovelwriter.git
cd webnovelwriter
4.2 安装 Python 依赖
python -m pip install -r requirements.txt
4.3 初始化小说项目
在 Claude Code 中执行：
/webnovel-init
4.4 配置 RAG 环境
cp .env.example .env
# 编辑 .env 填入 EMBED / RERANK / LLM API 密钥
最小配置：
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key
4.5 开始使用
/webnovel-plan 1 # 生成第 1 卷大纲
/webnovel-write 1 # 写第 1 章（自动 Step 0-7 + Round 19 全部 Phase）
/webnovel-review 1-5 # 审查 Ch1-5 质量
4.6 故障排查
python -X utf8 webnovel-writer/scripts/webnovel.py preflight
python -X utf8 webnovel-writer/scripts/webnovel.py sync-cache
python -X utf8 webnovel-writer/scripts/webnovel.py --project-root <project> sync-agents
4.7 启动可视化面板（可选）
/webnovel-dashboard
5. 与原项目同步策略
