@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/story-creation/upstream/skills/story-long-analyze/references/pipeline-ops.md

@@ -0,0 +1,154 @@
+# 长篇拆文运行、提交与恢复
+
+## 唯一状态与三个脚本
+
+生产运行只使用：
+
+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 列出的来源}"
+```
+
+`REUSE` 批次不传 `--range-sha256`。完整增强可以只输出 `REUSED_CHAPTERS` 与跨章观察；需要补摘要时输出同一套紧凑章节块。
+提交入口会再次检查 3 章与 25,000 字符上限；单个超长章仍允许独占。
+
+提交顺序固定：
+
+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` 必须逐字节保留。
+
+## 5. 失败、拆分和重试
+
+模型输出不完整时不提交。批次过大或连续失败时：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" split \
+  --root "{拆文目录}" --batch-id "RAW-4-6"
+```
+
+也可用 `--at 4` 指定左右边界。脚本在同一个 `_progress.md` 受管区把父块记为 `superseded`，写入两个相邻子块。重新运行 `plan` 后继续使用子块，不会按位置编号覆盖旧记录，也不会把子块重新合成父块。
+
+## 6. 中断恢复
+
+先重新运行 `plan`。已满足以下三项的成功批次不会出现：
+
+1. 范围内摘要都存在；
+2. 批次缓存完整，最后一个非空标记为 cache end；
+3. `RAW` 状态行的范围 hash 等于当前索引计算值。
+
+如果缓存已完整，但摘要或进度最后一步尚未落盘：
+
+```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
+```
+
+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/resources/skills/story-creation/upstream/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/resources/skills/story-creation/upstream/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/resources/skills/story-creation/upstream/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、按时序、白描客观｜剧情点包含因果与得失｜只保留关键事件/披露候选｜三维节奏分别解释｜跨批状态可继续。