@oh-story/dsh 0.1.0

package/lib/drama/skills/short-drama-storyboard/references/production-shot-grammar.md

@@ -0,0 +1,264 @@
+# 生产分镜工艺：把剧本事实编成可审查镜头
+
+## 目录
+
+- [贯穿原则](#一贯穿原则)
+- [编号与文本](#二编号与文本分工)
+- [拆分](#三拍镜拆分规则)
+- [动作顺序交接](#四动作顺序交接给视频提示词环节的输入)
+- [镜头叙事](#五镜头叙事学摄影决策问题)
+- [戏型诊断](#六场景戏型诊断问题)
+- [项目选择](#七项目选择craft_default)
+- [单集时长加总](#七之二单集时长加总sht-16)
+- [人物反应](#八人物反应sht-11)
+- [自检](#九自检清单)
+- [范例](#十范例合成决策记录不是镜头配额)
+- [反模式](#十一反模式)
+
+来自对剧本拍、分镜、关键帧与视频提示词如何衔接的定性案例阅读，示例均为合成改写。
+方法论见 [shot-craft.md](shot-craft.md) 与 [keyframe-craft.md](keyframe-craft.md)；
+本文档是生产端的转换规则和判断依据。出现的数字只有被创作者纳入项目方案
+（`craft_default`）后才是验收条件，不能只因偏离示例就判为问题。
+
+核心认知：**分镜先说明剪辑覆盖范围和可审查的起止边界，不是下游视频提示词**。
+它说明本镜为何存在、观众能知道什么、从哪一状态到哪一状态；只有已接受的制作方案
+需要时才补充时间段意图，完整动作措辞由视频提示词环节编写。`start_boundary` 可以是
+静止关键帧，也可以是上游明确的运动中瞬间，不能把“静帧输入”误写成故事必须静止。
+
+## 一、贯穿原则
+
+1. **一镜一职责**（SHT-03 的生产表述）：每镜有一个主导叙事职责。台词、反应与动作
+   可同镜存在，只要镜头时长、表演负荷和注意顺序可执行；过载时按行动转向、听者后果或
+   力学阶段拆镜，不按句号机械切镜。
+2. **先后顺序守住上游内容**：镜头记录必要动作与反应的相对顺序，不代写完整运动提示词。
+3. **几何要可比较**：方向、距离、占比或停留只在能消除当前歧义时量化；数值来自
+   已接受的项目方案，不是每镜必填。
+4. **摄影行为有职责**（SHT-04）：运镜或有意固定机位都应能说明它如何服务注意力、
+   压力、观众立场、揭示或节奏，而不是给每镜强加运镜。
+5. **连续性靠已确认边界比较**：精确绑定 `Location/View`、`start_boundary` 与
+   `end_boundary`；下游只
+   重复执行必需的局部状态，不逐镜复制整份状态表。
+
+## 二、编号与文本分工
+
+- 分镜号 = `场序-镜序`。**场序按 clip 内"地点组"顺位**：换地点才递增，同地点的
+  多个剧本场共用前缀；剧本自带集号时用三段式 `64-1-1`。
+- 文本分工：保留该镜覆盖的剧本原文；用简短中文纲要说明谁做什么以及镜头职责，供
+  人工审阅；另记录镜头目的、起止边界和摄影意图。完整时间过程由视频提示词环节编写。
+  **纲要写差 = 人审索引
+  失效**——"开场"两个字的纲要是真实事故案例。
+
+## 三、拍→镜拆分规则
+
+| 剧本形态 | 拆法 |
+|---|---|
+| 一拍 = 一句台词 + 一个动作 | 若同一镜头目的和边界可承担，可保留一镜；不是等式 |
+| 一拍含多次行动转向或听者后果 | 按议程变化、听者反应与可执行语速拆镜；不使用固定句数/字数配额 |
+| 一拍是爆发动作 | 若单镜过载，可按起势/接触/结果等力学阶段拆，切点绑定精确状态 |
+| 一拍是纯反应/沉默 | 只有承担反应或选择后果时独立成镜；停留由后果与节奏决定 |
+
+**建立镜头**是常见选择：新地点若观众尚不能定位人物、入口或冲突区域，
+用合适景别交代；若前镜已经建立地理，或上游有意让观众先迷失/延迟识别，就不为
+凑“第一镜全景”自增。任何新增镜头仍须解释它覆盖的内容与信息职责。
+
+## 四、动作顺序交接（给视频提示词环节的输入）
+
+需要把复杂动作交给视频提示词环节时，可用中性顺序草图：
+
+```text
+起点：<已接受镜头边界，可静止也可在运动中>
+顺序：<上游动作> → <必要反应或注意力转移> → <已接受终点>
+摄影意图：<固定/移动及其叙事职责>
+```
+
+- 起点逐字段写入已接受的 `start_boundary`，不把静态关键帧的媒介性质改成“人物必须静止”；
+- 结束状态由分镜文件记录，下一镜通过引用比较，不靠复制长篇说明获得权威；
+- 并行槽只放有来源的变化：他人反应、环境压力或持续运动锚点可以
+  帮助画面成立，但没有叙事/物理依据时宁可保持静止，不为满足配额发明微动态；
+- 只有已接受的时长或制作方案要求时才写秒数、角度或位移；它们是当前镜头选择，
+  不是跨项目动作质量公式；
+- 台词保持精确引用与相对动作顺序；是否把动作展开成更多阶段取决于时长和表演负荷。
+
+**质量问题**：不改动台词和上游顺序时，这个镜头是否仍明确谁承载信息、谁接收
+后果、画面从什么边界到什么边界，以及为什么此处需要切镜？
+
+## 五、镜头叙事学（摄影决策问题）
+
+| 需要解决的问题 | 先核对 | 可选实现，不是映射答案 |
+|---|---|---|
+| 信息必须被读到 | 通过脸、手、道具文字、空间关系还是声音呈现？何时允许看见？ | 固定机位、跟随信息所在位置、改变焦点或切到接收者 |
+| 观众立场改变 | 观众此前与谁同知、此刻为何要靠近或疏离？ | 保持原视点、换主观侧、拉开关系或有意拒绝切换 |
+| 空间压力改变 | 谁控制入口、距离、路径或画外威胁？地理是否已经建立？ | 调整机位、跟位移、用遮挡，或保持固定让调度自己改变关系 |
+| 力学动作需要理解 | 起势、接触、结果中哪些必须连续看清，哪些切点已有精确状态？ | 单镜保持、按力学阶段拆、补细节镜头或反应镜头 |
+| 情绪后果需要落地 | 哪个可见处理或选择证明人物接收了后果？ | 留在同镜、切反应、延迟到后镜；景别由信息或表演所在位置决定 |
+
+一场通常比它真正要演的景别先开宽一档，第二镜就落到本场的**工作景别**，之后多数切镜在
+这一档上下一格来回；宽景和特写是**离开**工作景别的标记事件，用过就回来，场尾略微放开是
+常见收法。例如两人在客厅摊牌：第 1 镜全景交代谁堵着门口，第 2 镜落到中景这个工作景别，
+之后在中景与中近景之间对切，只有她把信封推过茶几时切一次特写，随即回到中近景，场尾退回
+中景收住。一路单调收紧的场次到中段就没有余量了。也可以用细节、背影、负空间或不切镜保持
+压力；顶点后的拉远同样只是选项。选择必须回应本场注意力、观众立场和信息揭示变化，不从
+“情绪顶点=大特写”“结束=上帝视角”套模板。正反打、过肩和轴线策略服从已建立地理
+与有意的视角变化。
+
+### 切点必须带来可见变化
+
+上一段拒绝的是“按情绪套景别”，不是“景别可以原地不动”。两者的分界线是**这里到底切
+不切**：
+
+- **不切镜**：同一景别持续本身就是选择。压力累积、人物在同一构图里自己改变距离、
+  观众被迫一直看着不肯变的画面，都是有效理由。
+- **已经切镜**：新镜必须在景别、机位角度或人物关系里至少改变一项。相邻两镜景别相同、
+  角度相同、关系也没变时，观众读到的不是节奏，是跳切或穿帮——这个切点没有存在理由。
+  修法只有三种：让收放跟着注意重点走（最常见是沿阶梯相邻一格一收一放：
+  中景↔中近景↔近景↔特写），换轴线侧或视点，或者干脆并成一镜、用调度在镜内改变关系。
+- **新空间的第一镜**通常先给得开一些，让观众定位后再逐步收进去；但前镜已经建立地理，
+  或上游有意延迟识别时，不为“第一镜要宽”自增镜头（见第三节）。
+
+这条规则只在已经决定切镜时生效。它不是为景别多样性增加切点的理由：切多少镜仍由动作
+边界、听者反应和信息变化解释，收放幅度也要能说出注意力或观众立场变化在哪里。
+
+变焦推拉（Dolly Zoom）、荷兰角或甩镜是点睛手段；只有视角、失衡或注意力突然改变时才使用。
+重复使用会让每个节点失去差异，但不能靠固定次数判断（SHT-07）。
+
+### 角度、机位高度与焦段：三件常被写成一件的事
+
+景别有受控词表，角度长期只有一句"有动机的角度"，结果三种彼此独立的选择被压进同一个词。
+最常见的具体后果：写"俯拍"时其实想要的是"从她背后越过肩膀"（那是**水平角度**，不是高度），
+下游按字面给了一个从上往下的机位，权力关系当场反了。
+
+分三栏写，缺哪栏就说明哪栏无所谓：
+
+| 维度 | 词表 | 它在故事里回答什么 | 记在哪 |
+|---|---|---|---|
+| **水平角度** | `正面 / 斜侧（四分之三）/ 正侧 / 后斜侧 / 背面` | 观众被允许读到多少表情，以及站在谁的一侧 | 镜头 `framing.angle`，同时说明在轴线哪一侧 |
+| **机位高度** | `地平 / 低（仰）/ 平视 / 高（俯）/ 顶视` | 谁在这一刻大于谁；平视是**主动**表示势均力敌，不是"没选" | 镜头 `framing.camera_height` |
+| **焦段意图** | `广（空间关系优先）/ 标准（接近肉眼）/ 长（压缩纵深、隔离主体）` | 人与人的距离该显得更远还是更近 | 关键帧 `camera.lens_intent`（**帧级选择**） |
+
+前两栏是镜头拥有的调度事实，关键帧只投影不覆盖；焦段意图是关键帧自己的选择，因为它
+决定的是这一帧怎么被看，不改变人在哪、谁大于谁。不要在镜头记录里再写一次焦段——
+同一事实两处各写一份，改动时必然只改一处。
+
+三者互不推导，写死一栏不代表另两栏有了答案：
+
+- 仰拍不等于正面。从背后仰拍是"我们跟在他身后而他正在变大"，从正面仰拍是"他正压向我们"。
+- 长焦不等于特写。用长焦拍全景会把纵深压平，让两个人看起来贴在一起——这可能正是要的，
+  也可能是把"隔着半个房间对峙"拍成了"面对面"。
+- 焦段意图属于 `taste_option`（`SHT-07`）：写的是**要什么效果**，不是器材参数。写"长焦"
+  是意图，写具体毫米数是把创作者的器材决定替他做了。
+
+竖屏还有一条不能忽略：**高度变化在竖屏里比横屏更贵**。9:16 的画面纵向本来就长，俯仰会
+迅速吃掉人物所在的可用高度，同样的俯角在竖屏里读起来比横屏强得多。要靠角度表达权力时，
+先看水平角度和距离能不能承担，再动高度。
+
+## 六、场景戏型诊断问题
+
+- **对峙戏**：双方议程和可用筹码是什么？哪次行动真正改变距离、证据、关系或退出
+  能力？谁必须接收改变？只有这些转向需要新镜头。
+- **动作戏**：观众必须理解哪条路径、接触和结果？人物选择与代价落在哪里？先保证
+  地理和道具归属，再决定连续保持、拆力学阶段或切反应。
+- **情绪戏**：触发是什么，人物如何可见地处理，它促成什么选择或抑制？沉默、对白、
+  手部、空间距离和不切镜都可承载，不把情绪名自动匹配到特写或推拉摇移。
+- **悬疑/恐怖**：观众、角色与威胁分别知道什么？`show_now/withhold_now/reveal_trigger`
+  分别由什么画面或声音呈现？遮挡既不能提前泄露，也不能藏掉本镜负责交付的证据。
+- **喜剧**：铺垫事实、误读和纠正由谁看到？笑点可能来自节奏时机、构图内并存或切换，
+  不要求固定反应次数，也不让反应镜解释已经成立的笑点。
+
+## 七、项目选择（`craft_default`）
+
+| 决策 | 如何确定 |
+|---|---|
+| 拍如何拆镜 | 由动作边界、听者反应、空间变化与可执行时长共同决定，不追求固定比值。 |
+| 台词如何分配 | 先保证一次可表演语气与口型负载；过长时按行动转向拆分，而非机械按字数。 |
+| 单镜还是镜头组 | 先把每个镜头写成可单独审查的记录，再按目标交付方式编组；编组不改变镜头身份。本环节只负责镜头本身：定清每个镜头的目的、起止边界与已接受时长。编组之后由谁承担时长加总与成员资格，属于交付环节的事，不在这里决定，也不因为将来会编组就提前合并镜头。 |
+| 子镜密度 | 9:16 信息流上的注意力是按切镜买的：`craft_default` 是可看的切镜密度大致每 4–8 秒一次，爽点更紧、情感处理更松在这条带宽内浮动，每次切换仍要有注意、压力或状态理由。项目把生成单元固定在更长的一档时，这条带宽由镜内调度承担——一镜里要有景别或视点的实际变化、或一次完整的动作与反应交接，否则无论单帧多好，观众读到的都是幻灯片。 |
+| 单元时长 | 先从必须保留的动作、反应、对白与最终状态反推这一镜需要多久；放不下就删减、拆镜或请求改边界。项目已经定下可用的生成长度档位时，取容得下它的最短一档；没定就按反推出的秒数写，并把用到的档位报给创作者。超过约五到八秒后，一张冻结关键帧只描述了镜头开头，其余部分实际上没有规格：更长的镜头要么按精确状态边界拆开，要么由创作者明确接受它是一个宽规格镜头。 |
+
+## 七之二、单集时长加总（`SHT-16`）
+
+创作者在项目里写下的每集目标时长，如果全流程没有一处消费它，它就只是一个愿望。
+真实的失效是这样发生的：分镜逐镜看都合理，每一镜的时长也都是有理由的，直到全集镜头
+装到一起才发现比目标长出三分之一——而此时台词、资产、关键帧提示词都已经按这些镜头
+做完了，唯一还能改的只剩硬删。
+
+`structural_invariant`：覆盖记录带一个 `episode_duration`，它的 `shot_seconds_total`
+必须是本集镜头 `duration_seconds` 的**算术和**，且覆盖里列出的每个镜头要么贡献一个数字，
+要么出现在 `unresolved_durations` 里。这条只管账目对不对：**不允许有镜头无声地不进总和**。
+时长未定的镜头显式挂起是正常状态，静默漏掉不是。
+
+项目声明了 `target_seconds_per_episode` 时，记录还要绑定该字段并写出带符号的
+`delta_seconds` 与一个 `disposition`：
+
+| disposition | 含义 |
+|---|---|
+| `no_target_declared` | 项目没有声明目标，本项只留总和 |
+| `within_creator_tolerance` | 差值在创作者可接受范围内 |
+| `creator_accepted_overrun` | 超出但创作者明确接受，附理由 |
+| `to_revise` | 需要回到内容层处理 |
+
+`craft_default`：差值本身**不阻断交付**。目标时长是计划，不是质量门槛；`to_revise` 的
+处理手段是回到内容层（合并同质节拍、把说明改成传递、拆集），不是按数字均匀删镜头或
+砍台词——后者砍掉的往往正是兑现。
+
+这条与分集阶段的量级估算是两件事，不要互相代替：估算用项目已接受集的比值预测**还没写的
+集**，第一集因为没有基准而跳过；加总用**已经存在的镜头**做测量，第一集同样成立。第一集
+拿不到估算，但拿得到测量。
+
+## 八、人物反应（SHT-11）
+
+对白覆盖存在不等于后果被接收。关键信息改变听者的权力、关系、知识或选择时，必须
+在本镜或后续独立镜中给出可见处理与最终状态；景别、时长和是否切镜由后果重量、表演动作
+及项目节奏决定。群像可用全场与个体两级反应，但这只是表现选项，不是固定组合。
+
+## 九、自检清单
+
+只检查与当前镜头有关的项目；不要为通过清单补写无来源动作、镜头或文字。
+
+1. 台词、行动、证据或沉默由什么可见/可听载体承担？有没有把以对白为主的合法镜头
+   误判成必须添加动作？
+2. `start_boundary` 与 `end_boundary` 是否逐字段可比较？运动中边界、停顿和静止都与上游内容相容吗？
+3. 摄影选择或有意固定机位能回答它怎样服务注意力、观众立场、信息揭示、
+   空间或节奏吗？
+4. 并行微动态有上游或环境依据吗？没有时是否避免为“画面活”而硬加？
+5. 表演状态的变化或保持是否符合触发、人物策略与局部结果？克制不变是否正是选择？
+6. 当前理解若依赖新地理，是否交代了必要锚点？若有意延迟识别，是否记录观众可见边界？
+7. 台词与反应在所选时长/语速内可执行吗？对照剧本是否遗漏或改变相对动作顺序？
+8. 镜头数量能由覆盖内容、动作边界、听者反应和时长解释吗？本集时长总和是否已加出来，
+   时长未定的镜头是否显式挂起而不是漏掉？
+9. 每镜人物站位与上一镜衔接吗？（位置漂移是高频退回原因）
+10. 手部与持物能否逐步执行？放下、换手、双手动作、递交/取回是否有可见来源？
+11. 上游 `exact_readable` 字段是否有显示位置和处理方式，且没有被通用 `no_text` 覆盖？
+
+## 十、范例（合成决策记录，不是镜头配额）
+
+### 对峙中的证据递交
+
+- **上游必保内容**：甲把账页交给乙；乙读到签名后停止否认。
+- **为何切镜**：递交改变道具归属，乙的停顿证明信息被接收；两项可同镜完成时不拆。
+- **观众可见边界**：账页内容只需让乙可读，观众通过签名位置和乙的选择理解，不自动补
+  大特写或屏显全文。
+- **摄影意图**：若同一构图能同时保住交接与反应则固定机位；若手部遮掉签名位置，
+  才调整焦点或切细节镜头。选择由信息所在位置决定，不由“对峙戏”标签决定。
+
+### 动作是否拆镜
+
+- **上游必保内容**：角色越过桌面夺走钥匙并退到门边。
+- **单镜成立条件**：路径、接触、道具归属和退路都可读，且已接受时长足以完成。
+- **拆镜条件**：遮挡使钥匙易手不可读，或退到门边需要新的空间边界；切点绑定钥匙
+  在谁手中、双方位置和朝向，而不是套“起势—发力—结果”固定链。
+
+### 保持不动也可能是有效表演
+
+- **上游必保内容**：威胁落下后，角色拒绝给对方可利用的反应。
+- **实现判断**：稳定目光、没有退让和有意固定机位可以是人物策略；不为通过
+  “情绪必须变化”检查添加吞咽、握拳或无来源微动作。
+
+## 十一、反模式
+
+1. 旁白切片当分镜（小说旁白按逗号切进纲要，视频提示词全是“嘴唇开合说话”空壳）。
+2. 资产管理名泄漏进画面文本（占位文件名出现在视频提示词正文里）。
+3. 图片引用标记侵入台词内文。
+4. 无动机运镜（"镜头静止。"单独出现不解释）。
+5. 台词标点+句式句号叠加（"血口喷人！。"——收尾句号只加在无标点台词后）。
+6. 负面约束堆砌淹没内容（防缺陷补丁头尾重复 150+ 字，正文动作被稀释——补丁
+   只在目标模型确有该缺陷时使用）。

package/lib/drama/skills/short-drama-storyboard/references/review-and-fixtures.md

@@ -0,0 +1,70 @@
+# 分镜诊断目录：可机器判定的那一部分
+
+## 目录
+
+- [这份目录只收什么](#这份目录只收什么)
+- [诊断目录](#诊断目录)
+- [不进这份目录的东西](#不进这份目录的东西)
+
+## 这份目录只收什么
+
+本文只登记**不需要读懂戏就能判定**的分镜缺陷：时长账目的算术、关键帧声明的边界是否
+与它绑定的字段一致、边界条目有没有写成常见的回指说法、每条引用是否解析得到一个上游快照。它们由
+[storyboard_check.py](../scripts/storyboard_check.py) 执行，`enforcer` 一律是 `validator`。
+脚本读引用时先取文件的 `sources` 声明，再按每条引用的 `src` 取回 `owner` 与 `artifact`。
+
+分成脚本与审查两条路的理由很实际：账目类错误由人来核对既慢又不可靠——覆盖里少写一个
+镜头 ID，肉眼看过去和写全了完全一样。把这类工作交给脚本，审查者的注意力才能留给
+真正需要判断的东西。
+
+## 诊断目录
+
+| code | classification | enforcer | 默认 severity | owner | 含义 |
+|---|---|---|---|---|---|
+| REF_SRC_IS_NOT_DECLARED | structural_invariant | validator | error | storyboard | 引用的 `src` 在本文件 `sources` 里没有声明 |
+| REF_HAS_NO_UPSTREAM_BINDING | structural_invariant | validator | error | storyboard | 引用既没有 `src`，也没有完整的 `owner`/`artifact` |
+| REF_IS_NOT_AN_OBJECT | structural_invariant | validator | error | storyboard | 引用位置上不是一个对象 |
+| SOURCE_ENTRY_IS_INCOMPLETE | structural_invariant | validator | error | storyboard | `sources` 条目缺少 `owner` 或 `artifact` |
+| SHT05_BOUNDARY_ENTRY_IS_A_BACK_REFERENCE | structural_invariant | validator | error | storyboard | 边界条目整条是「同上」「位置不变」这类回指，没有写出绝对事实 |
+| SHT16_RECORD_MISSING | structural_invariant | validator | error | storyboard | 覆盖记录没有 `episode_duration` |
+| SHT16_RECORD_INCOMPLETE | structural_invariant | validator | error | storyboard | `episode_duration` 缺少 `counted_shot_ids` 或 `unresolved_durations` |
+| SHT16_SHOT_LEFT_THE_TOTAL | structural_invariant | validator | error | storyboard | 覆盖列出的镜头既不计入总和也没被挂起 |
+| SHT16_SHOT_COUNTED_AND_UNRESOLVED | structural_invariant | validator | error | storyboard | 同一镜头既算进总和又列为未定 |
+| SHT16_SHOT_UNRESOLVABLE | structural_invariant | validator | error | storyboard | 时长记录点名的镜头不在镜头文件里 |
+| SHT16_COUNTED_SHOT_HAS_NO_DURATION | structural_invariant | validator | error | storyboard | 计入总和的镜头没有数值 `duration_seconds` |
+| SHT16_SUSPENDED_SHOT_HAS_A_DURATION | structural_invariant | validator | error | storyboard | 挂起为未定的镜头其实已有时长 |
+| SHT16_TOTAL_MISSING | structural_invariant | validator | error | storyboard | `shot_seconds_total` 不是数值 |
+| SHT16_TOTAL_IS_NOT_THE_SUM | structural_invariant | validator | error | storyboard | 总和不等于各计入镜头时长之和 |
+| SHT16_DELTA_MISSING | structural_invariant | validator | error | storyboard | 声明了目标却没有带符号差值 |
+| SHT16_DELTA_IS_WRONG | structural_invariant | validator | error | storyboard | 差值不等于总和减目标 |
+| SHT16_SHOT_LISTED_TWICE | structural_invariant | validator | error | storyboard | 同一镜头在时长记录里出现多次，会被加两次 |
+| SHT16_EPISODE_SHOT_LEFT_THE_TOTAL | structural_invariant | validator | error | storyboard | `shots.jsonl` 里的镜头既不计入总和也没被挂起 |
+| SHT16_DISPOSITION_MISSING | structural_invariant | validator | error | storyboard | 声明了目标却没有对差值的处置 |
+| SHT16_DISPOSITION_CLAIMS_A_TARGET | structural_invariant | validator | error | storyboard | 没有目标却给出了判断目标的处置 |
+| SHT17_KEYFRAME_HAS_NO_ID | structural_invariant | validator | error | storyboard | 关键帧记录没有 `keyframe_id` |
+| SHT17_BOUNDARY_ROLE_MISSING | structural_invariant | validator | error | storyboard | 关键帧没声明它冻结的是哪一端 |
+| SHT17_BOUNDARY_REF_MISSING | structural_invariant | validator | error | storyboard | 关键帧没有绑定它投影的边界 |
+| SHT17_BOUNDARY_REF_DISAGREES_WITH_ROLE | structural_invariant | validator | error | storyboard | 声明的角色与绑定的边界字段不一致 |
+| SHT17_BOUNDARY_REF_UNRESOLVABLE | structural_invariant | validator | error | storyboard | 关键帧绑定的镜头不在镜头文件里 |
+| SHT17_DUPLICATE_BOUNDARY_KEYFRAME | structural_invariant | validator | error | storyboard | 同一镜头的同一端有两张关键帧 |
+| SHT01_BLOCK_UNCLAIMED | structural_invariant | validator | error | storyboard | 处理为 `covered`/`intentional_repeat` 的块没有镜头认领 |
+| SHT01_BLOCK_CLAIMED_TWICE | structural_invariant | validator | error | storyboard | 非 `intentional_repeat` 的块被多个镜头认领 |
+| SHT01_BLOCK_IS_ON_SCREEN_ANYWAY | structural_invariant | validator | error | storyboard | 记为不拍的块却有镜头认领 |
+| SHT01_BLOCK_NOT_IN_SCREENPLAY | structural_invariant | validator | error | storyboard | 镜头认领的块不在剧本索引里 |
+| SHT01_BLOCK_HAS_NO_DISPOSITION | structural_invariant | validator | error | storyboard | 有制作相关的块没有写处理 |
+| SHT01_DISPOSITIONS_MISSING | structural_invariant | validator | error | storyboard | 覆盖表没有 `dispositions` |
+| SHT01_DISPOSITION_MALFORMED | structural_invariant | validator | error | storyboard | 处理行不是对象或没点名块 |
+| SHT01_DISPOSITION_UNKNOWN | structural_invariant | validator | error | storyboard | 处理不是工作流定义的四种之一 |
+| SHT01_DISPOSITION_REPEATED | structural_invariant | validator | error | storyboard | 同一个块写了多行处理 |
+| SHT01_DISPOSITION_NOT_IN_SCREENPLAY | structural_invariant | validator | error | storyboard | 处理点名的块不在剧本索引里 |
+| SHT01_DISPOSITION_HAS_NO_REASON | structural_invariant | validator | error | storyboard | 重复或省略是决定，必须写理由 |
+| SHT01_SCREENPLAY_IS_NOT_FULLY_INDEXED | structural_invariant | validator | error | storyboard | 剧本索引里还有没归类的行，覆盖检查看不到剧本的全部 |
+
+## 不进这份目录的东西
+
+- **目标时长的差值本身**：`SHT-16` 只让脚本核对差值算得对不对。差值多大是创作者的判断，
+  目标时长是计划而不是质量门槛，脚本不因为差值大小报错。
+- **关键帧数量**：默认一张首帧，只在交付工作流真的消费尾帧时才有第二张。缺尾帧不是缺陷，
+  脚本也不检查"是否该有尾帧"。
+- **镜头拆得对不对、景别选得对不对、构图好不好**：这些需要读懂本场在做什么，属于审查者，
+  判据在本技能的工艺参考里，不在这份目录。

package/lib/drama/skills/short-drama-storyboard/references/scene-visual-plan.md

@@ -0,0 +1,39 @@
+# 场次视觉戏剧计划
+
+`scene_visual_plan` 是项目级视觉方向与逐镜规格之间的可选中间层。它回答整场怎样改变观众的
+位置、空间压力、观看节奏和声音注意；它**不是第二份剧本**，也**不拥有镜头边界**。
+
+## 启用条件
+
+只在导演选择明显影响体验时使用：主要人物亮相、身份/证据揭示、关系反转、高潮/结尾、
+复杂多人调度、延迟信息的悬念场或承担视觉母题的场景。普通场景直接从原文落实进入 shots，
+不要把可选方法变成表单负担。
+
+## 写法
+
+从 `assets/scene-visual-plan.example.jsonl` 建立一条候选。场次使用 screenplay-index 中真实的
+`BLK-…` heading/action 记录；再分别绑定已接受视觉方向、制作配置、Location/View 与涉及的
+CHAR/LOOK、PROP/PSTATE。只有创作者选过 audition 时才加 `source_audition_ref` 与独立的
+`creator_selection_ref`；没有 audition 时删除这两项，不能保留占位引用。先写：
+
+1. **戏剧转向**：本场哪一种公开关系、信息或选择不可逆地改变；
+2. **观众立场**：开场站在哪一方、结束被移到哪里；
+3. **空间压力**：入口、距离、占位、遮挡、让路或退路怎样承载人物策略；
+4. **视觉推进**：什么时候让信息、反应或空间先于特写落地；
+5. **摄影节奏**：固定、移动、切近和停留分别由什么变化触发；
+6. **反应落点**：结尾画面由谁的选择或空间后果承担；
+7. **声音策略**：主导声源、主动留白、距离变化、撤出/恢复和相邻场 sound bridge。
+
+每次景别、机位或运动变化都应对应注意、关系、信息、压力或节奏变化。高潮不默认“主角特写
++ 推镜”；场尾也不只是把最后一句对白拍完。
+
+## 接受与投影
+
+先向创作者展示转向、立场、空间、摄影、关键揭示、最终落点和声音运动。创作者接受后，正式
+shots 用准确 `scene_visual_plan_ref` 投影这条策略，并继续由每个 shot 自己拥有 purpose、
+duration、blocking 与 start/end boundary。计划与剧本或资产冲突时退回 owner，不让计划覆盖事实。
+
+审查时不按字段完整度打分，而看 audience alignment、knowledge、spatial access/pressure、rhythm
+中是否至少一项产生有意变化；有意保持同一观看位置也可以成立，但要说明它怎样制造观察、困住感
+或重新解释同构画面。再看空间和声音是否共同承担同一转向，以及逐镜变化是否只是重复
+中近景—反打—推镜。

package/lib/drama/skills/short-drama-storyboard/references/screenplay-to-keyframe-example.md

@@ -0,0 +1,157 @@
+# 合成正例：从剧本段到冻结关键帧
+
+## 目录
+
+- [剧本段](#剧本段)
+- [原文落实](#原文落实)
+- [SHOT-01](#shot-01拒绝交牌)
+- [SHOT-02](#shot-02声音引导注意)
+- [SHOT-03](#shot-03证据细节)
+- [KEY-03](#key-03冻结瞬间)
+- [连续性交接](#连续性交接)
+- [（情绪）交接](#情绪交接)
+
+本例只演示剧本内容怎样逐步变成镜头、关键帧和准确产物引用，不是镜头数量答案。
+素材为全新合成。
+
+## 剧本段
+
+~~~md
+## EP004-SC002 内 · 社区洗衣房 · 清晨
+
+烘干机还在转。沈禾把一张写着“17”的取衣牌压在掌心，没有递给柜台后的蒋姨。
+
+蒋姨：你不是来取衣服的。
+
+[SFX] 烘干机停转。
+
+沈禾摊开右手。取衣牌背面粘着一小片带血的蓝线头。
+~~~
+
+假设索引已经建立 H01（场景标题）、A01（持牌动作）、D01（判断）、P01（停机声）和
+A02（摊手与蓝线头）。
+
+## 原文落实
+
+| 剧本段 | 落实方式 | 理由 |
+|---|---|---|
+| H01 | 由 SHOT-01 落实 | 建立门、柜台、烘干机和双方位置 |
+| A01 + D01 | 由 SHOT-01 落实 | 持牌不递与台词属于同一次策略对撞 |
+| P01 | 由 SHOT-02 落实 | 声音改变注意并制造停顿 |
+| A02 | 由 SHOT-02 和 SHOT-03 落实 | 前一镜交代谁摊手并守住手位，后一镜让观众读清证据；重复带来新信息 |
+
+这里没有“一段一镜”的公式。A02 在两镜中出现，是因为第一次说明谁摊手，第二次才让
+观众看清蓝线头。
+
+## SHOT-01：拒绝交牌
+
+**镜头目的**： 建立蒋姨控制柜台、沈禾控制证物的关系，让台词成为判断，而不是说明。
+
+- 开始：沈禾在柜台外，右拳握牌；蒋姨在柜台内；烘干机转动。
+- 动作：沈禾把拳压在台沿但不越过边界，蒋姨不伸手。
+- 结束：手位不变，蒋姨已经公开表示“你另有目的”。
+- 构图：纵向双人中景，柜台横线分隔双方。
+- 摄影机：固定机位，让“不递”这个选择持续存在。
+
+来源：`shots.jsonl` 首行先声明本文件用到的上游快照——
+
+~~~json
+{"record_type": "sources", "schema_version": "1.0.0", "sources": {"screenplay-index": {"owner": "short-drama-write", "artifact": "剧集/EP004/screenplay-index.jsonl"}}}
+~~~
+
+镜头记录里的每条来源引用只写这个快照键和记录 ID：
+
+~~~json
+{"src": "screenplay-index", "record_id": "BLK-EP004-SC002-A01"}
+~~~
+
+若为了增加动作而让沈禾把取衣牌交出去，就改写了故事，必须拒绝这种改动。
+
+## SHOT-02：声音引导注意
+
+**镜头目的**： 停机声让原本被机器掩盖的沉默显出来，并把注意从两人脸上引到沈禾右手。
+
+- 开始状态准确继承 SHOT-01 的结束状态。
+- 音效准确引用 P01。
+- 沈禾听见停机后先不看机器，而是决定摊开右手。
+- 结束：右掌摊开，牌正面仍贴掌，背面朝向蒋姨和观众；蓝线头存在，但本镜不要求读清。
+- 摄影机：从固定双人镜头有目的地下移，结束构图仍保留蒋姨的视线。
+
+这次摄影机移动不是为了“节奏感”，而是因为观众注意从人物判断转到证据。
+
+## SHOT-03：证据细节
+
+**镜头目的**： 让观众确认牌背粘着带血的蓝线头，同时保留蒋姨已经看见的关系。
+
+- 开始状态准确继承 SHOT-02 的结束状态。
+- 细节镜头只拍右掌、牌背和蓝线头；后景保留蒋姨眼睛和视线的模糊位置。
+- 文字政策：数字“17”在牌正面，本镜展示背面，因此不得临时翻牌制造可读文字。
+- 结束状态与开始状态相同；观众获得了新信息，但物理状态没有变化。
+- 固定机位细节镜头；停留到观众能识别颜色、血迹和附着关系。
+
+“信息变化而物理状态不变”仍然可以成为有效的镜头目的。
+
+## KEY-03：冻结瞬间
+
+~~~text
+社区洗衣房柜台外，沈禾摊开的右掌位于画面焦点；取衣牌背面朝上，
+一小片带暗红血迹的蓝线头粘在牌背边缘。右手与牌完全静止，柜台横线
+仍分隔双方，后景保留蒋姨已经落在证物上的目光。清晨冷白顶光，已经
+停转的烘干机只是空间锚点。画面不展示牌正面的“17”，不加入递交、
+翻牌、推镜或表情变化过程。
+~~~
+
+冻结检查：所有事实能在同一时刻存在。摊开右手是 SHOT-02 的动作过程；KEY-03 只写
+“已经摊开”。
+
+## 连续性交接
+
+| 字段 | SHOT-01 结束 | SHOT-02 开始与结束 | SHOT-03 开始 |
+|---|---|---|---|
+| 沈禾右手 | 握牌 | 握牌 → 摊掌 | 摊掌 |
+| 牌朝向 | 背面不可见 | 背面转向蒋姨 | 背面可见 |
+| 蒋姨目光 | 沈禾脸 | 右手 | 牌背 |
+| 烘干机 | 转 | 停 | 停 |
+| 观众知道什么 | 她拒绝交牌 | 她决定展示 | 看见带血蓝线头 |
+
+运动规格只能实现表中的箭头，不能让蒋姨夺牌、让牌正面突然朝向摄影机，或让机器重新启动。
+
+## （情绪）交接
+
+剧本对白的表演括注是**写一次、投影两处**的来源：本技能把它投影成镜头里可见的表演
+状态，视频提示词把它投影成 `delivery`。两处绑定同一条剧本记录，谁都不另起情绪名。
+下面是另一段全新合成的示例。
+
+~~~md
+## EP002-SC004 内 · 老楼梯间 · 夜
+
+角色甲：（压着嗓子）你现在放回去，我就当没看见。
+
+角色乙：（笑）你确定还找得回来？
+~~~
+
+| 位置 | 负责人 | 写什么 | 不能写什么 |
+|---|---|---|---|
+| 剧本括注 `（压着嗓子）` | 编剧 | 唯一情绪来源，随该对白块一起发布 | — |
+| 本镜表演状态 | 本技能 | 边界里可见的收敛：下颌收紧、身体不前倾、音量压在楼道回声之下 | 不把“压着嗓子”升级成“低吼”或“怒斥” |
+| 下游 `delivery` | 视频提示词 | 由同一条来源取到的语气，再落成呼吸、停顿和音量走向 | 不新起情绪词，也不与本镜表演状态相反 |
+
+两处引用同一条来源。各自文件先在 `sources` 里声明这份剧本索引的快照：
+
+~~~json
+{"screenplay-index": {"owner": "short-drama-write", "artifact": "剧集/EP002/screenplay-index.jsonl"}}
+~~~
+
+镜头记录与运动规格里的引用都写成：
+
+~~~json
+{"src": "screenplay-index", "record_id": "BLK-EP002-SC004-D01"}
+~~~
+
+- 角色乙的 `（笑）` 同样同源投影：本镜写“嘴角上扬、眼睛不动、重心后靠”，下游写
+  “句尾带气声的短笑”，两处解释的是同一条括注，不是两次独立发明。
+- 若下游认为该情绪不成立——例如楼梯间的回声让“压着嗓子”传不出信息——修订回到剧本：
+  编剧改括注并重新发布，本技能与视频提示词再各自重新投影一次。**不能**在镜头写
+  “克制”、在运动规格写“爆发”，让同一句台词挂着两个互相冲突的情绪来源。
+- 情绪来源只决定表演状态，不自动决定景别或运镜。`（压着嗓子）` 不等于必须切特写；
+  本镜给什么景别，仍由观众此刻必须读到的信息决定。