@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/build-drama-storyboard/prompts/agent_cinematographer.zh.txt

@@ -0,0 +1,150 @@
+# Codex 执行合同：agent_cinematographer
+
+本文件由所属 Skill 读取，用于约束 Codex 的输入、判断与输出；不是发送给外部文本模型的 system prompt。花括号字段是从当前项目已选资产组装的具名输入槽。
+
+执行职责：经验丰富的电影摄影指导(Director of Photography)。你的任务是为一组分镜中的**每个镜头**分别设计摄影规则。
+
+【核心职责】
+
+分析整组分镜后，为每个镜头单独设计以下视觉要素：
+1. 灯光设置 - 光源方向和质感
+2. 构图设置 - 景别、主体布局与视觉重心
+3. 角色位置 - 画面中的具体位置
+4. 景深与焦点设置 - 根据叙事焦点、人物关系和空间信息确定
+5. 色调、氛围与技术约束 - 整体色彩氛围、连续性和拍摄注意事项
+6. 可见光学结果 - 先描述视场角、相机距离、透视压缩与焦平面，再在 technical_notes 补充焦段、T 值等设备参数
+7. 构图契约兑现 - 把 visual_plan.composition 的 primary/secondary code 翻译成 composition_contract 中的可见摄影结果（阅读顺序、主体位置、纵深层次、视线留白、光色几何、动作向量、镜尾状态），不得只复读模式名称，也不得改选 code 或新增构图
+
+每镜只设一个首要可读信息，并用景别、位置、遮挡、光线、色彩或焦点建立主次；背景分离优先依靠空间层次与明暗/色彩对比，不默认依靠极浅景深。主光、实景光和轮廓来源必须能在场景、时间或已确认视觉合同中解释；不得为“电影感”凭空添加无来源轮廓光、霓虹或彩色烟雾。
+
+【重要】每个镜头的规则必须是独立的！
+- 将输入中的 narrative_purpose、shot_group、motion_plan、scene_strategy、rhythm_plan、edit_plan、dialogue_plan、visual_plan 视为已确认导演合同：构图、焦点、景别递进和运镜必须服务于场级视点、节奏强度、视觉重点、组内角色与起止状态；遵守 axis、screen_direction 和转场动机，不得改写合同字段或用无动机运镜替代主体动作。
+- visual_plan.composition 是已确认构图合同：composition_contract 的 primary、secondary 必须原样继承输入的 code（secondary 无则为 null），不得改选、增删或重命名；提供合同时摄影不负责也不允许挑选 code，只能把给定 code 翻译成可见几何兑现。场级 composition_motifs 若在输入中出现，本镜光色、方向与镜尾处理必须与其变化/回收意图一致。
+- 不同场景的镜头有不同的光照和色调
+- 景别不自动决定景深；景深和焦点必须服务于当前需要读清的人物、关系、动作或空间
+- 不同镜头中的角色位置可能不同
+
+【分析步骤】
+
+1. 通读所有镜头，了解整体场景流程
+2. 为每个镜头单独分析：
+   - 时间与光照（从场景和时间推断）
+   - 角色位置（根据镜头描述确定）
+   - 景深与焦点（当前必须清晰的信息，以及前后景为何分离或共同清晰）
+   - 色调（根据场景氛围确定）
+
+【焦点与景深决策】
+- 建立空间或多人调度需要读清关系时，允许深景深或让关键人物处于同一焦平面。
+- 单人情绪、插入物或局部动作需要排除干扰时，才使用浅景深；特写不等于必须把背景完全化掉。
+- 对话镜按 dialogue_plan 决定：speaker/clean-single 可聚焦说话者；listener 聚焦听者；relation/two-shot 应保留两人关系可读；over-shoulder 可让前景肩部柔化，但不得遮住关键反应。
+- 只有信息权力确实从一人转移到另一人时才设计拉焦，并写清起始焦点、转移触发和终止焦点；否则从首帧到末帧锁定焦平面，禁止自动对焦漂移。
+- 口型风险通过明确唯一说话者、嘴部状态和对白覆盖解决，不得把虚化所有听者当作通用替代方案。
+- 焦段、T 值只在能解释可见结果时填写；禁止用设备数字冒充叙事选择。广角畸变、鱼眼或透视夸张必须有明确叙事动机，否则保持自然直线和人物比例。
+
+【构图受控词表与 composition_contract】
+
+{cinematography_vocabulary}
+
+完整模式卡片（画面结构、证据要求、可组合模式、禁忌/AI 风险、竖屏提示）见 references/director-composition.md，风险码见该文件 0.4。
+
+composition_contract 必须把构图 code 翻译成可见摄影结果，逐镜包含以下 11 个字段，禁止只复读模式名称或用抽象形容词兜底：
+- primary、secondary：原样继承 visual_plan.composition 的受控 code；secondary 无第二信息层时为 null，禁止自行改选
+- read_order：观众第一眼、第二眼依次读到什么（谁的决定/什么动作或道具/什么关系），第一项必须等于 narrative_purpose 的首要可读信息
+- subject_placement：每个可见角色的水平位置（画面左/中/右）、纵深层（前/中/后景）与机位高度关系（仰/平/俯），与 characters.screen_position 一致
+- depth_layers：前景、中景、远景分别放置什么、虚实与明度如何分配，纵深如何在竖屏中成立
+- eyeline_room：每道视线的方向、留白方向与大致占比，并写明与相邻镜轴线、屏幕方向的接续
+- light_and_color_geometry：主光方向与剧内来源、色温与色块分区、明暗如何把视线导向首要信息
+- action_vector：动作、入画/出画与朝向的屏幕方向，以及蓄力—接触点—结果的走向；无动作镜写 null，禁止自造动势
+- tail_state：镜尾定格时人物位置、朝向、剩余张力（镜头停在哪里），并与 motion_plan.end_state 一致
+- evidence：继承上游构图证据并落实到本摄影方案：逐条确认该 code 的证据等级（composition-only/set_dressing/weather_atmosphere/action_blocking），复合证据以 + 连接且逐组件确认，指出实际用到的 source_text、场景/道具资产或动作事实；任何等级不满足都必须在 technical_notes 标为阻塞，而不是换 code
+- ai_risks：secondary 非 null 时必须并集覆盖 primary 与 secondary 两个模式登记的风险，再加上 0.4 风险码表中本镜真实需要防控的风险码，并为每个风险在各几何字段中给出可见防控手段（如遮挡不超过三分之一且双眼完整、留白区保持纯净不填物、接触点清晰、动势边缘留 10%、相邻镜方向一致、locked-off 防止自行运镜）
+- 缺省输入（旧历史分镜）：若输入面板没有 visual_plan.composition，不要求上游回填补写。按 references/director-composition.md 的逐镜选择流程，依据本镜 source_text、场景/道具资产与动作事实自行选出 primary 与 secondary（确无第二信息层时 secondary 为 null），并在 evidence 逐条写出来源与证据等级；若现有证据不支持任何受控 code，不得编造 code 或无证据硬凑：primary 写 null，在 technical_notes 标注 composition blocked 与所缺证据，其余几何字段仍按本镜首要可读信息正常填写，不空转或拒答
+
+【输出格式】
+
+返回一个JSON数组，每个元素对应一个镜头的摄影规则。
+
+必须确保输出的数组长度与输入的镜头数量一致！
+
+示例输出（字段结构示意，不代表固定镜头方案）：
+
+[
+  {
+    "panel_number": 1,
+    "scene_summary": "室内对白，白天",
+    "composition": "双人构图，人物关系与关键反应同时可读",
+    "field_of_view": "容纳两人与必要环境关系的视场角",
+    "camera_distance": "保持人物比例自然并能读清双方反应",
+    "optical_result": "两人处于可读焦平面，背景通过层次和明暗适度分离",
+    "lighting": {
+      "direction": "主光延续场景中可见窗户方向",
+      "quality": "与时间和场景一致的柔和自然光"
+    },
+    "characters": [
+      {
+        "name": "角色甲",
+        "screen_position": "画面左侧",
+        "posture": "站立",
+        "facing": "面向右侧"
+      },
+      {
+        "name": "角色乙",
+        "screen_position": "画面右侧",
+        "posture": "站立",
+        "facing": "面向左侧"
+      }
+    ],
+    "depth_of_field": "足以同时读清双方关系的景深",
+    "color_tone": "延续场景视觉合同的主色与对比关系",
+    "atmosphere": "克制的关系张力",
+    "composition_contract": {
+      "primary": "composition.character.two_shot_standoff",
+      "secondary": null,
+      "read_order": "先读角色甲的逼问姿态，再读角色乙不回避的对视",
+      "subject_placement": "角色甲位于画面左侧中景、角色乙位于画面右侧中景，平视机位，两人同处中焦平面",
+      "depth_layers": "前景空出避免遮挡；中景为两人对峙主体；背景为房间深处暗部并保留可读出口",
+      "eyeline_room": "角色甲视线向右、角色乙视线向左，视线相交于画面中线；两人外侧各留约一成画面余量，与前镜轴线一致",
+      "light_and_color_geometry": "主光来自画面右前方并保持同一色温，两人面部受光均等；背景压暗把视线锁在中景两人身上",
+      "action_vector": "无进出画；角色甲向角色乙逼近半步，屏幕方向朝画面右方，止于两人间距之间，无肢体接触",
+      "tail_state": "镜尾两人维持对视与间距，角色甲半步落定，保留摊牌前的张力",
+      "evidence": "primary 与 secondary=null 均为 composition-only：source_text 的对峙台词支持两人同场意志对撞；本方案不添加陈设、天气或群体动作",
+      "ai_risks": ["eyeline_or_axis_break"]
+    },
+    "technical_notes": "保持人物轴线、视线、焦平面和主光方向连续；防控视线不交或与相邻镜越轴"
+  }
+]
+
+【输入数据】
+
+分镜数据（共 {panel_count} 个镜头）：
+{panels_json}
+
+场景描述：
+{locations_description}
+
+角色信息：
+{characters_info}
+
+道具描述：
+{props_description}
+
+【项目视觉圣经 - 独立于画风，必须遵守】
+{visual_bible}
+
+【严格要求】
+
+1. 只返回JSON数组，不要有markdown代码块标记
+2. 数组长度必须等于输入的镜头数量（{panel_count}个）
+3. 每个元素必须完整包含 panel_number、scene_summary、composition、field_of_view、camera_distance、optical_result、lighting.direction、lighting.quality、characters、depth_of_field、color_tone、atmosphere、composition_contract、technical_notes 字段；composition_contract 必须完整包含 primary、secondary、read_order、subject_placement、depth_layers、eyeline_room、light_and_color_geometry、action_vector、tail_state、evidence、ai_risks 十一个子字段，primary/secondary 必须原样继承输入 visual_plan.composition 的 code，禁止改选或只复读名称；输入缺少 visual_plan.composition 的旧历史分镜按合同节「缺省输入」处理：依证据自行选码并在 evidence 写明来源，或 primary=null 并在 technical_notes 标注 composition blocked，不要求上游回填
+4. 使用相对方向（画面左侧/右侧），禁止使用东南西北
+5. 角色位置必须与镜头描述一致！
+6. 如果角色对象中包含 slot，screen_position / posture / facing 应优先参考该位置语义，但 slot 不是绝对硬限制
+7. 当镜头属于移动过程、入口/出口、过渡区域、路径空间、临时位置、空镜、想象空间、梦境、回忆或抽象空间时，可以基于镜头描述自由决定构图与位置，不必强行贴合 slot
+8. slot 若被引用，必须视为一条完整的位置描述，禁止缩写、改写、总结或替换成短词
+9. 景深不得由 shot_type 自动推导，必须说明当前焦点选择如何服务 narrative_purpose 和 dialogue_plan
+10. 对话镜不得默认虚化听者；根据 speaker、listener、relation 或 action 焦点选择单人清晰、多人共同清晰或有动机的焦点转移
+11. 每镜只允许一个首要视觉信息；灯光必须有可解释来源，空间分离优先使用前中后景、明暗或色彩关系
+12. 如果镜头涉及不同场景，灯光和色调要相应调整
+13. 输出要简洁，每个镜头的规则独立完整
+14. ⚠️ JSON安全：所有引号（""''等）在 JSON 字符串值中必须统一替换为「」，严禁出现未转义的英文双引号 "
+15. 这是补丁阶段：必须逐项原样回传输入的 panel_number，禁止新增、删除、重复或重排镜头

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/build-drama-storyboard/prompts/agent_storyboard_detail.en.txt

@@ -0,0 +1,114 @@
+# Codex execution contract: agent_storyboard_detail
+
+The owning Skill reads this file to constrain Codex inputs, decisions, and output. It is not a system prompt sent to an external text model. Braced fields are named input slots assembled from selected local project assets.
+
+Execution role: senior storyboard detail refiner.
+Refine panel-level visual details and video prompts.
+`narrative_purpose`, `shot_group`, `motion_plan`, `scene_strategy`, `rhythm_plan`, `edit_plan`, `dialogue_plan`, and `visual_plan` are the approved director contract; `visual_plan.composition` (and the upstream cinematographer `composition_contract`, when present in the input) is the approved composition contract. Final description, camera_move, and video_prompt must fulfill the scene viewpoint and audiovisual motifs, intensity, action-reaction pattern, dialogue coverage, edit/sound bridge, visual emphasis, group role, and start/end states. Preserve every contract field unchanged, including every composition and composition_contract subfield; never alter the codes. `duration` is generated source length; `edit_plan.intended_duration` is the planned final edit hold.
+
+{cinematography_vocabulary}
+
+{storyboard_scene_types}
+
+{storyboard_scene_camera_styles}
+
+{character_video_subjects}
+
+For performance, preserve the acting plan already confirmed in the previous step and describe only visible, executable actions that fit the story.
+
+[MOTIVATED CHANGE]
+Each shot must contain either a narrative change or an intentional pause. Static framing, held gaze, breath holds, dialogue pauses, and impact pauses are valid performance choices; never add gestures or camera moves merely to keep things moving. By default use at most one primary body action, one micro-action, and one eyeline change unless the story explicitly requires a complex action. For impact, describe anticipation, force, contact point, impact pause, weight shift, and recovery or fall. At contact, localized directional motion blur and a brief contact-synchronized micro-shake are allowed, followed by immediate stability; forbid sustained global defocus and unmotivated shake.
+
+camera_move must contain exactly one canonical movement name. Do not join multiple movements with commas, slashes, or conjunctions.
+Close-ups default to locked framing and move only for an approved action follow, information reveal, or focus transfer. Camera behavior follows subject action, information power, or scene viewpoint; it may change speed or stability with an evidenced beat, but never performs independently of the character.
+Give each shot one primary readable fact and build hierarchy through scale, placement, occlusion, depth layers, light, color, or focus. Never add arbitrary neon, smoke, rim light, or generic symbols merely to look cinematic.
+Do not add actions, props, or environmental facts not approved for the current shot. Only turn visible content from the storyboard plan and approved acting plan into executable video wording.
+Props mentioned in props, description, video_prompt, and actingNotes must agree shot by shot. If props omits an asset, no other field may mention that asset or an action involving it.
+For prop contact, state the before/contact/after states and any adjacent object that stays attached or still; make the result clearly true and briefly stable before the exit frame. In group shots preserve exact headcount, left-to-right order, facing, and limb ownership; send interaction that cannot stay attributable back for shot splitting.
+
+[COMPOSITION CONTRACT REALIZATION]
+- Echo every subfield of visual_plan.composition and composition_contract (when present) unchanged: do not reselect codes, delete fields, or reorder; this stage only realizes the geometry.
+- description must visibly realize read_order (what is read first), subject_placement (each visible character's screen position and depth layer), eyeline_room (gaze direction, negative-space direction and share), depth_layers (what sits in foreground/midground/background and how sharpness falls), light_and_color_geometry (key direction and its in-story source, occluders and occlusion ratio), action_vector (screen direction of action and entrances/exits), and tail_state (end-frame position, facing, residual tension).
+- video_prompt must turn that geometry into executable screen instructions and end on a stable tail frame consistent with tail_state, followed by `Transition out [transition type]`. shot_type and camera_move obey the composition contract; static-pattern contracts explicitly say locked-off; forbid autonomous slow pushes, orbits, or floating camera moves.
+- Visible-element ceiling: composition evidence, source_text, props, and scene/prop assets are the only sources for picture elements. Never add rain, snow, fog, neon, mirrors, smoke, doors/windows/columns, weapons, or extra bystanders without evidence. Every risk in ai_risks needs a visible countermeasure in description or video_prompt (clean empty zones, occlusion never covering the eyes, clear contact point, 10% margin at motion edges, screen direction continuous with neighbors).
+- Legacy panels that lack composition/composition_contract subfields are read and refined as-is: no backfilling and no failure verdict on those grounds.
+
+[VOICE TYPE AND LIP MOVEMENT]
+- On-screen dialogue: the visible speaker may use natural speaking lip movement, breath, and expression matching the verbatim line.
+- Off-screen dialogue: the speaker is outside the frame; never make another visible character speak the line or use speaking lip movement.
+- A voice-over or inner monologue is off-screen audio: the visible character has no speaking lip movement, keeping a natural mouth position consistent with breathing and the current expression.
+- Use multiple speaking faces in one shot only when the Provider supports it, speech windows do not overlap, and every visible mouth state can be scheduled; otherwise split coverage, and use post-dub only when the Provider lacks native audio.
+
+[PREPRODUCTION NATURAL-MOTION CONTRACT]
+- On the video_prompt timeline, give every visible person one primary action, attention target, reaction trigger, and uninvolved state. Unless synchronization is story-required, offset group onset, amplitude, gaze, and reaction latency.
+- When readable at the shot scale, keep still people alive with irregular unsynchronized blinks, brief refocusing, breathing, or a small weight adjustment without mechanical loops or distracting business.
+- Ground body action in planted support, center-of-mass transfer, hip/shoulder lead, joint path, acceleration, deceleration, follow-through, and recovery. After prop contact, preserve the correct grip and load.
+- Hair, hems, loose sleeves, accessories, and props respond only to established wind, character acceleration, gravity, or contact with smaller delayed motion, damping, and settling. The environment responds locally only to evidenced forces. Split the shot when instruction load or multi-person contact ownership becomes ambiguous.
+
+Panel input JSON:
+{panels_json}
+
+Character info:
+{characters_age_gender}
+
+Location info:
+{locations_description}
+
+Prop info:
+{props_description}
+
+[PROJECT VISUAL BIBLE — independent from art style, must be followed]
+{visual_bible}
+
+Task:
+For each panel, output a complete panel object with improved cinematic detail.
+If any character already has `slot`, prefer preserving it exactly and use it as a preferred placement anchor.
+Treat `slot` as one full placement phrase from the location context, not as a short token.
+
+Required fields per panel:
+- panel_number
+- description
+- characters
+- location
+- scene_type (choose from the canonical list above)
+- source_text
+- shot_type
+- camera_move
+- video_prompt
+- visible_event_keys (stable keys for visible events that may justify action sound; empty when none)
+- duration (optional)
+
+Output schema example (field names must be preserved):
+[
+  {
+    "panel_number": 1,
+    "description": "panel description",
+    "characters": [{ "name": "Character", "appearance": "appearance", "slot": "the position beneath the throne steps at the center of the hall" }],
+    "location": "location name",
+    "scene_type": "daily",
+    "source_text": "source text excerpt",
+    "shot_type": "medium shot",
+    "camera_move": "static",
+    "video_prompt": "motion-ready prompt",
+    "duration": 3
+  }
+]
+
+Rules:
+0. Treat `identity_binding` as version and `appearance_id` validation metadata only; never expose it as visible text. Copy the visible `identity_constraints` — `grooming_and_makeup`, `costume_signature`, and every `memory_anchors` item — into each visible character description without inventing, dropping, or rewriting anchors. Keep one appearance consistent across shots unless an evidence-backed continuity change explicitly authorizes it.
+0a. Carry the same character reference's `performance_constraints` unchanged into the storyboard performance contract. Convert `eyeline_behavior`, `blink_rhythm`, `stress_response`, and a trigger-bound `habitual_actions` item into a visible beat only when this shot contains the recorded trigger; `forbidden_performance` always applies. Never invent psychology from a personality label alone.
+0b. Express psychology through stimulus or information, gaze target and shift, social mask, brief leak, decision/action, and exit residue. For a close shot specify one or two visible facial regions with a low-amplitude onset—apex—release; at wider scales use head, breath, posture, pause, distance, and blocking. Never output FACS/AU codes or non-executable labels such as “complex,” “shocked,” or “sinister.”
+1. Keep panel order unchanged.
+2. Keep source_text semantically aligned with input; do not rewrite story meaning.
+3. video_prompt should be motion-ready and concrete. End it with `Transition out [transition type]` and the current shot's motivated exit frame. Use a special transition only when its visible trigger already appears in source_text or the current description; otherwise, you must use a hard cut when the current shot has no visible evidence for a special transition, ending on a stable frame of an action already shown. Never foreshadow, add, or generate the next shot's story action.
+4. Use age+gender wording in video_prompt when naming actors in camera directions. When gender is "unknown", use the age band plus "person" (for example, "young person"). Do not use gendered pronouns; repeat "the person" when a reference is needed. Never infer gender from a name, occupation, appearance, or action.
+5. Preserve every input `slot` when the character is stably positioned, and reflect it as a preferred anchor in refined description/video_prompt.
+6. Do not remove characters that already exist in the input panel's `characters` array. If a close-up, insert, or reverse shot makes some characters invisible, explain the tight framing in `description` instead of deleting the character field entry.
+7. Every actually visible character must appear in `characters`, and appearance must retain a parseable `char-*@vNNN`. Do not leave identifiable seated, crowd, reflected, or background characters only in description. If source_text or description clearly introduces another visible asset-library character, add that character to `characters`.
+8. `slot` is not an absolute boundary. If the shot is clearly about movement, entry/exit, path traversal, transition space, temporary space, empty space, imagination, dream, memory, or abstract/non-literal space, you may remove `slot` or keep it without forcing a rigid static match.
+9. When no `slot` is used, decide placement freely from source text, action flow, spatial logic, and cinematic staging.
+10. Do not shorten, rewrite, summarize, or replace a provided `slot` phrase with a short token.
+11. `visible_event_keys` contains only stable keys for events visibly executed in this shot and eligible to justify action sound; use an empty array when none. Footsteps, cloth, impacts, doors, or energy sound respectively require a visible walking, cloth-motion, contact, door-motion, or energy event. Never invent an event for atmosphere.
+12. Return JSON array only.
+13. ⚠️ JSON SAFETY: All quotation marks in text (""''「」 etc.) MUST be converted to corner brackets「」in JSON string values. NEVER use raw ASCII double quotes " inside string values.
+14. This is a patch phase: echo every input panel_number in the same order; never add, remove, duplicate, or reorder panels.

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/build-drama-storyboard/prompts/agent_storyboard_detail.zh.txt

@@ -0,0 +1,89 @@
+# Codex 执行合同：agent_storyboard_detail
+
+本文件由所属 Skill 读取，用于约束 Codex 的输入、判断与输出；不是发送给外部文本模型的 system prompt。花括号字段是从当前项目已选资产组装的具名输入槽。
+
+执行职责：资深分镜细化师。补全逐镜可见细节和视频动作描述。
+
+`narrative_purpose`、`shot_group`、`motion_plan`、`scene_strategy`、`rhythm_plan`、`edit_plan`、`dialogue_plan` 和 `visual_plan` 是已确认导演合同；`visual_plan.composition`（及上游摄影给出的 `composition_contract`，若输入中存在）是已确认构图合同。最终 description、camera_move 和 video_prompt 必须兑现场级视点与视听母题、节奏强度、动作—反应 pattern、对白覆盖、剪辑声桥、视觉重点、组内角色及起止状态，并原样保留全部合同字段（含 composition 与 composition_contract 全部子字段，code 不得改写）。`duration` 是生成素材长度，`edit_plan.intended_duration` 是成片预计保留时长。
+
+{cinematography_vocabulary}
+
+{storyboard_scene_types}
+
+{storyboard_scene_camera_styles}
+
+{character_video_subjects}
+
+表演沿用已确认方案，只描述符合剧情、有来源证据、可见且可执行的动作。
+
+【有动机的变化】
+
+- 每镜必须包含叙事变化或有意停顿。固定机位、静止凝视、屏息、对白停顿和受击停顿都是有效选择；不得为“动起来”额外添加手势或运镜。
+- 默认最多一个主要身体动作、一个有证据的微动作和一个视线变化；剧情明确要求复杂动作时除外。
+- camera_move 只输出一个规范名称。特写默认固定，只有已确认的动作跟随、信息揭示或焦点转移需要时才移动。
+- 镜头运动必须响应主体动作、信息权力或场级视点；人物节拍改变时可同步改变速度或稳定度，不能让摄影机脱离角色自行表演。
+- 每镜只有一个首要可读信息，通过景别、位置、遮挡、空间层次、光线、色彩或焦点建立主次；不得用无来源霓虹、烟雾、轮廓光或通用象征物制造“电影感”。
+- 不新增未获批准的动作、道具或环境事实。props、description、video_prompt 与 actingNotes 必须逐镜一致。
+- 冲击动作按蓄力、发力、接触点、受击停顿、重心变化和恢复/倒地组织；局部运动模糊或短促微震只发生在接触瞬间，随后恢复稳定。
+- 道具交互写清接触前、接触点和接触后状态，以及保持静止/连接的邻接物。结果必须在镜尾前清晰成立并短暂稳定。
+- 多人镜保持准确人数、左右顺序、朝向和肢体归属；复杂交互无法清楚归属时退回规划阶段拆镜。
+
+【构图契约落实】
+
+- 原样回传 visual_plan.composition 与 composition_contract（若输入存在）的全部子字段，不改 code、不删字段、不重排；本阶段只做可见兑现，不重新选模式。
+- description 必须可见落实 read_order（第一眼读到什么）、subject_placement（每个可见角色的画面位置与纵深层）、eyeline_room（视线方向、留白方向与占比）、depth_layers（前中后景各放什么、虚实如何）、light_and_color_geometry（主光方向与剧内来源、遮挡物与遮挡比例）、action_vector（动作与进出画屏幕方向）和 tail_state（镜尾人物位置、朝向、剩余张力）。
+- video_prompt 必须把上述几何写成可执行画面指令，并以符合 tail_state 的稳定镜尾画面收尾，再写 `镜尾转场【类型】`；shot_type 与 camera_move 服从构图合同，静止类合同显式 locked-off，禁止模型自行缓推、环绕或漂浮运镜。
+- 可见元素上限：composition 证据（evidence）、source_text、props、场景/道具资产是全部画面元素来源；禁止添加证据之外的雨、雪、雾、霓虹、镜子、烟尘、门窗廊柱、武器或多余路人。ai_risks 列出的每个风险都必须在 description 或 video_prompt 中有对应防控（留白区保持纯净、遮挡不盖双眼、接触点清晰、动势边缘留 10%、相邻镜屏幕方向一致等）。
+- 旧项目历史分镜若没有 composition/composition_contract 子字段，按原文档读取与细化，不要求回填补写，也不据此判失败。
+
+【声音与口型】
+
+- 画内对白：可见说话者按逐字台词产生自然口型、呼吸和表情。
+- 画外对白：说话者不在画面中，不得让其他可见角色代说；所有可见非说话者保持符合呼吸和表情的闭口状态。
+- 旁白或内心独白按画外音处理，不触发画内角色说话口型。
+- 同镜多人对白仅在 Provider 明确支持、说话时段不重叠且每张可见嘴部状态可写清时使用；否则拆镜，仅在 Provider 无原生音频能力时才 post-dub。
+
+【自然运动前置合同】
+
+- 对每个可见人物在 video_prompt 的时间线上落实主要动作、注意对象、反应触发和未参与时状态；除剧情明确要求同步外，错开多人起势、幅度、视线与反应延迟。
+- 景别可读时，静止人物使用不规则且不同步的眨眼、短暂重新聚焦、呼吸或小幅重心调整保持生命感，不得机械循环或抢戏。
+- 身体动作必须有支撑脚、重心转移、髋肩带动、关节路径、加减速、随动和恢复；接触道具后持续保持正确握持与承重。
+- 头发、衣摆、宽袖、饰物和道具只响应已有风、人物加速度、重力或接触，并以更小幅度延迟、衰减、稳定；环境只对有证据的局部力产生反应。指令过载、多人精确接触归属不清时必须拆镜。
+
+【人物视觉身份】
+
+- 角色参考中的 `identity_binding` 只用于校验档案版本和 `appearance_id`，不得输出到可见描述；把 `identity_constraints` 的 `grooming_and_makeup`、`costume_signature` 与全部 `memory_anchors` 原样落实到每个可见角色。
+- 把同一角色引用的 `performance_constraints` 原样带入分镜表演合同。`eyeline_behavior`、`blink_rhythm`、`stress_response` 与带触发条件的 `habitual_actions` 只在当前剧情触发成立时转成可见节拍，`forbidden_performance` 始终生效；不得仅凭性格标签编造心理活动。
+- 心理变化必须写成刺激或信息、注视对象与眼神转移、表情面具、短暂泄露、决定/动作和镜尾残留；为近景/特写指定一至两个可见面部区域及低幅起势—峰值—释放，中远景改用头部、呼吸、姿态、停顿、距离和走位。不得输出 FACS/AU 编码或只写“复杂、震惊、腹黑”等不可执行标签。
+- 同一 `appearance_id` 的妆发、服装标识和记忆锚点必须跨镜一致；不得根据姓名、职业或画面自行增加、删减或改写 `memory_anchors`。只有连续性计划中带明确剧情证据的允许变化才能换装或换造型。
+
+【输入】
+
+分镜规划：
+{panels_json}
+
+角色年龄性别信息：
+{characters_age_gender}
+
+场景描述：
+{locations_description}
+
+道具描述：
+{props_description}
+
+【项目视觉圣经——独立于画风，必须遵守】
+{visual_bible}
+
+【输出】
+
+返回 JSON 数组，每个 panel 为原输入完整对象并补全或细化 description、shot_type、camera_move、video_prompt、visible_event_keys；可保留合法 duration。video_prompt 用年龄段+性别指代人物，gender=unknown 时使用年龄段+“人士”，不得根据名字、职业、外观或动作猜测性别。
+
+规则：
+1. 数组长度和 panel 顺序不变；逐项原样回传 panel_number、characters、location、scene_type、source_text 及全部导演合同字段，不新增、删除、重复或重排镜头。
+2. shot_type 使用“视角+景别”，camera_move 使用一个规范运镜名称。
+3. description 只能提升可见性和执行性，不改变剧情、人物身份、动作结果或场景事实。
+4. video_prompt 以当前镜头有证据的稳定结束画面收尾，并写明 `镜尾转场【类型】`。特殊转场必须有当前镜头可见触发；否则使用硬切，不提前生成下一镜剧情。
+5. 保留稳定站位角色的完整 slot，并作为优先锚点；移动、进出、路径、过渡空间、空镜、梦境、回忆或抽象空间可不使用 slot。不得缩写、改写或用短 token 替换已有 slot。
+6. 不得从 characters 删除输入角色。特写、插入或反打拍不到某角色时，在 description 说明镜头范围；只有 source_text 或 description 明确引入新的可见资产库角色时才可补入。
+7. 每个实际可见人物必须存在于 characters，且 appearance 必须保留可解析的 `char-*@vNNN`；座次、群像、镜面或背景中可辨认的人物不能只写进 description。visible_event_keys 只列本镜真实可见、可作为动作声依据的稳定事件 key；没有动作声事件时为空数组。脚步、衣料、碰撞、开门或能量声分别必须有对应的走动、衣物运动、接触、门体运动或可见能量事件，不得按气氛虚构。
+8. 只返回严格 JSON 数组，不要 Markdown、解释或注释。JSON 字符串内需要引用时使用「」，禁止未转义的英文双引号。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/build-drama-storyboard/prompts/agent_storyboard_plan.en.txt

@@ -0,0 +1,114 @@
+# Codex execution contract: agent_storyboard_plan
+
+The owning Skill reads this file to constrain Codex inputs, decisions, and output. It is not a system prompt sent to an external text model. Braced fields are named input slots assembled from selected local project assets.
+
+Execution role: storyboard planning director.
+Generate an initial panel sequence for one clip.
+
+Character library names:
+{characters_lib_name}
+
+Location library names:
+{locations_lib_name}
+
+Character introduction mapping:
+{characters_introduction}
+
+Character appearance list:
+{characters_appearance_list}
+
+Character full descriptions:
+{characters_full_description}
+
+Prop descriptions:
+{props_description}
+
+Clip metadata JSON:
+{clip_json}
+
+Clip content:
+{clip_content}
+
+Task:
+Create a coherent panel plan that covers the full clip content in chronological order.
+Treat one shot as one irreducible visible narrative beat. Merge dialogue, listening, ordinary reactions, and continuous action when they share the same blocking. Create a new shot only for a reveal, action turn, viewpoint change, or clear rhythm break. Never add repeated action, an empty reaction, or a shot with no new story information.
+Each panel is one video-model generation: one time, one place, and one continuous camera take. Split every montage, cross-cut, location change, camera cut, or chain of independent causal actions into separate panels and relate them with shot_group.
+
+Preproduction performance and natural-motion planning:
+- Before splitting shots, read each character's `performance_bible` from the full character descriptions. It is the ceiling for long-term body and attention behavior, not a per-shot action checklist. Apply center of gravity, gait, eyeline, blink rhythm, stress response, or a habitual action only when source_text or the current relationship task supplies its trigger.
+- At the first plan, give every visible person one primary action, one attention target, one reaction trigger, and an uninvolved state. Unless the screenplay explicitly calls for marching, ritual unison, shared shock, or synchronized action, offset onset, amplitude, gaze, and reaction latency; never make everybody turn, nod, blink, step, or gesture together.
+- A still person is not frozen. When readable at the shot scale, retain irregular blinks, brief refocusing, breathing, and a small weight adjustment only in service of the current relationship task, never as a loop or distracting business.
+- Hair, hems, loose sleeves, accessories, and props respond only to established wind, character acceleration, gravity, or contact, with smaller delayed motion, damping, and settling. Never add windless flutter, whole-body phase locking, or unsupported environmental response merely to look natural.
+- Plan psychology as stimulus/information → attention and gaze shift → maintained social mask → brief leak → decision/action → residual exit expression. In a readable close shot, use micro-expression in only one or two facial regions with a low-amplitude onset—apex—release; at wider scales use head, breath, posture, pause, distance, and blocking. Do not invent an inner state without evidence from source, profile, or director contract.
+
+{storyboard_scene_types}
+
+{cinematography_vocabulary}
+
+Output format (JSON array only):
+Every panel must include the complete director contract: `narrative_purpose`; `shot_group: {id, type, role, pattern}`; `motion_plan: {subject, start_state, end_state, verb, camera_role}`; `scene_strategy: {scene_id, objective, viewpoint, tone, pacing, visual_motif, sound_motif}`; `rhythm_plan: {beat_role, intensity}`; `edit_plan: {cut_motivation, axis, screen_direction, transition, sound_bridge, intended_duration, transition_in, transition_out}`; `dialogue_plan: {mode, focus}`; and `visual_plan: {emphasis, standout, technique, composition}`. For newly generated panels, `composition` is required and is `{primary, secondary, reason, evidence}`: primary is required and must be exactly one code from the controlled composition vocabulary (composition.basic.* / composition.film.* / composition.action.* / composition.character.*; names are injected in [CANONICAL CINEMATOGRAPHY VOCABULARY], and the code-name mapping, evidence floors, and combinable patterns live in references/controlled-vocabulary.json and references/director-composition.md); secondary must be null or one single code different from primary, used only for a genuine second information layer, never two competing strong style patterns; reason must bind the choice to this panel's narrative_purpose and its one primary readable fact; evidence must cite concrete support — an exact source_text excerpt, a specific item in the scene/prop assets, or an action fact established by the screenplay — labeled with the code's required evidence level (composition-only/set_dressing/weather_atmosphere/action_blocking), and a compound level joined with + requires each component to be evidenced separately. `pattern` must be one of standard/reaction-first/action-stacked/reaction-omitted/action-hidden/delayed-reaction/synchronous/reaction-chain/repeated-variation/contrapuntal/omitted-action/chain-link and stay identical inside a group. Keep `scene_strategy` identical for every panel sharing a scene_id. `duration` is generated source length; `intended_duration` is the planned final edit hold and must be greater than zero and no longer than `duration`.
+After completing the full ordered panel array, design one shared transition contract for every adjacent pair. Store the same contract as the source panel's `transition_out` and the target panel's `transition_in`. The first panel has no `transition_in`, the last panel has no `transition_out`, and every middle panel has both.
+Each `transition_in`/`transition_out` is `{source_shot_key, target_shot_key, kind, motivation, source_end, target_start, screen_direction, trigger, audio_bridge, confidence}`. During planning, use stringified `panel_number` values for the shot keys. `kind` must be action-hold-hard-cut/occlusion-cut/whip-pan-cut/action-match-cut/match-cut/motivated-light-cut/dissolve-time-cut/black-cut. Contract `screen_direction` must be left-to-right/right-to-left/up/down/in/out/neutral, and `confidence` must be high/medium/low.
+When a character exits in the source panel and remains absent from the target, source_end must retain that character's exit edge, last posture, movement direction, and held props. On the character's next entrance, target_start must continue that offscreen state unless the scene or time explicitly resets it.
+Prefer evidenced action, occlusion, whip, composition, story-motivated light, time, or black-frame bridges. Low-confidence contracts must fall back to `action-hold-hard-cut` with `neutral` direction. Never use an unmotivated flash, random smoke, or arbitrary spatial distortion as a fallback. Omit `audio_bridge` when the story provides no sound motivation.
+Allowed values: shot group type = single/montage/progression/causal/contrast; role = setup/action/reaction/bridge/payoff; camera_role = observe/follow/reveal/contrast/hold; beat_role = setup/build/turn/climax/release/transition with integer intensity 1–5; axis = establishing/same-axis/reverse/neutral/insert; screen_direction = left-to-right/right-to-left/neutral; transition = hard-cut/match-cut/J-cut/L-cut/dissolve/fade/continuous; dialogue mode = speaker/listener/two-shot/over-shoulder/dirty-single/clean-single/environment/long-take/none; dialogue focus = speaker/listener/relation/environment/action/none; visual technique = standard/metaphor/reveal/callback/contrast/withhold/spectacle, with boolean standout.
+First set the scene objective, viewpoint, tone, pacing, and audiovisual motifs, then design shot groups and shot-level change. Use visible subjects, distinct start/end states, and executable verbs; fade, slide, pop, or zoom alone is not story motion. Apart from an intentional hold, every shot should deliver the visible state or information change named by narrative_purpose. A causal group normally needs action plus reaction/payoff in the pattern order; reaction-omitted may omit the reaction, omitted-action/action-hidden may omit visible action, reaction-first reverses the order, and synchronous/repeated-variation/contrapuntal do not impose order. Read the shot-scale, camera-position, movement, and dialogue-coverage columns down the sequence; repeat them unchanged only for a stated purpose such as relational pressure, ritual, or deliberate monotony. Long scenes need readable intensity variation, and standout treatment is reserved for turns or climaxes rather than filled to a ratio. Motivate every cut and preserve axis, eyeline, and screen direction. J/L cuts and sound bridges need a concrete sound source. Equal start/end states are allowed only for an intentional hold whose purpose explains the pause.
+When dialogue_plan focuses speaker, keep that speaker visible with readable lip action. For listener, relation, or environment focus, the speaker may remain offscreen only when the sound source is explicit and every visible non-speaker mouth stays closed. Use multiple speaking faces in one shot only when the Provider supports it, speech windows do not overlap, and every visible mouth state can be scheduled; otherwise split coverage, and use post-dub only when the Provider lacks native audio.
+Build visual motifs only from source_text, registered assets, or established location anchors. Give existing objects, light, sound, or spatial relationships meaning through framing, occlusion, negative space, repetition, or contrast; never add generic symbolic birds, clocks, weather, mirrors, or props merely to explain an emotion.
+Composition selection order is mandatory and must not be skipped or reversed: (1) scene motifs first — read the director scene's camera_strategy.composition_motifs when provided; the panel composition must serve the variation or payoff of one of them, and must not introduce a composition or stylistic look that serves none of the provided motifs; (2) name the panel's one primary readable fact — whose decision, what threat, what relationship change, or what action result the viewer must read first, exactly one per shot; (3) then choose primary/secondary — the single code among the 64 patterns that best carries the primary fact, plus one secondary only for a real second information layer; (4) finally translate the codes into visible geometry in description: subject placement, eyeline and negative space, foreground/midground/background, light sources, occlusion, action direction, and tail state. Never merely echo a pattern name and never rotate patterns mechanically down the shot list.
+Evidence hard rule: evidence is the minimum floor for using a code. set_dressing elements (doors, windows, mirrors, columns, long tables, neon, weapons) must exist in the scene/prop assets or screenplay description; weather_atmosphere elements (rain, snow, fog, backlight, dual-color-temperature sources) must be supported by the source text, scene setting, or assets; action_blocking (conflict, pursuit, encirclement, group movement) must be established by the screenplay or director blocking; a compound evidence value joined with + requires every component. With insufficient evidence you must downgrade to a supported code; never add weather, dressing, or blocking absent from the source text or assets. When reading legacy panels that lack a composition field, read them as-is and never require backfilling.
+
+[
+  {
+    "panel_number": 1,
+    "shot_number": 1,
+    "description": "visual action description",
+    "characters": [
+      { "name": "Character Name", "appearance": "appearance name", "slot": "the position beneath the throne steps at the center of the hall" }
+    ],
+    "location": "location name",
+    "scene_type": "daily",
+    "source_text": "exact or near-exact source excerpt",
+    "shot_type": "medium shot",
+    "camera_move": "static",
+    "video_prompt": "short visual motion prompt",
+    "duration": 5,
+    "continuity_mode": "independent or previous-tail",
+    "continuity_reason": "specific reason for a hard cut or tail-frame continuation"
+  }
+]
+
+Planning rules:
+1. Keep strict chronological order.
+   - props may contain only assets explicitly present in the current shot source_text and actually visible or handled in that shot.
+   - The prop library is only a candidate list. Never carry a prop forward from a previous shot without current-shot evidence; use [] when no prop is evidenced.
+   - Before returning, remove from each shot every prop not explicitly present in that shot source_text, and remove the same prop from description.
+2. Avoid missing key beats from clip_content.
+3. Keep panel transitions smooth and logically continuous.
+4. Use locations and characters consistent with provided libraries and mappings.
+   - `clip_json.characters` is the minimum cast list for this clip. If `clip_content` or the structured screenplay explicitly mentions additional character assets, include them in relationship reasoning too.
+   - In wide, long, medium, and multi-character relationship shots, every core character still present in the current scene and not explicitly exited must appear in the `characters` array and be positioned or acknowledged in `description`.
+   - Close-ups, inserts, reaction shots, and reverse shots may include only what the camera can actually see, but `description` must make the tight framing clear so the character is not perceived as disappearing.
+   - Dialogue shots must include at least the speaker. If the listener, shoulder, silhouette, or reaction is visible, include the listener in `characters` and describe their screen position.
+
+   Macro vs. micro location selection:
+   - The location library annotates each entry as macro (overall setting) or micro (specific room/area inside a macro).
+   - Shot-scale drives the choice:
+     - Wide / establishing / aerial / exterior shots → select the **macro** entry. Fill the `location` field with just the macro name (e.g. `"Lin Manor"`).
+     - Medium / close-up / interior-detail shots → select the **micro** entry. Fill the `location` field with the **full path** `"macroName/microName"` (e.g. `"Lin Manor/Main Hall"`).
+   - Fallback: if the source text only mentions the macro without specifying a sub-location, pick the macro and use its plain name.
+   - If the source says characters move toward / enter a specific local area, bind subsequent related shots to the corresponding full micro path, such as `"Zixiao Palace/Palace Hall Entrance"` or `"Zixiao Palace/Main Hall"`.
+   - Establishing shots may use the macro. After entering a local area, medium, close-up, and relationship shots should keep using that micro path until the scene clearly changes.
+   - Never emit a bare micro name without its macro prefix — always output the full `macroName/microName` path for micro entries.
+
+5. Prefer concrete, visible actions over abstract wording.
+6. If location context contains available slots, treat them as preferred placement anchors rather than mandatory hard boundaries.
+7. Prefer assigning a `slot` by copying one full placement phrase from `available_slots` verbatim when a character is stably positioned in the scene.
+8. You may omit `slot` when the shot is mainly about movement, entry/exit, path traversal, transition space, temporary space, empty space, imagination, dream, memory, or abstract/non-literal space.
+9. When no `slot` is used, decide placement freely from source text, action flow, and cinematic staging instead of forcing one of the provided slots.
+10. Do not shorten, rewrite, summarize, or replace a provided slot phrase with a short token such as `slot_1`, `left`, or `throne_front`.
+11. `duration` is required. Estimate it from visible action, actual speaking time, movement, and camera rhythm, and keep it within {shot_duration_constraints}. Include editing handles only when the constraint allows them. Do not mechanically add or remove shots to hit an exact episode total or assign one fixed duration to every shot.
+12. Return strict JSON only.
+13. ⚠️ JSON SAFETY: All quotation marks in text (""''「」 etc.) MUST be converted to corner brackets「」in JSON string values. NEVER use raw ASCII double quotes " inside string values.
+14. Continuity is required: use independent for the episode opener, scene/time changes, black frames, title cards, or explicit hard cuts; otherwise default to previous-tail. A Part boundary alone never breaks continuity.
+15. ⚠️ visual_plan.composition is mandatory for newly generated panels: primary must be one of the 64 controlled codes, secondary must be null or one different code, reason must bind to narrative_purpose, and evidence must cite source_text, scene/prop assets, or an action fact with its labeled evidence level (every component of a + compound evidenced). Select in the order scene motif, primary readable fact, primary/secondary, visible geometry; never rotate patterns mechanically. With insufficient evidence switch codes; never add unsourced weather, dressing, or action.