@oh-story/dsh 0.1.10 → 0.1.12

package/lib/oh-story/skills/story-long-analyze/references/pipeline-ops.md

@@ -52,13 +52,7 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 脚本只按 LF 计算物理行号，支持楔子、序章、第0章、任意正文起始章、番外、后记、多卷和中文大数。CSV 保存内部连续号、来源章号、卷、标题、行界、字符数、`chapter_sha256`、全源 hash 和解析器版本。
 
-同源索引直接复用且不重写。原文变化时先非零退出；人工确认后加 `--rebuild`。重建沿用已有索引的章号口径：已有索引第 1 章是正式章节、而原文开头有楔子/序章/第0章（即上次用了 `--fold-prologue`），自动照样并入，无需再加参数；重建出的前面各章与已有索引对不上（`chapter_mapping_ambiguous:position=N` 或 `index_would_shrink`）时不写索引，返回 `author_message`。追加新章时旧章 hash 保持稳定，输出仅列出新增或内容变化的 `pending_chapters`。改动已拆章节的原文只会让覆盖它的批次缓存失效、下次计划重读该批；已有摘要不刷新——要刷新哪章就删掉哪章的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md` 再续跑（只删摘要会从缓存原样补回）。旧成果按旧章号命名，写新索引前逐一核对：旧摘要一律参与；黄金三章在 `_progress.md` 来自旧版（有「章节边界」表，或没有运行状态受管区）时参与，本次 Stage 1 按索引写的不参与。有旧版「章节边界」表时逐章定位：起始行正好是某章标题行就直接认定；否则按标题找（统一全半角，去掉章号前缀和「（求收藏）」「【二合一】」这类尾注，允许包含关系；标题只有章号时比章号），多个候选取离旧起始行最近的；全部对上才放行；没有表时，原文首章不是第 1 章就无法确认。对不上时不写索引，返回 `chapter_mapping_ambiguous` 和 `author_message`；`plan` 遇到已建好的错位索引同样拒绝。作者的三个选择：
-
-1. **按旧章号继续（推荐）**：`build_chapter_index.py ... --fold-prologue`，开头的楔子/序章/引子/前言/第0章并进第一个正式章节，编号回到旧版口径，旧成果原样复用；输出里的 `folded_into_first_chapter` 列出被并入的章节标签（如「楔子」「第0章」）。楔子内容不会单独拆，要在报告「还不确定的地方」说明。
-2. **楔子单独成章**：把除 `原文/` 外所有按旧章号写的产物——`章节/`、`剧情/`、`角色/`、`设定/`、`人物关系图/`、`快速预览.md`、`概要.md`、`拆文报告.md`、`文风.md`、`_analysis_cache/批次-*.md` 和 `_progress.md`——挪进 `_analysis_cache/legacy/旧章号/`（挪走，不删除），再从 Stage 0 按新章号重拆。旧库只拆到黄金三章时代价最小。
-3. **换一个新目录整本重拆**。
-
-`chapter_index.csv` 已按错误口径建好时，先删掉它（纯机械章节表，可随时重建），再按选择重建；`--rebuild` 只沿用已有索引的口径，不能用来改口径。
+同源索引直接复用且不重写。原文变化、重建后章号对不上或旧成果章号对不上时，按 [index-rebuild.md](index-rebuild.md) 处理。
 
 ## 3. 生成只读计划
 
@@ -77,25 +71,28 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 逐批派发时加 `--next 1` 只取下一批，确认进度用 `--next 0` 只看 `remaining_batches` 与压缩成区间的 `summary_gaps`；全量计划每批约五百字符，整本书反复全量输出会白占主会话上下文。不带 `--next` 时输出全部批次。
 
-计划只存在内存和标准输出，`state_written` 必须为 `false`。每块最多 3 章、25,000 字符；批次 ID 直接使用章节范围。`RAW` 只覆盖缺失章和缓存失效批次，`REUSE` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
+作者只要拆某一段时加 `--chapters 起-止`（可与 `--next` 同用）：只规划这段里的批次，`remaining_batches` 只数这段，`summary_gaps` 仍是全书。这段拆完即停，不标 `stage2`；按 author-facing「全部拆完」只汇报这一段，再问作者是否接着拆其余章节。
+
+计划只存在内存和标准输出，`state_written` 必须为 `false`。每块最多 3 章、25,000 字符，同一章不能出现在两个原文块；计划原文读取数为 0 时不得派发原文任务；批次 ID 直接使用章节范围。`RAW` 只覆盖缺失章和缓存失效批次，`REUSE` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
 
 ## 4. 执行与提交一个批次
 
-`chapter-extractor` 只处理计划中一个批次。**主会话不中转内容**：原文和批次结果都不经过主会话上下文。派发时只给——
+`chapter-extractor` 只处理计划中一个批次。**主会话不中转内容**：原文和批次结果都不经过主会话上下文。派发时照抄计划里这一批的字段，路径前加 `{拆文目录}/`，不另选、不推算：
 
-- 批次 ID、输入类型、计划的 `source_files`（原文块是逐章 `source_locator`，子代理自己按行号读原文）和 `chapter_chars`（每章字数，决定情节点密度）；
-- 输出文件 `{拆文目录}/_analysis_cache/输入-{批次ID}.md`（不写系统 `/tmp`：Windows 没有，多本书同批号会互相覆盖）；
-- 交接缓存路径：按下方派发方式选定的已提交批次缓存（没有就不给），子代理只读其中 `### 跨批状态`。
+- `batch_id`、`input_kind`；
+- `source_files`（原文块是逐章 `source_locator`，子代理自己按行号读原文）、`chapter_chars`（每章字数）和 `min_plot_points`（每章情节点下限，按字数算好）；
+- `input_file`：输出文件 `_analysis_cache/输入-{批次ID}.md`（不写系统 `/tmp`：Windows 没有，多本书同批号会互相覆盖）；
+- `handoff_cache`：交接缓存，计划算好的「本批起章之前最近的已提交批次」，为空就不给；子代理只读其中 `### 跨批状态`。
 
-子代理把完整输出写进输出文件，只回一行 `BATCH_WRITTEN` 回执。主会话**不 Read 这份输入文件**，直接提交；提交被拒时把错误码和输出文件路径交回子代理，让它用 Edit 只改出错处后再提交（结构整体错乱才整份重写）。提交成功后删掉这份输入。不论哪种派发方式，`commit` 都由主会话逐个执行，不并发跑。
+子代理把完整输出写进输出文件，只回一行 `BATCH_WRITTEN` 回执。主会话**不 Read 这份输入文件**，直接提交；提交被拒时重新派发同一批：上面的字段原样再给一遍（子代理补内容要按 `source_locator` 回看原文、按 `min_plot_points` 补情节点），再附错误码，让它用 Edit 只改出错处后再提交（结构整体错乱才整份重写）。提交成功后删掉这份输入。不论哪种派发方式，`commit` 都由主会话逐个执行，不并发跑。
 
-**派发方式三档**（Stage 1 后停下询问时一并请作者选，话术见 author-facing「开头三章拆完、停下来问」）：
+**派发方式**：默认第 2 档有限并行，不请作者在三档里选。作者问起能不能更快或更稳、或明确要求时，才按 author-facing「作者问起怎么拆」用白话解释并切换。三档都用计划给的 `handoff_cache`，它随提交进度自动落到对应的批次上。
 
-1. **串行**：上一批提交成功再派下一批，交接缓存给紧邻的前一批。优点：剧情点、未决悬念和已确认别名逐批完整接续，Stage 3 合并最省事。缺点：最慢，墙钟时间随批数线性增长。
-2. **有限并行**：每轮同时派 3 批，同轮都给「本轮开始前最近一个已提交批次」的缓存；整轮提交完再派下一轮。优点：约快两到三倍，接续最多滞后一轮。缺点：同轮批次互相看不到对方新建的剧情点与别名，边界处可能重复建 ID，靠 Stage 3 跨块合并收拢。
-3. **不限批次顺序**：不等前批，同时在跑的子代理最多 12 个（宿主或账号上限更低时以环境为准）；在跑的少于上限一半时，补派到上限。补派用 `plan --next {在跑数＋补派数}`，跳过已在跑的批次号（计划只认已提交）。遇到限流、超时或子代理报错，把上限减半后再补派。每批给「本批起章之前最近的已提交批次」的缓存，没有就不给。优点：最快。缺点：接续最弱，剧情点与别名最依赖 Stage 3 跨块合并和 Stage 4 归并；并发越高，被限流、整批重跑的风险越大。
+1. **串行**：上一批提交成功再派下一批，交接缓存就是紧邻的前一批。优点：剧情点、未决悬念和已确认别名逐批完整接续，Stage 3 合并最省事。缺点：最慢，墙钟时间随批数线性增长。
+2. **有限并行**：每轮同时派 3 批，同轮的交接缓存都是本轮开始前最近一个已提交批次；整轮提交完再派下一轮。优点：约快两到三倍，接续最多滞后一轮。缺点：同轮批次互相看不到对方新建的剧情点与别名，边界处可能重复建 ID，靠 Stage 3 跨块合并收拢。
+3. **不限批次顺序**：不等前批，同时在跑的子代理最多 12 个（宿主或账号上限更低时以环境为准）；在跑的少于上限一半时，补派到上限。补派用 `plan --next {在跑数＋补派数}`，跳过已在跑的批次号（计划只认已提交）。遇到限流、超时或子代理报错，把上限减半后再补派。优点：最快。缺点：接续最弱，剧情点与别名最依赖 Stage 3 跨块合并和 Stage 4 归并；并发越高，被限流、整批重跑的风险越大。
 
-作者没选、要求一次拆完 / 全量拆、多本书一起拆，或由 story-import 自动续跑时，都按第 2 档；第 3 档只在作者明确选择时使用。多本书同拆时按书轮流派，第 3 档的总并发也不超过同一上限。第 1、2 档用 `plan --next 1` / `--next 3` 取批。子代理不可用时主线程自己写批次，包裹标记照 output-templates「批次提交格式」：
+作者没提、要求一次拆完 / 全量拆、多本书一起拆，或由 story-import 自动续跑时，都按第 2 档；第 1、3 档只在作者明确选择时使用。多本书同拆时按书轮流派，第 3 档的总并发也不超过同一上限。第 1、2 档用 `plan --next 1` / `--next 3` 取批。子代理不可用时主会话自己写批次：先读 [stage2-extraction.md](stage2-extraction.md)，提取规则与包裹标记照其中「批次提交格式」：
 
 ```text
 "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" commit \
@@ -111,10 +108,10 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 提交顺序固定：
 
-1. 在写文件前校验整批范围、标记、所有紧凑字段和情节点（原文块每章 10–20 个、长章最多 30，少于 10 或多于 30 整批拒收；编号连续、每点带主题标签与基调行）；
+1. 在写文件前校验整批范围、标记、所有紧凑字段和情节点（原文块每章不少于 `min_plot_points`、最多 30，否则整批拒收；编号连续、每点带主题标签与基调行）；
 2. 对 `RAW` 再算当前范围 hash，与计划值不一致就拒绝；
 3. 原子写入含完整模型输出和最终结束标记的批次缓存；
-4. 只创建缺失的 `章节/第N章_摘要.md`，任何已有摘要都保留，并在结果的 `kept_existing_summary_chapters` 里列出；
+4. 只创建缺失的 `章节/第N章_摘要.md`，任何已有摘要都保留，并在结果的 `kept_existing_summary_chapters` 里列出；摘要投影把每个情节点的主题、基调和类型映射到固定枚举（主题/基调映射不上写“其他”），保留“关键事件”“情节点”“涉及”“基调”等旧消费者字段；
 5. 最后更新 `_progress.md` 受管批次表为 `completed`；有阶段记录时按 Stage 3–6 状态重写受管区的 `最终状态`（旧项目改写原有行，不写第二行）。
 
 每条成功行记录章节范围、输入类型、原文范围 hash、状态和缓存路径。受管区外的 BOM、换行、作者备注及既有 `schema_version` 必须逐字节保留。
@@ -146,43 +143,12 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 恢复只从完整、范围 hash 有效的缓存补缺失摘要并更新状态；不覆盖用户修改过的文件。缓存缺结束标记或范围 hash 失效时报告错误并重跑相应批次。
 
-## 7. Stage 3–6
-
-Stage 1 黄金三章与快速预览落盘后标 `stage1`；计划不再有批次时标 `stage2`。Stage 3–6 各运行一次。文件成功原子落盘后再标记：
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage \
-  --root "{拆文目录}" --stage stage3 --output "剧情/节奏.md"
-```
-
-**Stage 3–5 的读法**：不整份 Read 批次缓存（每批约七成是和逐章摘要重复的章节块），改用只读的 `digest` 按需取料，输出是 Markdown：
+## 7. 阶段标记与后续时刻
 
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" digest --root "{拆文目录}" --part observations [--chapters 1-60]
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" digest --root "{拆文目录}" --part chapters --chapters 1-60 --fields 三维节奏,涉及,状态变化 --points brief
-```
-
-- `observations`：按章序汇总已提交批次的跨章观察（剧情点、关键事件与披露候选、关系变化、三维峰谷、跨批状态），是 Stage 3–4 的主语料；
-- `chapters`：从逐章摘要抽字段（概要、关键事件、因果、局面结果、涉及、信息变化、状态变化、三维节奏、章尾钩子、证据），`--points brief` 给每点「标题｜类型｜基调」，`full` 另带白描；
-- 全书放不进一次上下文时按 `--chapters` 分窗口取，窗口间只带剧情状态与证据引用；只有关键证据冲突才定点 Read 单章摘要。
-
-阶段完成只看约定产物存在且进度行完成；没有依赖 hash 或 Stage receipt。`mark-stage` 会按阶段检查：Stage 1 的黄金三章与快速预览、Stage 2 的全部摘要、Stage 3 的情绪模块与节奏、Stage 4 的角色与设定、Stage 5 的报告、Stage 6 的文风。Stage 6 的单独重建见 [style-profile-generator.md](style-profile-generator.md)，允许按索引定点读取 4–6 段原文，不重扫全书，也不触发其他阶段。
-
-生成新的 `拆文报告.md` 前先执行：
+Stage 1 黄金三章与快速预览落盘后标 `stage1`；计划不再有批次、全部摘要落盘后标 `stage2`：
 
 ```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage --root "{拆文目录}" --stage stage5 --prepare
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage --root "{拆文目录}" --stage stage2
 ```
 
-若旧报告存在，命令会完整复制到 `_analysis_cache/legacy/拆文报告.md`；已存在的首份备份不覆盖。当前旧报告与首份备份不同时，另存一份带内容 hash 的历史备份。其他旧产物与已有摘要不得覆盖。新报告落盘后再用不带 `--prepare` 的 `mark-stage` 标记完成。
-
-## 8. 最终检查
-
-检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
-
-- 再运行检查器和计划器；完整项目应 `direct_use`，继续意图应无待处理批次；
-- 对比受保护路径 hash：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md`、`拆文报告.md` 不得被增强或恢复流程改写；
-- 允许变化的旧项目文件只有 `_progress.md` 受管状态区和 `_analysis_cache/` 新证据；
-- 检查旧 `schema_version` 原值；
-- 检查新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取；
-- 报告未执行的真实模型或跨平台检查，不得用静态 fixture 冒充。
+Stage 3–5 的取料（`digest`）与标记见 [synthesis-inputs.md](synthesis-inputs.md)，Stage 6 见 [style-profile-generator.md](style-profile-generator.md)，全部拆完后的收尾检查见 [final-checks.md](final-checks.md)。

package/lib/oh-story/skills/story-long-analyze/references/stage1-golden-chapters.md

@@ -0,0 +1,128 @@
+# Stage 0–1：概要初稿与黄金三章
+
+开头时刻（Phase 1 到 Stage 1 停下来问）读本文件。作者读到的 `快速预览.md` 与停下来问的话术见 [author-facing.md](author-facing.md)。
+
+## Stage 0 概要（thin first-pass）
+
+> **范围说明**：Stage 0 只能基于章节标题 + 卷段结构 + 抽样开头/结尾产出 thin first-pass（~200 字）。**禁止**在此阶段写出 500-1000 字 plot-aware 概要——读取范围不足以支撑那个密度。完整版在 Stage 5 落盘覆盖（见 [stage5-report.md](stage5-report.md)「完整概要」）。
+
+输出 `概要.md`：总字数{X}万 | 总章数{N} | 题材{类型}
+
+| 卷/段 | 章节范围 | 章数 | 预估字数 |
+|-------|----------|------|----------|
+| {卷名} | 第1-X章 | {N} | {W}万 |
+
+首版概要（~200字，thin first-pass）：{从章节标题 + 第1章+末章抽样归纳出的核心驱动 + 主角名 + 大致设定，不要硬凑剧情转折}
+章节索引：| 章节 | 标题 | 字数 |
+
+> Stage 5 完成后会就地覆盖此文件的「首版概要」段为「全书概要（500-1000字 plot-aware）」。章节索引和卷段表保留不变。
+
+## Stage 1 黄金三章
+
+黄金三章拆为三个单章文件，每章一个：`章节/第1章_深度拆解.md`、`章节/第2章_深度拆解.md`、`章节/第3章_深度拆解.md`。每个文件按以下模板输出。
+
+字数约{X}字 | 核心事件：{一句话}
+
+**开篇钩子**（第1章看前500字）：类型{悬念/冲突/反差/信息差/代入感} | 手法{描述} | 效果{强/中/弱}—{原因}
+
+**人物出场**：{列表} | 主角塑造{直接描写/对话/行为/他人评价} | 第一印象{描述}
+
+**世界观铺设**：透露{信息} | 隐藏{信息} | 方式{对话/旁白/事件}
+
+**结构拆解**：| 段落范围 | 功能{铺垫/冲突/爽点/收尾} | 字数 |
+
+**爽点分析**：类型{装逼打脸/逆袭反转/获得机缘/信息差碾压/情感满足} | 铺垫{X}字 / 释放{Y}字 / 铺放比{Z:1} | 情绪曲线
+
+**反应层拆解**（如有）：
+
+| 层级 | 角色 | 反应 | 篇幅 |
+|------|------|------|------|
+| 质疑/轻视 | | | |
+| 震惊/打脸 | | | |
+| 强者重评 | | | |
+| 扩散传播 | | | |
+
+反应篇幅比{N:1} — 低于1.5 = 爽感不足
+
+**释放后追证**（如有）：爽点释放后反派真实态度？{行为+原文引用}
+
+**冲突升级**（如有）：{行为} | 升级层级{口头→经济→暴力} | 对角色画像影响
+
+**背景信息揭示**（如有）：揭示{什么} | 叙事功能{推翻预设/重新解读/铺垫新线/认知偏差} | 对主线影响
+
+**章尾钩子**：类型{悬念/反转/新信息/新角色} | 内容{描述} | 期待度{强/中/弱}
+
+**可借鉴要素**：{可复用技巧}
+
+> 第二、三章额外关注：信息密度 / 冲突升级(vs上章) / 节奏变化 / 爽点间隔字数。
+> 反派若为非人形（灵气复苏/末世/国运等抽象对抗型），在「爽点分析」处改用抽象对抗型路由：核心对抗面{描述} | 紧迫感来源{描述} | 升级机制{描述} | 叙事替代{用什么替代传统打脸}。
+
+同一次黄金三章阅读优先另写 `_style-sample.txt`，减少 Stage 6 的定点取样；旧项目没有该缓存时，Stage 6 仍可按索引选择 4–6 章并只读取对应行段：
+
+```text
+<!-- STYLE_SAMPLE:v1 -->
+## 片段 A
+source_locator: 原文/原文.txt:L{起始行}-L{结束行}
+基调: {紧张/压抑/轻松/温馨/热血}
+示范点: {句长节奏/标点/对话潜台词/动作与反应等}
+{300—500字连续原句}
+```
+
+共选4—6段，允许同章多段，但范围不得重叠；只保留用于表达分析的最小样本，不建立第二套剧情事实。
+
+## 快速预览报告
+
+Stage 1 停靠点交付物 `拆文库/{书名}/快速预览.md`，模板见 [author-facing.md](author-facing.md)「快速预览.md」。字段只取 Stage 0/1 已产出数据（概要.md + 黄金三章深度拆解），不引入需 Stage 2-6 才能算出的内容；「基本信息」「黄金三章评分」两节与终态 `拆文报告.md` 同名同结构。终态生成后不删除 `快速预览.md`。
+
+## 通用速查
+
+### 爽点类型
+
+| 类型 | 定义 | 例子 |
+|------|------|------|
+| 装逼打脸 | 实力碾压被轻视的人 | 「你也配？」 |
+| 逆袭反转 | 绝境翻盘 | 废材觉醒 |
+| 获得机缘 | 得到别人没有的 | 捡到神器 |
+| 信息差碾压 | 读者和主角知道别人不知道的 | 重生先知优势 |
+| 情感满足 | 人物关系发展 | 告白/团聚/认可 |
+| 扮猪吃虎 | 隐藏实力突然展露 | 弱者实则是强者 |
+
+### 钩子类型
+
+| 类型 | 定义 | 示例 |
+|------|------|------|
+| 悬念钩 | 未解之谜 | 「剑为什么认他为主？」 |
+| 冲突钩 | 直接对抗 | 开篇追杀 |
+| 反差钩 | 违反常识 | 「穿越第一天就破产」 |
+| 代入钩 | 读者共鸣 | 相似困境 |
+| 信息差钩 | 读者知道角色不知道的 | 「他还不知道面前是……」 |
+
+### 爽点循环结构
+
+三层微观循环：
+- **铺垫层（蓄势）**：压抑/困境/信息差制造情绪缺口
+- **释放层（爽感）**：展露实力/打脸/碾压，强度由反应层数和篇幅决定
+- **衔接层（承转）**：旧循环结束埋新钩子
+
+反应层递进：质疑/轻视 → 震惊/打脸 → 强者重新评价 → 扩散效应
+反应篇幅比 = 反应总字数 / 装逼字数。低于1.5 = 爽感没接住。
+
+### 衔接过渡模式
+
+| 模式 | 机制 | 示例 |
+|------|------|------|
+| 打完小的来大的 | 释放层对手引出更强对手 | 打败弟子→师父找上门 |
+| 胜利发现隐患 | 释放成功暴露新问题 | 赢了比赛→发现中毒 |
+| 身份暴露/反转 | 释放中身份被识破 | 打脸后被认出真实身份 |
+| 利益升级 | 成果指向更大目标 | 线索→更深层宝藏 |
+| 关系突变 | 释放改变关系格局 | 救的人变仇家后代 |
+
+### 题材爽点形态
+
+| 题材 | 释放层形态 | 反应层来源 | 铺垫层缺口 |
+|------|-----------|-----------|-----------|
+| 玄幻/修仙 | 实力碾压/境界突破 | 同门/对手/长老震惊 | 功法残缺/资源匮乏/血脉压制 |
+| 都市 | 预测准确/身份揭露 | 商业对手/前女友/权贵 | 破产/被辞/被退婚 |
+| 系统文 | 解锁稀有技能/任务奖励 | 系统稀有度标注 | 任务失败惩罚/技能冷却 |
+| 历史 | 以弱胜强/先知优势 | 谋士/帝王/敌将震惊 | 信息不对称/身份低微 |
+| 悬疑 | 真相揭露/反杀 | 被揭穿者崩溃/读者恍然 | 线索误导/嫌疑人洗白 |

package/lib/oh-story/skills/story-long-analyze/references/stage2-extraction.md

@@ -0,0 +1,229 @@
+# Stage 2：批次提取规则与模板
+
+子代理可用时由 `chapter-extractor` 按自己的定义提取，主会话只按 [pipeline-ops.md](pipeline-ops.md) 派发与提交，不读本文件。子代理不可用、主会话自己写批次时读本文件。
+
+## 提取方法
+
+先运行 `manage_analysis_run.py plan`，只执行标准输出中的内存计划。Stage 2 不再存在逐章独立调用，也不落盘计划文件。
+
+### A. 已有成果批次
+
+对 `existing-results` 批次只读取计划列出的旧拆文文件：
+
+1. 上游 `章节/第N章_摘要.md` 优先；
+2. 没有摘要时复用黄金三章；
+3. 同一章只选择一个优先来源。
+
+从旧成果二次提取剧情点、关键事件与披露候选、关系和三维节奏。不得打开原文，不得为了统一格式重写旧逐章文件。旧资料没有的信息留空或写“旧资料未提供”。
+
+### B. 未拆原文章节块
+
+对 `raw-original` 批次一次读取一个不重叠的连续块：
+
+- 普通短章通常 3 章；
+- 长章或信息密集时 1-2 章；
+- 每块最多 3 章，默认同时受 25,000 字符上限约束；
+- 遇到卷界、来源缺口或空章必须断开；
+- 每章在全书运行计划中只属于一个原文块。
+
+同一次理解产生两层结果：
+
+1. 每章紧凑事实：概要、因果、信息变化、状态变化、三维分数、钩子、证据和情节点（一般 10–20 个、最多 30，短章按字数降下限）；
+2. 批次观察：剧情点、关键事件与披露候选、关系、三维异常点和跨批状态。
+
+逐章兼容文件由脚本从紧凑事实机械生成；批次缓存保留全部逐章紧凑事实和跨章观察，作为恢复证据。全局聚合用 `digest` 取跨章观察与所需逐章字段，不整份读缓存，也不逐个打开章节文件。不得第二次读取该块来生成逐章文件，也不得把 50-60 章交给一个 agent 后让它自行拆成多个“批次”。
+
+### C. 剧情点是主要分析单位
+
+每个剧情点记录：
+
+| 字段 | 说明 |
+|---|---|
+| 章节范围 | 当前可确认的起止章；允许跨批延续 |
+| 起始目标 | 谁想做什么 |
+| 阻碍 | 人物、规则、资源、信息或环境阻碍 |
+| 变化来源 | 改变局面的选择、行动或外部事件 |
+| 局面变化 | 目标、风险、资源、关系、知识或行动方向的前后差异 |
+| 得失 | 收益归谁、代价由谁承担 |
+| 后续影响 | 结果怎样促成或限制后续行动 |
+| 状态 | `open` / `closed` |
+| 证据 | 原文模式用 source locator；已有成果模式用资料路径 |
+
+读取批次不等于剧情点。一个批次可以出现多个剧情点，一个剧情点也可以跨批次。跨批延续时继承剧情点 ID 和当前状态；Stage 3 再统一合并、拆分和校验边界。
+
+### D. 兼容逐章资料
+
+逐章投影只保留现有导入、写作与查询实际使用的内容：概要、关键事件、因果、局面结果、涉及、信息变化、状态变化、三维节奏、章尾钩子、证据和情节点序列（逐点带基调）。取消逐章重复的长篇写法公式、角色复述和扩写技法长表。写法机制、信息差、关系与节奏集中在剧情点及 Stage 3 权威产物中。
+
+### E. 跨章观察
+
+批次缓存固定包含：
+
+1. 剧情点；
+2. 仅限主线/关键转折的事件与披露候选；
+3. 有向关系变化；
+4. 事件、情绪、篇幅三维节奏的峰谷与分离点；
+5. 未闭合剧情点、悬念、关系状态和待核事项。
+
+角色实体只记录新别名和状态变化，不在每章重复生成人物小传。
+
+### 原子提取六大铁律
+
+1. **双序分离**：逐章事实按文本披露顺序排列；客观事件另标故事内发生顺序，不能把倒叙或回忆挪成当前事件
+2. **客观白描**：记录"发生了什么"和结果，原文明说的起因照写，不推测未写出的动机，不用叙事框架词
+3. **信息保真**：不遗漏改变语境的关键细节
+4. **高度浓缩**：一个情节点一句话概括
+5. **复合合并**：为同一戏剧目的服务的连续微动作合并为一个情节点
+6. **客观事实**：提取客观事实，不做叙事分析
+
+**客观白描 vs 叙事框架词**：
+- 禁止：「通过对话，郑松得知张子豪在韩国训练」
+- 正确：「吴志斌告诉郑松，张子豪在韩国训练」
+- 禁止：「林风展现了自己的实力」
+- 正确：「林风三招击败对手，围观者倒吸一口凉气」
+- 禁止：「邵阳感到心碎和愤怒」
+- 正确：「邵阳目睹宋丽与人拥抱，表情由刺痛转为冷漠」
+
+## 分块与主会话串行
+
+Stage 2 按运行计划分别建立旧成果批次和缺章原文块，每批调用一次 chapter-extractor；原文块同次返回逐章事实和跨章观察，旧成果批次只返回跨章观察。其他阶段只消费这些结果和可复用旧资料。
+
+> **先分清两个互不相干的轴**（混在一个「块」字里会让 >500 章出现差 30-100 倍的两套规格）：
+> - **语义分块**＝*在哪里切*。按叙事弧切，产出「块元数据」用于组织分析结果，块可以很大（一个 914 章的书通常 5-10 个弧）。它不决定一次读多少。
+> - **处理批次**＝*一次读多少*。受上下文容量约束，原文块按索引字数切分，旧成果批次按资料体积切分。下表指的是**处理批次**。
+
+| 单章与上下文情况 | 读取批次策略 | 常见章数 |
+|------|------|--------|
+| 普通章节、上下文充足 | 连续读取并保留跨章状态 | 3 章/批 |
+| 长章、信息密集或上下文较小 | 缩小批次，不截断明显短因果链 | 1-2 章/批 |
+| 超长书 | 批次数量增加；语义弧仍独立于读取批次 | 仍按上述字数与上下文判断 |
+
+> 批次数由原文长度和上下文决定，不设“超过 500 章就固定 10-20 章/批”的第二套规则。
+
+**主会话串行模式（agent 不可用时的降级）**
+
+无法 spawn 子代理时由主会话按同一连续批次契约顺序处理。批次可因主会话上下文更小而缩短，但仍须同次产生逐章事实和跨章观察，不能退回每章一次调用。
+
+**不要做的事**
+
+- 不要把大语义弧整块塞进一次上下文。
+- 不要固定章数而忽略原文字数、上下文容量和章界。
+- 不要在 Stage 3、4、5 各自重新读取同一批原文。
+- 不要用跳读锚点冒充完整语义覆盖。
+
+## 输出模板
+
+Stage 2 有两种互斥输入。`raw-original` 只处理运行计划列出的未拆章节块；`existing-results` 只读取旧成果做二次提取。两种结果都形成批次剧情点，只有 `raw-original` 生成新的逐章兼容投影。
+
+### 未拆章节的紧凑语义结果
+
+`chapter-extractor` 在一次章节块阅读中按章输出以下紧凑字段。它是模型输出，不直接充当旧接口文件：
+
+```markdown
+## 第{N}章 {标题}
+
+**概要**：{60-160字，按文本披露顺序说明主要行动、原文给出的原因和结果}
+
+**因果**：目标：{谁想做什么}｜阻碍：{具体阻碍}｜行动：{改变局面的选择/行动/外部事件}｜结果：{局面变化}｜得失：{承担者及得失}
+
+**关键行动**：{真正改变局面的一个选择、行动或外部事件}
+
+**局面结果**：{行动后的目标、风险、资源或关系净变化}
+
+**涉及人物**：{关键人物，顿号分隔；没有写无}
+
+**信息变化**：{新披露内容｜读者所知｜关键角色所知或未知}
+
+**状态变化**：{角色/关系/资源/风险的净变化}
+
+**三维节奏**：事件{1-5}/5｜情绪{类型+1-5}/5｜篇幅{1-3}/3｜{三轴差异的一句话原因}
+
+**章尾钩子**：{类型与具体等待；没有写无}
+
+**证据**：{source_locator+5-15字定位词}
+
+**情节点**：
+
+P{序号} **{标题}**：类型{转折点/信息揭示/冲突/解决/铺垫/行动/对话/状态变化} | {白描一句话：谁做了什么、结果如何；原文给出的起因一并写进来，不推测动机；埋伏笔的写出伏笔线索} | 涉及{全名，逗号分隔；无人物写无} | 地点{如明确，否则无} | 物品{如涉及，否则无} | 时间{如明确，否则无}
+{可选引用行：≤400字原文连续切片，或 `原文定位：{可 grep 的原句片段}`}
+
+主题标签{爱情/亲情/友情/权力/金钱/成长/复仇/悬念/搞笑/热血/日常/其他} | 基调：{紧张/轻松/悲伤/热血/爽/甜/温馨/恐怖/压抑/其他}
+
+---
+
+P{序号+1} ……
+```
+
+**情节点**是逐章事件序列，下游对标挑章、结构关键点定位和导入反推情绪弧线都按它读：
+
+- 原文块每章一般 10–20 个，按字数调节，最多 30；下限是计划给的 `min_plot_points`（字数÷200 四舍五入，至少 1、至多 10）；旧成果补摘要下限 1 个，按旧资料写到的事件拆，不凑数；编号从 P1 连续。太粗（整段打架）丢细节，太细（举起右手）碎片化，恰当粒度是一个完整戏剧事件。
+- 严格按原文事件时间顺序，不重排、不归纳。标题 ≤15 字，不与白描同句。
+- 白描只写可见事实：不替角色补原文没写的情感、意图，不写“精彩”“气氛紧张”这类评价，不用“通过对话得知”这类叙事框架词；原文明说的起因和内心活动照写。
+- 字段名后不加冒号；`主题标签` 只填一个值；每个情节点紧跟自己的 `主题标签X | 基调：Y` 行，`基调：` 用全角冒号。
+- 引用只给关键转折、关键台词、写法样本，每章至多 8 条，其余情节点不写引用行。
+
+### 批次提交格式
+
+提交给 `manage_analysis_run.py commit` 的文件按下列标记包裹，子代理与主会话自己写批次都一样；标记缺失或顺序不对整批拒收：
+
+```markdown
+<!-- CHAPTER_START:{N} -->
+## 第{N}章 {标题}
+{上面的紧凑字段与情节点}
+<!-- CHAPTER_END:{N} -->
+（本批每章一块，章号连续、各恰好一次）
+
+<!-- BATCH_OBSERVATIONS_START -->
+## 跨章观察
+{下方「批次剧情点」的五个小节}
+<!-- BATCH_OBSERVATIONS_END -->
+```
+
+- 旧成果批次（`REUSE-*`）：计划列出的摘要缺口落在本批时，为本批每章都写章节块（情节点至少 1 个）；没有缺口时不写章节块，改在开头写一行 `<!-- REUSED_CHAPTERS:{起章}-{止章} -->`。
+- 跨章观察块恰好一个，放在所有章节块之后。不要输出 `MODEL_OUTPUT_START/END` 或 `story-long-analyze:cache` 标记（脚本自己加）。
+
+`manage_analysis_run.py commit` 校验这些字段后，机械生成缺失的 `章节/第{N}章_摘要.md`：情节点逐条投影并把类型、主题、基调映射到枚举，章级字段保留“概要、关键事件、涉及、章尾钩子、证据”标签。原文块每章情节点少于该章 `min_plot_points` 或多于 30 时整批拒收。同一批完整模型结果和跨章观察写进 `_analysis_cache/批次-{范围ID}.md`，作为恢复证据；全局合并用 `manage_analysis_run.py digest` 取其跨章观察，不整批读取。模型不输出章节卡表，也不为兼容文件再次读取原文。
+
+### 批次剧情点
+
+`raw-original` 与 `existing-results` 都按范围 ID 写完整批次缓存，内容共用下列结构：
+
+```markdown
+## 跨章观察
+
+### 剧情点
+
+| 剧情点ID | 章节范围 | 起始目标 | 阻碍 | 关键选择/行动/外部事件 | 局面变化 | 得失与承担者 | 后续影响 | 状态 | 证据 |
+|---|---|---|---|---|---|---|---|---|---|
+
+### 关键事件与披露候选
+
+只列可能进入主线或关键转折表的候选：候选ID｜章节｜客观事件及大致发生顺序｜异常→线索→解释→确认的披露路径｜读者所知｜关键角色所知｜判断变化｜叙事作用｜证据。过渡动作不建条目。
+
+### 关系变化
+
+| 关系ID | 主体 → 客体 | 关系动作 | 表面/真实状态 | 触发 | 双方得失 | 变化后状态 | 证据强度 | 证据 |
+|---|---|---|---|---|---|---|---|---|
+
+### 三维节奏
+
+只列峰值、谷值与三轴明显分离处：章节/剧情点｜事件推进及理由｜情绪类型/强度及触发｜篇幅展开度｜展开/压缩/省略/反复的作用｜证据。普通章的紧凑分数不在这里重复。
+
+### 跨批状态
+
+- 已确认别名：{别名→本名，含交接批传下来的}
+- 未闭合剧情点：{ID、主体、目标、阻碍、最后证据}
+- 未决悬念：{读者已知和等待确认的内容}
+- 关系状态：{下一批需继承的有向状态}
+- 待核事项：{冲突、C暂定或缺失}
+```
+
+剧情点回答“目标 → 阻碍 → 改变局面的行动或外部事件 → 得失 → 后续影响”。它可以跨章和跨读取批次，不能把每个处理批次直接当成剧情点。跨批未闭合时沿用剧情点 ID；Stage 3 再做合并、拆分和边界复核。
+
+### 已有成果二次提取
+
+`existing-results` 的证据只指向只读计划列出的旧成果文件。完整旧项目增强时用 `<!-- REUSED_CHAPTERS:{起章}-{止章} -->` 声明覆盖，只写批次剧情点及关联观察。计划列出的摘要缺口落在本批时，必须为本批每章从黄金三章生成同一紧凑章块（情节点至少 1 个），否则摘要永远补不上；提交脚本只补缺失文件。旧资料没有的字段写“旧资料未提供”。
+
+每个成功批次由 `manage_analysis_run.py commit` 先写完整缓存、再补缺失摘要、最后写 `_progress.md` 状态行。没有逐文件收据、checkpoint 账本或 Stage receipt。
+
+**Stage 2 输出自检**：输入模式与 `manage_analysis_run.py plan` 的内存计划一致｜原文章节块连续、不重叠且不超过3章/25,000字符｜已有成果模式没有读取原文｜每章紧凑字段完整｜情节点不少于 `min_plot_points`、最多 30、按时序、白描客观｜剧情点包含因果与得失｜只保留关键事件/披露候选｜三维节奏分别解释｜跨批状态可继续。