@oh-story/dsh 0.1.0

package/lib/drama/skills/short-drama-novel-analyze/references/chapter-extraction.md

@@ -0,0 +1,141 @@
+# 逐章提取
+
+## 目录
+
+- [提取什么](#提取什么)
+- [情节点写法](#情节点写法)
+- [白描与叙事框架词](#白描与叙事框架词)
+- [载体记录](#载体记录)
+- [机械自检](#机械自检)
+- [并发与串行](#并发与串行)
+- [失败处理](#失败处理)
+
+## 提取什么
+
+一章提取一份 `chapters/ch-<N>-extract.md`，`<N>` 用索引里的 `sequence`（多卷书的原文
+章号会重复，sequence 不会）。
+
+**第一行是标题**：`# ch-<N> <原文章节标题>`。原文没有标题就只写 `# ch-<N>`，不要自拟。
+
+其下五段固定顺序：
+
+1. **概要**：3–5 句，说这一章在整本书里**改变了什么**。不是缩写剧情，是回答
+   「读完这章，谁的处境、认知或筹码和读完上一章时不一样了」。写成条目罗列，
+   或整段「因为…所以…」串联，都是没做提取。
+2. **情节点**：见下。
+3. **载体记录**：见下。
+4. **出场人物**：本章出现的称谓原样记录，附本章内的作用**。不做跨章归并**——归并是 S4
+   的事，在这里做会让每一章各自发明一套人物表。
+5. **未决项**：本章无法判断的指代、时间关系或矛盾，逐条列出。留白比猜测便宜。
+
+## 情节点写法
+
+每个情节点一行，四段用 `|` 分隔：
+
+```
+P1 类型 | 白描 | 涉及：称谓、物件、地点 | 功能：这一步改变了什么
+```
+
+- **`P<n>` 与类型之间是一个半角空格**，类型与 `|` 之间也是。下游按这个字面形状 grep，
+  写成全角空格或不写空格，这一行就不算情节点——**这是最常见的一处格式漂移**。
+- **类型**取自：`行动`、`对话`、`信息`、`转折`、`铺垫`、`兑现`、`状态`。
+- **白描**是可观察的事实：谁做了什么、说了什么、什么被看见。见下一节。
+- **功能**回答改变了什么：权力、信息、关系、暴露、资源、时间或代价，至少一项。
+  写不出功能的情节点，多半不是情节点。
+- **`功能：` 是字段标记，不要在别处使用**。概要、载体记录、未决项里若出现这四个字符，
+  自检的计数就会超过情节点数。要在正文里说「功能」，改写成「作用」「起到的效果」。
+
+密度按章节字数动态调节，通常一个情节点覆盖 150–200 字原文。不要为凑数拆步骤，
+也不要把一整场戏压成一行。为同一个戏剧目的服务的连续微动作合并成一个情节点。
+
+## 白描与叙事框架词
+
+白描是这条情节点的主要证据——后面每一次事实回查都落在它上面。所以它只能写
+**原文写出来的可观察事实**：不写心理断言，不写作者意图，不用叙事框架词概括。
+
+| 禁止 | 正确 |
+|---|---|
+| 通过对话，郑松得知张子豪在韩国训练 | 吴志斌告诉郑松，张子豪在韩国训练 |
+| 林风展现了自己的实力 | 林风三招击败对手，围观者倒吸一口凉气 |
+| 邵阳感到心碎和愤怒 | 邵阳目睹宋丽与人拥抱，表情由刺痛转为冷漠 |
+| 这一章为后文埋下伏笔 | 管家把一枚旧钥匙放进抽屉最里层，没有说明用途 |
+
+**原文本身就是内心独白时**，写「他想」的内容本身，而不是写他的心理状态：
+原文「他想，这次真的完了」写成「他在心里说这次真的完了」，不写「他感到绝望」。
+第一人称叙述同理——原文以「我」写出来的判断是这一章的可观察事实，照录即可，
+但只能录他说出或想出的那句话，不能替他总结。
+
+左列的问题不是啰嗦，是**它把结论写在了证据的位置上**。S3 之后的每一次聚合都离原文
+两跳，如果证据本身已经是结论，后面就再也无法核对这个结论对不对。
+
+同一条纪律往后延伸到 S3–S5：**硬事实必须可回溯**。等级、数值、距离、势力数量、
+谁对谁说了什么、某人出现在哪几章——这类事实写进聚合产物前，必须能回到某条白描或原文；
+回不到就写「原文未明确」，绝不用近义项、别处的例子或惯例补一个看起来合理的值。
+相邻实体的属性也不互相挪用：坐骑的等级不是骑手的等级，A 的台词不是 B 的台词。
+
+## 载体记录
+
+每章至少写一条，标准章节通常 2–5 条。它把「本章必须让读者知道什么」和
+「原文用什么把它写成场景」拆开——**这一栏是 S5 判断 `needs_carrier` 的原始数据**，
+没有它，后面只能凭印象说某个功能能不能拍。
+
+| 字段 | 写什么 |
+|---|---|
+| 关键信息 | 本章必须让读者知道、误判、期待或确认的事 |
+| 原文载体 | 作者用了哪些事件、对话、反应、细节、误导、回扣把它写成场景 |
+| 通道 | 这个载体主要走哪个通道：可见行动 / 对白 / 心理叙述 / 叙述者旁白 / 信息密度 |
+| 对读者的作用 | 好奇、期待、压抑、爽、心疼、紧张、甜、热血中的哪几种 |
+
+**通道栏决定下游判定**。 走可见行动或对白的，多半 `screen_ready`；走心理叙述或
+叙述者旁白的，多半 `needs_carrier` 或 `prose_only`。这里只记通道，不做判定——
+判定是 S5 的事，需要跨章看完才成立。
+
+过渡章也要写：说明它维持了什么期待或冷却了什么情绪，不写「无」。
+
+## 机械自检
+
+落盘后由主线程直接跑，命中即判失败，不依赖子代理自报。这些检查存在的理由是
+下游会按同样的字面形状 grep：格式漂一个字符，聚合阶段就会静默漏掉整章。
+
+```bash
+F=项目开发/source-analysis/chapters/ch-${N}-extract.md
+P=$(grep -cE '^P[0-9]+ ' "$F")
+grep -cE '^P[0-9]+ [^|]+\|[^|]*[^|[:space:]][^|]*\|[^|]*涉及' "$F"   # 必须 == $P
+grep -cE '^P[0-9]+ .*\|.*\|.*\|[^|]*功能：' "$F"                     # 必须 == $P
+grep -hoE '^P[0-9]+ [^|]+' "$F" | awk '{print $2}' | sort -u        # 必须 ⊆ 类型表
+grep -cE '^\|[^|]*\|[^|]*\|' "$F"                                  # 必须 >= 2
+```
+
+- 白描段计数少于 `$P`：有情节点缺白描，或字段顺序、分隔符不对。
+- 功能段计数少于 `$P`：有情节点没回答改变了什么。注意全角冒号——半角会漏。
+  这一条只数情节点行第四段里的 `功能：`：早先的写法数的是全文任何位置的这四个字符，
+  于是正文里提一句「功能」就会让计数超过 `$P`，把一份合规的提取判成失败。
+- 类型超出枚举：自造类型会让 S3 的归类整段落空。
+- 载体表行数少于 2：表头加至少一行数据。只核对表头存在，是数不出「表里一条记录都
+  没有」的——而 S5 判定 `needs_carrier` 要的正是那些数据行。
+
+文件名由 S2 的覆盖率闸门按字面匹配，写歪一个字符会进 `unmatched_files`——
+那既不算覆盖也不算缺章，改名即可，不必重跑。
+
+## 并发与串行
+
+**两条路径的写法要求和自检是同一份**，区别只有速度。
+
+- **并发**：每批 5–8 章，一批全部落盘再发下一批，每批结束更新 `_progress.md`。
+  每条子任务的提示必须自带材料授权前缀，说明这是创作者合法持有的虚构作品、
+  任务是只读的转化性分析、通俗题材的黑暗元素照常提取——否则子代理会把正常的戏剧化
+  情节误判为有害内容并拒绝整章，而主线程只会看到一个空结果。
+- **串行**：主线程逐章处理，同样跑机械自检。
+
+运行环境不支持子代理、或本技能已在子代理上下文里运行时，直接走串行，并在汇报里说明。
+
+## 失败处理
+
+| 情况 | 处理 |
+|---|---|
+| 子代理崩溃、超时、空输出 | 同条件重试 1 次 |
+| 机械自检不过 | 带上失败项重写本章 1 次 |
+| 重试仍失败 | 标记 `⚠️ 跳过`，写入 `_progress.md` 失败记录 |
+
+单章失败不阻断管道。但**跳过的章必须出现在每一份继承它的聚合产物里**——
+一份看起来完整、实际缺了第 47 章的分析，比一份明说缺章的分析危险得多。

package/lib/drama/skills/short-drama-novel-analyze/references/stage-contract.md

@@ -0,0 +1,67 @@
+# 原著分析阶段契约
+
+## 目录
+
+- [独立运行与项目集成](#独立运行与项目集成)
+- [所有权边界](#所有权边界)
+- [材料授权与只读转化](#材料授权与只读转化)
+- [本阶段规则](#本阶段规则)
+
+本文件是本技能的自包含契约：预检、所有权、材料边界与规则表都在这里，
+不需要读取其他技能的文件。
+
+## 独立运行与项目集成
+
+本技能可以单独安装并运行；下面几条说明项目工具存在时怎样集成。
+
+1. **读取直接输入**：只读取用户明确提供或当前任务实际需要的文件，不批量加载整个项目。
+2. **可选项目集成**：若存在 `short-drama.json` 且 core 项目工具可用，可以运行
+   `python3 <core>/scripts/project_tool.py status <project>`，使用返回的目录布局和语言设置；
+   core 不可用时，直接基于已提供输入产出本阶段文件。
+3. **可选发布生命周期**：项目工具可用时，用 `publish` 原子发布并用 `--input <path>`
+   声明直接输入；`accept`、`review` 与 `package` 继续承担确认、复核与交付。
+4. **保持职责分离**：创作者确认、内容修订和复核是不同动作；reviewer 提修改要求，负责人改文件。
+
+## 所有权边界
+
+- **本阶段拥有**：`项目开发/source-analysis/` 下的章节索引、改编价值快评、逐章提取、
+  剧情单元、节奏情绪、人物与设定候选、改编价值评估与分集候选。
+- **本阶段继承**：创作者提供的原始材料与授权说明、项目语言、已接受的形式约束与制作形态。
+- **本阶段不越权**：不改写 `输入/`；不写改编契约、创作简报、故事引擎或
+  `adaptation-map.jsonl`（`$short-drama-develop` 拥有）；不建资产身份；不写场景、台词、
+  分镜与提示词；不生成媒体；不批准自己的产物。
+
+分析层与决策层分开的理由很直接：**分析可以被推翻，契约不能**。把两者写进同一份文件，
+创作者就再也无法只推翻分析而保留已确认的改编承诺。
+
+## 材料授权与只读转化
+
+- 只处理创作者声明**合法持有、拥有使用权**的作品；授权不清时保留问题，不替创作者定案。
+- 分析是转化性的：提取结构与功能，不复制原文成段落，不模仿原作文风生成新文本。
+- 引用采用最短必要片段，并绑定 span。功能摘要必须是**去引用**的重述。
+- 通俗题材的暴力、复仇、背叛、情爱张力与黑暗伦理照常提取；个别片段无法处理时跳过并记录，
+  不中止整章或整本。
+- `输入/` 与其中的原始材料不进入交付包。
+
+## 本阶段规则
+
+### `NVA`
+
+| ID | Class | Knowledge |
+|---|---|---|
+| NVA-01 | structural_invariant | All stages slice the source through one chapter index built from that source; `verify` blocks on a chapter set whose numbering, ordering or line spans do not cover that source. An edited source still invalidates the index and everything derived from it, but only a changed line count or numbering is reported — a same-line-count rewrite in place is not, so whoever edits the source re-indexes it. |
+| NVA-02 | structural_invariant | Every extracted claim carries a source locator and span; a claim with no span cannot be cited downstream. |
+| NVA-03 | structural_invariant | Aggregation may not start while chapter coverage is incomplete; missing chapters are named in every aggregate that inherits the gap. |
+| NVA-04 | structural_invariant | Analysis records de-quoted function summaries, never copied source paragraphs. |
+| NVA-05 | structural_invariant | A sampled stage states its own coverage and confines every claim to the chapters it read. |
+| NVA-06 | reviewed_invariant | A function summary states what a passage does to character choice, information, power or relationship, not what happens in it. |
+| NVA-07 | reviewed_invariant | Hard facts — levels, counts, distances, who said what, which chapters a character appears in — trace back to a description line or the source; an unsupported one is written as unstated, never filled in by plausibility. |
+| NVA-08 | reviewed_invariant | Character merges preserve dramatic role, knowledge scope, relational position and causal bridge; only proper names and evidenced nicknames may merge, never descriptors or titles. |
+| NVA-09 | reviewed_invariant | Adaptation value distinguishes what the screen can show from what only prose can deliver, and names the new carrier for each function it keeps. |
+| NVA-10 | reviewed_invariant | Episode candidates are cut on local dramatic result and precise handoff, not on chapter count or word budget. |
+| NVA-11 | craft_default | Triage a deterministic spread of chapters across the whole book and stop for the creator before committing to a full pass. |
+| NVA-12 | taste_option | Where to open, which line to keep and which ending to promise remain creator choices; analysis may argue but never blocks. |
+
+规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
+`reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、
+`taste_option`（创作者选择，不作缺陷）。创作者已接受的事实优先于本表。