第三方适配器（长尾厂牌插件）

内置账号中心覆盖常见云厂牌。若你要用的厂商还没进账号中心，可以用第三方适配器：在独立插件包里对接厂商 HTTP API，再导入客户端使用。插件与客户端解耦——厂商地址、应用 ID 等写在插件包里，不会写进软件本体；需要密钥的插件在导入时填写，密钥只会保存在本机账号里，不会写进插件源码。

这是进阶能力。只跑通义 / 火山 / 可灵等内置厂牌时，不必读本章。先按最快上手把云端跑通。

现在能做什么

可用路径：用 Rust 写插件（编译成 adapter.wasm），导入 Rust / TinyGo 预编译插件，或使用更简单的 profile 方案（适合纯 HTTP、契约能表达的场景）。
暂不支持：需要 Python / JS 运行时的插件。当前版本不提供这类运行时下载，无法运行，请改用 Rust / TinyGo 预编译插件或 profile 插件。
隔离边界：插件不能随意访问本机磁盘、不能自己开 socket / 起子进程、不能 pip / npm。出网与执行由客户端宿主按契约放行。
能力范围：以契约能表达的厂牌为准（随包标本含视频与文生图槽）。不要理解成「任意网页 API、任意厂牌一键全通」。

你需要准备什么

一台已安装本软件的 Windows 电脑。
若导入未签名的 Rust 源码包（选文件夹让客户端现场编译），本机还要自备工具链（不随安装包附带）：
- rustc / cargo
- cargo install cargo-component
- rustup target add wasm32-wasip2
装完后重启客户端，设置页才能看到你用户 PATH 里的编译器。
厂商控制台里的专用 API Key（见下方安全说明）。
可选：Cursor、Codex、Claude Code、Trae 等能打开本地文件夹改代码的独立编程智能体（强烈推荐，见下文）。

安装包里的参考样例

安装目录下有切片示例（不是完整开发仓）：

user-examples\vendor-adapter-v1\

先读该目录的 README.md，它列出合同、Rust SDK、模板、六个案例和升级说明的入口。目录还包含 WIT、协议和 JSON schema；案例只是参考实现，字段以 HOST_PAYLOAD.zh-CN.md（或英文版）及合同文件为准。云案例里的 Key 是占位符，不能直接出片。

examples\runninghub-workflow\：AI App 教学标本（空时长/画幅绑定）。模型 adapter:local.example.specimen:workflow。
examples\runninghub-minimax-h3\：V2 MiniMax H3 工作案例（版本 0.7.1）。一次导入后可选 r2v 一至四槽、单图参考 turbo、首帧 fl2va 和音频对口型七档；先读 crate 内 AI_AUTHOR_GUIDE，二至四槽不要把节点 141 当成参考图，对口型要提供一张参考图和一条参考音频。不要导入 runninghub-workflow 代替它，后者只显示教学占位模型 Workflow。
examples\comfyui-lan-minimax-h3\：局域网 ComfyUI MiniMax H3 视频（t2v / turbo 单图 / turbo 多参）。模型 adapter:local.example.comfyui-lan-h3:h3.t2v 等。导入后在适配器凭证填 Comfy 地址（例如本机 http://127.0.0.1:8188）。这不是软件内置 Comfy 工作流库，也不是 RunningHub 云。
examples\comfyui-lan-z-image-turbo\：局域网 ComfyUI Z-Image-Turbo 文生图（独立插件，不并进 H3）。模型 adapter:local.example.comfyui-lan-z-image:z.turbo（一个模型，内置 10 档宽高预设）。默认地址 http://192.168.18.8:8188（凭证可改）。走文生图工作台。
examples\lan-openai-compat-text\：局域网 OpenAI 兼容文本。占位地址 http://192.168.0.10:11434（不会回落到公网）；凭证可填文本引擎地址或本软件的局域网网关 18380 端口。模型 adapter:local.example.lan-openai-compat-text:example-lan-llm。
examples\video-reference-media-probe\：离线探针案例，不连任何厂商，用来在视频工作台检查参考素材如何下发。模型 probe-offline / probe-offline-reject。

把整个标本文件夹复制到可写磁盘（例如文档或项目目录）。不要在 Program Files 里直接改。
复制后的文件夹根目录应能看到 Cargo.toml、manifest.json、wit\、vendor-sdk\、src\。导入时选这个根目录，不要只选 src。
云案例：需要密钥的插件在导入时会弹出「填写插件密钥」，Key 只保存在本机账号里；源码里的占位 Key 会被客户端硬性拒绝。局域网 Comfy 案例没有 Key，导入后只填适配器凭证里的 Comfy 地址。

优先在导入时把 Key 填进本机账号，不要写进插件源码。若仍把密钥写进插件并编译进 adapter.wasm，别人拿到包就有可能提取。请用专用、低余额、可随时吊销的 Key；不要分享打好的插件包；不要把真实 Key 提交到公开仓库。

在软件里导入与使用

打开 设置 → 第三方适配器。
选择导入插件包：
- 未签名 Rust 源码：选 crate 根目录（见上）。客户端会隐藏调用 cargo component build，把 manifest.json / adapter.wasm 等装进数据目录；不会把 wasm 写回你的作者目录。
- 已签名发布包：须自带预编译文件，客户端不会重编。
「导入时绑定账号」：选已有账号，或「自动创建（仅无需密钥的插件）」。需要密钥的插件会弹出「填写插件密钥」：密钥只会保存在本机账号里，不会写进插件源码；取消则不会安装。
编译失败时：界面会用人话 toast，设置页同时保留编译器原文，便于排查。
已经装过同一身份的插件时，软件会先问你是否覆盖。覆盖不会多出一张卡。若要两张独立的卡，先改源码里的 pluginId 再导入。随包多例身份不同，可以同时装。
卡片上的粗体名称可以双击改成你自己的叫法；灰色那行是身份，不能改。
导入成功后：视频类插件打开 生成视频；Z-Image 等文生图插件打开 文生图 工作台。在模型列表里选类似 adapter:插件ID:模型或工作流标识 的项，填提示词再提交。

RunningHub / 局域网 H3 视频案例请走生成视频；局域网 Z-Image 文生图案例请走文生图。AI App 标本未声明的时长 / 画幅 / 帧率会隐藏；H3 工作案例会露出这些档。换厂商图时先选定 API 族（AI App 或 V2），禁止在同一 crate 里做两套查询解析兼容；上传参考帧须按图片魔数定 MIME/扩展名，未知格式应失败，不要一律当 PNG。

适配器通道的凭证跟内置厂牌卡片不是同一套：选中 adapter:… 模型后按插件约定提交即可，一般不必再跑去「设置 → 账号中心」为这家长尾厂牌另填一张云厂牌 Key（除非该插件文档另有说明）。

推荐：用编程智能体帮你写插件

可以，而且这是我们推荐给非全职插件作者的做法。把「比格熊适配器 SDK + 模板/标本」和「厂商官方 SDK / OpenAPI / 示例」一并交给智能体，让它在独立插件目录里改代码、跑检查，再由你导入客户端验证。

请用能打开本地文件夹、直接改代码的独立产品（AI 编辑器或本机智能体）。不要用网页聊天，也不要只装编辑器插件。任选其一即可：

国际：Cursor、Claude Code、Codex、Devin Desktop（原 Windsurf）、Google Antigravity
国内：Trae（字节）、Qoder CN（原通义灵码独立 IDE）

建议丢给智能体的材料

比格熊侧（缺一不可）
- 安装目录 user-examples\vendor-adapter-v1\ 整份（或你从中复制出的模板 / 标本）
- 其中的 wit\、vendor-sdk\、manifest.json、模板 README
- 若你另有开发仓权限：同一套契约与标本更完整，但日常开箱以安装目录切片为准
厂商侧
- 官方 API 文档 / OpenAPI / SDK（REST 说明或官方示例均可）
- 鉴权方式、提交与查询接口、结果字段含义、限额与内容审核说明
- 若有「应用 ID / 工作流 ID / 节点参数表」，一并附上（不要让智能体瞎猜节点 ID）
你的目标一句话：例如「对接某某厂商文生视频，参数只要时长与画幅，Key 放在插件配置里」。

可直接粘贴的提示词骨架

下面这段对上表各产品通用：打开插件副本目录后，整段贴进对话即可。把【】里的能力槽换成你的真实目标。

你是比格熊数字导演的第三方适配器作者助手。
请只在我提供的插件 crate 目录内修改，不要改桌面客户端本体。

我已附上：
1) 比格熊适配器模板/标本（含 wit、vendor-sdk、manifest）
2) 目标厂商的官方 API/SDK 文档

目标：实现可导入的 Rust 适配器，能力槽为【视频/生图/文本…按实填写】。
约束：
- 遵守 crate 内 README 与 WIT 契约；厂商专有字符串只留在本 crate
- 不要引入 WASI、不要访问真实文件系统、不要 subprocess
- 先选一种厂商 API 族（例如 RunningHub AI App 或 OpenAPI V2），禁止同一 crate 兼容双解析
- 参考图按内容魔数定 MIME/文件名再上传；未知格式显式失败，不要默认 PNG
- capabilities 只声明宿主认识的运行时能力字段；不确定的参数宁可不声明
- Key 使用占位符常量名，由我本地替换；不要把真实 Key 写进仓库
- 说明如何用「设置 → 第三方适配器」导入，以及在哪个工作台选 adapter:… 模型做联调

先读模板与标本，再改代码；改完列出自测步骤与已知限制。

和智能体协作时的注意点

绿不等于能出片：模板自检 / hello 通过，只说明宿主能加载；真正可生成还要厂商接口、鉴权、参数绑定都正确。
小步验证：先导入成功 → 模型列表出现 adapter:… → 再提交一条最短任务；失败时读软件内提示和「AI 任务」，把日志要点贴回给智能体继续改。
不要让智能体「兼容兜底」：厂商 A 失败时不要偷偷改调厂商 B；选什么通道就走什么通道。
签名发布（可选，面向分发）：正式对外分发通常需要预编译与签名信任流程；个人自用导入未签名源码包即可。对外发布细节以软件后续说明或官方渠道为准。

安全名单、探测与卸载

卡片上会标已签名或未签名 · 高风险 · 无法验证来源。未签名插件只在你信任来源时使用。
「刷新安全名单」联网更新名单；名单过期太久时，未签名适配器会被停用，刷新后再试。
「探测就绪」检查插件当前是否可用；不需要时点「卸载」。
「打开随包案例」直接打开安装目录里的 user-examples\vendor-adapter-v1\。

给插件开发者的契约入口

若你在开发/调试第三方适配器（含用 Cursor、Codex、Trae 等协助编写），请先读安装目录 user-examples\vendor-adapter-v1\ 里的对外字段契约（中文、英文各一份，不要读混排版）：

中文：HOST_PAYLOAD.zh-CN.md
English：HOST_PAYLOAD.en.md

标本 examples 只是案例，不是字段标准。

契约说明宿主在 payloadJson 里下发哪些字段、插件必须回传什么。不要只看 SDK README 里的玩具 prompt 例子。

常见问题

设置页找不到编译器	工具链装好后重启客户端；确认用户 PATH 里有 `cargo` / `cargo-component`。
导入时选错目录	必须选含 `Cargo.toml` + `manifest.json` + `wit` + `vendor-sdk` 的根，不要选 `src`。
占位 Key 被拒绝	正常。换成你自己的专用 Key。
模型列表没有 adapter 项	确认导入成功；到生成视频（或该插件声明的槽位对应工作台）再看模型下拉。
任务一直跑 / 很久	部分云厂牌查询可能数分钟到数小时；以界面与「AI 任务」状态为准，不要反复换模型碰运气。
想用 Python 写插件	需要 Python / JS 运行时的插件当前版本无法运行。请改用 Rust 模板、Rust / TinyGo 预编译插件或 profile 插件。

配好后，创作流程仍回到软件内学习专栏（帮助）。密钥与内置厂牌申请入口见账号中心与厂牌；排障见注意事项。