@lemoncat7/dsh-partner 2.4.2 → 2.7.0

package/resources/skills/drama-production/upstream/skills/short-drama-novel-analyze/scripts/selftest.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Offline self-test for the standalone novel index."""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+from novel_index import build_index, sample_chapters, verify_index
+
+MINIMUM_PYTHON = (3, 9)
+if sys.version_info < MINIMUM_PYTHON:
+    raise SystemExit("selftest.py requires Python 3.9 or newer")
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as directory:
+        root = Path(directory)
+        source = root / "novel.txt"
+        index_path = root / "index.json"
+        source.write_text(
+            "第一章 起势\n"
+            + "人物做出选择，代价随之发生，旧关系因此失衡，新的目标也被迫提前。" * 4
+            + "\n第二章 反转\n"
+            + "旧承诺被新的证据推翻，人物必须在名誉与家人之间付出不可逆的代价。" * 4
+            + "\n",
+            encoding="utf-8",
+        )
+        index = build_index(source)
+        require(index["chapter_count"] == 2, "chapter count")
+        require(index["problems"] == [], "valid chapter index")
+        index_path.write_text(json.dumps(index, ensure_ascii=False), encoding="utf-8")
+        require(verify_index(index_path, source)["verified"] is True, "fresh index")
+        require(sample_chapters(index_path, 2)["sampled_count"] == 2, "sample count")
+
+        source.write_text(source.read_text(encoding="utf-8") + "变化\n", encoding="utf-8")
+        require(verify_index(index_path, source)["verified"] is False, "source drift")
+
+    print("5 self-tests passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/resources/skills/drama-production/upstream/skills/short-drama-produce/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: short-drama-produce
+description: 在创作者明确确认后，执行短剧项目的图片、视频、TTS/配音或时间线音乐生产任务，并把结果与精简运行记录落回项目。用户说“生成这张图/这段视频/这句配音/这段配乐”“开始跑图/跑视频/合成语音/生成音乐”“把已确认提示词送去生产”，或要求批量执行已确认媒体任务时使用；不负责创作提示词、镜头、台词、歌词或声音身份，也绝不把预览、继续、预算说明或既有接受状态当作本次付费生产确认。
+license: MIT
+---
+
+# 确认后生产
+
+本技能只负责把已经写好的生产规格安全送到运行环境配置的 adapter。图片提示词仍归
+`$short-drama-image-prompts`，视频提示词归 `$short-drama-video-prompts`，台词与录音表归
+`$short-drama-write`，声音身份归 `$short-drama-assets`。
+
+## Quick Start
+
+只在用户明确要求实际生成后，从当前 `图片提示词.md`、`分镜.md` 或 `视频提示词.md` 中
+取出本次提示词，建立一个有边界的运行 job。creator-first job 的 `source` 必须指向拥有这条提示词的
+当前 Markdown，`source_entry` 必须点名该文档允许的二级标题：`图片提示词.md` 用 `IMG-*`，
+`视频提示词.md` 用 `MOTION-*`，`分镜.md` 用 `SHOT-*`（modality 为 `image`，正文取该镜的
+`### 冻结关键帧提示词`）。此选择器只提取首帧；尾帧需先由图片提示词阶段建立独立 `IMG-*` 状态图条目，
+再从 `图片提示词.md` 准备 image job。创作者也可以提供已有起始帧——
+在自己的工具里出图再放进项目同样成立，图片始终不进项目时走分镜的 `PLAN-...`；
+产出落在 `剧集/<EP>/制作成果/images/` 后，分镜 owner 才能把它绑成 `用途：起始帧` 的 `REF-...`。存在真实参考图时，
+还必须逐张填写 `reference_bindings` 的槽位、顺序、路径、中文名、用途以及允许/禁止控制范围；
+内置视频 adapter 把这里的 `用途` 字段读成供应商自己的 role，只接受它公布的取值
+（MiniMax 为 `first_frame`/`last_frame`/`reference_image`/`reference_video`/`reference_audio`，
+Seedance 为三个 `reference_*`）；带参考图却没有绑定的 job 会直接失败，不替它猜一个 role。
+本地图片由内置 adapter 按 base64 data URI 直接送出，不需要自建上传服务。
+条目的「输入参考图」写成 `PLAN-...` 时，那些图片在创作者自己的工具里，项目内没有文件可送：
+`prepare` 直接失败并说明先把真实文件放进项目、改写成 `REF-...`，不拿计划当输入，也不静默丢掉参考。
+`references` 可以省略并由绑定顺序生成，也可以作为相同顺序的显式镜像。输出放在
+`剧集/<EP>/制作成果/`；这个 job 是生产工具的临时输入，不是第六份创作文档：
+
+```bash
+python3 {技能目录}/scripts/production_tool.py prepare <project> --job <临时-job.json>
+```
+
+先展示 `prepare` 的完整预览；此时不会调用供应商。
+
+## 硬闸门
+
+每次生产都必须经过以下四步，顺序不可合并：
+
+1. 建立一个有边界的 job：一种 modality、明确数量、完整 prompt/spec、参考文件、参数、输出路径和 adapter profile。
+2. 运行 `prepare`，把返回的完整预览展示给创作者，尤其是数量、prompt、source entry、
+   reference bindings、references、outputs、overwrite 与 adapter。creator-first job 会在这一步机械核对
+   所选标题里的可复制提示词，以及参考图槽位、顺序、路径、中文名和控制边界；任一漂移都 fail closed。
+3. 等创作者在**看到这份预览之后**明确确认。只有明确同意这项当前任务，才运行 `confirm`；
+   “继续”“都做完”“预算没问题”、上游内容已接受或之前确认过另一版，都不算本次生产确认。
+4. 运行 `run`。它会在启动 adapter 前消费一次确认；成功或失败后再次执行都必须重新确认，
+   防止失败重试意外产生第二笔费用。
+
+job、prompt、参数、输出路径或直接输入任一变化，旧确认立即失效。不得代替创作者填写确认。
+当前已确认 job 是本轮唯一工作单元；运行结束后回报结果并交还控制权，不自动准备下一批或启动审查。
+
+`分镜.md` 的「输入参考图」路径只是创作阶段的可读依据与使用意图，不是生产输入快照。进入生产时，
+creator-first job 必须从 `图片提示词.md` 或 `视频提示词.md` 的对应条目建立绑定；`prepare` 展示的
+`reference_bindings`、`references` 与已确认 job 才是本次 adapter 实际读取哪些文件字节、各自允许
+影响什么的权威。非 creator 的结构化规格可不填 `source_entry`/`reference_bindings`，继续只使用显式
+`references`；但新的 image/video job 只要 `source` 指向 canonical `图片提示词.md` 或
+`视频提示词.md` 就强制使用对应 selector，不能靠省略字段降级绕过。升级前已经 prepare 并落盘的
+旧 job 仍可按原指纹读取。
+新生产结果不自动回填或刷新分镜；需要把它改为后续输入时，由分镜 owner 修订文档，再建立新 job
+并重新预览、确认。
+
+## 命令
+
+只在进入生产边界后把当前提示词和运行参数写成临时 JSON；视频与图片 job 的
+`parameters.prompt_language` 跟随当前可复制正文已经解析出的提示词语言，使 adapter 追加的参考约束
+使用同一种语言，而不是重新回退成固定英文。不要在创作阶段为每条提示词预建 job。
+格式和 adapter 契约见
+[adapter-contract.md](references/adapter-contract.md)。命令由
+[production_tool.py](scripts/production_tool.py) 提供，然后运行：
+
+```text
+python3 <本技能目录>/scripts/production_tool.py prepare <project> --job <job.json>
+python3 <本技能目录>/scripts/production_tool.py confirm <project> --job-id <id> --confirmation "CONFIRM <id> <code>"
+python3 <本技能目录>/scripts/production_tool.py run <project> --job-id <id> --adapter-config <outside-project-config.json>
+python3 <本技能目录>/scripts/production_tool.py status <project> --job-id <id>
+python3 <本技能目录>/scripts/production_tool.py collect <project> --job-id <id> --adapter-config <outside-project-config.json>
+python3 <本技能目录>/scripts/production_tool.py audit <project>
+```
+
+`prepare` 只验证并预览，不生产。`confirm` 只保存与当前 job 指纹绑定的一次性确认。
+`run` 才启动 adapter。`collect` 只取回**已经提交过、已经计费**的那次任务的结果，
+不重新提交、也不需要新的确认——见下面「中断不等于要重跑」。`audit` 只对账本地任务历史、失败后恢复、重复内容尝试和当前输出字节，
+不会调用供应商，也不把技术成功、文件存在或哈希一致写成媒体质量结论。同一 job 存在未决
+`running` attempt 时禁止重新 prepare、confirm 或 run；先等待完成或排查遗留 attempt。
+
+## 输入选择
+
+- **image**：读取 `图片提示词.md` 的当前 `IMG-*` 可复制正文，或 `分镜.md` 的当前 `SHOT-*`
+  冻结关键帧正文，加上必要参考图和明确的输出尺寸/数量；creator-first job 使用 `source_entry`
+  锁定这一条。资产板走 `IMG-*`，某一镜的起始画面走 `SHOT-*`；两者不互相替代。
+- **video**：读取 `视频提示词.md` 的当前 `MOTION-*` 可复制正文，并核对 `分镜.md` 中对应镜头、
+  冻结关键帧、时长与画幅；creator-first job 使用 `source_entry` 锁定这一条。连续段选择从上一段
+  生成结果续接时，下一段 job 同时绑定上一段实际视频和从该视频取得的实际尾帧，并保留
+  `continuity_video`、`actual_tail_frame` 的不同职责；供应商 role 由目标模型 adapter 翻译。H3 的这组
+  输入统一译为 `reference_video + reference_image`，不能混成 `reference_video + first_frame`；不以
+  计划尾帧或文字描述代替真实文件。
+- **tts**：从 `剧本.md` 读取原句与表演要求，声音参考由用户或现有媒体明确提供。不得在生产 job
+  中改词，也不为 TTS 新建第六份创作文档。
+- **music**：读取 `视频提示词.md` 中创作者已确认的时间线音乐章节；主题曲使用已确认歌词，纯配乐
+  不携带歌词。供应商不能精确承诺时长时，生成源音轨后仍由 `$short-drama-edit` 按文档里的混音意图完成落点、
+  循环、淡入淡出和对白 ducking。
+
+一个 job 不混合 modality。大批量工作拆成创作者能看清数量和成本边界的小 job；不为方便把整季
+隐式塞进一次确认。
+
+## Adapter 边界
+
+adapter 配置必须在项目外，只包含 argv 命令和超时；凭据由 adapter 自己从进程环境或系统凭据
+存储读取。项目 job、确认记录、运行记录和 Dashboard 都不得保存密钥。
+
+脚本以 JSON stdin 调用 argv 数组，不使用 shell，不拼接命令。adapter 返回本地临时文件；工具只
+接受与已确认 targets 完全一致的结果，并把完整文件原子复制到项目的 `剧集/<EP>/制作成果/`
+目录。项目和上游 Skill 不写死供应商、模型或即将变化的 API。
+
+内置图片/视频 compiler 会根据已确认的 `reference_bindings`，按顺序向供应商 prompt 附加一段确定性的
+引用语义说明（中文名、用途、允许控制与不得控制范围）；不会把槽位名误当成要渲染进画面的文字。
+外部 adapter 也必须保留这组语义或明确拒绝，不能只上传文件而静默丢失控制边界。
+
+本技能可选提供四个 stdlib adapter，均通过项目外 adapter config 选择，凭据只从运行环境读取：
+
+- [Seedance](references/providers/seedance.md)：模型/Endpoint ID 必须由账号显式配置；compiler 支持
+  官方图片、视频和音频参考 role，内置 runtime 未配置可信上传时仍拒绝本地参考文件。
+- [GPT Image 2](references/providers/gpt-image-2.md)：无参考图走 generation，有参考图走 edit；
+  固定高保真引用并校验尺寸、格式与透明背景限制。
+- [MiniMax Music](references/providers/minimax-music.md)：使用 `music-3.0` 与 hex 结果，区分主题曲
+  和纯配乐，不伪造时长请求字段。
+- [MiniMax 语音](references/providers/minimax-speech.md)：`tts` 模态；模型与 `voice_id` 都必须
+  由账号与文档显式给出，不内置音色清单。只从预置音色合成，不做声音克隆——克隆是授权问题，
+  创作者授权的参考录音按普通创作者输入走 `输入/`。
+- [MiniMax H3 视频](references/providers/minimax-h3-video.md)：模型 ID、分辨率集合与时长区间必须
+  由账号显式配置；提示词进 `content` 的 text 项，参考图按显式 role 绑定，本地参考在没有可信上传时
+  fail closed。该模型与画面同一次生成声音，写法影响见视频提示词技能的目标模型能力档案。
+
+这些 adapter 是已验证请求契约，不是账号可用性或生成质量保证；正式生产仍必须通过上面的本次
+确认闸门，并由审查 Skill 判断产物质量。
+
+仓库自带 `fixture_adapter.py` 只用于离线测试，不代表真实生成质量或默认生产 adapter。
+
+## 中断不等于要重跑
+
+视频任务在**提交那一刻**就已经计费，不是在拿到结果时。提交之后的一切——轮询几分钟、下载——
+都可能被进程被杀、断网、机器休眠打断。内置 adapter 因此在拿到供应商任务 ID 的第一时间就把它
+写进 `handle_path`（早于第一次轮询），这个路径不随本次尝试一起删除。
+
+于是中断之后有三条确定的动作，不必再花一次钱：
+
+1. `audit` 会把带着任务 ID 的未完成尝试报成 `orphaned_provider_job`，
+   `action` 是 `collect_before_retry`；
+2. `collect` 用那个 ID 取回结果并把这次尝试标成成功；
+3. 只有在 `collect` 也确认那边确实失败之后，才走重新确认与重投的老路。
+
+**不要在 `audit` 报出 `orphaned_provider_job` 时直接重投**——那是在为同一个镜头付第二次钱。
+`collect` 不走确认闸门是有意的：闸门防的是意外花钱，而 collect 不花钱；
+如果它也要求重新确认，那么中断之后最省事的路径就变成再付一次，正好是闸门要防的事。
+
+## 结果与复核
+
+成功后回报实际输出路径、媒体类型和运行状态；不要把“adapter 返回成功”写成质量结论。
+多任务或重试后先运行 `audit`：终态失败按 `retryable` 路由，重试仍须新的明确确认；输出缺失或
+文件的哈希或大小不再等于运行记录时，先复核当前字节或重新生产。`repeated_content` 只是成本与诊断信号，
+不能自动判定同文重试合理或不合理；`running_attempt` 是未决运营状态，audit 必须返回 attention。
+失败按三路走。超时、限流、服务端错误这类技术失败可做有上限重试。失败信息点名了被拒的是哪
+一项输入——提示词文本、参考图或音频——就先改那一项再投：文本被拒改写那一句，把「一拳砸在
+对方脸上，血顺着下巴滴」换成「一拳挥空，对方侧身避开，桌上的杯子被带倒」；参考图被拒换一张
+构图与角色一致、画面本身合规的图；音频被拒重录那句台词。改动写进新的 job 重新 prepare，让创
+作者在预览里看到改的是哪一项再确认；原样重投的那次确认不产生修复，只产生一笔费用。重复内容
+缺陷回到对应 prompt/spec owner。
+生产结束后不自动进入剪辑。素材要装配成成片时由用户点名 `$short-drama-edit`；它只取舍已有帧，
+不回头改本阶段的 job，也不生成新素材。
+如需质量复核，报告可把已有结果另行交给 `$short-drama-review`；不要在生产调用中自动启动复核。
+Dashboard 只负责展示这些文件和运行摘要，不提供 adapter 设置或生产按钮。
+
+## 安装维护
+
+只有安装、升级或排障时运行离线自检；普通创作和生产准备不运行：
+
+```bash
+python3 scripts/selftest.py
+python3 scripts/provider_adapters.py --selftest
+```

package/resources/skills/drama-production/upstream/skills/short-drama-produce/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "短剧生产"
+  short_description: "确认后安全执行图片、视频和语音生产任务，并保留可审计运行记录"
+  default_prompt: "Use $short-drama-produce to preview a bounded media job, request explicit confirmation, then execute it safely."

package/resources/skills/drama-production/upstream/skills/short-drama-produce/references/adapter-contract.md

@@ -0,0 +1,219 @@
+# Adapter Contract
+
+## Job file
+
+```json
+{
+  "schema_version": "1.0",
+  "job_id": "EP001-MOTION001-video",
+  "modality": "video",
+  "adapter": "studio-video",
+  "prompt": "the exact copyable prompt from MOTION-EP001-001",
+  "source": "剧集/EP001/视频提示词.md",
+  "source_entry": "MOTION-EP001-001",
+  "reference_bindings": [
+    {
+      "slot_id": "REF-HERO",
+      "order": 1,
+      "path": "输入/approved-character-reference.png",
+      "label": "女主定妆照",
+      "role": "reference_image",
+      "may_control": ["身份", "造型"],
+      "must_not_control": ["构图", "动作"]
+    }
+  ],
+  "references": ["输入/approved-character-reference.png"],
+  "outputs": ["剧集/EP001/制作成果/video/SHOT-EP001-001.mp4"],
+  "parameters": {"duration": 5, "ratio": "9:16", "prompt_language": "zh-CN"},
+  "overwrite": false
+}
+```
+
+- `modality`: `image`, `video`, `tts`, or `music`. `tts` is one bounded spoken
+  utterance; `music` is a separately accepted timeline-level cue or song and
+  must not be smuggled into every shot's video job.
+- `source`: optional current project text/spec that owns the prompt.
+- `source_entry`: for a creator-first job, the exact uppercase H2 ID inside a
+  canonical `剧集|episodes/<EP>/` creator document, matched to that document:
+  `图片提示词.md` takes `IMG-*` (image), `视频提示词.md` takes `MOTION-*` (video),
+  and `分镜.md` takes `SHOT-*` (image, whose prompt is the shot's
+  `### 冻结关键帧提示词` body rather than `### 可复制提示词`). A new image/video job pointing to either canonical filename must
+  provide the matching selector; an arbitrary Markdown file cannot impersonate a
+  creator source. `prepare` selects that section and requires `prompt` to exactly
+  equal its copyable prompt after Markdown quote markers are removed.
+- `reference_bindings`: zero to sixteen ordered semantic bindings. Every entry has
+  exactly `slot_id`, contiguous `order`, project-relative `path`, Chinese `label`,
+  non-empty `role`, and non-empty `may_control` / `must_not_control` lists. When
+  `source_entry` is present, these fields must exactly match that entry's
+  `参考` (IMG) or `输入参考图` (SHOT/MOTION) declaration (except `role`, which is
+  production metadata). Allowed and prohibited scopes may not overlap.
+  The creator declaration also carries a `用途` — what this picture decides in
+  this shot, from the closed set in the storyboard skill. `role` is its
+  production-side translation and is chosen per provider, so the two are not
+  compared; a binding whose `role` contradicts the declared `用途` is a defect
+  the creator document, not this schema, is the authority on. This schema keeps
+  `role` free-form because an external adapter names its own inputs, but the
+  bundled video adapters read it as the provider's own role and accept only
+  their published vocabulary: `first_frame`, `last_frame`, `reference_image`,
+  `reference_video`, `reference_audio` for MiniMax, and the three `reference_*`
+  values for Seedance. A video job carrying references without bindings fails
+  closed there rather than having a role guessed for it.
+- `references`: zero to sixteen current project files actually sent to production.
+  It may be omitted when `reference_bindings` is present, in which case the paths
+  are derived in binding order. If both are present, they must match exactly.
+- `outputs`: one to sixteen unique paths rooted at top-level `production/` or
+  `剧集|episodes/<EP>/制作成果|production/`; extensions must match the modality.
+  A nested directory merely named `production` does not grant write access to
+  protected input or delivery trees.
+- `parameters`: provider-neutral public settings only. Image/video jobs carry the resolved
+  `prompt_language` so a bundled compiler writes its appended reference contract in the same
+  language as the copyable prompt; this execution-only setting is not forwarded as a provider
+  request field. Secret-like keys are rejected.
+- `overwrite`: must be explicitly true to replace an existing result.
+
+`prepare` records internal digests of source/reference bytes and returns the exact confirmation phrase. Callers never
+calculate those digests. A changed input requires prepare and confirmation again.
+Jobs already prepared and stored before this contract remain readable under their
+original fingerprint. New non-creator structured jobs remain valid without
+`source_entry` and `reference_bindings`; they still receive the existing
+path/digest/confirmation checks. A `music` job may continue to use the timeline
+music section of canonical `视频提示词.md` without pretending that section is a
+`MOTION-*` entry; other new image/video jobs using canonical creator paths must use
+their matching selector.
+
+## Adapter config
+
+Keep this file outside the project:
+
+```json
+{
+  "adapters": {
+    "studio-image": {
+      "command": ["python3", "/opt/studio/image_adapter.py"],
+      "timeout_seconds": 600
+    }
+  }
+}
+```
+
+`command` is an argv array, never a shell string. Timeout is 1–3600 seconds. Do not put credentials in this file;
+let the adapter read its environment or operating-system credential store.
+
+## Capability sources
+
+Use the provider's current API reference for roles, limits and supported combinations.
+A relay can expose a different subset, reject inputs itself or transform requests.
+Record the tested execution path and distinguish its observations from the native API contract.
+
+## Adapter stdin
+
+The adapter receives one UTF-8 JSON document as raw stdin bytes. Read the
+binary stream (for example `json.load(sys.stdin.buffer)`) rather than relying
+on the machine locale. The document contains the confirmed job plus:
+
+- `run_id`: unique attempt ID;
+- `project_root`: local absolute path to a private, run-scoped snapshot containing
+  the exact confirmed `source` and `references`. It is not the live creator
+  project and is deleted after the attempt.
+- `output_root`: empty private, run-scoped staging directory owned by the
+  production tool. Every adapter output source must be a direct regular-file
+  child of this directory. The whole directory is deleted after success or
+  failure.
+- `handle_path`: absolute path where the adapter records the provider's task id
+  **as soon as it has one, before it starts polling** — write
+  `{"provider_job_id": "<id>"}`, atomically. Unlike `output_root` this path
+  survives the attempt.
+- `collect_provider_job_id`: present only on a collect call. When it is set the
+  adapter must **not submit anything**; it polls and downloads that existing
+  task and returns its outputs as usual.
+
+## Recovering a submitted task
+
+Record the provider task ID before polling so an interrupted task can be collected without resubmission.
+A local handle-write failure is non-fatal after submission. The tool copies the handle into the attempt
+record on success or failure; `audit` reports unfinished tasks as `orphaned_provider_job` with
+`action: collect_before_retry`.
+
+`production_tool.py collect` retrieves the existing task without new submission or confirmation.
+
+It may translate provider-neutral parameters into its chosen SDK/API. Optional
+provider adapters under `scripts/` document and implement known translations;
+the project job remains provider-neutral, and adapter selection, model access,
+polling and credentials stay in the external runtime configuration.
+
+The confirmed document includes `source_entry` and `reference_bindings`. Bundled
+image/video compilers append an ordered reference contract to the provider prompt so the Chinese
+label, role, allowed controls, and prohibited controls survive the handoff. Its prose follows
+`parameters.prompt_language`; model-native compilers also use that model's actual reference tokens,
+such as Seedance `@图片1` or H3 `<Picture 1>`, rather than adding a second generic numbering scheme.
+External adapters must preserve equivalent semantics
+or reject the job; silently reducing the input to an unlabelled file list is invalid.
+
+## Adapter stdout
+
+On success, write one bounded UTF-8 JSON object to stdout. Portable adapters
+should ASCII-escape JSON strings so Windows locale settings cannot corrupt
+project paths:
+
+```json
+{
+  "outputs": [
+    {
+      "target": "剧集/EP001/制作成果/images/SHOT001.png",
+      "source": "/temporary/adapter/result.png"
+    }
+  ],
+  "provider_job_id": "optional-public-id"
+}
+```
+
+Targets must appear in exactly the confirmed order. Sources must be direct
+regular-file children of `output_root`, not symlinks. The tool opens each source
+without following links, copies the pinned bytes into the project, records
+size/media type/checksum, and removes staging. It never stores adapter
+stdout/stderr or environment values.
+
+On a provider failure, an adapter may write only this whitelisted evidence to stdout:
+
+```json
+{
+  "error": {
+    "provider": "studio-image",
+    "category": "rate_limit",
+    "code": "rate_limit_exceeded",
+    "http_status": 429,
+    "request_id": "request_safe_123",
+    "retryable": true
+  }
+}
+```
+
+Never include provider messages, response bodies, prompts, paths or credentials.
+The production run record keeps only validated fields; malformed failure output
+is replaced with a generic adapter exit code.
+
+A nonzero exit, timeout, malformed response or mismatched output marks the run failed. Because the adapter may have
+submitted paid work before failing locally, confirmation is consumed as soon as execution starts; retry only after a
+new creator confirmation. A job with an unresolved `running` attempt cannot be prepared, confirmed, or run again;
+wait for its terminal record or investigate the interrupted attempt first.
+
+## Operational reconciliation
+
+`production_tool.py audit <project>` reads only local production metadata and the
+current output bytes. It reports terminal failures, retryable failures, recovered
+jobs, unresolved running attempts, repeated content fingerprints, and missing or
+changed outputs. Terminal state, recovery, and repeated output claims are ordered
+by validated completion time rather than start time. For paths written more than
+once, the latest completed successful claim is authoritative for this operational
+check. Only attempts bound to the current stored job fingerprint can claim its
+current outputs; older fingerprints remain visible as `superseded` attempt history.
+A successful record must declare exactly the current job's output set and media
+types before any output claim is trusted. Jobs, confirmations, run records, and the
+production lock use pinned no-follow directories where directory FDs are available,
+and reparse/identity checks on the portable fallback. A linked parent chain fails
+closed instead of redirecting state outside the project.
+
+The audit deliberately returns `quality_verdict: not_assessed`. A provider success,
+retry recovery, file presence, size, or checksum proves execution/custody only; it
+does not prove identity, performance, continuity, lip-sync, mix, edit, or audience
+quality. Those claims require an authorized observation and a separate review.

package/resources/skills/drama-production/upstream/skills/short-drama-produce/references/providers/gpt-image-2.md

@@ -0,0 +1,24 @@
+# GPT Image 2 adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "gpt-image-2"], "timeout_seconds": 600}
+```
+
+Required environment: `OPENAI_API_KEY`. `OPENAI_BASE_URL` optionally overrides the default
+`https://api.openai.com/v1` and must remain HTTPS.
+
+The job must have modality `image` and exactly one output. With no references, the adapter sends JSON to
+`POST /images/generations`. With one to sixteen references, it sends an `image[]` multipart edit to
+`POST /images/edits`. The model is always `gpt-image-2`, `n` is always one, and the single returned `b64_json` image is
+written to a private temporary file.
+
+Supported public parameters are `width` plus `height` (compiled to `size`), or `size`, and `quality`, `background`, and
+`moderation`. References use GPT Image 2's high-fidelity behavior without sending the older `input_fidelity` field.
+Transparent backgrounds are rejected because GPT Image 2 does not support them. The output extension selects `png`,
+`jpeg`, or `webp`.
+
+Protocol references: [GPT Image 2 model](https://developers.openai.com/api/docs/models/gpt-image-2),
+[image generation](https://developers.openai.com/api/reference/resources/images/methods/generate), and
+[image edits](https://developers.openai.com/api/reference/resources/images/methods/edit).

package/resources/skills/drama-production/upstream/skills/short-drama-produce/references/providers/minimax-h3-video.md

@@ -0,0 +1,86 @@
+# MiniMax H3 video adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "minimax-h3"], "timeout_seconds": 3600}
+```
+
+Required environment:
+
+- `MINIMAX_API_KEY`: MiniMax API key.
+- `MINIMAX_VIDEO_MODEL`: the exact enabled model ID. There is intentionally no default; the adapter
+  never assumes which MiniMax video release an account has.
+- `MINIMAX_VIDEO_RESOLUTIONS`: comma-separated subset the configured model actually accepts, drawn
+  from `480P`, `768P`, `2K`. The published envelopes differ per release, so this is configuration,
+  not a constant.
+- `MINIMAX_VIDEO_MIN_DURATION` and `MINIMAX_VIDEO_MAX_DURATION`: the configured model's explicit
+  inclusive duration range in whole seconds. Set both or neither; a job carrying `duration` without
+  the profile fails closed.
+
+Optional environment:
+
+- `MINIMAX_VIDEO_BASE_URL` (default `https://api.minimax.io/v2`)
+- `MINIMAX_VIDEO_RATIOS`: comma-separated subset of `adaptive`, `1:1`, `3:4`, `4:3`, `9:16`, `16:9`,
+  `21:9`.
+- `MINIMAX_VIDEO_POLL_INTERVAL` (default `5` seconds)
+- `MINIMAX_VIDEO_TIMEOUT_SECONDS` (default `1800` seconds)
+
+The job must have modality `video` and exactly one `.mp4` output. `duration` and `resolution` are
+required and are only accepted when the runtime profile above permits their values. `ratio` is
+optional for reference-conditioned jobs and **required** for text-to-video, where `adaptive` is
+refused because there is no reference frame to adapt to.
+
+The adapter validates and forwards `duration`; it does not estimate speech length or retime dialogue.
+Before preparing a speaking shot, compare the accepted shot duration, the prompt's spoken timeline,
+and the job's `duration`. Resolve insufficient speaking time in the storyboard and regenerate the
+dependent prompt before preparing the job. Prompt timestamps alone do not change the request duration.
+The official video API has no separate speech-rate parameter.
+
+The prompt is compiled into one `text` item of the multimodal `content` array and is refused above
+7000 characters. Each declared reference becomes one further `content` item carrying an explicit
+`role`: `first_frame`, `last_frame`, `reference_image`, `reference_video`, or `reference_audio`.
+Set the job's `parameters.prompt_language` to the resolved video-prompt language; the compiler
+consumes it when appending reference semantics and does not send it as a MiniMax request field.
+`first_frame` and `last_frame` may each appear once. The published envelope also caps reference
+conditioning at 9 `reference_image`, 3 `reference_video` and 3 `reference_audio` items, with video and
+audio clips between 2 and 15 seconds each and at most 15 seconds in total per modality; the compiler
+does not count them, so a configuration that can exceed those numbers has to bound them itself.
+frame conditioning (`first_frame` / `last_frame`) and full-reference conditioning
+(`reference_image` / `reference_video` / `reference_audio`) are mutually exclusive in one request.
+For continuation, bind the previous actual video as `reference_video` and its actual tail as
+`reference_image`; the compiler labels them `<Video 1>` and `<Picture 1>` in its appended contract.
+Never relabel that tail as `first_frame` while a reference video is present. Reference URLs may be HTTPS, `mm_file://{file_id}`, or a `data:<mime>;base64,<...>` URI — all three
+are documented inputs. A project-relative reference in the confirmed job is read from disk and sent
+inline as a data URI, so binding an image in the creator documents is enough to run the job; no
+upload service is required. Each file's bytes must match the media type its extension claims, and
+the published per-modality caps apply: 30MB per image, 50MB per video, 15MB per audio clip, and 64MB
+for the whole request measured after base64 expansion. A reference past those caps fails closed with
+an explicit message; host it and bind an HTTPS URL instead of splitting it.
+
+Each reference takes its provider role from the confirmed job's `reference_bindings[].role`, which is
+where the creator document's `用途` is translated for this provider. A job that carries references
+without those bindings fails closed rather than guessing a role.
+
+The adapter creates an asynchronous task with `POST {base}/video_generation`, polls
+`GET {base}/query/video_generation/{task_id}` until a terminal state, and downloads `task.content.url` into a private temporary directory. Any unknown
+status fails closed.
+
+## What this model changes for the prompt itself
+
+This release generates audio in the same pass as the picture. Its direct prompt dialect is also
+structured: base/first-frame/first-last-frame tasks use `integrated_multimodal_description`,
+`overall_soundscape`, and `non_diegetic_music`; full-reference tasks use the six-section H3 reference
+form. Chinese dialogue remains exact inside `<d>[Chinese] ...</d>`. Full details live in the
+video-prompt skill's `references/minimax-h3.md`.
+
+State the intended sound layers in the prompt. For no non-diegetic music, the
+H3 dialect uses `non_diegetic_music: N/A`; small probes observed unwanted music
+when this layer was omitted. They did not establish that omitted speech or
+negative clauses cause extra dialogue.
+
+Follow the project's subtitle and in-scene-text policy. Prompt wording belongs
+to the video-prompt skill and the declared language, not to adapter-generated
+boilerplate.
+
+Protocol reference: [MiniMax video generation API](https://platform.minimax.io/docs/api-reference/video-generation-v2-create).

package/resources/skills/drama-production/upstream/skills/short-drama-produce/references/providers/minimax-music.md

@@ -0,0 +1,25 @@
+# MiniMax Music adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "minimax-music"], "timeout_seconds": 600}
+```
+
+Required environment: `MINIMAX_API_KEY`. `MINIMAX_BASE_URL` optionally overrides the default
+`https://api.minimax.io/v1` and must remain HTTPS.
+
+The job uses the suite's `music` modality and must have exactly one output. The production prompt becomes the
+music style/mood prompt. Supported public parameters are `lyrics`, `is_instrumental`, `sample_rate`,
+`bitrate`, and `format`. Vocal jobs require exact accepted lyrics. The requested format must match the target extension
+and be `mp3` or `wav`.
+
+For this confirmed-production profile, `lyrics_optimizer` is rejected even when `true` is requested: supplier-authored lyrics would not have
+appeared in the preview and cannot satisfy creator ownership or licensing. A vocal job therefore requires the exact
+accepted lyrics; an instrumental job carries neither lyrics nor an optimizer request.
+
+The request always uses model `music-3.0`, non-streaming `output_format: hex`, and
+`POST /music_generation`. The adapter validates `base_resp.status_code`, decodes `data.audio` as hexadecimal bytes,
+and writes it to a private temporary file.
+
+Protocol reference: [MiniMax Music Generation](https://platform.minimax.io/docs/api-reference/music-generation).

package/resources/skills/drama-production/upstream/skills/short-drama-produce/references/providers/minimax-speech.md

@@ -0,0 +1,41 @@
+# MiniMax Speech adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "minimax-speech"], "timeout_seconds": 600}
+```
+
+Required environment: `MINIMAX_API_KEY`. `MINIMAX_BASE_URL` optionally overrides the default
+`https://api.minimax.io/v1` and must remain HTTPS.
+
+The job uses the suite's `tts` modality and must have exactly one output. The production prompt is the
+line to be spoken, verbatim — not a description of it. Supported public parameters are `model`,
+`voice_id`, `emotion`, `speed`, `vol`, `pitch`, `sample_rate`, `bitrate`, and `format`. The requested
+format must match the target extension and be `mp3` or `wav`.
+
+`model` and `voice_id` are both required and neither has a default. The model is an account-enabled
+endpoint, exactly as for the video providers. The voice is a creative decision recorded in
+`视觉设定.md` under the character's 声音方向, and it reaches the adapter through the confirmed job.
+
+## Voice selection
+
+Read the provider's voice listing and confirm availability for the chosen model and account.
+The adapter validates the ID format, not catalogue membership. Record the selected ID in the
+character's 声音方向 and pass it through the confirmed job.
+
+This workflow selects preset voices. The adapter does not enrol or clone a voice;
+any supplied recording retains its documented authorization and usage scope.
+
+## Request shape
+
+The request is non-streaming with `output_format: hex`, `POST /t2a_v2`, and carries
+`voice_setting` (`voice_id`, and any of `emotion`, `speed`, `vol`, `pitch`) alongside `audio_setting`
+(`sample_rate`, `bitrate`, `format`). The adapter validates `base_resp.status_code`, decodes
+`data.audio` as hexadecimal bytes, and writes it to a private temporary file.
+
+`emotion` accepts the provider's seven values: `happy`, `sad`, `angry`, `fearful`, `disgusted`,
+`surprised`, `neutral`. Anything outside that set is refused rather than passed through — a rejected
+emotion is a typo caught before it is paid for.
+
+Protocol reference: [MiniMax Text to Speech](https://platform.minimax.io/docs/api-reference/speech-t2a-http).