MG-04-004 模型目录

2026-10-16 视频管理页面统一读取（MG-CATALOG-10）

Console /backend/state 同时返回当前 model_catalog。视频渠道的标准关联、视频调度导航和测试模型只列出未删除的视频定义，显示名、说明及参数来自该定义。底层 PublicModel 的版本、绑定、调度、发布/启用与历史仍保留；目录删除只移出可选标准项，不删除执行历史。渠道上游型号和 Supply 能力仍是执行事实，不替代标准定义。读取及页面导航不写库、不创建执行模型。

新增定义尚无 PublicModel 时，页面显示“尚未建立调度配置”。显式建立或首次关联通过受管理员会话、CSRF、Origin 保护的 POST /backend/model-catalog/{catalog_id}/video-execution，请求仅 {version: <目录版本>}；核对当前未删除的视频定义和版本后，复用 Go PUT /admin/v1/video-configuration 原子创建停用、未发布、空绑定的异步模型。重复操作返回已有执行模型，409 仅核对已有结果，不重复创建；不触发 Provider 请求。

测试控件、默认值、枚举、数值范围/步长、素材类型/数量及选路检查均按所选 parameter_variants 的准确参数生成，无规格时使用 parameters。不合并不同规格的参数组合；目录保存/删除触发共享状态重读，页面重新获得焦点和调度刷新也重读。保留未保存配置并要求核对。首次提交测试前核对目录版本；结果未知时继续核对原 operation，保留冻结提交体，不因目录更新重复收费创建。

目录定义不意味着执行接口已经支持所有字段。现有视频执行接口尚未接入自动时长和部分新参数（如返回尾帧、联网搜索）；控件标识未接入，必要或有非中性默认值的未知参数阻止提交，不静默丢弃。已支持的传输字段仍受 Go 接口与所选 Supply 的真实能力校验。此任务未更改 Go 内核、迁移、渠道凭据、能力、成本、启用或在途任务。

2026-10-16 标准型号参数（现行）

MG-CATALOG-07将参数所有权固定到标准型号。模型目录不再提供“同步渠道参数”或“随渠道自动更新”；读取目录不使用渠道参数投影，不访问Provider，不按渠道归档/换Key改变标准参数或目录发布状态。每个标准型号统一维护parameters及parameter_variants，渠道/供给仍持有自身执行能力并在执行时校验。

POST/PUT标准定义新增可选parameter_variants（最多64组，每组有label、parameters和可选素材合计/提示词或图片条件），使用原受限参数校验；服务端从组合计算根parameters并生成input_schema.anyOf，保持互斥规格约束。无组合时按原平面字段维护。旧客户端省略组合且参数不变时保留已有组合；有组合的定义修改参数必须明确提交组合，不能无意丢失约束。use_channel_parameters仅接受false，true返回422。管理员/服务投影的parameter_source/parameter_status为standard（无字段的草稿为missing），公开目录继续使用schema_revision/ETag、input_schema与parameter_variants生成表单；客户身份/售价不归本契约。

全局POST /admin/v1/model-catalog/sync及Console facade现返回410 MODEL_PARAMETER_SYNC_RETIRED/model_parameter_sync_retired，不调用Provider或写入定义。图片渠道自己的discover-models保留版本、管理员会话及CSRF保护，仅读取当前Key的型号目录并保存发现快照。不会因已选模型而屏蔽新发现的可识别图片型号；显式配置的供应商别名也保留。渠道页面将同名标准型号加入关联草稿，异名选择标准型号生成标准名→上游名映射；保存渠道后生效，未匹配型号不自动生成标准定义。未知协议型号仍需明确映射，不能把价格表当参数Schema。

038仅新增parameter_variants存储列。升级在迁移后、启动新版API前显式执行cmd/catalog-freeze（默认dry-run，--apply才写入；私有GATEWAY_POSTGRES_URL）：把旧自动定义的有效参数及准确规格组合冻结；没有有效来源时保留最后保存的字段；保留人工定义、删除/发布状态，版本CAS前进并审计，失败整批回滚、重复运行不写入。新运行不调用该迁移操作。旧字段/历史发现快照保留兼容，禁止重新打开自动源逻辑。down保留列与组合；推荐只回退Console并保留新API，不把冻结组合降成旧版平面契约。

以下MG-CATALOG-03渠道自动投影及全局同步段落仅作历史实现说明，以本节为准。

任务 MG-CATALOG-02，2026-10-15。用户要求顶层归总视频/图片/音频对外型号，并让其他服务取得可配置参数生成网页表单。当前统一目录是技术型号与参数定义；客户可售范围、客户权限、售价/钱包/结算仍由 oceanway-platform 持有。

信息来源与生命周期

已有视频 PublicModel 和非归档图片渠道所选择的逻辑型号汇总为候选；同媒体/同调用名去重，不展开供应商或上游映射。候选在自动模式下直接投影已保存的渠道能力/参数，GET 不写入、不访问 Provider、不启用供给。无型号级参数的图片渠道只提供标为 basic 的协议基础字段，不推测尺寸、质量或数量限制。音频可人工登记目录定义，尚无音频供应/执行接口。

model_catalog_definitions 只保存面向调用方的技术定义：稳定 catalog_id、media_type+model 唯一、显示名/说明、参数、发布标记与版本。执行 PublicModel、图片渠道、供给与调度仍是执行事实，目录编辑不改这些表。可为尚无执行的型号先编写草稿。调用名称/媒体类型保存后不可改，显示名/说明/参数可按版本修改。

目录发布与执行发布独立：published 控制此参数定义是否进入服务读取接口；execution_ready 只表示既有视频执行目录 enabled+published 配置已打开，并非实时健康/容量保证。图片/音频当前固定 false。不得把目录发布当作真实生成验收或平台客户已可售；目录定义不替代执行 API 的最终请求校验。未知或尚未核实的能力保持草稿，不自动以供应商型号推测参数。

管理 API（独立管理员会话或管理 Bearer）

写入体：model、media_type（video/image/audio）、title、description、published、parameters。未知字段/类型拒绝。模型名1–120字符，由字母/数字开头，允许 . _ : / -；显示名非空最多120字符，说明最多2000字符；完整定义最多64KiB，最多64个参数。发布要求至少一个有效参数，草稿可为空。

更新行锁与版本CAS、唯一约束及审计同事务，失败回滚；冲突409并保留网页草稿，不自动换版本重发。权限由既有管理员边界保护，服务Key不能写。Console只通过同会话/CSRF/Origin的 /backend/model-catalog facade 写入，JSON version 转为 If-Match，凭据留在服务端。

服务读取 API

GET /v1/model-catalog，使用既有 Authorization: Bearer <GATEWAY_SERVICE_KEY>。服务端/BFF持有服务密钥，客户网页不持有网关Key。支持 ?media_type=video|image|audio、?model=<精确调用名>；未知/重复查询参数拒绝。返回已发布定义及有可用参数的自动候选；已保存的下架标记优先，空目录是空数组；不自动恢复历史 /v1/models 图片模块。

{
  "contract_version": "model-catalog.v1",
  "revision": "<sanitized-response-sha256>",
  "models": [{
    "model": "example-video",
    "media_type": "video",
    "title": "示例视频模型",
    "description": "按已核实能力配置",
    "version": 2,
    "execution_ready": false,
    "parameters": [
      {"key":"seed","label":"随机种子","kind":"integer","required":false,"minimum":0,"maximum":100,"default":0},
      {"key":"enhance","label":"提示词增强","kind":"boolean","required":false,"default":false}
    ],
    "input_schema": {"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"seed":{"title":"随机种子","description":"","type":"integer","minimum":0,"maximum":100,"default":0},"enhance":{"title":"提示词增强","description":"","type":"boolean","default":false}},"required":[],"additionalProperties":false,"x-order":["seed","enhance"]}
  }]
}

revision/ETag 对按媒体/型号排序的公开投影求哈希，发布、下架、参数/版本或执行配置状态变化都会改变它。支持 If-None-Match（包括弱标签/列表）返回304；Cache-Control private,no-cache，Vary Authorization。每份定义有自己的 version。读取没有生成、写数据库、获取素材、Provider网络或容量占用。公开响应使用显式DTO，绝不嵌入管理员配置/供应商/渠道/Supply/成本/绑定/凭据。

参数和表单渲染

共同字段：key（小写英文字母开头，最多64个字母/数字/下划线、不可重复或使用保留名）、label、description、required、可选 default。保持声明顺序。default 省略代表未设置，0和false完整保留，null不允许。参数说明最多1000字符，单位最多32字符。

数值绝对值不超过1e12；上下界、步长与默认值须一致。默认值必须匹配类型/范围/选项，不做字符串转布尔等隐式转换。input_schema 为JSON Schema 2020-12的本契约受限子集；x-order、x-unit、x-media-type辅助展示。客户端可直接按 parameters 渲染，也可消费 input_schema，并校验用户输入；媒体数组数量等规则不能仅依赖浏览器原生控件。

v1 人工定义仍是平面参数集合，不接受远程$ref、执行代码、任意JSON Schema 或供应商映射。MG-CATALOG-03 的自动参数另提供下述受限组合 Schema，客户端按声明的组合渲染，不自行猜测。此定义用于输入表单；调用服务按对应执行API转换请求，执行端仍校验真实供给能力。此批没有新增图片/音频生成端点。

页面与交付

顶层 模型→模型目录 /models 包含全部/视频/图片/音频筛选、状态/参数摘要、普通参数表单与预览/接口JSON。独立视频模型页已由 MG-NAV-02 退役，/models/video 转接 /models，原 /models/:id/dispatch 和视频/图片渠道入口保持。目录参数表单即时保存单定义；旧视频供应草稿/全量保存不承载该目录数据。

迁移033新增表，不触碰旧运行模型/供给/账务。回退代码保留表和所有定义；down只在表为空时允许。共享预览持锁前进迁移，生产部署/切流、平台跨仓联调和收费供给验收分别记录，见任务验收。

渠道自动参数（MG-CATALOG-03，2026-10-15）

use_channel_parameters 控制已保存定义是否随渠道更新。候选默认自动；既有非空人工参数保留，034只把空草稿设为自动。切换到人工模式时，页面复制当前字段作为编辑起点，之后不会被全局同步覆盖；发布/下架单独保存。新人工写入可不传此字段，默认 false，兼容旧客户端。

自动模式每次 GET 从最新已绑定 VideoCapability 和图片渠道最新有效发现快照计算，不依赖某次手动复制。渠道改名、容量/健康变化不会丢掉参数；协议、地址、凭据、所选型号或映射变化后旧发现参数失效，不能把旧账户的规格带到新渠道。归档/失去源时自动定义暂停对外返回，保留数据库定义与历史。人工定义仍由管理员控制。

图片优先使用渠道声明的 parameters 或 input_schema，适配器不再丢弃这些字段；类型/默认值/枚举/数量经过统一校验。当前支持受限平面 JSON Schema：string/integer/number/boolean、string enum、integer enum、URI素材数组、required、minimum/maximum/multipleOf/maxLength/minLength（已支持部分）、maxItems/minItems和展示元数据。嵌套对象、远程引用、执行代码、未知组合关键词、保留名、超限/不一致数据拒绝，不能悄悄放宽。没有 schema 时，OpenAI 图片仅有提示词和自由尺寸基础字段；Gemini 也只按已核对的具体渠道文档/适配器交集补参数，不把所有型号假设成相同能力。

vakv Gemini 3 Pro / 3.1 Flash 文档来源为 https://docs.vakv.cn/wendang.html（本轮服务器只读 HTTPS 获取，2026-10-15）；相关 preview 型号已在该渠道发现，按同系列文档配置并标为 documented，不冒充生成验收。size 选项在界面展示画幅（如16:9），调用值为16x9，经既有 Gemini adapter 转 aspectRatio；quality 为1k/2k/4k，经 adapter 转 imageSize；文档512档未通过现有adapter支持，未输出。其余未有型号文档或机器参数的型号保留 basic，不把官方直连能力当成中转供应商已经支持。

同步命令

POST /admin/v1/model-catalog/sync，body {}、管理员鉴权；Console 同会话/CSRF facade 为 POST /backend/model-catalog/sync。一次刷新所有未归档图片渠道模型目录（有界并发3、共享20秒预算，单通道失败保留已有快照并报告）；视频直接使用持久化规格。然后登记/刷新自动定义的最后参数快照，首次空草稿/自动候选加入参数目录，人工参数和已配置定义的主动下架标记保留。响应包含 updated/unchanged/manual/unavailable/channel_errors。单模型版本CAS与审计保持；跨模型不是全有或全无，失败可刷新后重试，已同步定义不会重复递增。不提交生成、不启用渠道或供给。

消费端新增字段

• schema_revision：参数与规格组合的内容哈希，自动源变化会更新，即使没有编辑记录写入。version 仍是保存定义的CAS版本，自动候选未登记时为0；消费者应以整表 revision/ETag 或 schema_revision 判断表单变化，不能只比较保存版本。
• parameter_status：synced（渠道能力/机器参数）、documented（已核对文档）、basic（仅协议基础字段）、manual（人工覆盖）；missing/unsupported 仅在管理端出现，无有效参数的自动定义不对外发布。
• parameter_variants：每个有效组合包含 label、parameters，以及可选 max_combined_references、prompt_or_image_required；不含渠道/Supply/上游ID、成本或凭据。根 parameters 是展示总览，不能把总览范围当作任意可混合的组合。
• input_schema.anyOf：对应每个有效规格组合，包含该组合完整属性/必填项/范围/选项。切换分辨率或规格时按匹配变体更新其他控件；完整 JSON Schema 校验用于验证合法组合。数值离散选项以 kind=integer, values:[4,6,8] 和 schema enum 数字数组输出，不转成字符串。媒体 min_items 对应 minItems。
• x-max-combined-references 与变体 max_combined_references 表示图片/视频/音频总数量上限，需要表单组件/消费端追加合计检查；标准 JSON Schema 不计算多个数组长度之和。prompt-or-image 条件另用标准 anyOf 表达。执行 API 始终作最终能力校验。

推荐消费流程：服务端带服务Key GET目录 → 用 revision/schema_revision 缓存 → 先显示媒体/模型 → 若有多个 parameter_variants 显示规格选择并渲染该变体字段，否则渲染 parameters → 按类型转换数值/布尔并省略未填可选字段 → 校验 input_schema 与素材合计 → 按对应API转换请求。客户网页不持有网关服务Key。目录参数存在不等于 execution_ready，图片/音频执行入口本轮仍不开放。

降级代码时保留034表列和已保存参数快照；旧版不再自动更新，也不能表达新增的组合/数值枚举语义。需要完整组合校验的消费端应要求 schema_revision/parameter_variants，缺失则停止使用该自动表单；优先只回退Console并保留本版API。034 down只移除策略列，不删除定义，但会把自动模式冻结为最后显式同步的快照。

模型系列展示（MG-CATALOG-05）

管理员定义新增 model_vendor 字符串，表示模型系列/原厂品牌，与实际采购渠道、供应凭据和选路无关。空串为按调用名自动识别；非空为1–40位小写字母开头、只含小写字母/数字/连字符的品牌标识。当前UI提供ChatGPT/OpenAI、Gemini、Grok、Sora、Veo、Seedream、Seedance、可灵、万相等27个选择，并本地展示对应LobeHub SVG；未知型号显示通用图标，未知显式标识原样保留。GPT图片如gpt-image-2.5使用ChatGPT/OpenAI标志。

POST/PUT可选传此字段，PUT省略时保留已有值（兼容旧客户端和渠道参数同步），显式空串切回自动。CAS/行锁/审计沿用，不改变执行配置；公开服务DTO暂不新增此管理展示字段。035迁移只加列，既有行默认空串，不批量改版本或推断写入品牌；应用降级可保留列，down会丢弃显式选择，须先导出。

模型目录列表与生命周期（MG-CATALOG-06）

目录仅展示模型身份、媒体类型、对应渠道、目录/调用状态及操作。Logo紧邻模型名称，视频调度的模型导航/标题、图片调度当前模型也使用相同系列Logo与显式model_vendor。可配置参数仍在配置窗口编辑，目录不展开参数标签或“表单与接口”入口。

管理员Entry新增 channels:[{id,name,status}]，从实际Supply绑定及图片渠道所选标准型号汇总，同模型同渠道去重，排除归档渠道及退役Supply。这里同时显示停用渠道，以表示配置关联，不宣称可用/验收通过；不向公共Descriptor暴露渠道身份。链接进入相应视频/图片渠道管理页。

DELETE /admin/v1/model-catalog/{catalog_id}，If-Match为当前定义版本，body {}，执行可恢复删除；POST /{catalog_id}/restore 相同版本/空体恢复。响应200与新定义/版本，缺少版本428，版本冲突409，未知字段400，已启用且发布的执行模型删除422（先停用调度）。沿用管理员鉴权/CSRF/同源Facade，浏览器请求body仅 {version}；不允许夹带定义/供给字段。

删除保留定义及品牌/参数、原ID、渠道/供给/绑定/历史任务，删除/恢复各原子递增版本并记录审计，不级联修改执行配置。已删除定义不能普通PUT，必须先恢复；模型发布门禁也拒绝已删除标准定义。默认管理员GET、公共服务目录、图片调度列表/详情/保存、视频调度选择器排除已删除定义；管理员GET可加 include_deleted=true 查看，网页“已删除模型”提供恢复。公共接口拒绝该管理查询。渠道派生及参数同步不能重新创建同名定义或清除删除状态。

未登记的自动候选（没有catalog_id）须先保存为标准模型再删除；同名删除记录占有原唯一键，新增遇冲突时从已删除列表恢复。036仅增加布尔标记，默认false；回滚应保留列与当前API，旧版API不理解隐藏标记会重新显示删除项，因此先核对恢复状态再降级。

官方标准参数资料（MG-CATALOG-08，2026-10-16）

现行来源为 tools/catalog-import/catalogs/official-models.json：按原厂文档集中维护15组可复用模板、16个现有型号，而不是从Key或Supply反推原厂规格。每组记录实际打开核对的官方URL、日期、限制及网关名称到原厂型号的对应关系。没有音频标准型号时不虚构音频表单。历史Origin资料是当时平台交集，不是原厂标准全集；新资料优先。参数说明随服务描述给出来源和适配边界。

本目录的范围是用户生成配置表单：提示词、素材、画幅、尺寸、质量、格式、数量、声音、创作模式等。鉴权、异步查询/重试、幂等、回调、任务TTL/队列优先级、计费和账户限额由调用服务管理，不作为客户表单控件。原厂标准不保证每个上游Key支持；execution_ready与实际供给校验保持独立。

重要型号差异：GPT Image 2.5有xhigh/max，2没有；GPT原厂返回base64，不再展示旧response_format/style/input_fidelity；Grok仅2.0有quality，不能凭价格表增加4K；Gemini不套用OpenAI的n/quality；3.1稳定版ImageConfig已核实512值，Preview官方字段页已下线，保留原已登记的1K/2K/4K而不推断512档。Gemini两个Preview原厂2026-06-25退役，保留上游调用名和历史表单并注明，不自动替换/删除/发布；2.5 Flash参考图片的3张是保守推荐用量，不是原厂硬限制。MiniMax-H3为768P/2K，不能套H3-Max或渠道的480P/720P/1080P；Seedance Fast/Mini不继承标准版1080p/4k。Seedance seed请求表仅明确1.0支持，2.5教程提及复用但未明确输入范围，暂不将未知范围伪装成已核实2.x参数。

表单约束扩展（向后兼容的v1字段）

• 参数 const：固定字符串/数值/布尔值，输出JSON Schema const。默认值必须相同；消费端把该控件锁定。用于Draft=true、文档/网页模式prompt_extend=true；false和0均可用。
• 字符串 format:"uri"：输出标准URI格式；输入URL的协议、权限、SSRF、文档类型等仍由执行服务验证。
• 字符串 dimension_limits：min_edge/max_edge、multiple_of、min_pixels/max_pixels、max_ratio（长边/短边）、allow_auto。输出 pattern 和 x-image-dimensions；先校验WIDTHxHEIGHT/auto，再计算边长、整除、像素乘积和长短边比例。JSON Schema本身不能计算像素乘积，消费端必须读此扩展，不能只使用pattern。GPT允许自定义合法尺寸，不用不完整的下拉枚举替代。
• 素材/URI文件 asset_limits：extensions、max_bytes、max_pages、same_dimensions_as（匹配指定图片字段的第一项尺寸）、dimensions、min_duration_seconds、max_duration_seconds、max_total_duration_seconds，输出 x-asset-limits。客户端先筛格式/大小，上传/媒体探测后验证尺寸、单段时长及同类总时长；不能仅凭URL字符串完成媒体校验。extensions是扩展名提示，执行端仍需检测实际媒体。
• 组合 requires_any:[key,...]：至少一个指定文本非空或素材数组非空，生成标准allOf/anyOf约束；不依赖中文label猜测模式。与旧prompt_or_image_required可叠加。
• 组合 max_video_and_output_duration_seconds：输出 x-max-video-and-output-duration-seconds，Wan输入视频时长与输出时长之和上限30秒。auto=-1不是负时长抵扣；自动时长交由模型选择并由执行端最终校验。

input_schema.x-required-features列出需要消费端实现的非JSON Schema能力：image-dimensions、asset-limits、combined-reference-count、combined-video-duration。消费端先核对自身支持这些能力，再选择parameter_variants中的组合，按该组合字段生成控件，填入默认值并锁定const，提交前校验完整input_schema和上述x扩展。根parameters仅作字段总览，不能把各组合混合成一个表单。忽略不理解的关键扩展会放宽约束，应停止提交并提示升级消费端。

网关规范字段不等于原厂请求体：视频duration_seconds→duration，aspect_ratio→ratio；首尾帧/参考素材根据字段角色组装content或input.media；Wan generate_audio→parameters.audio；MiniMax分辨率转768P/2K；Gemini prompt/素材→contents.parts，画幅/尺寸→generationConfig.imageConfig，response_modalities→responseModalities数组，搜索→tools，思考→thinkingConfig。GPT参考图片→images/edits的image、mask→单个mask；Grok参考图片→images[].url。调用服务按版本化执行API处理，不能把表单JSON原样POST到任意原厂端点。

校验与安全登记

go run ./cmd/catalog-validate 无数据库/Provider I/O，严格校验资料后输出与实际服务相同的16份表单Descriptor。node --test tools/catalog-import/register-standard-models.test.mjs 覆盖生命周期保持、缺失/删除跳过、所有版本预检、回读丢字段拒绝和重复0写入。

登记器默认只生成0600计划/旧定义备份，凭据仅从环境读取。显式apply-plan前再次核对资料哈希、所有模型ID/版本及旧参数，逐项使用If-Match。保持显示名、品牌、发布标记和删除状态；不创建缺失型号、不恢复删除项、不改渠道或供给。全局不是数据库事务，中途失败保留已成功的审计，核对后生成新计划继续；不能盲目重发旧计划。

回滚按计划的before定义和最新版本CAS恢复；先确认没有后续人工编辑。不回退迁移/任务/供应商配置。无需数据库迁移；旧代码不理解新增约束，因此有这批定义时应保留本版API，不能用旧Console保存而丢弃约束。