@oh-story/dsh 0.1.3 → 0.1.5

package/lib/drama/skills/short-drama-storyboard/SKILL.md

@@ -1,264 +1,142 @@
 ---
 name: short-drama-storyboard
-description: 把已接受的中文短剧剧本和资产转成原文落实表、有戏剧动机的镜头、连续性边界与冻结关键帧提示词；关键场次可先做场次视觉计划或 Coverage Audition 比较真正不同的导演方案。用户提出“拆分镜/设计镜头/做镜头表”“场次视觉计划/调度故事板”“比较导演方案/Coverage Audition”“写首帧/关键帧提示词”“检查轴线、站位、视线、持物连续性”，或需要在不生成媒体的前提下把竖屏短剧、漫剧的剧本内容转成可拍的画面时使用。
+description: 把中文短剧剧本和视觉设定写成有戏剧职责、连续性边界与冻结关键帧提示词的分镜 Markdown。用户提出“拆分镜/设计镜头/做镜头表”“场次视觉计划/调度故事板”“比较导演方案”“写首帧/关键帧提示词”或检查轴线、站位、视线、持物连续性时使用；不生成媒体。
 license: MIT
 ---
 
 # 短剧分镜与冻结关键帧
 
-先守住故事内容，再安排原文落实、空间和镜头，最后写冻结关键帧。不在这里写随时间
-变化的运动提示词，也不改写剧本或资产事实。
-
-镜头目的、边界说明与场次视觉计划是创作者读的：项目内跟随 `short-drama.json#/language`，
-独立运行时跟随用户使用的语言。关键帧的**可复制提示词正文**在项目内跟随
-`#/format/prompt_language`，独立运行时由用户指定、未指定则为 `en`。不要用
-其中一个推断另一个。ID、规则编号和字段名在两者之下都保持原样。
+把剧本和视觉事实转成有镜头职责、空间连续性和可冻结起点的 `剧集/<EP>/分镜.md`。
+每镜使用二级标题 `## SHOT-...`，同镜下用 `### 冻结关键帧提示词` 写起始帧正文。
 
 ## Quick Start
 
-离线验证时长合计和关键帧边界绑定的正反例：
-
-```bash
-python3 {技能目录}/scripts/selftest.py
-python3 {技能目录}/scripts/storyboard_check.py <coverage.json> --shots <shots.jsonl> --keyframes <keyframes.jsonl>
+```text
+用 $short-drama-storyboard 完成 EP001 的正式分镜和每镜冻结关键帧
 ```
 
-## 开始前
-
-本技能可独立安装和执行。先读取用户明确提供的剧本、资产与本任务直接输入；若当前目录是
-`short-drama` 项目且项目工具可用，可以读取 `status` 并使用其发布生命周期，但缺少 core
-或任何其他技能都不是分镜工作的阻断条件。[阶段契约](references/stage-contract.md) 给出
-本阶段边界、制作形态输入与规则表，无需读取其他技能的文件。
-
-## 按需读取资料
-
-始终读取：
-
-- 状态为 `accepted` 的 `screenplay.md` 与 `screenplay-index.jsonl`；
-- 状态为 `accepted` 的资产、版本与相关连续性；
-- `short-drama.json#/creator_authority/visual_direction` 中状态为 `accepted` 的视觉方向；
-  若状态为 `unset`，就向创作者给出选择，不从对话记忆补造。
+## 入口
 
-设计原文落实、场面调度、摄影机和剪切时读
-[shot-craft.md](references/shot-craft.md)；只有写冻结帧时读
-[keyframe-craft.md](references/keyframe-craft.md)。需要制作端的时长依据、景别与运镜
-词表或时间片写法时读 [production-shot-grammar.md](references/production-shot-grammar.md)。
-关键场次需要先组织整场的立场、空间、摄影与声音运动时读
-[scene-visual-plan.md](references/scene-visual-plan.md)；第一种合理拍法不应直接成为唯一答案时加读
-[coverage-audition.md](references/coverage-audition.md)。
-涉及背影、裁切、遮挡、画外或延迟揭示时读
-[阶段契约](references/stage-contract.md) 的参考媒体与补拍一节。
-只有所有权或直接输入影响不清楚时，才读核心所有权契约。
+当前剧本加必要视觉事实即可直接进入。资产图片提示词与分镜是兄弟分支，不互相等待。只有关键场次
+真的存在多个成立导演方案时，才在上下文比较覆盖方案；普通场次直接设计。
 
-- 竖屏多人、单房对白、证据揭示、群体轴线或门内外视角：
-  [blocking-playbooks.md](references/blocking-playbooks.md)
-- 需要查看“剧本 → 原文落实 → 镜头 → 关键帧”的完整正例，或对白表演括注
-  `（情绪）` 怎样同源投影到本镜表演状态与下游 `delivery`：
-  [screenplay-to-keyframe-example.md](references/screenplay-to-keyframe-example.md)
+创作者可读说明跟随项目语言；冻结关键帧的可复制正文跟随
+`short-drama.json#/format/prompt_language`。没有 `short-drama.json` 时正文默认使用 `en`。
+分配镜头时长前读取
+`short-drama.json#/creator_authority/production_profile/choices/native_duration_seconds`。已声明目标模型但
+没有原生时长时先补这一个选择；目标模型也未声明时照常按叙事节奏设计，不猜供应商限制。
 
-## 每轮的工作单元
+冻结关键帧写完之前，谁会出现在这一格画面里还没有定下来。所以三条依据都在关键帧之后回填，
+读的是成稿画面，不是镜头意图。
 
-一轮处理一个场次或一段连续镜头范围。整集请求按这些边界拆成若干轮，每轮：
-
-1. 只读这个范围的直接输入，做它的覆盖与镜头设计，跑本地结构检查；
-2. 落盘这个范围，其余范围保持原样；
-3. 报告已覆盖范围、剩余范围、未决 coverage 和下一个值得做的范围；
-4. 交还控制权，等创作者的下一次请求。
-
-视频提示词、生产和审查各自是独立的工作单元，由创作者明确请求时开始。
+用户没有手工点名参考图，不等于选择文生视频。冻结关键帧后先根据本镜可见人物、地点、关键道具与
+起始构图判断一致性需求，再检查项目中已有的真实图片。只有当前可读、内容与用途可核对的图片才能自动绑定；
+文件名像某个角色但内容未核对时，仍视为未准备好。
 
 ## 工作流
 
-### 1. 先确认每段原文由谁落实
-
-从 [coverage-template.json](assets/coverage-template.json) 开始，接受后发布为
-`剧集/<EP>/storyboard/coverage.json`。每个与制作有关的剧本段落都必须标明一种处理：
-
-- `covered`：由一个或多个镜头落实；
-- `intentional_repeat`：因表演或剪辑需要而有意重复，并写明理由；
-- `omitted_with_reason`：有理由地省略；
-- `nonvisual_context`：仅供理解、无需直接呈现的内容。
-
-对白、动作、画面文字、画外音或关键音效还没有着落时，不要先追求漂亮镜头。
-发布原文落实表时，先在文件的 `sources` 里为每个上游快照声明一次 `owner` 与 `artifact`，再让每条 `shot_refs` 用 `src` 指向该声明并写上 `record_id`。裸 `shot_id`
-只可表示同一镜头文件内的关系，不能证明审的是哪一版。
-
-### 2. 关键场次先比较整场导演选择（可选）
-
-只有导演选择明显改变体验时才增加本层。若存在多种真正不同的观看方法，先用
-[coverage-audition.example.jsonl](assets/coverage-audition.example.jsonl) 比较信息时机、对齐对象、
-表演空间、最强画面、落点、损失和制作相容性；创作者选择后，再用
-[scene-visual-plan.example.jsonl](assets/scene-visual-plan.example.jsonl) 把所选方法写成整场的戏剧转向、
-观众立场、空间压力、视觉推进、摄影节奏、反应落点与声音策略。只有一个明确方法时直接写计划，
-不为流程完整补 audition。
-
-这层不新增剧本/资产事实，也不拥有 shot purpose、duration 或 start/end boundary。普通场景跳过；
-不固定方案数、宫格或镜头数。
-
-### 3. 先写镜头目的
-
-使用 [shot-template.jsonl](assets/shot-template.jsonl)，接受后发布为
-`剧集/<EP>/storyboard/shots.jsonl`。每个镜头先用一句话回答：
-
-- 观众此刻必须注意什么、感到什么；
-- 信息、情绪、观众立场或权力关系发生什么变化；
-- 为什么要在这里切镜，而不是留在前一镜。
-
-同时按事实填写 `audience_visibility`：准确来源、现在展示还是暂缓展示、可见或可听的
-载体，以及各自的 `reveal_trigger`（何时揭示）和 `protection_method`（怎样防止提前泄露）。
-遮挡不是默认的画面风格：它既不能提前泄露剧本保留的信息，也不能藏掉本镜必须交代的
-证据或反应。
-
-之后才选择景别和摄影机行为。镜头不是给动作段落加几个摄影形容词。
-若本场有已接受视觉计划，每镜用准确 `scene_visual_plan_ref` 说明自己投影其中哪一段变化；
-只在这类镜头记录中新增该字段。普通场景完全省略；计划与来源冲突时退回负责人，不靠 shot 覆盖。
-
-### 4. 绑定空间和资产
-
-绑定准确的场景及视角、人物及造型、道具及状态和剧本来源段落，并建立：
-
-- 位置、朝向、视线、屏幕运动方向与轴线；
-- 进出路线和不随镜头改变的场景锚点；
-- 双手与持物、伤势与服装、文字状态、光线方向；
-- 有权威性的镜头开始边界和结束边界。
-
-可见字样必须通过 `text_treatment_refs` 指向资产负责人已接受的文字政策。预览只能
-指向带 `authority: candidate` 的候选政策。镜头和关键帧可以决定构图怎样让文字可见，
-但不得把 `exact_readable` 偷换成装饰字、凭空写新文案，或用自由文本代替政策引用。
-
-需要的资产或状态缺失、含混时，向资产或编剧环节提出修订，不要猜绑定关系。
-若创作者要求从头到尾预览，只能针对唯一且不是 `unresolved` 的提案建立临时的原文落实、
-镜头和关键帧。候选引用要明确标为待确认，不得写成已接受的绑定，
-也不得获得最终批准。
-
-### 5. 设计能够制作的镜头
-
-短镜头通常围绕一个主要动作，再保留让观众读懂后果所需的反应；这不是镜头数量公式。
-一个镜头守不住空间关系、表演、对白或信息变化时就拆开；新切镜没有增加注意重点或
-戏剧价值时就合并。
-
-上游明确的事件先后也是故事事实，不是可以为省镜头而重排的素材。把相邻镜头的开始/结束
-边界顺读一遍：冻结首帧不得提前包含本镜随后才发生的认出、松手、决定或持物变化；合并镜头
-也只能压缩停留，不能让后发生的接收跑到前一个动作之前。
-
-时长表示剪辑意图。只有明确的计时算术可以机械检查；一般的可拍性必须结合本镜内容判断。
-
-写 `duration_seconds` 之前，先按项目在 `short-drama.json` 的 `format.pacing` 里声明的速率，
-把每个镜头认领的剧本块折算成秒——台词按字数、动作段按段数，这与 `duration_estimate.py` 在
-剧本阶段用的是同一组速率。折算值是起点，为节奏调整它是创作决定；跳过折算直接凭感觉写，
-整集总时长会到覆盖检查那一步才暴露，而那时要重排的是全部镜头。项目没有声明速率时先向
-创作者要一个量级。
-
-### 6. 默认每镜一个冻结关键帧
-
-使用 [keyframe-template.jsonl](assets/keyframe-template.jsonl) 写结构化来源，发布为
-`剧集/<EP>/storyboard/keyframes.jsonl`；再用
-[keyframe-prompts.md](assets/keyframe-prompts.md) 渲染可复制的派生文本。结构化关键帧
-保存只属于单帧的选择；Markdown 不是第二份事实来源。
-
-把已接受镜头的开始边界和准确资产版本，落到一个可以同时存在的瞬间：焦点、构图、
-摄影机与镜头焦段、空间锚点、姿态、目光、双手与持物、表情、光线、排除项。
-
-`generic_prompt` 写这一瞬间要拍出来的画面本身，按 `keyframe-craft.md` 的十二项逐条写满，
-那里有一段四百余字的成稿可以照着写。它只含要被拍出来的内容——不写镜头/记录 ID、规则 ID、
-状态词与成段否定罗列（`SHT-21`）。同一集里两条关键帧的正文不应该只有编号不同：
-读起来一样，说明写的是模板不是画面。
-
-关键帧不得包含“先、再、最后”、表演变化过程、运镜过程或正在变化的环境；时间变化
-交给 `$short-drama-video-prompts`。
-
-### 7. 校验并呈现
-
-先做原文落实、参考图权限和连续性的结构检查，再按制作资料自检。
-候选预览也必须精确加总逐镜数值时长；若仍有未定时长或尚未完成这笔账，宁可省略总时长并
-列出未决项，也不要写一个与镜头表不一致的约数。
-
-时长账目与关键帧边界这两项是纯记账，交给
-[storyboard_check.py](scripts/storyboard_check.py) 核对，不要用人工目测代替：
-
-```bash
-python3 <skill-dir>/scripts/storyboard_check.py 剧集/EP001/storyboard/coverage.json \
-  --shots 剧集/EP001/storyboard/shots.jsonl \
-  --keyframes 剧集/EP001/storyboard/keyframes.jsonl \
-  --screenplay-index 剧集/EP001/screenplay-index.jsonl \
-  --project short-drama.json
-```
-
-给了 `--screenplay-index` 就多做一项覆盖对账：**剧本的每一个块都要有一种处理，而镜头认领
-必须与那种处理相符**。`covered` 要恰好一个镜头认领，`intentional_repeat` 可以多于一个，
-`omitted_with_reason` 与 `nonvisual_context` 不应有镜头认领——后两种是"决定不拍"，
-写清理由即可。认领按块 ID 走（`source_refs` 里的 `record_id`），不按正文——正文一直在改，
-块 ID 不变。
-
-处理表本身也一起校验：状态必须是上面四种之一，一个块只能有一行，指向的块要在剧本索引里，
-`intentional_repeat` 与 `omitted_with_reason` 必须写理由。此前这张表没有任何检查，
-删掉几行、填一个不存在的状态、把 `shot_refs` 指向别的镜头都能通过——覆盖表与 `shots.jsonl`
-是关于同一件事的两份独立说法，中间没有对账。
-
-它只做算术和结构比对：本集时长总和是否等于各镜头 `duration_seconds` 之和、覆盖列出的
-镜头有没有既不计入也不挂起、`shots.jsonl` 里的镜头有没有整个从总和里消失、
-同一个镜头有没有在总和里被列两次（列两次就会被加两次）、有没有边界条目整条写成「同上」「位置不变」这类回指、
-每张关键帧是否声明了 `boundary_role` 并绑定对应边界字段、
-同一镜头的同一端有没有两张关键帧、每条引用的 `src` 能否在本文件 `sources` 里解析到一个
-上游快照。有 `--project` 且项目声明了每集目标时长时，还会核对
-带符号差值。**差值不是缺陷**，脚本只检查它算得对不对。
-
-脚本报错时先修产物再继续；它不评价镜头好坏，也不决定该拆多少镜。需要逐条查诊断码
-含义、或确认某项该由脚本判还是由审查者判时，读
-[review-and-fixtures.md](references/review-and-fixtures.md)。
-
-候选选择清单必须覆盖正文中全部新增导演选择；没有必要让创作者判断的环境微动、具体手位或
-声音时机就删除，不能一面写进可执行提示词，一面在接受摘要中省略。
-摘要按选择类别总括本场全部新增的观众立场/信息时机、代表帧/最强画面/场尾落点、
-机位/景别/运动与停留、时长/节奏、手势/目光/表演信号、声音进入/撤出/留白与视觉处理，
-并声明“正文中未由来源接受的执行选择仍全部保持候选”，
-不逐镜复述已经清楚标注的细节。只点名会改变信息时机、因果顺序、观众立场或表演所有权、
-可读文字、场尾落点、制作成本或回退路径的高影响例外；正文新增项若既不在类别范围内也未被点名，
-就删除或补入摘要。总括是接受范围，不会把正文选择悄悄升级为已接受事实。
-
-若创作者尚未声明交付面遮挡区，内容构图仍可作为候选比较，但播放面避让核验保持 `blocked`，
-整体不能称为 `delivery-ready`；该缺口必须出现在本次准备度摘要中。只列真正影响当前候选判断或
-请求交付范围的缺口，不要罗列与本次候选判断无关的正式发布先决条件。
-
-按顺序呈现：
-
-1. 尚未落实的原文与 `unresolved` 项；
-2. 按场分组的镜头表；
-3. 可复制的关键帧提示词；
-4. 相对剧本原意发生的差异；
-5. 需要创作者接受的选择。
-
-本技能不在本轮自动启动终审；需要 delivery verdict 时，把当前有界范围作为单独请求交给
-`$short-drama-review`。
+1. 读取已接受的目标模型原生时长区间，再确认每个场景动作、对白、声音、画面文字和转折由哪些镜头承载。
+2. 确定观众何时知道什么、对齐谁、空间如何揭示、转折落在哪个可见动作。
+   剧本或 Brief 用“前半段 / 后半段 / 前三分之一 / 最后 N 秒”等相对时间限定首次出现、释放或禁止时，
+   先用已接受集长换成明确时间边界再分镜；例如 60 秒作品的“后半段首次出现”不得早于 30 秒。
+3. 每镜写清唯一职责、来源、时长、景别/机位、起点、唯一主要动作、终点和声音；用
+   `起点 → 唯一动作 → 终点` 直接说明人物、双手与持物怎样完成本镜状态转换。三条依据留到第 6 步。
+4. 锁定人物朝向、位置、视线、持物、出入口、屏幕方向和必要状态；上游已有会限制动作空间的持续关系时，把关系投影进本镜起点与终点。
+5. 冻结关键帧只投影镜头起点；删除终点才出现的文字、动作、姿态或道具状态。
+6. 关键帧成稿后，先从成稿正文读出这一格里需要保持身份、造型或地理的人物、地点和道具，
+   再用同一份清单一次填满三条依据：
+
+   - **视觉依据**：清单里每一项写成《视觉设定.md》的条目引用，这是必写字段；
+   - **图片提示词项**：清单里已有合适 `IMG-...` 条目的写上，没有的留「无」；
+   - **输入参考图**：按清单在用户提供的输入、`剧集/<EP>/制作成果/` 和文档已指向的其他可见媒体中查找匹配图片；
+     命中就写入 `REF-...`。一张都没命中时写「无（待补参考图：<本镜缺失的起始帧、人物、地点、道具>）」；
+     只命中一部分时，在已有 `REF-...` 后追加「；待补参考图：<仍缺的图片>」，缺口之间只用 `、` 分隔。
+     只有创作者明确表示不用图时，才写「无（创作者已明确选择文生视频）」。
+
+   三条依据读的是同一格画面，所以不能互相矛盾：关键帧里点名的人物或道具，一定出现在视觉依据里。
+7. 整集请求完成整集，末端一次报告覆盖、节奏和真实未决选择。
+
+## 镜头要求
+
+- 每镜有唯一职责、明确来源、可见起止状态和合理时长。
+- 已声明原生时长时，每个一镜一生成的镜头都落在其最短与最长秒数内。短于下限的叙事动作在合法
+  镜长内完成后保持终点；长于上限的动作按可见状态闭合点拆镜，拆出的每镜仍各有唯一职责与可信交界。
+- 「唯一动作」写从本镜起点到终点的那条可见状态链；涉及交接、换手、放置或取回时，把接触者、
+  接触方式和物件落点写在同一链里，不能让合法终点之间靠镜外瞬移衔接。
+- 切镜必须带来信息、权力、情绪、空间或节奏变化；同义重复镜头删掉。
+- 相对时间词约束的是事件首次可见或可听的时刻，不因前置动作已经完成就提前释放；分镜时间轴直接
+  写出该边界，不把“稍后”“交接后”等叙事顺序当成数值时间的替代。
+- 同一动作不跨镜重复发生；终点应能成为下一镜可信起点。
+- 关键信息的可读性优先于装饰性运镜，竖屏构图优先保证主体和反应可见。
+- 复杂群戏先锁空间锚点和屏幕方向，再决定景别变化。
+- 起终边界除了逐人姿态，还要写清本镜依赖的身体—物件—空间关系。关系在镜内不变时两端都保留；确需改变时，过程与终点必须有剧本依据。
+- 冻结关键帧只写该瞬间能看见的内容；文字、手指、反射和遮挡要可生成。
+- 《视觉设定.md》的连续性锁在生效镜头上原样写进冻结关键帧正文；锁面不因“参考图会交代”而省略。
+- 检查发现遗漏就直接修正文档，不生成覆盖表来证明自己检查过。镜头块里的「视觉依据」是本镜的依据字段，不是这里说的覆盖表。
+
+## 视觉依据与图片
+
+- `IMG-...` 是《图片提示词.md》里的**提示词条目 ID**，不代表图片已生成、已提供或可用。
+- 已有《图片提示词.md》且本镜需要其中条目时，写「图片提示词项」：ID 必须匹配该文档的可见二级标题，同时写中文名称和它控制的身份、造型、地理、构图或其他边界。ID 只用于查找，不让英文 slug 承担含义。
+- 没有《图片提示词.md》或没有合适条目时，写「图片提示词项：无」，再以中文指向《视觉设定.md》的人物、地点或道具项及控制范围。这是正常直接入口；不为继续分镜而编造 ID，也不补造另一个阶段。
+- 「视觉依据」是每镜必写字段：冻结关键帧成稿后按实际画面反查，需要保持身份、造型或地理的可见人物、地点和道具**必须**逐项写成
+  `《视觉设定.md》·<人物|造型|地点|道具>「<名称>」（控制：<范围>）`，多项用 `；` 连接，名称必须能在《视觉设定.md》里找到同名标题。
+  小比例或背景人物只要需要认出身份仍在范围内，画外人声和不可识别局部不算；本镜确实没有这类条目时写「视觉依据：无」。
+- 关键帧正文出现了某个条目的名字，但它本镜确实不在画面里（物主已离场、名字只出现在屏幕文字上、和某个词同形），
+  在「视觉依据」末尾追加 `；画外：<类别>「<名称>」`。这是如实记录，不是把不在场的人写成在场。
+- 某个条目的名字在正文里根本不可靠（`道具「手机」` 会撞上「手机店」，`人物「小雨」` 会撞上「下着小雨」），
+  在《视觉设定.md》该条目写 `画面代称：无`，机械核对就不再按名字找它；这一镜是否画到它仍由「视觉依据」如实回答。
+- 三条依据都描述同一格画面，不是本镜的资产花名册。「控制」只写这一格承担得起的范围：手背特写不写「本集造型」，
+  只出现屏幕和一根手指的镜头不写「体态」。上一镜的绑定不因为“角色还在这场戏里”就顺延到下一镜。
+- 关键帧正文点名的人物、地点或道具（《视觉设定.md》条目名称或它声明的「画面代称」），必须出现在本镜「视觉依据」里；
+  `creator_markdown_check.py` 会机械核对这一条。它只抓**被名字点到**的那一类：正文只描述不点名
+  （"a boy in a hooded jacket"）时机器不发声，画面里有谁仍然要靠这一步自己读出来，不能等报错。
+- 本镜需要保持一致、但《视觉设定.md》里还没有条目的可见物件（跨镜出现的道具尤其常见），不能因为
+  「写不进视觉依据」就当它不需要一致性。四镜都出现的一支笔和一件外套是同一类问题。做两件事：
+  正文里逐镜用完全相同的描述把它钉住，并在本轮末尾报告里点名它、建议 `$short-drama-assets` 补条目。
+  不自行新增《视觉设定.md》条目，也不把它塞进「视觉依据」冒充已有条目。
+- 「输入参考图」是独立的另一条轴：创作者已提供，或经确认生产且当前可读的实际图片，用不同于 `IMG-...` 的稳定 `REF-...` 槽位引用。每个槽位同时写显式顺序、仅用 `/` 分隔的项目相对路径、中文名称、「用途」、「控制」和「不得控制」范围；没有时必须区分「待补参考图」和「创作者已明确选择文生视频」，只准备了一部分时则保留已有 `REF-...` 并追加「；待补参考图：……」。不得把提示词条目、计划生成的图或对话中的描述写成已有图片。
+- 每个 `REF-...` 必须逐字遵循唯一格式：`REF-<slot>（顺序：<n>）· <项目相对路径>《<中文名称>》（用途：<用途>；控制：<范围>；不得控制：<范围>）`。注意「顺序：」后的全角冒号和路径前的中点 `·`；不得用 `/` 代替字段分隔符。多图只用中文分号 `；` 连接，部分缺图则在最后一个完整槽位后接 `；待补参考图：<缺口>`，缺口之间用 `、` 分隔。写完后按此格式回读一次再交付。
+- `用途` 只能取 `身份`、`造型状态`、`地理`、`构图`、`尺度`、`效果`、`起始帧`、`结束帧`、`风格` 之一；逐条能控制什么见 `$short-drama` 的《参考角色》。
+  本镜的起始画面图写 `用途：起始帧`，人物图写 `用途：身份` 或 `造型状态`，场景图写 `用途：地理`，道具状态图按它决定的那一件写。
+  一张图承担两件事就拆成两个槽位；一镜最多一张 `起始帧` 和一张 `结束帧`，写 `结束帧` 时必须同时有 `起始帧`。
+  下游视频提示词靠 `用途` 说清「本镜送哪一张分镜起始帧、哪些人物/道具/场景图」，所以缺 `用途` 的槽位不算准备好。
+- 本镜还没有起始画面图时，`用途：起始帧` 那一张由 `$short-drama-produce` 用本镜的冻结关键帧正文生成：
+  job 的 `source` 写 `剧集/<EP>/分镜.md`、`source_entry` 写本镜 `SHOT-...`，产出落在 `剧集/<EP>/制作成果/images/`。
+  拿到真实文件后再回来绑成 `REF-...`；生产前它仍然只是「待补参考图」里的一项。
+- 自动绑定不是把所有图都塞进一镜。只选本镜可见、且身份、造型、地理、关键道具状态或起始构图确实需要稳定的图；逐张写清它的用途、能控制什么、不得控制什么。
+- 两条轴可以独立组合：有合法的图片提示词项时，输入参考图仍可为「待补」或创作者明确选择的文生视频；创作者给了真实参考图时，图片提示词项也可为「无」。
+
+## 按需知识
+
+默认只读本 SKILL、当前剧本和必要视觉事实。遇到对应问题时只打开一份：
+
+- 阶段边界与规则分级：[阶段契约](references/stage-contract.md)
+- 镜头职责、切镜理由和边界：[镜头手艺](references/shot-craft.md)
+- 实际制作所需的镜头语法：[生产镜头语法](references/production-shot-grammar.md)
+- 关键场次比较导演方案：[场次视觉计划](references/scene-visual-plan.md)
+- 检查原文是否都有画面承载：[Coverage Audition](references/coverage-audition.md)
+- 多人、群体和复杂空间调度：[调度手册](references/blocking-playbooks.md)
+- 冻结瞬间、注意中心和可读性：[关键帧手艺](references/keyframe-craft.md)
+- 漫剧/二维漫画形态的共享画风词汇：[漫剧关键帧词表](references/comic-keyframe-lexicon.md)
+- 剧本事实到关键帧的完整示例：[剧本到关键帧](references/screenplay-to-keyframe-example.md)
+- 拆镜、并镜和稳定镜头 ID：[镜头修订身份](references/shot-revision-identity.md)
+- 完成前的连续性检查：[审查与示例](references/review-and-fixtures.md)
 
 ## 修订
 
-若运动提示词环节要求修改镜头开始或结束边界，负责人仍是本技能。对照剧本原意审查
-提议，修改当前有界范围的镜头与关键帧，并展示哪些旧产物已经关闭或需要刷新。运动提示词与
-终审属于后续的独立工作单元，本轮只报告它们的影响范围。
-运动提示词文件不得悄悄变成第二份边界事实。
-镜头重排、插入、拆分或合并时读取
-[shot-revision-identity.md](references/shot-revision-identity.md)，保留稳定身份、retire 被替代 ID，
-并重新对账 coverage 与全部下游引用；只在确有 predecessor/retirement 时新增
-`revision_lineage`，并使用 [按需 lineage 片段](assets/revision-lineage.fragment.json)；普通新镜不保存
-空 lineage。不用数组位置或文本相似度决定 ID。
+保留未受影响的镜头 ID。拆镜、并镜或改变镜头职责时，说明哪些下游视频提示词需要刷新，但不自动
+重写用户没点名的文件。
 
-## 边界
+## 完成
 
-- 不生成图片或视频。
-- 镜头绑定资产，不把完整外观描述复制到每一镜。
-- 外部制作单位不等于创作镜头本身的编号。
-- 镜头数量、每次切镜秒数、焦段分布都不是通用定律。
-- 新增或删除故事事实，必须先由编剧环节修订。
-- 创作者要求把已接受关键帧实际生成图片时，连同绑定和参考文件交给
-  `$short-drama-produce`；由生产技能展示任务预览并取得明确确认，本技能不调用媒体服务。
+点名范围的原文都有镜头落实，每镜职责不重复、空间与状态连续、起止边界可制作、关键帧可冻结，
+且每镜关键帧里的可见人物、地点、道具都在本镜「视觉依据」里，即完成。画面需要、但《视觉设定.md》
+还没有条目的可见物件，在末尾报告里逐项点名。本次请求同时修改
+《图片提示词.md》与《分镜.md》时，当轮刷新受影响镜头的引用；不另建覆盖表。
+视频提示词、生产和审查只有用户点名时开始。
+五份创作文档齐备后，可转 `$short-drama` 对跨文档结构做一次机械核对；内容质量仍由创作者审查。
 
-## 所有产物
+## 安装维护
 
-- `剧集/<EP>/storyboard/coverage.json`
-- `剧集/<EP>/storyboard/coverage-auditions/<SC>.jsonl`（仅关键场次需要比较方案时；每场独立接受，项目工作历史，
-  默认不进执行交付包；accepted 后打包时显式传 `--omit`，不会按文件名静默排除）
-- `剧集/<EP>/storyboard/scene-visual-plans/<SC>.jsonl`（仅关键场次需要场次计划时；每场独立接受）
-- `剧集/<EP>/storyboard/shots.jsonl`
-- `剧集/<EP>/storyboard/keyframes.jsonl`
-- `剧集/<EP>/storyboard/keyframe-prompts.md`（仅派生文本）
+只有安装、升级或排障时运行 `python3 scripts/selftest.py`。

package/lib/drama/skills/short-drama-storyboard/assets/shot-template.jsonl

@@ -1,2 +1,2 @@
 {"record_type":"sources","schema_version":"1.0.0","sources":{"<characters-or-props>":{"owner":"short-drama-assets","artifact":"设定集/<characters-or-props>.jsonl"},"<looks-or-prop-states>":{"owner":"short-drama-assets","artifact":"设定集/<looks-or-prop-states>.jsonl"},"location-views":{"owner":"short-drama-assets","artifact":"设定集/location-views.jsonl"},"locations":{"owner":"short-drama-assets","artifact":"设定集/locations.jsonl"},"props":{"owner":"short-drama-assets","artifact":"设定集/props.jsonl"},"screenplay-index":{"owner":"short-drama-write","artifact":"剧集/<EP>/screenplay-index.jsonl"},"short-drama":{"owner":"short-drama","artifact":"short-drama.json"}}}
-{"shot_id":"SHOT-EXAMPLE","status":"candidate","source_refs":[{"src":"screenplay-index","record_id":"BLK-EXAMPLE"}],"coverage_role":"primary | intentional_repeat","purpose":"<what the audience must notice and why this is a new shot>","information_change":"<before -> after for audience/character>","audience_visibility":[{"source_ref":{"src":"screenplay-index","record_id":"BLK-<id>"},"fact":"<本镜必须展示或暂缓的一个事实>","permission":"show_now | withhold_now","carrier":"<可见/可听载体；暂未出现则写 none>","reveal_trigger":"<允许释放的动作/台词/cut；不在本镜则写 future>","protection_method":"<framing/crop/occlusion/offscreen/focus/timing/none，可组合说明>","rationale":"<与 source 信息权限和本镜职责的关系>"}],"location_binding":{"identity_ref":{"src":"locations","record_id":"LOC-<id>"},"variant_ref":{"src":"location-views","record_id":"VIEW-<id>"}},"asset_bindings":[{"identity_ref":{"src":"<characters-or-props>","record_id":"CHAR/PROP-<id>"},"variant_ref":{"src":"<looks-or-prop-states>","record_id":"LOOK/PSTATE-<id>"},"role":"<subject/evidence/background>"}],"duration_seconds":null,"start_boundary":{"positions":["<每条都写成不读上一镜也能理解的绝对事实：谁在哪个锚点的哪一侧；『同上』『位置不变』『同前』要往回翻才解释得通，不算已写>"],"facing":[],"gaze":[],"hands":[],"held_props":[],"visible_state":[]},"end_boundary":{"positions":["<同样是绝对事实：本镜结束时人在哪、朝哪，不写成与开始状态的差异>"],"facing":[],"gaze":[],"hands":[],"held_props":[],"visible_state":[]},"framing":{"size":"<extreme_wide 远景/wide 全景/medium 中景/medium_close 中近景/close 近景/close_up 特写/extreme_close_up 大特写/detail 细节镜头 or creator vocabulary>","angle":"<horizontal: 正面/斜侧/正侧/后斜侧/背面 or creator vocabulary; say which side of the axis>","camera_height":"<地平/低(仰)/平视/高(俯)/顶视; 平视 is a choice, not an unset field>","aspect_notes":"<composition constraint>"},"delivery_surface_ref":{"src":"short-drama","field":"/creator_authority/delivery_surface"},"blocking":{"axis":"<working side/bridge/deliberate break>","screen_direction":"<direction>","paths":[],"fixed_anchors":[]},"camera_plan":{"behavior":"locked | pan | tilt | push | pull | track | follow | orbit | crane | handheld | transition","motivation":"<attention/pressure/alignment/reveal/rhythm>","intervals":[]},"dialogue_audio_refs":[],"text_treatment_refs":[{"src":"props","record_id":"PROP-<id>","field":"/text_policy"}],"transition_intent":null,"creator_overrides":[]}
+{"shot_id":"SHOT-EXAMPLE","status":"candidate","source_refs":[{"src":"screenplay-index","record_id":"BLK-EXAMPLE"}],"coverage_role":"primary | intentional_repeat","purpose":"<what the audience must notice and why this is a new shot>","information_change":"<before -> after for audience/character>","audience_visibility":[{"source_ref":{"src":"screenplay-index","record_id":"BLK-<id>"},"fact":"<本镜必须展示或暂缓的一个事实>","permission":"show_now | withhold_now","carrier":"<可见/可听载体；暂未出现则写 none>","reveal_trigger":"<允许释放的动作/台词/cut；不在本镜则写 future>","protection_method":"<framing/crop/occlusion/offscreen/focus/timing/none，可组合说明>","rationale":"<与 source 信息权限和本镜职责的关系>"}],"location_binding":{"identity_ref":{"src":"locations","record_id":"LOC-<id>"},"variant_ref":{"src":"location-views","record_id":"VIEW-<id>"}},"asset_bindings":[{"identity_ref":{"src":"<characters-or-props>","record_id":"CHAR/PROP-<id>"},"variant_ref":{"src":"<looks-or-prop-states>","record_id":"LOOK/PSTATE-<id>"},"role":"<subject/evidence/background>"}],"duration_seconds":null,"start_boundary":{"positions":["<每条都写成不读上一镜也能理解的绝对事实：谁在哪个锚点的哪一侧；『同上』『位置不变』『同前』要往回翻才解释得通，不算已写>"],"facing":[],"gaze":[],"hands":[],"held_props":[],"visible_state":[]},"primary_transition":{"trigger":"<什么可见或可听事件让动作开始>","action":"<从起点到终点的唯一主要动作；交接时写清接触者、接触方式与落点>","result":"<逐项落到 end_boundary，不在镜外补转换>"},"end_boundary":{"positions":["<同样是绝对事实：本镜结束时人在哪、朝哪，不写成与开始状态的差异>"],"facing":[],"gaze":[],"hands":[],"held_props":[],"visible_state":[]},"framing":{"size":"<extreme_wide 远景/wide 全景/medium 中景/medium_close 中近景/close 近景/close_up 特写/extreme_close_up 大特写/detail 细节镜头 or creator vocabulary>","angle":"<horizontal: 正面/斜侧/正侧/后斜侧/背面 or creator vocabulary; say which side of the axis>","camera_height":"<地平/低(仰)/平视/高(俯)/顶视; 平视 is a choice, not an unset field>","aspect_notes":"<composition constraint>"},"delivery_surface_ref":{"src":"short-drama","field":"/creator_authority/delivery_surface"},"blocking":{"axis":"<working side/bridge/deliberate break>","screen_direction":"<direction>","paths":[],"fixed_anchors":[]},"camera_plan":{"behavior":"locked | pan | tilt | push | pull | track | follow | orbit | crane | handheld | transition","motivation":"<attention/pressure/alignment/reveal/rhythm>","intervals":[]},"dialogue_audio_refs":[],"text_treatment_refs":[{"src":"props","record_id":"PROP-<id>","field":"/text_policy"}],"transition_intent":null,"creator_overrides":[]}

package/lib/drama/skills/short-drama-storyboard/references/blocking-playbooks.md

@@ -43,42 +43,17 @@
   **不因为猜测的区域改变构图**——猜出来的避让同样是一个通用安全框，只是没写在纸上。
   需要时向创作者提一次问：这次交付的播放面会在画幅哪些位置叠加什么、是否常驻。
 
-声明由**创作者拥有**，落在 `short-drama.json` 的 `/creator_authority/delivery_surface`，
-与视觉方向、制作形态同级。它要能回答三件事——**占用哪里、是否常驻、依据来自哪**：
-
-```json
-{
-  "status": "unset | declared",
-  "aspect": "<已接受画幅>",
-  "overlay_regions": [
-    {
-      "id": "<稳定 ID>",
-      "where": "<用画幅比例或可命名边带描述的占用范围>",
-      "permanence": "persistent | intermittent | conditional",
-      "carries": "<字幕 | 控件 | 角标 | 其他>"
-    }
-  ],
-  "source_ref": {
-    "src": "creator-decision",
-    "record_id": "<接受该声明的决定记录>"
-  }
-}
-```
-
-`creator-decision` 是 `short-drama.json` 的 `sources` 为那份创作者决定声明的快照键：
-
-```json
-{"creator-decision": {"owner": "creator", "artifact": "创作者决策/<artifact-id>.json"}}
-```
+声明由**创作者拥有**，写在 `视觉设定.md` 的“交付面”章节，与项目视觉方向和制作形态并列。
+它回答三件事：**占用哪里、是否常驻、依据来自哪**。每个区域使用稳定 ID，并写：
 
-镜头与关键帧记录用 `delivery_surface_ref` 绑定该声明的**精确快照与字段**（模板已有该字段，
-指向 `short-drama.json#/creator_authority/delivery_surface`）。创作者改版后引用变
-`stale`，受影响的镜头与关键帧按恢复流程重新核对，不沿用上一版的避让结论。
+- 当前画幅；
+- 用画幅比例或可命名边带描述的占用范围；
+- 常驻、间歇或条件出现；
+- 承载字幕、控件、角标还是其他内容；
+- 创作者提供的平台模板、截图或文字说明。
 
-`status` 为 `unset` 时本规则不生效：镜头照常按画面可读性构图，把它记为待创作者决定。
-声明自身不引用自己所在的文件。
-- **已声明时绑定版本**：镜头与关键帧引用该声明的具体版本；交付方案改版时，受影响的镜头
-  按 `stale` 处理并重新核对，而不是沿用上一版的避让结论。
+没有声明时本规则不生效：镜头照常按画面本身的可读性构图，把问题留为待创作者决定。已经声明时，
+受影响镜头在 `分镜.md` 指名交付面区域 ID；交付方案改版后重新核对，不沿用上一版避让结论。
 已声明遮挡区后，按下面的优先级判断哪些内容必须挪开：
 
 - **可读文字最敏感**：证据类道具上必须被读出的字，一旦落在字幕条位置，观众永远读不到。