| name | media-gen |
| description | 通用生图的统一入口（provider 抽象层）——一个调用，底下可插拔路由到多个生图后端 (gemini-gen / comfyui / codex-image-gen / dashscope 通义万象直连 API / browser-gen / ark 槽位)，上层不用 关心调的是哪个。当要生图但不想手动挑后端、要一致的统一结果契约、要失败自动降级、 或在 asset-bridge / produce-pipeline 等编排里程序化出图时使用。Triggers: 统一生图, 生图路由, 出图但不挑后端, 自动降级出图, media-gen, unified image gen, image provider router, generate an image (backend-agnostic)。吃 style-lock v1 保品牌一致，返 {path, type:"image", backend, meta} 统一结果。借 Pixelle MediaService 抽象思路： 一个入口按配置/可用性路由 + 统一结果 + capability 元数据。 |
media-gen —— 统一生图入口（provider 抽象 + 路由 + 降级）
把 gemini-gen / comfyui / codex-image-gen / dashscope（通义万象直连 API）/ browser-gen / jimeng / ark 这些各调各的生图后端，收敛到一个统一入口：上层只说「我要这张图」，由本 skill 按配置 + 可用性路由到合适后端、出错自动降级到下一个，最后返统一结果契约。学 Pixelle-Video 的 MediaService 抽象——一个入口按 source/前缀 路由到不同 provider，统一返 MediaResult，每个 provider 带 capability 元数据。
媒体生态定位：本 skill 是 media/image 层的调度壳，不重造任何出图能力——底下复用既有五个后端。asset-bridge（素材生成环节）、produce-pipeline（制片流水线素材阶段）调它，不直接挑后端。要点名某后端时仍可绕过本 skill 直接调那个 skill。
何时用
- 要生图，但不想手动挑后端——交给路由按默认链 + 可用性决定。
- 要统一结果契约——不管底下走哪个后端，都返一致的
{path, type, backend, meta} JSON，方便上游编排消费。
- 要失败自动降级——一个后端撞额度 / 报错 → 自动跳下一个（
gemini-gen 本就内置多账号跳号，本 skill 在它之上再做跨后端降级）。
- 被
asset-bridge / produce-pipeline 程序化调用——它们不该耦合某个具体后端。
反例（不走本 skill）：用户点名「用 ComfyUI 出图 / 用 Gemini 画」→ 直接调那个后端 skill。要手绘小黑配图 → links-illustrations。要 HTML 图表 → html-diagram。本 skill 只管「通用生图、由我来选后端」。
统一接口（一个调用）
入口 scripts/media_gen.py，任意 python 调用即可。stdout 只吐一行统一结果 JSON，进度 / 决策日志走 stderr。
MG=~/.claude/skills/media-gen/scripts/media_gen.py
python3 "$MG" gen --prompt "一条数据流穿过暗场，几何线框，柔和辉光" --out out/hero.png
python3 "$MG" gen --prompt "同一角色，全身，纯背景" \
--aspect 16:9 --ref refs/hero.png --out out/hero-run.png
python3 "$MG" gen --prompt "..." --prefer comfyui --out out/x.png
python3 "$MG" gen --prompt "..." --prefer dashscope --aspect 16:9 --out out/x.png
python3 "$MG" gen --prompt "..." --no-style-lock --out out/x.png
python3 "$MG" gen --prompt "..." --out out/x.png --dry-run
python3 "$MG" providers
python3 "$MG" contract
参数
| 参数 | 说明 |
|---|
--prompt | 必填。主体 + 构图 + 配色 + 留白，越具体越好。本 skill 会在前面自动拼 style-lock 的 locked_prompt（除非 --no-style-lock）。 |
--out | 必填。保存路径，父目录自动建。 |
--aspect | 可选。16:9 / 1:1 / 9:16 等；按后端转成它认的形参（gemini --aspect / codex --size / comfyui --w/--h）。 |
--ref | 可选，可重复。参考图，做系列图锁角色 / 画风时带上。注意：不是所有后端都吃 ref（见 capability 表）；带 ref 时路由会优先选支持 ref 的后端。 |
--prefer | 可选。后端偏好（gemini-gen/comfyui/codex-image-gen/…），把它提到链首；仍会降级，除非 --no-fallback。 |
--no-fallback | 可选。只试链首一个后端，失败即失败，不降级。 |
--no-style-lock | 可选。关掉 style-lock 注入（非品牌图才关）。 |
--style-lock | 可选。指定 画风锁.md 路径（默认自动找 Media-Studio 风格卡/风格锁/画风锁.md）。 |
--dry-run | 可选。只打印路由决策 + 降级链 + 可用性，不真生成。 |
路由 + 降级（核心）
本 skill 不自己生图，它决策走哪个后端并串行降级。完整决策表、capability 元数据、降级链见 reference/providers.md，要点：
- 默认链（与 Media-Studio 能力矩阵 / style-lock 同源）：
gemini-gen（免费快·默认）→ codex-image-gen（gpt-image-2·参考图锁风格）→ comfyui（本地可控·模型无关）→ dashscope（通义万象直连 API·可控质量稳定·≈¥0.14/张）→ browser-gen（Gemini 网页·兜底稳出）。
--prefer X：把 X 提到链首，其余按默认顺序续在后面。- 带
--ref：路由优先选支持参考图的后端（gemini-gen / codex-image-gen / comfyui-i2i），把不支持的降权（dashscope t2i 主路不吃 ref，带 ref 时会被降权）。
- 降级触发：某后端不可用（依赖缺失 / 未配置）→ 跳过不计失败；某后端真失败（撞额度 / 报错 / 退出码非零）→ 记一次失败、跳下一个。链路耗尽仍失败 → 返失败结果（绝不假装生成）。
- 直连 API 后端（需 key）：
dashscope（通义万象）：key 已配（media-api-keys.json 的 dashscope.api_key，运行时读·绝不硬编码），判定 ready、进默认自动链——这是有成本但稳定的真后端，免费/订阅/本地档都不可用时兜底出图。已真测：M3 上提交→SUCCEEDED→下载约 5~10s/张。- 审核降级（被拒→中性化重写→重试一次）：生图被内容审核拒同样常见（dashscope 等直连 API 会以
DataInspectionFailed / 敏感内容 等标志拒）。dashscope 调用内置审核降级（共用逻辑，借 Pixelle / ai-video-gen 的 moderation_fallback）：首次被拒 → 判是否审核类错误 → 是则把 prompt 中性化重写（去暴力/危险/极端表达、保留画面主题与品牌风格）、重试一次；中性化后仍失败 → 诚实带「原始 + 重试」两段错误返失败，不静默吞。非审核类错误（网络 / 超时 / 服务端 5xx / 下载失败）不触发中性化（不掩盖真因），直接返失败让上层降级到下一后端。正常出图链路完全不受影响——只有 failed 且审核类才触发。逻辑在 scripts/providers.py 的 is_content_inspection_error / neutralize_prompt + _invoke_dashscope，单测 python3 scripts/providers.py --selfcheck（不烧 API、不触发真审核）。
- 槽位后端（默认链外，需用户显式启用）：
browser-gen：要 Chrome MCP 实时驱动，CLI 不可全自动 → 路由判定为「需人工 / 半自动槽位」，给提示而非静默跳。ark（字节 Seedream）：media-api-keys.json 的 ark.api_key 当前为空，判定为槽位、给「填 key 后接入」提示（OpenAI 兼容 /images/generations 同步接口，slot invoke docstring 已写好接入路径，补 key + 落地真调后切 ready）。- 其它直连 API（GPT-Image 付费 ·
jimeng/Dreamina 付费）：需用户配 key / 权限。本 skill 绝不擅自调未授权付费接口——判定为槽位，打印「该后端需配置 X 才能启用」的清晰提示。
吃 style-lock v1（品牌一致）
所有生图默认自动拼 style-lock：读 风格卡/风格锁/画风锁.md 的 frontmatter，把 locked_prompt 拼到用户 prompt 前、negative_prompt 透传给支持负向的后端（comfyui）。这样跨内容画风不漂移。注入规则、各后端如何吃负向 / seed / sref 见 reference/style-lock-injection.md。
- frontmatter 的
backend: gemini-gen + 降级链与本 skill 默认链一致（同源），但本 skill 的 --prefer / 可用性优先于 frontmatter 的静态声明。
- 没传
--style-lock 时自动向上找 Media-Studio 的 画风锁.md；找不到则跳过注入并在 stderr 提示（不报错）。
统一结果契约（借 Pixelle MediaService）
无论底下走哪个后端，stdout 都吐一行 JSON，schema 见 reference/result-contract.md：
{
"ok": true,
"type": "image",
"path": "/abs/path/out/hero.png",
"backend": "gemini-gen",
"meta": {
"prompt_final": "<style-lock + 用户 prompt>",
"aspect": "16:9",
"refs": ["refs/hero.png"],
"style_lock": "v1",
"attempts": [{"backend": "gemini-gen", "status": "ok"}],
"fallback_chain": ["gemini-gen", "codex-image-gen", "comfyui", "browser-gen"]
}
}
- 失败：
{"ok": false, "type": "image", "path": null, "backend": null, "meta": {"attempts": [...], "error": "..."}}。
attempts 记录每个试过的后端及其 status（ok / failed / unavailable / slot），上游可据此知道到底走了哪个、为什么降级。
capability 元数据
每个后端带一份能力元数据（尺寸支持 / 是否吃 ref / 是否吃负向 / 授权与成本 / 可用性探测），是路由决策的依据。全表见 reference/providers.md。路由读它来：① 带 ref 时筛支持 ref 的后端；② 探测后端是否可用（命令在不在、服务起没起、key 配没配）；③ 把成本/授权信息透出到结果 meta，让上游知道这张图花了什么（如 dashscope 透出 cost: paid ≈¥0.14/张）。直连 API 后端（dashscope/ark）的 key 从 media-api-keys.json 运行时读——api_key 为空即判 unavailable/slot，绝不假装出图。
边界与诚实底线
- 本 skill 只路由，不重造生图——所有像素都由底下后端产，本 skill 负责选 + 降级 + 统一结果。
- 不注册账号、不硬编码 key、不擅自调未授权付费接口——key 运行时读
_secrets/media-api-keys.json，绝不写进脚本/不回显/不入库；ark / jimeng 等未配 key 或需权限的后端是槽位，路由判定为槽位时给清晰提示，绝不假装生成。
- 诚实标完成度：当前真能路由——
gemini-gen / codex-image-gen / comfyui（现成可调）+ dashscope（通义万象直连 API，key 已配·已真测 t2i 出真图·有成本·带审核降级中性化重试）；槽位——browser-gen（半自动）、ark（Seedream，待用户填 key）、jimeng（付费需 vip）。结果 attempts 里如实记每个后端 ok/failed/unavailable/slot。审核降级逻辑已写对并单测验证（providers.py --selfcheck），未真触发审核测（克制·不烧 API）。
- 本地可逆、不 push。
