docs: add M8 user quick start and migration guide

[DankerMu]

Summary

• rewrite docs/user/quick-start.md around the M8 workflow from init to daily writing
• add docs/user/migration-guide.md covering all backward-compatible M8 migrations
• mark the OpenSpec tasks complete and link the new guide from docs/user/README.md

Testing

• git diff --check

Closes #133

[DankerMu]

🔍 Cross-Review：PR #181 四维交叉审查报告

由 4 个独立审查 Agent 并行完成：技术准确性 / 文档一致性 / 写作质量 / CI 合规

---

一、CI 合规 ✅ PASS

• markdownlint：0 error
• 链接检查：所有内部链接和锚点有效
• 代码块、表格格式正确
• 结论：可以通过 CI，无阻塞

---

二、技术准确性问题（12 项，2 项严重）

🔴 严重

#	位置	问题	建议
T1	quick-start.md 质量门控表格	门控表遗漏 >= 4.0 直接通过分段，只从 3.5-3.9 开始	补上 >= 4.0 → 直接通过 行
T2	quick-start.md L358-366	hit / partial / miss 三级评价在 quality-rubric.md 和 QualityJudge 规范中均无定义，属于虚构概念	删除或改为"系统会综合考虑爽点是否与大纲目标、角色能力、情节逻辑一致"

🟡 中等

#	位置	问题
T3	quick-start.md L195	fanqie 门控写"尽量在前 200 字内出现"，实际 golden-chapter-gates.json 是硬限制 <=200，应为"必须"
T4	quick-start.md L195	fanqie excitement_type 写"通常应落在 reversal/face_slap/power_up"，实际是 allowed_values 硬限制，应为"必须"
T5	quick-start.md L58-59	tomato 兼容说明容易误解为"已完全移除"，建议明确"仍作为兼容别名在系统内部工作"
T6	quick-start.md L168	试写章写入 staging/quickstart/trial-chapter.md 后的最终去向未说明
T7	quick-start.md L345	2.0-2.9 分段的"暂停给你人工判断"没说明实际触发方式
T8	quick-start.md L136	writing_directives 缺少格式说明（实际应为 DO/DON'T 对比结构）
T9	quick-start.md 质量评审段	风格自然度维度的 7 个子指标完全未讲解，用户无法自助诊断低分原因

---

三、文档一致性问题（1 项关键，2 项警告）

🔴 关键

#	问题	影响
C1	Step F0 + Step F 流程在 migration-guide.md 中完全缺失	quick-start 用 60+ 行介绍 F0/F 作为 M8 核心新流程，但迁移指南只讲了 6 个配置迁移，完全没提工作流变更。老用户升级后可能不知道新项目有全新的初始化流程

🟡 警告

#	问题
C2	migration-guide 缺少对 Quick Start 流程顺序变更（world→characters→style→f0→trial→results）的说明
C3	migration-guide 导言"大多数老项目不需要停机迁移"可能让用户误以为完全不需要理会，建议补充"如果你想启用 M8 新特性或开新项目，仍建议通读"

✅ 通过项

• 术语统一：黄金三章、tomato 兼容、评分阈值、流水线描述——与 ops.md / spec-system.md / novel-cli.md 一致
• 锚点链接全部有效
• README.md 新增链接位置合理

---

四、写作质量与用户体验问题

🔴 严重：quick-start 信息过载

原版"30 分钟上手"是 97 行，现在膨胀到 386 行，混入了大量进阶内容：

• style-profile.json 的 12 个字段逐一讲解（~40 行）
• excitement_type 枚举值 + 评审口径详解（~30 行）
• 8 维度评分权重完整表格 + 门控决策矩阵（~50 行）
• 平台×题材交叉门控矩阵（~20 行）

建议：quick-start 应只保留核心流程（安装→建项→黄金三章→日常续写），进阶内容拆到 advanced-setup.md 或 quality-review.md。

🔴 严重：新手概念跳跃

• "黄金三章"在导言就出现但未解释——新手完全不知道这是什么
• "跑通黄金三章"段一次性涌入 F0、Step F、excitement_type、genre-excitement-map.json 等 10+ 新概念
• "适配层"等内部术语直接使用，缺乏面向新手的解释

🟡 AI 痕迹明显

特征	位置示例
"也就是说"/"换句话说" 堆砌	quick-start L176, L366
四行排比 100% 对称	quick-start L353-356（维度低→建议，格式完全一致）
"是否需要操作→如何操作→不操作会怎样"三段式模板化	migration-guide 全文 6 个小节
教导式/客服式语气	"先不要慌"、"此时更需要你…主动补强"

🟡 migration-guide 三段式建议优化

6 个小节每个都严格遵循"是否需要→如何操作→不操作会怎样"，过于模板化。建议：

• 开头加迁移优先级表（高/中/低），让用户快速判断该看哪段
• 对不需要操作的项（如 canon_status、excitement_type），可以合并为"自动兼容项"一段带过

---

五、汇总评级

维度	评级	阻塞合并？
CI 合规	✅ PASS	否
技术准确性	🟡 需修复	T1 T2 应修（虚构概念+遗漏分段）；T3 T4 措辞需收紧
文档一致性	🟡 需补充	C1 迁移指南缺 F0/F 覆盖
写作质量	🟡 建议优化	信息过载+AI痕迹，不阻塞但建议后续迭代

建议处理优先级

P0（建议合并前修复）：

1. 门控表补 >= 4.0 行（T1）
2. 删除虚构的 hit/partial/miss 评价值（T2）
3. fanqie 门控 "尽量"→"必须"、"通常"→"必须"（T3 T4）

P1（建议尽快补充）：
4. migration-guide 补 Step F0/F 工作流变更说明（C1）
5. quick-start 导言解释"黄金三章是什么"

P2（后续迭代）：
6. quick-start 拆分（核心流程 vs 进阶配置）
7. 去 AI 痕迹打磨
8. migration-guide 加迁移优先级表

---

审查方法：4 个独立 Agent 并行审查（技术准确性 × 文档一致性 × 写作质量 × CI 合规），交叉验证后汇总。

🤖 Generated with Claude Code

[DankerMu]

🔄 Round 2：复审报告（针对 commit 9e7b82a）

3 个复审 Agent 并行验证：P0 修复核查 / P1+新增内容核查 / 写作质量+新错误检查

---

P0 问题修复状态

#	问题	状态	验证依据
T1	门控表补 >= 4.0 行	✅ 已修复	表格完整覆盖所有分数段
T2	删除虚构 hit/partial/miss	✅ 已修复	实际上 excitement_landing 是 QualityJudge 的正式输出字段（见 quality-judge.md），旧版表述不够准确但非虚构；新版改为"判断爽点有没有真正落地"更恰当
T3	fanqie "尽量"→"必须"	✅ 已修复	"第 1 章主角必须在前 200 字内出现"
T4	excitement_type "通常"→"必须"	✅ 已修复	"核心爽点类型必须落在 reversal/face_slap/power_up 之一"
T7	2.0-2.9 人工审核触发方式	✅ 已修复	补充了"由你决定局部重写还是整章重写；Skill 入口里表现为流程暂停等待确认"

P1 问题修复状态

#	问题	状态	验证依据
C1	migration-guide 补 F0/F 说明	✅ 已修复	新增第 7 节，5 个编号步骤覆盖完整流程，与 quick-start 描述一致
C3	导言补"建议通读"提示	✅ 已修复	开头改为"仍然建议把全文通读一遍"，并新增迁移优先级速查表
P1-5	导言解释"黄金三章"	✅ 已修复	首段即定义"指项目开局的第 1–3 章，用来尽早验证平台门控、题材门控和开篇留存能力"

中等问题修复状态

#	问题	状态
T5	tomato 兼容说明	✅ 改善，"仍作为兼容别名在系统内部工作"
T6	试写章最终去向	✅ 已补，"归档到 logs/quickstart/"
T8	writing_directives 格式	✅ 已补，"最好用 DO / DON'T 对比结构"
T9	风格自然度 7 子指标	✅ 已补，7 指标 + structural_rule_violations 附加项，与 quality-rubric.md 完全对应

AI 痕迹改善

特征	修复前	修复后
"也就是说"	L176 存在	✅ 已消除
"换句话说"	L366 存在	✅ 已消除
"先不要慌" 教导式语气	存在	✅ 改为"先看失败点到底来自…"
排比对称	四行 100% 对称	✅ 改为三行科学分类，合理

新增内容质量

• 迁移优先级速查表：3 个场景划分准确，指向对应章节，实用性强
• 第 7 节 Step F0/F 说明：5 步递进清晰，与 quick-start 无矛盾，非模板化
• 风格子指标说明：每项一行中英混排 + 诊断含义，简洁准确
• 未引入新的技术错误

遗留建议（P2，不阻塞合并）

1. quick-start 仍为 394 行（原 97→386→394），长期建议拆分核心流程 vs 进阶配置
2. migration-guide 仍使用"是否需要→如何操作→不操作会怎样"三段式，但第 7 节已做差异化表述，整体可接受

---

结论

所有 P0/P1 问题均已修复，无新增错误，AI 痕迹显著改善。建议批准合并。 🟢

复审方法：3 个独立 Agent 并行验证（P0 逐条对标规范 × P1+新增内容交叉校验 × 写作质量+回归检查）

🤖 Generated with Claude Code