webnovel-writer

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 件）：

1. 自然度：写得不像 AI（不是"缓缓开口、瞳孔微缩、心中一凛"）
2. 画面感：场景具象、感官层次、节奏对（看得见、闻得到、节奏对）
3. 追读力：情绪欠债 + 悬念 + 爽点节奏（想看下一章）
4. 爽感强度（Round 20 新增）：金手指释放 / 主角胜利 / 反派受挫 / 标题承诺兑现（读完爽不爽）

所有功能必须直接映射到这 4 件之一——映射不到的不做（即使原项目有这功能）。这是本 fork 的取舍底线。

Round 20.x 8 道质量护栏（2026-04-25 → 2026-04-26 累计 4 批）

1. A9 dimension floor block：任一维度 <60 → overall ≤70 fail critical（评分体系不再撒谎）
2. reader-thrill-checker 6 子维度：金手指/胜利/反派/信息差/标题/节奏 → "读完爽不爽"系统化
3. H26 hook_close 落库一致性：Phase G 不再漂移
4. H25 连续 8 章无决策钩 P0：主角必须主动选择
5. H27 polish sunk cost 警报：v3+polish≥2+5 项 80 一线 → 提示重写
6. polish_cycle max-rounds=3 + deviation 出口：防 Ch1 v7 11 轮死循环
7. dialogue_ratio_override 章型豁免：空间/独白章型合理低对话
8. 大纲三计划 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：

1. v6 单 reviewer.md 替代 13 checker
2. workflow_manager 移除依赖 Claude Code /resume
3. story-system 事件溯源 + projection writers
4. vector_projection_writer + vectors.db
5. dashboard 路由多页重建
6. Token 整文件压缩替换
7. v6 chapter_drafted/reviewed/committed 状态机
8. SKILL.md 充分性闸门状态机
9. 移除 golden_three_checker / Step 2B legacy
10. 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，关键步骤：

1. webnovel-init 后 9 个 Phase 自动生效
2. 写完 Ch1-2 后跑 1 次 webnovel.py private-csv --table X --chapters 1-2 初始化项目本地私库
3. 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. 与原项目同步策略