@oh-story/dsh 0.1.9 → 0.1.10

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

@@ -1,80 +1,188 @@
-# 管道运维参考
-
-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 和解析器版本。
+
+同源索引直接复用且不重写。原文变化时先非零退出；人工确认后加 `--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` 只沿用已有索引的口径，不能用来改口径。
+
+## 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` 时输出全部批次。
+
+计划只存在内存和标准输出，`state_written` 必须为 `false`。每块最多 3 章、25,000 字符；批次 ID 直接使用章节范围。`RAW` 只覆盖缺失章和缓存失效批次，`REUSE` 只读取计划列出的旧成果。黄金三章深拆属于已有语义成果，可以生成缺失摘要，无需再次读取前三章原文。
+
+## 4. 执行与提交一个批次
+
+`chapter-extractor` 只处理计划中一个批次。**主会话不中转内容**：原文和批次结果都不经过主会话上下文。派发时只给——
+
+- 批次 ID、输入类型、计划的 `source_files`（原文块是逐章 `source_locator`，子代理自己按行号读原文）和 `chapter_chars`（每章字数，决定情节点密度）；
+- 输出文件 `{拆文目录}/_analysis_cache/输入-{批次ID}.md`（不写系统 `/tmp`：Windows 没有，多本书同批号会互相覆盖）；
+- 交接缓存路径：按下方派发方式选定的已提交批次缓存（没有就不给），子代理只读其中 `### 跨批状态`。
+
+子代理把完整输出写进输出文件，只回一行 `BATCH_WRITTEN` 回执。主会话**不 Read 这份输入文件**，直接提交；提交被拒时把错误码和输出文件路径交回子代理，让它用 Edit 只改出错处后再提交（结构整体错乱才整份重写）。提交成功后删掉这份输入。不论哪种派发方式，`commit` 都由主会话逐个执行，不并发跑。
+
+**派发方式三档**（Stage 1 后停下询问时一并请作者选，话术见 author-facing「开头三章拆完、停下来问」）：
+
+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「批次提交格式」：
+
+```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 列出的来源}"
+```
+
+`REUSE` 批次不传 `--range-sha256`。完整增强可以只输出 `REUSED_CHAPTERS` 与跨章观察；需要补摘要时输出同一套紧凑章节块。
+提交入口会再次检查 3 章与 25,000 字符上限；单个超长章仍允许独占。
+
+提交顺序固定：
+
+1. 在写文件前校验整批范围、标记、所有紧凑字段和情节点（原文块每章 10–20 个、长章最多 30，少于 10 或多于 30 整批拒收；编号连续、每点带主题标签与基调行）；
+2. 对 `RAW` 再算当前范围 hash，与计划值不一致就拒绝；
+3. 原子写入含完整模型输出和最终结束标记的批次缓存；
+4. 只创建缺失的 `章节/第N章_摘要.md`，任何已有摘要都保留，并在结果的 `kept_existing_summary_chapters` 里列出；
+5. 最后更新 `_progress.md` 受管批次表为 `completed`；有阶段记录时按 Stage 3–6 状态重写受管区的 `最终状态`（旧项目改写原有行，不写第二行）。
+
+每条成功行记录章节范围、输入类型、原文范围 hash、状态和缓存路径。受管区外的 BOM、换行、作者备注及既有 `schema_version` 必须逐字节保留。
+
+## 5. 失败、拆分和重试
+
+模型输出不完整时不提交。批次过大或连续失败时：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" split \
+  --root "{拆文目录}" --batch-id "RAW-4-6"
 ```
 
-**schema_version 说明**：
+也可用 `--at 4` 指定左右边界。脚本在同一个 `_progress.md` 受管区把父块记为 `superseded`，写入两个相邻子块。重新运行 `plan` 后继续使用子块，不会按位置编号覆盖旧记录，也不会把子块重新合成父块。
+
+## 6. 中断恢复
+
+先重新运行 `plan`。已满足以下三项的成功批次不会出现：
 
-| 版本 | 含义 |
-|------|------|
-| 2 | 当前契约：含「章节边界」表（Stage 0 章节边界子步骤产物）。Stage 1/2/6 全部以该表为切片真值，不再各自跑 regex |
+1. 范围内摘要都存在；
+2. 批次缓存完整，最后一个非空标记为 cache end；
+3. `RAW` 状态行的范围 hash 等于当前索引计算值。
 
-缺少 `schema_version: 2` 或「章节边界」表时不得续跑；从 Stage 0 章节边界子步骤重建 `_progress.md` 后再恢复。
+如果缓存已完整，但摘要或进度最后一步尚未落盘：
 
-**最终状态值说明**：
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" repair-progress --root "{拆文目录}"
+```
+
+恢复只从完整、范围 hash 有效的缓存补缺失摘要并更新状态；不覆盖用户修改过的文件。缓存缺结束标记或范围 hash 失效时报告错误并重跑相应批次。
 
-| 状态值 | 含义 |
-|--------|------|
-| `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` | 全管道完成，但有单章/单阶段失败（详见「失败记录」表，拆文报告中注明） |
+## 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"
+```
 
-触发：用户说「补剧情单元清单」，或写作侧检索发现 `剧情/README.md` 无「剧情单元清单」表。
+**Stage 3–5 的读法**：不整份 Read 批次缓存（每批约七成是和逐章摘要重复的章节块），改用只读的 `digest` 按需取料，输出是 Markdown：
 
-动作：读存量 `拆文库/{书名}/剧情/*.md`（或 `对标/{书名}/剧情/*.md`）各剧情单元表头的 标题 / 类型 / 桥段标签 / 章节范围 字段，按 output-templates.md「剧情单元清单」表模板机械重建 `剧情/README.md` 的清单表；项目 `对标/{书名}/` 视图存在时同步一份。不读原文、不重跑任何 Stage、不改剧情单元内容、不动 `节奏.md` / `情绪模块.md`。旧剧情单元「章节范围」行没有字数信息时，体量列只写「共{N}章」、字数记「未知」，不得编造。
+```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
+```
 
-写作侧消费点对无清单的书自动回退逐文件检索（见 story-long-write 的 outline-structure-theory.md「对标节奏迁移」步骤 1），补建只是加速，不是阻塞项。
+- `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` 前先执行：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage --root "{拆文目录}" --stage stage5 --prepare
+```
 
-| 场景 | 处理 |
-|------|------|
-| 章节识别失败 | 提示确认格式；支持自定义正则 |
-| 分块中断 | 读 _progress.md 断点恢复 |
-| 聚合质量不达标 | 孤立情节二次分类；阈值放宽至 0.5 |
-| 角色合并冲突 | 记录待确认列表 |
-| 输出目录冲突 | 追加不覆盖；冲突标 `[重新分析]` |
+若旧报告存在，命令会完整复制到 `_analysis_cache/legacy/拆文报告.md`；已存在的首份备份不覆盖。当前旧报告与首份备份不同时，另存一份带内容 hash 的历史备份。其他旧产物与已有摘要不得覆盖。新报告落盘后再用不带 `--prepare` 的 `mark-stage` 标记完成。
 
----
+## 8. 最终检查
 
-## 恢复机制操作步骤
+检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
 
-1. 管道启动时检查输出目录是否已有 `_progress.md`
-2. 校验 `schema_version: 2` 与「章节边界」表；任一缺失即停止，并提示从 Stage 0 章节边界子步骤重建进度文件
-3. 读取断点信息（最后处理章节 + 当前阶段 + 最终状态）
-4. **断点状态为 `paused_after_stage1`**（Stage 1 停靠点）→ 跳过 Stage 0/1，直接从 Stage 2 续跑逐章摘要，不重跑已完成的概要与黄金三章
-5. 其他断点状态 → 从断点所在块的起始章节恢复，覆盖该块已有输出
+- 再运行检查器和计划器；完整项目应 `direct_use`，继续意图应无待处理批次；
+- 对比受保护路径 hash：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md`、`拆文报告.md` 不得被增强或恢复流程改写；
+- 允许变化的旧项目文件只有 `_progress.md` 受管状态区和 `_analysis_cache/` 新证据；
+- 检查旧 `schema_version` 原值；
+- 检查新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取；
+- 报告未执行的真实模型或跨平台检查，不得用静态 fixture 冒充。

package/lib/oh-story/skills/story-long-analyze/references/semantic-acceptance-fixtures.md

@@ -0,0 +1,84 @@
+# 长篇拆文语义验收样例
+
+这些短文本为本项目自有合成样例，用于 review 和联合测试。每章只有一两句，过不了原文块每章 10 个情节点的提交下限，所以只用于 Stage 3+ 与模型语义评估：测试时让对应 Stage 处理原文，再按“应识别的关系”评估；不得仅以关键词或栏目存在判通过。
+
+## 样例一：事件与多次披露
+
+### 原文
+
+第一章，掌印官罗衡趁换值时把边军密函交给敌使，交易已经完成。叙述只写他洗掉指缝里的红蜡，没有解释来源。第二章，主角沈照发现封匣完好，罗衡却换了从不用的沉香。第三章，驿卒说昨夜有人持罗衡腰牌出城；罗衡声称腰牌早已遗失，读者第一次能把红蜡、香气和出城记录连起来，沈照仍认为可能是冒用。第四章，敌使被捕并交出密函，罗衡承认交易。
+
+### 应识别的关系
+
+- 客观事件只有一次：罗衡在第一章完成背叛和交付。
+- 至少四个披露节点：红蜡异常、香气异常、腰牌证词与解释冲突、物证加口供确认。
+- 读者在第三章已高度怀疑，沈照仍保留另一解释；第四章双方才获得确认。
+- 分析要说明判断怎样从“无解释细节”变为“可连接线索”再变成“事实确认”，不能把四个节点写成四次背叛。
+
+## 样例二：安静告别的三维节奏
+
+### 原文
+
+车已停在门外，阿芹只需要上车。祖母替她缝好松开的袖扣，又把针线盒里最后一颗旧铜扣塞进她掌心。两人谈的都是路上会不会下雨，谁也没提阿芹此去可能多年不归。作者用三页写针穿过布、手指停顿和几次被岔开的道别。场景结束时，阿芹上车，祖母仍站在门槛内。
+
+### 应识别的关系
+
+- 事件推进较低到中：外部结果主要是离家成行，但关系进入长期分离的新状态。
+- 情绪强度高：铜扣、回避直说和动作停顿共同制造不舍，不等于“因为是告别所以悲伤”。
+- 篇幅展开度高：一个简单动作被细节、停顿和潜台词展开；应解释展开服务于压住直白告别。
+- 三个分数必须各有证据和理由，不能用“慢节奏”概括全部。
+
+## 样例三：因果归属不只属于主角
+
+### 原文
+
+顾野要在天黑前把药送过关桥。守桥人因旧债扣下他，他第一次交涉失败。同行的秋禾主动拿自己的通行牌作抵押，守桥人才放行。两人刚过桥，山洪冲断桥面，追兵被隔在对岸，秋禾也永久失去通行资格。顾野救到了病人，却欠下秋禾无法立刻偿还的人情。
+
+### 应识别的关系
+
+- 起始目标：顾野送药；阻碍：旧债导致关桥受阻。
+- 改变局面的关键行动由秋禾作出；山洪是后续放大结果的外部事件。
+- 收益包括送药成功和摆脱追兵；代价由秋禾先承担，顾野新增关系债务。
+- 后续行动空间改变：秋禾不能再合法通关，顾野必须处理欠债。不得反推为顾野预先利用山洪。
+
+## 样例四：机制的成立与失效
+
+### 原文与变体
+
+原场景中，学徒周宁被诬陷篡改账册。师父一向允许学徒当众核账，三日前又让众人各自封存底稿。周宁在全体同门前拿出封条完整的底稿，对照出诬陷者新增的一笔。师父先前承诺“账目说话”，因此公开认错并恢复周宁资格。
+
+变体中，掌柜长期以惩罚控制伙计，底稿只由掌柜保管，围观者也依赖掌柜发薪。即使伙计拿出一张抄本，众人也可能认为它是伪造品，不敢公开站队。
+
+### 应识别的关系
+
+- 原机制不是抽象的“先压后扬”，而是公开质疑 → 可独立验证的旧证据 → 权威受先前承诺约束 → 公开纠错。
+- 成立条件包括核账惯例、多人独立封存、师徒关系仍承认程序、见证者有表达空间。
+- 可替换的是行业、证据载体和具体诬陷；不可随意删掉独立验证与权威自我约束。
+- 变体失效源于证据控制和关系权力不同，不应硬套同一兑现。
+
+## 样例五：资料不足保留未知
+
+### 原文
+
+密室地面有一串湿脚印，窗闩从内扣住。侦探只说“有人希望我们先看窗户”，本段到此结束。正文没有出现暗道、机关或凶手身份。
+
+### 应识别的关系
+
+- 可确认：湿脚印、内扣窗闩和侦探认为视线被引向窗户。
+- 不能确认：存在暗道、凶手从窗户进入、脚印由凶手留下、侦探已经知道答案。
+- 未知项写明证据缺口和待后文确认，不用类型小说惯例补齐。
+
+## 评价表
+
+每项 0–2 分：0 为错误或缺失，1 为部分正确，2 为关系清楚且有证据。总分至少 10/12，且无硬失败，才算通过。
+
+| 项目 | 2 分标准 |
+|---|---|
+| 因果与归属 | 目标、阻碍、改变局面的主体/事件、得失和后续约束连接正确 |
+| 事件与披露 | 客观事件不重复，多次披露和判断变化对应正确 |
+| 知识边界 | 读者与关键角色在各节点的已知/未知分开 |
+| 三维节奏 | 事件、情绪、篇幅分别解释并允许高低组合不同 |
+| 机制迁移 | 写出期待、铺垫、关系/资源/信息条件及失效原因 |
+| 证据纪律 | 结论可定位，未知不被常识或类型惯例填满 |
+
+硬失败包括：把披露当事件重复登记；把配角或外部事件的作用归给主角；用分数替代理由；把未知写成事实；为旧项目伪造当前主产物；主报告与底层事实相互冲突。

package/lib/oh-story/skills/story-long-analyze/references/style-profile-generator.md

@@ -1,149 +1,59 @@
-# 文风生成 SOP
+# 文风档案生成与单独重建
 
-> **何时加载**：story-long-analyze Stage 6 执行时。`拆文报告.md` 是阻断级前置依赖；`章节/*_摘要.md`、`章节/第1-3章_深度拆解.md` 与 `原文/原文.txt`（或 `.md`）是质量输入，缺失时严格按下方「失败模式与降级」逐项处理。
->
-> **输出**：`拆文库/{书名}/文风.md`（模板见 [style-profile-protocol.md](style-profile-protocol.md)）。
+> **何时加载**：story-long-analyze Stage 6。Stage 6 可以在完整管道末尾运行，也可以在已有拆文只缺 `文风.md` 时单独运行；单独运行不得触发 Stage 1–5。
 
-## 6 步流程
+## 原则
 
-### Step 1: 读拆文报告核心字段
+1. 文风档案描述作者实际写法，不评价作者水平。
+2. 情绪和节奏意图以 `剧情/情绪模块.md`、`剧情/节奏.md` 为准，文风只管表达层。
+3. 已有完整 `文风.md` 时原样保留；用户明确要求增强时才更新。
+4. Stage 6 不重扫全书。允许使用索引行号定点回读 4–6 段原文，以补齐可验证锚点。
+5. 摘要措辞不能冒充作者原句；缺少原文和有效样本时明确报错。
 
-读 `拆文库/{书名}/拆文报告.md`，提取：
+## 来源顺序
 
-- **「写法技巧」段** → 用于填文风「可借鉴技巧」的「写法技巧 Top 5」
-- **「可借鉴套路」段** → 用于填文风「可借鉴技巧」的「可借鉴套路 Top 3」
-- **「全书情绪节奏总览 / 伏笔与冲突网络」段** → 用于填文风「分层模仿建议」的进阶层与适配层，只抽象节奏和手法，不搬运具体桥段
-- **基本信息**（书名、题材、总章数）→ 填写文风标题与「生成记录」
-- 「生成记录」只写作者能看懂的信息：参考了哪些资料、抽样看了哪几章、生成时间、文风是否可用；不要写文件时间戳或内部降级标记这类实现术语。
+1. 既有 `文风.md`；
+2. 项目内非空且含连续原文的 `_style-sample.txt`；
+3. `章节/第1-3章_深度拆解.md` 中带定位的短引和写法证据；
+4. `_analysis_cache/批次-*.md`、`章节/*_摘要.md` 与 `拆文报告.md` 的结构层观察；
+5. 仍缺锚点时，读取 `chapter_index.csv`，按旧版“覆盖主要基调”的方式选择 4–6 章，再按 `start_line/end_line` 定点读取原文片段。
 
-### Step 2: 读黄金三章深度拆解
+第 5 项只读取被选章节的局部行段，不允许从头到尾扫描原文。没有索引的旧项目可以仅运行机械索引脚本；这一步不写 `_progress.md`，也不启动其他分析阶段。
 
-读 `章节/第1章_深度拆解.md`、`第2章_深度拆解.md`、`第3章_深度拆解.md`，提取：
-
-- **开篇钩子类型 + 手法**
-- **反应层拆解表**（对话潜台词样本）
-- **爽点铺放比**（情绪交替节奏样本）
-- **可借鉴要素**（与 Step 1 合并去重，喂「写法技巧 Top 5」）
-
-### Step 3: 提取章节基调/主题标签序列
-
-用 Grep 读所有 `章节/*_摘要.md`：
-
-```bash
-grep -hE '基调：(紧张|轻松|悲伤|热血|爽|甜|温馨|恐怖|压抑|其他)' 章节/*_摘要.md
-```
-
-**关键格式注意**：`章节/*_摘要.md` 的实际格式是 `主题标签X | 基调：Y` 单独成行、跟在每个情节点后（一章 10-40 行）。`基调` 用**全角冒号**，`主题标签` 后**不带冒号**，两者都**不在行首**。grep 模式不能用 `^基调:` 这种锚定。
-
-**章基调聚合规则**（每章一个章基调，写入文风「情绪交替模式」）：
-
-- 对该章所有情节点的「基调」字段做众数统计
-- 并列时（如 5 紧张 vs 5 热血）取章节内**最早出现**的基调（按 `_摘要.md` 中行号）
-- 输出格式：`第N章: {章基调}`，连成全书序列
-
-**章内情节点基调序列**（用于「章内基调切换」分析）：
-
-- 不做聚合，按 `_摘要.md` 中情节点出现顺序保留
-- 用于统计切换频率：相邻情节点基调不同的次数 / 总情节点数
-
-### Step 4: 原文采样
-
-`原文/` 下**只有一个全书单文件** `原文.txt`（或 `.md`），**不是按章拆分**。Stage 0 已把校验通过的章节起止行写入 `拆文库/{书名}/_progress.md`，该表是 Stage 1/2/6 共用的唯一切片真值。
-
-**Stage 6 只读 `_progress.md` 里的「章节边界」表，不重新搜索章节标题、不另行推断边界，也不自行修正规则。** 如果表缺失、目标章缺边界、边界不连续或指向原文范围之外，立即停止 Stage 6，提示重新执行 Stage 0 重建进度文件；不得用临时切片继续生成文风。
-
-**采样切片**：
-
-- 从 `_progress.md` 的章节边界表选第 1 章、第 10 章、第 20 章（如总章数 <20，按 1/3、2/3、收尾比例挑）
-- 每章用 `Read offset={该章起始行} limit=50` 切出约 1000 字
-- 把 3 段拼接写入 `拆文库/{书名}/_style-sample.txt`（固定这个文件名，不要换）：**第一段用 `>` 覆盖写，后两段才用 `>>` 追加**。全程用 `>>` 会让重跑 Stage 6 时把上一轮的样本累积进来，统计出的句长分布是两轮混合的结果
-
-**确定性句长/标点统计**（替代主观「眼测」）：
-
-Stage 6 由**主线程**执行，Bash 工具可用。把上一步拼好的 `_style-sample.txt` 喂给下面的脚本（heredoc 作 Python 源，样本路径按 argv 传入，避免 stdin heredoc 与 `< file` 双重重定向冲突）。先探测可用解释器再跑——**勿直接用 `python3`**，Windows 上它会触发 Microsoft Store 占位程序、exit 49 失败。
-
-样本路径**必须用项目内相对路径**，不要写 `/tmp/...`：下面探测到的解释器可能是 Windows 原生 python（`py` 启动器），它把 `/tmp/x.txt` 解析成 `C:\tmp\x.txt`，和 Git Bash 写入的位置不是同一个文件，脚本会直接 FileNotFoundError。
-
-```bash
-SAMPLE="拆文库/{书名}/_style-sample.txt"   # {书名} 换成实际书名，别照抄占位符
-for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done
-"$PYBIN" - "$SAMPLE" <<'PYEOF'
-import re
-import sys
-with open(sys.argv[1], 'r', encoding='utf-8') as f:
-    text = f.read()
-sents = [s for s in re.split(r'[。！？]+', text) if s.strip()]
-total = max(len(sents), 1)
-short = sum(1 for s in sents if len(s) < 15)
-mid   = sum(1 for s in sents if 15 <= len(s) <= 30)
-lng   = sum(1 for s in sents if len(s) > 30)
-chars = max(sum(1 for c in text if not c.isspace()), 1)
-puncts = sum(1 for c in text if c in '，。！？；：、…—""\'\'')
-avg = sum(len(s) for s in sents) // total
-print(f'sentences={total}; short_lt15={100*short//total}%; mid_15to30={100*mid//total}%; long_gt30={100*lng//total}%; avg_len={avg}; punct_density={100*puncts//chars}%')
-PYEOF
-```
-
-实测输出形如 `sentences=6; short_lt15=66%; mid_15to30=33%; long_gt30=0%; avg_len=12; punct_density=15%`。
-
-把输出的 `short_lt15 / mid_15to30 / long_gt30 / avg_len / punct_density` 数值直接填进 `style-profile-protocol.md` 模板第 40 行的 `{...X% / Y% / Z%}` 占位符——`confidence: high`，因为是确定性测量，不是抽样估计。
-
-**Bash 不可用时的降级**（仅子代理上下文等极端情况，主线程不会触发）：
-
-- 跳过本步骤；句长段写「Bash 工具不可用，跳过确定性统计」
-- `confidence: low`，narrative-writer 让位回默认 Gate D（按句长标准校准）
-
-### Step 5: 选原文锚点片段 (4-6 段)
-
-从 Step 3 输出的章节基调里挑覆盖度最高、且项目可能需要的 4-6 类基调（优先覆盖：紧张/悲伤或压抑/轻松或温馨/热血）。若某类基调在对标书中少于 3 章，不强行编造；在文风文件中说明跳过。每类基调选 1 章作为锚点章。
-
-**同基调多章时的选择规则**：
-
-1. **L1 爽点类型最强匹配**：参考该章 `_摘要.md` 的「关键事件」+ 基调序列，挑爽点最突出的章节
-2. **L2 原文章节长度最接近日更目标**：若 Step 4 已切出章节边界，用原文章节切片估算字数；若无法切原文，只用 `_摘要.md` 的情节点数量近似复杂度，不把摘要文件长度当作原文章节字数
-3. **L3 章节号最小**：最早期的章节 = 作者最 canonical 的 voice（未受连载漂移影响）
-
-锚点切片：
-
-- 用 Step 4 从 `_progress.md` 读取的章节起止行
-- 该章原文从中选 1 段 300-500 字（优先选对话+动作交织的段落，纯独白/纯设定段不选）
-- 用 `Read offset limit` 切出，保留原标点和段落断行
-- **锚点必须逐字连续切片，禁止改写/缩写/跳段/拼接**：narrative-writer 拿锚点当 few-shot 直接学，标注的行号要能回查原文。落盘前逐段抽 1-2 句 `grep -F` 回 `原文/原文.txt`，grep 不到即说明被改写或拼接——重切为忠实连续片段。确需跳过中间过渡段时，分别标各自真实行号（如「行264-267 + 行269-270」）并在引用块内用「（……中略……）」显式断开，不得用一个连续行号区间假装连续
-
-### Step 6: 落盘
-
-按 [style-profile-protocol.md](style-profile-protocol.md) 模板填写 `拆文库/{书名}/文风.md`：
+## 单独重建文风
 
-- **文风文件必须留在拆文库**（`拆文库/{书名}/文风.md`），**永不由 analyze 直接写入** `对标/` 或写作项目目录——拆文库是数据源；只有该书被明确选为另一项目的外部对标时，才由 story-import 或 story-long-write 首次引用同步到 `对标/{书名}/`
-- 每段标 `confidence: high/med/low`（内部给写作 agent 判断强弱，普通用户可忽略）：
-  - `high`：数据直接来自拆文产物（如「写法技巧」直接引用拆文报告）
-  - `med`：从样本归纳且样本充足（如基调序列从 ≥10 章摘要统计）
-  - `low`：样本不足或采样失败（如锚点缺失、Bash 不可用导致 Step 4 句长统计跳过）
-- 「分层模仿建议」必须分基础层 / 进阶层 / 适配层；基础层只写词汇、句式、描写和对话习惯，进阶层写节奏、伏笔、视角和场景衔接，适配层写哪些可用、哪些容易让本项目错位；明确不复制专名、标志性台词、独特桥段和事件顺序
-- 字数预算：硬上限 ~4000 字。**描述段 ≤ 1800 字 + 锚点 4-6 段 × 300-500 字**
-- 如果 Step 4 失败（章节分隔符识别不出）→ 「生成记录」写 `文风可用：否：无法识别章节分隔符`；原文锚点段全填占位符 "原文缺失，需手动补充"，confidence 全 low
+当 story-long-write 或用户发现 `文风.md` 缺失时：
 
-## 失败模式与降级
+1. 运行检查器，确认其他拆文成果可用且 `stage_repairs` 包含 `stage6_style`；
+2. 若 `_style-sample.txt` 有效，直接用它；
+3. 否则确认 `chapter_index.csv` 与原文存在。缺索引时只运行：
 
-| 场景 | 降级策略 |
-|---|---|
-| `原文/原文.txt` 不存在 | 跳过 Step 4-5；文风文件仅含描述段；「生成记录」写 `文风可用：否：原文缺失` |
-| `章节/*_摘要.md` 数量 <3 | 跳过 Step 3 基调序列；情绪交替段标 confidence: low |
-| `章节/第1-3章_深度拆解.md` 缺失 | 跳过 Step 2；对话潜台词段从拆文报告兜底；confidence: low |
-| `拆文报告.md` 不存在 | **停止 Stage 6**，提示用户拆文未完成，先跑完 Stage 5 |
+   ```text
+   "{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" --source "{拆文目录}/原文/原文.txt" --output "{拆文目录}/chapter_index.csv" --locator-path "原文/原文.txt"
+   ```
 
-## 与 chapter-extractor 的关系
+4. 从索引中选择 4–6 章，优先覆盖紧张、轻松、冲突、关系回收、高潮与收束等已有资料能确认的不同基调；按行号只取每章一段 300–500 字连续原句，写入或更新 `_style-sample.txt`；
+5. 按 [style-profile-protocol.md](style-profile-protocol.md) 生成 `文风.md`；
+6. 文件成功落盘后运行：
 
-**不修改 chapter-extractor**。文风直接从既有字段（基调/主题标签/可借鉴要素）整理生成即可。
+   ```text
+   "{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" mark-stage --root "{拆文目录}" --stage stage6 --output "文风.md"
+   ```
 
-句长 / 标点密度由 Step 4 的跨平台 Python 1-liner 在 Stage 6 主线程直接算出，不依赖 chapter-extractor。
+索引、原文和有效样本都不存在时停止，返回“无法取得可验证文风锚点”，不得生成锚点全空的可用文风。
 
-## 与写作端的关系
+## 档案内容
 
-- analyze Stage 6 写 `拆文库/{书名}/文风.md`
-- story-import 显式绑定外部对标或 story-long-write 首次引用 `拆文库/{书名}/` 时，同步到项目 `{项目}/对标/{书名}/` 并**包含**文风（与拆文报告同等待遇）；不得把正在导入的本书自身作为该外部对标
-- 写作端（story-long-write）的日更循环读 `{项目}/对标/{书名}/文风.md`（按对标书路径查找规则，回退 `拆文库/{书名}/`）
+- 叙述视角、段落推进、对白比例、动作与心理安排；
+- 句长、标点、口吻和角色语气，只从原文锚点归纳；
+- 情绪转场引用三维节奏和篇幅安排，不把剧情强度当文风；
+- 每项标 `high / med / low` 置信度及来源路径；
+- 原文锚点 4–6 段，每段标章节、行号、基调和示范点。
 
-## 单独重建文风
+## 质量检查
 
-当前拆文产物仅缺 `文风.md` 时，可直接按本 SOP 跑 6 步（仅 Stage 6），无需重跑 Stage 0-5；前提是 `_progress.md` 满足当前章节边界契约。触发：用户直接说 "为对标书 X 生成文风" 或 "重生 文风"。
+- 每条高置信结论都有资料路径或可核原文锚点；
+- 4–6 段锚点覆盖不同基调，且来自索引指定的局部行段；
+- 摘要没有被当成作者原句；
+- `文风.md` 保持现有下游字段，未获增强请求时不覆盖旧文件；
+- Stage 6 失败只报告本阶段缺口，不回头重跑 Stage 1–5。

package/lib/oh-story/skills/story-long-analyze/references/style-profile-protocol.md

@@ -6,12 +6,12 @@
 
 `拆文库/{书名}/文风.md` 是整书级写作技法视图，聚合：
 
-- 句长 / 标点 / 段落节奏（从原文采样统计）
+- 句长 / 标点 / 段落节奏（从已有样本或按索引定点读取的可验证原句统计）
 - 对话潜台词模式 + 角色语气区分
 - 章内 + 跨章情绪交替周期（看每章基调如何变化）
 - `拆文报告.md` 已有的「写法技巧」「可借鉴套路」
 - 分层模仿建议（基础层 / 进阶层 / 适配层，强调学手法不搬桥段）
-- 4-6 段 300-500 字原文锚点片段（范例片段用）
+- 4-6 段可验证原文锚点片段（范例片段用；优先已有样本，没有时按索引定点读取，都不可用时明确失败）
 
 ## 文件路径
 
@@ -32,13 +32,13 @@
 
 ## 生成记录
 - 参考资料：拆文报告.md、黄金三章深度拆解、章节摘要
-- 抽样章节：第 {K1}/{K10}/{K20} 章（每章约 1000 字）
+- 抽样章节：第 {K1}/{K2}/{K3}/{K4}[/{K5}/{K6}] 章（每章取 300-500 字连续行段）
 - 生成时间：{date}
 - 适用对标书路径：拆文库/{书名}/
 - 文风可用：是  # 若原文缺失或锚点不足，写“否：原因”
 
 ## 整体语感
-- 句长分布：{由 `style-profile-generator.md` Step 4 的跨平台 Python 1-liner 在 3 章拼接样本上确定性测量——短句(<15字)占比 X%、中句(15-30)Y%、长句(>30)Z%、平均句长 N 字、标点密度 M%。一句概括语感。`confidence: high`（数据由脚本算出，不是抽样估计）。}
+- 句长分布：{在 4-6 段合并样本上确定性测量——短句(<15字)占比 X%、中句(15-30)Y%、长句(>30)Z%、平均句长 N 字、标点密度 M%。一句概括语感。`confidence: high`（数据由机械统计得出，不是模型估计）。}
   - confidence: high | med | low
 - 标点习惯：{破折号/省略号/句号/感叹号/分号 的高频用法。附 2-3 个原文短片段示例。}
   - confidence: high | med | low
@@ -72,7 +72,7 @@
 
 ## 原文锚点片段
 
-> 每片段 300-500 字，**用于 narrative-writer 写作时的范例片段**。从 `原文/原文.txt` 按章节分隔符切片。模仿手法、不抄字句。
+> 每片段 300-500 字，**用于 narrative-writer 写作时的范例片段**。优先复用旧文风、黄金三章或批次中已经保存并带定位的连续原句；没有有效样本时，Stage 6 可按 `chapter_index.csv` 定点读取 4-6 段连续原文。不得重扫全书。模仿手法、不抄字句。
 
 ### 片段 A — 基调：紧张
 **出处**：第 {K} 章 第 {段号} 段（行 {L1}-{L2}）