interface:
  display_name: "短剧开发"
  short_description: "把原创想法或长篇小说发展为故事引擎、系列弧线和逐集交接结构"
  default_prompt: "使用 $short-drama-develop 把我的短剧想法或长篇小说发展成故事引擎和分集地图；方向不清时再给少量可选择方案。"

# 短剧创作简报

> 复制到 `项目开发/creative-brief.md` 后填写。保留未知项为“待确认”，不要替创作者猜答案。方括号说明填写后删除。

## 1. 项目意图

- **暂定名**：【填写】
- **一句原始想法**：【尽量保留创作者原话】
- **这次要完成的工作**：【方向探索 / 系列开发 / 分集规划 / 定点修订】
- **来源材料**：【无，或填写创作者提供的本地材料引用】
- **不可更改的来源事实**：每条写清它在哪一集、以什么可见方式落地；本轮不落地的显式写延后到第几集。
  - 【事实 → 落在 EPxxx，观众看到的是：〈可见载体〉；或：延后到 EPxxx；没有则写“暂无”】
- **允许改编/探索的范围**：
  - 【填写】

## 2. 创作者契约

- **希望观众反复获得的体验**：【情绪、信息、关系或权力回报】
- **不希望作品变成什么**：【填写】
- **主题张力**：【两项难以兼得的价值，不先写结论】
- **语气与尺度**：【现实 / 浪漫 / 荒诞 / 克制 / 强烈等，由创作者描述】
- **结局承诺或禁区**：【已定则写明；未定写“开放”】
- **内容边界**：【填写】

## 3. 形式与制作边界

- **主要语言**：【填写】
- **画幅/观看场景**：【如有明确约束则填写】
- **单集与系列形式**：【仅记录创作者已选约束，不据此推导剧情】
- **可用角色与场景规模**：【填写】
- **难以承受的制作元素**：【填写】
- **必须保留的视觉/声音特征**：【填写】

## 4. 戏剧承诺（工作版）

- **焦点人物**：【谁承受压力并作选择】
- **当前追求**：【想得到、守住、查明或摆脱什么】
- **昂贵阻力**：【谁/什么能持续阻挡，以及它的筹码】
- **独特矛盾**：【主角有效策略如何同时制造代价】
- **反复回报**：【观众每一阶段期待看到哪类真实变化】
- **终止性转变**：【什么变化会让旧冲突引擎无法继续】

**一句工作陈述**：

【用自然语言连接以上决策；不是宣传语，也不强求固定句式。】

## 5. 方向候选与选择

> 方向已明确时只记录选定方向，不为凑数制造候选。探索时，候选必须改变机制而非只换包装。

### 候选：【名称】

- 主角惯常策略：【填写】
- 主要对抗机制：【填写】
- 退出成本：【填写】
- 反复回报：【填写】
- 核心代价：【填写】
- 引擎终止条件：【填写】
- 主要制作负担：【填写】
- 擅长提供：【填写】
- 会牺牲：【填写】

### 创作者选择

- **选定/组合**：【填写】
- **选择理由**：【填写】
- **明确拒绝的方向**：【填写；防止后续悄悄混入】
- **仍待确认的分支**：【填写】

## 6. 核心人物与关系压力

### 【角色名】

- 当前目标/意识到的追求：【填写】
- 保护对象/不可失去之物：【填写】
- 被捍卫的信念：【人物如何解释自己与世界；不要求“正确”】
- 形成该信念的前史成因：【只写仍会影响现在选择的过去】
- 惯常策略与优势：【填写】
- 策略盲区与代价：【填写】
- 可用筹码：【填写】
- 底线与可能越线条件：【填写】
- 可能改变其策略的事实：【填写】

### 核心关系：【角色 A ↔ 角色 B】

- A 需要 B / 害怕 B 看见 / 用来约束 B 的东西：【填写】
- B 需要 A / 害怕 A 拿走 / 用来反制 A 的东西：【填写】
- 当前不平衡：【填写】
- 可能发生的关系状态变化：【填写】

## 7. 叙事切入窗口与前史储备

- **故事切入前已经运行的压力**：【填写】
- **叙事切入窗口**：【从哪个必须行动的时刻开始】
- **为什么不更早/更晚开始**：【更早会变成什么准备；更晚会丢掉哪个选择】
- **开场可见证据**：【让观众从行为、物件、关系或异常结果反推前因】
- **观众现在必须知道**：【只列当前行动所需】
- **观众暂时不需要知道**：【继续保留，不塞入首集说明】

### 前史储备

| 过去事实 | 如何解释当前选择 | 作者是否需要 | 观众何时/通过什么可见载体得知 |
|---|---|---|---|
| 【填写】 | 【填写】 | 【需要 / 可省】 | 【现在 / 延后 / 不展示；载体】 |

## 8. 成功条件与待确认项

- **本轮产物必须保住的创作者选择**：【填写】
- **可以由后续单集继续发现的空白**：【填写】
- **若不确认会改变故事方向的问题**：
  - 【填写；没有则写“暂无”】
- **不会阻止继续工作的次要未知项**：
  - 【填写】

## 9. 接受记录

- **预览版本/日期**：【填写】
- **语义变化摘要**：【填写】
- **创作者状态**：【待选择 / 已选择待接受 / 已接受 / 需修订】
- **创作者备注**：【填写】

# 短剧故事引擎

> 复制到 `项目开发/story-engine.md` 后填写。这里只记录能预测选择、升级和交接的事实；不要扩写成世界观百科。

## 1. 已接受的戏剧承诺

- **来源**：【creative-brief 的版本/引用】
- **焦点人物与追求**：【填写】
- **昂贵阻力**：【填写】
- **反复回报**：【填写】
- **核心代价**：【填写】
- **终止性转变**：【填写】

## 2. 引擎回路

### 压力怎样启动

【填写会反复出现、但能产生不同局面的触发来源。】

### 主角惯常怎样应对

- 策略：【填写】
- 为什么有效：【填写】
- 为什么同时制造新问题：【填写】

### 对抗力量怎样学习与反制

- 对抗者/约束：【填写】
- 目标与筹码：【填写】
- 能封住主角哪条路径：【填写】
- 受到压力后会怎样改变策略：【填写】

### 一轮冲突怎样留下下一轮压力

```text
触发：
→ 主角选择：
→ 反制：
→ 局部结果：
→ 新代价/状态变化：
→ 下一股压力：
```

### 为什么人物不能轻易退出

【填写关系义务、现实限制、身份、承诺或自我认同成本。】

## 3. 可升级的状态

> 只保留会影响选择的维度；不必填满。

| 状态维度 | 当前起点 | 可能怎样变化 | 变化会迫使谁作什么选择 |
|---|---|---|---|
| 权力/许可 | 【填写】 | 【填写】 | 【填写】 |
| 知识/误信/证据 | 【填写】 | 【填写】 | 【填写】 |
| 关系/联盟/债务 | 【填写】 | 【填写】 | 【填写】 |
| 暴露范围 | 【填写】 | 【填写】 | 【填写】 |
| 资源/时间 | 【填写】 | 【填写】 | 【填写】 |
| 物理状态 | 【填写】 | 【填写】 | 【填写】 |
| 道德代价 | 【填写】 | 【填写】 | 【填写】 |

## 3b. 前提装置契约（仅当设定包含先知或外部授权能力时填写）

> 没有这类装置就整节删除。**这里是创作者层的契约**，可以从一开始就写全，不要求向观众
> 披露；剧中披露到哪一步记在分集地图的信息权限栏，两者分开核对（`STY-17`）。

装置类型：【先知型 / 授权型 / 两者兼有】
契约状态：【draft / accepted】——`accepted` 之后才可让装置在剧中生效。

每条能力、限制或代价单独成行并给一个**稳定条款 ID**（`DEV-01`、`DEV-02`…）。后续任何
一集出现的装置能力或豁免都要能指回某个条款 ID；指不回去就是事后扩权。

| 条款 ID | 类型 | 内容 | 首次生效 | 可靠性 |
|---|---|---|---|---|
| DEV-01 | 能力范围 | 【装置能做什么，边界在哪】 | 【集号或"未生效"】 | 【可靠 / 会误述 / 未定】 |
| DEV-02 | 失效条件 | 【什么情况下不生效、精度下降或反噬】 | 【…】 | 【…】 |
| DEV-03 | 使用代价 | 【可见的、主角在意的代价，除消耗外的后果】 | 【…】 | 【…】 |

- **可靠性**列决定装置的宣告能否被当真。标为「会误述」的条款，后续揭穿时观众要能回看出
  线索；这属于已设计的不可靠，不是失约。
- 需要新增条款时走修订：先改本表并让创作者接受，再在剧中披露。**不得先在某一集写出来，
  事后再回填条款。**
- 装置只调整信息与能力的分配，不改写题材的压力来源、观众回报与结局承诺。

## 4. 人物行动模型

### 【角色名 / 稳定 ID（如已有）】

- 意识到的追求：【填写】
- 被保护的价值/关系/身份：【填写】
- 被捍卫的信念：【人物用什么判断证明自己合理】
- 前史成因：【哪件旧事让信念与策略曾经有效】
- 自我解释：【他怎样证明自己合理】
- 惯常策略：【填写】
- 可用筹码：【填写】
- 持续盲区：【填写】
- 底线与越线条件：【填写】
- 可能改变策略的事实/关系：【填写】
- 压力下的语言与行为变化：【填写】

### 人物跨集进展

| 角色 | 进入策略 | 压力测试 | 选择/回撤 | 局部结果与代价 | 离开时的可见策略 |
|---|---|---|---|---|---|
| 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【填写】 |

## 5. 关系压力网

### 【角色 A ↔ 角色 B】

- A 从 B 处需要：【填写】
- A 害怕 B 看见/拿走：【填写】
- A 约束 B 的筹码：【填写】
- B 从 A 处需要：【填写】
- B 害怕 A 看见/拿走：【填写】
- B 反制 A 的筹码：【填写】
- 当前权力位置：【填写】
- 可发生的关系位移：【填写】

## 6. 信息与证据设计

| 事实/问题 ID | 世界中实际事实 | 谁知道/误信什么 | 观众何时知道 | 可见证据 | 改变谁的选择 |
|---|---|---|---|---|---|
| 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【填写】 |

### 铺垫与兑现义务

| setup_id | 首次出现位置 | 初始自然理解 | 承诺回答的问题 | 计划兑现/改义方式 | 状态 |
|---|---|---|---|---|---|
| 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【填写】 | 【计划 / 已兑现 / 有意悬置 / 待解决】 |

### 跨集记忆最小集

> 每集接受后只更新变化；正文事实与摘要冲突时，以 accepted 正文为准并修订摘要。

- **人物**：【当前目标、策略、被测试的信念、代价、物理状态】
- **关系**：【权力位置、信任/债务、最近一次越线】
- **信息权限**：【世界事实；各角色与观众知道/误信/未知】
- **活跃铺垫债务**：【已埋未回、计划回扣、受影响位置】
- **双轨节奏落点**：【外部压力；内在情感负荷；下一集承接/对比理由】
- **精确交接**：【位置、动作、持物、伤势、时间、进行中的决定/危险】

## 7. 主题进入选择

- **难以兼得的价值**：【价值 A ↔ 价值 B】
- **主角起初的行动答案**：【填写】
- **其他人物的不同答案**：【填写】
- **剧情如何让这些答案付出后果**：【填写】
- **创作者希望明确/保留含混的部分**：【填写】

## 8. 视觉、声音与制作方向

- **核心场域为何适合发生冲突**：【填写空间与行动关系】
- **反复出现且会改变意义的物件/声音**：【填写】
- **视觉气质与色彩/光线方向**：【只写创作方向，不写生成参数】
- **声音气质**：【填写】
- **场景、角色、动作规模边界**：【填写】
- **明确不采用的表现方式**：【填写】

## 9. 引擎终止与变形

- 哪项人物变化会让旧策略失效：【填写】
- 哪项事实公开会让旧对抗无法继续：【填写】
- 哪段关系变化会终止/改造压力回路：【填写】
- 终止后希望留下的情绪与主题结果：【填写】
- 结局仍开放的部分：【填写】

## 10. 分集交接原则

- 每集需要兑现的承诺类型：【填写】
- 可用于持续运动的状态维度：【填写】
- 绝不能无原因重置的事实：【填写】
- 允许的叙事例外（跳时/梦/单元式等）：【填写】
- 分集地图开始前仍待解决的问题：【填写】

## 11. 接受记录

- 来源简报版本：【填写】
- 本次相对变化：【填写】
- 创作者状态：【草稿 / 待接受 / 已接受 / 需修订】
- 创作者覆盖了哪些默认建议及理由：【填写】

# 改编压缩、合并与信息视觉化

## 目录

- [改编契约](#1-先建立改编契约)
- [长材料导入](#长材料导入先建立可追溯语义层)
- [功能账本](#2-用功能账本压缩)
- [信息视觉化](#3-信息视觉化阶梯)
- [因果桥](#4-保住因果桥)
- [单集化](#5-单集化而不肢解)
- [登记不等于兑现](#5b-登记不等于兑现)
- [分级审查](#6-规则分级与审查)

改编不是把原文缩短，也不是为短剧补一套流行结构。目标是保留原材料真正承担的戏剧功能，
再为屏幕、单集边界和制作条件寻找新的载体。

## 1. 先建立改编契约

| 类别 | 含义 | 处理 |
|---|---|---|
| 不可改承诺 | 核心关系、关键选择、结局含义、必要世界规则 | 保持事实与功能 |
| 可换载体 | 叙述顺序、场景、配角、信息出现方式 | 可压缩/合并，但记录替代关系 |
| 可删冗余 | 重复说明、只连接路程的段落、无新状态的复述 | 删除并说明没有损失什么 |
| 未决歧义 | 原材料本身矛盾或授权不清 | 保留问题，不替作者定案 |

不要把“更短”当作唯一目标。删掉的段落可能很短，却承担信任转变；保留的奇观可能很长，
却没有推动人物选择。

### 长材料导入：先建立可追溯语义层

小说、多集散稿或混合格式不能直接交给剧本索引器。保留原始字节与来源说明，由 agent
按章节、场景变化、叙述视角、时间跳转和行动因果做语义分段；每段记录 source span、
人物称谓、地点、生产相关物件、信息权限、戏剧功能和低置信歧义。统计/正则可帮助定位
重复称谓或候选段落，但不能判断人物同一性、关系、场景功能或分集边界。

原始小说或散稿始终保存在不交付的 `输入/`；`项目开发/adaptation-map.jsonl` 只保存
输入文件的 locator、byte/line span、去引用的功能摘要、未解析称谓/物件，以及该功能
保留、合并、换载体、删减或进入哪个候选分集与可能损失。不得把来源原句或连续段落复制到
development，避免交付包把输入材料带出边界。

分集候选按局部戏剧结果和准确交接组织，不按章节号、字数或关键词机械切分。创作者接受
改编与分集决定后，write owner 才写/规范化 canonical `screenplay.md`，assets owner 再从
接受剧本生成可发布 occurrence 与资产决策。导入阶段可以展示人物/场景/物品**候选预览**，
但它只是 develop-owned proposal，必须带来源与 `unresolved`，不能写入资产 设定集，也不能在
角色合并、删场或道具换载体之前冒充最终资产库。

### 写下游内容时定点回原文

改编不是把原著通读一遍就再也不回头。写分集、写某一集时，经常需要回原文取具体细节——
动作顺序、物件在谁手里、围观者的反应、某句话实际起的作用。这一步有两种稳定的失败：
**查不准**，和**查到了不该用的**。

**查询用事件锚点，不用概念词**。 原著里反复出现的概念词（能力名、境界名、组织名、
主题词）会在几十处命中，返回的片段横跨全书各阶段，很难判断哪一段对应当前进度。事件
锚点是三样具体东西的组合：**谁 + 在哪里或用什么 + 正在做什么或与谁冲突**。锚点越像
一个具体场面，命中越集中。

- 弱：`修炼 突破 功法`
- 强：`<角色名> 后院 药炉 当众被夺`

命中为空时，换一组**更具体**的锚点重查，而不是退回更宽的词——宽词命中更多，可用的更少。

**命中之后回读原文段落，不要凭检索摘要写**。 摘要最先丢掉的正是你要取的东西：动作
先后、谁先开口、东西在谁手里。

**最容易被忽略的一条：命中可能来自故事后段**。 概念词尤其容易把后期章节拉进来。来自
更晚阶段的段落，其中的人物关系、知情范围和能力边界都已经推进过；直接拿它写当前集，
会让人物提前知道此刻不该知道的事，或提前拥有还没得到的手段。这类穿帮很难在后面被发现，
因为它读起来完全通顺。

判定办法：把命中片段的**知情状态**与当前集的进入状态逐项对照——片段里谁已经知道了什么、
谁已经与谁结盟、主角手里已经有什么。任何一项超前，这段就只能作为风格或信息参考，
不能作为当前集的依据。

**召回只补细节，不新增剧情**。 已接受的分集契约决定这一集发生什么；回原文是把已经
决定的事写具体。原文里另有更好看的段落时，它要走修订已接受契约的路径，由 develop
owner 改分集地图，而不是在写正文时顺手塞进来。

**`craft_default · STY-22`**：回原文取细节时，用"人物 + 地点/物件 + 当前动作或冲突"
的事件锚点检索，回读命中段落而不是凭摘要写，并在使用前把片段的知情状态与当前集进入
状态对照；超前的片段只作参考。召回用于补足已接受契约的细节，不用于新增剧情。

## 2. 用功能账本压缩

**`STY-07 · reviewed_invariant`**：人物或场景合并必须保留戏剧作用、知情范围、
关系位置和因果桥；“人更少”不能单独证明合并成功。

为候选人物、场景和信息记录它承担的功能：

- 谁迫使主角作选择；
- 谁持有证据、秘密、资源或社会许可；
- 哪个场景改变权力、知识、关系、风险或物理状态；
- 哪段建立后续兑现所需的误信/承诺；
- 哪个空间限制让冲突必须现在发生。

### 先删线，再合并

删掉整条支线和合并人物是两种操作，判据不同，顺序也不能反。**先删线**：合并是把功能
重新分配给某个人，如果这个人所在的线随后被删，刚做的分配全部作废，而且往往已经带着
它改过分集地图。

删整条线的判据不是"这条线好不好看"，而是**删掉之后主线还成不成立**：

1. **它的兑现是否被保留的线依赖**？这条线的结果如果是别处铺垫的兑现，或是别处兑现的
   铺垫，删掉就断桥。查 `payoff_ids`/`setup_ids` 两个方向，不要只查一个。
2. **主角是否靠它获得行动手段**？某条线是主角获得证据、盟友、权限或技能的唯一来源时，
   删掉它等于让主角在后面凭空拥有这些东西。
3. **它提供的是世界规模还是主线推进**？只负责让世界显得更大的支线，在竖屏连续短剧里
   是最便宜的删除对象——观众为主线的兑现节奏付费，不为世界的广度付费。
4. **它是否是某个信息权限落差的唯一来源**？某条线的作用是让观众知道而主角不知道时，
   删掉它会让后面所有"观众替他着急"的场次一起失效。
5. **删掉后会留下多少孤儿铺垫**？前面为它埋的每一处都要跟着删或改指向。孤儿铺垫比
   支线本身更伤：它们看起来像伏笔，观众会一直等。

**最常见的错误删法**：把节奏慢的线删掉、把好看的线留下。慢线经常正是让快线成立的
条件——铺垫、代价、信息落差都住在慢线里。删掉之后快线还在，但它不再打中人。

删线时把这条线承担的功能逐项列出来（用本节开头的功能账本），标明每一项是**一起删掉**
还是**转移到哪条保留的线**。转移的每一项都要写清接收方多承担了什么；只写"合并到主线"
等于没有交代。

### 合并人物

只有当两个角色的功能可以由同一人的目标、知识范围和关系位置自洽承担时才合并：

1. 两人是否原本知道不同事实？合并后会不会提前泄密？
2. 两人是否分别代表支持与压力？合并后对抗是否消失？
3. 两段关系是否需要不同历史/伦理位置？
4. 同一演员在同一时点能否完成两项行动？
5. 合并后某个背叛、证言或牺牲是否失去代价？

弱合并：“配角太多，所以把两个人改成同事甲。”
可用合并：“门店会计与房东都阻断账本获取；改为房东兼代账人，但把原会计掌握而房东
不知的假发票来源转给另一条证据链。”

### 合并场景

场景可合并需同时满足：时间/地点能连续、两个议程可以同场碰撞、信息出现不改变因果顺序、
合并后每个关键反应仍有空间。不能只因“都在办公室”就把隔日后果塞进同一分钟。

## 3. 信息视觉化阶梯

**`STY-08 · craft_default`**：优先尝试有后果的行为、证据、空间压力或对话策略，
再决定是否保留中性说明。

将“人物知道/回忆/解释”依次尝试转成：

1. **行动后果**：他不报门牌，直接用旧钥匙开门；
2. **可争夺证据**：缺页、录音、伤痕、持物、屏显；
3. **空间行为**：谁挡出口、谁避开座位、谁能触到证物；
4. **对话策略**：试探、误导、讨价、逼供、拒绝，而非中性说明；
5. **声音/主观表达**：VO/OS/主观画面，只有作品明确选择时使用。

视觉化不等于“每句话配一个动作”。来回倒水、走窗边、翻无关文件若不改变议程或证据条件，
只是制造假运动。

## 4. 保住因果桥

压缩时间后逐项检查：

~~~text
原因事实 -> 人物理解 -> 选择 -> 对手反制 -> 可见后果 -> 新压力
~~~

若删除的段落承担“人物为何相信”“对手如何得知”“道具如何到手”，需在新版本建立等价且
可见的桥，不能用一句“原来如此”跳过。

大幅重排时写改编功能对应表：

~~~json
{
  "source_function": "<原功能，不复制长原文>",
  "new_carrier": "<新人物/场景/证据/动作>",
  "preserved": ["<承诺/因果/关系>"],
  "lost_or_changed": ["<可能损失>"],
  "status": "proposed | creator_accepted | unresolved"
}
~~~

## 5. 单集化而不肢解

短剧单集应完成一个局部状态变化，同时保持长线：

- 当集兑现原材料的一部分吸引力；
- 结尾压力由本集选择/后果产生；
- 不靠把一个完整反应切掉来制造“卡点”；
- 下一集的进入状态是精确事实，不是“局势更紧张”。

可把一段长叙事拆成多集，但每集都要回答“本集观众具体得到了什么”。

## 5b. 登记不等于兑现

被自己登记为不可更改的来源事实，最容易的失败方式不是写错，是**写进简报之后再也没有回来**。
它在文件里，所以每次审查都读到它、每次都算数；而观众一次都没有看到。

判据是一句话：**这条事实，观众在本轮要写的集里从哪一个画面能得到它**？逐条回答，答案只有两种：

- **落在第几集、可见载体是什么**——那个载体必须真的被写进那一集的分集记录与剧本；
- **显式延后到第几集**——写下集号，本轮不欠。

两种都答不出来的，它就不是“不可更改的事实”，是一句备注，按备注处理。

同一个失败也发生在单集内部：分集记录写了“可见载体”“载体直接支持的判断”，剧本却从没演过
那个载体。最常见的一种是需要对照才成立的证据——“装置生效前后哼的同一句，音准完全不同”——
剧本只写了“之后”，“之前”从没上过屏幕，于是这条信息释放在纸面上成立、在画面上不成立。
写完剧本后按分集记录的可见载体逐条回读一遍，比事后审查便宜得多。

**`STY-23 · reviewed_invariant`**：简报登记为不可更改的来源事实，在本轮覆盖范围内要么有一处
写进了分集记录与剧本的可见载体，要么显式标注延后到某一集；分集记录声明的可见载体必须在对应
剧本里实际出现，需要对照才成立的载体两端都要出现。

## 6. 规则分级与审查

- `structural_invariant`：来源与功能对应表、授权边界、铺垫、兑现和交接引用都能解析。
- `reviewed_invariant`：合并没有造成知情穿帮，压缩没有删断因果，新的表现方式保留核心含义。
- `craft_default`：优先用选择、证据和空间后果承载说明；有明确风格理由时可以调整。
- `taste_option`：保留旁白、倒叙、多声部人物、慢场或开放结尾均是创作者选择。

审查时引用“原功能 → 新载体 → 损失/保持”，不要用与原材料的表面相似度代替判断。

# 创作参考作品的安全摄取

用户提供对标剧、小说、分镜样例或提示词时，学习它解决问题的机制，不召回它的表达外壳。
本流程只读取用户在当前会话明确提供或授权的材料；不自行连接外部、非公开项目库。

## 1. 先声明本次参考职责

为每份材料记录：来源 locator、用户允许的用途、本次要解决的问题，以及它是主参考还是
补充参考。主参考也不天然拥有创作者权威；任何可迁移选择都要先变成候选，再由创作者接受。

- **主参考**：回答一个主要问题，例如悬疑怎样逐步缩小安全空间；
- **补充参考**：只补一个不同维度，例如群体反应或二维运动预算；
- **无关材料**：与当前问题无关时不加载，避免多部作品的表层元素混成一锅。

材料过长时先按用户问题选择相关段落和完整因果窗口，不能用关键词命中代替阅读上下文。

## 2. 从观察写到机制，不从表面写到仿写

先区分“原材料里直接发生了什么”“agent 如何解释”“仍不知道什么”，再写去引用的
机制摘要，把表层桥段压缩成“观众状态 → 戏剧问题 → 可选机制 → 可见效果 → 失效边界”：

```yaml
reference_mechanism:
  source_ref: 输入/references/<locator>
  purpose: 本次参考要回答的问题
  direct_observation: 对功能的转述，不复制原句
  audience_state: 观众进入这一段时知道、期待或误信什么
  dramatic_problem: 要解决的戏剧问题
  optional_mechanism: 可选机制怎样改变信息、权力、关系、路线或代价
  visible_effect: 可见效果由什么行动、物件、空间或反应承载
  applies_when: 适用的观众承诺、人物状态与制作条件
  failure_boundary: 失效边界、反例或需要换法的信号
  may_influence: [因果功能, 信息释放, 场面职责]
  must_not_copy: [文风, 原句, 独特情节顺序, 专有设定, 人物关系组合]
  uncertainty: 仍需创作者决定或另找反例的部分
```

`may_influence` 只列当前项目可以重新选择的功能；`must_not_copy` 保护来源表达。若一项发现
离开人物名、专有设定或原句就说不清，它还不是可迁移 know-how，不进入写作上下文。

## 3. 下游只读取去引用候选

原材料与 observation 留在非公开 `输入/` 边界；develop/write 只消费经创作者接受的
机制候选：当前问题、适用条件、可选机制、可见效果、失效边界与禁止复制项。不要把原文、
“语感片段”、整段对话、独特反转顺序或多部作品的风格摘要塞进写作 prompt。

一次只召回与当前场景或分集问题直接相关的少量机制。需要另一维度时再读取另一张卡，
而不是按“参考越多越好”扩大上下文。

## 4. 做迁移检验再交给创作者

用完全不同的题材、人物关系、场景和措辞解释该机制；若仍能说明它解决什么、怎样观察
效果、何时失效，才算完成抽象。随后比较至少一个替代机制，说明各自制作负担与潜在副作用，
让创作者选择、组合或拒绝。

参考作品不是质量证明。当前项目的剧本与提示词仍要凭自身因果、可表演性、连续性和制作
文本接受审查；“与参考相似”既不能批准，也不能单独否决。

# 导演阐述工艺：拆分/分镜前的项目级指令

## 目录

- [基础写法](#基础写法)
- [可选写法](#可选写法按场景选用可组合)
- [反模式](#反模式)
- [拆分参数](#拆分参数配套)

来自对导演阐述如何约束完整生产链的定性案例阅读，示例均为合成改写。导演阐述是
整条流程里影响很大的人工输入：写在拆分/分镜之前，约束全剧后续工作——分镜
格式、摄影职责、节奏方向和已知能力条件。在本套件中，它落入
`short-drama.json#/creator_authority` 中的 `visual_direction` 与 `production_profile`，
由本技能在 `项目开发/director-brief.md` 中起草候选并展示语义差异。创作者接受后，
由 `$short-drama` 路由提升到 creator authority 才生效；本技能不直接写 creator-owned
配置，也不替代各环节对本环节文件的最终归属。

## 基础写法

```text
你负责把《剧名》已确认的剧本和设定编成可审查分镜。先读取创作者已接受的题材承诺、
人物视角和 `production_profile`；保留行动顺序、信息权限和逐字对白。若视觉实现需要
改变上游事实，提出带证据引用的修订请求，不在下游静默改写。
```

## 可选写法（按场景选用，可组合）

### 可验收约束型（项目需要稳定规格时）

每条规则都应能对交付文本和后续制作结果追溯，但“可验收”不等于先填一套镜头数量、
景别比例或秒数。先说明当前项目为何需要这条约束、它保护哪项上游必保内容、
什么证据允许例外，再由创作者接受：

```text
【本项目接受的约束】
- 空间：当观众尚不能定位入口、人物或冲突区域时，先建立完成当前理解所需的地理；
  上游材料有意延迟识别或前镜已经建立时，不补仪式化全景。
- 身份与状态：同一人物绑定已接受的 `identity` 与本段有效 `Look`；有来源的换装、伤损
  或伪装走 `variant`，无来源漂移不得进入。
- 连续性：相邻镜逐字段比较手、朝向、持物、位置与可见状态；跳时、蒙太奇或有意
  断裂按上游授权记录，不用“必须补过渡”抹掉剪辑意图。
- 对白与接收：切镜由议程、权力、信息或选择的变化决定；只有听者承担后果时，才要
  为其可见接收保留空间，景别和停留由表演与节奏决定。
- 结尾：先完成本集局部结果，再保留由结果启动的压力；特写、定格、切黑或不断镜
  都是候选实现，不预设一种收尾动作。
```

可选制作方案包括色温/光比、留白、节奏停顿、同场动作、反应安排和台词量。
具体数值只能来自本项目试跑与创作者选择；台词量从镜头时长、语速与表演动作反推，
多人同镜只要求指代可唯一解析，比喻只在目标模型无法执行时改写为物理表现。

**服装、光影、构图分别决定参考权限**：参考图只负责已声明的用途 `role`，提示词只
重复当前执行容易漂移的局部事实。同一镜可以让身份参考控制脸型，让 `Look` 参考控制
服装，同时由文字说明本镜光向；不要求在“全写文字”和“整图托管”之间二选一。

### 单集导演阐述型

按本集需要说明它在全剧的位置、必须改变的状态、分场注意力或节奏转折依据；不必凑齐
栏目。适合首集、大结局或转折集单独加写，功能数量和节奏形状由本集材料决定。

### 风格速记型（多项目复用）

用简短文字记录创作者已经选定的方向，并说明适用条件：

- `追逐段以方向清楚和呼吸受压为主；只有行动转向或风险位置变化时切镜。`
- `审讯段保持冷硬侧光；若证据需要可读或人物选择需要停留，优先保证信息承载。`

### 按已知制作能力写表演（项目已有证据时）

只把创作者已提供并接受的测试记录写进 `production_profile`：

- **可观察表演**：情绪词可保留为意图，但至少用与人物和触发相符的准备动作、面部
  微动作、肢体联动或重心变化承载；不要求每镜填满固定维度；
- **记录失败原因而非词表**：写清哪种表达在什么镜头、参考条件和制作方案下不可执行，
  以及当前采用的可观察替代；不把形容词或生理细节汇成跨题材禁词清单；
- 权力反转先确认旧权力如何成立、什么证据使其失效、谁必须接收后果，再选择同镜、
  反应镜或群体状态变化；不把题材标签翻译成固定阶段和固定景别；
- 特殊视角设计入阐述层（"将镜头固定在轮胎上拍车内人物"）。

能力条件不能从其他项目移植。若没有可追溯的测试记录，保留供应商无关的通用表达，
不猜可用词、并发量、时长或成片结果。

### 跨集人物弧线（长篇项目可选）

**跨集人物弧线与节奏方向在这一层统筹**，再写入分集表并交给各环节执行。阶段数与
边界来自人物选择、关系或信息权限的实际门槛；每阶段绑定有效范围、镜头语言职责与
节奏目的，不按固定集区间切块：

```text
阶段：公开同盟开始破裂后，直到主角主动承担代价
镜头语言职责：把多线压力汇到同一选择；只有注意力或风险位置改变时加速切换。
节奏目的：从被动防守收紧到不可撤回的决定，并保留决定后的反应时间。
```

再把方向绑定到有明确引用的剧情节点；手持、平行蒙太奇、升格或首尾呼应只有在承担该节点
的注意、时间或关系职责时才进入，不先用标签填满集区间。

## 反模式

1. **把剧本塞进导演阐述**（整集原文塞进指令字段）——指令与内容混流。
2. **空泛形容词**："画面高级有电影感"——无法验收。每条规则问一句：拿着成片
   能不能判定它被遵守了？
3. **无证据的能力规则**：从其他项目复制禁词、并发量或镜头配方，覆盖当前人物和已确认内容。

## 拆分参数配套

- 按集拆分：明确本集局部戏剧结果、代价与后续压力；文字量从目标时长、
  台词语速、动作和停留空间反推。
- 按字数拆分容易切断场景目标、行动转向或反应职责；项目若仍选择这种方案，必须在
  切点复核场景与交接内容。需要明确制作信息时，优先先改成剧本格式再拆。

若创作者选择量化制作方案，数值只在其已接受范围内成为验收约束。“禁改台词”与
相邻镜已确认边界的核对属于套件硬规则，不因写法流派而放松。

# 短剧分集与单集设计

## 目录

1. 分集的工作定义
2. 规则分级
3. 单集契约
4. 钩子、兑现与出去的压力
5. 因果节拍与升级链
6. 场景化之前的可见性检查
7. 系列弧线与分集地图
8. 集间状态交接
9. 扩写、压缩与重排
10. 合成示例
11. 失败征兆与审查问题

## 1. 分集的工作定义

一集不是被时长切下来的一段情节，而是一次有边界的状态变换：

```text
可验证的进入状态
→ 当集压力迫使人物追求目标
→ 选择遭遇反制并产生后果
→ 观众获得当集承诺的部分回报
→ 一个具体的新决定、危险或问题形成下一步压力
→ 可验证的出去状态
```

分集设计的重点是“这一集为什么必须在这里发生”，不是把事件均匀分配。

## 2. 规则分级

- **`structural_invariant`**：进入/出去状态、分集/铺垫/兑现引用是否存在，显式声明是否互相矛盾；校验器可阻断。
- **`reviewed_invariant`**：因果是否真实、升级是否改变局面、兑现是否匹配承诺；审查者须给出证据。
- **`craft_default`**：通常能加强单集运动的做法；创作者可说明理由覆盖。
- **`taste_option`**：钩子形态、弧线形状、转折烈度、留白程度；只由创作者和作品气质决定。

数字形式约束可以记录为创作者选择，但不能反过来证明剧情质量。

## 3. 单集契约

在写节拍或剧本前，先为本集回答以下字段。

### 3.1 进入状态

只写会影响本集行动的事实：

- 人物位置、持物、伤势或正在执行的行动；
- 谁知道什么、误信什么、掌握什么证据；
- 谁占主动，谁欠谁，谁与谁结盟或疏远；
- 上一集留下的决定、危险或未完成动作；
- 本集必须接住的视觉、声音或时间事实。

不要把整本设定复制进每集。进入状态要足以让本集第一场行动不凭空出现。

### 3.2 当前压力与钩子

“钩子”不是一句神秘台词，而是观众能立即理解的未稳定局面：

- 某人正在执行高代价行动；
- 一个看似正常的事实与可见证据矛盾；
- 有时限的目标已经开始；
- 先前选择的后果现在抵达；
- 某人必须公开作决定；
- 一个关系中的权力突然改变。

钩子要连接本集目标。若开场刺激与后续无因果关系，它只是装饰。

**可选的结果预演**：家庭、悬疑或关系戏有时先给观众看一个未来结果，再回到造成它的
决定。只有两段由同一关系动作、道具或场所事实清楚相连时才使用；否则会像无来源的
预告片。它是叙事选择，不是每集开场要求。

### 3.3 目标与反对力量

目标用“人物想让谁/什么在本集结束前发生怎样的变化”表达。反对力量要有：

- 自己的目标；
- 能真正阻挡的筹码；
- 对主角策略的理解或误解；
- 受到压力时会采取的动作。

环境、制度、身体限制也能成为反对力量，但最好通过人物选择获得戏剧形态。

### 3.4 因果升级

不要预填“发生若干次冲突”。写成选择链：

```text
因为进入状态中的事实 A，人物采取行动 B；
行动 B 触发反制 C；
C 让状态 D 改变，迫使人物放弃旧策略或付出更大代价；
新选择 E 产生本集的方向性转折。
```

### 3.5 方向性转折

转折意味着人物原来的计划、理解或关系位置不再适用。它可能是：

- 主角主动更换策略；
- 对手封住既有路径；
- 证据使旧解释失效；
- 一段关系改变立场；
- 代价真正落地；
- 人物拒绝了原本最想要的东西。

不要求每集使用秘密或身份变化。

### 3.6 当集兑现

兑现回答：“观众为什么不会觉得这一集只在拖延？”

可以兑现：

- 看见主角真实能力或代价；
- 回收先前问题的一部分；
- 完成一次关系/权力变化；
- 让承诺中的情绪落地；
- 让人物作出不可撤回的选择；
- 证实或推翻一个有依据的判断。

**`craft_default · STY-04`**：在留下新压力前，先给出本集自己的局部结果。开放结尾与未完成一集不是同一件事。

### 3.7 出去状态与交接

结尾不只写“悬念：他是谁”。写成下一集可执行的事实：

- 谁刚作出什么决定；
- 谁知道了什么，谁仍不知道；
- 权力、关系或资源怎样改变；
- 人物在哪里、拿着什么、能否行动；
- 哪个危险已经开始而非可能出现；
- 下一集开场必须保留什么。

**`structural_invariant · STY-05`**：所有进入/出去、铺垫/兑现引用应指向已知记录，或显式标记为未决。相邻集对同一事实的显式声明不得无解释冲突。

### 3.8 每集只写这一集独有的东西

分集记录**不是把这一集的所有信息抄一遍**。判据只有一条：

> 删掉这个字段，写剧本的人会不会失去一个重要的创作约束？

答案是"不会"的字段，要么删掉，要么放到只写一次的地方。按这条判据，下面几类**不进**
分集记录：

- **可以从别的字段推导出来的**。单步因果链就是"目标 → 反对 → 结果 → 出去的压力"，
  把它再写一遍不产生新约束；只有一集里确实有两步以上、后一步依赖前一步的结果时，
  才需要单独写因果链。
- **整部戏只发生一次的**。人物的跨集转变属于故事引擎的
  [人物行动模型](../assets/story-engine.md)，信息权限模型属于同一份文件的信息与证据设计。
  在每一集重写一遍，只会让同一句话出现在八个地方。
- **解释性的**。"为什么这个钩子连着本集目标""为什么这股压力由本集产生"是**理由**，
  不是约束。理由由审查者从已有字段判断，不需要作者逐集自证。
- **给字段本身分类的**。钩子属于哪一型、节奏是强是弱，这些标签不改变任何一句剧本。

留在分集记录里的，是**只有这一集才知道的事实**：进入状态、本集目标与反对、转折的触发、
局部结果、出去的压力、交接状态，以及本集要用到的资产与连续性变化。

一集只有一步因果时，它没有独立的因果链字段，单集卡里的实现块也就没有步骤可指——
此时直接写三个可见载体（选择、反制、状态变化），不写指向某一步的指针。真的有两步以上、
后一步依赖前一步结果时，才写因果链，实现块再逐步对应。

一个副作用值得知道：字段越多，越容易被"填满"而不是被"想清楚"。同一句话被抄进六个槽位
时，记录看起来完整，实际只作了一个决定。

## 4. 钩子、兑现与出去的压力

这三项承担不同工作：

| 部件 | 观众问题 | 常见误用 |
|---|---|---|
| 钩子 | 为什么现在就要看？ | 与本集无关的奇观或故弄玄虚 |
| 兑现 | 这一集给了我什么？ | 只重复承诺，不产生结果 |
| 出去的压力 | 为什么状态还会继续运动？ | 隐去一句信息便草草结束 |

### 4.1 选择钩子类型

根据本集运动选择，而不是轮换模板：

- **行动钩子**：人物已在执行高风险策略；
- **后果钩子**：上一集的选择立即反噬；
- **矛盾钩子**：话语与证据同时出现且不相容；
- **关系钩子**：熟悉关系出现新的权力位置；
- **决定钩子**：人物必须现在选择，拖延本身也有代价；
- **信息钩子**：观众获得能重排现场意义的事实。

**`taste_option · STY-06`**：可以安静开场、延迟解释、让观众先知道或让角色先知道；只要当前压力可感知并服务作品气质。

### 4.2 设计出去的压力

有效的出去压力来自本集结果，而非随意添加的新事故。可用以下问题：

- 本集的胜利让谁失去东西，从而会怎样反制？
- 新知识让谁必须立刻重选立场？
- 人物为赢付出的代价何时到期？
- 哪个被保护的人拒绝继续被保护？
- 现在公开的事实把冲突带到哪个新场域？

**`craft_default`**：结尾尽量把“会发生什么”升级成“某人已经决定做什么”或“某个后果已经启动”。

**`taste_option`**：一集也可以在完整情绪落点结束，不强制悬置；下一集压力可以来自新阶段而非截断动作。

### 4.3 创作者声明的门槛集

有些项目的观看契约里存在一个**门槛集**：观众要继续看下去，必须先付出一点额外代价——
解锁、跳转到另一个入口、等待，或完成某个平台动作。门槛是否存在、落在哪里，**由创作者
按项目声明**；本套件不设默认位置，不假定任何平台规则，也不把门槛位置当作质量判据。

门槛不新增规则，它让本文件已有的三条**在这个位置收紧**——因为别处失手观众只是走神，
这里失手观众直接离开：

- **出去的压力**（[4.2](#42-设计出去的压力)）：门槛后面必须还欠着观众一样东西。刚兑现
  完一次大回报就设门槛，观众此刻的状态是"满足"，而满足的人不会为继续看下去付出额外
  代价。别处可以停在完整落点，这里不行。
- **兑现依赖已建立的事实**（`STY-09`）：门槛处的悬念若依赖观众还不认识的人、还没理解
  的规则或还没看见的赌注，它对观众并不成立——没有投入过的问题不会让人付代价。
- **每集都有局部结果**（`STY-13`）：越靠近门槛，越不能出现只做交代、不产生结果的集。
  观众在这一段流失，就永远走不到门槛。

门槛集本身仍是普通一集：有自己的局部结果，出去的压力仍从本集结果长出。门槛只是给
"停在哪里"这个选择多加一层约束。

**`craft_default`**：项目声明了门槛集时，把它安排在一次尚未兑现的爆发之前，并确认门槛
处的悬念只依赖观众已经建立起来的人物、规则与赌注。集号、比例、是否设门槛都由创作者
决定；套件不提供默认值。

## 5. 因果节拍与升级链

### 5.1 一个节拍要回答什么

每条节拍至少记录：

- `because_of`：来自哪个进入事实或前序节拍；若开启新线，明确声明；
- `character_goal`：当前行动者想改变什么；
- `opposition`：谁/什么在此刻阻止；
- `observable_action`：可见或可听的行动；
- `state_change`：信息、权力、关系、情绪、风险或物理状态的前后差异；
- `next_pressure`：结果怎样迫使下一步发生；
- 相关铺垫与兑现引用。

**`structural_invariant`**：节拍必须引用一个原因，或声明开启新线；字段存在不代表因果成立。

**`reviewed_invariant`**：审查者判断“因为”是否真的改变了人物选择。只按时间先后排列的事件仍可能是空链。

### 5.2 用“所以/但是”朗读

把相邻节拍连起来：

```text
因为前一结果，所以人物现在这样做；
但是对抗力量利用新状态反制；
所以人物必须改变策略或承担代价。
```

如果只能用“然后”，检查是否缺少：人物选择、对抗反应、可见后果或下一股压力。

这是一种诊断语言，不要求成品按该句式呈现。

### 5.3 判断重复与升级

对比两个相邻冲突：

- 谁掌握的筹码变了？
- 谁知道的事实变了？
- 哪段关系的边界变了？
- 哪条退路消失了？
- 谁作出了不可撤回的决定？
- 哪个后果从威胁变成现实？

**`reviewed_invariant · STY-03`**：若没有可引用的变化，不能只凭更强烈的表演词声称升级。

**`craft_default`**：让主角的有效策略产生新的盲区，让对手学习，而不是每轮都回到同一起点。

## 6. 场景化之前的可见性检查

节拍将交给剧本写作，因此要提前检查它是否有戏剧载体：

- 冲突能否发生在人物必须行动的具体场域？
- 信息能否通过证据、争夺、行为或后果出现，而非纯说明？
- 内在变化由什么选择、停顿、身体行为或关系动作承载？
- 关键道具文字、声音或空间限制是否是故事必需？
- 转折发生后，人物下一动作是否改变？

**`reviewed_invariant`**：关键节拍需要可转译成可见/可听的行为。审查者描述缺失载体及其影响，而不是用关键词筛选心理词。

**`taste_option`**：旁白、画外音、主观画面或留白都可选，只需明确其叙事意图。

### 6.1 转折要写成那一下动作，不是那一下的功能

分集记录的字段名会诱导人写功能：`turn` 问触发是什么，`local_dramatic_result` 问改变了什么，
`opposition` 问对方要什么、筹码是什么。这些问题都可以用一句正确的话回答完，而一句正确的话
不是一场戏。

最常见的形态是把转折写成它的**结果**：

| 写成功能（不够） | 写成动作（够） |
| --- | --- |
| 他不再讲道理，用自己的信用担保 | 群里问他是不是急了的内部人士，有人跟着起哄；他把打了一半的辩解删掉，只发出一条链接 |
| 裁决权从立场转移到作品本身 | 刚才喊举报的那个人点开了视频 |
| 上级选择维持现状 | 上级把申请表推回来，说等有了成绩再谈 |

左栏读起来都对，而且**审查时不会被任何门拦下**——它们是对的功能描述。但把左栏交给剧本层，
写作者拿到的是一个待发明的结论；把右栏交给剧本层，写作者拿到的是一场戏。

判据是一句话：**这一拍，观众看见的是谁做了什么**？答不上来的，说明记录停在了功能层。
不要求分集记录写完整场次——那是剧本的活；要求的是**转折与本集结果各自都能指出一个具体的
可见动作**，哪怕只有半句。

同一条纪律适用于`opposition`：反对力量的筹码要写成它**做过或会做的事**，
不是它的属性。「人多、态度一致」是属性；「他们已经约好一起去平台投诉」是筹码。

**`STY-24 · reviewed_invariant`**：本轮覆盖范围内每一集的方向性转折与当集兑现，
在分集记录里各自要能指出一个具体的可见动作（谁做了什么），而不只是它达成的功能或状态变化；
反对力量的筹码同样写成已发生或将发生的行为。审查者引用「功能 → 对应的可见动作」，
指不出可见动作即为缺陷；这一条不用关键词筛，也不要求写成完整场次。

## 7. 系列弧线与分集地图

系列弧线不是把传统结构名称贴到集号上。先画状态运动：

1. **旧策略可用**：人物用熟悉方式获得局部结果，同时制造债务；
2. **旧策略被学习/反制**：同一方式开始伤害人物珍视的东西；
3. **选择成本显形**：人物必须在不能兼得的价值间行动；
4. **引擎变形或终止**：新事实、能力、关系或决定使旧回路无法照常继续。

这些是功能，不规定阶段数量、集数或位置。作品可以跳跃、循环、倒叙或以单元故事承载长线变化。

### 7.1 分集地图的列

每一行只保留能帮助写作与交接的字段：

- 集 ID、工作标题；
- 进入状态与活动压力；
- 当集目标和反对力量；
- 关键选择及其后果；
- 方向性转折；
- 当集兑现；
- 出去压力与精确交接；
- 铺垫/兑现引用；
- 连续性变化与未决问题。

一行地图应能回答“删掉这集会损失什么状态台阶”。答不出时，合并、重设转折或让这集承担明确结果。

### 7.2 长线与单集的双重责任

一集可以同时：

- 完成一个局部目标；
- 改变一段关系；
- 让长线证据前进；
- 让主角策略积累代价。

不需要每项都出现。关键是当集有自己的可识别结果，并对系列状态作出至少一项必要贡献。

## 8. 集间状态交接

### 8.1 写成事实，不写气氛词

弱交接：

> 关系更加紧张，危机升级。

可执行交接：

> 叶澄把店门钥匙交给齐曼，但没有告诉她备用账本在冷柜后；齐曼已答应天亮前让审查员进入厨房。

后者给出持物、知识差和已作决定，下一集能直接行动。

### 8.2 逐项核对

- **知识**：谁知道/误信/隐瞒什么；
- **权力**：谁有许可、证据、资源或公开话语权；
- **关系**：承诺、背叛、联盟、边界；
- **物理**：位置、伤势、造型状态、持物、门锁、天气、时间；
- **行动**：已经开始、被中断或必须完成的动作；
- **情绪**：只记录会改变下一步行为的情绪选择，不记录泛泛强度。

**`structural_invariant`**：上一集出去事实与下一集进入事实显式不一致时，需要修订归属或合理的时间/事件说明，不能静默忽略。

**`reviewed_invariant`**：即使字段不冲突，知识、关系或伤势也可能无原因跳变；审查者必须引用前后证据。

## 9. 扩写、压缩与重排

### 9.1 何时扩写

扩写不是增加闲聊，而是当前地图跳过了必要的选择：

- 人物突然改变立场，却没有受到足够压力；
- 证据出现，却没有获取、验证或争夺过程；
- 代价被宣布，却没有落到关系或行动；
- 重大决定后没有让受影响人物作出回应。

新增节拍时明确它补足哪条因果或哪个状态变化。

### 9.2 何时压缩

以下内容可以合并或删除：

- 重复说明观众已经知道的事实；
- 人物用同一策略遭遇同一反制，状态没有变化；
- 只负责移动人物且没有产生选择的过场；
- 两集拥有同一个进入状态、目标、转折和出去状态。

### 9.3 何时重排

重排前先检查依赖：

- 人物是否提前使用尚未获得的知识或道具；
- 关系变化是否在原因之前出现；
- 铺垫是否晚于兑现；
- 伤势、时间、位置和公开范围是否仍连续；
- 观众信息顺序改变后，体验是否仍是创作者要的悬念/惊讶。

**`structural_invariant`**：重排后所有引用与显式交接必须重新解析。

**`taste_option`**：允许倒叙、并行、跳时或主观叙事；声明其意图和连续性例外即可。

### 9.4 容量可行性预算 (`STY-16`)

第 1 节说一集不是被时长切下来的一段情节——这仍然成立，戏剧边界决定一集在哪里结束。
但一集写完之后要被拆成镜头、再变成有时长的画面，所以它**同时**占用一份制作容量。
这两件事不冲突：戏剧边界决定内容，容量预算只回答“这份内容装不装得下”。

不做这个检查的失效方式很具体：分集地图上每集看起来都合理，直到剧本交到分镜环节才发现
某几集的镜头数是别人的两三倍，于是要么临时砍戏（砍掉的往往正是兑现），要么让这几集
超长（打乱已接受的集数与节奏）。发现得越晚，能改的越少。

**`craft_default`**：进入场景化之前，用项目自身**已接受产物**的比例做一次量级估算，
把明显超出的集在地图阶段就调整。

估算方法（用比例，不用外部数字）：

1. 从本项目已经接受的集里取样，算出该项目当前的两个比值——每个镜头平均承载多少剧本
   体量，以及每个镜头平均占用多少时长。
2. 用这两个比值把待写各集的预估体量换算成镜头数与时长量级。
3. 与创作者已接受的集长和产物预算比较，只关注**量级偏差**（例如某集是同项目均值的两倍
   以上），不关注小幅波动。

**这不是质量门槛**。 比值来自项目自己的历史，不是跨项目标准；换题材、换制作形态或换
交付容器方式，比值都会变。所以：

- 偏差是**提示**，交给创作者判断，不阻断任何交付；
- 处理偏差优先用 9.1–9.3 的手段（把超载集拆成两集、把说明改成传递、合并同质节拍），
  而不是按数字删台词或删镜头；
- 项目还没有已接受集可取样时（例如只写第一集），跳过这一步，等有了基准再回来算。它的
  价值来自项目自身的一致性，用别处的数字代入反而会误导。

**跳过估算不等于第一集没有时长兜底**。 这里做的是**预测**：用已接受集的比值推算还没写的
集，所以第一集拿不到。等第一集的镜头真的存在了，另有一次**测量**——把本集镜头的已接受
时长直接加总，与项目声明的每集目标时长比对。测量不需要基准，第一集同样成立，它属于分镜
环节的账目责任（见该环节的单集时长加总规则），不在本节重复。

**`taste_option`**：单集长度、集数、每集镜头量级由创作者的格式与发行方案决定。

## 10. 合成示例

沿用一个全新虚构情境：一家共享厨房面临关停，排班员叶澄一直暗中调换灶位保护弱势摊主。

### 单集契约示意

- **进入状态**：叶澄刚删去一条换班记录；齐曼持有自己的订单记录，但尚不知道谁删改；物业审查员将在早晨进入。
- **当前压力**：齐曼当众要求出示完整排班记录。
- **目标**：叶澄想在不暴露删改的情况下说服众人维持营业。
- **反对力量**：齐曼要恢复公开规则；管理方可以借混乱立即收回排班权。
- **升级链**：叶澄展示整理后的记录 → 齐曼用订单证明缺口 → 叶澄承认改过排班但拒绝说为谁 → 被保护的新摊主主动承认并质问谁有权替他决定。
- **转折**：问题从“谁占了灶位”转成“叶澄是否有权以保护为名隐瞒”。
- **兑现**：订单缺口的原因被部分回答；叶澄的能力和代价同时显形。
- **出去压力**：叶澄把备用钥匙交给齐曼；齐曼已承诺让审查员进场，但不知道冷柜后的账本。

### 因果诊断

弱节拍：

> 众人争吵。管理方突然通知审查提前。叶澄很紧张。

改成可用链条：

> 因为齐曼公开证明排班记录缺口，管理方把“内部争执”作为提前进场的理由；叶澄若继续藏账本就会失去营业资格，若交出账本则会暴露所有私下调整。她把钥匙交给齐曼，却故意不提账本位置。

差别不在事件更多，而在前一选择改变了对手筹码，人物随后作出带代价的新选择。

## 11. 失败征兆与审查问题

### 失败征兆

- 开场压力与当集目标无关；
- 集内只有信息宣布，没有人物争取与反制；
- 各节拍可以任意换序；
- “升级”只是更大的争吵、追赶或误会；
- 本集所有答案都被推迟到下一集；
- 结尾用省略一句话制造假悬念；
- 出去状态只有情绪形容，没有知识、关系、物理或行动事实；
- 下一集重置上一集的决定和代价；
- 为适配形式而拆出无状态贡献的集；
- 把某种钩子或转折当成所有项目的必选项。

### 审查问题

审查者引用 `episode-map.jsonl`、单集卡或节拍记录回答：

1. 本集从什么进入状态运动到什么出去状态？
2. 哪个选择触发了哪项反制，证据在哪里？
3. 方向性转折后，人物的行动为什么必须改变？
4. 当集承诺具体在哪里兑现，而不是只被重复？
5. 出去压力是否由本集结果产生？
6. 相邻集的知识、权力、关系、持物和行动是否可精确交接？
7. 哪些形式选择属于创作者偏好，是否被保留？

开发/写作所有者可根据发现修订，但不能签发自己的最终通过结论。

# 题材条件与钩子手册

这份参考资料来自对不同题材完整“剧本—资产—分镜—提示词修订”链的定性阅读。
它只保留可以用在新项目里的故事推进方法和常见问题，不保留项目名、原台词、内部 ID、原提示词、媒体
地址、供应商字段或题材频次。这里没有热度排名，也没有按标签自动套用的剧情公式。

本手册负责**跨题材的比较**：同一条轴线上，不同题材怎样分岔。单个题材的执行细节
（场面颗粒、集尾钩子取向、前中后期打法、该题材特有的制作成本）拆在
[genre-cards.md](genre-cards.md) 索引下的题材卡里，一次只读一张。
两层的分工是：先用本手册确认压力机制选对了，再用题材卡校准这个题材更常用的落点。

## 目录

- [使用方式](#使用方式先看故事怎么运转不先认标签)
- [不同题材怎么推进](#不同题材怎么推进)
- [悬疑与规则恐怖](#悬疑与规则恐怖每过一道险关都要有实质变化)
- [家庭与关系戏](#家庭与关系戏从照料推进到证据和公开后果)
- [古装奇幻与身份戏](#古装奇幻与身份戏让礼制和地位先被看见)
- [职场与喜剧](#职场与喜剧用流程证明能力用反差制造笑点)
- [身份错位喜剧](#身份错位喜剧让外部任务逼身份作选择)
- [生活流与小人物](#生活流与小人物让小目标留下真实余波)
- [开场选择](#开场选择从旧办法开始付出代价处进入)
- [钩子](#钩子要接着本集结果往下走)
- [制作难点](#提前写清制作难点)
- [审查问题](#审查问题)

## 使用方式：先看故事怎么运转，不先认标签

题材标签只用来帮助找到可能相关的写法。真正要选择的是：

1. **压力从哪里来**：规则、关系、证据、制度、空间、资源还是身体限制；
2. **人物怎么应对**：主角靠隐藏、照料、专业能力、权威、交易、逃避还是冒险解决问题；
3. **观众每集看到什么结果**：真相、关系、权力、路线、身份或生存条件怎样变化；
4. **谁知道什么**：谁知道、误信、怀疑，谁能把事情说出来或公开；
5. **观众具体看到什么**：哪个行为、物件、空间变化或群体动作能证明结果成立；
6. **制作难点**：哪些造型/状态、场景/方位、道具/状态、群体区域、必须照抄的文字或
   镜头起止状态需要持续追踪。

同一“悬疑”可以由空间规则、关系谎言或技术证据驱动；同一“爱情”可以走互助、权力
不对等或身份冲突。只有故事推进方式和当前条件相符时才借用下文；不相符就回到
[story-craft.md](story-craft.md) 重新想清故事怎样持续推进。

## 不同题材怎么推进

这张表比较的是**轴线上的差异**，不是各题材的完整写法。选定方向后，到最后一列的题材卡里
取该题材的场面颗粒、钩子取向、前中后期打法和特有成本。

| 题材方向 | 压力怎样持续 | 每段先给什么结果 | 制作时必须拍清什么 | 常见问题 | 题材卡 |
|---|---|---|---|---|---|
| 悬疑 / 规则恐怖 / 生存 | 安全规则逐步失效，可走的路、可用的时间和保护手段越来越少 | 查明一条能决定下一步的新事实，同时失去一条退路 | 门槛、路线、计时、有明确用途的关键道具、感官异常与受限身体状态 | 只把黑暗、噪声和形容词变强；旁白替代可见验证 | [悬疑规则](genre-cards/悬疑规则.md) |
| 家庭 / 照料 / 关系伦理 | 私人义务与自我保护互相冲突，经济/照料/名誉筹码可执行 | 关系边界、证据归属或公开地位改变 | 往复照料动作、便携证据、见证人分区、退出路径 | 群体重复谴责，人物没有新选择或执行能力 | [家庭关系](genre-cards/家庭关系.md) |
| 亲子 / 血缘揭示 / 认亲 | 关系尚未被承认，监护、抚养与就学就医的硬期限持续逼近答案 | 名分或责任真的落地：签字、称呼、接送、监护归属改变 | 签字与关系栏、接送与等待、可验证的检验流程、孩子自己带来的物件 | 孩子只负责卖萌撮合，没有自己的目标；血缘结果自动等于情感结果 | [亲子隐秘](genre-cards/亲子隐秘.md) |
| 古装 / 奇幻 / 婚恋 / 隐藏身份 | 礼制、阶序、阵营与公开选择限制关系 | 行为让隐藏地位或联盟获得新的公开解释 | 造型、随行层级、身份道具、入场方式、空间区域与知情者反应 | 奢华/寒酸形容词堆叠；突然报身份代替此前证据 | [古装权谋](genre-cards/古装权谋.md) / [仙侠修真](genre-cards/仙侠修真.md) / [豪门婚恋](genre-cards/豪门婚恋.md) / [破镜重圆](genre-cards/破镜重圆.md) |
| 职场 / 技术 / 轻喜剧 | 一个日常工作疏漏造成越来越具体的后果 | 别人能当场核对的修复结果，随后角色地位改变 | 必须照抄的技术名称、操作顺序、核对点、屏幕/设备状态与见证更新 | 同事先夸“天才”；通用屏幕特写；人人同一惊讶反应 | [职场喜剧](genre-cards/职场喜剧.md) |
| 复仇 / 权力反转 | 对手拥有真实手段，主角以证据、联盟或能力改变实际权力 | 一项旧权力失效并产生后果，而非只获得口头认可 | 证据链、公开场合、对手反制、受影响者的反应与代价 | 重复受辱—亮牌；身份揭示不改变任何人的行动空间 | [复仇打脸](genre-cards/复仇打脸.md) |
| 动作 / 任务 / 冒险 | 地理、资源、时间与对手学习共同收窄可行路径 | 完成一个阶段目标并留下伤势、损耗、暴露或路线变化 | 轴线、出入口、距离、持物、能力边界、伤势与交接 | 动作更大但任务状态不变；同一镜承担过多力学阶段 | [动作任务](genre-cards/动作任务.md) |
| 身份错位 / 身体互换喜剧 | 外部任务迫使人物用不合身的身份、身体或权限解决现实问题 | 任务状态先改变，再让身份误读带来关系或地位余波 | 当前身份占用、别人如何识别、身体能力边界与多主体位置 | 设定梗不断重复，任务和人物策略没有进展 | [身份错位](genre-cards/身份错位.md) |
| 生活流 / 小人物 / 都市温情 | 一个具体小目标被来客、误会、匮乏或照料义务打断 | 小事被实际完成、放弃或重新理解，关系留下轻微但可见变化 | 日常物件、距离、手部选择、环境节奏与留白 | 套用真人爽剧的密集大特写和公开翻盘，压扁生活质地 | [生活流](genre-cards/生活流.md) |

这张表只是提问清单，不是题材判定器。混合题材可以把几种做法放在一起，但要说清
主要矛盾是什么、观众先看到哪个结果，以及制作要求会不会互相打架。

题材卡同样不是判定器：它是可被创作者一句话覆盖的 `craft_default`，一次只读一张，
跨题材时主卡读全、辅卡只摘一两条。召回规范与冲突优先级见 [genre-cards.md](genre-cards.md)。
本手册下文的各题材小节保留跨题材共用的因果链与失败征兆；具体到某一部戏怎么落，以卡片为准。

## 悬疑与规则恐怖：每过一道险关，都要有实质变化

规则恐怖不是不断宣读更多规则。每过一道安全线，都要让局面真的变掉：

```text
暂时安全的状态
→ 计时、封闭空间或逃生路线出现能被人物验证的小破口
→ 人物试探并得到局部发现
→ 空间、身体或保护手段受到无法马上恢复的限制
→ 旧策略失效，下一步只能承担更高代价
```

条件化做法：

- 先让保护行为真的改变行动条件，例如堵住入口、交出唯一光源、限制移动，而不是只给
  关系温情；
- 每过一道险关，先让人物和观众看清一种新变化，避免怪物、变形、解释、群体
  反应和摄影花样同时争夺注意；
- 完整揭示前，可先让失败者、受损物或失效路径证明威胁会造成什么；
- 有明确用途的关键道具从取得、未启用、触发、画面可见的启用状态、可用次数/进度、
  代价到恢复，保持前后一致，
  这一串状态由资产环节记录并逐镜传递，本阶段只需在分集地图里说明它必须被追踪；
- 下集压力可以停在安全距离被突破、救援路线被封，但本集必须先完成发现、
  试验结果或路线变化，不能只在惊吓前切黑。

失败时先问“这次过关后，谁能做什么、不能做什么”，而不是再加阴影、尖叫或规则 VO。

## 家庭与关系戏：从照料推进到证据和公开后果

家庭戏的强度不来自更响的责骂，而来自私下发生的事带来真实后果。一个可调整
的因果链是：

```text
互相照料或共同承受匮乏，让双方彼此有了牵挂和亏欠
→ 私人排斥/伤害留下可携带证据
→ 受影响者作出自我保护选择
→ 证据进入有人能作出决定或采取行动的公开场合
→ 不同见证者各自获得一条新事实并改变行动
→ 退出、保护、作证、让路或约束真正改变权力
```

- 预示未来结果再回到决定性选择，只在同一关系/物件锚点能让两段互相解释时使用；
  不是所有家庭戏都需要倒叙；
- 群体反应按“能做什么”分区：知情者、能作决定的人、利益相关者、旁观者。每组只在
  新事实改变其行动时反应，不能用一圈惊叹代替实际后果；
- 照料既可以证明爱，也可以成为控制手段；保留双方各自的实际手段和底线，不预设团圆、
  原谅或公开反击才是正确结局；
- 关键文件/录音/账目若是证据，先确定文字要清楚可读、只保留图形，还是留到后期制作，
  不能让“大家看见了”建立在不可读画面上。

## 古装奇幻与身份戏：让礼制和地位先被看见

隐藏身份要让观众觉得可信，就要先用行为和画面埋下依据。对白前可以用平行剪辑，
表现两个角色或阵营同时进行相似的礼制，再用少量而明确的画面信息表达不平等：

- 已确定的造型与佩饰用途；
- 随行者的类别/队形，而非把每个群众都扩张成个人资产；
- 谁拥有、递交或拒绝哪件身份/礼制道具；
- 到达方式、可进入区域、谁必须停在哪条界线外；
- 一个已知内情者如何压住或错开反应，而不是提前宣布答案。

身份揭示应由人物在公开场合的选择触发：例如拒绝服从、承担关系代价、使用先前建立的
权力，让旧解释失效。突然出现一位旁人报出头衔，只能传递信息，不能替代前置行为和选择。

“华丽”“破旧”“威严”都要落到当前故事职责，不把固定材质、身材、肤色或布光当
阶级或性别判断。群体调度和代表性反应见
由分镜环节按可见的站位、视线与阻挡关系落实；本阶段只写谁必须在场、谁必须看见。

## 职场与喜剧：用流程证明能力，用反差制造笑点

职场能力揭示先从一个普通流程缺口开始：文件没归档、权限没交接、设备步骤被跳过、
现场无人愿意承担。后果可以荒诞，但因果要直：

```text
组织遗漏产生具体故障
→ 集体依据错误解释扩大问题
→ 被忽视者找出确切的文件、设备或位置
→ 按观众能看懂的顺序操作，并经过一个能核对结果的步骤
→ 设备、流程或现场恢复，别人能当场核对
→ 见证者依其职责逐个更新判断
→ 结果之后才改变角色权限或地位
```

喜剧来自整个机构的慌乱与人物克制之间的反差、被压住的反应和简短落点，不来自笑点数量。
若文件名、命令、表单字段或设备读数直接决定结果，就必须照抄。剧本、分镜和提示词都
要指向同一内容；画面看不清时，不能让同事用一句“修好了”代替证明。

失败征兆是所有同事先说主角厉害、屏幕只写“复杂代码飞速滚动”、每个旁观者重复同一
惊讶。先恢复操作链和结果，再决定是否需要反应镜。

## 身份错位喜剧：让外部任务逼身份作选择

身份互换、灵魂错位或人/非人身份喜剧需要一条不依赖设定梗的外部任务线：完成工作、
保护某人、取得物件、通过检查或离开空间。每一段先推进任务，再让当前身份限制改变做法：

- 明确谁占用哪种身体/身份，谁知道、误信或怀疑；变化写入身份状态与连续性，而不是靠对白提醒；
- 让身体能力、职业权限、语言方式或社会期待制造可执行阻力，人物必须调整策略；
- 多主体同场时先交代位置和观察关系，让观众知道误认如何成立；
- 任务取得局部结果后，身份错位才作为反应、关系后果或收尾按钮再次发力。

若删去身份设定后这一段没有欲望、阻力和结果，说明设定梗正在取代故事。身份形态的制作
本阶段需要从制作形态取得哪些输入，见 [阶段契约](stage-contract.md) 的“制作形态需要什么”。

## 生活流与小人物：让小目标留下真实余波

生活流不是没有戏剧运动，而是把变化控制在人物日常能承受的尺度。可从一个具体小目标
开始：修好物件、等到某人、守住摊位、还一件东西或完成一次照料。意外来客、误会或匮乏
让旧做法受阻；人物通过一个细小选择完成、放弃或重新定义目标，再以温柔反转或远景余韵
留下关系变化。

低强度不等于无因果。仍要看见物件归属、距离、去留、承诺或理解发生了什么；只是不要求
公开打脸、身份宣告或每段都升高音量。二维漫剧可以利用 hold pose、局部循环、环境声和
留白承接余韵，不要把真人爽剧的密集大特写、眼部推进和群体震惊当成提速办法。

## 开场选择：从旧办法开始付出代价处进入

不规定第几秒或必须哪种景别。比较几个入口，选择能让观众立刻追踪因果的一处：

- 人物正在使用惯常办法，异常结果让这套办法开始带来损失；
- 日常仪式出现一个会改变人物处境的小错误；
- 一个关系请求同时触碰双方不能兼得的义务；
- 已经发生的后果通过一件看得见的东西或行动再次出现；
- 观众比角色多知道一条会影响下一步的事实，或少知道一条必须追问的原因。

开场可以安静、喜剧化、亲密或激烈。通常应让观众感到压力，并看见一个还没解决的问题，
不是固定时长、台词数量、冲突音量或镜头类型。更完整的切入方法见
[serial-character-and-memory.md](serial-character-and-memory.md)。

## 钩子要接着本集结果往下走

钩子要从本集已经发生的结果继续往下走。先写“本集已经改变什么”，再选择一件尚未
解决、而且确实由这个结果引出的事：

| 本集留下的问题 | 可形成的下集压力 | 不成立的替代品 |
|---|---|---|
| 选择带来的代价 | 人物作出的选择即将要求下一项代价 | 无来源的新人物踹门 |
| 旧证据有了新解释 | 同一载体现在支持更窄/更危险的新解释 | 只喊“你竟然不知道真相” |
| 对手反制 | 对手根据主角刚暴露的策略封住路径 | 反派重复上一集威胁 |
| 代价到达 | 先前成功造成伤势、债务、关系或资源损失 | 黑屏前把结果全部藏住 |
| 谁能采取行动发生变化 | 新事实让某人能公开真相、逃离、作证、进入或拒绝 | 群众只重复惊叹 |
| 安全线或出口变化 | 安全距离、出口或可达区域发生变化 | 只把环境写得更阴暗 |

温馨落点、完整收束或无悬念结尾同样是创作者选项。连续多集使用相似的收尾方式不必自动
报错；审查者应判断它们是否改变了不同状态、是否兑现承诺，而不是数“钩子类型”。

## 提前写清制作难点

开发阶段就在候选方案旁写清主要制作负担，不要等到提示词阶段才发现：

- **状态数量**：关键道具、伤势、礼制造型、证据版本是否跨镜或跨集复用；
- **空间**：安全线、公开场合、仪式区、办公室操作点是否需要不同场景方位；
- **群体**：谁是需要反复出现的角色，谁是代表性见证者，谁只属于背景人群；
- **文字/声音**：规则、技术名称、文件或称呼要清楚可读、只保留图形、用 VO/OS，
  还是留到后期；
- **动作**：哪一段操作、仪式、保护或险情变化必须拆成清楚的镜头起止状态；
- **修订风险**：同一剧本重做时，必须比较内容覆盖、资产版本、必须照抄的文字、
  镜头起止状态与镜头分组方式，不能因为提示词变短就认定内容更准确。

这些负担帮助创作者比较方案，不决定题材优劣，也不要求实际生成媒体。

## 审查问题

1. 这个候选使用的是真实压力机制，还是只有题材名称和常见外壳？
2. 本轮升级具体改变知识、关系、权力、路线、资源、身体或代价中的哪一项？
3. 观众具体看到或听到什么？这些画面或声音能证明到哪一步？
4. 隐藏身份、怪物规则、技术能力或家庭伤害是否已经有行为和画面证据，而非突然说明？
5. 群体中的不同人是否因新事实获得不同的实际行动空间，还是只合唱同一反应？
6. 下集压力是否由本集已经发生的结果造成？删掉黑屏后，本集还留下了什么结果？
7. 这个故事需要哪些资产状态、空间方向、必须照抄的文字和连续性记录？方案有没有考虑
   这些制作难点？
8. 是否把案例里的数字、景别、材质、性别气质或句式误升成通用规则？

审查结论要引用当前项目证据。题材频次、模板相似度、关键词命中和固定节拍都不能替代
这些问题。

# 题材卡索引

这里只做**索引与召回规范**。每个题材的可执行内容拆在同目录的 `genre-cards/` 下，一次只读一张。

题材卡回答"这个题材更常用哪些压力、场面和情绪落点"，不回答"这一集应该怎么写"。
后者由创作者已接受的事实、单集契约和 [episode-design.md](episode-design.md) 决定。

## 目录

- [召回规则](#召回规则)
- [冲突优先级](#冲突优先级)
- [题材卡一览](#题材卡一览)
- [跨题材与未覆盖题材](#跨题材与未覆盖题材)
- [不要把卡片写成硬规则](#不要把卡片写成硬规则)

## 召回规则

1. 先确认主题材、目标形态（实拍/漫剧）、创作者已声明的尺度与结局承诺，再来查表。
2. 查到匹配项后**只读那一张卡**，不要把整套题材卡加载进上下文。
3. 跨题材时：主题材读 1 张完整卡，辅题材只摘 1-2 条"常见场面颗粒"或"禁止漂移"。
   不要把两套打法并行铺满，先说清主要矛盾是什么、观众先看到哪个结果。
4. 传给下游的题材注入只保留与当前集相关的条目，短到能被完整读进上下文即可；写不满不必凑，写不下先删与本集无关的条目。可用条目：
   压力来源、人物策略与信息权限、本集要落的回报、可用的场面颗粒、钩子取向、禁止漂移、卡片置信度。
5. **题材卡只在内部校准题材味，绝不出现在交付物里**。剧本、分集地图、创作简报中不得出现
   卡名、题材标签、置信度、条目编号或"已按题材卡执行"一类合规自评——只交付作品本身。
6. 中置信卡不能单独决定方向：先结合创作者的设定、已接受的故事引擎和本项目的制作边界，
   再决定采纳哪几条。表中没有的题材按[跨题材与未覆盖题材](#跨题材与未覆盖题材)处理。

## 冲突优先级

题材卡的权限低于项目事实，高于通用手感。按本套件的四类规则读：

```text
创作者已接受的事实、结局承诺与改编边界（structural_invariant / creator authority）
→ 已接受的单集契约、进入/出去状态与铺垫兑现义务（structural_invariant / reviewed_invariant）
→ 题材卡（craft_default，创作者说明理由即可覆盖）
→ 通用工艺参考与叙事手感（craft_default / taste_option）
```

- 题材卡永远是 `craft_default`：它可以被创作者的一句"这部不这么走"直接推翻，且不需要额外论证。
- 题材卡里的钩子取向、情绪落点、结局气质属于 `taste_option`，任何审查者都不得据此单独阻断。
- 题材卡**不能**创造 `structural_invariant`。它不产生 ID、引用或可被校验器阻断的约束。
- 与 [genre-and-hook-playbook.md](genre-and-hook-playbook.md) 冲突时：手册负责跨题材共用轴线的比较，
  卡片负责单题材的执行细节；若两者对同一题材的说法不一致，以卡片为准并记录理由。

## 题材卡一览

| 题材 | 别名与匹配词 | 题材卡 | 置信度 |
|---|---|---|---|
| 复仇打脸 | 复仇 / 打脸 / 逆袭 / 权力反转 / 扮猪吃虎 / 隐藏身份归来 / 清算 | [复仇打脸](genre-cards/复仇打脸.md) | 高 |
| 古装权谋 | 古装 / 权谋 / 朝堂 / 宅斗 / 宫廷 / 门第 / 礼制身份戏 | [古装权谋](genre-cards/古装权谋.md) | 高 |
| 悬疑规则 | 悬疑 / 规则怪谈 / 规则恐怖 / 惊悚 / 生存 / 密室 / 灵异 | [悬疑规则](genre-cards/悬疑规则.md) | 高 |
| 家庭关系 | 家庭 / 亲情 / 婆媳 / 姐弟 / 照护 / 伦理 / 代际冲突 | [家庭关系](genre-cards/家庭关系.md) | 高 |
| 亲子隐秘 | 亲子 / 萌宝 / 神秘小孩 / 隐婚生子 / 认亲 / 单亲爸爸 / 单亲妈妈 / 血缘揭示 / 领养身世 | [亲子隐秘](genre-cards/亲子隐秘.md) | 中 |
| 职场喜剧 | 职场 / 轻喜剧 / 打工人 / 技术流 / 专业能力 / 办公室 | [职场喜剧](genre-cards/职场喜剧.md) | 高 |
| 身份错位 | 身份错位 / 身体互换 / 灵魂互换 / 冒名顶替 / 马甲 / 人非人身份 | [身份错位](genre-cards/身份错位.md) | 高 |
| 生活流 | 生活流 / 小人物 / 都市温情 / 日常 / 治愈 / 市井 | [生活流](genre-cards/生活流.md) | 高 |
| 仙侠修真 | 仙侠 / 修真 / 修仙 / 玄幻 / 宗门 / 御剑 / 东方奇幻 | [仙侠修真](genre-cards/仙侠修真.md) | 中 |
| 豪门婚恋 | 豪门 / 霸总 / 婚恋 / 契约婚姻 / 先婚后爱 / 甜宠 / 虐恋 | [豪门婚恋](genre-cards/豪门婚恋.md) | 中 |
| 破镜重圆 | 破镜重圆 / 追妻 / 复合 / 久别重逢 / 前任 / 失忆重逢 / 重逢不相识 / 意难平 | [破镜重圆](genre-cards/破镜重圆.md) | 中 |
| 动作任务 | 动作 / 任务 / 冒险 / 追逃 / 营救 / 押运 / 生存突围 | [动作任务](genre-cards/动作任务.md) | 中 |

置信度指"该卡的压力机制在本套件内被交叉印证的程度"，不是市场表现、不是热度排名，
也不是任何测量结果。每张卡的"证据与置信度"一节写明了它实际的来源。

## 跨题材与未覆盖题材

- 表里没有匹配项时，不要硬套最接近的一张卡。回到
  [genre-and-hook-playbook.md](genre-and-hook-playbook.md) 按压力来源、人物策略、观众回报、
  信息权限、可见证据、制作难点六个轴线自建一次，再决定是否借用某张卡的单独条目。
- 混合题材（例如复仇 + 悬疑、家庭 + 生活流）要先声明主要矛盾归谁，并检查两套制作要求会不会打架：
  一个要公开场合与群演，另一个要封闭空间与状态连续性时，成本会叠加而不是平均。
- 同一题材词可以由完全不同的机制驱动。"悬疑"可以是空间规则、关系谎言或技术证据；
  "婚恋"可以走互助、权力不对等或身份冲突。卡片只在机制相符时才适用。
- **不要把前提装置当成题材来查表**。 "主角重来一世""主角获得一套外部规则"这类设定是
  叠加在题材之上的一层，它决定主角比别人多拥有什么，不决定压力来源与情绪落点。带这类
  设定的项目仍然有各自的主题材（同一个装置可以装在婚恋、复仇、宅斗或修真上）。做法是
  照常取主题材那一张卡，再另读 [premise-devices.md](premise-devices.md) 校准装置那一层；
  本表不为装置新增条目。

## 不要把卡片写成硬规则

卡片里的任何内容都不是质量门槛。以下几项尤其不能被当成评分标准或校验规则：

- **节拍数量**：没有"每集几个转折""几秒一个钩子"的要求；节拍由因果决定。
- **字数与篇幅比例**：不规定单集字数、场景数量、场均时长或分幕比例。
- **台词比例与句式**：不规定对白占比、句长、语气词、倒装或任何句式模板。
- **钩子类型轮换**：连续几集使用相似的收尾方式不自动构成缺陷；要看它们是否改变了不同状态。
- **场面清单**：卡片列出的物件与场所是可选素材，不是必须出现的清单，也不是打卡项。

审查者不得引用题材卡作为阻断理由；开发者也不得用"题材卡里写了"替代因果说明。
需要质量结论时单独调用 `$short-drama-review`，并引用当前项目的证据。

# 机制循环与耗尽

## 目录

1. 使用方式与规则分级
2. 循环是引擎与分集之间的那一层
3. 写清一次运行
4. 一次运行与一次重复的区别
5. 循环耗尽：症状与根因
6. 换代：先处置，再把紧迫性交过去
7. 一种常见变体：落差型循环
8. 循环与单集契约的关系
9. 合成示例
10. 失败征兆与审查问题

## 1. 使用方式与规则分级

在故事引擎已经成立、要把它切成单元故事与分集时使用本文件。它回答的是
"同一件事凭什么值得再看一次"，不回答"这一集怎么写"。

| 分类 | 本层例子 | 谁可以执行 |
|---|---|---|
| `structural_invariant` | 循环内各次运行的引用、状态声明是否互相矛盾 | 校验器可阻断 |
| `reviewed_invariant` | 某次运行是否真的改变局面（沿用 `STY-03`） | 审查者引用证据 |
| `craft_default` | 声明循环、处置循环、交接紧迫性 | 创作者说明理由可覆盖 |
| `taste_option` | 循环长度、运行次数、结束气质 | 不得单独阻断 |

本文件不规定一个单元该跑几次、一次运行占几集、循环之间怎么排列。这些是创作者与
项目的选择。

## 2. 循环是引擎与分集之间的那一层

[story-craft.md](story-craft.md) 回答压力怎样反复生成，[episode-design.md](episode-design.md)
回答一集怎样完成一次状态变换。中间还有一层常被跳过：**一个单元故事通常是同一套机制
被反复运行**，观众的乐趣一半来自机制本身，一半来自"我已经知道它会怎么运作，我在等它
再运作一次"。

跳过这一层的典型后果是：每集都在发生事，事与事之间却没有共同的期待物。观众看完一集
知道发生了什么，却说不出下一集自己在等什么。

```text
故事引擎：压力为什么会反复出现
→ 机制循环：这个单元里，什么东西被反复运行，观众每次期待什么
→ 单集契约：这一集把哪一次运行推进到哪里
```

**循环的乐趣建立在观众掌握机制之上**。 这带来一个反直觉的做法：**第一次运行要把机制
演示完整，宁可慢**。观众没看懂机制之前，后面每一次运行都只是又一个事件；看懂之后，
同样的动作会自动携带期待。把第一次运行压缩成和后面一样快，是这一层最常见的浪费。

循环通常是**套着的**，不是排成一列：几次小循环共同构成一个更大循环的一次运行，几个
大循环构成整部戏。下文为了说清楚只写单层，但每一条同样适用于外层——**外层的赌注要
更早建立**，因为观众正在跟的是小循环，而让他们留到几十集之后的是大循环。嵌套几层、
每层多长由创作者与项目决定，本文件不给层数与集数配方。

**`craft_default · STY-20`**：为每个单元声明它反复运行的机制、观众每次运行能预期的
回报，以及这个循环在什么条件下应当结束。第一次运行完整展示机制，后面的运行才能靠
"认得出来"生效。

## 3. 写清一次运行

一次运行不是"又赢了一次"。为每次运行记录：

- **谁在用什么已知优势**：主角掌握的信息、习惯、权限或关系，观众此刻知道多少；
- **对方基于什么行动**：对手不是变笨，而是依据他手里的事实作出合理选择；
- **观众提前知道什么**：这是期待的来源。观众可以比对手多知道一步，也可以和对手一样
  被蒙住——但要选定一种；
- **本次改变什么状态**：知情者名单、对手的解释空间、主角的可用次数、代价的到期时间、
  某段关系的位置；
- **本次的成本**：主角为这次运行付出了什么，或欠下了什么。

没有第五项的运行会让循环变成免费的。免费的循环耗尽得最快，因为观众很早就算出了
它可以无限进行。

## 4. 一次运行与一次重复的区别

判据只有一条：**把几次运行的顺序打乱，会不会损失东西**。

会损失，说明每次运行都改变了下一次的条件。不会损失，说明这是同一件事的复述，无论
场面换到哪里、金额加到多大。

具体可查的差异项：

- 对手对机制的认知——完全不知道 / 察觉异常 / 知道有人在做 / 知道是谁；
- 主角的执行难度——同样的手段这次要多付什么；
- 机制的适用范围——上次能用的条件，这次还在不在；
- 知情者名单——谁新看见了，谁因此必须选边；
- 退路——哪条原本可以撤退的路现在关上了。

指不出上述任一项变化而声称"这次更狠"时，它不是升级——这与 `STY-03` 判断升级用的是
同一条标准，本文件只是把它落到循环这一层。

### 4.1 避免重复时最容易走错的那一步

发现重复之后，通常有两个修法，只有一个是对的：

- **换靶心**（错）：为了不重复，换一件全新的、与核心回报无关的事来写。重复消失了，
  但观众追的那条线也断了。几次之后，整部戏会被描述成"后面不知道在讲什么"。
- **换向量、抬阈值、不换靶心**（对）：同一个矛盾点，用不同性质的东西回应，且这次的
  代价或规模比上次高一层。

举例说明差别。对手反复质疑主角"拿不出钱"：

- 重复：第一次用一笔钱回应，第二次用更大一笔钱回应。方向没变，阈值没变，观众疲劳。
- 换向量：第一次用一笔钱回应；第二次对手改口说"东西是借的"，回应它的不再是钱，而是
  一个只有真正拥有者才会有的日常细节（有人来向他请示当晚的安排）。靶心仍是"他到底
  有没有"，但证明它的东西换了一类，阈值也抬了一层。
- 也可以换承担者：引入一个新人物，由她的态度来完成同一次回应。这仍然合格——**判据不是
  "有没有换人换事"，而是"换过之后，观众追的还是不是同一件事"**。

失效判据只有一条：这个新事件与本剧的核心优势、核心矛盾是否还有关系。答案是"关系很弱
但也说得通"时，它就已经偏了——短剧的篇幅不提供容纳弱关联的余地，而偏靶一次的损失会
一直带到后面。

## 5. 循环耗尽：症状与根因

任何循环都会耗尽。耗尽不是写坏了，是这一层的正常寿命；写坏的是**没有察觉耗尽**。

症状（出现两项以上即应处置）：

- 观众能提前说出运行结果和对手反应，猜中之后不再有期待；
- 兑现的规模在变大（更大的场面、更高的筹码、更公开的场合），状态变化却在变小；
- 必须靠加大羞辱、加大金额或加多围观者来维持强度；
- 对手为了让机制继续生效，开始作出他自己都不该作的选择。

最后一项是根因，也是最容易被忽略的：**机制越有效，对手越必须变笨，世界越不可信**。
一个已经被反制三次的对手仍然按老办法上钩时，损失的不只是这一段，还有观众对整部戏
因果的信任。到这一步再修补，往往要回头重写更早的段落。

### 5.1 没有终点的循环一定会耗尽

题材说法（"隐藏身份归来""高手回归""带着记忆重来"）只描述了**推进方式**，没有描述
**去处**。只有推进方式的循环，唯一的续命办法是不断换上更强的对手重跑同一套流程——集数
可以很多，内容却很薄，观众第一轮就看到了头。

补法不是加强机制，是给它一个能被用完的去处：主角最终要让**哪件具体的事被改变**。
一旦这个去处成立，每次运行就都在朝它推进，循环自带终点，也自带"还差多少"的可感刻度。

去处不必宏大，但必须**具体到可以被核对**："让当年那份名单被公开更正"比"变成最强的人"
更有用，因为前者能被完成，后者只能被无限延长。这也决定了故事能不能收得干净——
[story-craft.md](story-craft.md) 讲的终止条件，在循环这一层的表现就是它。

## 6. 换代：先处置，再把紧迫性交过去

### 6.1 三种处置

- **收束**：让循环以一次**不能再重复**的运行结束。常见办法是让机制被识破，或让代价
  第一次落到主角自己或他保护的人身上。收束会同时结清观众的期待和主角的债，是最干净
  的一种。
- **改造**：保留机制，换掉它的一项前提——适用范围、代价结构、知情者、或谁承担风险。
  改造后的循环与原循环共享观众已经建立的理解，因此不需要重新教学，起步就有期待。
- **移交**：把机制交给另一个人物使用。观众的立场随之改变：原本站在使用者一侧看它奏效，
  现在可能站在承受者一侧看它逼近。同一套机制因此获得完全不同的情绪。

**不成立的第四种：并接**。 不处置旧循环，直接在旁边开一个新的。

### 6.2 换代真正丢掉的是紧迫性

新循环往往更新奇却更弱。原因不是它写得不好，而是它**从零开始**：旧循环攒下的三样
东西没有交接过来。

1. **可感的时限或到期的代价**——旧循环里"再不做会怎样"是具体的，新循环里常常只剩
   "情况不太好"；
2. **主角不能退出的理由**——旧循环的退出成本是攒出来的，新循环若没有重新给出，主角
   随时可以走开，观众也就随时可以走开；
3. **观众已经押上的赌注**——旧循环让观众在意某个具体的人或某样具体的东西，新循环若
   换掉了这个对象，等于让观众重新下注。

检查办法：问"如果主角这一轮什么都不做，会发生什么"。新循环的答案必须比旧循环**更具体
且更糟**，而不是更抽象。答案变抽象时，先补时限与退出成本，再谈新机制好不好玩。

这也解释了并接为什么不成立：旧循环的期待没有结清，新循环又要从零建立理解，两边同时
变弱。观众的说法通常是"后面不如前面好看"，实际发生的是前面那笔账没有还。

### 6.3 做法：把下一个循环埋在这一个里面

不要等到换代那一刻才让观众第一次听说下一件事。在当前循环还在运行时，就让下一个循环
需要的东西以次要身份出现过一次：一个还没解释的人、一份被顺手放下的文件、一句当时不
重要的话。它们此刻只是背景，旧循环收束时才被提起——观众会感到"原来那个东西是有用的"，
而不是"怎么突然又来一件事"。

代价很低：每次只需要一处，不必额外加场，也不必在当时解释。真正的成本是**必须提前
知道下一个循环大概是什么**，所以它属于分集地图，不属于写正文时的临场发挥。

换代之间还需要一段缓冲。一个循环刚收束就立刻拉满下一个，观众来不及感受刚才那次兑现；
留一段低压力的过渡——处理后果、确认损失、让关系落定——反而让下一个循环起得更高。
这段过渡不是空转，它交付的正是刚结束那次运行的余波。

**`craft_default · STY-21`**：结束一个循环时先处置它（收束、改造或移交），再开下一个；
新循环要接管旧循环的赌注与时限，而不是从零重建紧迫性。

## 7. 一种常见变体：落差型循环

有一类循环的回报不是"权力被夺回"，而是"紧张被解除"：人物反复进入危险处境，又反复
脱身，观众买的是那一下松口气。

它有两个特点：

- **耗尽更快**。解除一旦可被预期，紧张就不再产生。夺回型循环靠"这次能拿回什么"维持，
  落差型循环靠"这次会不会真的出事"维持，而后者只要连续几次都没出事，就不再有人担心。
- **常见修补是让虚惊留下真实损失**。每次脱身都带走一点确定的东西——一条退路、一个
  知情者、一次可用的机会、身体上的一处代价。损失可以很小，但必须是确定发生的。全是
  虚晃的落差型循环，通常在观众能数出第三次时就失效了。

不要把这条当成"必须每次受伤"。它只说明：落差型循环的可持续性由**真实损失的积累**
提供，而不是由危险的规模提供。

## 8. 循环与单集契约的关系

- 一次运行可以跨几集，也可以一集完成；**不要求每集一次运行**。
- 一集里可以推进循环的一部分（布置、试探、遭遇反制），只要这一集自己仍有局部结果——
  这条由 `STY-13` 管，本文件不重复。
- 集尾钩子从本次运行的当前状态往下长，而不是从循环的最终目标往下长。写法见
  [episode-design.md](episode-design.md) 的"钩子要接着本集结果往下走"。
- 循环换代的位置不必对齐整数集，也不必对齐单元边界；对齐与否是节奏选择。

## 9. 合成示例

以下人物、机构与情节均为新写虚构，不指向任何实际作品。

**单元设定**：社区医院的排班表被护士长改过，把夜班压在一个没有靠山的年轻护士身上。
主角查到改动，但拿不出能立刻推翻结果的证据。

**机制**：主角每次都让对方**在有第三方记录的场合重新说一遍自己的说法**——交接本、
科室会议、家属沟通单。说法一旦和可核对的记录对不上，对方必须当场改口；而每次改口，
都会缩小他下一次能用的解释空间。

观众第一次看完就掌握了机制：不是抓把柄，是让他自己把路一条条说死。

**运行一（完整演示，不赶）**：主角当着交接班的人问一句排班依据。护士长说"按上月轮次"。
主角把交接本翻到上月那页放在台面上，不说话。护士长改口成"临时调整"。
状态变化：他从"有规则依据"退到"临时决定"；知情者从零变成一桌人。
成本：主角暴露了自己在查这件事。

**运行二**：家属投诉夜班无人应答。护士长解释"人手不够"。主角把上周的在岗签到摊开。
护士长改口成"我安排失误"。
状态变化：解释空间从"客观条件"退到"个人失误"；主角的执行难度上升——对方开始
避免在有记录的场合说话。
成本：主角被调离了能接触交接本的岗位。

**运行三**：科室会议上，护士长干脆不解释了，改为反问主角为什么总盯着排班。
状态变化：对手学会了机制，开始拒绝进入触发条件。
——这里就是耗尽点：**机制要继续生效，必须让对手继续开口，而他已经知道不该开口**。

**三种处置各自会走向哪里**：

- *收束*：主角把仅剩的一次机会用在一个对方无法沉默的场合（比如必须签字的责任书），
  换来结果，同时暴露自己而失去这条路径。循环结清，单元结束。
- *改造*：机制保留，换掉前提——不再由主角发问，而是由那位年轻护士自己在有记录的场合
  提问。适用范围变了，代价结构也变了（风险转到她身上），观众不必重新学机制，但要
  重新为她担心。
- *移交*：护士长学会了同一套办法，反过来在有记录的场合逼主角表态。观众第一次从
  承受者的位置看这套机制，情绪完全不同。

*并接会怎样*：不处置以上任何一种，直接开一条"主角发现药品短缺"的新线。旧账没还，
新线又要从头建立时限与退出成本，两边都变弱。

## 10. 失败征兆与审查问题

### 失败征兆

- 单元里找不到被反复运行的东西，只有一串不同的事件；
- 第一次运行和后面一样快，观众没有机会看懂机制；
- 几次运行可以任意交换顺序而无损失；
- 兑现规模变大而状态变化变小；
- 对手为了让机制继续奏效而作出不合理选择；
- 旧循环没有结清就开了新循环，新循环的紧迫性只剩形容词；
- 落差型循环连续多次没有留下任何确定损失；
- 把"每集一次运行"当成硬性配方，或用运行次数证明质量。

### 审查问题

审查者引用分集地图或剧本证据回答：

1. 这个单元反复运行的是什么？观众每次期待的具体回报是什么？
2. 第一次运行是否把机制演示清楚？观众凭什么在第二次就有期待？
3. 每次运行改变了认知、难度、适用范围、知情者或退路中的哪一项？
4. 主角每次运行付出了什么？这个循环是不是免费的？
5. 有没有出现耗尽症状？其中是否包含"对手必须变笨"？
6. 循环换代时用的是收束、改造、移交，还是并接？
7. 新循环的时限、退出成本和观众赌注从哪里来？"什么都不做会怎样"的答案变具体了吗？
8. 是否把循环长度、运行次数或换代位置当成了质量门槛？

# 多集整稿接入与断点续跑

当创作者给的是一份已经写好的多集剧本、散稿或合订稿，并希望生成或补齐
`项目开发/episode-map.jsonl` 时使用本流程。它不是小说改编分析，也不是把整份文件塞进一次
提示词：**Agent 判断这份文件实际怎样分集、每集讲了什么；脚本只保存精确定位并防止重复劳动**。

## 不变边界

- 原文件原样保存在 `输入/`；byte span 按原始字节计算，CRLF 不做归一化。
- 自动标题识别只生成候选索引，不是对文件语义的裁决。不要为了迎合脚本而改写创作者原文。
- 不把整稿、全部分集正文或整季 map 塞进 heredoc、内联 Python、命令参数或单次模型上下文。
- `episode_intake.py` 不生成转折、回报、钩子等创作字段。它只做索引、校验、单集切片、
  完成集推导和 Agent 所写记录的原子合并。
- 批次没有通用固定值。Agent 先看索引里的各集 `byte_length`、实际复杂度和当前可用上下文，
  再为**本轮**明确选择 `--batch-size`；首轮宜保守，读过真实切片后可以调整。

## 1. 在工作区只建一次候选索引

```text
python3 <本技能目录>/scripts/episode_intake.py index \
  输入/<完整剧本> \
  --source-ref 输入/<完整剧本> \
  --out 项目开发/_work/episode-intake-index.next.json
```

脚本识别短独立行形式的 `第N集`、`第N集 标题` 与 Markdown `# EP N`，统一写成规范
`EP001` ID。索引只含行/字节跨度、长度与结构问题，不含正文。

退出码 `0` 表示机械结构自洽；退出码 `2` 表示候选已落盘但有缺号、重号、空集或未识别等
问题。

`unmapped_spans` 用 locator 标出**落在任何一集跨度之外**的材料——实际上就是第一个集标题
之前的前言与目录。它标不出集间说明与尾注：分集跨度从一个集标题一直延伸到下一个集标题
（最后一集延伸到文件末尾），两集之间不存在空隙，所以一段插在中间的制作方说明会被并进
前一集，尾注会被并进最后一集，`problems` 仍是空的。**这不是可以靠正则补上的**：
「这一段属于上一集还是不属于任何一集」是语义判断，扩大正则去猜作品语义正是下一段
禁止的做法。

所以「材料不会静默丢失」这条要靠下面的边界检查来保证，而不是靠 `unmapped_spans` 报全：
Agent 必须对每个 `unmapped_spans` 做小范围检查，**并且**按下一段的做法读每一集的首尾几行，
确认边界落在正确的位置。
此时根据候选中的 line span，只读取疑似边界附近的小段，判断**这份文件**使用的是
幕标题、分隔线、混合标题、目录加正文还是别的规律。不要扩大自动正则去猜作品语义。

非标准结构由 Agent 写一个很短的 JSONL 边界文件，每行只给规范 `episode_id` 与 1-based
`line_start`，必要时给 `line_end`；然后让工具推导精确 byte span：

```jsonl
{"episode_id":"EP001","line_start":12}
{"episode_id":"EP002","line_start":58}
```

```text
python3 <本技能目录>/scripts/episode_intake.py manual-index \
  输入/<完整剧本> <临时边界.jsonl> \
  --source-ref 输入/<完整剧本> \
  --out 项目开发/_work/episode-intake-index.next.json
```

`manual-index` 仍会机械阻断重号、跳号、倒序、空跨度和非规范 ID，但不会判断一幕是否应该
属于上一集还是下一集；这个选择仍由 Agent 结合文件内容完成。

自动或手工候选通过检查后，把它发布到正式 owner 路径；不要让 intake 工具直接覆盖规范索引：

```text
python3 <本技能目录>/scripts/episode_intake.py verify \
  项目开发/_work/episode-intake-index.next.json 输入/<完整剧本>

python3 <core 技能目录>/scripts/project_tool.py publish <项目根> \
  --owner short-drama-develop --artifact-id series:episode-intake-index \
  --output 项目开发/episode-intake-index.json=项目开发/_work/episode-intake-index.next.json \
  --input 输入/<完整剧本>
```

发布成功且下游命令已改读正式索引后再删除工作区候选。可重建索引仍通过 owner 的 `publish` 发布，以保持路径所有权和原子替换。

## 2. 每次只读当前集

任何切片前都验证索引；原文件变化一个字节就重建，不沿用旧 locator：

```text
python3 <本技能目录>/scripts/episode_intake.py verify \
  项目开发/episode-intake-index.json 输入/<完整剧本>

python3 <本技能目录>/scripts/episode_intake.py progress \
  项目开发/episode-intake-index.json 输入/<完整剧本> \
  项目开发/episode-map.jsonl --batch-size <本轮由 Agent 决定>

python3 <本技能目录>/scripts/episode_intake.py slice \
  项目开发/episode-intake-index.json 输入/<完整剧本> EP001 \
  --out <临时单集文件>
```

只读取 `next_batch` 指向的单集切片。Agent 根据每集自己的进入状态、追求、阻力、因果升级、
局部结果和出去压力写 map 记录；需要连续性时只携带已接受的紧凑前情、上一集交接和已有 map
相关记录，不回读整稿。每完成一集先落到短 batch JSONL，随后再处理下一集。

## 3. 合并与发布

`merge` 读取当前 map，但必须把结果写到另一个候选文件，绝不直接覆盖当前项目事实：

```text
python3 <本技能目录>/scripts/episode_intake.py merge \
  项目开发/episode-intake-index.json 输入/<完整剧本> \
  <本轮 batch.jsonl> 项目开发/episode-map.jsonl \
  --out 项目开发/episode-map.next.jsonl \
  --batch-size <本轮由 Agent 决定>
```

它拒绝未知 ID、批内重号、超过本轮显式上限的记录和对已完成集的冲突重写；相同记录重放是
no-op。合并成功后，通过 core 的公开生命周期把 `episode-map.next.jsonl` 作为同一 artifact
的新候选发布，并声明它实际读取的完整剧本与索引：

```text
python3 <core 技能目录>/scripts/project_tool.py publish <项目根> \
  --owner short-drama-develop --artifact-id series:episode-map \
  --output 项目开发/episode-map.jsonl=项目开发/episode-map.next.jsonl \
  --input 输入/<完整剧本> \
  --input 项目开发/episode-intake-index.json
```

发布完成后再删除临时候选和单集切片。不要让 `merge` 直接覆盖
`项目开发/episode-map.jsonl`，也不要绕过 `project_tool.py` 手工替换它。

中断后先重新运行 `progress`；项目工具可用时也读取 `status`。磁盘上的当前
`episode-map.jsonl` 是唯一完成真相；checkpoint 若需要只是由它重建的缓存，不能用
`last_completed` 猜连续进度。已有 `EP001`、`EP003` 时，`EP002` 仍会出现在 pending，已完成
记录不会重跑。全部 `pending` 清空后，再做所有者检查、创作者接受与审查。

# 前提装置：把外来优势写成有边界的压力

## 目录

- [装置不是题材](#装置不是题材)
- [共同的失效机制](#共同的失效机制)
- [先知型装置](#先知型装置带着已知结果开局)
- [授权型装置](#授权型装置外部规则给出能力)
- [与既有机制的接口](#与既有机制的接口)
- [自检](#自检)

前提装置是叠加在题材之上的一个开局设定：主角比处境中的其他人**多拥有一样东西**——
一段已经发生过的记忆，或一套外部授权的能力。装置本身不提供冲突，它**取消**冲突；
所以它带来的全部工艺问题都是同一个：把取消掉的阻力用什么补回来。

## 装置不是题材

装置和题材是两层，不互相替代：

- **题材**回答"观众为什么看这个世界的这类矛盾"，决定压力来源与情绪落点；
- **装置**回答"主角凭什么在这个世界里有别人没有的余地"，决定信息与能力的分配。

同一个装置可以装在完全不同的题材上：带着前世记忆去打商战、去宅斗、去修真、去修补一段
关系，是四件不同的事。所以**不要为装置单独建一张题材卡**，也不要因为出现了装置就跳过
题材卡——先按 [genre-cards.md](genre-cards.md) 取主题材那一张，再用本文校准装置那一层。

若创作者的设定里没有这类外来优势，本文整篇不适用，不要为了"更有卖点"而加装置。

**`craft_default`**：装置只调整信息与能力的分配，不改写题材的压力来源、观众回报与
结局承诺。

## 共同的失效机制

两类装置坏掉的方式是同一个形状，先认这个形状，再看各自的处理：

1. **阻力被抽空**：主角每次都提前知道或直接获得答案，段落退化成"执行已知正确操作"的
   流程演示。观众能看出结果不再由选择决定。
2. **对手不学习**：装置让主角持续正确，对手却仍用同一套手段，于是中段开始，场上没有
   任何人能改变结果。
3. **装置替戏说话**：本该由行动、证据和对峙承担的信息，改由记忆闪回或规则宣告直接讲出来。
   省了戏，也省掉了观众的参与。
4. **规则通胀**：写不下去时给装置加新能力或新条款救场。每加一次，先前所有段落的紧张
   感都被追溯性地削弱。

对应的共同解法只有一条：**给装置装上边界，并让边界本身产生成本**。装置能做什么要写
清楚，不能做什么要同样清楚，且使用它必须付出可见代价。

### 两层必须分开：创作者契约与剧中披露

这是本文最容易写坏的地方。装置有两个不同的东西，混成一层会同时误伤两种正当设计：

- **装置契约（创作者层）**：能力范围、失效条件、代价、以及规则是否可靠。它属于创作者
  已接受的事实，**从一开始就可以是完整的**，写在故事引擎里供后续对账。它不需要、通常也
  不应该在装置首次生效时就全部告诉观众。
- **披露状态（剧中层）**：此刻人物以为装置是什么、观众被允许知道多少。它可以是残缺的、
  可以是错的，也可以是装置本身在说谎。

分开之后，两种设计都不再被误判：**边界后来才被发现**是正当的（甚至是主要的悬念来源）；
**装置的宣告不可靠**也是正当的（欺骗性系统、记错的前世、别有用心的告知者）。被禁止的
只有一件事：**没有上游依据的事后扩权或免除代价**——即契约里从来没有过这条能力，写到
困境时凭空给出来。

**`reviewed_invariant`**：装置契约的**每一条条款**都必须在该条款首次生效前被创作者接受，
并记录能力范围、失效条件、代价与规则可靠性；剧中披露可以晚于契约、可以不完整、也可以被
人物或装置本身误述。后续段落里出现的每一项装置能力或豁免，都要能追溯到某一条已接受条款；
追溯不到即为事后扩权，按缺陷处理。观众在某一刻不知道全部边界，本身从不构成缺陷。

闸门是**条款级**而不是装置级：装置在第一集生效之后，仍然可以新增条款，只要走
「先改契约表并让创作者接受 → 再在剧中披露」这个顺序。但要防住一种形式合规的滥用——
写不下去时补一条新条款、让它被接受、再写出来。程序上无懈可击，实质上就是上面第 4 条
失效机制的规则通胀。可追溯性检验不到这一点，所以判断依据是**新增条款是不是由困境驱动**：
新条款如果只在主角脱不了困的那一集出现、且不产生新的代价或新的限制，就按规则通胀处理，
而不是按正常修订处理。

契约写在故事引擎的装置条目里，与承诺、引擎、升级链一起被引用；剧中已披露到哪一步属于
信息权限，写进单集契约的信息权限栏，随集推进。两者各自有位置，才可能分别核对。

## 先知型装置（带着已知结果开局）

主角保有一段"已经发生过"的经历——重来一次、看过结局、被告知未来。

### 信息边界怎么切

未来信息不是一整块，切开它才有戏。可选的切法（按项目挑一到两种，不要全用）：

- **只知结果，不知过程**：知道某人会背叛，不知道用什么方式、在哪一步。
- **只知亲历，不知全局**：只覆盖主角当时在场或后来听说的部分，其余是空白。
- **知道旧版本，而非新版本**：主角一行动，时间线就偏离；越往后，记忆越不可靠。
- **记忆有损**：关键时刻记不清顺序、人名或数字，且不知道自己记错了。

第三种最能长线供能：它让装置**随剧情自然衰减**，不需要作者不断找理由削弱主角。前期
记忆好用，中期开始频繁失准，后期主角必须靠这一世新建立的能力和关系。

### 起点选在哪里，决定要还的第一笔账

重来的起点不是随便一个"从前"。它应当落在**主角当时做错了一个可指认的选择之前**，
或**某样东西还没有失去之前**。起点一旦确定，全剧第一笔债务就确定了：观众会一直等
这件事被改写。落在无关的日常上，开局就没有牵引。

### 观众信息权限是独立选择

观众知道多少前世，与主角知道多少是两个旋钮：

- **观众与主角同步**：悬念强，观众和主角一起赌。
- **观众知道得更多**（例如先看到前世结局）：主角每一步"聪明"都自带紧张感，因为观众
  知道哪里会出错。
- **观众知道得更少**：主角行为反常，观众带着疑问追看，代价是前期共情较慢。

三种都成立，但必须选定并保持；中途切换会让观众不知道该替谁着急。这一项服从信息释放
校准规则（`STY-15`），并写进单集契约的信息权限栏。

### 合成例：边界如何创造压力

角色甲记得三个月后仓库会失火，不记得起火点，也不记得当天自己为什么不在场。她提前
换掉线路，火仍然发生了——只是提早了两周，而且这一次她在场。装置给了她一次干预机会，
干预本身改变了她后续所有记忆的可靠性，也让她第一次意识到：她记得的那个版本里，
可能有人是故意的。

这段成立是因为三件事同时发生：信息被用掉了、结果偏离了记忆、并且偏离本身成了新的
悬念。只写"她提前换了线路所以避免了火灾"就同时丢掉了这三样。

## 授权型装置（外部规则给出能力）

主角获得一套由外部宣告的规则：能力、任务、数值、奖惩。

### 宣告是一次披露，不是新增契约

这里要用上前面那两层。装置在剧里宣告一条规则时，发生的是**披露**：契约里已有的一条
被说给人物和观众听。宣告不创造契约条款——**先有契约，才能宣告**。所以宣告前要回答的
不是"这条规则听起来好不好"，而是"契约里有没有这条，它在后面每一次相关处境是否都成立"。

观众会记住被说出口的条款并逐集对账，所以披露过的内容有它自己的重量：

- **契约里没有的，不要宣告**。写到困境时临时宣告一条新能力，就是事后扩权，只是换了个
  好听的形式。
- **数值、时限、冷却、次数一经披露就被记住**。不确定能否守住，就在契约里写成定性条件，
  披露时也只披露定性部分——不要先给一个精确数字再回头改。
- **宁可少披露**。契约可以完整而暂不披露；已披露又被违反的收不回来。这两句不矛盾：
  前者说的是披露节奏，后者说的是披露之后的约束。
- **可以设计不可靠的宣告**，但不可靠本身要写进契约（它是"装置会误述"，而不是"作者改了
  主意"）。后续揭穿时，观众能回看出线索，才算兑现而不是失约。

**`reviewed_invariant`**：每一条已披露的装置规则都能追溯到已接受的装置契约；违反已披露
规则时，要么它在契约里本就标为不可靠并已埋线索，要么按冲突处理。装置规则的对账走铺垫
债务台账，与其他已接受事实一起被引用。

### 代价是唯一的张力来源

无代价的能力等于没有装置。代价要落在**观众看得见、且主角在意的东西**上：时间、身体
状态、关系、名声、只能用一次的机会、下一次使用的可用性。写成"消耗精神力"这类不可
见量，等于没有代价——除消耗之外还要有可见后果。

### 装置不替主角做决定

它可以给能力、给信息、给限期任务，但**不能替他选**。让装置提出选项、由主角付代价
选择，段落才有主体。若每次装置宣告后主角只是照做，主角就退化成执行者，观众没有可
认同的对象。

### 载体与可读文字义务

这类装置常常同时用两个载体：一层声音（画外的宣告）和一层画面上的可读文字（面板、
提示、数值）。这会产生真实的下游后果：

- 画面上必须能读的文字属于 `exact-readable`，与全局"画面不出现任何文字"的策略**直接
  冲突**。选择了屏显载体，就要在资产与提示词环节指定唯一允许的文字内容与受控显示位置，
  剧本环节要把这类必须可读的文字与普通叙述区分标注（`SCR-07`），图片提示词环节再据此定文字策略。
- 若项目决定不做屏显，装置信息就只能靠声音与人物反应承载；此时更要写清主角听到之后
  的可见处理，否则观众只听到条款、看不到影响。
- 两个载体同时用时，不要让它们逐字重复：声音给条款，画面给当前数值与变化，或者反过来。
  两边说同一句话会占掉两份注意力却只给一份信息。

### 合成例：条款如何变成戏

装置宣告：角色乙在同一处所内可以让一个人忘记刚发生的三十秒，每日一次，使用后他自己
会短暂失去平衡感。这条规则在后面每一集都可被对账：他不能远程用、不能对两人用、不能
连用，而且用完的那几秒他站不稳——这几秒正好够对手察觉异常。能力、边界与代价在同一
句里给全，之后所有段落都能从中长出选择：救人还是留着这一次、忘掉的三十秒里对方到底
说了什么、有人开始记录他每次站不稳的时间点。

## 与既有机制的接口

装置不新建一套体系，它只是几条既有机制的特例：

| 装置带来的问题 | 交给既有机制 |
|---|---|
| 装置契约（范围、失效、代价、可靠性）存在哪里 | 故事引擎的装置条目，与承诺和引擎一起被创作者接受并引用 |
| 剧中披露到哪一步、谁知道什么 | 单集契约的信息权限栏，随集推进；世界事实、人物认知与观众知情分层见所有权契约 |
| 未来信息与前世事实的释放节奏 | 信息释放校准规则 `STY-15`，落在单集契约的信息权限栏 |
| 前世/现世两条时间线的状态不混 | 跨集记忆见 [serial-character-and-memory.md](serial-character-and-memory.md)；跨场状态见资产环节的变化记录 |
| 已披露规则的对账与追溯 | 铺垫债务与 `setup_ids`/`payoff_ids` 台账 |
| 装置揭示不能凭空反转 | [reveal-reversal-payoff.md](reveal-reversal-payoff.md) |
| 屏显条款的可读文字义务 | 剧本生产标签与图片提示词的文字策略 |
| 闪回属于自己的时间分支 | 资产环节的变化记录不被闪回重写 |

## 自检

1. 主题材那张卡读了吗？装置有没有被当成题材、顶替了压力来源？
2. 用到的每一条条款是否都在它首次生效前被接受，且写清了能力范围、失效条件、代价与可靠性？
3. 剧中披露到哪一步，是否记在信息权限栏里？**不要**把"观众还不知道全部边界"当成缺陷。
4. 后续出现的每一项装置能力或豁免，能否追溯到某一条已接受条款？追溯不到的在哪一集？
   新增的条款是由设计需要驱动，还是刚好出现在主角脱不了困的那一集、且没带来新代价？
5. 阻力靠什么补回来？去掉装置以后，这一集还剩下选择吗？
6. 对手在装置生效后学到了什么、改了什么做法？
7. 先知型：记忆的切法选了哪一种？它会随剧情衰减，还是需要作者不断找理由削弱主角？
8. 先知型：起点落在哪个可指认的错误或损失之前？第一笔债务是什么？
9. 先知型：观众信息权限选了哪一档，全剧是否保持一致？
10. 授权型：已披露的每条规则，在你还没写的高潮段里是否仍然成立？
11. 授权型：若设计了不可靠宣告，契约里是否标明，并已埋下可回看的线索？
12. 授权型：代价是否可见、是否落在主角在意的东西上、是否有除消耗之外的后果？
13. 授权型：装置是提出选项，还是替主角做了决定？
14. 授权型：用了屏显载体吗？可读文字义务是否已经交代，且没有与无字策略并存？

# 冲突、揭示、反转与回报的条件方法

这是一组按项目条件选择的工具，不是题材公式。先问作品承诺什么体验，再选择能让人物付出代价、
让观众获得回报的机制。

## 1. 从承诺选择压力来源

| 承诺重心 | 可持续压力 | 可变化的回报 |
|---|---|---|
| 身份/伪装 | 暴露风险、两套义务、识别证据 | 观众多知道一层、角色被迫选边 |
| 职场/制度 | 签字权、时限、替罪链、程序筹码 | 规则被反用、责任归属改变 |
| 家庭/遗产 | 照护债、记忆版本、物件归属 | 关系真相或选择成本落地 |
| 复仇/追责 | 证据可信度、共犯关系、代价升级 | 对手失去一项保护，主角承担新债 |
| 悬疑/秘密 | 谁能看见什么、证据可否解释 | 排除一种解释，同时产生更难选择 |
| 轻奇幻 | 有限规则、使用代价、普通秩序摩擦 | 规则被聪明运用，而非不断加大法术 |
| 情感/关系 | 需求不对称、面子、承诺、边界 | 一方改变策略或公开真实代价 |

同一题材可以选不同压力。不要让“霸总=羞辱升级”“悬疑=每集新秘密”代替故事引擎。

## 2. 区分四种动作

- **信息揭示**：观众/角色获得已有事实。
- **方向性反转**：已有事实使计划、解释或关系位置失效。
- **情绪回报**：承诺的恐惧、甜、爽、痛、温暖真正落到可感知结果。
- **情节钩子**：新决定、危险、问题让状态继续运动。

一次动作可以兼任，但不要混称。只展示秘密却没人改变选择，是 reveal，不一定是 turn；
只在最后藏住一句话，是 withholding，不一定是 hook。

## 3. 公平揭示

揭示前检查：

1. 观众是否见过足够的可解释迹象？
2. 谁在此前能接触事实，谁不能？
3. 证据为何现在出现，而不是作者需要时凭空出现？
4. 新事实排除了什么旧解释？
5. 得知后谁必须改变行动？

有效揭示常由“旧事实的新关系”产生，而不是突然加入更大的秘密。

合成例：维修员早先发现签字页缺失，只知道有人藏页。她在主管桌上看到订书孔方向相反，
才意识到被拿走的不是最后一页，而是中间一页；这让“补签”计划失效，必须先保护被点名的
新同事。订书孔不是装饰；它改变策略。若此前从未建立页序和装订方式，这个揭示就不公平。

## 4. 有因果的反转

**STY-09 · reviewed_invariant**：揭示/反转必须从已建立事实生长，并且让计划、
解释、关系位置或高代价选择至少一项真正改变。

反转必须能完成一句话：

~~~text
因为 <已建立的事实/选择>，
原计划 <为何不再成立>，
人物现在只能在 <新代价 A/B> 之间行动。
~~~

常见可用反转：

- 胜利触发对手有准备的程序反制；
- 证据是真的，但证明的是另一项责任；
- 被保护者拒绝保护方式；
- 主角的长处暴露新的盲区；
- 关系盟友要求兑现此前承诺；
- 规则没有失效，人物用规则改变了时间或权限。

弱反转：陌生人突然出现宣布一切都是梦。它改变信息，却没有从人物行动长出。

## 5. 回报先于下一股压力

每集至少明确一种已兑现结果（craft_default，不是数量门槛）：

- 主角确实救下/失去/赢得/公开/拒绝了什么；
- 一个旧问题获得部分可验证答案；
- 一段关系的边界真的改变；
- 承诺的能力、亲密、羞耻或恐惧得到一次完整呈现。

然后才问：这项结果让谁失去筹码、暴露什么、产生什么债，形成 outgoing pressure。
“马上要揭晓”不是回报。

## 6. 避免机械轮换

不要按集轮换“打脸—身份—误会—救场”。比较相邻集的机制：

- 压力来源是否学习；
- 主角策略是否改变；
- 代价落在哪种价值；
- 观众获得的是信息、关系、能力还是情绪回报；
- 空间/资产/制作负担是否仍可承担。

重复可以是类型节奏，但第二次应产生新意义或更难选择，而不是形容词更大声。

## 7. 规则分级

- structural_invariant：setup/payoff refs、incoming/outgoing refs 和 accepted constraints 可解析。
- reviewed_invariant：反转由已建立事实引发，揭示不越过知识权限，升级改变状态。
- craft_default：先给局部回报再留压力；让对手学习主角策略。
- taste_option：是否反转、谁先知道、揭示快慢、开放程度与题材强度。

# 连续短剧的人物、切入与跨集记忆

## 目录

1. 使用方式与规则分级
2. 先建前史储备，再选叙事切入窗口
3. 用人物驱动力预测选择
4. 把人物变化写成可追踪的压力测试
5. 每集必须产生局部戏剧结果
6. 管理信息权限与铺垫债务
7. 用双轨节奏安排张弛
8. 建立可恢复的跨集记忆
9. 合成示例
10. 失败征兆与审查问题

## 1. 使用方式与规则分级

开发连续剧、从长篇材料切分短集、续写下一集，或人物与伏笔开始失去连续性时，
在 `story-craft.md` 和 `episode-design.md` 之外读取本文件。它补足人物纵向变化与
长线记忆，不规定固定集数、弧线形状或情节点比例。

- `structural_invariant`：已声明的角色、事实、铺垫、兑现与分集引用必须存在，或
  明确标为未解决；校验器只能处理这种可证明关系。
- `reviewed_invariant`：人物选择是否来自已有压力、单集是否产生局部结果、信息
  释放是否可信，需要审查者引用上下文判断。
- `craft_default`：前史储备、人物驱动力、双轨节奏和跨集记忆通常能减少空转；
  创作者可说明理由调整。
- `taste_option`：人物成长、倒退、停滞、悲剧化或拒绝改变都可成立，不能把“正向
  成长”设成质量门槛。

## 2. 先建前史储备，再选叙事切入窗口

故事第一页之前，人物已经形成习惯，关系已经积累债务，世界规则也已经留下后果。
开发者要知道这些前因，但观众不需要先听完人物小传。

### 2.1 前史储备

只储备能解释现在选择的过去：

- 哪次旧事让人物开始依赖当前策略；
- 哪个承诺、羞耻、损失或受益关系仍在约束他；
- 哪项旧事实让两个人对同一行为产生不同解释；
- 哪种世界规则已经在人物身上留下可见后果；
- 哪个过去形成的盲区会在当前压力下制造代价。

前史储备不是待塞进对白的资料库。每一项都标记：`writer_needs`（作者需要知道）、
`audience_needs_now`（观众此刻必须知道）或 `withhold`（暂时保留）。

### 2.2 叙事切入窗口

比较几个可能的切入时刻，选择满足以下问题最多的一处：

1. 压力已经启动，人物必须采取行动；
2. 人物的惯常策略眼下仍有效，却即将显出代价；
3. 观众能从一个行为、物件、关系动作或异常结果反推“之前发生过什么”；
4. 本集可以先完成一个局部行动，而不是只负责介绍世界；
5. 切得更早会变成准备工作，切得更晚会失去关键选择。

**`craft_default · STY-11`**：先建立与当前冲突有关的前史储备，再从旧策略开始付出
代价的时刻切入。只释放本场行动需要的证据，其余继续留在储备中。

开场安静或激烈都是 `taste_option`。钩子不是音量，而是观众能察觉的未闭合因果：
一个人为何提前锁门、一个熟人为何不用旧称呼、一个日常物件为何出现在错误位置。

## 3. 用人物驱动力预测选择

人物设定要能回答“压力变化后他会怎么做”，不只说明性格和外貌。为主要人物记录：

| 层 | 开发问题 |
|---|---|
| 意识到的追求 | 他现在明确想改变什么？ |
| 被保护的价值 | 即使追求失败，他仍不愿失去谁、什么身份或哪种自我看法？ |
| 被捍卫的信念 | 他用哪句偏颇但有来历的判断解释世界和自己？ |
| 前史成因 | 哪件旧事使这套信念与策略曾经合理？ |
| 惯常策略 | 他通常如何控制、讨好、试探、隐藏、交易、公开或撤退？ |
| 即时代价 | 这套策略正在伤害什么？ |
| 改变条件 | 哪个事实、关系后果或自主选择可能让旧策略失效？ |

“内在需要”不必等于道德正确答案。有人需要学会信任，有人需要承认自己想要权力，
有人最终拒绝改变。关键是行动、后果与选择能互相解释。

### 3.1 关系让驱动力相撞

同一场景中的双方分别写：

```text
A 想让 B 现在做什么：
A 不愿让 B 看见什么：
A 采取的策略与筹码：
B 想让 A 现在做什么：
B 不愿让 A 拿走什么：
B 的反制策略与筹码：
```

这样能把“关系很好/关系紧张”改写成当下可表演的压力。

## 4. 把人物变化写成可追踪的压力测试

人物弧线不是每集增加一个“成长点”，也不是性格标签从负面换成正面。记录每次真正
触碰旧策略的事件：

```text
进入策略 → 压力测试 → 仍按旧信念行动 / 尝试新行动 / 退回旧行动
→ 获得的局部结果 → 支付的代价 → 下一次更难的测试
```

**`reviewed_invariant · STY-12`**：若声称人物发生变化，审查者必须能指出压力测试、
人物选择、结果、代价与变化后的可见策略。只有台词宣称“我变了”或情绪强度改变，
不足以证明弧线移动。

以下都可以成立：

- **确认**：旧策略再次奏效，人物更相信它；
- **裂缝**：策略成功但代价第一次无法忽视；
- **试探**：人物短暂采用新策略，但保留退路；
- **回撤**：新策略失败，人物加倍依赖旧策略；
- **不可逆选择**：人物主动承担代价，使旧身份或关系无法恢复；
- **拒绝变化**：人物看见替代路径仍拒绝，走向悲剧或反弧线。

不要求每集都移动人物弧线。没有移动时，明确本集是在积累证据、加强信念、推进
外部目标，还是让配角/关系承担变化。

## 5. 每集必须产生局部戏剧结果

连续剧可以从上一集最后一秒接起，也可以在最危险的动作中切黑，但新一集不能只把
同一动作拖到下一个切点。每集至少完成一个可辨认的微型戏剧动作：

```text
当前目标 → 有能力的阻碍 → 人物选择 → 局部戏剧结果
→ 状态/代价改变 → 从结果中长出的下一股压力
```

局部戏剧结果不等于主角获胜。它可以是：

- 目标部分成功，但暴露了新的弱点；
- 目标失败，却拿到改变下一策略的证据；
- 人物误以为成功，观众看见代价已经启动；
- 人物主动放弃原目标，关系或道德位置因此改变；
- 对手成功封住路径，迫使主角换策。

**`reviewed_invariant · STY-13`**：集尾钩子之前，本集要产生一个局部结果，且这个结果
要能追溯到**本集焦点人物的一次选择**。若删掉集尾黑屏后，本集没有任何已落地变化，
只是在动作中间暂停，应修订分集边界或补足结果。

上面那条因果链里，"人物选择"是必经环节而不是三选一。结果**由外力送达**是允许的
（援兵、证据自己浮出、对手内部翻脸），但要同时写清两件事：主角此前的哪个动作使它
**现在**到达，以及他拿到之后**做了什么处置**。两件都答不上来，这一集就是主角站着
挨打、外力替他翻盘——所有字段都能填满，观众却看不到他有能力改变自己的处境。

反例（合法通过旧措辞、但不该通过）：主角被当众羞辱，全程只是承受与追问，随后
一辆车开来、随从递上身份凭证，全场哗然。这里"阻碍产生了结果"成立，但主角没有做出
任何促成它的选择；他是这一集的观众，不是主角。修法不是加动作，而是把某个已经发生的
被动承受改写成主动选择——例如他本可以走后门完成任务，是他自己坚持走正门，那么随从的
到达就成了这个选择的后果而不是救援。

集尾可以停在即将发生的动作，但悬念必须由本集结果造成。例如“门外有人”只是新
刺激；“主角为藏证据反锁门，门外的人却拿出她刚交出的钥匙”才承接了本集选择。

## 6. 管理信息权限与铺垫债务

“故事真相”“角色相信”“观众知道”是三套状态。维护最小信息权限表：

| fact_id | 世界事实 | 角色 A | 角色 B | 观众 | 当前可见证据 | 下一次改变权限的动作 |
|---|---|---|---|---|---|---|
| FACT-01 | 【填写】 | 知道/误信/未知 | 知道/误信/未知 | 明知/怀疑/未知 | 【填写】 | 【填写】 |

信息释放不是把答案说出来，而是改变某人可以采取的行动。揭示后追问：谁现在能质疑、
交易、逃跑、撒谎或公开？没有行动后果的信息可以延后、压缩或删除。

### 6.1 证据结论边界

可见载体出现后，分开三层记录：

1. `visible_carrier`：观众和人物实际看见/听见了什么；
2. `supported_claim`：该载体直接支持的最强结论；
3. `unresolved_inference`：仍可能成立、但现有载体没有证明的解释或责任归属。

例如，一台设备只对 `00:17` 作出反应，可以支持“设备识别 `00:17`”，却不能单独证明
“某个特定人物把记录改掉”。后者若仍影响行动，应保持 `suspected/unknown`，等待新的
独立载体，而不是因角色说得笃定就升级成 `known`。

**`reviewed_invariant · STY-15`**：信息权限升级必须与 `supported_claim` 相称；审查者
引用载体、直接结论和未决推断，阻止道具反应、巧合或单方陈述被扩写成其未证明的世界
事实。创作者可以选择角色误判，但要把角色信念与观众/世界权限分开记录。

铺垫是一笔债务，不是装饰：

- 首次出现要有当前场景的表面理由；
- 记录观众自然会怎样理解；
- 记录承诺回答的问题；
- 回扣时既回答旧问题，又改变当前选择；
- 改写铺垫后，标出受影响的分集、资产和镜头。

引用是否存在属于 `structural_invariant`；铺垫是否自然、回扣是否有力属于
`reviewed_invariant`。

## 7. 用双轨节奏安排张弛

双轨节奏分别记录：

- **外部压力**：事件密度、对抗强度、时间限制、空间风险；
- **内在情感负荷**：人物正在处理的损失、羞耻、希望、亲密、恐惧或道德冲突。

两轨可以同步，也可以错位：

- 外部高 / 情感高：爆发与不可逆选择；
- 外部高 / 情感低：熟练执行、冷静追逐、程序性危机；
- 外部低 / 情感高：等待、照料、隐瞒后的余震；
- 外部低 / 情感低：必要交接或呼吸，需控制篇幅并保留潜在压力。

**`craft_default · STY-14`**：分集与场景规划同时写外部压力和情感负荷，并说明与
上一单元相比为何升、降或错位。不要为了画出波浪而机械交替；节奏变化应来自人物
处理后果所需的时间。

呼吸不是无事发生。好的呼吸段会让人物重新解释刚才的事、尝试修复关系、隐藏代价、
处理伤势/道具/证据，或作出下一步选择。

## 8. 建立可恢复的跨集记忆

跨集记忆只保存后续决策所需内容，不复述全文。每集接受后更新：

1. **人物**：当前目标、策略、被测试的信念、选择、代价、物理状态；
2. **关系**：权力位置、信任/债务、未说出口的交易、最近一次越线；
3. **信息权限**：世界事实、各角色与观众知道/误信的差异；
4. **铺垫债务**：已埋未回、已改义、计划回扣、受影响位置；
5. **节奏方向**：上一集两轨落点与下一集需要承接/对比的原因；
6. **精确交接**：位置、动作、持物、伤势、时间、正在发生的决定或危险。

更新原则：

- 只写变化；未变化但下一集必须继承的事实进入精确交接；
- 已完成且不再影响后续的事件压成一句或移出活跃记忆；
- 伏笔、信息权限和未支付代价不能因摘要压缩而丢失；
- 新一集开写前先读活跃记忆，再读最近一集正文核对证据；
- 摘要与已接受正文冲突时，正文事实胜出，并修订摘要 owner。

## 9. 合成示例

以下仅演示方法，人物与事件均为合成。

> 一名夜班调度员长期私改末班车日志，替临时司机掩盖迟到。她相信“只要我把记录
> 做平，所有人就能保住工作”。某夜，一辆早已注销的旧车按她伪造的时间驶入总站。

### 前史储备与切入

- 储备：她曾因如实上报导致搭档被解雇，因此开始保护性改表；这是作者需要知道的
  前史，不在开场解释。
- 切入：她正把最后一处时间改平，打印机却吐出一张不存在于系统的到站单。旧策略
  仍在执行，代价已经进入同一画面。
- 释放：磨损的旧工牌与她下意识遮住日志的动作先给证据；搭档旧事暂时保留。

### 第一集局部动作

- 目标：在交班员进门前销毁异常到站单；
- 阻碍：到站单每撕下一角，旧车广播就准确报出她的位置；
- 选择：她不再销毁，而是把纸压进当晚真实日志并签上自己的名字；
- 局部戏剧结果：异常记录获得了一个可追责的现实入口，她也失去“只是系统错误”的
  退路；
- 下一压力：交班员刷卡进门，手里拿着那名被解雇搭档的旧工牌。

### 人物与双轨节奏

- 人物进展：旧策略“替别人隐藏”第一次变成“用自己的名字承担”；这只是裂缝，
  不是完成成长；
- 外部压力：由低到高（改表→异常单→广播定位→交班员进门）；
- 情感负荷：前段被压低，签名时升高，集尾旧工牌让过去的代价重新进入现在。

## 10. 失败征兆与审查问题

### 失败征兆

- 人物小传被整段塞进首集 VO/对白；
- 开场从世界起源讲起，当前人物还没有必须完成的动作；
- 角色弧线只写“从自私到无私”，没有压力测试、选择与代价；
- 为保证每集有反转，人物无证据地反复改变立场；
- 集尾停在动作半途，而整集没有局部结果；
- 所有铺垫只为解释答案，不改变任何人的下一动作；
- “情感戏”只有慢镜与哭泣，没有人物处理后果；
- 跨集摘要很长，却遗漏谁知道真相、谁持有证据或哪笔铺垫未回；
- 一个道具只证明时间/地点/状态，却被角色或摘要直接升级成作案者、动机或完整机制；
- 固定比例、集数配额或节奏图被当成普遍阻断规则。

### 审查问题

1. 开场哪个可见证据说明世界此前已运行？哪些前史被正确保留而没有倾倒？
2. 为什么选择这个叙事切入窗口；更早或更晚会损失哪个选择？
3. 人物的追求、被保护价值、被捍卫信念与惯常策略怎样产生当前行动？
4. 若人物发生变化，压力测试、选择、局部结果与代价分别在哪里？
5. 本集在集尾钩子之前完成了哪个局部戏剧结果？
6. 新信息改变了谁的行动权限，而不只是让观众听到解释？
7. 外部压力与情感负荷为何同步或错位；呼吸段处理了什么后果？
8. 跨集记忆能否恢复人物、关系、信息、铺垫、节奏和精确交接？
9. 每个 visible carrier 直接支持什么结论？哪些责任归属或机制解释仍必须保持未决？

# 开发阶段契约

## 目录

- [独立运行与项目集成](#独立运行与项目集成)
- [所有权边界](#所有权边界)
- [制作形态需要什么](#制作形态需要什么)
- [本阶段规则](#本阶段规则)

本文件是本技能的自包含契约：预检、所有权、形态输入与规则表都在这里，
不需要读取其他技能的文件。

## 独立运行与项目集成

本技能可以单独安装并运行；下面几条说明项目工具存在时怎样集成。

1. **读取直接输入**：只读取用户明确提供或当前任务实际需要的文件，不批量加载整个项目。
2. **可选项目集成**：若存在 `short-drama.json` 且 core 项目工具可用，可以运行
   `python3 <core>/scripts/project_tool.py status <project>`，使用返回的目录布局和语言设置；
   core 不可用时，直接基于已提供输入产出本阶段文件。
3. **可选发布生命周期**：项目工具可用时，用 `publish` 原子发布并用 `--input <path>`
   声明直接输入；`accept`、`review` 与 `package` 继续承担确认、复核与交付。
4. **保持职责分离**：创作者确认、内容修订和复核是不同动作；reviewer 提修改要求，负责人改文件。

## 所有权边界

- **本阶段拥有**：系列承诺、冲突引擎、弧线、已规划的单集契约；已规划的知识/目标/关系/
  交接状态；改编取舍与题材选择。
- **本阶段继承**：创作者已接受的方向、约束、题材与受众承诺。
- **本阶段不越权**：不写逐镜事实，不指定供应商字段，不代替剧本决定场景怎么演。剧本环节
  只投影本契约，不复制它；契约变化时由本阶段发出修订，让下游刷新引用。

## 制作形态需要什么

视觉风格不是贴在提示词前面的标签。创作者已接受的视觉方向与制作形态由项目层决定并传入，
**本技能不加载形态卡，也不自行选择形态**；本节只说明本阶段需要形态回答什么、以及拿到
答案后投影成哪些字段。

形态决定属于 `craft_default`：创作者说明理由即可覆盖。形态不能创造新的
`structural_invariant`，也不能改写身份、地理、持物归属与可读文字政策。审查者不得单凭
形态偏好阻断交付。

不要用“加一句风格前缀”处理形态差异。前缀只改变检索标签；形态改变的是**必须出现和
可以省略的字段**，只有后者会被执行，也只有后者能被审查。

本阶段要向形态决定问三件事，答案写进创作简报，不写进剧本：

- **叙事职责**：这种形态要帮观众更快看懂什么、感到什么——不能只写“高级”“电影感”。
- **运动预算**：哪些段落必须全动作，哪些可以靠保持姿态、局部循环、视差或剪辑完成。
  这直接决定分集地图里哪些场面写得起、哪些要换写法。
- **未决试验**：哪些形态能力还没验证过，需要先做小样。

本阶段新增：叙事职责、形态假设、运动预算与未决试验。不产出形、材质、光或镜头层字段。

## 本阶段规则

### `STY`

| ID | Class | Knowledge |
|---|---|---|
| STY-01 | craft_default | State the promise as protagonist, pursuit, costly opposition, and recurring payoff. |
| STY-02 | craft_default | Build a repeatable conflict engine whose pressure can change power, knowledge, relationship, exposure, cost, or time. |
| STY-03 | reviewed_invariant | A beat/episode escalation must change a story state rather than repeat the same pressure louder. |
| STY-04 | craft_default | Enter with pressure active and deliver part of the promised payoff before the outgoing hook. |
| STY-05 | structural_invariant | Incoming/setup/payoff references resolve to known records or are explicitly unresolved. |
| STY-06 | taste_option | Hook, arc shape, episode count, and climax position follow the creator's format. |
| STY-07 | reviewed_invariant | Character/scene merges preserve dramatic function, knowledge permissions, relationship position, and causal bridges. |
| STY-08 | craft_default | Translate exposition through consequential behavior, evidence, spatial pressure, or dialogue strategy before adding neutral explanation. |
| STY-09 | reviewed_invariant | A reveal/reversal grows from established facts and changes a plan, explanation, relationship, or costly choice. |
| STY-10 | craft_default | Establish the recurring-payoff promise once the opening pressure makes it legible; an opening may imply, delay, or state it according to genre and creator intent. Plan each outgoing hook from the episode's local result rather than repeating a type by quota. |
| STY-11 | craft_default | Build only the prior-world reservoir needed to predict present choices, then enter where an established strategy begins to create visible cost. |
| STY-12 | reviewed_invariant | Claimed character progression cites a pressure test, choice or retreat, local result, cost, and changed visible strategy. It is recorded once per character in the story engine, not restated in every episode record; the episode carries only the local result and the outgoing pressure it produced. |
| STY-13 | reviewed_invariant | Each episode produces a local dramatic result before its outgoing hook; serialization cannot rely only on pausing an unfinished action. |
| STY-14 | craft_default | Maintain compact serial memory for character strategy/state, relationships, information permissions, setup debt, rhythm, and exact handoff. |
| STY-15 | reviewed_invariant | Calibrate each information release to what its visible carrier directly supports, while keeping unproved identity, cause, motive, or mechanism explicit as unresolved inference. |
| STY-16 | craft_default | Before scene work, estimate each planned episode's shot and duration magnitude from the project's own accepted ratios, and resolve order-of-magnitude outliers in the map; the estimate informs the creator and never blocks delivery. |
| STY-17 | reviewed_invariant | A premise device separates its creator-accepted contract (scope, failure conditions, cost, whether its own declarations are reliable) from in-fiction disclosure; the contract is accepted before the device first takes effect, while disclosure may lag, stay partial, or be misstated by a character or the device itself. Every later device ability or exemption traces to a contract clause—an untraceable one is retroactive widening—and the audience not yet knowing every boundary is never itself a defect. |
| STY-18 | structural_invariant | A multi-episode source is read through an exact-byte episode index that `verify` checks against the current source — total length, span validity, ordering, and line/byte agreement — so an edit that changes any length is reported. A same-length rewrite in place is not, and source drift still invalidates every old span, so whoever edits the source re-indexes it. Resume derives missing IDs from the current episode map rather than a last-completed guess. |
| STY-19 | craft_default | For a multi-episode source, the Agent chooses each batch from this file's measured episode spans, semantic complexity, and available context, then reads only the current slices and compact accepted handoff; no fixed episode quota substitutes for that judgment. |
| STY-20 | craft_default | Name each unit's repeating mechanism, the payoff the audience can expect from every run of it, and the condition under which the loop ends; the first run demonstrates the mechanism in full so later runs pay off on recognition, and each further run changes the opponent's knowledge, the execution difficulty, the mechanism's scope, who is now aware, or which retreat is closed. |
| STY-21 | craft_default | Retire a loop deliberately—close it, remake one of its premises, or hand it to another character—before opening the next one, and carry the stake, deadline, and exit cost forward instead of rebuilding urgency from zero; a new loop opened alongside an unsettled one weakens both. |
| STY-22 | craft_default | When returning to a long source for detail while writing downstream, retrieve with an event anchor—character plus place/object plus the current action or conflict—rather than a recurring concept term; read back the matched span instead of writing from the search summary; and before use, check the excerpt's knowledge state against the episode's entry state, treating anything ahead of it as reference only. Recall fills in detail for an accepted contract and never adds plot. |
| STY-23 | reviewed_invariant | A source fact the brief registers as unchangeable is either realized on screen inside the episodes this round covers—named in the episode record and present in that episode's screenplay—or explicitly deferred to a named episode. A visible carrier an episode record declares must actually appear in that episode's screenplay; a carrier that only works as a comparison needs both of its halves staged. Registering a fact is not paying it off. The suite runs no mechanical check for this; the reviewer cites the brief and the episode record against the screenplay. |
| STY-24 | reviewed_invariant | Each episode's directional turn and its payoff inside that episode name one concrete visible action -- who did what -- rather than only the function or state change it achieves; an opposing force's leverage is likewise written as something it has done or will do. The suite runs no mechanical check; the reviewer cites the function against the visible action that carries it, and a function with no such action is the defect. It does not require a full scene. |

规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
`reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、
`taste_option`（创作者选择，不作缺陷）。创作者已接受的事实优先于本表。

# 短剧故事开发方法

## 目录

1. 使用方式与规则分级
2. 从题材词到戏剧承诺
3. 设计能持续运转的冲突引擎
4. 让人物成为压力的制造者
5. 用状态变化判断升级
6. 管理信息、证据与兑现
7. 让主题进入选择
8. 生成真正不同的方案
9. 从引擎走向分集
10. 合成示例
11. 失败征兆与审查问题

## 1. 使用方式与规则分级

在制作 `creative-brief.md` 与 `story-engine.md` 时使用本文件。它提供决策问题，不替创作者选择题材、结局或风格。

四类规则的权限不同：

| 分类 | 适用内容 | 谁可以执行 |
|---|---|---|
| `structural_invariant` | ID、引用、已声明事实、显式矛盾 | 本地校验器可以阻断 |
| `reviewed_invariant` | 承诺是否成立、升级是否真实、行动是否可信 | 审查者引用证据判断 |
| `craft_default` | 通常能减少空转的创作做法 | 创作者可说明理由覆盖 |
| `taste_option` | 题材、弧线、钩子、叙事气质 | 只呈现选择，不阻断 |

规则标签只约束如何判断，不把审美变成机械评分。

## 2. 从题材词到戏剧承诺

“复仇”“甜宠”“悬疑”“家庭冲突”只说明货架位置，没有说明观众每次回来会得到什么。

先回答五个问题：

1. **主体**：观众跟随谁承受压力、作出选择？
2. **追求**：这个人现在想得到、守住、查明或摆脱什么？
3. **昂贵阻力**：谁或什么能让追求持续付出代价？
4. **独特矛盾**：主角最有效的策略为什么同时会伤害自己珍视的东西？
5. **反复回报**：每一集观众期待看到哪类局面变化——夺回主动、识破谎言、关系靠近、身份暴露、道德抉择，还是别的？

把答案压成一句可检验的工作陈述：

> 当【主角】用【惯常策略】追求【当前目标】时，【对抗机制】迫使其付出【核心代价】；系列反复兑现【观众回报】，直到【终止性转变】发生。

这是一张检查表，不是文案格式。自然语言可以完全不同。

**`craft_default · STY-01`**：戏剧承诺同时包含主体、追求、昂贵阻力和反复回报。缺一项时，后续常退化成题材标签或事件清单。

**`reviewed_invariant`**：实际分集必须能提供承诺过的体验。审查者应引用分集或剧本证据说明兑现/背离，不能只说“不够抓人”。

**`taste_option · STY-06`**：回报可以外放、克制、温暖、残酷或含混；主角也可以胜、败、误判或拒绝行动。

### 回报词本身不构成承诺：要写清它落在哪里

"后悔""复仇""守护""翻身"都只是回报的**名字**。同一个名字在不同观众承诺下，落点可以
完全不同，而落点决定了哪些事件算数、哪些事件白写。

以"让对方后悔"为例，至少有两种互不通用的落点：

- **落在关系上**：观众要看的是那个人意识到自己弄丢了什么，痛苦本身就是兑现，收束常常
  发生在一次无法挽回的告别或一句迟到的承认上；
- **落在地位上**：观众要看的是"没有我，你什么都不是"被当众证实，兑现必须是可核对的
  位置变化，仅有内心痛苦不够。

两种落点会挑走完全不同的事件。按第一种写却用第二种兑现，观众会觉得"赢了但不解气"；
反过来则是"解气了但不动人"。承诺阶段不写清落点，这个偏差要到中段才暴露，而那时纠正
的成本已经落在整条分集线上。

**`craft_default`**：写下回报的名字之后，再写一句它的落点——观众最后要看到的是关系
变化、位置变化、认知变化，还是别的什么。

### 回报要先有舞台，再有能力

观众期待的不是"主角获得了什么"，而是"获得之后，那些人会怎样"。这决定了铺垫顺序：
**先建立回报会被花掉的场合，再让主角拿到能力**。

顺序颠倒的典型症状是能力先到位，然后临时找一个人来被打脸——这一段无论写得多热闹，
观众都没有攒下期待，因为在能力出现之前，他们并不知道该盼什么。

可用的检查：在主角取得关键优势之前，观众是否已经认得**具体的人、具体的场合、具体的
那句话**？三样里至少要有一样是先立起来的。

**`craft_default`**：让能力、证据或身份的兑现落在此前已经建立的对象与场合上；确实需要
新对象时，先给它一段独立的建立，不与兑现同场发生。

### 承诺的压力测试

- 如果换掉人物姓名和职业，概念仍与大量故事没有区别，独特矛盾还不够具体。
- 如果对抗者只需解释一句话就会停止阻碍，阻力没有结构性。
- 如果主角不行动也能得到结果，追求没有戏剧主动性。
- 如果只有最终结局有回报，中间各集没有可兑现的体验。
- 如果每次回报都完全同形，系列缺少变化空间。

## 3. 设计能持续运转的冲突引擎

故事引擎不是“大反派不断使坏”，而是一个会对人物选择作出反应的压力回路。

### 3.1 写出一轮回路

按顺序描述：

```text
触发压力
→ 主角依据自己的信念选择策略
→ 对手/制度/关系作出有能力的反制
→ 主角得到局部结果并承担新代价
→ 权力、信息、关系、暴露、资源、时间或身体状态改变
→ 新状态制造下一轮更难的选择
```

如果删掉“选择”与“代价”仍能发生相同剧情，这一轮主要靠作者搬运事件，不是人物驱动。

### 3.2 检查引擎的六个部件

| 部件 | 开发问题 |
|---|---|
| 压力来源 | 哪个角色、规则、秘密、资源限制或关系义务会反复施压？ |
| 对抗能力 | 它为什么真的能阻挡主角，而不只是态度恶劣？ |
| 主角策略 | 主角通常怎样解决问题？该策略的优点和盲区是什么？ |
| 退出成本 | 主角为何不能离开、报警、坦白或轻易换目标？ |
| 变化空间 | 压力能在哪些状态维度改变，而不只是声量增加？ |
| 终止条件 | 什么事实、选择、关系或能力变化会让旧回路无法继续？ |

**`craft_default · STY-02`**：让压力来自多种相互作用的来源，例如人物意志、关系义务和现实约束。单一坏人若没有筹码，往往只能重复阻挠。

**`reviewed_invariant · STY-03`**：升级需要改变故事状态或后果。审查者要指出升级前后哪项状态发生变化；“更生气、更吵、更危险”若没有新的能力、知识、代价或决定，不足以证明升级。

**`taste_option · STY-06`**：引擎可以是追逐、谈判、秘密维持、关系拉扯、任务解决、身份错位或日常困境；不要求同一种商业套路。

### 3.3 给引擎留出变化

同一承诺可通过改变以下变量产生新局面：

- **权力**：谁能决定规则、分配资源、定义事实；
- **知识**：谁知道什么，谁只知道一半，谁掌握可验证证据；
- **关系**：信任、债务、依赖、联盟和边界如何移动；
- **暴露**：秘密被谁看见，公开范围和被利用方式如何变化；
- **资源**：时间、场地、证件、金钱、工具或帮助者是否可用；
- **物理状态**：距离、伤势、持物、封闭空间、天气等怎样改变行动能力；
- **道德成本**：要赢这一轮，主角必须变成怎样的人或伤害谁。

变量不是待填满的清单。每一轮只选对当前选择真正有影响的维度。

## 4. 让人物成为压力的制造者

角色小传不应只列年龄、性格与外貌。开发阶段更需要能预测选择的“行动模型”。

为主要人物写：

- **表层目标**：此刻想让什么发生；
- **保护对象**：即使失败也不愿失去什么；
- **自我解释**：他怎样证明自己的行为合理；
- **惯常策略**：控制、讨好、试探、撤退、公开、交易、冒险等；
- **筹码**：能提供或剥夺什么；
- **盲区**：对自己、他人或局势持续看错什么；
- **底线与越线条件**：什么不会做，什么压力可能迫使他做；
- **可变事实**：哪项认识或关系变化可能改变其策略。

### 4.0 观众为什么站在他这边

上面八项回答的是"他会怎么选"，全部服务因果预测。它们答不出另一个问题：**观众第一次
看见这个人时，凭什么替他着急**。一个只有压力、策略与代价的人物是**可分析的**，不是
**可跟随的**——这是"结构正确但没人看"最常见的产地：第一集看完，观众知道发生了什么，
却不知道该替谁紧张。

为焦点人物再答四问，答案要能落到第一集的可见画面上，不是形容词：

- **他正在承受什么不该由他承受的东西**？ 不公要具体、要可见——被顶掉的署名、被改的
  排班、当众被拿走的东西。观众的立场来自看见不公，不来自被告知他是好人。
- **他正在替谁扛**？ 替自己扛容易变成执拗，替一个具体的人扛才有牵引。那个人最好在
  第一集出现过，哪怕只有一个照面。
- **他想要的那样东西，观众自己是不是也想要**？ 尊严、被认出来、把一件事做完、护住
  一个人——观众能代入的欲望，比"复仇"这类抽象目标更早生效。
- **他有什么本事是观众想借来用一次的**？ 不必是金手指。看穿谎言、修好别人修不好的
  东西、在难堪的场合仍然体面，都算。这决定观众是**同情**他还是**想成为**他。

四问不必全答，但**至少要答出一条，并且它要在第一集就能被看见**。答不出来时，人物仍
可以是精确的，只是没人会跟着他走完六十集。

反面提醒：这四问不是"把人物写讨喜"。让人物一直正确、一直被善待、或者一上来就赢，
反而会同时取消不公与欲望，观众没有可替他争取的东西。可跟随来自**他想要而尚未得到**，
不来自他可爱。

### 4.1 关系不是标签，而是双向压力

不要只写“母女”“上司下属”“旧恋人”。写成两个方向：

```text
A 需要 B 提供什么 / 害怕 B 看见什么 / 用什么约束 B
B 需要 A 提供什么 / 害怕 A 拿走什么 / 用什么反制 A
```

同一个关系中的爱、债、羞耻、利益和身份可以同时存在。场景冲突来自这些力量当下无法兼得。

**`craft_default`**：让关键人物拥有独立目标和可用筹码，而不是只负责给主角递线索或制造障碍。

**`reviewed_invariant`**：关键选择应当能从人物当时掌握的事实、目标与压力中解释。审查者引用选择前的证据，不以“正常人不会这样”替代分析。

**`taste_option`**：人物可以稳定、成长、倒退、自欺或拒绝改变；变化方向由创作者决定。

## 5. 用状态变化判断升级

### 5.1 先写前后状态

对计划中的主要事件，不先问“够不够炸”，先问：

- 事件前谁占主动，事件后谁占主动？
- 新获得或失去的事实、证据、盟友、资源是什么？
- 哪段关系变得更近、更远或更不平等？
- 哪个选择现在不可撤回？
- 下一步为什么比上一步更难、更贵或更暴露？

### 5.2 区分四种常见运动

- **扩张**：同一矛盾影响到新的关系、场域或责任；
- **反制**：对手学习主角策略并封住原有路径；
- **代价落地**：先前选择的损失现在真正发生；
- **意义改变**：新证据让旧事件获得不同解释，但不抹去已发生事实。

转折不是必然等于秘密揭晓。一次拒绝、联盟变化、证据失效、承诺兑现或人物主动改策，都能改变方向。

**`craft_default`**：主要转折优先来自角色选择与此前压力的后果，偶然事件适合开启问题，不适合替人物解决核心困境。

**`taste_option`**：有的系列依靠剧烈位移，有的依靠微小但不可逆的关系变化；变化幅度服从作品气质。

## 6. 管理信息、证据与兑现

### 6.1 分开事实与认知

维护四个问题：

1. 世界中实际发生了什么？
2. 每个角色相信什么，依据是什么？
3. 观众知道什么，何时知道？
4. 哪个可见证据能改变某人的判断？

这样能避免“作者知道，所以角色也知道”或“说出秘密就自动可信”。

### 6.2 铺垫记录的是义务

一条铺垫至少记：

- `setup_id` 与首次出现位置；
- 观众当时自然会怎样理解；
- 它承诺回答的问题或造成的期待；
- 计划兑现方式；
- 若不兑现，是有意悬置、改义还是遗漏；
- 改写后哪些分集会受影响。

**`structural_invariant · STY-05`**：被引用的进入状态、铺垫、兑现与分集 ID 必须存在，或明确标为未解决。校验器只判断引用关系，不判断揭示是否精彩。

**`reviewed_invariant`**：揭示不能凭空发明先前不存在的决定性事实；若改变旧事件意义，审查者应引用旧证据与新解释，判断二者是否相容。

**`craft_default`**：兑现不仅回答问题，还让人物当下作出新选择或承担后果。纯解释会停止运动。

**`taste_option`**：观众可以早于、晚于或同步于角色知道真相；悬念、惊讶和共谋感是不同体验。

## 7. 让主题进入选择

主题不是角色替作者宣读的结论。把主题写成无法同时满足的价值：

- 诚实与保护是否能兼得？
- 被看见与保持自主是否冲突？
- 规则公平与个体补偿谁先？

然后把价值放进有代价的选择。不同人物用行动给出不同答案，剧情后果继续追问，而不是立即宣布谁正确。

**`craft_default`**：至少让核心冲突同时触碰外部目标与人物珍视的价值，胜负才不会只剩流程。

**`taste_option`**：作品可以给出明确立场、矛盾结论或开放余味。

## 8. 生成真正不同的方案

方向探索时，用“机制差异表”比较，而不是写几段同义文案：

| 维度 | 方案甲 | 方案乙 | 为什么会产生不同剧情 |
|---|---|---|---|
| 主角惯常策略 |  |  |  |
| 主要对抗机制 |  |  |  |
| 退出成本 |  |  |  |
| 反复回报 |  |  |  |
| 核心道德代价 |  |  |  |
| 引擎终止条件 |  |  |  |
| 制作负担 |  |  |  |

若各列只更换职业、地点或秘密名称，重新设计。创作者方向已明确时，不需要强行产出多个方案。

**`craft_default`**：比较方案时同时写“它擅长提供什么”和“它会牺牲什么”，避免所有选项都被包装成最优。

**`taste_option`**：创作者可以选一个、组合兼容部分，或拒绝全部方案；记录其理由以保护后续修订。

## 9. 从引擎走向分集

故事引擎准备好进入分集规划时，应能回答：

- 第一集开始前，压力为什么已经活跃？
- 主角第一次选择如何暴露其策略与盲区？
- 哪些状态维度有足够变化空间？
- 哪些铺垫有明确的兑现责任？
- 系列终止条件与当前人物距离多远？
- 视觉、场景、角色规模是否符合创作者边界？

然后转到 [episode-design.md](episode-design.md)。不要从“要多少集”倒推出重复事件；先设计必要的状态台阶，再由创作者的形式约束决定如何分集。

## 10. 合成示例

以下例子只演示机制，不是答案模板。

> **起点**：老城区一家共享厨房即将关闭。负责排班的年轻厨师想保住所有摊主的位置，却一直靠私下调换时段解决冲突。

题材词只是“职场/群像”。更可用的承诺是：

> 她每次用隐瞒和临时协调替弱势摊主争到喘息，都让公开规则更不可信；观众反复看到她用现场解决能力夺回局部主动，也看到被保护者开始要求发言权，直到她必须选择由自己控制还是让众人承担真实决定。

引擎部件：

- 压力来源：有限灶位、互相冲突的生计、即将到来的物业审查；
- 主角策略：暗中调整、先解决再解释；
- 反制：摊主根据不透明排班争夺关系，管理方以混乱为由收权；
- 退出成本：她的家人也依赖厨房收入，且过去承诺会保住团队；
- 变化空间：谁知道排班真相、谁能定义公平、联盟如何移动；
- 终止条件：排班权从个人保护转成可承担后果的共同规则，或厨房彻底失去自治。

一个**重复而不升级**的事件是：又有摊主因排班迟到，大家再次争吵，主角再次调开时段。

一个**产生状态变化**的事件是：她为保护新摊主删掉一条换班记录；被挤掉的老摊主拿着自己的订单证明公开质问。此后问题从“如何排开”变成“谁有权改记录”，主角的可信度与管理方筹码同时变化。

例子没有规定必须如何结局，也没有要求秘密揭晓或固定位置的转折。

## 11. 失败征兆与审查问题

### 失败征兆

- 概念只有题材标签、身份噱头或结局愿望；
- 对手没有筹码，只能不断升级恶意；
- 主角靠等待他人救援获得核心结果；
- 所有事件都能互换顺序，选择没有后果；
- 每一轮只是同一种羞辱、误会、争吵或营救；
- 铺垫只用于延迟说明，不改变人物选择；
- 人物关系只有标签，没有双向需要与制约；
- 未选方案被悄悄当成既定事实；
- 形式配方取代了作品自己的因果与气质。

### 审查问题

审查者应引用具体字段或分集记录回答：

1. 承诺的回报在计划中哪里被实际兑现？
2. 主角的策略怎样同时产生能力与代价？
3. 对抗者在哪些地方根据新状态作出有效反制？
4. 相邻升级改变了哪项状态，为什么不可简单复位？
5. 揭示使用了哪些已有证据，是否改义而非改写事实？
6. 主题如何通过选择与后果出现，而不是口号？
7. 哪些是创作者选择，修订有没有擅自替换？

审查结论属于单独的审查动作；开发者只能据证据修订自己的文件，不能把修订本身冒充 verdict。

#!/usr/bin/env python3
"""Mechanical intake guards for a multi-episode screenplay source.

This tool deliberately does not interpret story content.  It records exact byte
spans once, verifies them before every read, exposes one episode at a time, and
atomically merges agent-authored episode-map records in small configurable
batches.  The episode map remains the completion truth; a progress checkpoint
is only a reproducible derived cache.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
import tempfile
from pathlib import Path
from typing import Any, Iterable


MINIMUM_PYTHON = (3, 9)
if sys.version_info < MINIMUM_PYTHON:
    raise SystemExit(
        "episode_intake.py requires Python {}.{} or newer; found {}.{}".format(
            *MINIMUM_PYTHON, sys.version_info.major, sys.version_info.minor
        )
    )

SCHEMA_VERSION = "1.0.0"
CHINESE_DIGITS = {
    "零": 0,
    "一": 1,
    "二": 2,
    "两": 2,
    "三": 3,
    "四": 4,
    "五": 5,
    "六": 6,
    "七": 7,
    "八": 8,
    "九": 9,
}
CHINESE_UNITS = {"十": 10, "百": 100, "千": 1000}
CHINESE_NUMBER = "零一二三四五六七八九十百千两"
CHINESE_HEADING_RE = re.compile(
    r"^[ \t　]*第\s*([0-9]+|["
    + CHINESE_NUMBER
    + r"]+)\s*集(?:[ \t　]+\S.*|[：:][ \t　]*\S.*)?[ \t　]*$"
)
EP_HEADING_RE = re.compile(
    r"^[ \t]*#[ \t]+EP[ \t]*([0-9]+)(?:[ \t　]+\S.*)?[ \t　]*$",
    re.IGNORECASE,
)
EPISODE_ID_RE = re.compile(r"^EP([0-9]{3}|[1-9][0-9]{3,})$")
MAX_HEADING_LENGTH = 80


def chinese_to_int(text: str) -> int | None:
    if not text:
        return None
    if text.isdigit():
        return int(text)
    total = 0
    pending = 0
    seen = False
    for character in text:
        if character in CHINESE_DIGITS:
            pending = CHINESE_DIGITS[character]
            seen = True
        elif character in CHINESE_UNITS:
            total += (pending or 1) * CHINESE_UNITS[character]
            pending = 0
            seen = True
        else:
            return None
    return total + pending if seen else None


def _line_table(data: bytes) -> tuple[list[bytes], list[int]]:
    lines = data.splitlines(keepends=True)
    if data and (not lines or sum(map(len, lines)) != len(data)):
        raise ValueError("could not construct exact source line table")
    offsets = [0]
    for line in lines:
        offsets.append(offsets[-1] + len(line))
    return lines, offsets


def _heading_number(line: bytes) -> int | None:
    text = line.decode("utf-8").removeprefix("\ufeff").rstrip("\r\n")
    if len(text.strip()) > MAX_HEADING_LENGTH:
        return None
    match = CHINESE_HEADING_RE.fullmatch(text)
    if match:
        number = chinese_to_int(match.group(1))
        return number if number and number > 0 else None
    match = EP_HEADING_RE.fullmatch(text)
    number = int(match.group(1)) if match else None
    return number if number and number > 0 else None


def _episode_id(number: int) -> str:
    if number <= 0:
        raise ValueError("episode numbers must be positive")
    return f"EP{number:03d}"


def _portable_source_ref(source: Path, source_ref: str | None) -> str:
    value = source_ref or source.name
    candidate = Path(value)
    if (
        not value
        or candidate.is_absolute()
        or ".." in candidate.parts
        or "://" in value
        or "\\" in value
        or re.match(r"^[A-Za-z]:", value)
    ):
        raise ValueError("source_ref must be a portable project-relative path")
    return candidate.as_posix()


def _structural_problems(episodes: list[dict[str, Any]], data: bytes) -> list[str]:
    problems: list[str] = []
    numbers: list[int] = []
    previous_end = 0
    for position, row in enumerate(episodes, 1):
        if not isinstance(row, dict):
            problems.append(f"episode row {position} is not an object")
            continue
        match = EPISODE_ID_RE.fullmatch(str(row.get("episode_id", "")))
        if not match:
            problems.append(f"episode row {position} has an invalid episode_id")
            continue
        number = int(match.group(1))
        if number <= 0:
            problems.append(f"episode row {position} has a non-positive episode_id")
            continue
        numbers.append(number)
        if row.get("source_number") != number:
            problems.append(f"{row['episode_id']} source_number does not match episode_id")
        start = row.get("byte_start")
        end = row.get("byte_end")
        if isinstance(start, int) and isinstance(end, int) and 0 <= start < end <= len(data):
            if start < previous_end:
                problems.append(f"episode row {position} overlaps or is out of source order")
            previous_end = max(previous_end, end)
            lines = data[start:end].splitlines(keepends=True)
            if not b"".join(lines[1:]).strip():
                problems.append(f"empty episode: {row['episode_id']}")
        else:
            problems.append(f"episode row {position} has an invalid byte span")
    seen: set[int] = set()
    duplicates: list[int] = []
    for number in numbers:
        if number in seen and number not in duplicates:
            duplicates.append(number)
        seen.add(number)
    if duplicates:
        problems.append("duplicate episode numbers: " + ", ".join(map(str, duplicates)))
    if numbers:
        if numbers != sorted(numbers):
            problems.append("episode numbers are out of source order")
        missing = sorted(set(range(min(numbers), max(numbers) + 1)) - set(numbers))
        if min(numbers) != 1:
            missing = sorted(set(range(1, min(numbers))) | set(missing))
        if missing:
            problems.append("missing episode numbers: " + ", ".join(map(str, missing)))
    else:
        problems.append("no episode headings found")
    return problems


def build_index(
    source_path: str | Path, *, source_ref: str | None = None
) -> dict[str, Any]:
    source = Path(source_path)
    data = source.read_bytes()
    lines, offsets = _line_table(data)
    headings: list[tuple[int, int]] = []
    for line_index, line in enumerate(lines):
        number = _heading_number(line)
        if number is not None:
            headings.append((line_index, number))
    episodes: list[dict[str, Any]] = []
    for position, (line_index, number) in enumerate(headings):
        next_line = headings[position + 1][0] if position + 1 < len(headings) else len(lines)
        start = offsets[line_index]
        end = offsets[next_line]
        episodes.append(
            {
                "episode_id": _episode_id(number),
                "source_number": number,
                "line_start": line_index + 1,
                "line_end": next_line,
                "byte_start": start,
                "byte_end": end,
                "byte_length": end - start,
            }
        )
    return {
        "schema_version": SCHEMA_VERSION,
        "record_type": "episode_intake_index",
        "source_name": source.name,
        "source_ref": _portable_source_ref(source, source_ref),
        "source_byte_length": len(data),
        "episode_count": len(episodes),
        "episodes": episodes,
        "unmapped_spans": _unmapped_spans(episodes, data, offsets),
        "problems": _structural_problems(episodes, data),
    }


def _line_number(offsets: list[int], byte_offset: int, *, end: bool = False) -> int:
    if byte_offset not in offsets:
        raise ValueError(f"byte offset {byte_offset} is not a line boundary")
    index = offsets.index(byte_offset)
    return index if end else index + 1


def _unmapped_spans(
    episodes: list[dict[str, Any]], data: bytes, offsets: list[int]
) -> list[dict[str, Any]]:
    """Locate meaningful source bytes outside episode spans without copying them."""

    spans: list[dict[str, Any]] = []
    cursor = 0
    ranges = [
        (row.get("byte_start"), row.get("byte_end"))
        for row in episodes
        if isinstance(row, dict)
    ]
    for start, end in ranges:
        if not isinstance(start, int) or not isinstance(end, int):
            continue
        if start > cursor and data[cursor:start].strip():
            spans.append(
                {
                    "line_start": _line_number(offsets, cursor),
                    "line_end": _line_number(offsets, start, end=True),
                    "byte_start": cursor,
                    "byte_end": start,
                    "byte_length": start - cursor,
                }
            )
        cursor = max(cursor, end)
    if cursor < len(data) and data[cursor:].strip():
        spans.append(
            {
                "line_start": _line_number(offsets, cursor),
                "line_end": _line_number(offsets, len(data), end=True),
                "byte_start": cursor,
                "byte_end": len(data),
                "byte_length": len(data) - cursor,
            }
        )
    return spans


def make_manual_index(
    source_path: str | Path,
    spans: Iterable[tuple[str, int, int]],
    *,
    source_ref: str | None = None,
) -> dict[str, Any]:
    """Create a verifiable index from agent-selected, line-aligned byte spans.

    This is the escape hatch for nonstandard headings.  The agent chooses the
    boundaries; this function only binds those choices to exact source bytes.
    """

    source = Path(source_path)
    data = source.read_bytes()
    _, offsets = _line_table(data)
    episodes: list[dict[str, Any]] = []
    for episode_id, start, end in spans:
        match = EPISODE_ID_RE.fullmatch(episode_id)
        if not match or int(match.group(1)) <= 0:
            raise ValueError(f"invalid episode_id: {episode_id}")
        if not (0 <= start < end <= len(data)):
            raise ValueError(f"invalid byte span for {episode_id}")
        episodes.append(
            {
                "episode_id": episode_id,
                "source_number": int(match.group(1)),
                "line_start": _line_number(offsets, start),
                "line_end": _line_number(offsets, end, end=True),
                "byte_start": start,
                "byte_end": end,
                "byte_length": end - start,
            }
        )
    document = {
        "schema_version": SCHEMA_VERSION,
        "record_type": "episode_intake_index",
        "source_name": source.name,
        "source_ref": _portable_source_ref(source, source_ref),
        "source_byte_length": len(data),
        "episode_count": len(episodes),
        "episodes": episodes,
        "unmapped_spans": _unmapped_spans(episodes, data, offsets),
        "problems": [],
    }
    document["problems"] = _structural_problems(episodes, data)
    return document


def build_manual_index(
    source_path: str | Path,
    boundaries_path: str | Path,
    *,
    source_ref: str | None = None,
) -> dict[str, Any]:
    """Turn agent-selected one-based line starts into exact verified spans."""

    source = Path(source_path)
    data = source.read_bytes()
    lines, offsets = _line_table(data)
    boundaries = _read_jsonl(Path(boundaries_path))
    if not boundaries:
        raise ValueError("boundaries JSONL must contain at least one episode")
    prepared: list[tuple[str, int, int | None]] = []
    seen: set[str] = set()
    for position, boundary in enumerate(boundaries, 1):
        episode_id = boundary.get("episode_id")
        line_start = boundary.get("line_start")
        line_end = boundary.get("line_end")
        if not isinstance(episode_id, str):
            raise ValueError(f"boundary {position} has an invalid episode_id")
        match = EPISODE_ID_RE.fullmatch(episode_id)
        if match is None or int(match.group(1)) <= 0:
            raise ValueError(f"boundary {position} has an invalid episode_id")
        if episode_id in seen:
            raise ValueError(f"boundaries contain duplicate episode_id {episode_id}")
        seen.add(episode_id)
        if not isinstance(line_start, int) or isinstance(line_start, bool):
            raise ValueError(f"{episode_id} line_start must be an integer")
        if line_end is not None and (
            not isinstance(line_end, int) or isinstance(line_end, bool)
        ):
            raise ValueError(f"{episode_id} line_end must be an integer")
        prepared.append((episode_id, line_start, line_end))
    spans: list[tuple[str, int, int]] = []
    for position, (episode_id, line_start, explicit_end) in enumerate(prepared):
        if not 1 <= line_start <= len(lines):
            raise ValueError(f"{episode_id} line_start is outside the source")
        next_start = prepared[position + 1][1] if position + 1 < len(prepared) else None
        if next_start is not None and next_start <= line_start:
            raise ValueError("boundary line_start values must be strictly increasing")
        line_end = explicit_end if explicit_end is not None else (
            next_start - 1 if next_start is not None else len(lines)
        )
        if not line_start <= line_end <= len(lines):
            raise ValueError(f"{episode_id} line_end is outside its source span")
        if next_start is not None and line_end >= next_start:
            raise ValueError(f"{episode_id} line_end overlaps the next episode")
        spans.append((episode_id, offsets[line_start - 1], offsets[line_end]))
    return make_manual_index(source, spans, source_ref=source_ref)


def _json_bytes(document: Any) -> bytes:
    return (json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")


def _atomic_write(path: Path, content: bytes) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
    temporary = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "wb") as handle:
            handle.write(content)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temporary, path)
    finally:
        temporary.unlink(missing_ok=True)


def write_index(path: str | Path, document: dict[str, Any]) -> None:
    _atomic_write(Path(path), _json_bytes(document))


def _load_index(index_path: str | Path) -> dict[str, Any]:
    document = json.loads(Path(index_path).read_text(encoding="utf-8"))
    if not isinstance(document, dict) or not isinstance(document.get("episodes"), list):
        raise ValueError("index must be a JSON object containing an episodes list")
    return document


def verify_index(index_path: str | Path, source_path: str | Path) -> dict[str, Any]:
    problems: list[str] = []
    try:
        document = _load_index(index_path)
        data = Path(source_path).read_bytes()
    except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as error:
        return {"verified": False, "problems": [str(error)]}
    if document.get("schema_version") != SCHEMA_VERSION:
        problems.append("unsupported schema_version")
    if document.get("record_type") != "episode_intake_index":
        problems.append("record_type is not episode_intake_index")
    if document.get("source_byte_length") != len(data):
        problems.append("source_byte_length does not match")
    try:
        _portable_source_ref(Path(source_path), document.get("source_ref"))
    except (TypeError, ValueError) as error:
        problems.append(str(error))
    episodes = document["episodes"]
    if document.get("episode_count") != len(episodes):
        problems.append("episode_count does not match episodes")
    _, offsets = _line_table(data)
    previous_end = -1
    for position, row in enumerate(episodes, 1):
        if not isinstance(row, dict):
            problems.append(f"episode row {position} is not an object")
            continue
        label = str(row.get("episode_id", f"row {position}"))
        start, end = row.get("byte_start"), row.get("byte_end")
        if not isinstance(start, int) or not isinstance(end, int) or not (0 <= start < end <= len(data)):
            problems.append(f"{label} has an invalid byte span")
            continue
        if start < previous_end:
            problems.append(f"{label} overlaps or is out of source order")
        previous_end = end
        try:
            expected_line_start = _line_number(offsets, start)
            expected_line_end = _line_number(offsets, end, end=True)
        except ValueError as error:
            problems.append(f"{label}: {error}")
        else:
            if row.get("line_start") != expected_line_start or row.get("line_end") != expected_line_end:
                problems.append(f"{label} line span does not match its byte span")
        if row.get("byte_length") != end - start:
            problems.append(f"{label} byte_length does not match its byte span")
    problems.extend(_structural_problems(episodes, data))
    if not any("byte span" in problem or "overlaps" in problem for problem in problems):
        try:
            expected_unmapped = _unmapped_spans(episodes, data, offsets)
        except ValueError:
            problems.append("unmapped spans cannot be located in the current source")
        else:
            if document.get("unmapped_spans") != expected_unmapped:
                problems.append("unmapped_spans do not match bytes outside episode spans")
    # Avoid multiplying an identical structural message if a hand-edited index
    # already carried it in its advisory problems field.
    problems = list(dict.fromkeys(problems))
    return {"verified": not problems, "problems": problems}


def _require_verified(index_path: str | Path, source_path: str | Path) -> dict[str, Any]:
    result = verify_index(index_path, source_path)
    if not result["verified"]:
        raise ValueError("index verification failed: " + "; ".join(result["problems"]))
    return _load_index(index_path)


def slice_episode(
    index_path: str | Path,
    source_path: str | Path,
    episode_id: str,
    output_path: str | Path | None = None,
) -> bytes:
    if output_path is not None and Path(output_path).resolve() in {
        Path(index_path).resolve(),
        Path(source_path).resolve(),
    }:
        raise ValueError("slice output must not replace its source or index")
    document = _require_verified(index_path, source_path)
    matches = [row for row in document["episodes"] if row.get("episode_id") == episode_id]
    if len(matches) != 1:
        raise ValueError(f"episode_id must identify exactly one span: {episode_id}")
    data = Path(source_path).read_bytes()
    row = matches[0]
    content = data[row["byte_start"] : row["byte_end"]]
    if output_path is not None:
        _atomic_write(Path(output_path), content)
    return content


def _read_jsonl(path: Path, *, absent_ok: bool = False) -> list[dict[str, Any]]:
    if absent_ok and not path.exists():
        return []
    records: list[dict[str, Any]] = []
    for line_number, raw in enumerate(path.read_bytes().splitlines(), 1):
        if not raw.strip():
            continue
        try:
            record = json.loads(raw.decode("utf-8"))
        except (UnicodeDecodeError, json.JSONDecodeError) as error:
            raise ValueError(f"{path}: invalid JSONL line {line_number}: {error}") from error
        if not isinstance(record, dict):
            raise ValueError(f"{path}: JSONL line {line_number} is not an object")
        records.append(record)
    return records


def _validated_records(records: list[dict[str, Any]], valid_ids: set[str], label: str) -> dict[str, dict[str, Any]]:
    by_id: dict[str, dict[str, Any]] = {}
    for position, record in enumerate(records, 1):
        episode_id = record.get("episode_id")
        if not isinstance(episode_id, str) or episode_id not in valid_ids:
            raise ValueError(f"{label} record {position} has an episode_id outside the index")
        if episode_id in by_id:
            raise ValueError(f"{label} contains duplicate episode_id {episode_id}")
        by_id[episode_id] = record
    return by_id


def _jsonl_bytes(records: Iterable[dict[str, Any]]) -> bytes:
    return b"".join(_json_bytes(record) for record in records)


def progress(
    index_path: str | Path,
    source_path: str | Path,
    map_path: str | Path,
    checkpoint_path: str | Path | None = None,
    *,
    batch_size: int,
) -> dict[str, Any]:
    if batch_size <= 0:
        raise ValueError("batch_size must be positive")
    if checkpoint_path is not None and Path(checkpoint_path).resolve() in {
        Path(index_path).resolve(),
        Path(source_path).resolve(),
        Path(map_path).resolve(),
    }:
        raise ValueError("checkpoint must not replace the index, source, or episode-map")
    document = _require_verified(index_path, source_path)
    ordered_ids = [row["episode_id"] for row in document["episodes"]]
    records = _read_jsonl(Path(map_path), absent_ok=True)
    by_id = _validated_records(records, set(ordered_ids), "episode-map")
    completed = [episode_id for episode_id in ordered_ids if episode_id in by_id]
    pending = [episode_id for episode_id in ordered_ids if episode_id not in by_id]
    checkpoint = {
        "schema_version": SCHEMA_VERSION,
        "record_type": "episode_intake_progress",
        "completed": completed,
        "pending": pending,
        "next_batch": pending[:batch_size],
        "complete": not pending,
    }
    if checkpoint_path is not None:
        _atomic_write(Path(checkpoint_path), _json_bytes(checkpoint))
    return checkpoint


def merge_batch(
    index_path: str | Path,
    source_path: str | Path,
    batch_path: str | Path,
    current_map_path: str | Path,
    output_path: str | Path,
    checkpoint_path: str | Path | None = None,
    *,
    batch_size: int,
) -> dict[str, Any]:
    if batch_size <= 0:
        raise ValueError("batch_size must be positive")
    protected = {
        Path(index_path).resolve(),
        Path(source_path).resolve(),
        Path(batch_path).resolve(),
    }
    current_map = Path(current_map_path)
    output = Path(output_path)
    if current_map.resolve() in protected:
        raise ValueError("current episode-map must not replace an index or source input")
    if output.resolve() in {*protected, current_map.resolve()}:
        raise ValueError("merged output must be separate from every input")
    if checkpoint_path is not None and Path(checkpoint_path).resolve() in {
        *protected,
        current_map.resolve(),
        output.resolve(),
    }:
        raise ValueError("checkpoint must not replace an input or merged output")
    document = _require_verified(index_path, source_path)
    ordered_ids = [row["episode_id"] for row in document["episodes"]]
    valid_ids = set(ordered_ids)
    batch_records = _read_jsonl(Path(batch_path))
    if len(batch_records) > batch_size:
        raise ValueError(f"batch contains {len(batch_records)} records; maximum is {batch_size}")
    batch = _validated_records(batch_records, valid_ids, "batch")
    existing_records = _read_jsonl(current_map, absent_ok=True)
    existing = _validated_records(existing_records, valid_ids, "episode-map")
    added: list[str] = []
    for episode_id, record in batch.items():
        if episode_id in existing:
            if _json_bytes(existing[episode_id]) != _json_bytes(record):
                raise ValueError(f"conflicting episode-map record: {episode_id}")
        else:
            existing[episode_id] = record
            added.append(episode_id)
    merged_records = [existing[episode_id] for episode_id in ordered_ids if episode_id in existing]
    _atomic_write(output, _jsonl_bytes(merged_records))
    derived = progress(
        index_path,
        source_path,
        output,
        checkpoint_path,
        batch_size=batch_size,
    )
    return {
        "output": str(output),
        "added": [episode_id for episode_id in ordered_ids if episode_id in set(added)],
        "progress": derived,
    }


def _parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Byte-accurate multi-episode screenplay intake guard")
    commands = parser.add_subparsers(dest="command", required=True)
    index = commands.add_parser("index")
    index.add_argument("source", type=Path)
    index.add_argument("--out", type=Path, required=True)
    index.add_argument("--source-ref")
    manual = commands.add_parser("manual-index")
    manual.add_argument("source", type=Path)
    manual.add_argument("boundaries", type=Path)
    manual.add_argument("--out", type=Path, required=True)
    manual.add_argument("--source-ref")
    verify = commands.add_parser("verify")
    verify.add_argument("index", type=Path)
    verify.add_argument("source", type=Path)
    slice_command = commands.add_parser("slice")
    slice_command.add_argument("index", type=Path)
    slice_command.add_argument("source", type=Path)
    slice_command.add_argument("episode_id")
    slice_command.add_argument("--out", type=Path, required=True)
    status = commands.add_parser("progress", aliases=["status"])
    status.add_argument("index", type=Path)
    status.add_argument("source", type=Path)
    status.add_argument("episode_map", type=Path)
    status.add_argument("--checkpoint", type=Path)
    status.add_argument("--batch-size", type=int, required=True)
    merge = commands.add_parser("merge")
    merge.add_argument("index", type=Path)
    merge.add_argument("source", type=Path)
    merge.add_argument("batch", type=Path)
    merge.add_argument("current_episode_map", type=Path)
    merge.add_argument("--out", type=Path, required=True)
    merge.add_argument("--checkpoint", type=Path)
    merge.add_argument("--batch-size", type=int, required=True)
    return parser


def main(argv: list[str] | None = None) -> int:
    args = _parser().parse_args(argv)
    try:
        if args.command in {"index", "manual-index"}:
            if args.source.resolve() == args.out.resolve():
                raise ValueError("index output must not replace its source")
            if args.command == "manual-index" and args.boundaries.resolve() == args.out.resolve():
                raise ValueError("index output must not replace its boundaries input")
            document = (
                build_index(args.source, source_ref=args.source_ref)
                if args.command == "index"
                else build_manual_index(
                    args.source,
                    args.boundaries,
                    source_ref=args.source_ref,
                )
            )
            write_index(args.out, document)
            result: Any = {"output": str(args.out), "episode_count": document["episode_count"]}
            if document["problems"]:
                result["problems"] = document["problems"]
                print(json.dumps(result, sort_keys=True))
                return 2
        elif args.command == "verify":
            result = verify_index(args.index, args.source)
            if not result["verified"]:
                print(json.dumps(result, sort_keys=True), file=sys.stderr)
                return 1
        elif args.command == "slice":
            content = slice_episode(args.index, args.source, args.episode_id, args.out)
            result = {"output": str(args.out), "episode_id": args.episode_id, "byte_length": len(content)}
        elif args.command in {"progress", "status"}:
            result = progress(args.index, args.source, args.episode_map, args.checkpoint, batch_size=args.batch_size)
        else:
            result = merge_batch(
                args.index,
                args.source,
                args.batch,
                args.current_episode_map,
                args.out,
                args.checkpoint,
                batch_size=args.batch_size,
            )
    except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as error:
        print(json.dumps({"error": str(error)}), file=sys.stderr)
        return 1
    print(json.dumps(result, sort_keys=True))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Offline self-test for multi-episode source intake."""

from __future__ import annotations

import tempfile
import sys
from pathlib import Path

from episode_intake import build_index, slice_episode, verify_index, write_index

MINIMUM_PYTHON = (3, 9)
if sys.version_info < MINIMUM_PYTHON:
    raise SystemExit("selftest.py requires Python 3.9 or newer")


def require(condition: bool, message: str) -> None:
    if not condition:
        raise AssertionError(message)


def main() -> int:
    with tempfile.TemporaryDirectory() as directory:
        root = Path(directory)
        source = root / "episodes.md"
        index = root / "index.json"
        source.write_text("第1集 开端\n行动一。\n第2集 反转\n行动二。\n", encoding="utf-8")

        document = build_index(source, source_ref="输入/episodes.md")
        require(document["episode_count"] == 2, "episode count")
        require(document["problems"] == [], "valid episode index")
        write_index(index, document)
        require(verify_index(index, source)["verified"] is True, "fresh index")
        require(
            slice_episode(index, source, "EP002").startswith("第2集".encode()),
            "verified episode slice",
        )

        source.write_text(source.read_text(encoding="utf-8") + "变更。\n", encoding="utf-8")
        require(verify_index(index, source)["verified"] is False, "source drift")

    print("5 self-tests passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())