novel-analysis

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>
# 输出：texts/{book_id}/raw_text.txt + metadata.json

python skills/novel_analysis/scripts/split_chapters.py texts/{book_id}/raw_text.txt
# 输出：texts/{book_id}/chapters.json

python skills/novel_analysis/scripts/chunk_manager.py texts/{book_id}/chapters.json [--max-words 3000]
# 输出：texts/{book_id}/chunks.json

脚本只做文件读写和切割，Claude 负责判断结果是否合理。章节切割完成后，抽查 3~5 章确认边界正确。

Step 1.5 — 任务队列初始化

python skills/novel_analysis/scripts/build_queue.py <book_id> [--arc-size 10]
# 生成 texts/{book_id}/analysis_queue.json（任务堆栈）
# 若 texts/{book_id}/analysis_log.txt 不存在，自动初始化

运行后确认输出中的任务数量：CFE 任务数 ≈ chunks.json 的 total_chunks，Arc 任务数 = ceil(总章节数 / arc_size)。
已有 results/ 产物的任务会自动识别为 passes: true，断点续跑直接从断点继续。

Step 2 — 章节逐块分析（chapter_function_extractor）

批处理协议（每轮对话开始时执行）：

1. 读取 texts/{book_id}/analysis_log.txt 顶部 Book Patterns 区块，恢复全书上下文
2. 调用 next_tasks.py 获取本批任务：

   python skills/novel_analysis/scripts/next_tasks.py <book_id> --batch-size 20
   

3. 按序对每个 task 执行分析（加载 references/chapter_function_extractor.md），输出符合 schema 的 JSON
4. 每个 chunk 分析完成后立即保存并标记完成：

   python skills/novel_analysis/scripts/save_result.py <book_id> chapter_function_extractor <chunk_id> <json_file> --task-id <task_id>
   

5. 本批全部完成后，再次调用 next_tasks.py 确认下批，或检测全部任务已完成
6. 每轮结束后按 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>
# 例：python skills/novel_analysis/scripts/aggregate_results.py my_novel 1-10
# 输出：results/{book_id}/arc_input/arc_001.json（打包后的多章输入）

加载 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>
# 读取：results/{book_id}/chapter_function_extractor/ 下全部章节结果
# 输出：results/{book_id}/topic_inputs/{topic}.json
# 支持 topic：character_system / worldbuilding / pacing_hook / style_pattern

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>
# 例：python skills/novel_analysis/scripts/save_result.py my_novel character_system_extractor full result.json
# 落盘路径：results/{book_id}/{topic_skill_name}/full.json

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>]
# 读取：两书的 results/{book_id}/compiled/ 内容
# 输出：results/fusion/{fusion_id}/comparison_report.json

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" 字段