多媒体 Provider

Spark Work 的多媒体能力用「能力注册表 + 平台适配器 + Media Model Manifest」三层实现： Provider Profile 声明它支持哪些能力，适配器负责平台协议，manifest 负责单个模型的参数与 产物提取。图片、语音、视频共用同一套代码路径，画布、spark_media MCP 与 Provider 表单读的是同一份元数据。

1. 能力枚举与适配器

统一能力 id 共 11 个（不是 9 个），定义在 packages/protocol/src/media-config.ts 的 MEDIA_CAPABILITY_IDS。 括号里是 Provider 表单上的中文标签（providerMediaConfig.ts 的 MEDIA_CAPABILITY_LABELS）。

1.1 平台适配器枚举

mediaProvider 的合法值共 18 个（MEDIA_PROVIDER_KINDS）。 Provider 表单里的「平台适配器」下拉不是全量枚举，而是按模型类型裁剪： 生图 / 视频模型给 9 项，其余给 15 项。

适配器注册是显式的：MediaRouterService 构造函数里 register() 了 12 个实例（含 Google 适配器注册两次，分别对应 google-generative-ai 与 omni）。路由时先看有没有专用适配器且它声明支持该能力，否则改用 manifest 驱动的模板适配器；两者都没有时抛 provider_not_configured: No adapter for provider kind ...。

openai-compatible 没有注册为独立适配器（openai-compatible-media.adapter.ts 是其他适配器的基类），所以这一类渠道必须绑定 manifest 才能调用。

2. Media Model Manifest

Manifest 是「模型元数据单一来源」：类型与 zod schema 在 packages/protocol/src/media-model-manifest.ts，内置种子共 167 条，覆盖 13 个 providerKind。

一条 manifest 的关键字段：

• id / providerKind / modelId / displayName / domains（image / audio / video / text …）。
• capabilities[]：每条含 id、label、input.required、input.maxImages、output.types、paramSchema、defaults、aliases。
• invocation：mode（sync / async_polling / async_callback / stream / file_job）、endpoint、method、contentType（json / multipart / binary）、requestTemplate、response、polling。
• docs.sourceUrls + lastCheckedAt：记录参数是照着哪份官方文档核对的。
• safety：maxPromptLength、allowLocalFiles、maxInputBytes。

Contract V2 增补了 contractVersion: 2、adapterMode（native / template）与 baseTemplate；后者在 Provider 表单的「配置自定义适配器」里有 4 个基底可选：完全自定义、OpenAI 接口协议基底、通用异步 JSON 任务（GET 轮询）、ToApis 图片全能力异步轮询。

持久化用两张表：media_model_manifests（manifest 本体）与 media_provider_models（某个 Provider 启用了哪些 manifest、本地默认参数覆盖）， 见 packages/storage/migrations/033_media_model_manifests.sql。启动时由 MediaModelCatalogService.seedBuiltinManifests() 把内置种子写回 SQLite。

3. 配置步骤（真实界面）

1. 打开 设置 → Provider，点「新建」（或「新增配置」）打开编辑面板。
2. 模型类型选 4 项之一：对话模型 / 生图模型 / 语音模型 / 视频模型。对话模型属于附加能力场景，需要额外打开 附加生成能力开关才会出现多媒体面板。
3. 选模板预设（如 APIMart、xAI、火山方舟），会预填 Base URL、默认模型、能力与轮询参数。
4. 在多媒体面板里确认三件事：
   • 平台适配器：图片 / 视频模型从 9 个里选，其余从 15 个里选。
   • 支持能力：勾选本 Provider 真实支持的能力，别多勾——路由和调用方式都按它判断。
   • 调用方式：sync / async / auto。
5. 模型清单里从内置目录勾选要启用的 manifest；自定义渠道可以手输模型 ID 并按 Enter 添加。
6. 参数默认值填 size / 比例 / 质量 / 时长等；异步渠道再填 轮询间隔 ms 与 接口超时 ms。
7. 填 API Key 保存。表单下方会给出「实际请求地址」预览，确认适配器拼出的 URL 与渠道文档一致。

注意：「测试连接」不是媒体链路验证。它发的是文本协议 ping （OpenAI 兼容走 /chat/completions，Anthropic 走 messages），纯图片 / 视频渠道 常常没有 chat 端点，因此测试失败不代表媒体不可用；反过来测试通过也不代表生图能跑通。请以 「实际请求地址」+ 一次真实生成为准。

4. 内置预设清单

当前共 64 个 Provider 预设，其中 35 个带多媒体配置。下表为真实 id 与默认模型 （预设定义在 packages/protocol/src/provider-presets.ts）。

预设里的默认 Base URL（可直接对照渠道文档核对）：

APIMart            https://api.apimart.ai/v1
xAI               https://api.x.ai/v1
OpenAI            https://api.openai.com/v1
Agnes AI          https://apihub.agnes-ai.com/v1
阿里百炼           https://dashscope.aliyuncs.com/api/v1/services/aigc
火山方舟           https://ark.cn-beijing.volces.com/api/v3
火山豆包语音        https://openspeech.bytedance.com（X-Api-Key，非方舟 Bearer）
Google Gemini     https://generativelanguage.googleapis.com/v1beta
Kling             https://api.klingai.com
MiniMax           https://api.minimaxi.com
腾讯云 TokenHub    https://tokenhub.tencentmaas.com
Midjourney 网关    https://your-midjourney-gateway.example/v1（占位，必须改成自建网关）

5. 默认值、超时与重试

重试只发生在异步轮询阶段：只有「网络层错误 / HTTP 5xx / 429」会重试，并会识别 响应里的 Retry-After（秒数或时间戳，上限 8 s）；4xx 参数错误、 task_failed、task_timeout 不重试。一次性提交请求（create/submit） 本身不自动重试，失败会直接把错误交给调用方。

历史配置的超时会被迁移脚本抬高到当前口径：055_video_poll_timeout_30m.sql、056_image_poll_timeout_10m.sql、067_video_poll_timeout_48h.sql。 迁移只替换「仍等于旧默认值」的记录，你手填过的值不会被覆盖。

6. 产物、任务与错误码

• 产物根目录是当前 workspace 下的 .spark-artifacts/media，按类型分成 images / audio / videos / text （语音转写落 text）。落盘前会把 .spark-artifacts 写进仓库本地忽略，避免被连带提交。
• 每次调用都会被持久化成 media_generation_tasks（表在 029_media_generation_tasks.sql，恢复所需字段由 066_media_task_recovery.sql 补充）。运行时有 submit / inquire / cancel / materialize 四段接口。
• media-task-recovery.service.ts 只按持久化的查询契约去问渠道「这个任务怎么样了」，不会重新提交 create/submit，所以重启应用不会重复计费。
• 画布的模型调用详情面板会显示 Provider / Manifest / 模型 / 状态 / 反向提示词 / Request ID 以及本次实际参数。

代码里会出现的错误码（MediaProviderError.code）：

• provider_not_configured：渠道没配好，或该 mediaProvider 既没有专用 适配器也没有匹配到 manifest。
• capability_not_supported：勾选的能力与实际调用不匹配。
• api_key_missing / auth_required：凭据缺失或渠道返回鉴权失败。
• invalid_input：参数被 manifest 校验拦下（常见于时长、分辨率越界）。
• provider_http_error：渠道返回非 2xx，附带 statusCode。
• task_failed / task_timeout：异步任务失败或超过总时限。
• artifact_download_failed：任务成功但产物 URL 下载失败（签名过期、需要鉴权头）。

渠道错误响应还会被归一成 unsupported_parameter / invalid_parameter_value / missing_required_input / auth_failed / quota_exceeded / rate_limited / content_policy_blocked / bad_provider_response 这类语义码，便于判断 该改参数还是该充值。

7. spark_media MCP

会话只要存在可用的媒体 Provider，就会注入内部 stdio MCP server spark_media，共 14 个工具：

mcp__spark_media__list_models       列出已配置的模型与能力（可用 capability 过滤）
mcp__spark_media__describe_model     查看单个模型的参数 schema 与调用元数据
mcp__spark_media__generate_image     文生图 / 图生图
mcp__spark_media__edit_image         图片编辑 / 多图合成
mcp__spark_media__generate_audio     语音合成或音乐生成（取决于所选模型）
mcp__spark_media__transcribe_audio   语音转写
mcp__spark_media__generate_video     文生视频 / 图生视频 / 参考图生视频 / 视频编辑 / 扩展
mcp__spark_media__upload_file        上传文件到渠道文件平台
mcp__spark_media__get_file           查询渠道文件元数据
mcp__spark_media__list_files         列出渠道文件
mcp__spark_media__delete_file        删除渠道文件（需用户确认）
mcp__spark_media__list_tasks         列出渠道异步任务（百炼支持官方 24 小时查询窗口）
mcp__spark_media__get_task           查询任务（支持生成工具返回的 taskId 或百炼 task id）
mcp__spark_media__cancel_task        取消排队中/运行中的任务（百炼仅 PENDING 可远程取消）

文件四件套只在路由到 volcengine-ark 或 bailian 时暴露；其余渠道 工具列表里看不到它们。

• 参数：model 支持「selectionKey（推荐）/ manifest id / 渠道模型 id」三种写法，selectionKey 形如 <providerProfileId>/<manifestId>。常用参数（size / aspectRatio / resolution / durationSeconds / mode / seed / output_format / prompt_optimizer 等）直接暴露，渠道私有字段走 extraJson，且会被按 manifest 裁剪，多余字段不会发给渠道。
• 凭据隔离：运行时把 Provider 列表写进一个 0600 权限的临时配置文件（SPARK_MEDIA_CONFIG_FILE），API Key 不进文件，而是通过 SPARK_MEDIA_API_KEY_0、SPARK_MEDIA_API_KEY_1… 逐个注入子进程环境变量。 Agent 拿不到 Key，也没有工具能读出来。
• 多档切换：每个模型保留自己 Provider 的 Key / endpoint / 适配器；生成工具靠 model 参数切换实际路由，同名模型必须用唯一 selectionKey 指定。
• 单 Provider 环境变量（SPARK_MEDIA_PROVIDER / SPARK_MEDIA_MODEL / SPARK_MEDIA_API_TYPE / SPARK_MEDIA_BASE_URL / SPARK_MEDIA_OUTPUT_DIR）与 SPARK_MEDIA_MANIFESTS_JSON / SPARK_MEDIA_PROVIDERS_JSON 仍作为兼容回退保留。
• 图片的旧链路 spark_image 只在「没有可解析的统一媒体配置」时才注入，避免两套工具 争抢模型选择；详见 图片生成 Provider。

8. 接入自定义渠道

两条路，先试第一条：

1. UI 手工配置：Provider 表单里把「平台适配器」选成自定义， 会多出「自定义渠道适配器 → 配置自定义适配器」入口，用 ProviderManifestContractEditor 从 4 个基底模板改起（提交 / 鉴权 / Body / 上传 / 轮询 / 参数 / 错误契约）。适合渠道是「JSON 提交 + 可选轮询 + URL/base64/binary 产物」。
2. 让 Agent 配置：Agent 侧有 5 个平台工具—— providers_media_guide（取能力枚举与起始契约）、 providers_media_validate（只读校验，不落库）、 providers_media_configure（校验通过后写入正式 Provider，Key 进 Keychain）、 providers_media_discover_models（打渠道 /models）、 providers_media_diagnose（分阶段诊断 401/404/400/轮询/产物解析）。诊断里的真实 生成调用需要用户显式确认。

只有在渠道需要自定义鉴权、multipart、回调、文件型 job 或特殊取消语义时，才需要写专用适配器： 新增 packages/agent-runtime/src/services/media/adapters/<vendor>-media.adapter.ts， 在 MediaRouterService 构造函数里 register()，并补 mediaProvider 枚举、表单标签与预设。给这个渠道写 manifest 的模型更适合走模板适配器。

9. 常见报错与排查