| name | novel_analysis |
| description | 拆书分析系统。将一本小说拆解为可复用、可检索、可融合的结构化资产。当用户说"帮我拆这本书"、"分析这部小说"、"提取小说结构"、"我想拆书"、"分析人物/节奏/文风"、"分析多本书"、"对比两本小说"时，必须使用此 skill。即使用户没有明确说"拆书"，只要涉及小说结构分析、章节功能、人物系统、世界观建模、作者隐性规律、多书融合，都应主动调用此 skill。 |
Novel Analysis — 拆书分析系统
核心原则
Claude 是主脑，Python 脚本是只做 I/O 的工具。分析逻辑全部由 Claude 执行，脚本只负责读写和格式转换，不含任何决策逻辑。
1. 快速定位
你在做什么？
你正在用一套分层分析流程，将一本小说拆解为结构化资产：
- 不是写一篇读后感
- 不是复述情节
- 是提取结构、机制、模式，产出可被下游系统继续使用的 JSON 格式结果
分析哲学
| 错误做法 | 正确做法 |
|---|
| "节奏紧凑" | 说明钩子密度、章末悬念类型 |
| "人物鲜活" | 描述角色的欲望/恐惧/行为模式 |
| "文笔细腻" | 指出句长倾向、对话密度、情绪表达习惯 |
| 脑补全书规律 | 先做局部抽取，再归纳高层模式 |
2. 分析深度与模式说明
本 skill 支持三个分析深度层次。根据用户需求选择对应模式，每个模式都建立在上一层的结果之上。
| 模式 | 适用场景 | 核心产物 |
|---|
| 1.0 最小闭环 | 快速了解一本书的结构与机制 | 章节功能分析 + 阶段归纳 + 四类编译输出 |
| 2.0 专题深挖 | 需要深入分析人物/世界观/节奏/文风某一维度 | 四个专题 skill 输出（建立在 1.0 之上） |
| 3.0 深度研究 | 多书对比、发现作者隐性规律、生成跨书融合输入 | 隐性规律提取 + 多书对比报告 + 融合输入构建 |
使用规则：
- 1.0 是所有分析的前提，没有完整的 1.0 结果不得直接跳到 2.0 或 3.0
- 2.0 专题之间互相独立，可按需单独执行任意一个
- 3.0 依赖全部 2.0 结果 + arc 结构结果，不得局部执行
- 执行顺序严格串行：1.0 全部完成 → 2.0 → 3.0
3. 主流程（11步，完整版）
工作目录约定：所有脚本命令均以项目根目录（包含 全职法师.txt、texts/、results/ 的那一层）为 CWD 执行。
格式：python skills/novel_analysis/scripts/<script>.py
数据目录 texts/、results/、exports/ 均在项目根目录下，不在 skill 目录内。
Step 1 — 预处理
python skills/novel_analysis/scripts/ingest.py <file_path>
python skills/novel_analysis/scripts/split_chapters.py texts/{book_id}/raw_text.txt
python skills/novel_analysis/scripts/chunk_manager.py texts/{book_id}/chapters.json [--max-words 3000]
脚本只做文件读写和切割，Claude 负责判断结果是否合理。章节切割完成后，抽查 3~5 章确认边界正确。
Step 1.5 — 任务队列初始化
python skills/novel_analysis/scripts/build_queue.py <book_id> [--arc-size 10]
运行后确认输出中的任务数量：CFE 任务数 ≈ chunks.json 的 total_chunks，Arc 任务数 = ceil(总章节数 / arc_size)。
已有 results/ 产物的任务会自动识别为 passes: true，断点续跑直接从断点继续。
Step 2 — 章节逐块分析（chapter_function_extractor）
批处理协议（每轮对话开始时执行）：
- 读取
texts/{book_id}/analysis_log.txt 顶部 Book Patterns 区块，恢复全书上下文
- 调用
next_tasks.py 获取本批任务：
python skills/novel_analysis/scripts/next_tasks.py <book_id> --batch-size 20
- 按序对每个 task 执行分析（加载
references/chapter_function_extractor.md），输出符合 schema 的 JSON
- 每个 chunk 分析完成后立即保存并标记完成：
python skills/novel_analysis/scripts/save_result.py <book_id> chapter_function_extractor <chunk_id> <json_file> --task-id <task_id>
- 本批全部完成后，再次调用
next_tasks.py 确认下批，或检测全部任务已完成
- 每轮结束后按 Section 7 协议追加
analysis_log.txt Session 日志块
断点续跑：重新打开对话后，直接从步骤 1 开始执行上述协议，analysis_queue.json 中 passes: true 的任务会被自动跳过。
Step 3 — 阶段汇总（arc_structure_summarizer）
每 5~20 章为一组，执行一次阶段归纳：
python skills/novel_analysis/scripts/aggregate_results.py <book_id> <arc_range>
加载 references/arc_structure_summarizer.md，对打包结果执行阶段分析，保存输出。
Step 4 — 编译（novel_analysis_compiler）
所有章节和阶段分析完成后：
python skills/novel_analysis/scripts/validate_coverage.py <book_id>
无缺失后，加载 references/novel_analysis_compiler.md，汇总全部结果，输出四类资产（总报告 / 全书模型 / 融合输入卡 / 风格约束卡）。
Step 5 — 导出
python skills/novel_analysis/scripts/export.py <book_id> [--format json|csv|excel] [--skill all|chapter_function_extractor|...]
以上 Step 1~5 为 1.0 最小闭环。如只需了解一本书的基本结构，在此结束。
Step 6 — 专题输入打包（2.0 前置）
1.0 完成后，如需进行专题深挖，先将全书章节结果打包为专题 skill 所需输入：
python skills/novel_analysis/scripts/build_topic_input.py <book_id>
Step 7 — 专题分析（2.0）
对打包后的输入，逐专题执行分析（可按需选择执行哪些）：
- 加载
references/character_system_extractor.md，执行人物系统专题分析
- 加载
references/worldbuilding_extractor.md，执行世界观专题分析
- 加载
references/pacing_hook_extractor.md，执行节奏钩子专题分析
- 加载
references/style_pattern_extractor.md，执行文风模式专题分析
每个专题分析完成后，保存结果：
python skills/novel_analysis/scripts/save_result.py <book_id> <topic_skill_name> full <json_file>
Step 8 — 超长章节场景切分（可选，2.0）
若 chapter_function_extractor 输出中存在 has_scene_split: true 的章节，可对该章节执行更细粒度的场景切分：
- 加载
references/scene_breakdown_extractor.md
- 以该章节原文为输入，输出场景列表
- 落盘至
results/{book_id}/scene_breakdown/{chapter_id}.json
has_scene_split 字段在 chapter_function_extractor 输出中标记，由 Claude 在 Step 2 分析时判断：该章是否值得做更细粒度的场景切分（通常为章节字数超长、场景跳转复杂的章节）。
Step 9 — 作者隐性规律提取（3.0）
2.0 全部专题分析完成后，执行跨维度的隐性规律归纳：
- 加载
references/author_hidden_pattern_extractor.md
- 以全部 2.0 输出 + arc_structure_summarizer 结果为输入
- 分析作者在结构、角色、节奏、文风上的隐性重复模式
- 落盘至
results/{book_id}/author_hidden_pattern/full.json
Step 10 — 多书融合输入构建（3.0）
如需将两本或多本书的分析结果融合为创作输入：
- 加载
references/fusion_input_builder.md
- 输入：多本书的
compiled/ 目录内容，格式为 books: [...] 数组
- 构建跨书融合输入卡，不在此步执行对比分析
- 落盘至
results/fusion/{fusion_id}/fusion_input.json
Step 11 — 多书对比报告（3.0）
python scripts/compare_books.py <book_id_1> <book_id_2> [--output <fusion_id>]
compare_books.py 是纯 I/O 脚本，只负责读取 compiled/ 内容并格式化输出对比报告，不含任何分析智能。如需深度对比解读，由 Claude 基于输出结果进一步分析。
4. references 引用指引
| 文件 | 职责 | 何时加载 |
|---|
references/novel_cleaner.md | 清洗规则、禁止改写语义 | 预处理前如需手动清洗 |
references/novel_chapter_splitter.md | 章节边界识别、低置信度降级 | 脚本切章后发现异常时 |
references/chapter_function_extractor.md | 系统底座，完整 12 字段 schema + 证据规则 | Step 2 每次章节分析前 |
references/arc_structure_summarizer.md | 5~20 章阶段汇总逻辑 | Step 3 每次阶段归纳前 |
references/novel_analysis_compiler.md | 四类输出编译规则 | Step 4 开始时 |
references/character_system_extractor.md | 人物系统专题分析（2.0） | Step 7 人物专题时 |
references/worldbuilding_extractor.md | 世界观与规则专题分析（2.0） | Step 7 世界观专题时 |
references/pacing_hook_extractor.md | 节奏与钩子专题分析（2.0） | Step 7 节奏专题时 |
references/style_pattern_extractor.md | 文风模式专题分析（2.0） | Step 7 文风专题时 |
references/scene_breakdown_extractor.md | 超长章节场景切分（2.0，可选） | Step 8，对 has_scene_split: true 的章节 |
references/author_hidden_pattern_extractor.md | 作者隐性规律归纳（3.0） | Step 9，2.0 全部完成后 |
references/fusion_input_builder.md | 多书融合输入构建（3.0） | Step 10，多书对比场景 |
references/schemas.md | 所有 JSON schema + 通用包装格式 | 需要确认字段结构时 |
5. 目录结构
skill 包结构（仅含代码与参考文档，不含数据）：
skills/novel_analysis/
├── SKILL.md ← 本文件（主控入口）
├── references/
│ ├── novel_cleaner.md
│ ├── novel_chapter_splitter.md
│ ├── chapter_function_extractor.md ← 1.0 核心底座
│ ├── arc_structure_summarizer.md ← 1.0
│ ├── novel_analysis_compiler.md ← 1.0
│ ├── character_system_extractor.md ← 2.0 专题
│ ├── worldbuilding_extractor.md ← 2.0 专题
│ ├── pacing_hook_extractor.md ← 2.0 专题
│ ├── style_pattern_extractor.md ← 2.0 专题
│ ├── scene_breakdown_extractor.md ← 2.0 可选
│ ├── author_hidden_pattern_extractor.md ← 3.0
│ ├── fusion_input_builder.md ← 3.0
│ └── schemas.md
├── scripts/
│ ├── ingest.py
│ ├── split_chapters.py
│ ├── chunk_manager.py
│ ├── save_result.py
│ ├── aggregate_results.py
│ ├── validate_coverage.py
│ ├── export.py
│ ├── build_topic_input.py ← 2.0 新增
│ └── compare_books.py ← 3.0 新增
└── evals/
└── evals.json
项目根目录（运行时数据，CWD）：
{project_root}/
├── {book}.txt ← 原始小说文件
├── texts/{book_id}/ ← 预处理产物（脚本自动创建）
│ ├── raw_text.txt
│ ├── chapters.json
│ ├── chunks.json
│ ├── metadata.json
│ ├── analysis_queue.json
│ └── analysis_log.txt
├── results/{book_id}/ ← 分析结果（脚本自动创建）
└── exports/{book_id}/ ← 导出产物（脚本自动创建）
结果落盘路径约定：
results/{book_id}/
├── metadata.json
├── chapter_function_extractor/{chapter_id}.json
├── arc_structure_summarizer/{arc_id}.json
├── topic_inputs/
│ ├── character_system.json
│ ├── worldbuilding.json
│ ├── pacing_hook.json
│ └── style_pattern.json
├── character_system_extractor/full.json
├── worldbuilding_extractor/full.json
├── pacing_hook_extractor/full.json
├── style_pattern_extractor/full.json
├── scene_breakdown/{chapter_id}.json
├── author_hidden_pattern/full.json
└── compiled/
├── full_report.json
├── book_model.json
├── fusion_input_card.json
└── style_constraint_card.json
results/fusion/{fusion_id}/
├── fusion_input.json
└── comparison_report.json
6. 全局底层规则
以下规则适用于所有分析步骤，不得豁免：
6.1 分析边界
- 只能基于输入文本分析，严禁脑补未提供内容
- 证据不足时必须明确写
"evidence_status": "insufficient"
- 不得用单次现象上升为全书规律（至少 3 处以上支撑才可归纳）
- 不得擅自补完缺失章节的分析结果
6.2 输出边界
- 优先输出结构和机制，不做空泛文学评价
- 不得用剧情复述代替机制分析
- 所有重要结论必须附
evidence（章节来源 + 原文片段）
- 禁用词：精彩、细腻、生动、丰满、紧凑（发现这些词时替换成机制描述）
6.3 置信度
三档统一：high / medium / low
降级条件（必须触发 low 或 medium）：
- 章节切分不稳，边界模糊
- 上游输入不完整
- 单章证据少于 2 处
- 文本残缺、格式损坏
6.4 错误处理
- 脚本报错时，不继续执行下游步骤，先排查并修复
- 章节级分析失败时，记录 warning，继续处理下一章，最终在 validate_coverage 阶段补齐
7. 跨上下文日志协议（analysis_log.txt）
texts/{book_id}/analysis_log.txt 是追加式（append-only）的跨上下文记忆文件，由 build_queue.py 首次运行时自动初始化。每轮 Claude 分析结束后必须执行以下写入操作。
7.1 每轮结束后：追加 Session 日志块
在文件末尾新增一个 Session 块，格式严格如下：
## [YYYY-MM-DD Session N] {起始 chunk_id} ~ {结束 chunk_id}
- 已完成: {N} 个 chunk，覆盖第 {X}~{Y} 章
- 发现规律: {本轮发现的局部规律，如无则写"无"}
- 已知异常: {遇到的异常情况，如无则写"无"}
- 下次继续: {下一个待处理 chunk_id}（从 {chapter_id} 开始）
---
7.2 发现全书级规律时：更新顶部 Book Patterns 区块
当某个规律在 3 处或以上章节中得到验证，提升为全书级规律，更新文件顶部的 ## Book Patterns 区块（追加或替换对应条目）。
Book Patterns 区块格式：
## Book Patterns ← Claude 每次必读，更新可复用规律
- {规律描述，一行一条，包含支撑章节引用}
- {规律描述}
---
7.3 每轮对话开始时：优先读取 Book Patterns
每次新开对话处理分析任务前，第一步必须读取 analysis_log.txt 顶部至第一个 --- 分隔线之间的 Book Patterns 区块，恢复全书上下文，再调用 next_tasks.py 获取本批任务。
- 单步失败不得跳过记录，必须在结果中保留
"status": "failed" 字段
