@oh-story/dsh 0.1.9 → 0.1.11

package/lib/oh-story/skills/story-long-analyze/references/author-facing.md

@@ -0,0 +1,252 @@
+# 写给作者看的话
+
+拆文的读者是网文作者，不是工程师。作者会看到的东西有两类：对话里的回复（进度、停下来问、拆完汇报、出错说明），和落盘给人读的文件（`快速预览.md`、`拆文报告.md`、`人物关系图/人物关系图.md`）。这两类都按本文件写；本文件代码块里的内容就是作者会看到的原样，守卫脚本会检查代码块里有没有工程词。
+
+## 总规则
+
+1. **说书，不说系统**：讲这本书、这几章、读者的感受和作者能怎么用。进度用「拆到第几章 / 共几章」，不说阶段编号、批次或命令。
+2. **不出现工程痕迹**：脚本名和命令、JSON 字段名（如检查器和计划器输出里的分类、推荐路径、阶段修复、最终状态）、状态值、批次编号、内部文件（运行进度、缓存、机械章节表）、hash、质量指标名（置信度、覆盖率、重叠率）、证据分级字母、「三维」这类内部口径。这些只在你自己的判断里用。
+3. **编号必须带人话名**：情绪模块卡、关系、事件的编号单独出现作者看不懂。要么只写名称，要么写成「退婚当众打脸」（情绪模块卡 EM-003）；关系写成「林远 → 苏晴：由信任到反目（第9章宗门大比）」，不写关系编号。
+4. **证据强弱说人话**：原文直接写了的直接陈述；由几处细节推出来的写「从第3、5章的细节看，大概率……」；证据不够的写「推测，待回原文核实：……」。
+5. **需要作者拿主意时**：问一个具体问题，给出推荐选项和理由，并说明不回答时按哪个默认继续。一次只问一件事。
+6. **工程细节默认不写**：作者追问或排障确实需要时，放在回复最后单独一行「（技术备注：……）」，不超过一行。
+7. 脚本输出里带 `author_message` 的，按它的意思转述给作者（可润色，不改事实、不删选项），不要贴 JSON、错误码或 `detail`。
+
+## 对话里的回复
+
+### 开头三章拆完、停下来问
+
+```text
+《{书名}》开头三章拆完了，速览写在 快速预览.md。
+
+一句话判断：{开篇靠什么抓人、主角怎么立住，一两句}。
+最值得学的一点：{最有借鉴价值的写法，一句}。
+
+要继续把后面 {剩余章数} 章也拆完吗？我建议{继续 / 只拆第 X–Y 章这一段 / 到此为止}，因为{理由}。
+继续的话我每次同时拆三段，比一段段按顺序拆快两三倍，段和段之间的人物称呼、没收尾的剧情在最后汇总时对齐。
+
+不回复的话我按「{推荐选项}」处理。
+```
+
+### 作者问起怎么拆
+
+拆法默认替作者定好（每次同时拆三段），不主动列选项。作者问能不能更快、更稳，或说想换拆法时，才这样解释，作者选了就换：
+
+```text
+有三种拆法：
+1. 一段接一段按顺序拆：前后章的人物称呼、没收尾的剧情都接得最稳；最慢。
+2. 每次同时拆三段（现在用的）：快两三倍；段和段之间偶尔要等全部拆完汇总时再对齐人物和剧情。
+3. 能同时拆多少就拆多少：最快；前后接续全靠最后汇总时对齐，汇总会多花些工夫。电脑或账号扛不住时我会自动放慢。
+```
+
+### 拆的过程中报进度
+
+每拆完约一成或每隔几次提交报一次，不要每批都报。
+
+```text
+《{书名}》拆到第 {已拆章} / {总章数} 章（约 {百分比}%）。
+刚拆完的这段：{这几章的看点，一句话}。
+接下来拆第 {起章}–{止章} 章。
+```
+
+某几章连续没拆成、正在缩小范围重试时，只在重试也失败后才说：
+
+```text
+第 {起章}–{止章} 章拆了两次都没成功，{原因的人话说法，如：这几章特别长 / 内容格式识别不了}。
+其余章节不受影响，我先继续往后拆；这几章{稍后单章重试 / 需要你看一下原文是否完整}。
+```
+
+### 全部拆完
+
+```text
+《{书名}》拆完了：共 {总章数} 章、约 {总字数} 万字，{全部拆完 / 第 {x}–{y} 章没拆成：{原因}}。
+
+这本书最值得学的三点：
+1. {开篇怎么钩住读者——在第几章、用了什么手法}
+2. {读者追着看的核心情绪或爽点，怎样一次次兑现}
+3. {节奏上的特点：哪里快、哪里慢、为什么这样安排}
+
+可以直接借用的套路：
+- {套路名}：{在什么场景用、怎么起效}
+- {套路名}：{……}
+
+不建议学的：{一条，附原因}
+
+去哪看：
+- 先看总报告：拆文报告.md
+- 开头三章逐章怎么写的：章节/第1-3章_深度拆解.md
+- 节奏和信息怎么一步步放出来：剧情/节奏.md
+- 读者爱看的情绪套路（可以拿去用的模块）：剧情/情绪模块.md
+- 故事主线和每段剧情：剧情/故事线.md 和 剧情/ 下的各段
+- 人物和人物关系：角色/，关系图看 人物关系图/人物关系图.md
+- 世界观和设定：设定/
+- 想模仿它的文风：文风.md
+- 查某一章发生了什么：章节/第N章_摘要.md
+
+{需要你定的：一个问题 + 推荐选项；没有就不写这一段}
+```
+
+只拆了一部分、或只补了某几个文件时，删掉用不上的「去哪看」条目，只列这次新增或更新的文件，并说清哪些是上次就有的。
+
+### 停下来或出错时
+
+先说发生了什么、对这本书有什么影响，再给出路；有选择就按总规则第 5 条问。常见情况：
+
+```text
+没找到拆文目录：
+「没找到 拆文库/{书名}，书名或路径对吗？」
+
+原文和上次拆的时候不一样了：
+「原文和上次拆的时候不一样了（{改了哪几章 / 换了文件}）。已拆好的章节不会被改动，只有改过的章会重读{上次楔子并进了第一章时加：；楔子这次也照样并进第一章}。按新原文继续吗？（推荐：继续）」
+重建后前面的章号对不上时，转述脚本给出的说明和两个选项，推荐第一个。
+
+原文里认不出章节：
+「原文里认不出章节标题（比如“第1章”“楔子”这类），能看一下原文开头的格式吗？」
+
+旧拆文的章号和这次对不上：
+（转述脚本给出的说明和选项，问作者选哪一个：开头有楔子时是三个选项，推荐「按旧章号继续」；没有楔子时是两个选项，推荐「换一个新目录」）
+
+选题决策缺栏目：
+「选题决策.md 缺「能爆的原因」这一栏，这次先不回填。想回填的话，重新做一次长篇扫榜的选题决策再回来。」
+
+关系图画不出中文：
+「{照转脚本返回的原因：当前环境不能画图片 / 这台电脑没有中文字体 / 电脑上的中文字体显示不了图里的某几个字}，关系图没做成图片，已经写成 人物关系图/人物关系图.md，用能预览 Markdown 的编辑器打开就能看到中文。」
+
+文风没生成：
+「文风这部分没生成：{缺原文 / 样本太少}。其他结果都能用；{补上原文 / 多给几章} 后我可以单独补文风。」
+```
+
+## 快速预览.md
+
+开头三章拆完后的快照，只用开头三章和全书概要里已经有的信息。`拆文报告.md` 沿用「基本信息」「黄金三章评分」两节的同名同结构，拆完后两份并存，不删快速预览。
+
+```markdown
+# 快速预览：{书名}
+
+> 根据开头三章和全书概要做的早期判断；全书拆完后以 拆文报告.md 为准。
+> 进度：开头三章已拆完，{等你决定是否继续 / 正在继续拆后面的章节}。
+
+## 基本信息
+
+书名 | 题材 | 总章数 | 总字数 | 目标平台（原书所在平台，看不出来就留空）
+
+## 黄金三章评分
+
+| 维度 | 评分（1-5） | 为什么这么打 |
+|------|------|------|
+| 开篇钩子 | | |
+| 主角塑造 | | |
+| 爽点设计 | | |
+| 世界观铺设 | | |
+| 章尾悬念 | | |
+
+## 开篇判断
+
+- 开头靠什么抓人，效果怎样；
+- 主角是怎么立住的；
+- 世界观是怎么一点点交代的；
+- 三章各自承担什么任务。
+
+## 早期可借鉴点
+
+3-5 条，每条写清「在第几章、用了什么写法、为什么有效」。
+
+## 值不值得拆完
+
+一句话建议：{继续拆完 / 重点拆某一段 / 参考价值有限}，理由：{……}。
+
+## 继续拆会得到什么
+
+逐章摘要、主线和每段剧情、节奏与信息释放、读者爱看的情绪套路、人物和设定、人物关系图、完整拆文报告、文风。
+```
+
+## 拆文报告.md
+
+全书的阅读入口。只综合已经落盘的剧情、节奏、情绪模块、角色、设定和文风结果，不为写报告重读全文，也不复制逐章摘要；细节写一句结论再指向对应文件。下列一级小节名被导入、写作和选题回填读取，保留原名。
+
+```markdown
+# 拆文报告：{书名}
+
+> 一句话：{这本书靠什么留住读者}
+> 拆到哪：全书 {总章数} 章、约 {总字数} 万字，{全部拆完 / 第 {x}–{y} 章没拆成：{原因}}。
+
+## 基本信息
+
+书名 | 题材 | 总章数 | 总字数 | 目标平台（与 快速预览.md 同结构）
+
+## 核心发现
+
+3-5 条这本书为什么好看：每条写「发现 + 在哪几章能看到 + 你写书时可以怎么用」。
+
+## 黄金三章评分
+
+与 快速预览.md 同一张五项表；「为什么这么打」一栏写一句人话理由。
+
+## 读者在追什么
+
+读者最想看的 1-3 件事、每次怎样被满足、满足之后为什么还想往下看。详细的情绪套路见 剧情/情绪模块.md。
+
+## 故事怎么推进
+
+主线和主要副线各一句。再按大段落写：主角想要什么 → 卡在哪 → 靠自己、别人还是意外翻过去 → 得到什么、付出什么 → 引出下一段的什么。每段注明章节范围，细节见 剧情/ 下的各段剧情。
+
+## 人物与关系
+
+主角、主要对手、核心配角各一两句：是谁、想要什么、在故事里起什么作用。
+关系图见 人物关系图/人物关系图.md（有图片版时在这里嵌入 人物关系图/核心人物关系.png）。
+关键关系的变化逐条写成「甲 → 乙：由……到……（第几章，因为……）」；甲保护乙、乙依赖甲这类方向不同的关系分开写。
+
+## 读者知道的和角色知道的
+
+挑几个关键秘密或真相：它实际发生在哪一章、读者在第几章知道、主要角色在第几章知道，这个时间差带来了什么悬念或爽感。详见 剧情/节奏.md。
+
+## 节奏
+
+- 事情推进：哪几段推得快、哪几段在铺垫，转折落在哪几章；
+- 读者情绪：高点在哪几章、低谷拉了多长、怎么拉回来；
+- 笔墨分配：作者在哪些场面上花大篇幅、哪些一笔带过，这样安排的效果。
+
+### 爽点密度
+
+大约每 {几章 / 几万字} 一次明显的爽点，{偏高 / 适中 / 偏低}；最长的空档在第 {x}–{y} 章，作者用{什么}撑住。
+
+## 伏笔与冲突
+
+跨章较远或影响主线的伏笔：在第几章埋下、第几章揭开、揭开时读者是什么感受。冲突怎么一级级升级，最后落到哪里。
+
+## 核心机制
+
+这本书反复使用的爽点类型、节奏套路和更新上的做法，各一两句。
+
+## 角色体系
+
+主角 / 对手 / 核心配角 / 功能性角色各有哪些人、分别承担什么戏份。
+
+## 可借鉴套路
+
+1. {套路名}：在什么场景用、怎么起效、第几章能看到（对应情绪模块卡「{模块名}」（EM-{编号}））
+2. ……
+
+## 可复现模块
+
+从 剧情/情绪模块.md 挑最值得复用的三张卡，每张写：读者想看什么、情绪链、戏剧单元、可替换项、不可照搬。
+
+## 写法技巧
+
+1. {技巧名}：怎么用、在第几章能看到。优先覆盖一笔两用、延迟揭示、视角欺骗、对比锚点、行为循环、用身体反应代替心理描写、跨章回扣（同一件物品或意象在不同章节承担不同作用）。
+
+## 不建议模仿
+
+1. {问题}：{为什么不建议、写的时候怎么避开}
+
+## 文风一句话
+
+{句子长短、对话习惯、情绪起伏的特点}；详细见 文风.md。
+
+## 还不确定的地方
+
+- 没拆到的章和原因；
+- 原文没有直接写、靠推测得出的结论（写成「推测：……，依据：第几章……」）；
+- 没能生成的内容和原因（照转脚本给的原因，例如不能画图片或缺中文字体时关系图只有 Markdown 版）；
+- 值得回原文再核一下的地方。
+```

package/lib/oh-story/skills/story-long-analyze/references/deconstruction-notes.md

@@ -1,5 +1,5 @@
 # 长篇拆文参考
-拆书方法论、结构设计、卖点循环、题材实战要点的速查手册。配合 SKILL.md 和 `material-decomposition.md` 使用。
+拆书方法论、结构设计、卖点循环、题材实战要点的速查手册。配合 SKILL.md 与各 Stage 的规则文件使用。
 
 ## 管道阶段映射
 
@@ -7,12 +7,12 @@
 |-----------|-------------|------|
 | 核心情绪控制 | Stage 1（黄金三章）| 判断开篇情绪是否到位 |
 | 题材边界与核心梗 | Stage 0（概要提取）| 识别题材类型和核心梗 |
-| 拆书方法论 | Stage 1-2（三章+逐章）| 拆解视角和提取方法 |
+| 拆书方法论 | Stage 1-2（三章+连续章节块）| 拆解视角和提取方法 |
 | 结构设计与节奏 | Stage 3（聚合分析）| 节奏地图和情绪曲线构建 |
 | 卖点循环设计 | Stage 3（聚合分析）| 爽点循环模式识别 |
 | 桥段词表 | Stage 3（聚合分析）| 给剧情模块打桥段标签 |
 | 经典作品拆解 | Stage 1-2 | 对标拆解参考框架 |
-| 拆书实操技巧 | Stage 2（逐章摘要）| 情绪折线图、期待分析 |
+| 拆书实操技巧 | Stage 2（连续章节块提取）| 情绪折线图、期待分析 |
 | 对标书选择 | Stage 0（概要提取）| 确定拆解对象 |
 | 抽象拆书法 | Stage 3（聚合分析）| 三幕式结构归纳 |
 | 影视拉片与情绪控制 | Stage 2-3 | 情绪曲线精细化分析 |

package/lib/oh-story/skills/story-long-analyze/references/final-checks.md

@@ -0,0 +1,19 @@
+# 收尾检查与维护者回归
+
+全部拆完（或本次要拆的一段拆完）的时刻读本文件的「收尾检查」；「维护者回归」只在改动本 skill 时用。
+
+## 收尾检查
+
+检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
+
+- 再运行检查器和计划器；完整项目应 `direct_use`，继续意图应无待处理批次；
+- 对比受保护路径 hash：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md`、`拆文报告.md` 不得被增强或恢复流程改写；
+- 允许变化的旧项目文件只有 `_progress.md` 受管状态区和 `_analysis_cache/` 新证据；
+- 检查旧 `schema_version` 原值；
+- 检查新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取。
+
+## 维护者回归
+
+改动本 skill 后必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 schema。报告未执行的真实模型或跨平台检查，不得用静态 fixture 冒充。
+
+联合验收用 [semantic-acceptance-fixtures.md](semantic-acceptance-fixtures.md) 的六项 0–2 分表，真实模型结果至少 10/12 且无硬失败才算语义通过。

package/lib/oh-story/skills/story-long-analyze/references/index-rebuild.md

@@ -0,0 +1,11 @@
+# 原文变化与章号对不上
+
+`build_chapter_index.py` 因原文变化非零退出，或返回 `chapter_mapping_ambiguous`、`index_would_shrink` 时读本文件；把脚本的 `author_message` 按 [author-facing.md](author-facing.md)「停下来或出错时」转告作者。
+
+同源索引直接复用且不重写。原文变化时先非零退出；人工确认后加 `--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` 只沿用已有索引的口径，不能用来改口径。

package/lib/oh-story/skills/story-long-analyze/references/inspiration-library.md

@@ -0,0 +1,105 @@
+# 三层灵感库管道
+
+story-long-analyze 的可选后置管道：把 Stage 3 已抽象好的 EM 机制卡组织成可跨书检索的机制资产。不重新拆文，不写新故事；**单书拆文不自动入库**——只在用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时运行。
+
+## 复用优先（第一原则）
+
+机制与案例分析在拆文主管道已完成一次：`剧情/情绪模块.md` 的 EM 卡是机制全文的**唯一维护点**，剧情单元是案例的唯一维护点。本管道只做登记（IA）、单书归并（NM）、跨书聚合与打标（CBA），任何一层都**不复制** EM 卡正文；卡内引用一律用 `书名/EM-xxx` 式裸 ID，需要读原文时按 ID 经 `灵感索引.csv` 回查（或用 `resolve` 子命令），禁止在卡里堆路径链接——`validate` 会机械拒绝。
+
+## 输入边界
+
+只读：各书 `剧情/情绪模块.md`（EM 完整卡＋其他机制索引）、按 EM 卡「关联节奏/证据来源」定点查证的 `剧情/节奏.md` 与剧情单元、现有 `灵感库/灵感索引.csv` 与 NM/CBA 卡。
+
+**禁止读取 `原文/`、`chapter_index.csv` 与逐章摘要正文。** 一本书没有 `剧情/情绪模块.md` 或完整卡字段不全时，停止并返回 `repair_action`：先用 `--intent enhance` 补跑 Stage 3+（从既有摘要聚合，原文读取可为 0），不得在灵感层代写机制卡。原文追加或局部变化后，主管道 rebuild 并更新 EM 卡，再重跑登记即可（幂等）；`validate` 的 `ia_em_set_mismatch` 会指出未重登记的书。
+
+## 公共目录
+
+从当前工作区向上定位最近的现有 `灵感库/`；没有时在工作区根创建：
+
+```text
+灵感库/
+├── 灵感索引.csv                      # 三层统一索引，也是 ID → 位置的唯一解析表
+├── 单小说灵感合并/{书名}/NM-001.md    # 仅在确有合并时创建
+└── 跨书灵感聚合/CBA-001_{机制名}.md
+```
+
+- 原子灵感 = Inspiration Atom，ID `IA-001`。**只是索引行，没有文件**——对一张 EM 卡的登记，编号镜像 EM 编号。
+- 单小说灵感合并 = Single-Novel Merge，ID `NM-001`。
+- 跨书灵感聚合 = Cross-Book Aggregation，ID `CBA-001`。
+
+## 管道三步
+
+### 1. 原子灵感登记（确定性机械步骤）
+
+```text
+{PYTHON} "{story-long-analyze skill 根}/scripts/inspiration_index.py" register-atoms --root "{灵感库}" --module "{拆文目录}/剧情/情绪模块.md" --book "{书名}"
+```
+
+- 完整卡（读者想看什么/情绪链/戏剧单元/可替换项/不可照搬 五字段齐）登记为 `grade=full`；「其他机制索引」条目登记为 `grade=index`。
+- 五字段缺失报 `em_fields_missing`，字段在而值空报 `em_field_value_empty`（多行值合法：值可写在字段名行之后、下一个字段/标题之前的列表或段落里）。机制字段（标题/读者想看什么/情绪链/戏剧单元/可替换项）的专名检查分两级：本卡「不可照搬」已点名该词却仍在抽象字段使用、或 `可替换项` 写成「专名→任意X」（报 `replaceable_antipattern`），都是高置信真引用，报 `source_specific_name_in_mechanism` error；仅角色卡文件名子串命中而无佐证的降为 `leak_suspect` warning 并列出命中字段，人工复核。都指回 Stage 3 修复；「不可照搬」字段本身例外——点名原书专名正是它的职责。
+- 泄漏门的角色名单取自工作区 `拆文库/{书}/角色/`。工作区从 `--root` 向上探测含 `拆文库/` 的目录，探测不到报 `workspace_not_located`（可加 `--workspace` 显式指定），不得回退空名单静默通过；输出恒带 `character_roster` 数，书目录在而 `角色/` 缺失报 `character_roster_missing` warning，提示人工确认无专名。
+- 所有卡的所有问题一次收集报全（`errors` 数组），有任一 error 即整体不写盘。落盘 `剧情/情绪模块.md` 后先用只读的 `check-atoms`（与 register-atoms 同参数）自检：输出卡数、索引数、名单规模与全部问题，不写任何文件。
+- 一次原子写入、重跑逐字节幂等；多本书逐本串行登记，不要并行跑 `register-atoms`。`--module` 必须是 `拆文库/{--book}/` 下的文件（`module_book_mismatch`）；卡头须为 `### EM-xxx 名称`，缺名称报 `em_title_missing`，认不出的 EM 标题行报 `em_header_unrecognized`，同卡重复字段报 `em_field_duplicate`——三者都意味着卡被截断或并进了上一张。本步不得调用模型重新概括机制。
+
+### 2. 单小说灵感合并
+
+只在一本书内确有 ≥2 张 EM 卡同构时创建 NM；孤立机制不建 NM。卡内容是**合并增量**，机制链不抄写：
+
+```markdown
+# NM-001：{簇名}
+
+- 合并对象：EM-001、EM-003
+- 合并理由：{为何同构，一两句}
+- 差异形态：{各卡触发物/场合/规模的不同}
+- 本书特有偏置：
+- 共同反例/边界：
+```
+
+### 3. 跨书灵感聚合
+
+把各书 IA/NM 与现有 CBA 轻量索引比较，只读可能匹配的 active CBA。已建库后的增量先跑只读的 `coverage`：它列出尚未进入任何 active CBA 闭包的原子与现存单书假设卡——聚合比较只对 uncovered 原子做，顺带复核单书假设卡是否因新证据升级为「跨书重复验证」；uncovered 为空即无事可做，不重读已覆盖的 EM 卡。CBA 是**唯一供写作反复读取的卡**，必须自包含跨书归纳的抽象（聚合新产出，不是 EM 原文复制）：
+
+```markdown
+# CBA-001：{机制名}
+
+- 验证状态：{单书假设/跨书重复验证}
+- 来源：{甲书/EM-001、甲书/NM-002、乙书/EM-003}（溯源按 ID 查 灵感索引.csv 或用 resolve）
+
+## 共同机制链
+{触发 → 读者认知/情绪变化 → 持续阅读动力 → 兑现}
+
+## 可变参数
+- 人物功能位：／关系动作：／冲突载体：／兑现规模：／节奏位置：
+
+## 可能适用于
+- 题材：／读者需求：／情绪：／关系动作（可空）：／剧情功能：／节奏位置（可空）：／适用阶段：／风险：
+
+## 条件、反例与边界
+- 成立条件：／反例：／不可照搬：／误用风险：
+```
+
+`novel_count`/`atom_count` 不手写进卡——由索引 `source_ids` 闭包自动核算并校验。只有一部书支持时，最多激活 3 张最有写作复用价值的 CBA 并标 `单书假设`；两部及以上独立来源才标 `跨书重复验证`。标签只表达适用性，一本书来源不能写成市场定论。
+
+## 索引与受控标签
+
+`灵感索引.csv` 表头严格为：
+
+```csv
+item_id,layer,title,source_book,path,source_ids,novel_count,atom_count,grade,tags,status
+```
+
+- IA 行 `path` 为空、`grade` 取 `full/index`；NM/CBA 行 `grade` 留空；IA/NM 的 `tags` 留空，避免写作绕过聚合层。
+- `source_ids` 来源图：IA 行＝单个 `EM-xxx`；NM 行＝同书 ≥2 个 `EM-xxx`（`|` 分隔）；CBA 行＝`书名/EM-xxx` 与 `书名/NM-xxx` 混合列表（必须带书名前缀）。引用 NM 时其成员 EM 自动并入闭包，**不需要也不应该再展开列出**；`novel_count`＝闭包内不同小说数，`atom_count`＝闭包内不同 EM 数。
+- 标签序列化为 `轴=值1|值2；轴=值`。CBA 必填轴：题材、读者需求、情绪、剧情功能、适用阶段、风险；可选轴：关系动作、节奏位置。同义值先归一；不用「好看/有趣/高级」等不可执行词。
+- **标签值受控于库内 `灵感库/标签词表.md`**（每轴一节 `## 轴`、一行一值 `- 值`）：建库首轮聚合把用到的值落盘成首版，此后打标先读词表。扩表走同义判定——候选新值逐一与该轴现有值语义比对，重合或从属就用现有值，确属新维度才追加一行；词表膨胀就是查询失效的前兆。query 命中靠值的精确匹配，写入侧与查询侧共用这一张表。
+- `validate` 校验：表头、ID 前缀、EM↔IA 集合一致、NM/CBA 闭包与计数、必填标签轴、单书 active CBA ≤3、验证状态标记、**卡内无路径引用**；词表存在时另拒表外值（`tag_value_not_in_vocabulary`）与缺必填轴的词表（`vocabulary_axis_missing`）——词表缺失时这两项不查（旧库兼容），应尽快补建；同义值靠扩表时的人工比对，不做机械子串判定。列数不对的索引行报 `column_count_mismatch`。
+- `query --tag 轴=值 …` 只筛 `layer=跨书灵感聚合` 且 `status=active`，核心轴（题材/读者需求/情绪/剧情功能/适用阶段）2 分、其余 1 分，无核心轴命中不返回，按分数/来源数/ID 稳定排序取 Top 3–8。返回值另带 `unmatched_tags`（请求值在全库该轴零出现）与 `axis_inventory`（所查各轴现存值）：零命中先按它们纠词重查一次，仍零命中才算「库里没有」。
+- `resolve --ref 书名/EM-xxx --ref CBA-001` 把裸 ID 解析为可读位置——需要时才查，不预先展开进任何卡。
+
+## 写作侧消费约定
+
+写作模块只读标签命中的 active CBA 全卡（Top 3–8），不沿来源下钻 EM/NM；CBA 不作文风样本，也不触发原文读取；同一 CBA 最多派生 2 个候选变化。消费入口只在 story-long-write 的开书、卷纲、细纲三处（适用阶段=设定/卷纲/细纲）；逐章写前召回和写手 prompt 不读灵感库，灵感经细纲进入正文。
+
+## 断点与禁止事项
+
+不设进度文件——索引与卡片现状就是状态；中断后重跑登记（幂等），用 `validate` 报错清单定位未完成层。禁止：回读原文、二次逐块语义分析、任何层复制 EM 卡机制全文、卡内路径链接、自动生成故事种子/角色组合/成稿桥段、复制原作专名与原句（跨书层连角色名都不得出现）、为凑数硬并语义不同的机制。

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

@@ -1,80 +1,154 @@
-# 管道运维参考
-
-story-long-analyze 拆解管道的运维工具文档：`_progress.md` 模板、错误处理、恢复机制操作步骤。
-
-> 质量阈值（置信度 / 覆盖率 / 重叠率）见 [material-decomposition.md 质量阈值体系](material-decomposition.md)。
-
----
-
-## _progress.md 模板
-
-```markdown
-# 深度拆解进度：{书名}
-- 小说：{标题} | 总章数：{N} | 输出目录：{路径} | 开始：{日期}
-- 最终状态：{pending/paused_after_stage1/completed/completed_with_errors}
-- schema_version: 2
-## 管道进度
-| 阶段 | 状态 | 进度 | 备注 |
-|------|------|------|------|
-## 章节边界（Stage 0 章节边界子步骤产物，唯一权威）
-| 章号 | 标题 | 起始行 | 字数 |
-|------|------|--------|------|
-## 分块进度
-| 块 | 章节 | 状态 |
-## 失败记录
-| 类型 | 章节/阶段 | 错误信息 | 重试状态 |
-|------|----------|---------|---------|
-## 质量检查
-| 检查项 | 阶段 | 结果 | 修正 |
-## 角色合并
-| 合并前 | 合并后 | 依据 | 确认 |
-## 断点
-- 最后处理：第{N}章 | 当前阶段 | 下一操作
+# 长篇拆文运行、提交与恢复
+
+## 唯一状态与三个脚本
+
+生产运行只使用：
+
+1. `build_chapter_index.py`：建立机械章界和逐章原文 hash；
+2. `inspect_existing_assets.py`：只读识别旧成果、当前成果、缺章和修复阶段；
+3. `manage_analysis_run.py`：只读计划，并负责批次提交、拆分、恢复和阶段标记。
+
+Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人物关系图，不参与运行状态。
+
+脚本输出只给你看。失败或需要作者决定时，脚本会带 `author_message`（大白话说明和选项），按 [author-facing.md](author-facing.md) 转述给作者；不要把 JSON、错误码或下文的分类、路径名原样贴给作者。
+
+`chapter_index.csv` 是机械章节边界唯一真源。批次和阶段状态只写在 `_progress.md` 的
+`story-long-analyze:runtime-state` 受管区。`_analysis_cache/` 保存完整结果和恢复证据，不承担状态库功能。
+
+既有项目中的 `schema_version: 2` 沿用且不修改；该值只供报告，不用于否定旧成果。`_progress.md` 不再保存机械章节边界镜像。
+
+禁止创建 `run-plan.json`、`batch-checkpoints.json`、逐批 JSON receipt 或 Stage receipt。计划始终打印到标准输出，由当前运行直接消费。
+
+所有命令使用实际 Python 与 skill 根路径：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/{脚本名}.py" ...
+```
+
+## 1. 先检查目录
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/inspect_existing_assets.py" --root "{拆文目录}" --compact
+```
+
+- 路径不存在、不是目录或不可读：非零退出，先修正路径。
+- 已存在的空目录：`empty / new_analysis`。
+- 完整旧项目：`direct_use`，不建索引、不读原文。
+- 部分项目：精确报告 `missing_semantic_chapters` 与 `missing_summary_chapters`。
+- 新旧投影混存：`mixed_sources: true` 并列明逐章来源，仍可直接使用完整项目。
+- `schema_version` 只报告，不参与否定旧项目，也不在检查或复用时改写。
+- `stage_repairs` 中的情绪、节奏和文风修复与 Stage 2 缺章分开处理。
+
+## 2. 需要原文时建立或校验索引
+
+完整旧成果默认直接使用和纯旧成果增强无需索引。全新或部分完成才运行：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" \
+  --source "{拆文目录}/原文/原文.txt" \
+  --output "{拆文目录}/chapter_index.csv" \
+  --locator-path "原文/原文.txt"
+```
+
+脚本只按 LF 计算物理行号，支持楔子、序章、第0章、任意正文起始章、番外、后记、多卷和中文大数。CSV 保存内部连续号、来源章号、卷、标题、行界、字符数、`chapter_sha256`、全源 hash 和解析器版本。
+
+同源索引直接复用且不重写。原文变化、重建后章号对不上或旧成果章号对不上时，按 [index-rebuild.md](index-rebuild.md) 处理。
+
+## 3. 生成只读计划
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" plan \
+  --root "{拆文目录}" \
+  --intent continue
+```
+
+意图：
+
+- `continue`：补缺失语义章，以及缓存失效的已记录批次；已有语义但缺摘要时用旧成果投影；
+- `enhance`：只读既有拆文成果形成 `REUSE-{起章}-{止章}` 批次，原文读取数必须为 0。
+
+没有“整本重拆”意图：已有摘要永不覆盖。整本重拆就换一个新目录重新拆。
+
+逐批派发时加 `--next 1` 只取下一批，确认进度用 `--next 0` 只看 `remaining_batches` 与压缩成区间的 `summary_gaps`；全量计划每批约五百字符，整本书反复全量输出会白占主会话上下文。不带 `--next` 时输出全部批次。
+
+作者只要拆某一段时加 `--chapters 起-止`（可与 `--next` 同用）：只规划这段里的批次，`remaining_batches` 只数这段，`summary_gaps` 仍是全书。这段拆完即停，不标 `stage2`；按 author-facing「全部拆完」只汇报这一段，再问作者是否接着拆其余章节。
+
+计划只存在内存和标准输出，`state_written` 必须为 `false`。每块最多 3 章、25,000 字符，同一章不能出现在两个原文块；计划原文读取数为 0 时不得派发原文任务；批次 ID 直接使用章节范围。`RAW` 只覆盖缺失章和缓存失效批次，`REUSE` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
+
+## 4. 执行与提交一个批次
+
+`chapter-extractor` 只处理计划中一个批次。**主会话不中转内容**：原文和批次结果都不经过主会话上下文。派发时照抄计划里这一批的字段，路径前加 `{拆文目录}/`，不另选、不推算：
+
+- `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 这份输入文件**，直接提交；提交被拒时重新派发同一批：上面的字段原样再给一遍（子代理补内容要按 `source_locator` 回看原文、按 `min_plot_points` 补情节点），再附错误码，让它用 Edit 只改出错处后再提交（结构整体错乱才整份重写）。提交成功后删掉这份输入。不论哪种派发方式，`commit` 都由主会话逐个执行，不并发跑。
+
+**派发方式**：默认第 2 档有限并行，不请作者在三档里选。作者问起能不能更快或更稳、或明确要求时，才按 author-facing「作者问起怎么拆」用白话解释并切换。三档都用计划给的 `handoff_cache`，它随提交进度自动落到对应的批次上。
+
+1. **串行**：上一批提交成功再派下一批，交接缓存就是紧邻的前一批。优点：剧情点、未决悬念和已确认别名逐批完整接续，Stage 3 合并最省事。缺点：最慢，墙钟时间随批数线性增长。
+2. **有限并行**：每轮同时派 3 批，同轮的交接缓存都是本轮开始前最近一个已提交批次；整轮提交完再派下一轮。优点：约快两到三倍，接续最多滞后一轮。缺点：同轮批次互相看不到对方新建的剧情点与别名，边界处可能重复建 ID，靠 Stage 3 跨块合并收拢。
+3. **不限批次顺序**：不等前批，同时在跑的子代理最多 12 个（宿主或账号上限更低时以环境为准）；在跑的少于上限一半时，补派到上限。补派用 `plan --next {在跑数＋补派数}`，跳过已在跑的批次号（计划只认已提交）。遇到限流、超时或子代理报错，把上限减半后再补派。优点：最快。缺点：接续最弱，剧情点与别名最依赖 Stage 3 跨块合并和 Stage 4 归并；并发越高，被限流、整批重跑的风险越大。
+
+作者没提、要求一次拆完 / 全量拆、多本书一起拆，或由 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 \
+  --root "{拆文目录}" \
+  --input "{拆文目录}/_analysis_cache/输入-RAW-4-6.md" \
+  --batch-id "RAW-4-6" \
+  --range-sha256 "{plan 输出值}" \
+  --source-file "{plan 列出的来源}"
 ```
 
-**schema_version 说明**：
+`REUSE` 批次不传 `--range-sha256`。完整增强可以只输出 `REUSED_CHAPTERS` 与跨章观察；需要补摘要时输出同一套紧凑章节块。
+提交入口会再次检查 3 章与 25,000 字符上限；单个超长章仍允许独占。
 
-| 版本 | 含义 |
-|------|------|
-| 2 | 当前契约：含「章节边界」表（Stage 0 章节边界子步骤产物）。Stage 1/2/6 全部以该表为切片真值，不再各自跑 regex |
+提交顺序固定：
 
-缺少 `schema_version: 2` 或「章节边界」表时不得续跑；从 Stage 0 章节边界子步骤重建 `_progress.md` 后再恢复。
+1. 在写文件前校验整批范围、标记、所有紧凑字段和情节点（原文块每章不少于 `min_plot_points`、最多 30，否则整批拒收；编号连续、每点带主题标签与基调行）；
+2. 对 `RAW` 再算当前范围 hash，与计划值不一致就拒绝；
+3. 原子写入含完整模型输出和最终结束标记的批次缓存；
+4. 只创建缺失的 `章节/第N章_摘要.md`，任何已有摘要都保留，并在结果的 `kept_existing_summary_chapters` 里列出；摘要投影把每个情节点的主题、基调和类型映射到固定枚举（主题/基调映射不上写“其他”），保留“关键事件”“情节点”“涉及”“基调”等旧消费者字段；
+5. 最后更新 `_progress.md` 受管批次表为 `completed`；有阶段记录时按 Stage 3–6 状态重写受管区的 `最终状态`（旧项目改写原有行，不写第二行）。
 
-**最终状态值说明**：
+每条成功行记录章节范围、输入类型、原文范围 hash、状态和缓存路径。受管区外的 BOM、换行、作者备注及既有 `schema_version` 必须逐字节保留。
 
-| 状态值 | 含义 |
-|--------|------|
-| `pending` | 管道进行中，尚未跑完 |
-| `paused_after_stage1` | Stage 1 停靠点暂停——Stage 0/1 已完成，已产出 `快速预览.md`，等待用户决定是否继续 Stage 2-6。续跑时跳过 Stage 0/1，从 Stage 2 开始 |
-| `completed` | 全管道 Stage 0-6 完成 |
-| `completed_with_errors` | 全管道完成，但有单章/单阶段失败（详见「失败记录」表，拆文报告中注明） |
+## 5. 失败、拆分和重试
 
----
+模型输出不完整时不提交。批次过大或连续失败时：
 
-## 剧情单元清单补建（存量书）
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" split \
+  --root "{拆文目录}" --batch-id "RAW-4-6"
+```
 
-触发：用户说「补剧情单元清单」，或写作侧检索发现 `剧情/README.md` 无「剧情单元清单」表。
+也可用 `--at 4` 指定左右边界。脚本在同一个 `_progress.md` 受管区把父块记为 `superseded`，写入两个相邻子块。重新运行 `plan` 后继续使用子块，不会按位置编号覆盖旧记录，也不会把子块重新合成父块。
 
-动作：读存量 `拆文库/{书名}/剧情/*.md`（或 `对标/{书名}/剧情/*.md`）各剧情单元表头的 标题 / 类型 / 桥段标签 / 章节范围 字段，按 output-templates.md「剧情单元清单」表模板机械重建 `剧情/README.md` 的清单表；项目 `对标/{书名}/` 视图存在时同步一份。不读原文、不重跑任何 Stage、不改剧情单元内容、不动 `节奏.md` / `情绪模块.md`。旧剧情单元「章节范围」行没有字数信息时，体量列只写「共{N}章」、字数记「未知」，不得编造。
+## 6. 中断恢复
 
-写作侧消费点对无清单的书自动回退逐文件检索（见 story-long-write 的 outline-structure-theory.md「对标节奏迁移」步骤 1），补建只是加速，不是阻塞项。
+先重新运行 `plan`。已满足以下三项的成功批次不会出现：
 
-## 错误处理
+1. 范围内摘要都存在；
+2. 批次缓存完整，最后一个非空标记为 cache end；
+3. `RAW` 状态行的范围 hash 等于当前索引计算值。
 
-| 场景 | 处理 |
-|------|------|
-| 章节识别失败 | 提示确认格式；支持自定义正则 |
-| 分块中断 | 读 _progress.md 断点恢复 |
-| 聚合质量不达标 | 孤立情节二次分类；阈值放宽至 0.5 |
-| 角色合并冲突 | 记录待确认列表 |
-| 输出目录冲突 | 追加不覆盖；冲突标 `[重新分析]` |
+如果缓存已完整，但摘要或进度最后一步尚未落盘：
 
----
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" repair-progress --root "{拆文目录}"
+```
+
+恢复只从完整、范围 hash 有效的缓存补缺失摘要并更新状态；不覆盖用户修改过的文件。缓存缺结束标记或范围 hash 失效时报告错误并重跑相应批次。
+
+## 7. 阶段标记与后续时刻
 
-## 恢复机制操作步骤
+Stage 1 黄金三章与快速预览落盘后标 `stage1`；计划不再有批次、全部摘要落盘后标 `stage2`：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage --root "{拆文目录}" --stage stage2
+```
 
-1. 管道启动时检查输出目录是否已有 `_progress.md`
-2. 校验 `schema_version: 2` 与「章节边界」表；任一缺失即停止，并提示从 Stage 0 章节边界子步骤重建进度文件
-3. 读取断点信息（最后处理章节 + 当前阶段 + 最终状态）
-4. **断点状态为 `paused_after_stage1`**（Stage 1 停靠点）→ 跳过 Stage 0/1，直接从 Stage 2 续跑逐章摘要，不重跑已完成的概要与黄金三章
-5. 其他断点状态 → 从断点所在块的起始章节恢复，覆盖该块已有输出
+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)。