---
name: story-long-analyze
version: 1.0.0
description: "长篇网文拆文。保留黄金三章、逐章摘要、剧情、情绪、节奏、角色、设定和文风接口，以连续章节块完成因果、双时间线、关系与三维节奏分析；兼容旧成果直接使用、按需增强和断点续跑。"
metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
---
# story-long-analyze：长篇网文拆文

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

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

> 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。本次不修改 `agents_version`、插件版本或发布版本。

## 分析边界

1. 只根据可读原文和已有资料下结论；缺失写“未知”或“文本未明确”。
2. 硬事实附章节、`source_locator` 或 5–15 字定位词；推断标证据强度。
3. 区分客观发生顺序、文本披露顺序、读者所知和角色所知。
4. 分开分析事件推进、读者情绪和篇幅安排，分数不能代替解释。
5. 只迁移抽象机制，不复刻专有设定、角色组合、关键事件链、标志性场面或原句。
6. 不为填字段虚构事实，不把结果倒推成人物早有计划。

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

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

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

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

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

| 情况 | 行为 |
|---|---|
| 部分完成 | 已完成章只读旧拆文；黄金三章可补缺失摘要；仅缺摘要的章进入原文块 |
| 已完整拆完 | 默认直接使用；增强只写 `_analysis_cache/` 和 `_progress.md` 状态 |
| 全新小说 | 建索引、完成黄金三章，再把其余正文放入不重叠连续章块 |

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

### 固定交付接口

- `拆文报告.md`、`概要.md`、`快速预览.md`；
- `章节/第1-3章_深度拆解.md`、`章节/第N章_摘要.md`；
- `剧情/故事线.md`、剧情单元、`节奏.md`、`情绪模块.md`、`散落情节.md`；
- `角色/`、`设定/`、`人物关系图/`、`文风.md`；
- `chapter_index.csv`、`_progress.md`、`_analysis_cache/`。

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

### Stage 0–6

| 阶段 | 输入 | 主要输出 | 完成判断 |
|---|---|---|---|
| 0 机械索引 | 原文 | `chapter_index.csv`、`概要.md` 初稿（Stage 5 覆盖） | 章界、逐章 hash 和全源 hash 有效 |
| 1 黄金三章 | 前三章原文 | 深度拆解、快速预览、可选 `_style-sample.txt` | 老接口完整；同次阅读保存可用样本 |
| 2 连续块提取 | 只读计划列出的旧成果或原文块 | 批次缓存；缺失逐章摘要投影 | 缓存完整、摘要存在、状态范围 hash 有效 |
| 3 剧情与机制 | 批次缓存和可信旧成果 | 剧情单元、故事线、节奏、情绪模块 | 文件存在、阶段状态完成 |
| 4 角色与设定 | 批次涉及人物、状态变化、关系观察 | 角色、设定、关系图 | 文件存在、阶段状态完成 |
| 5 主报告 | 权威底层结果 | 拆文报告、完整概要 | 文件存在、阶段状态完成 |
| 6 文风 | 既有资料、样本或索引定点原文 | `文风.md` | 文件存在、阶段状态完成 |

用户未要求一次跑完时，Stage 1 后停下询问是否继续；续跑不重复 Stage 0/1。Stage 3–5 不重读原文。Stage 6 可按索引定点读取 4–6 段原文锚点，但不重扫全书。

## Stage 0：机械章节索引

全新和部分完成运行：

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

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

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

只按 LF 计物理行。支持楔子、序章、第0章、任意正文起始章、番外、后记、中文大数、英文章号、多卷重置和卷章组合。目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效，其中特殊章独立编号，正文允许从任意首章开始。原文变化先拒绝；确认后用 `--rebuild`。追加章节不使前面逐章 hash 失效，只有新章进入待处理；改动已拆章节的原文只会让该批缓存重读，已有摘要不刷新（要刷新就删掉对应摘要和批次缓存再续跑）。旧章映射会整体漂移或旧成果从序章、第0章、非第一章开头而无法确认身份时，停止并明确报告。

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

### 只读计划

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

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

### 两种互斥输入

- `raw-original`：只按索引读取计划范围，一次产生紧凑逐章事实和跨章观察；
- `existing-results`：只读 `source_files` 列出的摘要或黄金三章，不得打开原文。完整旧项目增强只产批次观察；本批含摘要缺口时必须为每章生成紧凑章块。

`chapter-extractor` 输出字段为：概要、因果、关键行动、局面结果、涉及人物、信息变化、状态变化、三维节奏、章尾钩子、证据，以及情节点列表（原文块每章 10–20 个、长章最多 30 个，格式见 output-templates）。不得另做章节卡表。

提交：

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

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

### 拆分与恢复

```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 "{拆文目录}"
```

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

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

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

三维节奏分别说明：事件推进 1–5 及状态变化，读者情绪类型/强度 1–5 及触发，篇幅展开度 1–3 及展开/压缩/省略/反复的作用。最强三个情绪机制完整写读者期待、铺垫、条件、触发、兑现、可变项和失效情形；其余保留索引。

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

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

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

同一关系数据生成核心人物关系图与关键关系演变图。环境无法可靠渲染时记录缺失原因，不另建关系事实。

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

## Stage 5：主报告

报告包括范围与覆盖、人物动力、剧情因果、双时间线与知识边界、三维节奏、核心机制、文风摘要、证据边界和待核项。生成新报告前运行 `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；文件不存在不影响拆文。

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

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

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

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

最终必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 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 且无硬失败才算语义通过。