v1.0.0 to v1.0.0

91 added, 258 removed. Audit A to A.

---

name: story-long-analyze

version: 1.0.0

- description: "长篇网文拆文。深度拆解爆款长篇小说的黄金三章、人设架构、爽点设计、节奏控制。单一深度拆解管道：跑完黄金三章（Stage 1）后产出快速预览报告并询问是否继续全量拆解，确认后从 Stage 2 续跑逐章摘要、聚合分析、设定关系、汇总报告，全程产物落盘拆文库/{书名}/。触发方式：/story-long-analyze、/长篇拆文、「帮我拆这本书」「拆这本书」「分析黄金三章」「深度拆解」「完整拆解」「系统拆解」或提供小说文本文件路径——全部进入同一管道。"

+ description: "长篇网文拆文。保留黄金三章、逐章摘要、剧情、情绪、节奏、角色、设定和文风接口，以连续章节块完成因果、双时间线、关系与三维节奏分析；兼容旧成果直接使用、按需增强和断点续跑。含可选三层灵感库管道（灵感库、跨书灵感聚合、更新灵感库）。触发方式：/story-long-analyze、/长篇拆文、「帮我拆这本书」「拆这本书」「分析黄金三章」「深度拆解」「完整拆解」或提供小说文本文件路径。"

metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}

---

# story-long-analyze：长篇网文拆文

你是网络小说结构分析师。

- **核心信念：看懂别人的爆款，才能写出自己的爆款。**

- ---

+ **核心原则：机械边界只解析一次；原文按连续章节块读取一次；同次读取产生逐章事实和跨章观察；聚合阶段复用落盘结果，不重新阅读全文。**

- > Agent 兼容性：只检查当前运行时的 canonical 目录：Claude `.claude/agents/{agent}.md`、OpenCode `.opencode/agents/{agent}.md`、Codex `.codex/agents/{agent}.toml`、Antigravity `.agents/agents/agent-name/agent.md`（`agent-name` 为目标 agent 名），不得因其他端文件存在而误判。Codex 使用同名 `agent_type`；Antigravity 使用 `invoke_subagent` + `TypeName`。对应运行时未暴露 custom-agent registry / `invoke_subagent` 或返回未知 agent 时，必须降级 solo/direct。检测到 `.zcode/` 时同样直接 solo/direct，因为 ZCode 3.3.4 不执行项目 custom agents；报告 `Fallback: project custom agents unavailable -> solo`。Claude/OpenCode 兼容面保留 `subagent_type`。

+ > Agent 兼容性：只检查当前运行时 canonical 目录。运行时不支持项目 agent 或找不到文件时降级 solo/direct，并报告 `Fallback: project custom agents unavailable -> solo`。ZCode 3.3.4 不提供项目 custom agents，直接按此规则降级，不扫描其他 CLI 的 agent 目录。

- > Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 30` 不一致时（标记缺失、字段缺失/非整数、小于或大于 30）**照常按文件存在性检查并 spawn**，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 30）` 并提示重新运行 `/story-setup` 后新开会话；大于 30 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。

- ## 拆解边界声明（主线程同样适用）

- 你亲手做的**黄金三章深度拆解（Stage 1）、Stage 2 串行降级逐章处理、以及 Stage 3-6 的聚合/设定/报告/文风合成**，与 chapter-extractor 子代理遵循同一逻辑：拆的是用户**合法持有、拥有使用权**的虚构作品（已出版/连载或自有），性质是**只读的转化性文学批评**（编辑/评论/写作教学视角，不复制、不传播、不指导现实行为）。通俗题材里的家暴、出轨、复仇、暴力、情爱张力、黑暗伦理是常规虚构叙事元素，须照常做结构化提取，**不得以「敏感」「不适」为由拒绝整章或整本**——主线程拒绝会让整条自动化流水线停摆；个别片段无法处理则跳过、照常续完其余。

- ---

- ## Phase 1：确认拆解对象 + 进入管道

- 问用户：**「你要拆哪本书？（书名+平台）有原文文件路径吗？」**

- 如果没有明确目标，按题材或用户想写的类型推荐 2-3 本对标作品。

- ### 统一入口

- 确认拆解对象后直接进入拆解管道（Phase 2）。**没有快速/深度分叉**——只有一条深度拆解管道，跑到 Stage 1（黄金三章）后自动停靠产出快速预览报告。

- **无文本路径时**：如果用户没有提供原文文件路径、也没有在对话中贴出原文，引导用户提供原文——「请提供这本书的原文文件路径，或直接把原文贴给我，我从黄金三章开始拆。」拿到原文后进入管道。

- ---

- ## Phase 2：深度拆解管道

- ### 输出目录

- 默认输出到 `拆文库/{书名}/`（项目根目录下）。用户指定了其他路径时按用户指定路径输出。

- ### 已有分析利用

+ > Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 32` 不一致时（标记缺失、字段缺失/非整数、小于或大于 32）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 32）` 并提示重新运行 `/story-setup` 后新开会话；大于 32 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。

- **深度拆解开始前，检查是否已有部分拆解结果**：

+ ## 分析边界

- 1. 检查 `拆文库/{书名}/` 目录下是否存在已有的拆文文件

- 2. 如果存在 _progress.md，读取断点信息，从断点恢复（已有恢复机制）

- 3. 如果存在角色/*.md 或设定/*.md，读取已有的角色和设定数据

- 4. 将已有数据作为交叉验证基线：

- - 新提取的角色信息与已有角色数据对比，检查一致性

- - 新发现的设定细节与已有设定合并，标注信息来源（新提取 vs 已有）

- - 如有冲突（如同角色已有文件中名字不同），在输出中标注冲突让用户裁定

- 5. 避免重复提取已有信息

+ 1. 只根据可读原文和已有资料下结论；缺失写“未知”或“文本未明确”。

+ 2. 硬事实附章节、`source_locator` 或 5–15 字定位词；推断标证据强度。

+ 3. 区分客观发生顺序、文本披露顺序、读者所知和角色所知。

+ 4. 分开分析事件推进、读者情绪和篇幅安排，分数不能代替解释。

+ 5. 只迁移抽象机制，不复刻专有设定、角色组合、关键事件链、标志性场面或原句。

+ 6. 不为填字段虚构事实，不把结果倒推成人物早有计划。

- ### 原文备份（管道前置步骤）

+ ## 对作者说话

- **拆解开始前，必须先备份原文**：

+ 作者读到的一切——停下来提问、进度、拆完汇报、出错说明，以及 `快速预览.md`、`拆文报告.md`、人物关系图——按 [references/author-facing.md](references/author-facing.md) 写：大白话讲书、讲章、讲读者和作者能怎么用；不出现脚本名、命令、字段名、状态值、批次编号、内部文件名、质量指标名和证据分级字母；编号只和名称一起出现；需要作者拿主意时给一个问题、推荐选项和默认值；工程细节默认不写，确需时只在末尾留一行技术备注。脚本输出带 `author_message` 时转述它，不贴 JSON 或错误码。

- 1. 检查 `拆文库/{书名}/原文/` 目录是否已存在

- 2. 如果不存在，从用户提供的源路径复制原文文件到 `拆文库/{书名}/原文/`

- 3. 如果用户未提供源文件路径（直接在对话中贴文本），将原始文本保存到 `拆文库/{书名}/原文/原文.md`

- 4. 备份完成后验证：

- - 源文件路径模式：确认 `原文/` 目录下的文件数量和大小与源文件一致

- - 对话贴文本模式：确认 `原文.md` 文件非空（>0 bytes）

+ ## Phase 1：确认对象并检查目录

- ### 输出目录结构

+ 没有书名或原文时询问书名、平台和原文路径；已有完整成果直接使用时不强制索要原文。已有目录先运行只读检查器：

- ```

- 拆文库/{书名}/

- ├── 原文/

- │ └── 原文.txt # 扩展名随源文件；对话直接贴入的文本存为原文.md

- ├── 概要.md

- ├── 章节/

- │ ├── 第1章_深度拆解.md

- │ ├── 第2章_深度拆解.md

- │ ├── 第3章_深度拆解.md

- │ ├── 第1章_摘要.md

- │ └── ...

- ├── 快速预览.md

- ├── 角色/

- │ ├── {角色名}.md

- │ └── 角色关系.md

- ├── 剧情/

- │ ├── {剧情标题}.md

- │ ├── README.md # 剧情目录索引：节奏/情绪模块/故事线的权威范围

- │ ├── 故事线.md

- │ ├── 节奏.md # 关键信息推进 / 爽点循环 / 情绪触动点 / 爆发节奏

- │ ├── 情绪模块.md # 读者需求 / 情绪引擎 / 可复现模块卡

- │ └── 散落情节.md

- ├── 设定/

- │ ├── 世界观/

- │ │ ├── 背景设定.md # 核心规则 + 特殊设定（无法独立的内容合并）

- │ │ ├── 力量体系.md

- │ │ ├── 地理.md

- │ │ └── 金手指.md

- │ └── 势力/

- │ └── {势力名}.md # 内容 >= 200 字时独立；不足合并到世界观/背景设定.md

- ├── 拆文报告.md

- ├── 文风.md # Stage 6 文风：句长/标点/对话潜台词/情绪交替 + 原文锚点范例片段

- └── _progress.md

+ ```text

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/inspect_existing_assets.py" --root "拆文库/{书名}" --compact

```

- > **权威产物**：`剧情/README.md` 说明剧情目录内各文件权威范围；`剧情/节奏.md` 是节奏/关键信息推进/情绪触动点的权威索引；`剧情/情绪模块.md` 是读者需求、情绪引擎、套路框架和可复现模块卡的权威索引。`拆文报告.md` 与 `剧情/故事线.md` 只做摘要投影；若摘要与这两个文件冲突，下游写作以 `剧情/节奏.md` / `剧情/情绪模块.md` 为准。

- ### 管道主体：Stage 0-6

- 这是 story-long-analyze 唯一的执行管道。Stage 0-1 跑完后**自动停靠**产出快速预览报告（见下「Stage 1 停靠点」），用户确认后从 Stage 2 续跑。

- **预期耗时提示**：开始前根据章节数给用户一个粗估：<50 章通常 30-60 分钟；50-200 章通常 1-3 小时；>200 章可能需要多轮会话。Stage 2 可并行提取，但 Stage 3-6 仍依赖前序产物，需按阶段推进。

- | 阶段 | 名称 | 输入 | 输出 | 完成标志 |

- |------|------|------|------|----------|

- | 3 | 聚合分析 | 全部章节摘要 | 剧情/*.md + README.md（含权威分工表与**剧情单元清单**索引）+ 故事线.md + **节奏.md + 情绪模块.md**。**故事框架识别**（前置，决定聚合策略）。**两步法剧情聚合**（先从摘要识别剧情大纲，再按大纲分配情节点）。**关键信息推进索引**（按章节/剧情单元追踪信息如何被扩写）。**情绪触动点与爆发节奏**（爽点/虐点/期待点的铺垫→释放→余波）。**全书情绪节奏总览**（情绪折线、爽点频率、小/中/大高潮位置、冲突升级路径、跨章伏笔地图、小/中/大循环单元）。**读者需求 / 情绪引擎 / 爽文套路框架**（沉淀为可复现模块卡）。**角色合并**（跨章节去重+别名归一）。**角色分级**（主角/反派/核心配角/功能角色）。**散落情节兜底**（6步，含覆盖率验证）。**桥段标签**（每个剧情模块按 deconstruction-notes.md 桥段词表打标，best-effort，无匹配留空）。**质量检查**（阈值详见 material-decomposition.md 质量阈值体系）。 | 质量检查通过 |

- | 4 | 设定+关系（4a/4b/4c） | **4a**：Stage 2 情节点+章节摘要（不依赖 Stage 3，与 3 并行）；**4b/4c**：Stage 3 合并后角色数据+情节点 | 设定/*.md + 角色/*.md。**4a 设定**（世界观/金手指/势力，从 Stage 2 mention 数据归纳）。**4b 角色完整档案**（两阶段模型：Stage 2 轻量提及 → Stage 4b 完整档案；别名解析置信度≥0.85自动合并）。**4c 角色关系提取**（从情节点提取，不从原文；含演变追踪+最终状态合并+隐含推断）。非人形反派在 4a 做完整抽象对抗型分析。 | 4a/4b/4c 全部完成 |

- | 5 | 汇总报告 | 全部输出 | 拆文报告.md（含「读者需求 / 情绪引擎」「关键信息与扩写技法总览」「全书情绪节奏总览」「节奏与情绪触动点」「循环单元」「跨章伏笔地图」「冲突升级路径」「可复现模块」摘要，并指向 `剧情/节奏.md` / `剧情/情绪模块.md`；含「写法技巧」清单，覆盖一笔两用/延迟揭示/视角欺骗/对比锚点/行为循环/身体反应替代心理描写/**跨章回扣**——物品/意象在不同章节承担不同功能）+ **概要.md 全书 500-1000 字版**（plot-aware，覆盖 Stage 0 的 200 字 thin first-pass） | 报告 + 全书概要生成完成 |

- | 6 | 文风 | 拆文报告.md + 章节/第1-3章_深度拆解.md + 章节/*_摘要.md + 原文/原文.txt | 文风.md（整书级写作技法视图：句长/标点/对话潜台词/情绪交替周期 + 4-6 段原文锚点范例片段 + 分层模仿建议，硬上限 ~4000 字。详见 [style-profile-protocol.md](references/style-profile-protocol.md) + [style-profile-generator.md](references/style-profile-generator.md)） | 文风落盘 `拆文库/{书名}/文风.md` |

- ### Stage 0 章节边界子步骤

- Stage 0 完成概要 + 章节索引之后、转入 Stage 1 之前，**必须**额外产出一份「章节边界」表写入 `_progress.md`。这是后续 Stage 1（黄金三章原文切片）/ Stage 2（每章传给 chapter-extractor agent）/ Stage 6（文风采样）共用的**唯一切片来源**——避免每个阶段各跑一次 regex 切片，结果可能不一致。

- 操作：

- - 用 `style-profile-generator.md` Step 4 的章节正则（含千/两，覆盖 1000+ 章）grep 出全部章节行号

- - **先剔掉目录块**：不少原文开头带一段目录，目录里的 `第N章` 同样顶行，会和正文章节行重复命中，不处理就会切出两个「第一章」。判据是行距——目录块内相邻命中只隔一两行，正文章节之间隔着整章篇幅。算相邻命中的行号差，把文件开头那段「行距持续远小于全体中位数」的连续命中整块丢弃

- - **剔完仍有重复章号时不要自行取其一**：多卷书每卷从「第一章」重起是合法结构。这种情况在标题列保留卷号消歧（如 `卷二第一章`），章号列按全书连续序号重编

- - 按 `| 章号 | 标题 | 起始行 | 字数 |` 四列写入 `_progress.md` 的「章节边界」section（见 [pipeline-ops.md](references/pipeline-ops.md) 模板）

- - 落表前校验章号连续、无重复、无跳号；不满足就停下报告，不要带着错表进 Stage 1——Stage 1/2/6 都以这张表为唯一切片真值，错一次会一路错到底

- - `_progress.md` 顶部 `schema_version: 2` 同时落盘

- **恢复前置条件**：续跑只接受 `schema_version: 2` 且包含「章节边界」表的 `_progress.md`。缺失或结构不完整时停止续跑，提示从 Stage 0 章节边界子步骤重建进度文件，避免不同阶段使用不同切片真值。

+ 路径错误必须停止。完整旧项目返回 `direct_use` 后直接使用，不建索引、不读原文。只有用户明确要求增强才读取旧成果。已有摘要一律不覆盖：要重拆某章就删掉它的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md`（只删摘要会从缓存原样补回），整本重拆就换一个新目录。`schema_version` 只报告，不作为新旧门禁，也不得在复用时改写。

- ### Stage 1 停靠点

+ ## Phase 2：唯一管道与三种情况

- Stage 0+1 完成后，管道**自动停靠**，产出快速预览报告并询问用户是否继续全量拆解：

+ | 情况 | 行为 |

+ |---|---|

+ | 部分完成 | 已完成章只读旧拆文；黄金三章可补缺失摘要；仅缺摘要的章进入原文块 |

+ | 已完整拆完 | 默认直接使用；增强只写 `_analysis_cache/` 和 `_progress.md` 状态 |

+ | 全新小说 | 建索引、完成黄金三章，再把其余正文放入不重叠连续章块 |

- 1. **生成停靠交付物**：写 `拆文库/{书名}/快速预览.md`（模板见 [output-templates.md](references/output-templates.md) 的「快速预览报告」）。此时 `概要.md`、`章节/第1章_深度拆解.md`、`章节/第2章_深度拆解.md`、`章节/第3章_深度拆解.md`、`原文/` 均已落盘。

- 2. **写停靠状态**：`_progress.md` 的「最终状态」字段写 `paused_after_stage1`，「断点」段记录「下一操作：Stage 2 逐章摘要」。

- 3. **询问用户**（用 AskUserQuestion 风格的明确二选一）：

- > 「黄金三章已拆完，快速预览报告见 `快速预览.md`。是否继续全量拆解（Stage 2-6：逐章摘要 / 聚合分析（含 `剧情/节奏.md`、`剧情/情绪模块.md`）/ 设定关系 / 汇总报告 / 文风）？预计耗时 {基于章节数粗估}。」

- - 选「继续全量拆解」→ 读 `_progress.md`，从 **Stage 2** 续跑，**不重跑 Stage 0/1**。

- - 选「就到这里」→ 管道结束，`_progress.md` 状态保持 `paused_after_stage1`，告知用户「之后可随时 `/story-long-analyze` 同一本书，会自动从 Stage 2 续跑」。

- 4. **跳过询问的情形**：用户在一开始就明确说「完整拆解 / 一次跑完 / 系统拆解 / 别问」时，仍生成 `快速预览.md`（保留早期判断快照），但**不停下询问**，直接从 Stage 2 续跑到 Stage 6。

+ 检查器只扫描上游 `章节/*_摘要.md` 与黄金三章，逐章报告缺口。新旧投影混存要报告来源，但不要求重拆。

- ### Stage 5 后：选题决策回填（可选）

+ ### 固定交付接口

- `拆文报告.md` 出来后（Stage 5 跑完）执行——和 Stage 6 无关，Stage 6 失败也不影响这步。

+ - `拆文报告.md`、`概要.md`、`快速预览.md`；

+ - `章节/第1-3章_深度拆解.md`、`章节/第N章_摘要.md`；

+ - `剧情/故事线.md`、剧情单元、`节奏.md`、`情绪模块.md`、`散落情节.md`；

+ - `角色/`、`设定/`、`人物关系图/`、`文风.md`；

+ - `chapter_index.csv`、`_progress.md`、`_analysis_cache/`。

- 先定位 `选题决策.md`：项目根有就用它。项目根没有 → 从项目根及其上一级目录起、向下最多 3 层按文件名搜（跳过隐藏目录），按 mtime 由新到旧取最新 3 份。回填是写文件，项目根之外的文件写之前必须先确认：搜到 1 份 → 报出路径问「把本书的拆解支撑回填进这份吗？」；搜到多份 → 用 AskUserQuestion 列候选（路径 + `扫榜日期` + 「都不回填」）。用户不选 → 记「未回填」跳过，不动任何文件。

+ `拆文报告.md` 是阅读入口。剧情单元管因果事实，`剧情/节奏.md` 管信息推进与三维节奏，`剧情/情绪模块.md` 管读者需求和复现机制，`角色/角色关系.md` 管关系事实，`文风.md` 管表达层。

- **仅当**定位到 `选题决策.md`（项目根那份直接用；项目根之外的那份须经上面的确认）时：按本书题材，在它的推荐选题里找**题材关键词对得上**的那个——

- - 正好对上一个 → 把该选题的"能爆的原因"从 `待拆文验证` 改成带出处的支撑：「本书拆解支撑：{`拆文报告.md` 的读者需求/情绪引擎 + `剧情/情绪模块.md` 的可复现模块 Top + `剧情/节奏.md` 的爽点/触动点节奏摘要}（`拆文库/{书名}/拆文报告.md`、`剧情/情绪模块.md`、`剧情/节奏.md`）」。注意还只是假设（只拆了一本，不算坐实）。

- - 对上多个 / 拿不准 → 问用户「《{书名}》对应选题决策里的哪个方向？」

- - 一个都对不上 → 记录「无匹配选题，未回填」，不改文件。

- - `选题决策.md` 缺少当前契约必需的「能爆的原因」字段 → 报告 `invalid_topic_decision_contract`，提示重跑 `story-long-scan` Phase 5 生成当前文件；不猜测、不静默回填，拆文主流程仍可完成。

- - 重复拆文不覆盖：只回填还标着 `待拆文验证` 的；已经填过的不动。

+ ### Stage 0–6

- 工作区里搜不到 `选题决策.md` → 直接跳过，不影响拆文。

+ | 阶段 | 输入 | 主要输出 | 完成判断 |

+ |---|---|---|---|

- ### Stage 6 文风

+ 用户未要求一次跑完时，Stage 1 后按 author-facing.md「开头三章拆完、停下来问」询问是否继续，并一并请作者选 Stage 2 派发方式（串行 / 有限并行 / 不限批次顺序，见 pipeline-ops「执行与提交一个批次」）；作者没选、要求一次跑完、多本书一起拆或由导入自动续跑时都按有限并行（每轮 3 批），后三种情况不停下询问；续跑不重复 Stage 0/1。Stage 3–5 不重读原文。Stage 6 可按索引定点读取 4–6 段原文锚点，但不重扫全书。

- `文风.md` 只负责表达层风格；情绪/节奏意图仍以 `剧情/情绪模块.md` 与 `剧情/节奏.md` 为权威。

- 原文缺失或章节分隔符识别不出 → 在 `文风.md` 的「生成记录」写明 `文风可用：否：{原因}`。Stage 6 失败不阻断管道。

+ ## Stage 0：机械章节索引

- ### Stage 3-4 并行执行

+ 全新和部分完成运行：

- **并行执行图**：

- ```

- Stage 3（剧情聚合 + 角色合并） ──┐

- ├── 4a 与 Stage 3 可并行

- Stage 4a（设定：世界观/金手指/势力） ──┘

- │

- ▼（Stage 3 + 4a 都完成后）

- Stage 4b（角色完整档案）— 串行，依赖 Stage 3 合并后的角色实体

- │

- ▼

- Stage 4c（角色关系提取）— 串行，依赖 4b 角色实体存在

+ ```text

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" --source "{拆文目录}/原文/原文.txt" --output "{拆文目录}/chapter_index.csv" --locator-path "原文/原文.txt"

```

- 4a 数据源是 Stage 2 摘要故可与 3 并行；4b/4c 依赖 Stage 3 角色合并故串行。

- ### 部分失败容忍

- > 与 material-decomposition.md 的对应关系：Stage 0 含 Material 阶段1（章节解析）；Stage 1、5 为新增；Stage 2 = Material 阶段2；Stage 3 = Material 阶段3；Stage 4 合并 Material 阶段4+5。

- 详细模板见 [output-templates.md](references/output-templates.md)，方法论见 [material-decomposition.md](references/material-decomposition.md)。

- ---

- ## 质量检查概要

- Stage 3-4 完成前需通过质量检查（置信度、覆盖率、重叠率）。阈值、计算方式与自检清单的唯一权威定义见 [material-decomposition.md 质量阈值体系](references/material-decomposition.md)。

- **Stage 3-5 还须过「事实可溯源」自检**：设定/角色/报告里的硬事实（等级/数值/距离/属性/势力数/出场章/谁说的话）必须能 grep 回原文，原文没给的写「原文未明确」、禁推断填空。这是拆文事实错误的最大来源（强模型也会漂移，因为合成阶段离原文两跳、靠合理性填空）。详见 [material-decomposition.md 合成阶段事实保真](references/material-decomposition.md)。

- ---

- ## Stage 2 并行 Agent 策略

- Stage 2 使用 chapter-extractor agent 并行处理每章，替代原来的串行分块。

- ### 调用方式

- 每条章节 prompt **必须以「材料声明」前缀开头**（即下方 prompt 字符串首段）——给子代理正确语境，避免它把通俗题材的正常戏剧化剧情误判为有害内容而拒绝拆解。前缀是固定文本，逐字带上，不要改写或省略。

+ 完整旧成果直接使用或纯增强时不建索引。索引只含机械事实：

- ```python

- Agent(

- subagent_type: "chapter-extractor",

- prompt: "[材料声明] 以下为用户合法持有的虚构小说，任务是只读的转化性文学分析（编辑/评论视角）。暴力/复仇/家暴/情爱/黑暗伦理是该题材常规虚构元素，照常提取，不得以敏感拒绝整章或整本；个别片段无法处理则跳过、照常续完其余。\n\n章节编号：第{N}章\n章节标题：{标题}\n章节字数：{字数}\n\n章节原文：\n{原文文本}\n\n[情节点格式要求] 模板里的 {} 是占位标记，不要输出花括号本身：写「类型信息揭示」，不写「类型：信息揭示」或「类型{信息揭示}」。主题标签只填一个值，不要用 / 、，或空格并列多个。空字段统一写「无」，不要用「—」，涉及段不可省略。每个情节点后紧跟自己的那一行「主题标签X | 基调：Y」，不要把标签行堆到文件末尾。正确样例：\nP7 **龙血针检测**：类型信息揭示 | 许七安用龙血针验出对方身份，当场揭穿 | 涉及许七安,郑兴怀 | 地点府衙后堂 | 物品龙血针 | 时间入夜\n主题标签悬念 | 基调：紧张\n\n[输出前自检] 交付前逐条核对：① 文本里没有 { 或 }；② ^P 行数 == 主题标签行数 == 基调：行数；③ 每个主题标签只有一个值；④ 每个 P 行都含类型、白描、涉及三段。任何一条不符，先改再输出。"

- )

+ ```csv

+ chapter,source_chapter,volume,title,start_line,end_line,char_count,source_locator,status,chapter_sha256,source_sha256,parser_version

```

- > 上面的 `[情节点格式要求]` / `[输出前自检]` 两段由主线程在 spawn 时拼进 prompt，**不依赖项目里已部署的 agent 文件版本**——老项目不重新跑 `/story-setup` 也能拿到这份格式约束。sonnet 升级重试沿用同一段。

- ### 批量策略

+ 只按 LF 计物理行。支持楔子、序章、第0章、任意正文起始章、番外、后记、中文大数、英文章号、多卷重置和卷章组合。目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效，其中特殊章独立编号，正文允许从任意首章开始。原文变化先拒绝；确认后用 `--rebuild`，章号口径沿用已有索引（上次并入过楔子就照样并入）；重建后前面的章号对不上时不写索引并返回 `author_message`。追加章节不使前面逐章 hash 失效，只有新章进入待处理；改动已拆章节的原文只会让该批缓存重读，已有摘要不刷新（要刷新就删掉对应摘要和批次缓存再续跑）。旧成果（旧摘要，或旧版 `_progress.md` 下的黄金三章）的章号与新索引对不上时，脚本在写索引前停下并返回 `author_message`：有旧版「章节边界」表就逐章核对标题与起始行，没有表而原文不从第一章开始也停。把说明和选项转告作者（默认推荐①）：① 按旧章号继续——加 `--fold-prologue` 重建，楔子/序章/第0章并进第一章，旧成果原样复用、楔子不单独拆；② 楔子单独成章——把除 `原文/` 外所有按旧章号写的产物（`章节/`、`剧情/`、`角色/`、`设定/`、`人物关系图/`、`快速预览.md`、`概要.md`、`拆文报告.md`、`文风.md`、`_analysis_cache/批次-*.md` 和 `_progress.md`）挪进 `_analysis_cache/legacy/旧章号/`（不删除），再从 Stage 0 重拆；③ 换新目录整本重拆。索引已建过时先删 `chapter_index.csv`（只是机械章节表）再按所选方式重建。

- - 每次 spawn 5-8 个 agent（避免并发限制）

- - 等待当前批次全部完成后，再 spawn 下一批

- - 每批完成后更新 `_progress.md` 记录已处理章节

+ ## Stage 2：计划、提取、提交

- ### Agent 输出收集

+ ### 只读计划

- - 每个 agent 返回 markdown 格式的提取结果

- - 主线程将 agent 输出写入 `章节/第{N}章_摘要.md`

- - 收集所有 agent 的出场人物表，供 Stage 3 合并使用

+ ```text

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" plan --root "{拆文目录}" --intent continue

+ ```

- ### 失败处理 + 质量升级重试

+ 用户明确增强改为 `--intent enhance`。逐批派发加 `--next 1` 只取下一批，确认进度用 `--next 0`。计划不落盘，批次 ID 固定为 `RAW-{起章}-{止章}` 或 `REUSE-{起章}-{止章}`。计划与提交都拒绝超过 3 章或 25,000 字符的非单章原文块；同一章不能出现在两个原文块。计划原文读取数为 0 时不得派发原文任务。

- **两类失败**：

- 1. **执行失败**（agent crash / 超时 / 空输出）→ 同模型（haiku）重试 1 次

- 2. **质量失败**（输出落盘后跑 chapter-extractor.md「质量检查」12 条自检，任一不达标——典型：情节点 < 10、P 行缺白描、概要写成条目罗列或整段「因为…所以…」串联、类型/基调/主题标签超出枚举、`基调：` 漏全角冒号、角色名为昵称/通用称呼）→ **升级到 sonnet 重试 1 次**

+ ### 两种互斥输入

- **可机械校验的硬检查**（主线程落盘后直接 grep，命中即判质量失败，不依赖 agent 自报）：

- - 情节点数 `N = grep -cE '^P[0-9]+ '`；`grep -c '基调：'` 必须 == N（少于 N = 有情节点漏 `基调：` 或漏全角冒号 → 下游 Stage 6 文风采样按全角 `基调：` grep，会静默漏章）

- - 白描段有内容：`grep -cE '^P[0-9]+ [^|]+\|[^|]*[^|[:space:]][^|]*\|[^|]*涉及'` 必须 == N（`涉及` 段前要有两个 `|`，即类型段与白描段各占一段，且白描段不能只有空白；少于 N = 有情节点缺白描，或字段顺序/分隔符不对。白描是情节点的主要证据，引用改为精选后由它承担事实回查）

- - `grep -hoE '基调：[^ |]+'` 去重后 ⊆ {紧张, 轻松, 悲伤, 热血, 爽, 甜, 温馨, 恐怖, 压抑, 其他}

- - `grep -hoE '主题标签[：]?[^ |]+'` 去重（去 `主题标签`/冒号前缀后）⊆ {爱情, 亲情, 友情, 权力, 金钱, 成长, 复仇, 悬念, 搞笑, 热血, 日常, 其他}（出现 `主题标签：` 带冒号、或值为基调词均判失败）

+ - `raw-original`：只按索引读取计划范围，一次产生紧凑逐章事实和跨章观察；

+ - `existing-results`：只读 `source_files` 列出的摘要或黄金三章，不得打开原文。完整旧项目增强只产批次观察；本批含摘要缺口时必须为每章生成紧凑章块。

- > **硬检查就是上面 4 条，没有更多。** 格式漂移主要靠 spawn prompt 与 agent 模板里的格式约束**事前预防**，不靠事后再加校验：花括号残留、标签行位置、空字段占位这类变体只影响可读性，下游没有消费方（Stage 6 文风只 grep `基调：`），为它们新增校验只会让本可用的章节触发重跑。**因此已经落盘的 `章节/*_摘要.md` 不会因为本次格式说明而变成「不合格」，无需重新生成**；老摘要里的 `类型{行动}`、`物品—` 等写法照旧可用，Stage 3-6 读取行为不变。

+ `chapter-extractor` 输出字段为：概要、因果、关键行动、局面结果、涉及人物、信息变化、状态变化、三维节奏、章尾钩子、证据，以及情节点列表（原文块每章 10–20 个、长章最多 30 个，格式见 output-templates）。不得另做章节卡表。派发只给 `source_locator`、字数、输出文件路径和上一批缓存路径：子代理自己读原文、把完整结果写进 `_analysis_cache/输入-{批次ID}.md`，只回一行回执；主会话不转贴原文、不读这份输入，直接提交（细则见 pipeline-ops「执行与提交一个批次」）。

- **升级重试调用方式**（主线程在校验失败后执行）：

+ 提交：

- ```python

- Agent(

- subagent_type: "chapter-extractor",

- model: "sonnet", # 显式覆盖 frontmatter 的 haiku

- prompt: "章节编号：第{N}章\n...（同首次 prompt，含开头的「材料声明」前缀，可追加：'上次校验失败原因：{自检失败项}'）"

- )

+ ```text

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" commit --root "{拆文目录}" --input "{拆文目录}/_analysis_cache/输入-RAW-4-6.md" --batch-id "RAW-4-6" --range-sha256 "{plan 输出值}" --source-file "{plan 来源}"

```

- **最终落盘规则**：

- - haiku 首次通过 → 写入 `章节/第{N}章_摘要.md`，`_progress.md` 标记 `success`

- - haiku 失败 + 同模型 retry 通过 → 同上，备注 `retry_same_model`

- - 质量失败 + sonnet retry 通过 → 同上，备注 `retry_sonnet`

- - sonnet retry 仍失败 → 章节标记 `⚠️ 跳过`，失败原因写入 `_progress.md` 「失败记录」表，拆文报告中注明

- - 单章失败不阻断管道；批次全部 spawn 完成后才决定是否进入 Stage 3

+ 提交脚本先完整校验（原文块每章情节点不足 10 或超过 30 即整批拒收），再按“缓存 → 缺失摘要 → `_progress.md`”写入。摘要投影逐个情节点固定主题、基调和类型枚举，映射不上时主题/基调写“其他”；保留“关键事件”“情节点”“涉及”“基调”等旧消费者字段。任何已有摘要均不覆盖，结果里的 `kept_existing_summary_chapters` 列出被保留的章。

- ### Agent 不可用降级

+ ### 拆分与恢复

- 以下任一情况，Stage 2 自动退回串行模式，由主线程逐章处理（质量不受影响，只是改为串行、速度略慢）。**两条路径的要求是同一份**：串行时概要写法、情节点白描、原文引用精选规则和输出自检都按 [output-templates.md](references/output-templates.md)「Stage 2 章节摘要+情节点」执行；上面的机械硬检查串行同样要跑。串行没有 sonnet 升级重试这条路——硬检查命中时由主线程按失败项重写本章摘要 1 次，仍不过按 `⚠️ 跳过` 记入 `_progress.md` 「失败记录」表。

+ ```text

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" split --root "{拆文目录}" --batch-id "RAW-4-6"

+ "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" repair-progress --root "{拆文目录}"

+ ```

- - **agent 未部署**：当前运行时的 canonical agent 目录未找到 `chapter-extractor.md` 或 Codex 同名 TOML。项目 agent 通常不随写作仓库预置，应重新运行 `/story-setup` 完成当前适配器部署，不跨 Skill 读取模板源。

- - **环境不支持 spawn 子代理**：本 skill 正运行在某个子代理上下文中，无法再起下一层 agent。

+ 拆分将父块记为 `superseded` 并持久化两个相邻子块，重规划不会合回。计划不再有批次、全部摘要落盘后运行 `manage_analysis_run.py mark-stage --stage stage2`；Stage 1 的黄金三章与快速预览落盘后同样标 `--stage stage1`。恢复只信任带结束标记且范围 hash 有效的完整缓存，只补缺失摘要，最后更新进度；不覆盖用户文件。

- ### Stage 2 收尾：合并章节摘要（_章节摘要汇总.md）

+ ## Stage 3：剧情、双时间线与三维节奏

- Stage 2 所有 `章节/*_摘要.md` 落盘后、进入 Stage 3 前，主线程把它们按章号顺序**无损拼接**成 `拆文库/{书名}/_章节摘要汇总.md`（只拼接、不压缩、不改写）：

+ Stage 3–5 用 `manage_analysis_run.py digest` 取料：先读全书跨章观察，逐章字段与情节点简表按章节窗口取，不整份读批次缓存（用法见 pipeline-ops「Stage 3–6」）。

- ```bash

- ls 章节/*_摘要.md | sed -E 's/.*第([0-9]+)章.*/\1 &/' | sort -n | cut -d' ' -f2- | while read -r f; do cat "$f"; echo; done > _章节摘要汇总.md

- ```

+ 剧情点按“起始目标与阻碍 → 改变局面的选择/行动/外部事件 → 局面变化与得失 → 后续影响”合并。事件发生与信息披露分开；同一事实的异常、线索、解释、确认属于一条披露路径。全局只保留约 8–15 个主线或关键转折节点。

- **无损检查**（拼接后校验，任一不过即删除 `_章节摘要汇总.md`、回退逐文件扫描，行为不变）：

- - `grep -cE '^P[0-9]+ ' _章节摘要汇总.md` == 各摘要 `^P` 行数之和

- - `grep -cE '^\*\*概要\*\*' _章节摘要汇总.md` == 摘要文件数（`**概要**` 每章一行，chapter-extractor 并行输出与串行摘要模板都有；不用 `## 第N章` 头——串行摘要模板没有章节头，会误判）

+ 三维节奏分别说明：事件推进 1–5 及状态变化，读者情绪类型/强度 1–5 及触发，篇幅展开度 1–3 及展开/压缩/省略/反复的作用。情绪机制写完整卡，至少覆盖最强三个，值得复现的不设数量上限；其余保留索引。完整卡以 `读者想看什么`、`情绪链`、`戏剧单元`、`可替换项`、`不可照搬` 五个字段齐全为准，字段名按 `references/output-templates.md` 的 EM 卡表原样使用；缺任一项即无法登记灵感库。铺垫、成立条件、关键触发物、复现步骤、失效情形等按需增列。索引节标题用字面量 `## 其他机制索引`。

- Stage 3 / 4a / 4c / 散落情节兜底改为**只读一次 `_章节摘要汇总.md`** 并在上下文中复用，替代每阶段 `glob 章节/*_摘要.md` 重扫（同一份语料的 4-5 次冷读降为 1 次）。

+ `剧情/情绪模块.md` 与 `剧情/节奏.md` 都落盘后，用 `manage_analysis_run.py mark-stage --stage stage3 --output "剧情/节奏.md"` 标记。命令会同时检查两份必需产物；阶段没有 receipt 或依赖 hash。

- **仅当语料能放进上下文时才生成汇总文件**：>500 章、或合并后 `_章节摘要汇总.md` 过大放不进上下文时**跳过本步骤**，改走 [material-decomposition.md](references/material-decomposition.md)「处理批次 → A. 子代理并行模式」：按 10-20 章/批 spawn 子代理，子代理在自己上下文里读该批摘要、只回传 ≤8K tokens 的降维聚合，主线程仅合并聚合结果（必要时分层两两合并）。**主线程不逐章读原始摘要**——跳过汇总文件不等于回到逐文件扫描，那对大书同样放不下。`_章节摘要汇总.md` 不替代 `章节/*_摘要.md`——单章文件仍是落盘真源，Stage 6 文风采样、人工复核照用单章文件。管道结束（Stage 6 后）删除 `_章节摘要汇总.md`——它是派生临时文件，不随 `拆文库/` 交付（`拆文库/` 会被 story-import 保留为写作工程）。

+ ## Stage 4：角色、设定与关系

- Stage 3-5 分块见 [material-decomposition.md](references/material-decomposition.md)（唯一权威）。

+ 从 Stage 2 的 `涉及人物`、状态变化和批次关系观察归一实体，再结合 Stage 3 剧情单元生成角色档案与设定。关系记录动作方向、触发、双方得失、表面/真实状态、阶段变化和证据；“甲保护乙”与“乙依赖甲”分别记录。

- ---

+ 关系图只从 `角色/角色关系.md` 生成：`"{PYTHON}" "{story-long-analyze skill 根}/scripts/render_relation_chart.py" --root "{拆文目录}" --png`。主产物是 `人物关系图/人物关系图.md`（Mermaid + 文字清单，任何 Markdown 查看器都显示中文）；PNG 只在找到能显示图中全部文字的字体时生成（表情等符号不画进图片）。字体不够就不出图，不得自行改画拼音或首字母版，把脚本的 `author_message` 转告作者。

- ## 恢复机制

+ 至少一份角色档案和一份设定文件落盘后运行 `manage_analysis_run.py mark-stage --stage stage4`；缺任一类文件时不得标完成。

- 启动时检查 _progress.md；`paused_after_stage1` → 直接从 Stage 2 续跑。

- 操作步骤见 [pipeline-ops.md](references/pipeline-ops.md)。

+ ## Stage 5：主报告

- ---

+ 报告按 author-facing.md「拆文报告.md」写：拆到哪、核心发现、读者在追什么、故事怎么推进、人物与关系、读者与角色的信息差、节奏、核心机制、可借鉴套路、不建议模仿、文风一句话、还不确定的地方。生成新报告前运行 `manage_analysis_run.py mark-stage --stage stage5 --prepare`，把旧报告完整保存到 `_analysis_cache/legacy/拆文报告.md`；新报告落盘后再运行 `manage_analysis_run.py mark-stage --stage stage5`，命令在 `拆文报告.md` 不存在或为空时拒绝完成。报告只综合底层结果，不再次阅读全文。

- ## 流程衔接

+ 如项目存在 `选题决策.md`，只回填仍标记“待拆文验证”且题材匹配的项。文件存在但缺少当前契约必需的“能爆的原因”等字段时返回 `invalid_topic_decision_contract`，提示重跑 `story-long-scan` Phase 5；文件不存在不影响拆文。

- **流水线：** 长篇

- **位置：** 拆文（长篇流水线第 2 步，在 story-long-scan 之后、story-long-write 之前）

+ ## Stage 6：文风与单独重建

- | 时机 | 跳转到 | 命令 |

- |---|---|---|

- | 准备开写 | story-long-write | `/story-long-write` |

- | 需要市场数据 | story-long-scan | `/story-long-scan` |

- | 更适合短篇 | story-short-scan → story-short-analyze | `/story-short-scan` |

+ 加载 [references/style-profile-generator.md](references/style-profile-generator.md)。优先使用已有 `文风.md` 和有效 `_style-sample.txt`；样本不足时允许依据索引选择 4–6 章、定点读取原文行段。只缺文风时直接运行 Stage 6，不重跑 Stage 1–5。没有有效样本、索引或原文时明确失败，不生成锚点全空的可用档案。

- ---

+ ## 三层灵感库管道（可选后置）

- ## 参考资料

+ 用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时加载 [references/inspiration-library.md](references/inspiration-library.md)。复用 Stage 3 的 EM 机制卡：`inspiration_index.py register-atoms` 机械登记原子灵感索引（无 IA 文件），再按该文档做单书合并与带受控标签的跨书聚合；卡内只用 `书名/EM-xxx` 裸 ID，禁路径引用。缺情绪模块的书先走上方按需增强，不在灵感层代拆。单书拆文不自动入库。

- | 文件 | 何时加载 |

- |------|----------|

- | [references/output-templates.md](references/output-templates.md) | 管道全程：各 Stage 输出模板 + 快速预览报告模板 + `剧情/节奏.md` / `剧情/情绪模块.md` 模板 + 通用速查表 |

- | [references/material-decomposition.md](references/material-decomposition.md) | Stage 2-5：素材拆解方法论 + 质量阈值 + 分块策略；Stage 6 另见文风资料 |

- | [references/pipeline-ops.md](references/pipeline-ops.md) | 管道运维：_progress.md 模板、错误处理、恢复机制操作步骤 |

- | [references/deconstruction-notes.md](references/deconstruction-notes.md) | 拆书方法+影视拆解+抽象拆解法+题材实战 |

- | [references/style-profile-protocol.md](references/style-profile-protocol.md) | Stage 6：文风模板 + 可信度/可用性说明 |

- | [references/style-profile-generator.md](references/style-profile-generator.md) | Stage 6：文风生成 SOP（6 步，含中文数字章节识别 + 全角冒号基调 grep） |

+ ## 状态、旧项目与最终回归

- ---

+ 运行状态只有 `_progress.md` 受管区；既有 `schema_version: 2` 原值保留；`chapter_index.csv` 是机械索引；缓存是恢复证据。有阶段记录后，受管区的 `最终状态` 由脚本按 Stage 3–6 的阶段状态写出（都完成为 `completed`，否则 `pending`）；旧项目沿用自己原有的 `最终状态` 行，全部完成时由脚本改为 `completed`，不写第二行，会话 hooks 靠它判断拆文是否完成，不要手改。不得创建运行计划、checkpoint、逐批 JSON receipt 或 Stage receipt。

- ## 语言

+ 全部完成后按 author-facing.md「全部拆完」向作者汇报。最终必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 schema。

- - 跟随用户的语言回复，用户用什么语言就用什么语言回复

- - 中文回复遵循《中文文案排版指北》

+ 详细命令和恢复顺序见 [references/pipeline-ops.md](references/pipeline-ops.md)。输出模板见 [references/output-templates.md](references/output-templates.md)，素材聚合方法见 [references/material-decomposition.md](references/material-decomposition.md)。联合验收用 [references/semantic-acceptance-fixtures.md](references/semantic-acceptance-fixtures.md) 的六项 0–2 分表，真实模型结果至少 10/12 且无硬失败才算语义通过。