docs(skill): 媒体契约升级三数组image_files/audio_files/video_files(r2v变长数组Jinja for动态组装,禁固定槽位);干跑双形态;坏模板apply自愈禁转嫁人工手改

skills_library/pipelines/platform_general/common/model-auto-config/SKILL.md

@@ -32,7 +32,7 @@ tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, apply_model_pri
    建定价方案+时序YAML并挂 ppid，出处URL+文档原文写入描述。
 6. **测试**：`test_model_call(model_name, prompt, params)` 真实调用走完整治理链。
    前置：供应商账号已配 api_key（没配如实告知用户去补，禁止伪造结果）。
-   生成类模型 params 传 image_file/resolution/duration 等；返回 task_ref/usage/media（生成物本地URL）。
+   生成类模型 params 传 image_files/audio_files/video_files（字符串或数组均可）+ resolution/duration 等；返回 task_ref/usage/media（生成物本地URL）。
 7. **记账检查**：`check_model_accounting(task_ref)` 查三态 + 独立复算金额：
    - accounted 且 amount_match=true → 全链通过，汇报金额
    - created → 等 60~120 秒再查（出账循环 60 秒一轮）
@@ -67,20 +67,26 @@ tools: [fetch_model_doc, extract_llm_api_spec, apply_llm_config, apply_model_pri
 `{{ b64media2url(request, params.xxx_file) }}` 骨架——纯文生视频(t2v)没有图片输入，
 运行时渲染即崩（`'dict object' has no attribute 'xxx_file'`）。i2v 那份能跑全靠手工修。
 
-**现行机制**（apply_llm_config 落库时自动执行）：
+**现行机制**（apply_llm_config 落库时自动执行，2026-09-06 三数组契约版）：
 - 提取层的 `request_example`（文档 cURL/代码示例的完整请求体，逐字照抄）驱动模板生成：
   - `model` 键 → `{{ model|tojson }}`；`prompt/text` 键 → `{{ prompt|tojson }}`
-  - 示例里是 URL 叶子且结构/键名带媒体线索（first_frame/img_url 等）或能力属输入媒体类
-    (i2v/i2i/v2v) → `{{ b64media2url(request, params.image_file|video_file|audio_file)|tojson }}`
+  - **媒体数组**（如 r2v `input.media: [{type, url}...]` 变长，最多 9 张）→
+    按元素 type 归组到统一参数 `image_files/audio_files/video_files`，
+    生成 Jinja `{% for _f in ... %}` 动态组装（`is string` 判断兼容字符串/数组两形态；
+    元素结构逐字保留仅 URL 叶子换 b64media2url；混合类型多循环 namespace 计数合并逗号）。
+    **禁止按示例元素个数展开固定槽位**——r2v 曾因按示例 3 元素展开成
+    image_file 单值契约渲染崩（2026-09-06 实测）。
+  - 单值上传媒体（URL 叶子且带媒体线索）→ `{{ b64media2url(request, <scalar_expr>)|tojson }}`
   - 其他标量 → `{{ params.<键名>|default(<文档示例值>)|tojson }}`（业务参数带文档默认值）
-- **示例里没有上传媒体就不生成媒体参数**——t2v 模板自然纯文本，i2v 才带 image_file
+- **示例里没有上传媒体就不生成媒体参数**——t2v 模板自然纯文本
 - 响应模板：产物字段路径递归取 `response_example` 里的 URL 字段（如 output.video_url），
   经 `downloadfile2url` 落地；文档没给响应示例用供应商惯例兜底并在 notes 如实标注
 - 请求头按文档示例带（DashScope 异步必需 `X-DashScope-Async: enable`，协议兜底自动补）
-- **落库前干跑渲染自检**（StrictUndefined 模拟运行时命名空间）：模板引用运行时拿不到的
-  变量当场拦截，报进 `template_errors`——宁可不建，不埋雷到 test 才崩
-- 旧骨架模板（含 `__from_doc__`/`__note__`/`xxx_file` 标记）视为不可用，
-  apply 时自动弃用（status=deprecated）并按文档示例重建
+- **落库前干跑渲染自检双形态**（StrictUndefined，数组+字符串各渲染一遍）：模板引用运行时
+  拿不到的变量、或只兼容单一形态，当场拦截报进 `template_errors`——宁可不建，不埋雷
+- 旧骨架模板（含 `__from_doc__`/`__note__`/`xxx_file`/旧单值 `params.image_file)` 标记）
+  视为不可用，apply 时自动弃用（status=deprecated）并按文档示例重建——**存量坏模板
+  重跑一次 apply 即自愈，不需要人工去页面改**
 - 任务查询接口供应商级共用（DashScope 全系生成模型都是 GET /tasks/{task_id}）：
   查询步骤模板按 `{protocol}-query-{path}` 命名复用，多模型共享一份
 
@@ -151,32 +157,37 @@ accounted（成功）/ failed（失败）。出账前置：模型有产品映射
 + 挂 ppid，缺一出账置 failed 并写明原因。非 token 计价因子存 llm_usage.usages。
 内部助手工具 `check_model_accounting` 检查三态并对 accounted 流水独立复算金额。
 
-## 媒体转换铁律（2026-09-05 用户定夺——每个 llm_api_profile 配置必查）
+## 媒体转换铁律（2026-09-06 用户定夺三数组契约——对齐 sage/llmage）
 
-生成类模型（t2i/i2v/t2v/tts/i2i/v2v/3d 等出参是文件的能力）的适配模板
+生成类模型（t2i/i2v/t2v/r2v/tts/i2i/v2v/3d 等出参是文件的能力）的适配模板
 `llm_api_profile`，**data 和 response 必须处理两个媒体转换逻辑**：
 
-- **上行（request_template / data）**：上传/本地媒体一律 `xxx_file` 命名，
-  用 `{{ b64media2url(request, params.image_file) }}` 转成本地公网 URL
-  再传上游（base64 落盘 → /idfile 公网地址；已是 http/https URL 则原样透传）。
+- **上行（request_template / data）**：上传媒体统一三数组参数
+  `image_files` / `audio_files` / `video_files`（值为**字符串或数组均可**，
+  Jinja 模板 `is string` 动态判断两形态）。r2v 这类变长输入（最多 9 张参考图、
+  有些模型图/视频/音频任意组合）用 `{% for %}` 循环按文档示例结构动态组装。
+  每个元素经 `{{ b64media2url(request, _f) }}` 转成本地公网 URL 再传上游
+  （base64 落盘 → /idfile 公网地址；已是 http/https URL 则原样透传）。
 - **下行（response_template）**：上游生成物 URL 用
   `{{ downloadfile2url(request, output.video_url) }}` 落地为本地持久 URL
   再给调用者——**上游 URL 有效期极短（DashScope 视频仅 24 小时），不落地即丢**。
 
-同类能力对外契约统一：i2v 一律 `image_file` 进 → `video` 出；
-t2i 出 `image`。模板不用为同一类能力写多套参数名。
+同类能力对外契约统一：i2v/r2v 一律 `image_files` 进 → `video` 出；t2i 出 `image`。
+旧单值别名 `xxx_file`/`xxx_url` 与 DashScope 形态 `media` 数组由运行时
+`_normalize_media_aliases` 自动归一进三数组（按 type 分组），调用方传哪种都兼容。
 
 **执行机制（已落地，非口头约定）**：
 - 推理层 `inference.py` 已把 `downloadfile2url`/`b64media2url` 注入模板命名
   空间（`_media_ns_extra`，request=None 时走部署机 `BASEURL` 兜底拼公网地址）。
 - `apply_llm_config` 落库后自动调 `_audit_media_convention` 审计本次涉及的
   生成类模板，缺转换函数会返回 `media_audit` 警告，必须如实转告用户。
-- 非标协议骨架模板已自带转换占位，人工只需把产物字段名换成文档真实路径。
 
 **核对清单（配每个生成类模型都过一遍）**：
-1. request 模板含 image/video/audio 上传参数 → 是否有 `b64media2url`？
-2. response 模板 → 产物 URL 是否经 `downloadfile2url` 落地？
-3. 出参字段名是否与同类能力一致（video/image）？
+1. request 模板媒体参数是否用三数组契约（image_files/audio_files/video_files）？
+2. 变长媒体数组是否 `{% for %}` 动态组装（非固定槽位）且兼容字符串/数组两形态？
+3. 每个媒体元素是否经 `b64media2url`？
+4. response 模板产物 URL 是否经 `downloadfile2url` 落地？
+5. 出参字段名是否与同类能力一致（video/image）？
 
 ## 提取链路机制（2026-09-05 修复）
 
@@ -207,6 +218,9 @@ t2i 出 `image`。模板不用为同一类能力写多套参数名。
 1. 先看报错原文定位是哪一环（门禁/上游/模板/记账），不猜。
 2. 模板类错误：把渲染结果打出来对照期望 JSON（历史案例：媒体数组收尾花括号
    顺序错 `}}]`→`}]}`，渲染断裂在 column 361）。
+   **模板渲染报错=生成器机制缺陷，禁止让用户去模型治理页面手改模板**（2026-09-06
+   r2v 实测教训：助手把 image_file 渲染崩转嫁人工兜底）——如实报告错误原文+
+   判断的根因即可，修复生成器后重跑 apply 自愈（旧坏模板自动弃用重建）。
 3. 记账类 failed：按 note 原因对号——未挂ppid→apply_model_pricing；未映射产品→
    产品管理导入；金额不符→核对 usages 维度值与定价 YAML 的维度值是否逐字一致
    （480P≠480，字符串必须精确匹配）。