@oh-story/dsh 0.1.15 → 0.1.17

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

@@ -1,19 +1,11 @@
-# 收尾检查与维护者回归
+# 收尾检查
 
-全部拆完（或本次要拆的一段拆完）的时刻读本文件的「收尾检查」；「维护者回归」只在改动本 skill 时用。
+全书或本次指定范围拆完后执行。检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
 
-## 收尾检查
-
-检查全部通过后，按 [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 且无硬失败才算语义通过。
+- 再运行检查器和计划器：完整项目应 `direct_use`；`continue` 在本次指定范围内无待处理批次；
+- 完整管道及其续跑确认「文风一句话」已根据 `文风.md` 补齐；单独补旧项目文风时保留已有报告；
+- 检查受保护路径：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md` 不得被常规增强或恢复流程改写；明确请求重建文风、主报告或修情绪模块卡时，按各自的说明处理；
+- 常规增强与恢复只补缺失产物、新证据和 `_progress.md` 受管状态区；
+- 旧 `schema_version` 原值未变；
+- 新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取；
+- 找到过 `选题决策.md` 时，确认回填只改了题材匹配的选题那一行。

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

@@ -2,10 +2,16 @@
 
 `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` 遇到已建好的错位索引同样拒绝。作者的三个选择：
+原文未变时直接复用索引。原文变化后脚本先非零退出，作者确认继续后再加 `--rebuild`。重建沿用已有索引的章号口径：已有索引第 1 章是正式章节、而原文开头有楔子/序章/第0章（即上次用了 `--fold-prologue`），自动照样并入，无需再加参数；重建出的前面各章与已有索引对不上（`chapter_mapping_ambiguous:position=N` 或 `index_would_shrink`）时不写索引，返回 `author_message`。追加新章时旧章 hash 保持稳定，输出仅列出新增或内容变化的 `pending_chapters`。
 
-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 按新章号重拆。旧库只拆到黄金三章时代价最小。
+改动已拆章节的原文只会让覆盖它的批次缓存失效、下次计划重读该批；已有摘要不刷新——要刷新哪章就删掉哪章的 `章节/第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

@@ -1,16 +1,18 @@
 # 三层灵感库管道
 
-story-long-analyze 的可选后置管道：把 Stage 3 已抽象好的 EM 机制卡组织成可跨书检索的机制资产。不重新拆文，不写新故事；**单书拆文不自动入库**——只在用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时运行。
+story-long-analyze 的可选后置管道：把 Stage 3 已抽象好的 EM 机制卡组织成可跨书检索的资料。不重新拆文，不写新故事；**单书拆文不自动入库**——只在用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时运行。
 
 ## 复用优先（第一原则）
 
-机制与案例分析在拆文主管道已完成一次：`剧情/情绪模块.md` 的 EM 卡是机制全文的**唯一维护点**，剧情单元是案例的唯一维护点。本管道只做登记（IA）、单书归并（NM）、跨书聚合与打标（CBA），任何一层都**不复制** EM 卡正文；卡内引用一律用 `书名/EM-xxx` 式裸 ID，需要读原文时按 ID 经 `灵感索引.csv` 回查（或用 `resolve` 子命令），禁止在卡里堆路径链接——`validate` 会机械拒绝。
+机制与案例分析在拆文主管道已完成一次：`剧情/情绪模块.md` 的 EM 卡是机制全文的**唯一维护位置**，剧情单元是案例的唯一维护位置。本管道只做登记（IA）、单书归并（NM）、跨书聚合与打标（CBA），任何一层都**不复制** EM 卡正文；卡内来源引用使用裸 ID；跨书引用带书名前缀，如 `书名/EM-xxx`，需要读原文时按 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` 会指出未重登记的书。
+**禁止读取 `原文/`、`chapter_index.csv` 与逐章摘要正文。** 入库前先对每本书跑一次只读检查器（SKILL.md「Phase 1」），看 `classification`、`current_capabilities`、`conflicts` 和覆盖范围。缺 `剧情/情绪模块.md` 或完整卡字段不全（`check-atoms` 报 error）时停下，请作者回拆文主流程：缺文件补 Stage 3，卡不全按 SKILL.md「Phase 2」末段修卡，都不读原文；不得在灵感层代写机制卡，也不得把旧资料概括成伪造的主产物。原文追加或局部变化后，先由主管道重建索引、补齐分析，并按请求更新 EM 卡，再重跑登记；`validate` 的 `ia_em_set_mismatch` 会指出未重登记的书。
+
+各层引用拆文产物的约定：单书案例以 `剧情/*.md` 的剧情单元为准，可迁移机制以 `剧情/情绪模块.md` 的 `EM-*` 为准，`拆文报告.md` 只是阅读入口，不作第二份事实来源。客观事件、披露节点和三维节奏分别用 `EV-*`、`RV-*`、`AX-*`，机制卡通过 ID 引用，不跨层复制全文。
 
 ## 公共目录
 
@@ -36,14 +38,25 @@ story-long-analyze 的可选后置管道：把 Stage 3 已抽象好的 EM 机制
 ```
 
 - 完整卡（读者想看什么/情绪链/戏剧单元/可替换项/不可照搬 五字段齐）登记为 `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`——三者都意味着卡被截断或并进了上一张。本步不得调用模型重新概括机制。
+- 先用只读的 `check-atoms`（与 register-atoms 同参数）自检：输出卡数、索引数、角色名单规模与全部问题，不写文件。所有卡的问题一次报全，有任一 error 就整体不写盘。
+- 一次原子写入、重跑逐字节幂等；多本书逐本串行登记，不要并行跑 `register-atoms`。本步不得调用模型重新概括机制。
+- 专名检查的角色名单取自 `拆文库/{书}/角色/`；从 `--root` 向上查找含 `拆文库/` 的工作区，输出恒带 `character_roster` 数。
+
+报错处理：error 都回 Stage 3 改 `剧情/情绪模块.md` 再登记，warning 由人工复核。
+
+| 报错 | 意思 | 怎么修 |
+|---|---|---|
+| `em_fields_missing` / `em_field_value_empty` | 五个必填字段缺失或值空 | 补齐；表格写法把整段值写进格子，`- **字段**：` 列表写法的值可以接在字段名行之后多行写 |
+| `em_title_missing` / `em_header_unrecognized` / `em_field_duplicate` | 卡头不是 `### EM-xxx 名称`、标题行认不出、同卡字段重复 | 多半是卡被截断或并进了上一张，按模板重写卡头 |
+| `source_specific_name_in_mechanism` / `replaceable_antipattern` | 本卡「不可照搬」点名的专名又出现在标题、读者想看什么、情绪链、戏剧单元或可替换项里，或可替换项写成「专名→任意X」 | 改成功能位；「不可照搬」字段本身点名专名是它的职责，不算 |
+| `leak_suspect`（warning） | 只是角色卡文件名子串命中，没有佐证 | 人工看命中字段，确认不是专名就保留 |
+| `character_roster_missing`（warning） | 书目录在但没有 `角色/` | 人工确认卡里没有专名 |
+| `workspace_not_located` | 找不到含 `拆文库/` 的工作区 | 加 `--workspace` 指定，不得用空名单放行 |
+| `module_book_mismatch` | `--module` 不在 `拆文库/{--book}/` 下 | 改对书名或路径 |
 
 ### 2. 单小说灵感合并
 
-只在一本书内确有 ≥2 张 EM 卡同构时创建 NM；孤立机制不建 NM。卡内容是**合并增量**，机制链不抄写：
+只在一本书内确有 ≥2 张 EM 卡同构时创建 NM；同构须满足触发、情绪链与兑现机制相同，孤立机制不建 NM。卡内容是**合并增量**，机制链不抄写：
 
 ```markdown
 # NM-001：{簇名}
@@ -57,7 +70,7 @@ story-long-analyze 的可选后置管道：把 Stage 3 已抽象好的 EM 机制
 
 ### 3. 跨书灵感聚合
 
-把各书 IA/NM 与现有 CBA 轻量索引比较，只读可能匹配的 active CBA。已建库后的增量先跑只读的 `coverage`：它列出尚未进入任何 active CBA 闭包的原子与现存单书假设卡——聚合比较只对 uncovered 原子做，顺带复核单书假设卡是否因新证据升级为「跨书重复验证」；uncovered 为空即无事可做，不重读已覆盖的 EM 卡。CBA 是**唯一供写作反复读取的卡**，必须自包含跨书归纳的抽象（聚合新产出，不是 EM 原文复制）：
+把各书 IA/NM 与现有 CBA 索引摘要比较，只读可能匹配的 active CBA。已建库后的增量先跑只读的 `coverage`：它列出尚未进入任何 active CBA 闭包的原子与现存单书假设卡——聚合比较只对 uncovered 原子做，顺带复核单书假设卡是否因新证据升级为「跨书重复验证」；uncovered 为空时不再比较已覆盖的 EM 卡；仍复核已有单书假设卡的验证状态。CBA 是**唯一供写作反复读取的卡**，必须自包含跨书归纳的抽象（聚合新产出，不是 EM 原文复制）：
 
 ```markdown
 # CBA-001：{机制名}
@@ -91,7 +104,7 @@ item_id,layer,title,source_book,path,source_ids,novel_count,atom_count,grade,tag
 - 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 命中靠值的精确匹配，写入侧与查询侧共用这一张表。
+- **标签值受控于库内 `灵感库/标签词表.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 解析为可读位置——需要时才查，不预先展开进任何卡。

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

@@ -2,7 +2,7 @@
 
 ## 唯一状态与三个脚本
 
-生产运行只使用：
+拆文运行使用三个脚本：
 
 1. `build_chapter_index.py`：建立机械章界和逐章原文 hash；
 2. `inspect_existing_assets.py`：只读识别旧成果、当前成果、缺章和修复阶段；
@@ -12,18 +12,12 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 脚本输出只给你看。失败或需要作者决定时，脚本会带 `author_message`（大白话说明和选项），按 [author-facing.md](author-facing.md) 转述给作者；不要把 JSON、错误码或下文的分类、路径名原样贴给作者。
 
-`chapter_index.csv` 是机械章节边界唯一真源。批次和阶段状态只写在 `_progress.md` 的
+`chapter_index.csv` 是机械章节边界的唯一依据。批次和阶段状态只写在 `_progress.md` 的
 `story-long-analyze:runtime-state` 受管区。`_analysis_cache/` 保存完整结果和恢复证据，不承担状态库功能。
 
-既有项目中的 `schema_version: 2` 沿用且不修改；该值只供报告，不用于否定旧成果。`_progress.md` 不再保存机械章节边界镜像。
+既有项目中的 `schema_version: 2` 沿用且不修改；该值只供报告，不用于否定旧成果。
 
-禁止创建 `run-plan.json`、`batch-checkpoints.json`、逐批 JSON receipt 或 Stage receipt。计划始终打印到标准输出，由当前运行直接消费。
-
-所有命令使用实际 Python 与 skill 根路径：
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/{脚本名}.py" ...
-```
+计划只打印到标准输出，由当前运行直接消费；不另建计划、检查点或逐批回执文件。`{PYTHON}` 与路径占位见 SKILL.md「运行约定」。
 
 ## 1. 先检查目录
 
@@ -34,14 +28,13 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 - 路径不存在、不是目录或不可读：非零退出，先修正路径。
 - 已存在的空目录：`empty / new_analysis`。
 - 完整旧项目：`direct_use`，不建索引、不读原文。
-- 部分项目：精确报告 `missing_semantic_chapters` 与 `missing_summary_chapters`。
+- 部分项目：带 `--compact` 时缺章看 `semantic_coverage.missing_ranges`；不带时另有逐章的 `missing_semantic_chapters` 与 `missing_summary_chapters`。
 - 新旧投影混存：`mixed_sources: true` 并列明逐章来源，仍可直接使用完整项目。
-- `schema_version` 只报告，不参与否定旧项目，也不在检查或复用时改写。
-- `stage_repairs` 中的情绪、节奏和文风修复与 Stage 2 缺章分开处理。
+- `stage_repairs` 按 SKILL.md「Phase 2」第二张表补对应 Stage，与 Stage 2 缺章分开处理。
 
 ## 2. 需要原文时建立或校验索引
 
-完整旧成果默认直接使用和纯旧成果增强无需索引。全新或部分完成才运行：
+完整旧成果默认直接使用；纯增强也无需索引。全新或部分完成且仍需读取原文时运行；只补文风时按 style-profile-generator.md 单独建索引：
 
 ```text
 "{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" \
@@ -65,15 +58,15 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 意图：
 
 - `continue`：补缺失语义章，以及缓存失效的已记录批次；已有语义但缺摘要时用旧成果投影；
-- `enhance`：只读既有拆文成果形成 `REUSE-{起章}-{止章}` 批次，原文读取数必须为 0。
+- `enhance`：把还没有完整批次缓存的已拆章做成 `REUSE-{起章}-{止章}` 批次，从旧成果提取跨章观察。逐章成果已覆盖全书时原文读取数为 0；仍有缺章时计划照样列出这些章的 `RAW` 批次，照计划处理，或先问作者是否只增强已拆的范围（加 `--chapters`）。
 
 没有“整本重拆”意图：已有摘要永不覆盖。整本重拆就换一个新目录重新拆。
 
-逐批派发时加 `--next 1` 只取下一批，确认进度用 `--next 0` 只看 `remaining_batches` 与压缩成区间的 `summary_gaps`；全量计划每批约五百字符，整本书反复全量输出会白占主会话上下文。不带 `--next` 时输出全部批次。
+逐批派发时加 `--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` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
+计划只存在内存和标准输出，`state_written` 必须为 `false`。每块最多 3 章、25,000 字符，单个超长章允许独占；同一章不能出现在两个原文块；计划原文读取数为 0 时不得派发原文任务；批次 ID 直接使用章节范围。`RAW` 只覆盖缺失章和缓存失效批次，`REUSE` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
 
 ## 4. 执行与提交一个批次
 
@@ -81,7 +74,7 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 
 - `batch_id`、`input_kind`；
 - `source_files`（原文块是逐章 `source_locator`，子代理自己按行号读原文）、`chapter_chars`（每章字数）和 `min_plot_points`（每章情节点下限，按字数算好）；
-- `input_file`：输出文件 `_analysis_cache/输入-{批次ID}.md`（不写系统 `/tmp`：Windows 没有，多本书同批号会互相覆盖）；
+- `input_file`：子代理的输出路径 `_analysis_cache/输入-{批次ID}.md`，每本书保存在各自拆文目录中；
 - `handoff_cache`：交接缓存，计划算好的「本批起章之前最近的已提交批次」，为空就不给；子代理只读其中 `### 跨批状态`。
 
 子代理把完整输出写进输出文件，只回一行 `BATCH_WRITTEN` 回执。主会话**不 Read 这份输入文件**，直接提交；提交被拒时重新派发同一批：上面的字段原样再给一遍（子代理补内容要按 `source_locator` 回看原文、按 `min_plot_points` 补情节点），再附错误码，让它用 Edit 只改出错处后再提交（结构整体错乱才整份重写）。提交成功后删掉这份输入。不论哪种派发方式，`commit` 都由主会话逐个执行，不并发跑。
@@ -89,8 +82,8 @@ Stage 4 另用 `render_relation_chart.py` 从 `角色/角色关系.md` 生成人
 **派发方式**：默认第 2 档有限并行，不请作者在三档里选。作者问起能不能更快或更稳、或明确要求时，才按 author-facing「作者问起怎么拆」用白话解释并切换。三档都用计划给的 `handoff_cache`，它随提交进度自动落到对应的批次上。
 
 1. **串行**：上一批提交成功再派下一批，交接缓存就是紧邻的前一批。优点：剧情点、未决悬念和已确认别名逐批完整接续，Stage 3 合并最省事。缺点：最慢，墙钟时间随批数线性增长。
-2. **有限并行**：每轮同时派 3 批，同轮的交接缓存都是本轮开始前最近一个已提交批次；整轮提交完再派下一轮。优点：约快两到三倍，接续最多滞后一轮。缺点：同轮批次互相看不到对方新建的剧情点与别名，边界处可能重复建 ID，靠 Stage 3 跨块合并收拢。
-3. **不限批次顺序**：不等前批，同时在跑的子代理最多 12 个（宿主或账号上限更低时以环境为准）；在跑的少于上限一半时，补派到上限。补派用 `plan --next {在跑数＋补派数}`，跳过已在跑的批次号（计划只认已提交）。遇到限流、超时或子代理报错，把上限减半后再补派。优点：最快。缺点：接续最弱，剧情点与别名最依赖 Stage 3 跨块合并和 Stage 4 归并；并发越高，被限流、整批重跑的风险越大。
+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)，提取规则与包裹标记照其中「批次提交格式」：
 

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

@@ -2,26 +2,41 @@
 
 开头时刻（Phase 1 到 Stage 1 停下来问）读本文件。作者读到的 `快速预览.md` 与停下来问的话术见 [author-facing.md](author-facing.md)。
 
-## Stage 0 概要（thin first-pass）
+## Stage 0 机械索引与概要初稿
 
-> **范围说明**：Stage 0 只能基于章节标题 + 卷段结构 + 抽样开头/结尾产出 thin first-pass（~200 字）。**禁止**在此阶段写出 500-1000 字 plot-aware 概要——读取范围不足以支撑那个密度。完整版在 Stage 5 落盘覆盖（见 [stage5-report.md](stage5-report.md)「完整概要」）。
+全新和部分完成且要读原文时先建索引（原文放置见 SKILL.md「运行约定」）：
 
-输出 `概要.md`：总字数{X}万 | 总章数{N} | 题材{类型}
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" --source "{拆文目录}/原文/原文.txt" --output "{拆文目录}/chapter_index.csv" --locator-path "原文/原文.txt"
+```
+
+完整旧成果直接使用或纯增强时不建索引。原文变化或章号对不上时脚本会停下并返回 `author_message`，按 [index-rebuild.md](index-rebuild.md) 处理。
+
+概要初稿只基于章节标题、卷段结构和抽样开头/结尾，写约 200 字，不写 500–1000 字的剧情与因果——读取范围不足，完整版由 Stage 5 覆盖（见 [stage5-report.md](stage5-report.md)「完整概要」）。逐章标题和字数在 `chapter_index.csv` 里，概要不列。
+
+```markdown
+# 概要：{书名}
+
+总章数：{N}
+总字数：{X}万
+题材：{类型}
 
 | 卷/段 | 章节范围 | 章数 | 预估字数 |
 |-------|----------|------|----------|
 | {卷名} | 第1-X章 | {N} | {W}万 |
 
-首版概要（~200字，thin first-pass）：{从章节标题 + 第1章+末章抽样归纳出的核心驱动 + 主角名 + 大致设定，不要硬凑剧情转折}
-章节索引：| 章节 | 标题 | 字数 |
+## 首版概要
+
+{约 200 字：从章节标题和第 1 章、末章抽样归纳出的核心驱动、主角名、大致设定，不硬凑剧情转折}
+```
 
-> Stage 5 完成后会就地覆盖此文件的「首版概要」段为「全书概要（500-1000字 plot-aware）」。章节索引和卷段表保留不变。
+「总章数：N」逐行写，检查器靠这一行认总章数。Stage 5 只替换「首版概要」一节，基本信息和卷段表保留。
 
 ## Stage 1 黄金三章
 
 黄金三章拆为三个单章文件，每章一个：`章节/第1章_深度拆解.md`、`章节/第2章_深度拆解.md`、`章节/第3章_深度拆解.md`。每个文件按以下模板输出。
 
-字数约{X}字 | 核心事件：{一句话}
+字数约{X}字 | 核心事件：{一句话}；原文不足三章时只拆已有章节，不补造缺章。
 
 **开篇钩子**（第1章看前500字）：类型{悬念/冲突/反差/信息差/代入感} | 手法{描述} | 效果{强/中/弱}—{原因}
 
@@ -31,7 +46,7 @@
 
 **结构拆解**：| 段落范围 | 功能{铺垫/冲突/爽点/收尾} | 字数 |
 
-**爽点分析**：类型{装逼打脸/逆袭反转/获得机缘/信息差碾压/情感满足} | 铺垫{X}字 / 释放{Y}字 / 铺放比{Z:1} | 情绪曲线
+**爽点分析**：类型{装逼打脸/逆袭反转/获得机缘/信息差碾压/情感满足/扮猪吃虎} | 铺垫{X}字 / 释放{Y}字 / 铺放比{Z:1} | 情绪曲线
 
 **反应层拆解**（如有）：
 
@@ -42,7 +57,7 @@
 | 强者重评 | | | |
 | 扩散传播 | | | |
 
-反应篇幅比{N:1} — 低于1.5 = 爽感不足
+反应篇幅比{N:1}，分母为实力展示篇幅；低于1.5时检查反应是否充分承接爽感
 
 **释放后追证**（如有）：爽点释放后反派真实态度？{行为+原文引用}
 
@@ -56,6 +71,7 @@
 
 > 第二、三章额外关注：信息密度 / 冲突升级(vs上章) / 节奏变化 / 爽点间隔字数。
 > 反派若为非人形（灵气复苏/末世/国运等抽象对抗型），在「爽点分析」处改用抽象对抗型路由：核心对抗面{描述} | 紧迫感来源{描述} | 升级机制{描述} | 叙事替代{用什么替代传统打脸}。
+> 感情流、女频（言情、宅斗、甜宠等）在「爽点分析」处改用关系路由：情感张力来源{误会/身份差/旧怨/契约等} | 关系推进一步{从什么到什么} | 虐甜安排{先虐后甜/甜中藏刀等} | 读者期待{想看谁对谁表态}；「反应层拆解」改看旁人对这段关系的反应。快速预览的「爽点设计」一项按情感兑现打分。
 
 同一次黄金三章阅读优先另写 `_style-sample.txt`，减少 Stage 6 的定点取样；旧项目没有该缓存时，Stage 6 仍可按索引选择 4–6 章并只读取对应行段：
 
@@ -97,28 +113,10 @@ Stage 1 停靠点交付物 `拆文库/{书名}/快速预览.md`，模板见 [aut
 | 代入钩 | 读者共鸣 | 相似困境 |
 | 信息差钩 | 读者知道角色不知道的 | 「他还不知道面前是……」 |
 
-### 爽点循环结构
-
-三层微观循环：
-- **铺垫层（蓄势）**：压抑/困境/信息差制造情绪缺口
-- **释放层（爽感）**：展露实力/打脸/碾压，强度由反应层数和篇幅决定
-- **衔接层（承转）**：旧循环结束埋新钩子
-
-反应层递进：质疑/轻视 → 震惊/打脸 → 强者重新评价 → 扩散效应
-反应篇幅比 = 反应总字数 / 装逼字数。低于1.5 = 爽感没接住。
-
-### 衔接过渡模式
-
-| 模式 | 机制 | 示例 |
-|------|------|------|
-| 打完小的来大的 | 释放层对手引出更强对手 | 打败弟子→师父找上门 |
-| 胜利发现隐患 | 释放成功暴露新问题 | 赢了比赛→发现中毒 |
-| 身份暴露/反转 | 释放中身份被识破 | 打脸后被认出真实身份 |
-| 利益升级 | 成果指向更大目标 | 线索→更深层宝藏 |
-| 关系突变 | 释放改变关系格局 | 救的人变仇家后代 |
-
 ### 题材爽点形态
 
+铺垫层制造情绪缺口，释放层负责兑现，反应层记录旁人反应；衔接层及完整拆法见 Stage 3 节奏一节。
+
 | 题材 | 释放层形态 | 反应层来源 | 铺垫层缺口 |
 |------|-----------|-----------|-----------|
 | 玄幻/修仙 | 实力碾压/境界突破 | 同门/对手/长老震惊 | 功法残缺/资源匮乏/血脉压制 |
@@ -126,3 +124,4 @@ Stage 1 停靠点交付物 `拆文库/{书名}/快速预览.md`，模板见 [aut
 | 系统文 | 解锁稀有技能/任务奖励 | 系统稀有度标注 | 任务失败惩罚/技能冷却 |
 | 历史 | 以弱胜强/先知优势 | 谋士/帝王/敌将震惊 | 信息不对称/身份低微 |
 | 悬疑 | 真相揭露/反杀 | 被揭穿者崩溃/读者恍然 | 线索误导/嫌疑人洗白 |
+| 言情/宅斗 | 当众表态/护短/真相大白 | 情敌/长辈/旁观者 | 误会/身份差/被轻视 |