MG-03-008 视频插件兼容架构

2026-10-14，MG-PLUGIN-02。用户授权架构/Skill/视频兼容层；禁止部署、切流、业务数据迁移与收费调用。

来源与版本

格式基线：new-api v1.0.0-rc.44，Plugin API v1。复用 pkg/jsplugin 的 MoeJS 引擎与 utils，依赖 moejs v0.1.0-alpha.6；不引入 new-api 全平台。升级须显式评估 SDK 差异。来源、固定提交、AGPL-3.0 许可证与改动见 internal/provider/newapiplugin/UPSTREAM.md。

责任与持久化

现有调用方接口 → Planner/Supply/Dispatcher → new-api-video Go adapter → JS driver → Provider。Poller、租约、Reconciler、下载、对象存储和费用关联沿用现有实现。插件输出请求描述符；Go 决定允许的 URL、方法、凭据、超时、响应大小和实际 I/O。JS 的 utils.fetch 仅允许有界 GET/HEAD 读取，不能生成付费任务。

Schema 3 是本网关安装信封：key/name/revision/documentation_url/models/source + plugin_version/source_hash；provider_kind/adapter_profile=new-api-video，request_profile=new_api_video。source 是完整、同步 ESM plugin.js；meta.apiVersion=1，key/version 必须匹配信封。官方四个任务钩子保持签名：buildSubmitRequest(ctx)、parseSubmitResponse(ctx,response)、buildQueryRequest(ctx)、parseTaskResult(ctx,body,response)。安装不可变；key/version 与 revision 都不能覆盖，SHA-256 校验源代码。Supply/Attempt 固定 plugin_id，轮询永远读取原插件，而不是当前渠道绑定。

提交成功保存去密且有界的 taskData/state、模型/上游模型/action/publicTaskId 作为 provider reference 的附加 JSON；已有 reference 无此字段仍可读。任何发送 POST 后的网络错误、5xx、错误解析或无法安全保存状态进入 submission_uncertain，禁止再次付费创建。publicTaskId 在兼容层为 AttemptID，与现有上游 client_task_id 一致。不向插件注入客户身份/账务。

本批支持范围

支持 per_task、vendor、api_key/none、JSON POST 提交与 GET 查询、HTTPS 同 Base URL origin 或显式 allowedHosts、签名/编码/JSON utilities、GET/HEAD utils.fetch、SUCCESS/FAILURE/进度归一化。无跨 origin 默认凭据转发；拒绝重定向、私网请求与危险路径，网络防护复用现有安全传输。插件元数据模型列表是声明，不能作为真实目录或验收证据；上游目录通过可选 OceanWay discoverModels/discoverPrices 扩展读取，不是官方必需钩子。无扩展则返回不可用，禁止伪造连接成功。

初期明确拒绝 batch、SSE、multipart/FilePlaceholder、OAuth、new_api 上游、非视频运行入口。需要执行这些不支持能力的插件在安装/描述符检查时给出不支持错误，不能静默降级。官方 native/protocol renderer 不接管网关公开路由，网关保留 OpenAI/ModelArk 契约。usage 定义可保留为文档，计价与结算不执行插件表达式。

结果 URL 走现有 TemporaryResult 与受保护下载；StarFrame 的鉴权内容端点用 buildContentRequest 描述，支持现有固定 /v1/videos/{taskId}/content 鉴权形式与 credentialless HTTPS 结果链接，凭据不持久化。暂不声称兼容所有 marketplace 插件。

首批上游

StarFrame：/v1/videos + /v1/videos/{id} + content，bearer JSON，容易适配。保持模型规格校验、client_task_id、reference 角色，成功取得授权内容而不伪造结果 URL。

Wangpai：/models 动态 inputs + /generations；以只读 utils.fetch 读取动态 schema，把显式请求逐项映射，未知参数/角色拒绝。HTTPS URL 输入可以使用插件；需要上传为资产 ID 或预处理的协议继续使用已有 Go 原生能力，不能用 GET-only utils.fetch 偷做上传。模型/价格读取是目录观察，采购价格发布与真实验收另行完成。

两个示例是仓库插件源，未安装到业务库、未绑定现有渠道、未启用或真实收费验收。

运维与回滚

新管理员入口 /new-api-plugins/validate、/new-api-plugins、/channels/{id}/new-api-plugin；旧插件写入口继续关闭。所有写操作经过现有管理员鉴权、审计、渠道版本与停用保护。渠道更换插件重置相关供给验收，已接受任务用固定版本继续执行。回滚停止新增新 profile 渠道；已创建任务须保留本版本执行器直到终态。纯代码回退不能删除不可变插件或任务附加字段。

没有运行服务重启、生产迁移、线上入口切换或新增收费请求。

可原样保留官方插件的额外协议 renderer 与 extractUsage* 导出，但本网关不调用或开放它们；计价/结算仍属原有内核。官方 openai_video.decodeRequest 可用于将当前请求转为 driver body，不能改选 Supply、模型或建立新路由；本批通用 decoder 仅接受文生视频，素材请求使用经明确映射的渠道插件（两个示例）或既有 Go 原生适配器，拒绝隐式改变素材角色。

原样官方兼容 Fixture：new-api-plugins Hailuo 1.2.1，固定提交 5754eb24c3ad2bf65760b952a9154ffafcdbdb4c；未修改源文件，覆盖文生视频 decoder、提交、轮询、只读获取签名下载地址。额外 usage/Responses renderer 保留但不执行。此证据为隔离模拟，不是上游在线验收。

供应商最新在线文档本轮无法读取；两个渠道示例的协议来源是已有 adapter 与其带日期的证据，发布前由管理员核对最新文档、实际型号和账户能力。

即时同步结果（immediate）尚无独立执行路径，本批插件需返回可继续查询的任务；不把无法查询的同步视频结果冒充异步任务。控制状态仅保存 48 KiB 原始 JSON，预留 JSONB 空白开销；数据库硬限 64 KiB。