@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/generate-character-profiles/character-profile-output.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Character profile analysis result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["new_characters", "updated_characters"],
+  "properties": {
+    "new_characters": {"type": "array", "items": {"$ref": "#/$defs/newCharacter"}},
+    "updated_characters": {"type": "array", "items": {"$ref": "#/$defs/updatedCharacter"}}
+  },
+  "$defs": {
+    "shortText": {"type": "string", "maxLength": 160},
+    "performanceBible": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["center_of_gravity", "gait", "habitual_actions", "eyeline_behavior", "blink_rhythm", "stress_response", "forbidden_performance"],
+      "properties": {
+        "center_of_gravity": {"$ref": "#/$defs/shortText"},
+        "gait": {"$ref": "#/$defs/shortText"},
+        "habitual_actions": {"type": "array", "maxItems": 8, "items": {"$ref": "#/$defs/shortText"}},
+        "eyeline_behavior": {"$ref": "#/$defs/shortText"},
+        "blink_rhythm": {"$ref": "#/$defs/shortText"},
+        "stress_response": {"$ref": "#/$defs/shortText"},
+        "forbidden_performance": {"type": "array", "maxItems": 8, "items": {"$ref": "#/$defs/shortText"}}
+      }
+    },
+    "voiceIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pitch", "timbre", "accent", "pace", "delivery"],
+      "properties": {
+        "pitch": {"$ref": "#/$defs/shortText"},
+        "timbre": {"$ref": "#/$defs/shortText"},
+        "accent": {"$ref": "#/$defs/shortText"},
+        "pace": {"$ref": "#/$defs/shortText"},
+        "delivery": {"$ref": "#/$defs/shortText"}
+      }
+    },
+    "audienceAppeal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["age_class", "appeal_mode", "screen_presence", "grooming_and_makeup", "costume_signature", "memory_anchors", "prohibited_treatment"],
+      "properties": {
+        "age_class": {"enum": ["adult", "child", "unknown", "not-applicable"]},
+        "appeal_mode": {"enum": ["adult-charisma", "child-cuteness", "not-applicable"]},
+        "screen_presence": {"type": "string"},
+        "grooming_and_makeup": {"type": "string"},
+        "costume_signature": {"type": "string"},
+        "memory_anchors": {"type": "array", "maxItems": 3, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "prohibited_treatment": {"type": "array", "maxItems": 8, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+      }
+    },
+    "appearance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "change_reason"],
+      "properties": {
+        "id": {"type": "integer", "minimum": 1},
+        "change_reason": {"type": "string", "minLength": 1}
+      }
+    },
+    "newCharacter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "aliases", "introduction", "gender", "age_range", "role_level", "archetype", "personality_tags", "era_period", "social_class", "occupation", "costume_tier", "suggested_colors", "primary_identifier", "visual_keywords", "performance_bible", "voice_identity", "audience_appeal", "expected_appearances"],
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "aliases": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "introduction": {"type": "string", "minLength": 1},
+        "gender": {"enum": ["male", "female", "nonbinary", "unknown"]},
+        "age_range": {"type": "string", "minLength": 1},
+        "role_level": {"enum": ["S", "A", "B", "C", "D"]},
+        "archetype": {"type": "string", "minLength": 1},
+        "personality_tags": {"type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "era_period": {"type": "string", "minLength": 1},
+        "social_class": {"type": "string", "minLength": 1},
+        "occupation": {"type": "string", "minLength": 1},
+        "costume_tier": {"enum": [1, 2, 3, 4, 5]},
+        "suggested_colors": {"type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "primary_identifier": {"type": "string"},
+        "visual_keywords": {"type": "array", "items": {"type": "string", "minLength": 1}},
+        "performance_bible": {"$ref": "#/$defs/performanceBible"},
+        "voice_identity": {"$ref": "#/$defs/voiceIdentity"},
+        "audience_appeal": {"$ref": "#/$defs/audienceAppeal"},
+        "expected_appearances": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/appearance"}}
+      }
+    },
+    "updatedCharacter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "updated_introduction", "updated_aliases"],
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "updated_introduction": {"type": "string", "minLength": 1},
+        "updated_aliases": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+      }
+    }
+  }
+}

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/generate-character-profiles.md

@@ -0,0 +1,7 @@
+# 生成人物档案
+
+先运行 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/character-profiles.mjs" context <项目目录>`，将输出 JSON 作为 `characters_lib_info`；它是动态本地人物上下文，不是枚举。`input` 使用当前确认的小说或剧本文本。再用 `render-prompt.mjs` 渲染 `../../assets/modules/generate-character-profiles/prompts/agent_character_profile.{zh,en}.txt`：`character_profile_enums` 与 `character_profile_reference_vocabulary` 会从插件本地 [受控词表](../controlled-vocabulary.json) 自动注入，不得由用户临时填写。
+
+先合并别名、第一人称映射和关系，禁止把仅被提及或不出镜的对象建成人物。`performance_bible`、`voice_identity` 只记录原文明示或跨场景重复的长期特征；一次性动作、情绪和特效不得固化。每个角色至少保留初始形象，只有换装、年龄或持续造型变化才新增版本。
+
+输出必须符合 [人物档案 Schema](generate-character-profiles/character-profile-output.schema.json)，且顶层只能有 `new_characters[]` 与 `updated_characters[]`。先运行 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/character-profiles.mjs" validate <项目目录> <结果 JSON>`；向用户展示新增、合并与冲突结果并确认后，才运行 `apply` 写入 `assets/characters/profiles.json`。人物事实确认后交给 `generate-character-images`；用户未确认前不得生成图片。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/generate-drama-art-style.md

@@ -0,0 +1,9 @@
+# 生成短剧画风
+
+读取 brief、bible、用户参考和项目当前 `creative.art_style`。未提出自定义画风时保留默认 `system-realistic`；提出明确画风时，由 Codex 使用 `../../assets/modules/generate-drama-art-style/prompts/config_generation.{zh,en}.txt` 生成 prompt、description、renderingContract 和 visualBible，不调用文本 Provider。
+
+画风必须统一人物、场景、道具、分镜与视频的媒介、色板、光线和运动语言，但不得写入具体人物身份、剧情动作或地点事实。画风确认阶段就必须形成 `renderingContract`，明确 `medium`、`rendering_method`、`surface_language`、`image_formation` 和 `forbidden_substitutions`；不得把真人写实设为隐式默认，也不得用“电影感”“高级感”代替媒介定义。需要预览时调用 `drama-generation-service`，展示并确认图片 Provider、模型、尺寸、参考图和候选数，不计算具体价格；预览保存到本地 `assets/other/`。
+
+用户确认后，用 `project-store.mjs update-project` 将完整配置写入 `.short-drama/project.json` 的 `creative.art_style`。随后必须使用 `art_style_decision.{zh,en}.txt` 输出确认合同，并以 `project-store.mjs put-document <项目> art-style <JSON>` 保存为 `.short-drama/art-style.json`；其 style 必须与项目配置完全相同，才能登记本 Skill。下游 `render-prompt.mjs` 必须接收完整 style 对象，统一把它编译成画风合同后再注入人物、场景、道具、双分镜板和视频提示词；不得只传名称、分类或一行风格短语。
+
+当用户确认的是自定义画风（而非系统画风）时，必须将完整 style 对象追加或更新到统一工作区根目录下的 `art-styles.custom.json`（或环境变量 `SHORT_DRAMA_CUSTOM_ART_STYLES_FILE` 指定的路径），确保下次可直接选择。只登记已确认且通过完整字段校验的画风；不得把草稿、未确认结果或系统画风复制进自定义库，也不得覆盖系统画风同 ID。修改已投入使用的画风必须标记受影响资产为 stale，不静默混用旧风格。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/generate-prop-assets.md

@@ -0,0 +1,11 @@
+# 生成道具资产
+
+用 `select_prop`，向 `input` 传目标文本、向 `props_lib_name` 传已有道具库。只保留可移动、不可替代且有跨场景或长期持有证据的实体；普通家具、餐具、服装、场景设施和一次性物件不建资产。无合格项时接受 `{"props": []}`。
+
+`props[].description` 只写材质、颜色、形状、结构、数量与装饰。参考图或修改指令引起描述变化时，用 `prop_description_update`；出图时用 `prop_generate` 把已确认描述与完整项目画风对象编译为主视图、正/侧/背视图和有证据的结构细节设定板，不在调用处另拼隐藏提示词。设定板版式不得覆盖 renderingContract 选定的媒介与材质语言。
+
+同一道具存在多个状态版本时，先生成并选定基础状态；后续状态必须把该选版作为身份参考，只改变版本证据明确要求的开合、破损、内容物或使用痕迹，并保持尺寸等级、结构、材质、纹样和独特锚点。基础状态缺少可用选版时不生成派生状态；不得用人物或手部充当尺度参照。
+
+对同一依赖层的全部道具全量提交 `generate_image`；StarRouter 并发由 Hypit Runtime Endpoint 控制，其余请求排队；派生状态只在基础状态选版后进入下一并发层。生成白底居中、单道具资产图，传 `{kind:"asset-plan",episode_key,version_id,asset_key}`，并向 `render-prompt.mjs` 传完整项目画风对象；实际 prompt 必须等于 `prop_generate` 的已留痕输出。提交前展示并确认模型、数量、尺寸、参考路径和制作计划，不计算具体价格。用 `asset-ledger.mjs fetch|decode` 保存候选并写入相同制作文档引用；检查结构、数量、纹样、损伤状态以及 renderingContract 的媒介、材质和成像规则。新生成候选不得直接选版，必须执行 `review-ledger.mjs review-visual-asset`，绑定当前画风 ID 与内容哈希后才可原子选版。
+
+StarRouter 图片枚举：`model=gpt-image-2`；`resolution ∈ {1K,2K,4K}`；`aspect_ratio ∈ {1:1,16:9,9:16,4:3,3:4}`；`quality ∈ {auto,low,medium,high}`；`background ∈ {auto,opaque,transparent}`；`moderation ∈ {auto,low}`；`output_format ∈ {png,jpeg,webp}`；`n=1..4`。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/generate-scene-assets.md

@@ -0,0 +1,13 @@
+# 生成场景资产
+
+先用 `select_location` 从目标文本提取需要独立背景图的 macro/micro 场景；不得把跨地点空间强行嵌套。输出 `locations[]`，每项保留三条 `descriptions`、2–6 个 `available_slots`，且站位锚点必须真实出现在描述中。
+
+临时创建使用 `location_create`；后续按操作选 `location_modify`、`location_regenerate` 或 `location_description_update`。严格使用 [提示词索引](../prompt-skill-index.md) 中的变量与 JSON 合同。图片候选默认生成无人空镜；只有原文明示且公共活动是空间语义的一部分时，才允许无名、非主体背景人群。具名人物、剧情动作、字幕和水印不得写入场景提示词。
+
+`asset-plan` 中场景存在 `derived_from` 时，不得从零重画：先读取母场景当前 selected 本地图片，把它作为结构与材质参考，只生成版本证据明确要求的时段、天气、前景或陈设变化，并保持建筑骨架、出入口、固定锚点、尺度和磨损一致。母场景没有可用选版时将该变体保持 blocked，不用文字描述冒充视觉继承。
+
+对同一依赖层的全部场景全量提交 `generate_image`；StarRouter 并发由 Hypit Runtime Endpoint 控制，其余请求排队；`derived_from` 场景只在母场景选版后进入下一并发层。调用时传 `{kind:"asset-plan",episode_key,version_id,asset_key}`，并向 `render-prompt.mjs` 传完整项目画风对象；实际 prompt 必须等于 `scene_asset_sheet` 的已留痕输出。提交前展示并确认模型、数量、尺寸、参考路径和制作计划，不计算具体价格。用 `asset-ledger.mjs fetch|decode` 保存候选并写入相同制作文档引用；检查父子空间、固定锚点、时代、建筑结构、光线方向以及当前 renderingContract 的媒介、材质和成像规则。新生成候选不得直接选版，必须执行 `review-ledger.mjs review-visual-asset`，绑定当前画风 ID 与内容哈希后才可原子选版。
+
+正式出图必须用 `scene_asset_sheet` 生成同一场景的九视角网格、平面布局、轴测图、色卡和关键材质样本；各视角共享同一空间结构。网格只是空间信息布局，不得把用户媒介偷换成概念原画、真人摄影、二维厚涂或三维游戏场景；以当前 renderingContract 为唯一媒介事实源。不得在调用处退化为单张泛化背景。
+
+StarRouter 图片枚举：`model=gpt-image-2`；`resolution ∈ {1K,2K,4K}`；`aspect_ratio ∈ {1:1,16:9,9:16,4:3,3:4}`；`quality ∈ {auto,low,medium,high}`；`background ∈ {auto,opaque,transparent}`；`moderation ∈ {auto,low}`；`output_format ∈ {png,jpeg,webp}`；`n=1..4`。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/manage-drama-art-styles.md

@@ -0,0 +1,9 @@
+# 管理短剧艺术风格
+
+读取项目当前画风和已有候选；创建新画风时路由到 `generate-drama-art-style`。选择画风时检查 prompt、visualBible、预览图和适用题材，风格不得包含具体人物身份、剧情事件或与场景冲突的地点事实。
+
+生成预览前展示并确认模型、尺寸和候选数，不计算具体价格；使用同一中性测试内容比较候选。每个候选先具备明确的 `renderingContract`，中性测试内容分别验证媒介、渲染方法、表面材质语言和成像方式，不能只比较“好不好看”。预览图下载到本地资产库并记录 provenance，选定的结构化风格配置写入 `.short-drama/project.json` 的 `creative.art_style`。
+
+画风库由系统画风库 `manage-drama-art-styles/art-styles.json` 与统一工作区根目录下的 `art-styles.custom.json`（或 `SHORT_DRAMA_CUSTOM_ART_STYLES_FILE`）合并组成。选择或确认自定义画风后，必须保存完整 style 对象到自定义库并按 `id` upsert；系统画风只读，不得被自定义对象覆盖。自定义画风必须包含 `id`、`name`、`description`、`prompt`、完整 `renderingContract` 和完整 v1 `visualBible`，未确认或不完整的候选不得登记。旧自定义画风缺少 renderingContract 时先补齐并让用户重新确认，不从名称自动猜媒介。
+
+`update-project` 会把既有人物、场景、道具、故事板和视频版本标记为 stale 并取消选版；重新生成使用新版本，不得清除旧版失效记录。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/manage-drama-assets.md

@@ -0,0 +1,9 @@
+# 管理短剧资产
+
+所有媒体资产使用稳定 key、类型、输入指纹、候选版本和 `selectedVersionId`。key 必须使用 `char-`、`scene-`、`prop-`、`board-`、`shot-`、`audio-` 或 `other-` 前缀，版本使用 `v001`。先用 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/asset-ledger.mjs" put <项目目录> <资产.json>` 建档；本地结果用 `import`，Provider 返回的 HTTPS URL 用 `fetch`，base64 结果文件用 `decode`。三者都会把内容保存到项目并记录本地相对路径、文件大小、SHA-256 和固定 provenance。
+
+只读查看使用 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/asset-ledger.mjs" list <项目目录> [资产 key]`；第一个参数必须是子命令，不能省略。
+
+Provider 结果执行 `fetch|decode` 时必须在文件名参数后提供 provenance JSON；不自定义文件名时传 `-`。provenance 固定记录 `origin`、`created_by`、Provider、模型/工作流、任务 ID、视频提示词文档、上游资产版本和生成参数，禁止密钥。已有本地文件版本可用 `add-version` 登记，但必须携带 provenance，且 `localPath` 位于项目目录并真实存在。使用 `select`、`revert`、`list` 管理选版历史；不得直接修改 `.short-drama/assets.json`。
+
+远程 URL 只是临时传输结果：文件未进入 `assets/{characters,scenes,props,storyboards,audio,videos,other}/` 并成功登记前，任务不得标记完成。选版后按 ID 回读，不按修改时间猜测成品；上游内容变化时标记真实下游 stale。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/analyze-drama-source/prompts/source_analysis.en.txt

@@ -0,0 +1,24 @@
+# Codex execution contract: source_analysis
+
+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: short-drama adaptation analyst. Analyze the material only; do not create or rewrite plot.
+
+[SOURCE MATERIAL]
+{source_material}
+
+[USER PRODUCTION REQUIREMENTS AND PROJECT CONFIG]
+{project_requirements}
+
+After reading the complete input, return strict JSON whose only top-level keys are: source_scope, adaptation_mode, facts, timeline, characters, locations, props, conflicts, themes, visual_challenges, content_constraints, user_requirements, contradictions, open_questions, coverage.
+
+Rules:
+1. Every facts item contains fact, evidence, and source_locator. Keep source fact, user requirement, and analytical inference separate.
+2. Sort timeline by story time while preserving source positions for flashbacks, nonlinear order, and parallel plots.
+3. characters, locations, and props are clues only; do not create final asset profiles here.
+4. contradictions lists both sides and the decision impact. Never choose silently.
+5. coverage must contain a complete boolean, per-source ranges, and gaps. complete may be true only when ranges cover every selected source without gaps. Merge every chunk of long material; never claim full coverage from sampling.
+6. adaptation_mode is exactly original, faithful_adaptation, or authorized_adaptation.
+7. source_scope records every local source's stable key, selected version, and covered chapters, such as src-original-novel@v001. Never store the original machine's absolute path.
+
+Do not output story prose, screenplay, shots, image prompts, Markdown, or explanation.

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/analyze-drama-source/prompts/source_analysis.zh.txt

@@ -0,0 +1,24 @@
+# Codex 执行合同：source_analysis
+
+本文件由所属 Skill 读取，用于约束 Codex 的输入、判断与输出；不是发送给外部文本模型的 system prompt。花括号字段是从当前项目已选资产组装的具名输入槽。
+
+执行职责：短剧改编分析师。只分析材料，不创作或改写剧情。
+
+【来源材料】
+{source_material}
+
+【用户制作要求与项目配置】
+{project_requirements}
+
+完整阅读后，只返回严格 JSON，顶层必须且只能包含：source_scope、adaptation_mode、facts、timeline、characters、locations、props、conflicts、themes、visual_challenges、content_constraints、user_requirements、contradictions、open_questions、coverage。
+
+规则：
+1. facts 每项包含 fact、evidence 和 source_locator；原文事实、用户要求、分析判断必须分开，不得混写。
+2. timeline 按故事时间排序，同时保留倒叙、插叙或多线叙事的来源位置。
+3. characters、locations、props 只记录线索，不在此阶段生成最终资产档案。
+4. contradictions 逐项列出冲突双方和需要用户决定的影响；不得自行选择。
+5. coverage 必须包含 complete 布尔值、逐份来源的 ranges 和 gaps；只有 ranges 无缺口覆盖全部 selected 来源时 complete=true。长篇必须合并所有分块结果，不能用抽样声称全量覆盖。
+6. adaptation_mode 只能是 original、faithful_adaptation 或 authorized_adaptation。
+7. source_scope 必须记录每份本地来源的稳定 key、选定版本和覆盖章节，例如 src-original-novel@v001；不得写原机器绝对路径。
+
+禁止输出故事正文、剧本、镜头、图片提示词、Markdown 或解释。

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

@@ -0,0 +1,61 @@
+# Codex execution contract: agent_acting_direction
+
+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: experienced Acting Director.
+Your task is to generate acting notes for each character in each panel.
+Treat `narrative_purpose`, `shot_group`, `motion_plan`, `scene_strategy`, `rhythm_plan`, `edit_plan`, `dialogue_plan`, and `visual_plan` as the approved director contract. Performance must move the subject from start_state to end_state, serve the scene viewpoint, intensity, and group role, and use dialogue mode/focus to distinguish speaking, listening, and relationship reactions. For camera_role=hold, preserve the intentional pause. Do not invent movement or rewrite contract fields.
+Performance must obey the composition contract: when an input panel contains visual_plan.composition or an upstream composition_contract, visible action must follow read_order (the character carrying the primary readable fact leads the on-screen event), eyeline_room (eyeline direction and negative space; performance must not invade the empty zone or reverse the gaze), isolation/occlusion (an occluded, defocused, or secondary-layer character does not upstage or make large moves), and action_vector (screen direction of action and entrances/exits, and the anticipation-contact-result sequence), landing on tail_state at the end frame. Performance must never demand changes to composition, axis, or picture elements. The acting text still contains only goal, obstacle, strategy, and visible action; add no visual fields and emit no composition codes.
+
+Core input:
+- Total panel count: {panel_count}
+- Panels JSON:
+{panels_json}
+- Character info:
+{characters_info}
+
+{storyboard_scene_types}
+
+{storyboard_scene_acting_styles}
+
+Performance vocabulary (select only observable cues that fit the panel):
+{performance_visual_vocabulary}
+
+Requirements:
+1. Treat each panel independently. The same character can have different emotional states across panels.
+2. Adapt performance style to the canonical panel.scene_type above.
+3. For each character, write one concise visual acting instruction using only categories supported by the current shot.
+4. Use only observable descriptions. Avoid abstract words like "sad" without visual evidence.
+5. When character info contains a performance bible, apply long-term physical constraints such as center of gravity and gait only to relevant actions. Use habitual actions, eyeline, and blink rhythm only when the current shot provides evidence.
+6. Do not repeat the full performance bible in each panel; write only the current goal, obstacle, action strategy, and visible action.
+7. The current shot's source_text and description are the evidence ceiling for visible action. Do not infer new hand actions, support actions, scanning, or environmental obstacles from mood, the character profile, or neighboring shots.
+8. Do not carry a one-off action that already ended or was released into later shots unless that later shot's source_text states it again.
+9. Visible action may omit unsupported categories. Do not invent details merely to fill expression, body language, micro-action, or eyeline categories.
+10. A silent character in frame still performs a relationship task: assess the partner, conceal a response, wait for an opening, or protect the situation. A reaction may begin when the key information lands rather than mechanically after the line ends; a difficult reply shows an evidenced assessment or pause before speech. Do not invent a new plot reaction.
+11. If source_text already contains ongoing work, daily business, exertion, impact, or injury, let the tactic travel through that action, breath, and weight. An evidenced interruption can punctuate a beat. Physical load and breathing must continue across the cut rather than resetting immediately.
+12. 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; never make a group turn, nod, blink, or step together.
+13. When readable, keep a still person alive through irregular blinks, brief refocusing, breathing, or a small weight adjustment without loops or distracting business. Hair, hems, loose sleeves, accessories, and props respond only to established wind, acceleration, gravity, or contact with smaller delayed motion, damping, and settling; forbid windless flutter and instant stops.
+14. State the gaze target, screen direction, hold/glance/avert/return behavior, and whether eyes or head initiate the shift. Forbid lens gaze outside explicit POV or direct address. Render psychology as stimulus/information → attention and gaze shift → maintained social mask → brief leak → decision/action → residual exit expression.
+15. Use micro-expression only in a readable close shot, limiting it to one or two facial regions with low-amplitude onset—apex—release. At wider scales use head, breath, posture, pause, distance, and blocking; never emit AU codes or substitute an emotion label for action.
+
+Output format (JSON array only):
+[
+  {
+    "panel_number": 1,
+    "characters": [
+      {
+        "name": "Character Name",
+        "acting": "Goal: calm the trainee; Obstacle: the alarm is escalating; Strategy: reduce visible urgency while taking control; Visible action: lower the shoulders, hold the gaze on the signal, and speak without raising the voice"
+      }
+    ]
+  }
+]
+
+Strict constraints:
+1. Return JSON only, no markdown.
+2. Array length must equal {panel_count}.
+3. Each character object must contain only "name" and "acting". Acting must use exactly: "Goal: ...; Obstacle: ...; Strategy: ...; Visible action: ...".
+4. Keep character names exactly consistent with panel input.
+5. Every visible character's action must express a speaking, listening, or relationship task; never leave them neutral until a line ends and then switch them on mechanically.
+6. ⚠️ 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.
+7. 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_acting_direction.zh.txt

@@ -0,0 +1,79 @@
+# Codex 执行合同：agent_acting_direction
+
+本文件由所属 Skill 读取，用于约束 Codex 的输入、判断与输出；不是发送给外部文本模型的 system prompt。花括号字段是从当前项目已选资产组装的具名输入槽。
+
+执行职责：经验丰富的表演指导(Acting Director)。你的任务是为一组分镜中的**每个镜头**设计角色的表演细节。
+
+【核心职责】
+
+分析整组分镜后，为每个镜头中的角色用一句话描述当前镜头有证据支持的表演指令。
+
+【重要】每个镜头的表演必须是独立的！
+- 将 narrative_purpose、shot_group、motion_plan、scene_strategy、rhythm_plan、edit_plan、dialogue_plan、visual_plan 视为已确认导演合同：表演必须把主体从 start_state 推进到 end_state，服从场级视点、节奏强度和组内 role；对白镜头按 mode/focus 安排说话、聆听与关系反应，camera_role=hold 时保留有意停顿，不得强加动作或改写合同字段。
+- 表演必须服从构图合同：当输入分镜含 visual_plan.composition 或上游 composition_contract 时，可见动作必须服从其 read_order（由承担首要可读信息的角色主导画面事件）、eyeline_room（视线方向与留白，表演不得侵入留白区或让视线反向）、隔离/遮挡安排（被遮挡、虚焦或处于次要信息层的角色不抢戏、不做大幅动作）和 action_vector（动作与进出画的屏幕方向、蓄力—接触点—结果时序），并在镜尾落到 tail_state。表演不得反向要求更改构图、轴线或画面元素；acting 文本仍只写目标、障碍、策略和可见动作，不新增任何视觉字段，也不输出构图 code。
+- 同一角色在不同镜头可能有不同情绪变化
+- 表演风格匹配 scene_type（日常/情感/动作/史诗/悬疑）
+- 角色信息若含表演主档案，只把重心、步态等长期身体约束用于相关动作；习惯动作、视线和眨眼节奏仅在当前镜头有证据时使用
+- 逐镜不得复述整份主档案；acting 只写当前目标、障碍、动作策略和可见动作
+- 当前镜头的 source_text 和 description 是动作证据上限；不得从情绪、角色档案或相邻镜头推导新的手部动作、支撑动作、扫视或环境障碍
+- 已经结束或释放的一次性动作不得带入后续镜头，除非后续镜头的 source_text 再次明确该动作
+- 可见动作可以只包含当前有证据的类别；不得为了凑齐表情、肢体、微动作或视线而补写
+- 沉默但在画内的角色仍需执行当前关系任务：判断对方、隐藏反应、等待开口或维持局面。反应可在听懂关键信息时开始，不必机械等到整句结束；困难回答先有可见的判断或停顿，再开口。仅在台词与镜头时长支持时使用，不添加新的剧情反应。
+- 若 source_text 已有持续工作、生活动作或体力状态，让策略通过该动作、呼吸和重心表现；动作突然停止可作为节拍重音。刚奔跑、受击或用力后的呼吸与身体负荷必须连续，不能立刻恢复平稳。
+- 为每个可见人物明确主要动作、注意对象、反应触发和未参与时状态；除剧情要求同步外，错开多人起势、动作幅度、视线和反应延迟，禁止群体同时转头、点头、眨眼或迈步。
+- 静止人物在景别可读时以不规则眨眼、短暂重新聚焦、呼吸或小幅重心调整维持生命感，不机械循环、不抢主动作。头发、衣摆、宽袖、饰物和道具只响应已有风、加速度、重力或接触，并以较小幅度延迟、衰减、稳定；禁止无风飘动或瞬停。
+- 眼神戏写清注视对象、画面方向、持续/扫视/回避/返回以及眼睛或头部谁先启动；非主观镜头或明确直视观众时不得看镜头。心理变化按“刺激/信息 → 眼神与注意转移 → 维持面具 → 短暂泄露 → 决定/动作 → 残留”落成可见节拍。
+- 微表情仅用于可读的近景或特写，一次限一至两个面部区域并包含低幅起势—峰值—释放；中远景改用头部、呼吸、姿态、停顿、距离和走位，不输出 AU 编码或把情绪标签当动作。
+
+{storyboard_scene_types}
+
+【表演风格匹配 scene_type】
+
+{storyboard_scene_acting_styles}
+
+【表演描述词库】
+
+{performance_visual_vocabulary}
+
+【⚠️ 禁止规则】
+
+1. 禁止抽象情绪词：悲伤、愤怒、紧张 → 改用可见表现
+2. 禁止身份称呼：母亲、父亲 → 改用角色名
+
+【输出格式】
+
+返回JSON数组，每个镜头一个对象，每个角色只有 name + acting 两个字段。示例只演示结构，可见动作仍须由当前镜头证据决定：
+
+[
+  {
+    "panel_number": 1,
+    "characters": [
+      {
+        "name": "角色名",
+        "acting": "目标：让对方继续说；障碍：对方正在犹豫；策略：保持倾听并留出回应空间；可见动作：视线停在说话者身上"
+      }
+    ]
+  }
+]
+
+【输入数据】
+
+分镜数据（共 {panel_count} 个镜头）：
+{panels_json}
+
+角色信息：
+{characters_info}
+
+【严格要求】
+
+1. 只返回JSON数组，不要有markdown代码块标记
+2. 数组长度必须等于输入的镜头数量（{panel_count}个）
+3. 每个角色只有 name 和 acting 两个字段
+4. acting 必须严格使用「目标：…；障碍：…；策略：…；可见动作：…」格式；可见动作只写当前镜头有证据的项目
+5. 角色名必须与输入分镜中的 characters 完全一致
+6. 所有描述必须是可视化的，禁止抽象情绪词
+7. 根据 scene_type 调整表演风格
+8. 情绪弧线连贯，前后镜头有合理递进
+9. 每个画内角色的可见动作都必须体现其说话、倾听或关系任务；禁止写成等待台词结束后才突然启动的机械反应
+10. ⚠️ JSON安全：所有引号（""''等）在 JSON 字符串值中必须统一替换为「」，严禁出现未转义的英文双引号 "
+11. 这是补丁阶段：必须逐项原样回传输入的 panel_number，禁止新增、删除、重复或重排镜头

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

@@ -0,0 +1,101 @@
+# Codex execution contract: agent_cinematographer
+
+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: cinematography planner.
+For each panel, generate a concise photography rule package.
+Treat `narrative_purpose`, `shot_group`, `motion_plan`, `scene_strategy`, `rhythm_plan`, `edit_plan`, `dialogue_plan`, and `visual_plan` as the approved director contract. Make framing, focus, coverage progression, and camera behavior serve the scene viewpoint, intensity, visual emphasis, group role, and start/end states. Preserve axis, screen direction, and cut motivation. Do not rewrite the contract or replace subject action with unmotivated camera movement.
+Give each shot one primary readable fact and establish hierarchy through scale, placement, occlusion, light, color, or focus. Prefer depth layers and tonal/color contrast over reflexively using an extremely shallow plane. Every key, practical, or rim source must be motivated by the location, time, or approved visual contract; never add arbitrary rim light, neon, or colored smoke merely to look cinematic.
+visual_plan.composition is the approved composition contract: composition_contract.primary and .secondary must echo the input codes exactly (null when there is no secondary). Never replace, add, or rename a code; when the contract is supplied cinematography neither may nor needs to choose codes — it only translates the supplied codes into visible geometry. When scene-level composition_motifs are present in the input, light/color geometry, direction, and tail handling must serve their variation and payoff.
+
+[CONTROLLED COMPOSITION VOCABULARY]
+{cinematography_vocabulary}
+The full pattern cards (frame structure, evidence floors, combinable patterns, risks, vertical-screen notes) live in references/director-composition.md; risk codes are defined in its section 0.4.
+
+Inputs:
+- Panel count: {panel_count}
+- Panels JSON:
+{panels_json}
+- Location context:
+{locations_description}
+- Character context:
+{characters_info}
+- Prop context:
+{props_description}
+
+[PROJECT VISUAL BIBLE — independent from art style, must be followed]
+{visual_bible}
+
+[COMPOSITION CONTRACT]
+composition_contract translates the composition codes into visible photographic results. Every panel must contain all 11 fields; never merely echo a pattern name or fall back on abstract adjectives:
+- primary, secondary: echo the controlled codes from visual_plan.composition exactly; secondary is null when there is no second information layer; never reselect codes
+- read_order: what the viewer reads first and second (whose decision / which action or prop / which relationship); the first item must equal narrative_purpose's primary readable fact
+- subject_placement: every visible character's horizontal placement (left/center/right), depth layer (foreground/midground/background), and camera-height relation (low/eye-level/high), consistent with characters.screen_position
+- depth_layers: what occupies foreground, midground, and background, how sharpness and brightness are distributed, and how depth holds in a vertical frame
+- eyeline_room: each eyeline direction, negative-space direction and rough share, and how it continues the axis and screen direction of neighboring shots
+- light_and_color_geometry: key direction and its in-story source, color temperature and color-block zones, how light and dark guide the eye to the primary fact
+- action_vector: screen direction of movement, entrances/exits, facing, and the anticipation-contact-result path; null for a non-action shot; never invent momentum
+- tail_state: position, facing, and residual tension of the characters at the held end frame (where the shot lands), consistent with motion_plan.end_state
+- evidence: inherit the upstream composition evidence and realize it here: confirm each required evidence level (composition-only/set_dressing/weather_atmosphere/action_blocking; compound levels joined with +, every component confirmed), citing the actual source_text, scene/prop asset, or action fact used; if any level is unsupported, flag the blocker in technical_notes instead of swapping codes
+- ai_risks: when secondary is non-null this must cover the union of risks registered for the primary and the secondary pattern, plus any risk codes from the section 0.4 table genuinely relevant to this panel; each risk gets a visible countermeasure in the geometry fields (occlusion under one third with both eyes readable, empty zones kept clean, clear contact point, 10% margin at motion edges, direction continuous with neighbors, locked-off to prevent autonomous camera drift)
+- Missing input (legacy panels): when the input panel has no visual_plan.composition, never demand an upstream backfill. Follow the per-shot selection flow in references/director-composition.md: select primary and secondary yourself (null when there is no genuine second layer) from this panel's source_text, scene/prop assets, and action facts, and state every source with its evidence level in evidence; if the available evidence supports none of the controlled codes, never fabricate a code or force an unsupported downgrade: set primary to null, flag composition blocked with the missing evidence in technical_notes, and still fill the remaining geometry fields from the panel's primary readable fact instead of stalling or refusing the panel
+
+Output format (JSON array only):
+[
+  {
+    "panel_number": 1,
+    "scene_summary": "short scene and time summary",
+    "composition": "framing, subject layout, and visual center",
+    "field_of_view": "visible horizontal or diagonal field of view",
+    "camera_distance": "observable camera-to-subject distance",
+    "optical_result": "visible perspective compression, focus plane, and background separation",
+    "lighting": {
+      "direction": "screen-relative key-light direction",
+      "quality": "soft or hard light quality"
+    },
+    "characters": [
+      {
+        "name": "character name",
+        "screen_position": "left, center, or right placement",
+        "posture": "specific pose or action",
+        "facing": "screen-relative facing direction"
+      }
+    ],
+    "depth_of_field": "visible focus plane and foreground/background separation",
+    "color_tone": "dominant palette and color treatment",
+    "atmosphere": "visual mood",
+    "composition_contract": {
+      "primary": "composition.character.two_shot_standoff",
+      "secondary": null,
+      "read_order": "first Character A's pressing advance, then Character B's unbroken gaze",
+      "subject_placement": "Character A at left midground, Character B at right midground, eye-level camera, both on one focus plane",
+      "depth_layers": "empty foreground to avoid occlusion; the two characters in the midground; a darkened room depth behind with one readable exit",
+      "eyeline_room": "A looks right and B looks left, eyelines meeting at frame center; about 10% outer margin each; axis continuous with the previous shot",
+      "light_and_color_geometry": "key from front-right in one color temperature, faces lit evenly; darkened background locks attention on the midground pair",
+      "action_vector": "no entrances or exits; Character A presses a half-step toward Character B, screen direction toward screen right, stopping within the gap between them without physical contact",
+      "tail_state": "the pair hold the gaze and distance, A's half-step settled, tension unresolved before the confrontation",
+      "evidence": "primary and secondary=null are composition-only: the confrontational dialogue in source_text supports the two-person will clash; no dressing, weather, or group action added",
+      "ai_risks": ["eyeline_or_axis_break"]
+    },
+    "technical_notes": "continuity, axis, focus, or exposure notes; countermeasure: eyelines must meet and never cross the axis relative to neighboring shots"
+  }
+]
+
+Rules:
+1. Return exactly {panel_count} items.
+2. Keep continuity across neighboring panels.
+3. Adapt to scene_type and story rhythm.
+4. Every item must include every field shown in the schema, even when a value is an empty string or array. composition_contract must include all 11 subfields primary, secondary, read_order, subject_placement, depth_layers, eyeline_room, light_and_color_geometry, action_vector, tail_state, evidence, and ai_risks; primary/secondary must echo the input visual_plan.composition codes exactly, never reselected and never reduced to a name restatement; for legacy panels whose input lacks visual_plan.composition, follow the Missing input rule in the contract section: select codes yourself with sourced evidence, or set primary=null and flag composition blocked in technical_notes, without requiring an upstream backfill.
+5. Describe field_of_view, camera_distance, and optical_result as visible outcomes first. Put focal length, T-stop, sensor, and other equipment parameters only in technical_notes.
+6. Shot scale does not automatically determine depth of field. Choose the focus plane and separation from narrative_purpose and dialogue_plan: speaker/clean-single may isolate the speaker; listener may focus the listener; relation/two-shot keeps the relationship readable; over-shoulder may soften the foreground shoulder without hiding a key reaction.
+7. Use a rack focus only when information or power visibly transfers between subjects; state the initial focus, trigger, and final focus. Otherwise lock the intended focus plane from first frame to last and forbid autofocus hunting.
+8. Solve lip-sync risk by identifying the sole speaker and every visible mouth state, not by automatically blurring every listener. Keep multiple faces clear when the relationship or reaction is the point.
+9. Use focal length or T-stop only when it explains a visible result. Preserve natural straight lines and human proportions unless wide-angle distortion, fisheye, or exaggerated perspective has an explicit narrative purpose.
+10. Give each shot one primary visual fact. Motivate light sources and prefer foreground/midground/background, tonal, or color relationships for spatial separation.
+11. If characters already carry `slot`, treat it as a preferred placement anchor, not an absolute boundary.
+12. When a panel is about movement, entry/exit, path traversal, transition space, temporary space, empty space, imagination, dream, memory, or abstract/non-literal space, composition and placement may deviate from a static slot if the shot logic requires it.
+13. Treat `slot` as one full placement phrase from the location context, not as a short token, whenever you reference it.
+14. Do not shorten, rewrite, summarize, or replace a provided `slot` phrase with a short token.
+15. JSON only, no markdown.
+16. ⚠️ 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.
+17. This is a patch phase: echo every input panel_number in the same order; never add, remove, duplicate, or reorder panels.