@aswless_854771076/ai_short_studio_cli 0.1.97 → 0.1.99

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/starrouter-provider.md

@@ -0,0 +1,53 @@
+# StarRouter Provider 合同
+
+短剧插件的新制作统一使用 Hypit Runtime 的 StarRouter 配置与 Credential Store；以下适配器细节保留作兼容实现说明，不应单独配置另一套厂商路由。
+
+插件通过独立适配器直接访问 StarRouter，不导入任何业务应用代码：
+
+- 图片：`/v1/images/generations`；有本地参考图时使用 multipart `/v1/images/edits`。支持 `1K/2K/4K + aspect_ratio` 尺寸推导和常用输出参数。
+- 视频：Seedance 使用 `/volcengine/doubao/contents/generations/tasks`；MiniMax H3/H3-Max 使用 OpenAI 兼容 `/v1/videos`，并通过 `/v1/videos/{task_id}` 查询。适配器按模型选择协议。
+- 语音：同步 `POST /v1/audio/speech`，支持 `speech-2.8-hd`、`speech-2.8-turbo`、Qwen3 TTS、PawSense 与 `tts-1`；通用模型的 `instructions` 和 `metadata` 原样转发，当前 MCP 不缓冲 SSE 流式结果。
+- 语音识别：同步 multipart `POST /v1/audio/transcriptions` 或 `/v1/audio/translations`；默认模型为 `qwen3-asr-flash`、`whisper-1`。词级或分段时间戳必须使用 `response_format=verbose_json`，`timestamp_granularities` 只接受 `word|segment` 并按 multipart 同名重复字段发送；未知粒度和其他响应格式在请求前拒绝。
+- 音乐：`POST /suno/submit/MUSIC` 提交 `suno_music`，`GET /suno/fetch/{task_id}` 轮询；生成结果作为 audio 资产保存。
+- 认证：优先使用 Hypit Runtime 指定的 Credential Store；旧适配器仍支持从 `STARROUTER_API_KEY` 读取 Bearer Token。
+- 保底目录：图片 `gpt-image-2`，视频为适配器登记的 Seedance 系列及 `MiniMax-H3`、`MiniMax-H3-Max`，语音和 ASR 为上述模型，音乐为 `suno_music`。可分别用 `STARROUTER_IMAGE_MODELS`、`STARROUTER_VIDEO_MODELS`、`STARROUTER_AUDIO_MODELS`、`STARROUTER_ASR_MODELS`、`STARROUTER_MUSIC_MODELS` 和 `STARROUTER_MULTIMODAL_VIDEO_MODELS` 提供逗号分隔目录；自定义模型仍需补能力合同。
+
+## Suno 音乐合同
+
+`generate_music` 使用项目路由模型 `suno_music` 和非空 `prompt`，可选 `title`、`tags`、`lyrics` 与 `make_instrumental`。StarRouter 当前不读取请求体的 `model`，由 `/MUSIC` 路径映射计费模型；无歌词时把音乐方向提交为上游 `gpt_description_prompt`，有自定义歌词时只把批准歌词提交为上游 `prompt`，音乐方向仍保存在本地创作合同并以 `tags` 辅助上游。纯音乐不能同时提供歌词。远端 task id 在本地加 `music:` 路由前缀，查询时移除前缀；只提取音乐响应中的音频 URL，避免把封面或 MV 视频误登记为音频。
+
+## MiniMax H3/H3-Max 视频合同
+
+两者固定使用 `prompt_profile=h3`，输入模式枚举为 `T2VA`、`I2VA`、`FL2VA`、`L2VA`、`Ref2VA`，画幅为 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。`MiniMax-H3` 支持 `768P/2K`、4–15 秒及参考图/视频/音频；`MiniMax-H3-Max` 支持 `480P/768P`、5–15 秒，不接受参考素材或 Ref2VA。
+
+`images` 最多两张，依次是 `first_frame`、`last_frame`；`input_reference` 仅在 `images` 为空时作为首帧。参考内容使用 `metadata.content`，元素类型只能是 `text`、`image_url`、`video_url`、`audio_url`，素材角色只能是 `first_frame`、`last_frame`、`reference_image`、`reference_video`、`reference_audio`。每个请求至少含一个非空 text；Hypit Runtime 的 Ref2VA 可把一个 `first_frame` 连续性锚点与完整参考素材同时提交。
+
+`metadata` 仅接受 `model`、`content`、`resolution`、`duration`、`ratio`、`callback_url`；适配器要求 `metadata.model` 与顶层模型一致，回调地址和所有素材必须是公网 HTTPS。公开任务状态 `queued/in_progress/completed/failed` 被统一归一化为 pending/completed/failed，完成地址从响应（包括 `metadata.url`）提取。
+
+## 同步语音合同
+
+`generate_audio` 对 StarRouter 使用 `model`、`input`、`voice`，可选 `instructions`、`speed`、`response_format` 和 `metadata`。`voice` 必须是用户已确认且有权使用的模型声音 ID；`speed` 为 0.5–2；格式支持 `mp3`、`pcm`、`flac`。
+
+`speech-2.8-*` 继续严格校验 MiniMax 的 `voice_setting`、`audio_setting`、`pronunciation_dict`、`timbre_weights`、`language_boost`、`voice_modify`、`subtitle_enable`、`aigc_watermark`、`output_format`、`stream`、`stream_options`。其余 OpenAI 兼容模型原样转发 `instructions` 与 metadata。当前 MCP 返回完整文件，明确拒绝 `stream_format`，避免把 SSE 事件流误登记成音频。
+
+上述字段透传能力不等于完整情感配音合同能力。当前已验证的 MiniMax `speech-2.8-*` 只能表达单一情绪枚举和部分声学参数，不能可靠承载意图、潜台词、情绪强度、重音、停连、呼吸及空间关系；`tts-1` 不支持 `instructions`。因此二者在 `compile_dubbing_request` 中都对完整逐句表演合同失败关闭，不会静默降级。旧 CosyVoice 与 RunningHub 工作流不能用于新制作；若当前 StarRouter 能力无法满足完整合同，应明确阻塞。
+
+`emotion` 与 `language_boost` 按非空字符串透传：Skill 只列已验证常用值，不把上游可能扩展的值固化为封闭枚举；范围错误由 StarRouter/MiniMax 返回。
+
+StarRouter 返回的二进制音频会统一转为 `outputs[0].b64_json` 数据 URI，并保留 `media_type=audio`、Content-Type 和格式。立即用 `asset-ledger.mjs decode` 保存到 `assets/audio/<asset-key>/v001.<ext>`；项目账本只保存生成来源和参数，不保存 Key。
+
+附件同时描述了异步 `/v1/t2a_async_v2`，但其最终产物是 TAR 而非可直接剪辑的音频文件。本插件当前不把 TAR 暴露为音频资产；需要长文本异步合成时，应先增加安全解包、逐文件校验和音频版本登记，再开放该模式。
+
+## 本地资产约束
+
+所有生成工具要求 `confirmed: true`。本地参考文件必须已落入当前项目 `assets/`，插件会在请求前通过真实路径校验，拒绝项目外文件和符号链接逃逸。视频公网参考只接受已授权的 HTTPS 地址；仅当用户另外调用 `publish-drama-references` 并确认第三方公开上传时，插件才会把本地选版图片临时发布到 TempFile.org，生成调用本身不会隐式发布。
+
+Seedance 2.0 视频必须同时提交 `prompt_profile=seedance2`、`input_mode`、本地 `prompt_version` 和 `reference_manifest`。清单按图片、视频、音频各自从 1 连续编号，并与 URL 数组及提示词中的 `@图片N/@视频N/@音频N` 同序；适配器在付费请求前校验 4–15 秒目标时长、图片最多 9 个、视频最多 3 个、音频最多 3 个、总参考最多 12 个、音视频参考总时长、用途和真实人物脸部禁用声明。
+
+图片、视频或语音结果统一返回 `outputs[]`；每项包含 `media_type` 以及 `url` 或 `b64_json`。立即用 `asset-ledger.mjs fetch|decode` 下载并登记哈希；远程结果不视为资产，落盘前任务保持未完成。文本资产由 Codex 直接创作，不经过本适配器。
+
+图片生成始终提交 `reference_manifest`；无参考图时为 `[]`，有参考图时必须与 `reference_paths` 等长，并按顺序记录 `type=image`、资产 key、selected 版本和用途。该清单只进入本地请求快照和 provenance，不发送给 StarRouter。
+
+## 扩展规则
+
+新制作的厂商与模型选择以 Hypit Runtime 为准；旧适配器注册表只用于保留兼容代码和历史证据读取，不能绕过 Runtime 审批门禁。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/build-drama-storyboard.md

@@ -0,0 +1,13 @@
+# 构建分镜
+
+先核对源剧本语言、交付语言、人物说话语言和字幕语言，并从已选 Provider/制作计划取得 `shot_duration_constraints`。由 Codex 使用本 Skill 的 `../../assets/modules/build-drama-storyboard/prompts/agent_storyboard_plan.{zh,en}.txt` 生成严格 JSON；需要整集合同输出时，向 `professional_storyboard` 显式传入 screenplay_contract、asset_whitelist、cinema_knowledge、production_constraints、correction 和 target_language。新生成分镜必须依次执行 `agent_cinematographer`、`agent_acting_direction` 与 `agent_storyboard_detail`，不得把表演、眼神、自然运动和声音证据留到最终视频提示词阶段才临时补写；只有读取旧项目且不重制分镜时允许保留历史薄合同。
+
+分镜初稿开始前必须读取每个在场角色的 `performance_bible`，但不能把长期档案机械复制到每镜。初稿先确定每个可见角色的主要动作、注意对象、反应触发和未参与时状态；表演指导再把有证据的重心、步态、视线、眨眼节奏、压力反应与习惯触发编译为逐镜可见节拍；分镜细化最后核对多人起势与反应延迟不齐步、头发衣摆等次级运动有物理原因、眼神与微表情符合景别、动作声有 `visible_event_keys`。任一步缺少来源证据都应删去该细节或阻塞，不得靠“自然一点”“电影感”补全。
+
+
+分镜选定且制作计划完成后，必须交给 `plan-shot-continuity` 建立独立的 `camera_setup_id`、`start_state`、`end_state` 和 `transition_link` 合同，再进入视频提示词编译。分镜只描述本镜事实，不得提前伪造上一镜尾帧资产或用模糊的“保持连续”代替状态字段。分镜选定后，若后续 `plan-drama-production` 或 `write-drama-video-prompts` 因缺构图证据、素材缺口或镜头需要拆并而产生 `unresolved`，必须退回 `revise-drama-storyboards` 生成新的不可变分镜版本，不覆盖旧版，再重新走制作计划与视频提示词。
+
+分镜必须是可拍摄的原子单元：一镜只允许一个时间地点、一个连续摄影机动作和一条主要因果动作链；不得把蒙太奇、平行剪辑、多个地点或互不依赖的动作塞进同一 panel。若剧作需要多个动作，拆成连续 panel，并为每个 panel 写清入点、动作完成点、出点、轴线、视线、道具接触和下一镜承接证据。生成前后都要检查人物数量、关键道具状态和屏幕/文字禁绘约束，不能用后期字幕替代缺失的画面因果。
+
+
+三名以上具名人物同框时先设计可读覆盖：锁定人数、左右顺序、朝向、前后层次和每人的说话/倾听任务；同一时刻只让能清楚归属的角色承担主要说话或道具交互，其余角色用有任务的关系反应维持在场。若一个镜头同时要求群体全貌、两人表演、手部细节和复杂交互，按叙事重心拆为关系镜、动作/插入镜与反应镜，不把所有信息塞进一次生成。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/design-fight-video.md

@@ -0,0 +1,19 @@
+# 设计打斗视频
+
+用于当前分集存在近身冲突、兵器对抗、追逐或能力战时。读取已选剧本、导演本、人物/道具/场景资产与制作约束，输出一份可被 `build-drama-storyboard` 消费的 `fight_design` 对象，建议随制作计划一并保存为不可变版本。
+
+先锁定不可被参考资料覆盖的事实：角色、武器、能力、动作顺序、胜负、时长、画幅、结尾和权利范围。参考资料只用于补充通用机制；零命中时按原创处理，不强行套案例。
+
+每个关键动作必须写成：目的 → 起势/身体路径 → 对手响应 → 接触或落空 → 受力反馈 → 位移/状态结果 → 下一动作条件。每个空间阶段必须写起点、转向点、终点、观察轴和环境反馈；上一段末态必须成为下一段起点。一打多不得排队，终结必须来自前文形成的破绽。
+
+动作与技能分开：能落到兵器、身体路径、接触结果或连续动作链的内容归入动作；只有具备独立“前置 → 发动 → 作用 → 终止”机制、且无法具体化为动作链的内容才归入能力。选用能力前必须检查法器、身体部位、介质和状态条件。
+
+输出至少包含：`locked_facts`、`conflict_arc`、`character_signatures`、`action_beats`、`spatial_route`、`shot_plan`、`continuity_constraints`、`unresolved`、`approved`。`shot_plan` 每项包含 `shot_number`、`duration_seconds`、`narrative_purpose`、`camera`、`positions`、`action`、`handoff`；不得用模型平台语法、负面词、字幕或声音指令替代动作事实。
+
+保存前运行：
+
+```bash
+node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/validate-fight-plan.mjs" <fight_design.json>
+```
+
+校验通过后，再将其中的动作事实转译到 `storyboard` 和 `plan-shot-continuity`；不要把 `fight_design` 当成正式视频提示词，也不要跳过逐镜审核。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/direct-blender-previz/action-previz.md

@@ -0,0 +1,39 @@
+# 动作白模编导门禁
+
+仅在镜头含武打、追逐、擒抱、跌倒、兵器或明确身体接触时读取。本文件扩展现有白模导演合同，不另建平行流程。
+
+## 来源门禁
+
+- 正式镜头逐项引用当前 selected 剧本、导演本、结构化分镜和制作计划版本；不得为补足动作自行编写剧情。
+- 独立能力测试必须写 `test_only=true` 和 `source_script=null`，只能评价技术表现，不能评价是否符合项目剧情，也不能选版。
+
+## 动作交换
+
+每次攻防交换都要在 `direction.beats` 中明确：攻击者、目标、起势、攻击轨迹、接触帧、接触部位、防守或闪避、受力后的位移/转动、回收与镜尾状态。动作名称不能代替可见姿态。
+
+关键帧必须形成可读的“预备—发力—接触—受力—回收”链条：
+
+- 支撑脚稳定，重心路径与移动方向一致；不得滑步、瞬移或无支撑转身。
+- 发力链不得让脚、胯、胸、肩、肘、腕在同一帧同时启动或停止；按动作方向错开关键帧，并在接触前加速、接触后留出至少 2–4 帧制动与受力反应。
+- 拳掌至少控制肩—肘—腕，踢击至少控制髋—膝—踝；只转上臂不能算完成动作。
+- 接触帧必须有明确接触点，双方肢体不能穿插；受击方随后要有与方向、力度匹配的反应。
+- 擒抱、兵器、跌倒等需要持续约束或 IK 的动作，当前执行器没有相应控制时直接阻断生成，先补足骨架控制或采用已验证的动作重定向方案。
+- 兵器必须绑定持握手骨，持握手使用 `fist` 或与柄形匹配的收拢手型；轨迹由肩—肘—腕—兵器尖端共同形成。接触帧按实际碰撞部位检查兵器 `origin`/`mid`/`tip` 与目标，不能只检查两名演员的手是否靠近。
+- 术法必须具有“结印或蓄力—生成—运动—碰撞/闪避—消散—结果”链条；粒子与辉光只是空间提示，不能替代施法者动作和受力反应。
+- 相机首先保证攻击轨迹、接触点和结果同时可读；除非剧本明确要求主观混乱，不用抖动或快速环绕掩盖动作缺陷。
+- 相机运动必须早于接触点停稳；结果阶段可以轻微回拉或重构图，但不得与攻击者同时抢动势。
+- 动作镜头的相机合同应明确“建立空间—跟随启动—接触锁机—结果释放”四段，并在攻守权转移时把目标点从攻击线交给承受结果的一方；不得始终瞄准双人中点。位移幅度要产生可见视差，但相机全程留在既定轴线同侧。
+
+执行合同使用 `bone_keyframes` 控制完整肢体链，并用 `hand_pose_keyframes` 明确拳、掌或放松手型；每个明确接触点必须写入 `contact_checks`，每个发力段至少给一个支撑脚写入 `plant_checks`。这些数值门禁在渲染前执行，不能用生成后目测代替。
+
+## 生成后审计
+
+完整观看后按白模七维合同评分，并额外逐帧检查每次交换的起势、接触和结果。以下任一情况属于 P1，样片不得选版：
+
+- 缺少真实来源却声称符合剧情；
+- 攻击对象、接触部位或攻防归属不可辨；
+- 滑步、穿插、瞬移、关节反折或受力方向错误；
+- 剧本要求的攻防结果没有在镜尾形成；
+- 当前骨架控制不足却用近似动作冒充完成。
+
+每次只修改一个最可能变量并生成新版本；同类问题连续两版没有改善，就停止盲调，退回导演合同或更换经验证的动作数据/重定向工具链。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/direct-blender-previz/direction-contract.md

@@ -0,0 +1,96 @@
+# 白模导演合同与评分
+
+## 合同结构
+
+JSON 顶层同时保存编导依据和 Blender 可执行场景：
+
+```json
+{
+  "schema_version": 1,
+  "source": {
+    "episode_key": "ep-001",
+    "storyboard_version": "v001",
+    "production_plan_version": "v001",
+    "shot_number": 1,
+    "storyboard_medium": "blender",
+    "board_asset": null
+  },
+  "direction": {
+    "dramatic_intent": "本镜造成的关系或信息变化",
+    "primary_read": "观众第一眼必须读到的唯一信息",
+    "axis": {
+      "line": "轴线两端或运动方向",
+      "camera_side": "相机保持在哪一侧",
+      "screen_direction": "人物和动作的屏幕方向"
+    },
+    "beats": [
+      {"name": "发现", "start_frame": 1, "end_frame": 12, "actor": "人物A", "action": "转头看向目标", "result": "目标被建立"}
+    ],
+    "camera": {
+      "shot_size": "medium-wide",
+      "lens_mm": 48,
+      "principal_move": "slow_track_then_settle",
+      "motivation": "跟随行动并在阻断点转移注意",
+      "stop_frame": 80
+    },
+    "continuity": {
+      "entry_exit": "人物从画面右侧进入",
+      "eyelines": "人物A与人物B先看目标，再看人物C",
+      "end_state": "人物C完成阻挡，目标仍可见"
+    }
+  },
+  "review_contract": {
+    "hard_gates": ["剧情因果", "人数与身份", "轴线与屏幕方向", "物理接触", "关键物可见"],
+    "score_target": 85
+  },
+  "fps": 24,
+  "duration_seconds": 5,
+  "resolution": [640, 360],
+  "cameras": [
+    {"name": "建立镜头", "location": [0, -10, 3], "target": [0, 1, 1.2], "lens": 48, "keyframes": []},
+    {"name": "人物A正打", "location": [2, -6, 2.2], "target": [-1, 0, 1.5], "lens": 62, "keyframes": []},
+    {"name": "人物B反打", "location": [-2, -6, 2.2], "target": [1, 0, 1.5], "lens": 62, "keyframes": []}
+  ],
+  "camera_cuts": [{"frame": 1, "camera": "建立镜头"}, {"frame": 25, "camera": "人物A正打"}, {"frame": 49, "camera": "人物B反打"}],
+  "objects": []
+}
+```
+
+人物对象可使用：
+
+- `heading_degrees`：初始朝向。
+- `keyframes[].location/rotation_degrees/scale`：身体调度和视线转向。
+- `head_keyframes[].rotation_degrees`：先由头部建立视线，身体随后跟随，避免用整个人体旋转冒充反应。
+- `walk={start_frame,end_frame,step_frames,swing_degrees,phase_offset}`：位移期间的落脚节奏；同行人物用 `phase_offset=0|1` 错开半拍。
+- `walk` 会让普通左右臂与腿反相摆动；`pose=block` 的阻挡臂仍由导演关键帧控制，避免步态覆盖表演动作。
+- `pose=block`、`arm_rotation_degrees`、`arm_keyframes`：阻挡手臂从垂下到伸出的关节动画。
+- `bone_keyframes[].rotations`：以 UE Mannequin 默认导入姿态为基准，按逻辑骨骼名填写 XYZ 旋转偏移，控制骨盆、脊柱、锁骨、上臂、前臂、手、大腿、小腿和足；武打优先使用它表达完整肢体链，旧 `arm_keyframes` 只用于简单阻挡兼容。不得把 Blender 骨骼本地绝对欧拉角直接写入合同。
+- `hand_pose_keyframes[]`：按帧分别设置左右手为 `open`、`relaxed` 或 `fist`；武打默认用 `fist` 或 `relaxed`，不得让默认张开的手指冒充拳或护手。
+- `color=[r,g,b]`：多人身份难辨时使用稳定的中性灰阶或低饱和色，不能随镜头变化。
+- `shape=weapon`：`weapon_type` 支持 `sword`、`dao`、`spear`、`staff`、`shield`；用 `attach_to={object,bone,location,rotation_degrees}` 绑定人物左右手骨。武器局部 Z 轴由握柄指向尖端。
+- `shape=effect`：`effect_type` 支持 `orb`、`beam`、`ring`、`burst`；使用普通 `keyframes` 控制位移、旋转和缩放，使用 `color` 与 `emission` 区分术法归属。
+
+单机位摄影使用 `camera`；正反打、多机位覆盖使用具名 `cameras[]` 和从第 1 帧开始的 `camera_cuts[]`。每个摄影机的 `keyframes[]` 可分别设置 `location`、`target` 和可选 `lens`。正反打机位必须位于同一轴线侧，匹配相邻镜头的视线方向、头部留白和景别尺度；接触或命中优先回到能同时说明双方空间关系的机位。默认保持固定焦段；只有叙事需要透视变化时才给 `lens` 做关键帧。
+
+双分镜板的版本与审核由项目账本独立校验，不复制进白模合同；因此白模模式保持 `board_asset=null`，`source.storyboard_version` 绑定同镜结构化分镜。生成的白模资产 provenance 必须在 `parameters.direction_contract` 记录本合同的项目内相对路径，在 `parameters.direction_contract_sha256` 记录合同文件 SHA-256，并用 `parameters.duration` 记录制作计划时长。门禁会重新探测 MP4 的实际时长、平均帧率、帧数和分辨率，同时复核合同与媒体哈希，声明值不能替代实际媒体证据。
+
+`beats` 必须按时间顺序排列；相邻节拍可共享一个边界帧或首尾相接，但不得倒序、被前一节拍完全覆盖或大段重叠。`review_contract.hard_gates` 至少完整包含示例中的五项固定硬门禁，不得用模糊名称删减。
+
+`purpose=motion-reference` 时，合同 `duration_seconds` 必须与制作计划该镜 `duration_seconds` 完全一致；`beats`、人物与相机关键帧均不得超出该范围，并应覆盖镜尾停稳。白模、合同或登记 provenance 任一时长不一致，都不得选版或提交正式视频。当前只允许 StarRouter `MiniMax-H3`，经 Runtime 的 TempFile.org 临时发布本地资产；视频提示词必须把当前 selected 白模登记为 `type=video, role=reference_video` 的执行期派生引用，该引用不回写制作计划 `reference_assets`。
+
+武打合同还应提供 `contact_checks[]`，用双方人物逻辑骨骼或对象的 `origin`/`mid`/`tip`、接触帧和 `max_distance` 在渲染前验证接触距离；提供 `plant_checks[]`，用人物、左右足、帧段和 `max_drift` 验证支撑脚没有明显滑动。检查失败时生成器直接停止，不输出可选版视频。
+
+## 评分
+
+总分 100：
+
+- 剧情因果与节拍 20：发现、反应、行动、结果顺序清楚。
+- 人物调度与表演 15：朝向、视线、落脚、停步和动作归属可信。
+- 相机动机与运动曲线 20：主运动明确，起步、减速和停稳服务剧情。
+- 构图与视觉层级 15：首要信息突出，关键人物和道具不过度遮挡。
+- 空间、轴线与连续性 15：地理、180 度轴线、屏幕方向和镜尾状态成立。
+- 物理与接触 10：手、道具、目标的入点—接触—完成态可读。
+- 技术交付 5：时长、帧率、画幅、编码和安全区正确。
+
+任一硬门禁失败都不得用总分抵消。审核记录的 `hard_gates[]` 必须与导演合同同序，每项写入 `{gate,status,frame,observation}`，以实际帧证据决定 passed/failed。对白或对峙镜头还要检查对白对象关系是否可辨；剧本指定的镜尾反应必须由实际入画人物完成。评分只基于完整视频和逐帧证据，不以 JSON 中写过人物或动作作为完成证明。
+评分结果写入逐镜审核账本，`score.breakdown` 的键和顺序必须与上表一致；总分至少 85，且每项至少取得该项满分的 70%。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/direct-blender-previz/weapons-vfx.md

@@ -0,0 +1,23 @@
+# 武器、灰模与术法预设
+
+只在镜头确有兵器、关键道具或超自然动作时读取。预设服务空间、动作和接触验证，不追求最终美术质量。
+
+## 选择顺序
+
+- 普通场景物：门、墙、桌、台阶、箱体优先组合 `cube`；柱、瓶、树干优先 `cylinder`；球形关键物优先 `sphere`。只在轮廓会改变调度或遮挡判断时增加细节。
+- 常见兵器：直剑用 `sword`，单刃挥砍用 `dao`，长距离突刺用 `spear`，无刃长兵器用 `staff`，防御面积验证用 `shield`。不要用不同名称复制同一几何体。
+- 修仙术法：蓄力/飞行物用 `orb`，持续直线能量用 `beam`，范围冲击边界用 `ring`，碰撞或破裂瞬间用 `burst`。复杂烟火留给最终 VFX，不在白模阶段堆粒子。
+
+## 编导约束
+
+- 兵器用 `attach_to` 绑定 `left_hand` 或 `right_hand`；持握偏移先在低清预览校准，再锁定合同。双手兵器若没有双手 IK，只能测试单手主控轨迹，合同必须披露该限制。
+- 刀剑挥砍检查尖端弧线和刃侧朝向；枪棍检查杆身是否穿体、前手引导与后手发力；盾检查盾面是否覆盖攻击线。每次真实碰撞写 `contact_checks`，对象端按碰撞位置使用 `point=origin`、`mid` 或 `tip`。
+- 术法至少保留施法者身体动作、特效生成点、可跟踪轨迹、碰撞/闪避点、对方反应和消散。强光不能遮住人物轮廓与接触点；同镜不同阵营使用稳定的冷暖色区分。
+- 发光预设使用 Eevee 发射材质和低质量 Fog Glow，只用于动作可读性。需要烟雾、流体、布料、破碎或精确法术形态时，白模标记能力缺口并移交最终特效流程。
+
+## 审计补充
+
+- 持握：柄与手同动，无明显脱手、穿掌或反向握持。
+- 轨迹：起点、攻击线、接触点、回收方向连续；长兵器不穿过持有者或镜头。
+- 术法：颜色能辨归属，运动方向与施法动作一致，碰撞后有结果，粒子不替代剧情动作。
+- 技术：记录合同生成、首帧/预览、完整渲染和审计耗时；重跑时分别记录，不用累计值冒充单次制作时间。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/direct-blender-previz.md

@@ -0,0 +1,15 @@
+# 编导 Blender 白模预演
+
+只处理制作计划中 `previz_strategy.mode=blender` 的镜头。读取当前 selected 剧本、导演本、结构化分镜、制作计划、人物/场景/道具选版，以及本镜已选且通过八维审计的时间故事版和镜头分镜板；双板始终是前置条件，白模不能替代，也不凭文字单独猜测资产已定义的三维空间。
+
+信息优先级固定：剧本和导演本决定因果与表演先后，结构化分镜决定时间和连续动作，人物/场景/道具选版约束身份与空间；时间故事版锚定动作阶段和状态，镜头分镜板锚定构图与屏幕方向。白模负责验证三维距离、遮挡、接触、节奏和相机路径。冲突时退回上游澄清，不用白模悄悄改剧情。
+
+为每镜确定唯一首要可读信息，再拆成带帧号的发现、反应、行动、介入、接触/阻断、结果和镜尾状态。人物调度必须记录起止位置、朝向、视线、入出画边、前后层次、行走区间和关节动作；多人镜保持身份、左右顺序和动作归属可辨。对白、对峙或攻防接管不能只依赖一个移动主镜头：叙事需要拆开意图与反应时，优先使用建立镜头、正打、反打、双人接触镜头和结果反应镜头。正反打全部保持在同一轴线侧，匹配人物视线、屏幕方向、头部留白和近似景别，切点落在动作启动、视线接管或反应开始处，不在接触瞬间破坏可读性。即使以单人为主体，也必须让对象通过同框、过肩、明确视线或相邻镜头关系可辨；合同写了对象或反应不算完成，必须在实际画面中看见。单个机位只保留一个有叙事动机的主运动，写明起止构图、焦段、机位高度、目标点、加速、减速和停稳帧；关键帧用缓入缓出，接触或揭示前完成减速并留出可读停顿。除非有明确视觉目的，不同时叠加变焦、推拉、横移和环绕。
+
+白模作为正式视频运动参考时，合同 `duration_seconds` 必须与当前制作计划该镜 `duration_seconds` 完全一致，所有节拍和镜尾停稳必须覆盖完整时长；不得用三秒动作摘要替代八秒镜头。若台词尚未配音，也要为说话表演、反应停顿和可剪辑镜尾分配明确帧段。
+
+按 [白模导演合同与评分](direct-blender-previz/direction-contract.md) 输出与 `scripts/blender-previz.py` 兼容的 JSON，保存为 `episodes/<episode-key>/previz/shot-<NNN>-vNNN.json`。合同必须包含当前分镜与制作计划版本、剧情意图、覆盖首帧到镜尾且无空档、无倒序或过度重叠的节拍表、轴线与屏幕方向、相机动机、连续性和验收项；五项固定硬门禁不得删减。单机位使用 `camera`，正反打覆盖使用 `cameras` 与 `camera_cuts`，并配合 `objects`、人物 `walk`、根节点关键帧和 `arm_keyframes`。接触检查声明的帧不得同时作为机位切点；生成前必须通过脚本的合同结构校验，不能用文字约定替代可执行门禁。
+
+镜头含武打、追逐、擒抱、跌倒、兵器或明确身体接触时，还必须读取 [动作白模编导门禁](direct-blender-previz/action-previz.md)。涉及兵器、常用灰模道具或修仙术法时，同时读取 [武器、灰模与术法预设](direct-blender-previz/weapons-vfx.md)。先验证当前骨架控制能否表现所需肢体链、落脚和接触；能力不足就停止并报告缺口，不用直臂、滑步或模型穿插冒充武打。没有真实剧本来源的能力测试必须标记 `test_only`，不得声称符合项目剧情。
+
+交给 `generate-blender-previz` 渲染后完整观看，并在动作入点、接触点、完成点和镜尾逐帧复核。剧情因果、人数与身份、对白对象关系、轴线与屏幕方向、物理接触、关键物可见，以及剧本要求的镜尾反应必须在实际画面中可见；任一失败都不得用合同文字或总分抵消。全部通过、评分达到 85/100 且没有单项低于该项分值的 70% 才可进入正式视频；否则一次只改一个最可能变量并生成新合同、新视频版本。同一问题连续两次未改善就停止盲调，退回结构化分镜或导演本。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/generate-blender-previz.md

@@ -0,0 +1,20 @@
+# 生成 Blender 白模分镜
+
+
+直接执行导演合同中的 JSON 场景。基础灰模使用 `cube`、`cylinder`、`sphere`、`human`；确有叙事需要时使用经过门禁的 `weapon` 与 `effect` 预设，不临时下载来源和授权不明的模型。人物位移区间使用 `walk` 保留落脚节奏，身体调度使用根节点 `rotation_degrees`，视线反应使用 `head_keyframes`，阻挡等关节动作使用 `arm_keyframes`；不在生成阶段重新解释剧情或改变相机动机。人物可以共用白色材质，但同框身份难辨时应使用稳定的色块或标签，不为预演制作精细模型、贴图和毛发。
+
+渲染前读取当前制作计划并核对该镜时长；调用时必须把计划中的 `duration_seconds` 传给 `--expected-duration`，脚本发现合同不一致就停止，不生成可选版视频：
+
+```bash
+"${BLENDER_BIN:-blender}" --background --python "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/blender-previz.py" -- --spec <场景.json> --output <预演.mp4> --blend-output <场景.blend> --expected-duration <制作计划镜头时长>
+```
+
+人物默认使用插件自带的 `public/models/ue-mannequin-retopology.glb`，以便检查肩胯、手脚和关节动作；默认模型缺失时必须停止，不得静默退回程序化简模。只有用户明确指定其他兼容骨架时才传 `--mannequin-model <本地.glb>` 覆盖默认值。模型只用于本地渲染，不登记为项目资产，不上传给视频 Provider。
+
+兵器用 `attach_to` 绑定 UE Mannequin 的 `left_hand` 或 `right_hand`，并以 `contact_checks` 检查 `tip`/`origin` 到对手骨骼或另一件兵器的距离。术法预设只表达发射、轨迹、碰撞和消散，不把辉光或粒子数量当成动作成立；施法者起手、目标反应、冲击点和镜尾结果仍须分别可读。预设字段与适用边界见 `direct-blender-previz/generate-blender-previz/weapons-vfx.md`。
+
+没有 Blender 可执行文件但能安装官方 `bpy` Python 包时，可用 `uv run --python 3.11 --with bpy python <插件目录>/scripts/blender-previz.py ...` 验证无界面批处理。实际项目输出登记为 `other-previz-epNNN-NNN` 的 `other` 资产，版本文件落在 `assets/other/<key>/vNNN.mp4`；provenance 使用 `origin=generated`、`created_by=codex`、`model_or_workflow=blender-eevee-previz`，`prompt_document` 指向当前 storyboard 镜头，`parameters` 必须同时写入计划时长 `duration`、项目内导演合同路径 `direction_contract` 和该合同文件的 `direction_contract_sha256`。缺少任一绑定都不得登记候选。
+
+MP4 生成成功不等于白模完成。登记和审核前必须用 `ffprobe` 核对 MP4 实际时长、平均帧率、帧数和分辨率与合同、制作计划一致，并重新核对 MP4 与合同 SHA-256；不能只相信 provenance 声明。随后完整观看，至少每 0.5–1 秒抽查一次，并在动作入点、接触点、完成点、每个多机位切点和镜尾逐帧核对；检查剧情因果与节拍、人物调度与表演、相机动机与运动曲线、构图与视觉层级、空间/轴线/连续性、物理与接触、技术交付七项。把媒体 `asset_sha256`、各项得分、P0/P1/P2 问题以及与导演合同同序的 `hard_gates[]` 写入 `shot-reviews.json`；每项硬门禁必须包含 `gate/status/frame/observation` 的实际逐帧证据，任一失败即不得选版。审核入口会在自动选版前重新验证合同路径与哈希、实际媒体参数和当前制作计划版本。正式镜头还必须给出真实来源剧本、导演本、结构化分镜和制作计划版本；没有真实来源的临时演示只能标记 `test_only`，不得判断“符合剧情”、不得选版或进入正式视频。
+
+人数、身份、剧情因果、对白对象关系、轴线、物理接触、关键物可见性或剧本要求的镜尾反应任一未在实际画面中成立，都不得用合同字段或总分抵消。存在 P0/P1、任一硬门禁失败、总分低于 85/100 或任一项低于该项满分 70% 时，必须明确标记“不通过”，不得以“完成”“可用”或“已通过”交付；需要展示失败样片时必须同时展示审计结论。登记的 provenance `parameters.duration`、导演合同 `duration_seconds` 与制作计划镜头时长必须完全一致。通过后才可选中预演资产。`purpose=motion-reference` 当前只允许 StarRouter `MiniMax-H3`，把 selected 预演版本作为 `type=video, role=reference_video` 的执行期派生引用写入新 video-prompts 版本；公网临时发布使用 Runtime 的 TempFile.org 配置。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/plan-drama-production.md

@@ -0,0 +1,21 @@
+# 规划短剧制作
+
+
+
+读取本地已选导演本、人物/场景/道具、分镜和项目配置。由 Codex 使用 `../../assets/modules/plan-drama-production/prompts/production_plan.{zh,en}.txt` 输出 `production-plan.json`，逐镜记录：输入版本、`storyboard_strategy`、分镜图类型与实际格数、`previz_strategy`、视频方式、声音方式、Provider、模型或工作流、`prompt_profile`、`input_mode`、分辨率、画幅、时长、候选数、参考素材及其用途与顺序、依赖关系、预计付费次数、失败回退和验收项。
+
+
+时间故事版按连续动作阶段、运镜轨迹和精确状态变化组织；镜头分镜板按景别、人物关系、调度、轴线与叙事节拍组织。两张板使用相同格数但职责不同，必须生成独立资产和版本。视频引用顺序固定包含两张板；其余人物、场景、道具超过 Provider 剩余图片槽位时按既有 `overflow_strategy` 处理。
+
+
+格数必须按本分镜构图合同复核（`visual_plan.composition`、`composition_contract` 或 `photographyPlan.composition` 的 primary/secondary code、evidence 与 ai_risks；权威解释见 [导演构图模式参考](../director-composition.md)）：静态单一情绪仍至少用 2 格固定起止状态；追逐、接触、倒计时和运镜按不可合并阶段增加格数；多人站位、包围、遮挡、武器或多手交互按叙事节拍增加格数。风险只决定格数与回退，不得用增加格数替代证据。证据不足时 `status=blocked` 并写入 `unresolved`，退回分镜修订。
+
+每镜 `review_checks` 必须从合同 ai_risks 与证据元素反推具体、可观察、具名的验收项，不得复制同一组空泛检查：镜面/光滑水面核对映像与真人及现场陈设一致、无多指或多余摄像机；雨、雾、霓虹、烟尘核对天气光色有据、方向统一且不淹没接触点与人物身份；群体镜核对人数、身份和服色锚点、无多余路人；武器与多手交互核对形制、持有关系、手数和接触前/中/后；窄门缝或前景遮挡核对可见宽度、双眼完整和关键动作不被盖；高速拖影核对双眼、面部与接触点清晰可辨；前后夹击/包围核对前后景两方身份、距离和朝向可辨；竖屏镜头核对脸、关键道具和接触点位于中上安全区、底部字幕安全区不被占、动势边缘留余量。这些构图风险项与对白嘴部、道具三态、行走打斗物理、画内屏幕等既有风险项按命中取舍组合，视频验收会按此原顺序逐项核对。
+
+文本策划全部由 Codex 完成，不调用外部文本模型。Provider、模型/工作流、尺寸、时长、候选数、参考文件、声音方式、素材数量和批量请求范围必须逐项展示，不计算具体价格；只有用户确认后才把 `approved: true` 写入计划。
+
+Provider 支持 MiniMax H3 原生音频（`video.native-audio`）时，默认使用 `audio_strategy.mode=native`，并锁定逐秒对白表、全片音乐锚点和相邻镜头成对声音转场；此时不安排独立 TTS。仅当用户明确要求后配、或 Provider/模型明确声明不支持原生音频时，才写 `post-dub`/`independent` 并进入 `design-drama-audio`；能力信息缺失不得作为转后配的理由。
+
+使用 `project-store.mjs put-episode-document <项目目录> production-plan <episode-key> <version> <文件>` 保存不可变版本。选定后，所有镜头执行 `generate-storyboard-images`，分别完成时间故事版和镜头分镜板的八维审计；启用白模的镜头再执行 `direct-blender-previz`、`generate-blender-previz` 并完成导演评分。逐镜门禁全部通过后才能调用 `generate-drama-videos`。计划不得包含 API Key、Token 或远程业务对象 ID。
+
+只有双板加独立参考图实际超过 Provider 槽位才使用 `compose-assets`，未超槽位保留独立参考图。项目 `automation_mode=true` 且仅缺 Provider 已支持的分辨率时，agent 直接选择并落档，不等待用户。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/plan-shot-continuity.md

@@ -0,0 +1,15 @@
+# 规划跨镜连续性
+
+读取当前 selected 且已批准的 `storyboard`、`director-book` 和 `production-plan`，并使用 `../../assets/modules/plan-shot-continuity/prompts/continuity_plan.{zh,en}.txt` 生成一份 `continuity-plan`。只采用这些结构化文档和已选资产中的证据；不得引用尚未生成的双分镜板或白模，也不得推断未声明的道具、持物关系、入画边、出画边或精确米制坐标。
+
+规划阶段固定使用 `coordinate_mode=semantic`，以画面左/中/右、前/中/后景、朝向、视线对象和出入画边表达语义位置；不得从结构化分镜、图片透视或经验估算三维坐标。后续 Blender 白模只能验证或暴露冲突，不能静默改写已批准连续性计划；冲突必须回退规划阶段生成新版本。
+
+逐镜记录 `camera_setup_id`、`start_state`、`end_state`、人物位置/姿态/运动方向/持物、道具状态、轴线、机位侧和主光锚点。对每组相邻镜调用 `continuity-plan.mjs` 导出的 `recommendTailLink(previous,current)`：仅同场景、同机位、同轴线且状态无未解释跳变时，才可启用 `previous-tail`；第一镜、切换机位、越轴、场景变化或有意状态跳变使用 `independent`。合法 previous-tail 必须绑定上一镜号、上一镜 `camera_setup_id` 和 `video.first-frame` 能力。
+
+任何无法由证据解释的差异都写入 `unresolved`，并令 `approved=false`；不得把猜测写进 `allowed_changes` 以绕过校验。`allowed_changes` 只记录剧本、导演本或已批准调度明确要求的变化，`evidence` 指向相应来源。
+
+用 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/project-store.mjs" put-episode-document <项目目录> continuity-plan <episode-key> <version> <文件>` 保存不可变版本。只有 `unresolved=[]` 且逐镜校验通过后才能写 `approved=true`，随后必须用同一脚本的 `select-episode-document` 显式选定；未选定的连续性计划不能进入视频提示词编译。
+
+计划确定使用上一镜尾帧时，媒体阶段调用 `prepare_previous_tail`。上一镜视频换版后必须重新派生尾帧，不能继续使用旧文件或旧 SHA-256。
+
+`storyboard.shot_group` 是导演叙事分组，必须完整、连续且保持同组 type/pattern 一致；它可以包含反打、蒙太奇或其他切机位镜头，因此不能直接等同于尾帧链。执行阶段把每段连续的 `previous-tail` 链派生为一个生成镜头组：不同生成组可以并行，同组只开放一个前沿镜头。前镜候选未审核时状态为 `waiting-review`；前镜已审核选版但首帧尚未派生时为 `waiting-tail`；只有尾帧版本、来源版本和 SHA-256 全部匹配后，下一镜才可进入 `ready`。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/storyboard/revise-drama-storyboards.md

@@ -0,0 +1,5 @@
+# 修订短剧分镜
+
+先读取目标镜头、前后镜、源剧本片段、资产引用、selected 历史和当前 Provider 的 `shot_duration_constraints`。插镜用 `agent_storyboard_insert`；变体先用 `agent_shot_variant_analysis`，确认方向后再用 `agent_shot_variant_generate`；定向文本修改用 `storyboard_edit` 或镜头不可变编辑。
+
+不得改变 `shotKey`、来源身份或未获授权的剧情事实。修改后重新检查剧本覆盖、台词逐字一致、人物/场景/道具版本、轴线、视线、动作方向、时长和相邻转场，并只使受影响的图片、视频提示词和视频版本 stale。删除、调序或批量重生成前必须明确影响范围。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/usage-guide.md

@@ -0,0 +1,107 @@
+# 本地标准短剧使用手册
+
+原项目能力的保留、转换、排除和当前边界见 [能力审计](feature-completeness.md)。
+
+## 制作顺序
+
+参考片复刻统一使用原生 Hypit 链路；短剧插件只负责原创短剧制作。
+
+### 原创短剧制作
+
+1. **初始化项目**：`manage-drama-projects` 按项目规范 v1 创建固定配置、目录与状态，并归档 `src-xxx@v001` 原始资料。
+2. **Codex 分析**：`analyze-drama-source` 直接分析已选本地小说与要求；再形成简报、故事圣经和分集目录，不调用文本模型。
+3. **剧本落盘**：`short-drama` 提供开场、节奏、爽点、钩子和合规方法，`write-drama-episode` 由 Codex 写作或转换初稿，`humanizer` 产生自然化新版本，`review-drama-script` 对当前版本形成批准报告。
+4. **导演本落盘**：`write-drama-director-book` 形成场次级导演执行意图。
+5. **资产分析与画风**：`plan-drama-assets`、`generate-character-profiles` 确认资产范围，`generate-drama-art-style` 确认或生成项目统一画风。
+6. **资产生成落盘**：人物完整原画设定板、场景多视角设定板、道具设定板通过 `drama-generation-service` 调用用户选择的 Provider；结果全部进入本地资产账本。
+7. **声音证据与合同**：对原声或外部音频先执行 `analyze_speech_timing`，人工复核后用当前 timing 写逐句表演合同；`compile_dubbing_request` 只预检，不产生费用。
+8. **三轮生成与审核**：最多生成三轮，最终 alignment 达到一帧容差后执行八维完整听看审核；通过候选才能 selected。
+9. **字幕与口型**：调用 `build_subtitles_from_audio` 从最终 selected 音频生成绑定字幕；换版后重建字幕、口型和剪辑引用。
+10. **制作规划**：构建/修订结构化分镜，`plan-drama-production` 逐镜确定双分镜板格数、按需启用的 Blender 白模、模型、`prompt_profile`、输入模式和参考顺序，只汇总任务与素材数量。
+11. **分镜与素材制作**：制作规划先建立空间连续性。原创短剧默认使用双分镜板，只有复杂调度风险无法由静态板证明时才追加 Blender 白模。所有镜头生成时间故事版与镜头分镜板并分别完成八维审计，再由 `write-drama-video-prompts` 绑定本镜实际需要的参考和音频参考。声音按 native-first 执行。
+    随后执行 `hypit short-drama production plan ep-001 --runtime <profile> --workspace <项目>`；计划中的 `generation_groups` 会列出不同连续生成组及 `ready`、`waiting-review`、`waiting-tail`、`complete` 状态。确认计划后执行 `production build ... --confirmed`，一次只提交每组当前的 `ready_shot_number`。候选生成后先按制作计划审核；审核通过会自动选版。若下一镜显示 `waiting-tail`，调用 `prepare_previous_tail`，再重新执行 production plan/build；系统会把上一镜当前选版的尾帧作为下一镜第一个 `first_frame`，相同来源重复调用会直接复用。存在 `pending-build.json` 时再次执行 build 只恢复原任务，不产生新付费提交；它会核对提交时提示词文档、Run 和 Runtime Profile 的 SHA-256，文件变化或 Runtime 不同则须先恢复，终态失败也会先回收成功镜头。成功候选审核并选中后，未变化镜头会从重试 Run 中排除。启用白模的镜头绑定已审核的主运动参考。项目不得调用 legacy `submit_video` 绕过 Runtime。
+12. **授权音乐与本地修复**：许可证用途验证通过后才把目录音乐放入时间线；本地局部修复保留来源、范围和专项审核。远端超分暂时禁用，等待 StarRouter 等价模型验证。
+13. **剪辑**：`remotion-best-practices` 约束 Remotion 工程与帧确定实现，`edit-drama-timeline` 按本地剪辑方案完成粗剪、字幕、转场、声音和渲染。
+14. **成片**：`edit-deliver-drama` 逐集完整审片并输出 `delivery/<episode-key>/`。
+
+文本资产默认由 Codex 直接生成，不使用外部文本模型。图片、视频、音频才进入生成 Provider 路由。
+
+制作计划确认只授权所列 Provider 请求，不改变阶段，也不计算具体价格。Runtime 与仍保留的生成 MCP 都会在请求落盘前检查当前阶段和全部上游门禁；直接编辑 `selected.json`、项目配置或占位文档不能使越级调用通过。
+
+全流程只调用 `short-drama` 主 Skill。进入阶段后运行 `node scripts/module-runs.mjs required <项目目录> <阶段>`，主 Skill 完整读取并执行返回的 reference 模块，再用 `record` 关联实际项目产物。`workflow.mjs advance` 会拒绝没有模块执行凭证的结果。
+
+## Reference 模块
+
+| 模块 | 用途与使用场景 | 上下游/顺序 | 必须由用户确认 |
+|---|---|---|---|
+| `manage-drama-projects` | 按规范 v1 初始化和校验本地项目、来源、分集、剧本、导演本、制作计划与分镜版本 | 全流程控制面；第一步 | 项目目录、名称、语言、画幅、集数；旧配置迁移、覆盖/重命名 |
+| `analyze-drama-source` | Codex 全量分析小说、资料和制作要求 | 初始化后；先于简报/剧本 | 原文范围、改编边界、冲突要求 |
+| `analyze-drama-source` | 分析原创短剧来源资料 | analysis 阶段 | 原文范围与改编边界 |
+| `define-drama-brief` | 固化题材、受众、平台和交付边界 | source analysis 后 | 平台、语言、画幅、集数、目标时长、分级、禁区；目标时长默认允许约 ±15% 自然浮动 |
+| `design-drama-bible` | 建立世界观、人物弧、冲突和结局 | brief 后 | 结局类型、人物关系、重大改编 |
+| `outline-drama-series` | 拆分分集冲突、兑现和钩子 | bible 后 | 总集数、单集时长、分集结构 |
+| `short-drama` | 用开场、节奏、爽点、钩子、反派、付费卡点和合规方法指导剧本 | script 阶段首个方法层 | 改编事实、集数、结局和付费策略变化 |
+| `write-drama-episode` | Codex 编写或忠实转换单集剧本 | outline 后 | 原创/忠实转换、目标集、剧情改动、台词定稿 |
+| `humanizer` | 减少模板腔、说明腔和角色同声，保持剧情事实与制作约束 | 剧本初稿后、复核前 | 用户语言样本；任何会改变台词含义或剧情事实的修改 |
+| `review-drama-script` | 复核开场、节奏、兑现、对白、连续性、合规和可制作性 | 自然化后、导演本前 | 接受 P2；P0/P1 必须修改后重审 |
+| `write-drama-director-book` | 生成场次级表演、调度、摄影、光线和声音导演本 | 已选剧本后 | 改变剧情含义、表演基调或声音策略的决定 |
+| `plan-drama-assets` | 识别本集人物、场景、关键道具及叙事版本 | 导演本后 | 资产范围、合并/拆分、版本需求 |
+| `generate-character-profiles` | 建立人物事实、别名、关系、长期表演与声音特征 | 资产分析阶段 | 人物身份、关系、是否出镜、持续造型 |
+| `generate-drama-art-style` | Codex 生成项目画风、色板、光线和运动语言 | 资产生成前；默认真人风格可直接确认 | 画风名称/描述、参考图、预览模型和制作计划 |
+| `manage-drama-art-styles` | 选择、绑定或变更已有画风并计算 stale 范围 | 画风生成后或变更时 | 入选画风和重新生成范围 |
+| `generate-character-images` | 生成含脸部特写、正侧背全身和辅助设定的角色原画板 | 人物档案确认后 | Provider、模型/工作流、候选数、尺寸、参考图、制作计划、选版 |
+| `generate-scene-assets` | 提取并生成无人场景候选 | 资产分析后 | 场景层级、锚点、Provider、候选数、尺寸、制作计划、选版 |
+| `generate-prop-assets` | 提取并生成关键道具候选 | 资产分析后 | 是否值得独立资产、Provider、候选数、尺寸、制作计划、选版 |
+| `manage-drama-assets` | 将文件、URL、base64 结果归档本地，登记哈希和选版 | 每次媒体生成后立即执行 | 导入目标、文件名、选版、回退或覆盖影响 |
+| `build-drama-storyboard` | 将剧本、导演本和已选资产拆成结构化镜头 | 资产选版完成后 | 镜头数量/时长、剧情覆盖、台词和镜头策略 |
+| `revise-drama-storyboards` | 插镜、变体、修改、重排并保留分镜版本 | 已有分镜后按需 | 修改镜头、剧情影响、批量范围、选定版本 |
+| `write-drama-video-prompts` | Codex 把分镜编译成 Seedance 2.0、MiniMax H3 或通用逐镜提示词，并本地版本化 | 制作计划锁定模型与参考顺序后 | prompt_profile、input_mode、时长、参考用途/顺序、声音方式、台词、转场意图 |
+| `plan-drama-production` | 汇总逐镜生成方式、Provider、参考素材和依赖 | 媒体生成前最后门禁 | Provider、模型/工作流、尺寸、时长、候选数、参考文件和批量请求范围 |
+| `drama-generation-service` | 通过 Hypit Runtime 的 StarRouter 配置生成图片、视频与音频 | 所有远端媒体生成入口 | 模型、参数、参考文件用途和制作计划；切换或重试 |
+| `publish-drama-references` | 查询或用 TempFile.org 临时托管把本地选版图转为公网 HTTPS URL | StarRouter 需要公网参考素材时 | 先查有效收据；素材权利、公开暴露、用途许可、逐项资产版本和 24h 时效；强制重传需再次确认 |
+| `configure-generation-providers` | 配置和探活 Provider，不生成 | 首次使用或凭据/目录变化时 | 各模态 Provider 选择；密钥由用户自行配置 |
+| `generate-storyboard-images` | 为每镜独立生成时间故事版与镜头分镜板 | 制作计划批准后、视频提示词编译前 | Provider、格数、尺寸、候选数、参考图、制作计划、选版 |
+| `direct-blender-previz` / `generate-blender-previz` | standard 仅为静态双板无法证明的复杂调度生成可选白模；原创项目仅为复杂调度追加 review 白模 | 双分镜板之后、视频提示词编译前 | 剧情节拍、调度、轴线、运镜、评分与选版 |
+| `generate-drama-videos` | 生成并下载逐镜视频 | 双分镜板、按需审核的白模主运动参考、音频参考与视频提示词确认后 | Provider、模型/工作流、时长、分辨率、参考素材、声音、制作计划、重试 |
+| `design-drama-audio` | 原生音频优先；做七维复听，并允许导入已授权外部音频；自定义音色克隆和口型驱动暂时禁用 | 制作计划或逐镜视频阶段 | StarRouter 语音模型、声音权利、文本、失败区间、制作计划、选版 |
+| `transform-drama-media` | 本地裁剪、抽帧、剪接等版本化媒体操作；远端口型和超分暂时禁用 | 媒体生产中按需 | 来源资产、操作范围、结果选版与专项审核 |
+| `monitor-drama-tasks` | 本地登记、去重、查询异步任务并校验完成文件 | 媒体生产贯穿执行 | 取消任务、扩大重试或重新付费 |
+| `recover-drama-pipeline` | 恢复中断任务、缺失下载和 stale 下游 | 失败或续作时 | 重提、换 Provider/模型、重新付费、回退阶段 |
+| `review-drama-shots` | 分别审计双分镜板八维逻辑、按导演合同评分可选白模，并验收正式视频 | 分镜选版后、视频生成前必做；视频落盘后再次执行 | 接受 P2 缺陷、重生成或选用替代版本 |
+| `remotion-best-practices` | 约束 Remotion 工程、React 时间线、字幕、音频、预览与渲染 | editing 阶段首个实现层 | 工程初始化、外部包安装和输出规格 |
+| `edit-drama-timeline` | 用本地 Remotion 工程完成剪辑、字幕、转场、声音和渲染 | 全部选镜验收通过后 | 入选版本、剪辑结构、字幕样式、转场、声音目标、输出规格 |
+| `edit-deliver-drama` | 完整审片、技术检查和本地交付打包 | 最后一步 | 批准版、文件名、交付目录和发布规格 |
+| `orchestrate-short-drama` | 按状态机编排完整流程，不替代原子工作 | 新建、继续、查看项目时 | 阶段回退、批量范围和任何付费动作 |
+| `short-drama-skill-index` | 按产物类型查找对应模块 | 不确定该加载哪个 reference 时 | 无；只路由 |
+| `use-short-drama-studio` | 使用者入口，解释全流程、依赖、顺序和确认门禁 | 开始制作或询问怎么使用时 | 汇总当前缺失决策，不自行代选 |
+
+## 市场调研流程
+
+显式执行 `node scripts/market-research.mjs refresh /absolute/workspace` 才会联网刷新公开榜单。`list` 查看快照与报告历史，`report` 读取最新报告，`analyze /absolute/workspace <snapshot-id>` 重算指定历史快照；Studio 使用全局 `#/market`。报告持续标注公开 Top 30 样本边界，不作为收益承诺。
+
+市场数据按四层使用，不能混写：
+
+1. **事实**：`market-report.v2` 中可回链快照、榜单和作品证据的观测值；缺失值保持 `null`。
+2. **推断**：机会分、供需象限、共现和平台偏好等分析结论，必须保留置信度、覆盖率和限制。
+3. **创作假设**：`ideate-drama-from-market` 或 Studio 灵感板从信号提出的原创切口，仍需验证，不能复制榜单作品标题、人物关系或具体情节。
+4. **用户决定**：用户明确选择候选并登记后，才写入 `market-inspiration.v1` 和 Brief 的 `market_inspiration_ref`。
+
+推荐使用路径：
+
+1. 可选执行 `refresh`；不刷新时只读已有 `.short-drama-market/reports/*.json`。
+2. 在 Studio `#/market` 选择报告周期和筛选范围，查看题材 × 榜单热度、证据和限制。
+3. 在灵感板选择 1–3 个题材并生成本地候选，逐项核对事实、推断、假设和低置信风险。
+4. 选择一个候选和目标项目，点击“登记已选候选”。该动作只登记 `.short-drama/market-inspiration.json` 并更新 `.short-drama/brief.json` 的引用，不改变项目题材或 Brief 平台。
+5. 继续执行 `define-drama-brief`；后续 Bible 和 Outline 只消费已确认的 Brief，不直接读取榜单作品清单。
+
+Agent 只有在用户明确要求“参考市场/排行榜找灵感”时才执行 `ideate-drama-from-market`。命令行工作流先用 `node scripts/project-store.mjs market-report-ref <项目目录> <report-id> <hypothesis-id...>` 生成可校验报告引用，再按 Skill 合同生成并登记灵感；普通创作不强制经过市场步骤。运行 `node scripts/market-inspiration-offline-smoke.mjs` 可在临时工作区验证全程不刷新网络的闭环。
+
+## 通用门禁
+
+项目配置 `automation_mode` 默认为 `true`。开启时由 agent 自主完成下表中的常规确认；关闭时才等待用户逐项确认。阶段门禁、权限/素材权利事实和安全校验始终有效。
+
+- 覆盖、删除、重命名、阶段回退、批量生成、付费重试、切换 Provider/模型/工作流、上传参考素材和最终选版都必须产生确认记录。
+- 多集项目仍按全局阶段推进；分集级 Skill 必须为每个已建 `ep-NNN` 同时登记独立产物，Codex 合同运行记录必须逐一绑定对应分集证据，不能用某一集替其他集背书。
+- Provider 返回成功不等于完成；本地文件、哈希、provenance、账本和验收缺一不可。
+- 源时间线情感配音发布验收还必须指定 `DUBBING_EVIDENCE_PROJECT` 与 `DUBBING_EVIDENCE_REPORT`；报告必须来自真实镜头 A/B，并绑定完整复听、制作耗时、实际 Provider 任务、字幕和口型证据。
+- 用户未确认的参数保持未决，不用示例值或所谓“最佳实践”替用户决定。

package/skills/using-vvicat-ai-short-studio-cli/references/special-workflows.md

@@ -4,7 +4,7 @@
 
 ## 专业剧本和纯文本拆镜
 
-微短剧从选题或方案开始时，按 [编剧合同](story-craft/guide.md) 完成方案、角色、分集、目标单集剧本和审校，再按 [文风润色](writing-polish.md) 只调整表达，最后重新运行画布剧本审校。已有专业剧本直接创建 screenplay resource。
+微短剧从选题或方案开始时，先用 `short-drama` 完成方案、角色、分集、目标单集剧本和 review，再用 `humanizer` 只润色表达，最后回到 short-drama 复核。已有专业剧本直接创建 screenplay resource。
 
 用户明确要求专业 Markdown 纯文本拆镜测试时，给 `storyboard-breakdown` 配置 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、任意规范 BCP 47 `targetLanguage`、平台和画幅，且只连接一条剧本。执行前按 [拆镜语言匹配门禁](assets-and-storyboard.md#拆镜语言匹配门禁) 验证每个本地化块；`targetLanguage` 不能被项目 `outputLanguage` 或 CLI `--locale` 替代。该模式只验收分镜文本和镜头资产，不执行声音设计、TTS、图片、音频或视频生成；失败时确认没有持久化半成品。
 
@@ -22,4 +22,4 @@
 
 ## AI 剪辑
 
-涉及时间线、裁切、字幕、转场、音频编排或渲染时，完整执行 [剪辑与交付流程](editing-delivery.md)；使用 Remotion 时再读随包的 [实现参考](remotion-editing.md)。只使用已确认的 selected 资产；原始镜头和 manifest 单独保留。H3 成片只对原生整轨做轻量处理，禁止另铺外部 TTS、旁白、对白、环境音或 BGM 覆盖。
+涉及时间线、裁切、字幕、转场、音频编排或渲染时，必须先加载 `remotion-best-practices`，然后完整执行 [剪辑与交付流程](editing-delivery.md)。只使用已确认的 selected 资产；原始镜头和 manifest 单独保留。H3 成片只对原生整轨做轻量处理，禁止另铺外部 TTS、旁白、对白、环境音或 BGM 覆盖。

package/dist/auth/login-provider.d.ts

@@ -1,2 +0,0 @@
-import type { CliProfile } from '../config/profiles.js';
-export declare function resolveLoginProvider(explicit: string | undefined, profile: Pick<CliProfile, 'authProvider'> | null): 'supabase' | 'memhub';

package/dist/auth/login-provider.js

@@ -1,3 +0,0 @@
-export function resolveLoginProvider(explicit, profile) {
-    return (explicit || profile?.authProvider || 'supabase');
-}

package/dist/commands/canvas/node/quote.d.ts

@@ -1,17 +0,0 @@
-import { BaseCommand } from '../../../base-command.js';
-export default class CanvasNodeQuote extends BaseCommand {
-    static description: string;
-    static args: {
-        nodeId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static flags: {
-        project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-}

package/dist/commands/canvas/node/quote.js

@@ -1,13 +0,0 @@
-import { Args } from '@oclif/core';
-import { BaseCommand } from '../../../base-command.js';
-import { commandApi, projectFlag } from '../../../command-helpers.js';
-export default class CanvasNodeQuote extends BaseCommand {
-    static description = '只读核对画布节点的模型、请求参数和已发布价格；不提交任务或冻结积分';
-    static args = { nodeId: Args.string({ required: true }) };
-    static flags = { ...BaseCommand.baseFlags, project: projectFlag };
-    async run() {
-        const { args, flags } = await this.parse(CanvasNodeQuote);
-        const { api } = await commandApi(flags);
-        this.print((await api.quoteNode(flags.project, args.nodeId)).quote);
-    }
-}