@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/operations/short-drama-skill-index.md

@@ -0,0 +1,29 @@
+# 本地短剧 Skill 索引
+
+首次使用、完整生产或询问流程时先路由 `use-short-drama-studio`。普通操作读取本地 `.short-drama/state.json`，再路由到最小可完成目标的 Skill；模板归属见 [提示词索引](../prompt-skill-index.md)。
+
+- 小说/要求分析、简报、故事圣经、分集、剧本、自然化与复核 → `analyze-drama-source`、`define-drama-brief`、`design-drama-bible`、`outline-drama-series`、`short-drama`、`write-drama-episode`、`humanizer`、`review-drama-script`
+- 市场题材、公开榜单、平台差异、竞争格局与新剧势能 → `analyze-drama-market`
+- 用户明确要求把已保存市场信号转为原创立项假设或登记项目引用 → `ideate-drama-from-market`
+- 导演本 → `write-drama-director-book`
+- 本地项目、剧集、剧本和分镜版本 → `manage-drama-projects`
+- 资产清单和本地媒体版本 → `plan-drama-assets`、`manage-drama-assets`
+- 人物档案、成年魅力/儿童保护、完整角色原画设定板与人物专项审核 → `generate-character-profiles`、`generate-character-images`、`review-drama-shots`
+- 场景、道具 → `generate-scene-assets`、`generate-prop-assets`
+- 打斗动作链、空间路线与动作分镜 → `design-fight-video`
+- 首次拆镜、分镜修订 → `build-drama-storyboard`、`revise-drama-storyboards`
+- 分镜参考 → 每镜双分镜板使用 `generate-storyboard-images` 与 `review-drama-shots` 八维审计；可选白模使用 `direct-blender-previz`、`generate-blender-previz` 与导演评分；图片确定性变换使用 `transform-drama-media`
+- 制作规划、跨镜连续性、尾帧首帧承接、Seedance 2.0/H3/通用视频提示词 → `plan-drama-production`、`plan-shot-continuity`、`write-drama-video-prompts`
+- 视频镜头 → `generate-drama-videos`
+- 原生音频复听、受控 TTS/外部音频兜底与口型 → `design-drama-audio`；授权配乐与许可证也由该 Skill 规划，媒体登记和变换走 `drama-generation-service`、`transform-drama-media`
+- 镜头验收、时间线、交付 → `review-drama-shots`、`remotion-best-practices`、`edit-drama-timeline`、`edit-deliver-drama`
+- 画风生成、选择与变更 → `generate-drama-art-style`、`manage-drama-art-styles`
+- Hypit Runtime 的 StarRouter 模型配置和媒体生成 → `configure-generation-providers`、`drama-generation-service`
+- Provider 只接受公网 URL 时临时发布本地参考图 → `publish-drama-references`
+- 本地任务监控和故障恢复 → `monitor-drama-tasks`、`recover-drama-pipeline`
+
+媒体能力的唯一逻辑顺序是：`character-appeal → continuity-plan → previous-tail（符合条件才启用）→ native-audio → native-audio-review → audio-fallback（仅审核失败）→ lip-sync（仅可见独立对白）→ licensed-music → media-editing → video-upscale → delivery`。可选节点不满足前置条件时直接跳过，不得伪造执行记录。
+
+所有生成结果必须先保存到本地项目再进入下一步；远程 URL、任务 ID 或聊天内容都不是资产。用 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/audit-plugin.mjs"` 检查插件自身完整性，不读取任何外部业务仓库。
+
+完整制作不能把本索引当作阶段 Skill 的替代品。先运行 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/module-runs.mjs" required <项目目录> <阶段>`，完整读取并执行列出的原子 Skill；完成后用 `record` 绑定项目内证据，阶段门禁会验证这些记录。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/operations/use-short-drama-studio.md

@@ -0,0 +1,15 @@
+# 使用本地短剧工厂
+
+开始前完整读取 [使用手册](../usage-guide.md) 和 [Codex 原生合同说明](../codex-contracts.md)；创建、复制、迁移或修复项目时读取 [项目规范 v1](../project-spec-v1.md)，需要查看状态机时再读取 [本地生产合同](../pipeline.md)，需要核对与原项目的能力边界时读取 [能力审计](../feature-completeness.md)。
+
+新项目先确认最少必要配置；用户未指定其他绝对路径时，项目目录固定为 `~/darma_project/<project-key>`。未确认项保留 `null`，再调用 `manage-drama-projects` 初始化；原始小说或要求必须复制进 `source/` 并选定明确版本。既有项目先运行 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/validate-project.mjs" <项目目录>`，再读取 `.short-drama/project.json`、`state.json`、`tasks.json` 和 `assets.json`，只路由当前阶段所需的原子 Skill。无论项目位于默认工作区还是用户指定的绝对路径，初始化及 startup/resume 都会自动打开项目 Dashboard 精确路由并生成 `.short-drama/dashboard.json`；先核对凭证，只有缺失、路由不匹配或系统开窗失败时才显式运行 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/studio.mjs" open-project <项目目录>`。不能把“服务器已启动”当成“项目 Dashboard 已打开”，也不能在自动打开成功后重复开窗。
+
+
+
+项目 `automation_mode` 默认开启；开启后 agent 自主处理常规确认，不重复打断用户，但不能伪造权限、素材权利或绕过安全门禁。
+
+标准顺序是：初始化与环境预检 → 打开项目 Dashboard → Codex 分析小说与要求 → `short-drama` 方法论 + 剧本初稿 → `humanizer` 自然化新版本 → 剧本复核批准 → 导演本落盘 → 资产分析 → 人物吸引力/儿童保护审核与资产生成落盘 → 制作规划（双分镜板格数、可选白模、模型和提示词协议）→ 每镜时间故事版与镜头分镜板生成/选版/分别八维审计，复杂镜头追加白模编导/生成/评分 → 空间连续性与可选尾帧承接 → Seedance 2.0/H3/通用逐镜提示词落盘 → 原生声音生成和复听 → 仅对失败区间兜底、按需口型 → 授权配乐与媒体修复 → 对已选视频按需超分并复审 → `remotion-best-practices` + Remotion 剪辑 → 成片交付。每阶段必须先用 `module-runs.mjs required` 获取原子 Skill，完整读取并执行，再用 `module-runs.mjs record` 记录项目内产物；仅生成文件但没有 Skill 凭证不能通过阶段门禁。
+
+文本资产全部由 Codex 直接创作和校验，不调用任何文本生成 Provider；媒体生成统一交给 `drama-generation-service`，由用户选择 StarRouter 模型和参数。需要公网 URL 时，另行路由 `publish-drama-references`；TempFile.org 链接公开、临时且受用途条款约束。项目 `automation_mode=true` 时，已配置范围内的生成、上传、选版、覆盖、回退和切换按合同自动继续，不为常规步骤重复询问；`false` 时才逐项等待确认。真实付费、素材权利、安全事实和删除项目仍需明确确认，不能由 agent 代替授权；缺少这些条件时一次说明缺口并停在安全边界。阶段交付前再次运行项目校验。
+
+生成型媒体优先由 Studio 打开的同一项目通过 Hypit Source、Run 与 Runtime 执行，任务是否暴露插件 MCP 工具不影响原生 Provider 可用性。仅插件专属且尚无 Hypit Model 的能力依赖 MCP；未暴露时停止该能力，不得绕过 Runtime 直接加载厂商脚本，也不得降级为占位素材或声称已生成。

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

@@ -0,0 +1,85 @@
+# 本地短剧生产合同
+
+标准流程固定为：
+
+`analysis → script → director-book → asset-analysis → asset-generation → production-plan → per-shot image or Blender storyboard → plan-shot-continuity → video prompts → videos/audio → editing → delivery`
+
+短剧插件只提供原创短剧状态机；参考片复刻统一使用原生 Hypit 复刻链路。旧复刻项目由插件阻止并提示迁移。
+
+市场调研和市场灵感位于正式状态机之外，是 `analysis` 前或过程中按需使用的辅助输入，不是所有项目的必经阶段。工作区级 `.short-drama-market/` 保存公开榜单快照和 `market-report.v2`；只有用户明确选择灵感后，项目内才保存 `market-inspiration.v1` 并由 Brief 引用。
+
+所有状态、文本、分镜和媒体都以用户指定的本地项目目录为事实来源，不调用或回写任何业务系统 API。
+
+```text
+<project>/
+├── .short-drama/
+│   ├── project.json
+│   ├── state.json
+│   ├── environment.json / RESUME.md
+│   ├── module-runs.json
+│   ├── prompt-runs/<prompt-run-id>.json
+│   ├── requests/<request-id>.json
+│   ├── uploads/<upload-receipt-id>.json
+│   ├── source-analysis.json / brief.json / market-inspiration.json
+│   ├── bible.json / outline.json
+│   ├── assets.json
+│   ├── shot-reviews.json
+│   └── tasks.json
+├── source/
+│   ├── manifest.json
+│   └── src-<name>/v001.<ext>
+├── episodes/<episode-key>/
+│   ├── episode.json
+│   ├── scripts/<version>.(json|md|txt)
+│   ├── script-review/<version>.json
+│   ├── director-book/<version>.json
+│   ├── asset-plan/<version>.json
+│   ├── production-plan/<version>.json
+│   ├── continuity-plan/<version>.json
+│   ├── video-prompts/<version>.json
+│   ├── audio-plan/<version>.json
+│   └── storyboard/<version>.json
+├── assets/{characters,scenes,props,storyboards,audio,videos,other}/
+├── editing/ep-NNN/timeline.json / review.json
+└── delivery/ep-NNN/
+```
+
+所有项目必须遵循 [项目规范 v1](project-spec-v1.md)：JSON 使用 snake_case 业务字段，项目 key 使用小写 kebab-case，分集使用 `ep-001`，版本使用 `v001`，媒体资产使用类型前缀并携带 provenance。
+
+市场灵感严格分层：报告保存可追溯事实和分析推断，灵感文档保存待验证的创作假设，`decision` 保存用户已选择/拒绝的决定。报告引用绑定 report ID、snapshot IDs、筛选条件、生成时间和 SHA-256；登记时同时校验并原子写入 `market-inspiration.json` 与 Brief 引用。该可选动作不得覆盖 `project.json` 的题材、Brief 的平台、来源事实或合规约束，Bible 与 Outline 也不得绕过 Brief 直接消费榜单作品清单。
+
+用 `node scripts/project-store.mjs init <项目目录> [项目元数据.json]` 初始化并执行 init 环境预检；进入媒体或剪辑阶段前再运行 `node scripts/preflight.mjs <media|editing> <项目目录>`。每阶段先用 `node scripts/module-runs.mjs required <项目目录> <阶段>` 获取 reference 模块，由 `short-drama` 主 Skill 完整执行，完成后用 `record` 绑定项目内证据；同一阶段已有证据时可用 `record-stage`。阶段检查、推进与回退使用 `workflow.mjs`；`advance` 会拒绝缺少模块凭证、真实本地产物或验收的阶段。
+
+初始化一次性创建资产、任务、逐镜审核和模块账本。媒体 MCP 不信任聊天中的流程声明或手写 selected 文件：每次付费生成前校验当前阶段并重新检查所有上游阶段门禁；失败发生在请求快照和 Provider 访问之前。项目配置同时校验画幅—分辨率方向和 Provider 模型参数枚举。
+
+图片、音频和视频生成成功后，必须立即用 `node scripts/asset-ledger.mjs <import|fetch|decode> ...` 把结果存入项目的 `assets/`，登记 SHA-256、文件大小、本地相对路径和 provenance，再允许选版或进入下游。独立配音先保存并选中 `audio-plan/vNNN.json`。资产生成与媒体制作阶段结束时用 `snapshot-stage-evidence.mjs` 生成不可变证据，避免后续合法修改总账导致早期凭证失效。远程 URL 只是临时传输结果，不得作为最终资产。
+
+声音采用 `native-first`：先选同时满足画面引用和 `video.native-audio` 的 StarRouter 模型，原生生成对白、电影感旁白、环境声和动作声；BGM 走独立配乐与许可证流程。每个原生声候选必须完成 `speech_intelligibility`、`speaker_identity`、`narration_performance`、`ambience_action_sync`、`lip_sync`、`technical_audio`、`undeclared_music` 七维审核。失败时把受控 reason 和证据写入 `native_audio_exception`；当前缺少已验证的自定义音色、七维后配和口型驱动能力，不得用旧厂商自动补做这些步骤。
+
+媒体能力按 `character-appeal → continuity-plan → previous-tail → native-audio → native-audio-review → licensed-music → local-media-editing → delivery` 推进。previous-tail 是有前置证据的可选节点；历史状态机中的 audio-fallback、lip-sync 和 video-upscale 节点目前禁用，不能为了填满流程伪造任务或切到旧厂商。
+
+配乐分为 `music.generate` 与 `music.catalog`。生成曲保持现有 `generate_music` 流程；目录曲只返回本地已授权结果或 Pixabay、YouTube Audio Library、Uppbeat 官方搜索页，不自动登录或下载。用户试听并取得文件与许可证证据后，`register_licensed_music` 先写不可变收据，再登记未选音频候选。audio-plan 绑定精确资产、`license_receipt` 与项目用途，时间线再次验证选版和 allowed uses；普通视频页面、无同步权与母带权凭证的热曲不能进入资产库。
+
+剧本阶段的 `short-drama` 必须绑定实际分集剧本版本；人物分析必须绑定 `assets/characters/profiles.json`。人物链路固定为：年龄证据 → `audience_appeal` 校验 → 人物定妆候选 → 人物专项审核与选版 → 分镜/白模/正式视频引用绑定 → 跨镜一致性复核。明确成年人物使用 `adult-charisma`，必须有专属 `grooming_and_makeup`、`costume_signature` 和角色级 `memory_anchors`；儿童只使用 `child-cuteness`，任何成人化或性化处理都是不可由总分抵消的硬失败。未知年龄停在人物档案阶段。新生成角色候选只能经 `validateCharacterAppealReview` 和 `review-character` 选版，正式视频人物引用还要通过 `assertCharacterReadyForVisuals` 及档案 SHA、appearance 与可见身份约束校验。
+
+每个镜头都必须生成两张独立参考板：`board-epNNN-temporal-NNN` 时间故事版和 `board-epNNN-shot-NNN` 镜头分镜板，分别选版并通过八维审计。原创项目默认直接使用双板，仅在复杂路线、多人交互、精确接触、轴线风险或连续运镜无法由静态板证明时追加 Blender 白模。Blender 不能替代双板。
+
+选择 Blender 的镜头先由 `direct-blender-previz` 写入 `episodes/<episode>/previz/shot-NNN-vNNN.json` 导演合同，再由 `generate-blender-previz` 渲染为 `other-previz-epNNN-NNN`，登记、完整观看、按七项 100 分合同验收并选版；总分低于 85 或任一单项低于 70% 时不得提交正式视频。双板和白模都不能替代正式视频所需的人物、场景和道具资产。
+
+结构化分镜与制作计划批准后，由 `plan-shot-continuity` 汇总 selected 分镜、导演本和制作计划，生成并显式选定 `continuity-plan/vNNN.json`。分镜 `shot_group` 表达叙事组；计划逐镜固定机位、轴线、人物/道具起止状态与转场方式，只有同场景同机位且状态连续时才允许 previous-tail。Runtime 把连续 previous-tail 链派生为生成镜头组：不同组并行、同组串行，一次只生成各组当前前沿镜头。后续双分镜板或白模若暴露冲突，必须回退生成连续性计划新版本。媒体阶段用 `prepare_previous_tail` 从上一镜当前 selected 且已审核的视频派生下一镜首帧，正式提交前再次比对来源版本和 SHA-256。
+
+资产计划中的人物、场景或道具若已有 selected、未失效且不是 Provider 产出的本地版本，可直接复用；缺失、失效或由 Provider 生成/变换时，动态要求对应生成 Skill 与 `drama-generation-service`，防止 Provider 变换资产绕过执行凭证。
+
+生成工具必须携带 `project_root`、`target` 和模态对应的 `prompt_document`。MCP 先核对项目已确认的 StarRouter 模型与 Runtime；视频由 Hypit `production plan/build` 核对当前 selected 视频提示词，图片绑定当前资产计划/分镜和 Provider 提示词记录，音频绑定当前配音计划。通过本地合同校验后，在访问 Provider 前保存实际调用参数到 `.short-drama/requests/` 并原子登记 `submitting`；同目标同输入已有在途任务时不会再次付费。TempFile.org URL 绑定提交时有效的本地收据。快照禁止密钥和内联媒体，不能手工覆盖。
+
+只接受公网 URL 的 StarRouter 模型使用 TempFile.org 临时发布参考素材；上传写入 `.short-drama/uploads/` 收据并要求权利、公开风险及用途许可确认。同资产版本默认复用有效收据，剩余时效不足时才经确认重传；过期 URL 和上传收据都不能替代本地资产。
+
+原系统的 LLM 提示词已按 [Codex 原生合同](codex-contracts.md) 固化在所属 Skill：Codex 直接执行合同，完成后用 `render-prompt.mjs --codex-output` 保存输入与实际产物；只有 `provider_prompts` 用 `--output` 渲染为媒体模型提示词。项目内所有 JSON 写入采用原子替换；新导演本、资产计划、制作计划、分镜、视频提示词、剧本和媒体版本不得覆盖旧版本。视频提示词先形成模型无关的镜头事实，再由同一 Skill 编译为 `seedance2`、`h3` 或已确认的 `generic` 协议，禁止跨协议混写。
+
+使用 `node scripts/audit-plugin.mjs` 验证 Skill、提示词、人工索引与脚本引用。该检查不读取外部项目仓库。
+使用 `node scripts/validate-project.mjs <项目目录>` 校验实际项目配置、目录、命名、来源、选版、资产 provenance、文件存在性和 SHA-256。
+# 源时间线情感配音
+
+独立配音固定经过 `selected 原声资产 → speech-timing 候选 → 人工复核 timing → audio-plan 三层合同 → 最多三轮编译生成 → 最终 alignment → 八维审核选版 → 字幕/口型/剪辑同源绑定`。行级 ASR 自动通过阈值为 `0.90`，词级为 `0.80`；StarRouter 词级时间戳只接受 `verbose_json + timestamp_granularities=word`，低置信证据不得静默补造。第二轮校准语速钳制在 `0.85–1.15` 后必须实际执行；最终后处理只允许合同内停顿和 `±3%` tempo，容器时长不能替代发声边界。硬门禁比较首词起点和末词终点是否都在一帧内，内部词边界保留为节奏审计证据。换选音频会递归失效旧字幕和口型派生资产。
+
+历史源时间线第三方配音项目若要验收，须对一个真实镜头完整听看原声与配音，运行 `dubbing-live-acceptance.mjs` 生成项目内 A/B 报告，再以 `DUBBING_EVIDENCE_PROJECT=<项目目录>`、`DUBBING_EVIDENCE_REPORT=<项目内报告路径>` 运行 `next-version-acceptance.mjs`。门禁会重新核对媒体 SHA、可解码音视频流、当前选版、已完成任务、正整数制作耗时、八维完整复听、词级误差、字幕和口型绑定。当前新制作已禁用七维后配和口型驱动，未选择该历史路线的版本验收只检查合同与停用门禁，不要求制造一份无法合法生成的第三方配音证据。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/project-spec-v1.md

@@ -0,0 +1,217 @@
+# 短剧本地项目规范 v1
+
+本规范是插件创建、继续、复制和校验短剧项目的唯一文件合同。文本资产由 Codex 通过 `short-drama` 主 Skill 加载当前 reference 模块后直接输出；图片、视频和音频才调用用户选择的 Provider。项目文件不得包含 API Key、Token、密码或 Authorization。
+
+## 固定目录
+
+```text
+<project>/
+├── .short-drama/
+│   ├── project.json
+│   ├── state.json
+│   ├── environment.json
+│   ├── environment/<timestamp>-<mode>.json
+│   ├── module-runs.json
+│   ├── RESUME.md
+│   ├── prompt-runs/prompt-<uuid>.json
+│   ├── evidence/<stage>-<uuid>.json
+│   ├── requests/req-<uuid>.json
+│   ├── uploads/upload-<uuid>.json
+│   ├── source-analysis.json
+│   ├── brief.json
+│   ├── bible.json
+│   ├── outline.json
+│   ├── art-style.json
+│   ├── assets.json
+│   ├── tasks.json
+│   └── shot-reviews.json
+├── source/
+│   ├── manifest.json
+│   └── src-<name>/v001.<ext>
+├── episodes/ep-001/
+│   ├── episode.json
+│   ├── scripts/v001.(md|txt|json)
+│   ├── script-review/v001.json
+│   ├── director-book/v001.json
+│   ├── asset-plan/v001.json
+│   ├── storyboard/v001.json
+│   ├── production-plan/v001.json
+│   ├── previz/shot-001-v001.json
+│   ├── video-prompts/v001.json
+│   ├── audio-plan/v001.json
+├── assets/{characters,scenes,props,storyboards,audio,videos,other}/<asset-key>/v001.<ext>
+├── editing/ep-001/{timeline.json,review.json}
+└── delivery/ep-001/{final.mp4,final.srt,final.ass,manifest.json}
+```
+
+用户未明确指定其他绝对路径时，新项目统一位于 `~/darma_project/<project-key>`；Dashboard 与 `project-store.mjs init <相对项目目录>` 使用同一默认根目录。新项目还会在项目根创建 `AGENTS.md` 作为 Codex 的项目级恢复入口；若目录已有用户自己的 `AGENTS.md`，初始化不会覆盖。默认目录和自定义绝对目录在初始化完成后都会自动打开对应项目 Dashboard。更换会话时只要从项目根或其子目录打开任务，SessionStart hook 会向上定位 `.short-drama/project.json`、恢复阶段并在 startup/resume 打开对应项目路由；compact 只恢复上下文，不重复开窗。从无关目录打开时必须显式给出项目路径。不要建立跨项目全局记忆，避免旧选版、旧 Provider 或旧阶段污染当前项目。
+
+初始化必须原子创建 `assets.json`、`tasks.json`、`shot-reviews.json` 与 `module-runs.json` 空账本。`format.resolution` 使用“宽x高”，方向必须与 `aspect_ratio` 一致；Provider、模型和 `parameters` 必须通过已注册目录校验。更新 Provider 参数时整组替换，不能残留上一模型字段。
+
+每个版本目录通过 `selected.json` 指向当前入选版本。版本文件不可覆盖；剧本初稿、Humanizer 成稿和后续修改依次产生新版本。`script-review` 必须记录并匹配当前 selected 剧本版本，批准后才允许进入导演本。剪辑、审片和交付必须按 `ep-NNN` 分集保存，禁止多集共用 timeline 或 manifest。复制项目时保留相对路径，删除 `.short-drama/tasks.json` 中仍在运行的外部任务前必须先核对 Provider 状态。
+
+资产计划包含人物时，必须先由 `generate-character-profiles` 生成并确认 `assets/characters/profiles.json`；计划中的每个规范人物名都必须存在于人物档案，不能用资产计划本身冒充人物档案执行证据。
+
+`module-runs.json` 记录每个阶段实际执行的 reference 模块、模块哈希、输入、项目内证据及 `prompt-runs`。用 `module-runs.mjs required` 获取当前阶段要求，由主 Skill 完整读取对应 reference、运行 Codex 合同或 Provider 提示词并完成产物后，再用 `record` 登记。模块、输入、证据或提示词运行记录变化后必须重新执行并登记；旧 `skill-runs.json` 只能由 `module-runs.mjs migrate` 读取迁移。`workflow.mjs <check|advance|complete>` 会重新检查全部已完成阶段。
+
+选中新的来源、剧本、导演本、资产计划、分镜、制作计划、视频提示词或媒体版本，以及更新项目创作/Provider 配置、时间线或完整审片时，脚本会自动回退到最早受影响阶段并清除该阶段及之后的模块凭证；`state.json.invalidatedAt` 保存各受影响阶段的最近失效时间。新模块记录及其提示词运行必须晚于该时间，历史 `prompt-runs` 只供审计，不能重放为当前凭证。交付完成后执行 `workflow.mjs complete`，在 `state.json.finishedAt` 固化终态。
+
+## 生成请求快照
+
+文本资产不调用文本模型。Codex 按当前 reference 模块与 [Codex 原生合同](codex-contracts.md) 直接制作；完成后 `render-prompt.mjs --codex-output` 将合同、合同哈希、完整变量、解析后的约束、实际产物和产物哈希保存为不可变 `.short-drama/prompt-runs/prompt-<uuid>.json`。合同必须由主 Skill 在当前模块中明确选择。只有 `module-map.json` 登记的 `provider_prompts` 能使用 `--output`；脚本会拒绝 Codex 合同与 Provider 提示词混用。
+
+图片、音频 MCP 调用前会自动生成 `.short-drama/requests/req-<uuid>.json`，并在访问 StarRouter 前以请求 ID 登记 `submitting` 任务；视频通过 Hypit `production plan/build` 提交并保留审批与 Build 证据。本地参考文件必须位于当前项目 `assets/` 且逐项等于清单版本的真实路径；TempFile.org URL 必须绑定提交时间点有效的同版本收据。视频必须引用明确的 `{episode_key,version_id,shot_number}` 提示词文档。快照保存实际提交给生成适配器的完整参数并计算稳定输入指纹；快照使用独占创建，不覆盖旧请求，失败和中断请求同样保留。
+
+正式生成图片分别引用当前 `asset-plan` 的资产 key 或 `storyboard` 的镜号，音频逐句引用当前 `audio-plan` 的 `line_index`；入口在付费前核对选版、批准状态、提示词正文、逐字台词和音色绑定。仅 `other-*` 辅助图允许没有独立制作文档。临时发布到 TempFile.org 的参考图另写 `.short-drama/uploads/upload-<uuid>.json`，记录本地资产版本、哈希、公开 URL 与到期时间；`list_reference_uploads` 可跨会话查询有效或过期收据。有效同版本收据默认复用，`force_reupload` 只在用户再次确认延长时效后使用。
+
+生成 Provider、模型及项目级 `parameters` 必须与 `project.json.providers` 的已确认选择一致；调用未显式传参数时使用这里保存的默认值，显式传入不同值时在付费前拒绝。视频提交还会读取当前 selected、approved 且无未决项的 `video-prompts`，逐项核对目标镜号、模型/工作流、提示词正文、profile、输入模式、时长和参考素材清单；账本中的参考资产必须仍是 selected 版本。该校验发生在付费请求之前。
+
+交付 `manifest.json` 当前为 v2：除成片、SRT、ASS 的相对路径、大小与 SHA-256 外，还固定记录 `editing/<episode>/timeline.json` 和已批准 `review.json` 的相对路径、大小与 SHA-256。任一输入或交付文件变化都会使交付门禁失败，必须重新审片并生成新的交付版本。
+
+`.short-drama/tasks.json` 中每个任务必须包含 `requestPath`、`requestSha256` 和 `inputFingerprint`。生成资产只能绑定已完成任务，任务的 `outputVersionId` 必须指回该资产版本；请求、任务和 provenance 的目标、模态、Provider、模型、提示词文档、参数及视频参考素材版本必须一致。项目校验会重新核对这条完整证据链、请求文件 SHA-256 和密钥字段。API Key、Token、Authorization、密码、Secret 或超过 1MB 的内联媒体不得写入请求快照。
+
+## `project.json`
+
+初始化元数据和落盘配置使用相同的 snake_case 结构；`createdAt`、`updatedAt` 由脚本生成，初始化输入省略：
+
+```json
+{
+  "schema_version": 1,
+  "key": "my-short-drama",
+  "title": "短剧名称",
+  "automation_mode": true,
+  "paid_automation_authorized": false,
+  "workflow": { "type": "standard", "version": 1 },
+  "description": null,
+  "format": {
+    "aspect_ratio": "9:16",
+    "resolution": "1080x1920",
+    "fps": 24,
+    "episode_count": 12,
+    "episode_duration_seconds": 90
+  },
+  "languages": {
+    "output": "zh-CN",
+    "spoken": "zh-CN",
+    "subtitle": "zh-CN"
+  },
+  "creative": {
+    "adaptation_mode": "original",
+    "genre": "都市情感",
+    "tone": "现实、克制",
+    "rating": "PG-13",
+    "art_style": {
+      "id": "system-realistic",
+      "name": "真人风格",
+      "description": "真实电影级画面质感，适合标准真人短剧制作。",
+      "prompt": "Realistic cinematic look, real-world scene fidelity, rich transparent colors, clean and refined image quality.",
+      "visualBible": { "version": 1, "palette": {}, "baseline": {}, "lighting": {}, "narrative_arc": [], "motion_language": {}, "negative_constraints": [] }
+    }
+  },
+  "storyboard": {
+    "type": "shot-board",
+    "default_panel_grid_size": 4,
+    "preferred_medium": "blender"
+  },
+  "providers": {
+    "image": { "provider": "starrouter", "model_or_workflow": "gpt-image-2", "prompt_profile": null, "parameters": { "resolution": "1K", "aspect_ratio": "1:1", "n": 1, "quality": "auto" } },
+    "video": { "provider": "starrouter", "model_or_workflow": "dreamina-seedance-2-0-260128", "prompt_profile": "seedance2", "parameters": { "duration": 5, "resolution": "720p", "ratio": "9:16", "generate_audio": false, "watermark": false } },
+    "audio": { "provider": null, "model_or_workflow": null, "prompt_profile": null, "parameters": {} },
+    "music": { "provider": "starrouter", "model_or_workflow": "suno_music", "prompt_profile": null, "parameters": { "make_instrumental": false } }
+  },
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+`automation_mode` 控制项目后续操作的确认策略，默认值为 `true`。开启后，Codex/agent 可自行判断并提交项目内的选版、批量请求范围和重试确认，不再为每一步询问用户；仍须展示制作计划且不计算具体价格，并满足阶段门禁、权限/素材权利事实和安全校验。缺少这些依据时必须停下。设置为 `false` 时恢复逐项确认。
+
+
+未确认的可选值写 `null`，不删除字段，也不使用示例值代替用户决策。例外是新项目画风默认使用 `system-realistic` 完整预设，分镜默认使用 `shot-board`（分镜板）和 4 格；用户可在资产生成前修改。制作计划仍须逐镜在 `single`（单图）、`storyboard`（故事版）和 `shot-board`（分镜板）之间判断，项目默认值只作回退。项目 key 创建后不可变。
+
+## 命名
+
+| 对象 | 格式 | 示例 |
+|---|---|---|
+| 项目 | 小写 kebab-case | `my-short-drama` |
+| 原始资料 | `src-<name>` | `src-original-novel` |
+| 分集 | `ep-NNN` | `ep-001` |
+| 版本 | `vNNN` | `v001` |
+| 人物 | `char-<name>` | `char-linwan` |
+| 场景 | `scene-<name>` | `scene-office-night` |
+| 道具 | `prop-<name>` | `prop-letter` |
+| 故事板 | `board-<episode>-<shot>` | `board-ep001-shot001` |
+| 视频镜头 | `shot-<episode>-NNN` | `shot-ep001-001` |
+| 音频 | `audio-<episode>-<subject>` | `audio-ep001-linwan` |
+| 其他 | `other-<name>` | `other-style-preview` |
+
+key 表示稳定身份，名称、描述和文件可以更新，key 不随版本变化。
+
+## `episode.json`
+
+```json
+{
+  "key": "ep-001",
+  "order": 1,
+  "title": "第一集",
+  "logline": null,
+  "target_duration_seconds": 90,
+  "status": "draft",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+`status` 只能是 `draft`、`approved`、`in-production`、`completed`。
+
+`project.format.episode_duration_seconds` 与 `episode.target_duration_seconds` 都表示策划目标，不是要求成片精确卡秒的硬截止。默认实际成片可在目标值约 ±15% 内自然浮动；超过该范围需要记录叙事原因并重新请用户确认。平台明确规定最大时长时，以平台上限为硬约束。
+
+## 来源与媒体版本
+
+原始资料使用 `project-store.mjs put-source|select-source` 复制到 `source/`，并登记相对路径、文件大小和 SHA-256。原创短剧文本来源支持 txt、md、json、pdf、docx、epub；参考视频复刻统一使用原生 Hypit。分析文档通过 `src-xxx@v001` 引用，不保存原机器绝对路径。
+
+每个媒体版本必须携带：
+
+```json
+{
+  "id": "v001",
+  "localPath": "assets/videos/shot-ep001-001/v001.mp4",
+  "sizeBytes": 12345678,
+  "sha256": "...",
+  "provenance": {
+    "origin": "generated",
+    "created_by": "provider",
+    "provider": "starrouter",
+    "model_or_workflow": "dreamina-seedance-2-0-260128",
+    "task_id": "remote-task-id",
+    "prompt_document": { "episode_key": "ep-001", "version_id": "v001", "shot_number": 1 },
+    "source_assets": [{ "key": "board-ep001-shot001", "version_id": "v001" }],
+    "parameters": { "duration": 5, "resolution": "1080p", "ratio": "9:16" }
+  },
+  "createdAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+`origin` 只能是 `imported`、`generated`、`transformed`。Provider 新生成和生成式改图分别使用 `generated`、`transformed`，两者都必须记录 Provider、模型/工作流、任务 ID 和制作文档引用；本地确定性变换使用 `transformed` + `created_by=codex` 并记录源资产版本，不伪造远程任务。所有引用都使用稳定 key 与明确版本。
+
+资产记录可包含 `staleVersionIds`。项目画风变化时，人物、场景、道具、故事板和视频的既有版本会自动加入该集合并取消选版；已失效版本不能再次选择或通过阶段门禁。重新生成或重新导入应创建新 `vNNN`，不得清除旧版本的失效事实。
+
+## 命令与校验
+
+```bash
+node scripts/project-store.mjs init <项目目录> <项目元数据.json>
+node scripts/project-store.mjs put-source <项目目录> src-original-novel v001 <原文文件>
+node scripts/project-store.mjs select-source <项目目录> src-original-novel v001
+node scripts/project-store.mjs migrate-project-layout <项目目录> ep-001
+node scripts/preflight.mjs <init|media|editing> <项目目录>
+node scripts/render-prompt.mjs --template <合同> --vars <变量.json> --codex-output <实际产物> --project-root <项目目录>
+node scripts/render-prompt.mjs --template <媒体模板> --vars <变量.json> --output <提示词文件> --project-root <项目目录>
+# 已确认重渲染时可追加 --force；不会覆盖 prompt-runs 留痕
+node scripts/snapshot-stage-evidence.mjs <项目目录> <asset-generation|media-production>
+node scripts/validate-project.mjs <项目目录>
+node scripts/workflow.mjs complete <项目目录>
+```
+
+`preflight media` 按 `project.json.providers` 中实际选定的 Provider 逐一检查对应环境变量，不以“任意 Provider 有凭据”代替。每次预检除刷新当前 `environment.json` 外，还会保留带时间戳的历史报告；报告只保存布尔检查结果，不保存凭据。
+
+旧项目只迁移配置时执行 `migrate-project-config`；脚本会先写入 `.short-drama/project.legacy.<timestamp>.json`。旧项目若仍把时间线、审片或成片直接放在 `editing/`、`delivery/` 根目录，执行 `migrate-project-layout <项目> <episode-key>`；脚本只移动不存在冲突的已知文件，并把旧 manifest 保留为 `manifest.legacy.<timestamp>.json`，随后必须重新审片并生成 manifest v2。旧版 `v1` 文件和无 provenance 资产不会被静默改名或伪造来源，必须人工核对后以 `v001` 重新登记。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/prompt-skill-index.md

@@ -0,0 +1,62 @@
+# 本地提示词与模块索引
+
+所有文件都是插件内置静态资产，不依赖外部提示词目录、数据库或业务系统。先读取 [Codex 原生合同说明](codex-contracts.md)：文本类文件是 Codex 执行合同，不再作为 system prompt 发送给另一个 LLM；`module-map.json` 的 `provider_prompts` 才是直接提交媒体模型的模板。主 Skill 按 module ID 决定何时加载哪一份，Codex 每次只处理当前原子步骤。
+
+花括号变量是具名输入槽。文本步骤完成后，用 `node scripts/render-prompt.mjs --template <合同> --vars <输入.json> --codex-output <实际产物> --project-root <项目>` 留存合同、变量和产物；媒体模板用 `--output <本地提示词>` 渲染。输出文件已存在时默认拒绝覆盖；确认需要重渲染可追加 `--force`（提示词运行记录仍不可变新增）。缺少变量或包含密钥字段时失败。
+
+| 原子产物 | 模块 | 模板 |
+|---|---|---|
+| 单集资产分析 | `plan-drama-assets` | `asset_analysis` |
+| 来源与要求分析 | `analyze-drama-source` | `source_analysis` |
+| 创作简报 | `define-drama-brief` | `drama_brief` |
+| 市场创作灵感 | `ideate-drama-from-market` | `market_inspiration` |
+| 场次导演本 | `write-drama-director-book` | `director_book` |
+| 剧本质量复核 | `review-drama-script` | `review_drama_script` |
+| 逐镜制作计划 | `plan-drama-production` | `production_plan` |
+| 跨镜连续性计划 | `plan-shot-continuity` | `continuity_plan` |
+| 艺术风格确认与配置 | `generate-drama-art-style` | `art_style_decision`、`config_generation` |
+| 故事扩写 | `design-drama-bible` | `ai_story_expand` |
+| 分集拆分 | `outline-drama-series` | `episode_split` |
+| 剧本转换 | `write-drama-episode` | `screenplay_conversion` |
+| 剧情片段 | `write-drama-episode` | `agent_clip` |
+| 人物档案 | `generate-character-profiles` | `agent_character_profile` |
+| 人物视觉候选 | `generate-character-images` | `agent_character_visual` |
+| 创建人物描述 | `generate-character-images` | `character_create` |
+| 修改人物描述 | `generate-character-images` | `character_modify` |
+| 重生成人物描述 | `generate-character-images` | `character_regenerate` |
+| 参考图修订人物 | `generate-character-images` | `character_description_update` |
+| 图片反推人物描述 | `generate-character-images` | `character_image_to_description` |
+| 完整角色原画设定板 | `generate-character-images` | `character_asset_sheet` |
+| 场景提取 | `generate-scene-assets` | `select_location` |
+| 创建场景描述 | `generate-scene-assets` | `location_create` |
+| 修改场景描述 | `generate-scene-assets` | `location_modify` |
+| 重生成场景描述 | `generate-scene-assets` | `location_regenerate` |
+| 参考图修订场景 | `generate-scene-assets` | `location_description_update` |
+| 多视角场景原画设定板 | `generate-scene-assets` | `scene_asset_sheet` |
+| 关键道具提取 | `generate-prop-assets` | `select_prop` |
+| 参考图修订道具 | `generate-prop-assets` | `prop_description_update` |
+| 标准道具资产图 | `generate-prop-assets` | `prop_generate` |
+| 分镜规划 | `build-drama-storyboard` | `agent_storyboard_plan` |
+| 摄影设计 | `build-drama-storyboard` | `agent_cinematographer` |
+| 表演设计 | `build-drama-storyboard` | `agent_acting_direction` |
+| 分镜细化 | `build-drama-storyboard` | `agent_storyboard_detail` |
+| 专业故事板约束 | `build-drama-storyboard` | `professional_storyboard` |
+| 插入镜头 | `revise-drama-storyboards` | `agent_storyboard_insert` |
+| 镜头变体分析 | `revise-drama-storyboards` | `agent_shot_variant_analysis` |
+| 镜头变体生成 | `revise-drama-storyboards` | `agent_shot_variant_generate` |
+| 分镜定向编辑 | `revise-drama-storyboards` | `storyboard_edit` |
+| 宫格分镜图 | `generate-storyboard-images` | `panel_grid_image` |
+| 手绘故事板 | `generate-storyboard-images` | `panel_storyboard_image` |
+| 宫格单格增强 | `generate-storyboard-images` | `panel_grid_enhance` |
+| 图片提示词修改 | `transform-drama-media` | `image_prompt_modify` |
+| 二维转真人 | `transform-drama-media` | `2d_to_live_action` |
+| 宫格视频提示词 | `write-drama-video-prompts` | `panel_grid_video` |
+| 故事板视频提示词 | `write-drama-video-prompts` | `panel_storyboard_video` |
+| Seedance 2.0 视频提示词 | `write-drama-video-prompts` | `seedance2_video` |
+| MiniMax H3 视频提示词 | `write-drama-video-prompts` | `h3_video` |
+| 声音分析 | `design-drama-audio` | `voice_analysis` |
+| BGM、OP、ED 音乐创作简报 | `design-drama-audio` | `music_track_design` |
+| 通用音色推荐 | `design-drama-audio` | `character_voice_recommend` |
+| 自然语言音色描述 | `design-drama-audio` | `character_voice_description` |
+
+完整机器可读归属见 `module-map.json`。运行 `node scripts/audit-plugin.mjs` 可验证全部中英文模板、全部模块和人工索引保持一致。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/recreation/publish-drama-references/litterbox.md

@@ -0,0 +1,5 @@
+# 临时发布短剧参考素材
+
+此旧路径保留供已有 Skill 引用；当前唯一支持的临时托管服务是 TempFile.org。只发布项目内当前 selected 且未失效的图片、视频或音频版本，发布前确认素材权利、公开暴露、使用范围和服务条款。默认有效期为 24 小时，先查询并复用同一资产版本的有效收据；强制重传需要重新确认。
+
+临时 URL 只用于 StarRouter 所需的公网参考，不是最终交付资产。项目账本保留素材哈希、资产版本、服务名称、URL 和到期时间，不写入凭据。旧 Litterbox 收据不能用于新请求，过期或服务不匹配时重新走 TempFile.org 发布门禁。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/review/review-drama-script.md

@@ -0,0 +1,7 @@
+# 复核短剧剧本
+
+读取已选剧本、source-analysis、brief、bible、outline，并读取 [合规清单](../writing/compliance-checklist.md)。由 Codex 使用 `../../assets/modules/review-drama-script/prompts/review_drama_script.{zh,en}.txt` 复核，不调用外部文本模型。
+
+把结果保存为 `script-review` 不可变版本并选定。`approved` 仅在来源覆盖、开场、节奏、兑现、对白、连续性、合规与可制作性都通过，且无 P0/P1 问题时为 true。问题必须定位到场次或台词；需要修改时回到 `humanizer` 或 `write-drama-episode` 产生新剧本版本，再对新版本复核，旧报告不得复用。
+
+使用 `project-store.mjs put-episode-document <项目目录> script-review <episode-key> <version> <JSON>` 保存，再用 `select-episode-document` 选定。导演本阶段只接受与当前 selected 剧本版本一致且已批准的报告。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/review/review-drama-shots.md

@@ -0,0 +1,39 @@
+# 验收短剧镜头
+
+人物定妆候选先执行独立的人物视觉专项审核，不能套用普通镜头总分。必须完整检查整张设定板及必要的局部细节；Agent 使用符合主 Skill 体积上限的保真预览和局部裁切完成检查，不直接上传生产原件。审核需写 `review_type:"character-appeal"`、`assetKey`、`versionId`、`watched_or_inspected_full:true`、`approved`、`protection_flags[]`，以及六个不可互相补偿的维度：`age_classification:{status,observation,observed_age_class}`、`identity:{status,observation}`、`grooming_costume:{status,observation}`、`memory_anchors:{status,observation}`、`audience_appeal:{status,observation}`、`art_style_fidelity:{status,art_style_id,observation}`。最后一项绑定项目当前画风，按其 renderingContract 检查媒介/渲染、材质、色彩和光线；不得把真人写实当通用标准，二维、三维、定格、像素及自定义画风分别按自身合同审核。任一维度 failed、年龄观察与档案不符或任何保护标记存在都不得批准。使用 `review-ledger.mjs review-character` 后，脚本才原子选择候选并绑定资产 SHA、人物档案 SHA 与当前画风 SHA；不得直接调用 `asset-ledger select` 绕过。
+
+新生成场景和道具候选执行 `review-ledger.mjs review-visual-asset`，审核写 `review_type:"visual-asset"`、`assetKey`、`versionId`、`inspected_full:true`、`approved`、`structure_identity`、`sheet_consistency`、`unsupported_content` 和同结构的 `art_style_fidelity`。审核观察必须是画面实际可见证据，不得把提示词里的画风名称当作通过证据；画风 ID 或合同内容变化后旧审核哈希自动失效。
+
+每镜的时间故事版与镜头分镜板生成候选后，先用图像查看能力逐张检查完整画面的保真预览；小字、面部、手部、道具或格间细节另做局部裁切检查，不得把生产原件直接上传，也不能只看界面缩略图、文件存在或生成状态。随后结合前后镜、结构化分镜、人物/场景/道具选版和项目画风做整集连续审计。两张板必须分别写审核记录，`criteria` 严格按以下八项原顺序记录 `{criterion,status,observation}`：`空间关系与轴线`、`时间与动作连续性`、`物理与交互逻辑`、`光线与色彩连续性`、`人物身份与造型一致性`、`场景与道具一致性`、`构图与镜头语言`、`叙事覆盖与阅读顺序`。时间故事版重点核对动作阶段与状态变化，镜头分镜板重点核对景别、调度、轴线和叙事节拍；两者仍需完整通过八项。任何一项 failed 都必须修订或重生成后复审，双板全部通过前不得制作正式视频。
+
+分镜审计通过后、视频提示词编译前执行 `plan-shot-continuity`。审计观察必须足以支持人物位置、姿态、运动方向、持物、出入画边、轴线、机位侧和主光锚点；看不清或上下镜冲突的内容进入连续性计划 `unresolved`，不得用主观判断补齐。启用 previous-tail 的下一镜还要确认上一镜结束状态已稳定可读，并与同机位承接相容。
+
+`storyboard_strategy.mode=blender` 的镜头还要完整观看白模分镜，但不能省略双分镜板八维审计。审核记录必须以 `asset_sha256` 绑定正在观看的白模文件，并把 `watch_evidence.duration_seconds` 写成实际探测时长；两者与资产账本或制作计划不一致时不得批准。`criteria` 严格按 `剧情因果与节拍`、`人物调度与表演`、`相机动机与运动曲线`、`构图与视觉层级`、`空间、轴线与连续性`、`物理与接触`、`技术交付` 原顺序记录，并写入对应满分 20/15/20/15/15/10/5 的 `score.breakdown`。同时按导演合同原顺序填写 `hard_gates[]`，每项包含 `gate/status/frame/observation`；任一硬门禁 failed 都不得批准。审核入口会在自动选版前复核导演合同路径与哈希、实际时长/帧率/帧数/分辨率及当前制作计划版本。总分至少 85、每项至少达到该项满分 70%、全部 criteria 和 hard_gates passed，且 `watchedFull` 与首/中/尾证据完整才可批准和选版。
+
+空间检查人物左右、景深层次、出入口、视线、180 度轴线和跨格/跨镜位置；时间检查动作起点—过程—结果、口型/反应先后、道具状态和昼夜；物理检查重力、落脚、接触点、受力、持物、遮挡、镜像及人体结构；光线检查主光来源、方向、影子、曝光、色温和同场景连续性。其余四项分别核对人物身份/服装/年龄、场景结构与道具版本、第七项构图五问（见下段），以及剧情信息是否无遗漏、无重复、按正确阅读顺序呈现。观察必须写出实际可见证据，不能复述提示词或只写“合理”。
+
+第七项「构图与镜头语言」必须按固定顺序回答五个观察问题，并把实际可见证据写进 observation：①首要可读信息——本镜唯一要观众第一眼读到的决定、威胁、关系变化或动作结果是否第一眼读到，有无第二视觉重音争夺注意；②合同实现——分镜构图合同（`visual_plan.composition`、`composition_contract` 或 `photographyPlan.composition`）的主体位置、视线留白、前中后景、光源方向与剧内来源、遮挡比例、景别/焦段与运镜意图（含有无无据推镜、移镜、环绕等 false_camera_motion）、action_vector、tail_state 是否逐项可见兑现，还是只在分镜里复读构图名称；③证据元素——雨、雪、雾、霓虹、镜面/水面、烟尘、门窗廊柱、武器、群体等元素是否都有原文、已选资产或已确认调度依据，画面有无模型自添的高风险元素（对照 ai_risks 风险码）；④相邻连续——轴线、视线、屏幕方向、出入画边、光源方向是否与相邻镜连续，越轴是否有合同或导演调度依据；⑤竖屏安全区——面部双眼、关键道具、接触点是否在中上安全区，底部字幕安全区是否被人物或动作侵占，动势边缘是否留足约 10% 余量。旧分镜无构图合同时，②改按分镜既有摄影意图核对，其余四问照常回答。视频镜头按制作计划 `review_checks` 验收时，其中构图风险项（镜面/水面、雨雾霓虹烟尘、群体人数、多手/武器接触、窄门缝/遮挡、高速拖影、前后夹击、竖屏字幕安全区）同样按这五问取证。五问口径、证据等级与 ai_risks 风险码的权威定义见 [导演构图模式参考](../director-composition.md)（0.2 证据等级、0.4 风险码表与各模式卡片），取证口径或缺陷分级存疑时查阅；审片只记录画面可见证据，不复读构图模式名。
+
+构图缺陷分级固定：构图导致剧情因果、人物关系或动作结果不可读（首要信息被构图/遮挡/光效淹没，动作的地理、蓄力、接触或结果因果不可读，多人关系站位不可辨，竖屏裁切丢失关键元素等）记 P1；构图合同已经兑现、信息完整可读，仅风格强度或氛围不足（模式感偏弱、留白偏空、对称偏呆板等不损信息的问题）记 P2；无证据新增雨、雪、雾、霓虹、镜面、烟尘、门窗廊柱、武器、多余人物等高风险元素，即使画面美观也至少记 P1，并把无据元素与所缺证据写入退回分镜的修订要求，不得在审片端放行或用后期掩盖。
+
+分镜图验收记录使用 `visual=passed|failed`，`audio/transition/captions=not-applicable`，并记录 P0/P1/P2 issues。视频镜头则实际观看完整画面并听完整音轨，按制作计划 `review_checks` 原顺序填写 criteria；缺失关键剧情点必须 failed。用 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/review-ledger.mjs" put <项目目录> <验收.json>` 直接验收未失效候选版本；通过时原子选版，失败时保留为未选候选。
+
+visual 必须 passed；无声音或字幕时使用 not-applicable，不得伪造通过。P0/P1 只修复受影响镜头并重新验收；不得用字幕掩盖错误人声，用长叠化掩盖动作/轴线错误，或用外部 TTS 覆盖要求原生音频的镜头。四项通过且无 P0/P1 后才加入剪辑候选池。
+
+任务回写时脚本会对每条视频成片自动做宫格/分屏启发式检测（`media-tools.mjs detect-grid` 可手工复跑）：高置信命中写 `grid_high_confidence` 并自动禁止批准，中置信命中写 `grid_suspect`，检测环境异常写 `grid_check_failed`。后两类必须实际观看整段素材后二选一——确认是宫格/分屏/拼贴就把 `visual` 判为 `failed` 并按最小变量重生成；确认是结构误报，才在验收 JSON 中写 `grid_check:{"status":"false-positive","observation":"具体可见证据"}` 放行。视频验收必须写 `watchedFull:true`，并使用结构化播放证据 `watch_evidence:{method,duration_seconds,start,middle,end}`；`method` 只能是 `human-playback` 或真正接收视频的 `agent-video-tool`，首/中/尾分别写 `{time_seconds,observation}`，时间必须落在实际媒体对应区间且三条观察不能重复。每个通过的 `criteria[].observation` 还必须引用具体秒数或帧号；仅写“已观看”“动作合理”或由合同批量套出的通用观察会被门禁拒绝。随后在 `continuity` 中逐项以 `status/observation` 记录 `identity`、`screen_direction`、`facing_and_gaze`、`entry_exit`、`end_state`；任一项 failed 都不能选版。
+
+每个缺陷先记录实际症状，再判断最可能的生成机制，并给出只改变一个变量的最小修复；无法从成片区分原因时明确标为待验证，不把猜测写成结论。重生成后对照旧版验证该症状是否消失；同一修复连续失败两次就停止盲重试，回到分镜、参考绑定、提示词或模型能力边界重新定位。
+
+H3 原生音频镜头在候选选版后整集批量审计：先跑 `node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/native-audio-audit.mjs" audit-episode <项目> <ep-001>` 取待审计清单（自动跳过无 speech_timeline、未选版和已按当前 sha256 审计过的镜头），向用户展示 ASR 模型、镜头数和请求次数，不计算具体价格；确认后加 `--confirmed` 顺序执行。单镜重生成后用 `audit <项目> <ep-001> <镜号> <视频资产 key> <候选版本> --confirmed` 单审。默认使用 StarRouter `qwen3-asr-flash`（可用 `STARROUTER_ASR_MODEL` 改为 `whisper-1`）核对 speech_timeline 的对白文本、说话人和时间偏差；接口未返回时间戳或说话人时不能自动通过，命令对未通过项返回非零退出码。再人工核对统一 music_anchor 和相邻 transition_pair；任一对白错位、音乐断层或声音桥不成对都记为 audio/transition 缺陷，不用后配音静默掩盖。
+
+审片不可只看首帧、联系表或任务状态：逐镜至少按 0.5–1 秒间隔抽查，并对关键动作的入点、接触点、完成点和镜尾逐帧复核；记录实际观察而非复述提示词。整集审片必须完整观看和听完，六个维度分别填写观察；“计划写了动作”不能作为“画面已经实现”的证据。整集剪辑审查还要在每个转场的前一帧、精确切点、淡化中点和完成帧抽检，单帧黑闪、跳轴或动作断裂即记为 P1，即使长时段黑帧/静音检测没有报警；标为 action-cut 的接缝还必须检查地点、主体姿态、运动方向和道具状态，任一突变均不能按动作连续通过。
+
+视觉复核还要逐项检查：非有意空镜是否把开头浪费在主体到场；物理交互中手、道具和目标是否都发生了计划中的状态变化，邻接物是否错误跟随；多人镜人数、左右顺序、朝向和肢体归属是否稳定；人物离画后的边、最后姿态、运动方向和持物状态是否延续到重新入画，是否无依据从错误一侧返回；步行是否有落脚、重心转移、方向与同行相对位置；跨镜动作或打斗是否在切点重置姿势和速度；缺少可信运动参考时，打斗是否用招式名称冒充编排而没有可读的身体位置、蓄力、接触点、受力结果和反应；焦点是否锁在叙事对象上，是否出现无动机拉焦或自动对焦漂移。任何一项影响剧情因果、人物身份或动作完成态都记为 P1。
+
+自然运动复核必须在完整播放和关键帧慢看中另行取证：多人是否无剧情依据地同帧转头、点头、眨眼、起步或做相同手势；静止人物是否像定格图，或相反出现周期性眨眼、重复摇摆等机械微动；眼神是否真正追随注意对象；动作是否有支撑脚、重心转移、加减速、惯性跟随和恢复；头发、衣摆、宽松袖口、饰物与道具是否由风、加速、重力或接触驱动，并以较小延迟运动衰减，而不是无风自飘、全身同相或瞬停；环境响应是否有可见作用因果；固定机位是否发生无动机漂移。明显破坏人物表演或动作可信度记 P1；仅有不抢戏的轻微幅度偏差记 P2。失败时只改对应主体的起始时刻、反应延迟、物理链或次级运动之一，不用再堆“更自然”后原样重试。
+
+眼神与心理表演还要逐节拍核对：刺激或信息是否先出现，眼神是否落在正确对象和屏幕方向，眼睛/头部启动关系是否自然，画外目标是否跨镜保持轴线；非主观镜头或直视观众镜头是否错误看镜头；说话者表情转折是否发生在具体词、停顿、声音或事件之后，听者是否有独立注意和反应；表情面具、短暂泄露、决定和残留是否存在可见因果。近景/特写检查微表情是否只改变一至两个区域并完成起势—峰值—释放，是否出现整脸同时抽动、表情长时间冻结、面部漂移或身份变化；中远景不得因看不清微表情而宣称通过，应改查头部、呼吸姿态、停顿、距离和走位。档案习惯动作若无触发条件却重复出现、或命中 `forbidden_performance`，至少记 P1；无证据编造心理事实同样退回分镜和提示词阶段。
+
+同一角色跨镜对白必须核对基础声纹、年龄感、性别、口音、音高和语速；未来来电与当前人物只能在电话带宽/空间效果上不同。声纹主体不同属于 P1，不能用“来自未来”解释通过。
+
+若当前 Agent 或工具链不能实际接收视频或音频，不得把解锁电脑、联系表、波形、ASR 或技术探测冒充完整观看/复听，也不得在心跳中重复等待。先完成可独立执行的画面筛查、技术 QC 和最小修复，再生成一次人工验收交接，逐镜列出本地文件、精确时间点、待确认维度和已排除的技术问题；通知用户一次后，仅暂停依赖该模态的审核单元，其他镜头工作继续。只有用户实际观看/复听确认或具备对应模态能力的工具留下证据，才能填写 `watchedFull`、声音维度和正式选版。

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

@@ -0,0 +1,33 @@
+# RunningHub Provider 合同
+
+> 历史合同，仅用于读取旧任务与审计证据。短剧插件当前禁止 RunningHub 提交；下述工作流、环境变量、冒烟命令和确认步骤不得用于新制作。
+
+RunningHub 既支持用户自己的通用工作流，也内置迁移自现项目的 Krea2 图片、MiniMax H3 视频和 SeedVR2.5 视频超分工作流：
+
+- 环境变量：`RUNNINGHUB_API_KEY`、可选 `RUNNINGHUB_BASE_URL`，以及通用工作流的 `RUNNINGHUB_IMAGE_WORKFLOW_ID`、`RUNNINGHUB_VIDEO_WORKFLOW_ID`、`RUNNINGHUB_AUDIO_WORKFLOW_ID`。Krea2 默认工作流 ID 为 `2096515700701929473`，可用 `RUNNINGHUB_KREA2_WORKFLOW_ID` 覆盖；H3 默认平台工作流 ID 为 `2086743729407733762`，可用 `RUNNINGHUB_H3_WORKFLOW_ID` 覆盖。
+- 本地参考素材先上传到 `/openapi/v2/media/upload/binary`。
+- 任务提交到 `/task/openapi/create`，查询使用 `/openapi/v2/query`。
+- 同一 API Key 的图片、视频和音频提交共用 2 个并发槽位；超出的请求在适配器内等待，任务查询不占用提交槽位。
+- `node_info_list` 由工作流定义决定；字段值可使用 `@prompt` 和 `@asset:0`、`@asset:1` 等占位，提交前由适配器替换。
+
+内置视频超分使用 `operation=video-upscale`、`model=seedvr2.5-video-upscale`，工作流固定为 `2099866760106491906`，不接受环境变量替换或手写 `node_info_list`。仓库映射来自 RunningHub 官方 `getJsonApiFormat` 导出，输入固定为节点 `25` 的 `video` 字段，输出固定为节点 `27` 的 `VHS_VideoCombine`；适配器只上传当前 selected 视频并覆盖这一项，禁止空节点试错或借用其他 SeedVR 工作流。该命名能力只列入 transform 目录，不列入普通视频生成模型。
+
+超分完成后先保留 Provider 原始输出，再检查时长和帧率是否与来源一致；工作流映射未声明会改变这两项，因此漂移会被拒绝。若来源有音轨而 Provider 输出缺失，回写器以视频流复制和源音频 AAC 封装生成最终候选，并在 provenance 中同时记录原始输出版本/哈希和源音轨版本/哈希。候选仍不自动选中：必须做结构化 QC、完整观看并覆盖 `resolution,duration_fps,audio_preservation,faces_hands_text,motion_artifacts,color_crop` 六项专项观察。
+
+真实冒烟先运行不带 `--confirmed` 的摘要命令：
+
+```bash
+node scripts/generation/live-smoke-test.mjs runninghub seedvr2.5-video-upscale "$SEEDVR25_PROJECT_ROOT" "$SEEDVR25_ASSET_KEY" "$SEEDVR25_VERSION_ID"
+```
+
+摘要会列出 selected 资产、SHA-256、时长、分辨率、帧率、音轨、上传事实、固定工作流和节点覆盖，不计算具体价格。只有用户针对这份制作计划再次确认后才追加 `--confirmed`，随后轮询同一个任务 ID，禁止失败后静默重提。
+
+内置 H3 使用 `model=minimax-h3-reference-to-video`，不要求 `node_info_list`。本地 `reference_image_paths`、`reference_video_paths`、`reference_audio_paths` 会依次上传并注入内置 ComfyUI workflow；图片 0–9 张、视频 0–2 段、音频 0–2 段，纯文本零媒体也可用。Hypit 原生 Runtime 的有效时长不得低于 5 秒，画幅为 `16:9|9:16`，模型分辨率严格使用 `768P|2K`，不得把旧 MCP 的 `480p|720p|1K` 配置静默折算。工作流同时生成视频与原生音频。
+
+内置图片使用 `model=krea2-normal-v1`，不要求 `node_info_list`。适配器把 prompt 注入节点 5，并按 `resolution=1K|2K` 与 `aspect_ratio=1:1|16:9|9:16|3:4|4:3|2:3|3:2` 设置节点 8；当前普通工作流不接受参考图。
+
+选择 RunningHub 前，用户必须确认工作流 ID、覆盖节点、参考文件、请求数量和输出模态；门禁不计算具体价格。视频还必须传入已选 `prompt_version`、prompt_profile、input_mode 和 reference_manifest；MiniMax H3 工作流必须使用 `h3` 及其真实 T2VA/I2VA/FL2VA/L2VA/Ref2VA 模式。T2VA 不带素材，I2VA/FL2VA/L2VA 分别绑定首帧、首尾帧、尾帧，Ref2VA 使用与类型一致的 `reference_image/reference_video/reference_audio`；适配器会在上传前核对数量、顺序和角色。插件不猜测节点 ID，也不把某个工作流的 schema 当成通用协议。查询任务时显式传 `media_type`，返回统一 `outputs[]`；全部远程输出仍必须下载进本地资产库。
+
+通用图片工作流使用 `reference_paths` 时还必须提交等长 `reference_manifest`，逐项绑定本地 selected 图片版本和用途；清单只用于本地审计，不注入 RunningHub 节点。
+
+通用对口型工作流若没有独立的时间范围节点，`submit_media_operation` 只从 selected 源镜头抽取台词前后约半秒的上下文窗口，避免 1080p 长镜头在 PainterAV2V 采样阶段耗尽显存。窗口扩展到 4 帧栅格，并额外补一个克隆尾帧，使工作流丢弃尾帧后的帧数可被 4 整除；插件只在 `.short-drama/provider-input` 创建 CFR 派生副本，不覆盖账本源资产。已审核 selected 配音以前导静音对齐窗口内台词起点并补尾到 Provider 输入时长。远端返回后，回写器校验分辨率、帧率和最小帧数，按精确帧号把窗口拼回完整 selected 源镜头并保留源音轨；Provider 原始窗口与最终整镜候选分别留证。请求快照和输出 provenance 必须记录 `provider_video_preparation`、`provider_audio_preparation` 与 `output_processing`，专项审核仍要完整观看范围内外、口腔伪影、身份和时长。