任务插件管理

• 任务插件管理仅 Root 可访问，Root 从侧边栏「管理员」 → 「任务插件」或访问 /task-plugins 进入管理页。
• 任务插件把图像、视频、音频等异步任务平台接入 AIMirrorX 的统一任务接口。
• 插件是 JavaScript 脚本，在 AIMirrorX 内置的沙盒中运行，通过「任务插件」类型渠道（或绑定了插件扩展的 AIMirrorX 渠道）接入渠道路由。

任务插件管理概览

页面顶部提供「启用任务插件」全局开关，下方为「已安装」「插件市场」两个标签页。已安装标签用于查看、上传和管理插件；市场标签从配置的索引源浏览和安装插件。

全局启用开关

• 「启用任务插件」开关对应系统选项 TaskPluginEnabled。
• 启停只有两个层级：全局主开关和每个插件各自的启用开关。关闭主开关时，整个任务插件系统（包括出厂与自定义插件）立即停止服务。

已安装与市场

• 「已安装」：列出当前注册的任务插件，支持表格/卡片视图、搜索、分页与排序。
• 「插件市场」：从已配置的市场来源浏览可安装插件，安装流程与手动上传完全一致。

任务插件简介与内置插件

任务插件描述了一个异步任务平台如何提交任务、查询结果、提取用量与产出结果。插件声明自己支持的模型、可绑定的渠道类型、计费参数与能力端点。插件与渠道两层分离：上传插件只注册插件能力，不会自动创建渠道；需另行创建「任务插件」渠道并绑定插件 Key（见「创建任务插件渠道」）。

插件分为三层来源：

• 出厂插件：随 AIMirrorX 内置，源码以 //go:embed 方式嵌入（plugins/tasks/<key>/plugin.js），启动时自动注册。出厂插件不可独立删除。
• 自定义插件：通过上传或市场安装的覆盖层，与同名出厂插件按 Key 关联，可以覆盖出厂插件的某个版本。
• 第三方插件：与出厂插件不同名的插件。

AIMirrorX 当前内置以下出厂插件（随版本更新，以实际列表为准）：

创建任务插件渠道

插件本身不参与路由；要让某个平台可调用，需要创建「任务插件」类型的渠道并绑定插件 Key。也可以把插件作为扩展绑定到 AIMirrorX 渠道，见网关渠道。

前置条件

1. 目标插件已启用，且「运行状态」为「已注册」：出厂插件无需上传，其他插件需先上传或从市场安装。被禁用的插件不会出现在可选列表中。
2. Root 默认拥有创建渠道权限；Admin 需由 Root 在管理员权限矩阵中授予渠道操作权限和 task_plugin.bind（绑定任务插件）权限，否则创建渠道时看不到「插件」分类。
3. 准备好上游服务地址与凭证（API 地址、API Key 等，按插件接入的平台要求）。

操作流程

• 任务插件-创建任务插件渠道

1. 进入「渠道管理」 → 「创建渠道」。
2. 在弹出的选择对话框中切到「插件」分类，点击目标插件卡片（卡片显示插件名称、描述、Key 和模型数）。
3. 进入渠道表单后，渠道类型自动设为「任务插件」；名称为空时填入插件名，「模型」中填入该插件声明的全部模型。
4. 填写「API 地址」（必填），即插件请求的上游地址。插件声明了默认地址时会自动填入，下方显示「插件默认值」；未声明时下方提示「该插件未声明默认地址，必须手动填写」。
5. 填写「API 密钥」——渠道 key 会作为插件环境的 apiKey 传入。
6. 核对模型、分组，按需设置优先级/权重、标签、状态等（通用字段见渠道管理）。
7. 保存渠道。保存后可使用实际模型发起一次异步任务验证。

字段说明

已安装插件

列表视图

「已安装」支持表格与卡片两种视图。两种视图共用同一份插件数据，卡片视图把常用信息集中展示，表格视图更适合排序与批量查看。列表可按名称、Key 搜索，并支持分页、排序与列设置。

• 任务插件-表格视图

• 任务插件-卡片视图

列表字段

运行状态

行操作

• 详情：打开插件详情面板，包含概览、计费参数、插件源码、版本历史、源码差异和插件沙盒。
• 上传新版本：为该 Key 上传一个新的版本。
• 删除当前自定义版本：只对自定义插件可用，出厂插件该项为灰色。删除前会确认后果，并检查插件是否仍被使用，见删除当前自定义版本。

上传插件

点击「上传插件」打开上传对话框。上传即注册一个新的插件版本；同名 Key 的多个版本保存在数据库中，同一 Key 同一时刻只有一个版本处于激活态。该 Key 的首个版本上传后自动激活；已有激活版本时，新上传的版本只保存、不激活。

• 任务插件-上传插件

• 任务插件-上传新版本

1. 核对「第三方插件风险」提示：上传插件是管理员级别的信任决策。插件可以访问渠道凭证并构造上游请求，激活前应审查源码。

2. 选择源码来源，支持三种方式：

   • 拖放或选择 .js 插件文件；
   • 直接粘贴 JavaScript 源码到编辑器；
   • 在「从 URL 导入」中输入插件源码 URL 并点击「拉取」，由浏览器拉取源码填入编辑器（GitHub / gist 页面地址会自动改写为 raw URL）。

   源码填入后，下方会预览插件声明的适用渠道、上游认证方式、默认 API 地址、额外访问域名和支持的模型，可在上传前核对。

3. 按需选择「插件图标」（与 plugin.js 同目录的 icon.svg 或 icon.png，最大 512 KiB），并填写「备注」（可选），用于描述该版本。

4. 点击「上传」。服务端会先编译源码并校验元信息，再执行路由冲突预检；通过后保存版本并同步注册表。被拒绝时，对话框显示「网关拒绝了该插件」及具体原因（冲突时会写明冲突的插件）。

5. 上传成功后，对话框显示「插件上传成功」及插件名称、Key 和版本。首个版本会直接激活；该 Key 已有激活版本时显示「插件已保存，待激活」，可点击「立即激活」替换当前版本，或点击「稍后」，之后在插件详情的「版本历史」中激活。

上传参数与限制：

插件元信息

routes 与 protocols 决定插件如何接入请求；usageSchema 决定任务结果如何计费（见「插件详情」 → 「计费参数」）。只有与插件声明的模型、渠道类型相匹配的请求才会路由到该插件。

插件市场

「插件市场」标签页从已配置的市场来源（每个来源提供一个 index.json，列出可安装插件）浏览并安装插件。市场索引与插件源码都由浏览器拉取，网关不发起任何外部请求，因此不存在服务端 SSRF 面。

• 任务插件-插件市场

浏览与安装

• 任务插件-安装插件-插件详情

• 任务插件-安装插件-版本差异

• 任务插件-安装插件-完整源码

• 任务插件-安装插件-更新日志

1. 若配置了多个来源，先切换目标来源；点击「刷新」重新拉取当前来源索引。
2. 浏览插件列表（卡片右上角显示「未安装」「已是最新」或可升级的 v旧 → v新），点击卡片上的「安装」打开安装对话框，在「选择版本」中选择要安装的版本（默认最新版本）。
3. 在对话框各标签中核对插件：「插件详情」显示支持的模型、支持的接口和连接配置（适用渠道、上游认证方式、默认 API 地址、额外访问域名）；「版本差异」对比已安装版本与所选版本的源码（仅已安装该插件时显示）；「完整源码」显示所选版本的全部源码；「更新日志」显示该版本的更新说明，没有当前语言版本时显示英文。
4. 若索引未提供 sha256，会提示「无完整性哈希」：无法确认下载到的源码与该源所发布的内容一致，但不阻止安装。
5. 若浏览器拉取源码后计算出的哈希与索引不一致，会提示「完整性校验失败」并阻止安装。
6. 点击「安装并启用」；已安装该插件时，新版本安装后会自动激活。安装走与手动上传完全相同的审查与准入流程：服务端会重新计算收到的源码哈希。索引与哈希均由浏览器提供，服务端不校验市场索引；篡改的浏览器可同时替换源码与哈希，因此完整性检查不能防止此类篡改。

市场来源管理

• 任务插件-市场源

点击「管理源」打开「市场源」对话框。每个来源包含：

默认提供两个官方源：Official（来源切换按钮中显示为「官方」，https://www.newapi.ai/api/v1/plugins/index.json）和 GitHub（https://raw.githubusercontent.com/QuantumNous/new-api-plugins/main/index.json）。在对话框中添加、删除或编辑来源后点击「保存」，整张列表一次保存并立即生效；「取消」放弃本次修改。删除全部来源后不会自动恢复默认源，需要时手动重新添加上述地址。索引由浏览器拉取，主机需允许跨域并能从浏览器所在网络访问；无法访问时，可在「上传插件」中手动上传插件源码。

插件详情

从列表的「详情」操作打开插件详情面板，包含「概览」「计费参数」「插件源码」「版本历史」「源码差异」「插件沙盒」六个标签。

概览

• 任务插件-插件详情-概览

「概览」标签显示三部分：「插件元数据」（排序优先级、拉取模式、渠道类型、插件官网、默认 Base URL）、「模型」（可「复制全部模型」）和「端点」（「标准协议接口」与「插件自定义接口」的方法和路径）。

计费参数

• 任务插件-插件详情-计费参数

插件可在 usageSchema 中声明计费参数。「计费参数」标签按适用模型分组列出参数表，列为名称、类型（数值/布尔/枚举）、单位（秒/数量/token/credit，插件可自定义单位名，如「张」）、枚举值和说明信息。任务模型的计费表达式用这些参数计价，见计费表达式；未声明时显示「未声明计费参数」。

插件源码

• 任务插件-插件详情-插件源码

显示当前激活版本的 JavaScript 源码（出厂插件显示出厂源码），便于人工审查。审查时重点确认插件访问的主机、读取的凭证以及构造的上游请求。

版本历史与激活

• 任务插件-插件详情-版本历史

列出该 Key 已上传的所有版本（按上传时间倒序；只有出厂版本时显示「暂无版本历史」），当前版本显示「生效」。点击其他版本的「激活 / 回滚」使其成为当前生效版本；激活前服务端会先编译该版本源码，激活后插件同时被启用。

源码差异

• 任务插件-插件详情-源码差异

在「选择要比较的版本」中选择一个历史版本，按行显示它与当前激活版本的源码差异；两者相同时显示「源码无变化」。

插件沙盒

• 任务插件-插件详情-插件沙盒

插件沙盒用于在不真正发起上游请求的情况下，验证当前激活版本的钩子行为：

1. 选择钩子（如 buildSubmitRequest、parseSubmitResponse、extractUsage、buildQueryRequest、parseTaskResult、buildBatchQueryRequest、parseBatchResult、buildContentRequest、renderers.openai_video 等）。
2. 以 JSON 数组填写参数（必须是数组）。
3. 点击「运行干跑」，查看 JSON 结果；若钩子或参数错误，会在结果中显示错误信息。

启用、禁用与删除

启用与禁用单个插件

插件行（或卡片）的「已启用」开关用于启停单个插件，切换前会弹出「启用插件？」或「禁用插件？」确认框；出厂插件也可以单独禁用。禁用时若插件仍被启用渠道或在途任务使用，会弹出「插件仍在使用中」，列出这些渠道和在途任务数：

• 点击「级联禁用渠道」（有启用渠道时显示）：把使用该插件的启用渠道改为手动禁用（禁用原因记录为 task plugin disabled），然后禁用插件；AIMirrorX 渠道不会被禁用，只解除对该插件的绑定。仍有在途任务时此按钮无法完成禁用，需点击「强制操作」。
• 点击「强制操作」：同样按上述方式级联处理渠道，并且不等待在途任务，直接禁用插件。

删除当前自定义版本

• 任务插件-删除插件版本

仅自定义版本可删除（出厂插件不可删除）。删除前会弹出「删除插件版本？」确认框：

• 若存在同名出厂插件：提示「删除此自定义版本不会停用平台，同名出厂插件将自动恢复。」
• 若没有出厂回落版本：提示「此插件没有出厂回落版本，删除或禁用后该平台将不可用。」
• 若没有同名出厂插件，且插件仍被启用渠道或在途任务使用：会弹出「插件仍在使用中」，可点击「强制操作」继续删除。

删除后，若该 Key 还有其他已上传的版本，系统会激活其中最近上传的一个（被激活的版本沿用它自己的启用状态）；没有剩余版本时，有同名出厂插件则恢复出厂插件（该 Key 已被禁用时除外），否则该平台不可用。

全局开关

关闭页面顶部「启用任务插件」会立即停用整个任务插件系统（出厂插件和自定义插件都停止服务），新的插件请求会被拒绝；在途任务由超时清理处理，见任务超时与清理。

任务超时与清理

• 在途任务指 platform 为插件 Key 且状态不是成功/失败的任务。
• 禁用插件不会取消任务；超时任务由全局轮询清理扫描，达到 TASK_TIMEOUT_MINUTES（默认 4320 分钟，即 72 小时，从任务提交时间算起；设为 0 表示不按时长超时）后标记失败，非旧版任务会退还额度。该清理仅在 UPDATE_TASK 开启时运行；关闭后，超时任务不会被标记失败，也不会退还额度。
• 连续轮询失败上限由 TASK_POLL_MAX_FAILURES（默认 20）控制。

推荐配置流程

1. 确认当前账户为 Root，并确认管理员具备所需渠道权限（创建任务插件渠道需要 task_plugin.bind）。
2. 打开「任务插件」页，确认全局「启用任务插件」开关已开启。
3. 上传插件源码，或从市场安装所需平台插件；上传/安装后核对解析出的 Key、版本、渠道类型与模型。
4. 在「已安装」列表检查插件运行状态是否为「已注册」；若为编译失败或未注册，按详情与错误信息处理。
5. 前往「渠道管理」创建任务插件渠道（在「插件」分类中选择插件），填写 API 地址、API 密钥与分组；确认模型自动填充是否符合预期。
6. 使用实际模型发起一次异步任务请求，通过任务日志确认提交、查询与结果解析正常，并检查计费参数是否生效。
7. 需要切换插件版本时，先在插件详情的「版本历史」中激活目标版本，再用实际模型发起任务验证。
8. 变更或禁用插件前，先确认绑定的渠道与在途任务，必要时执行级联禁用，避免请求路由到不可用插件。

故障排查

相关文档

• 渠道管理：创建「任务插件」类型渠道、为 AIMirrorX 渠道绑定插件扩展、配置分组与路由映射。
• 日志与异步任务：查看任务日志、任务状态与后台处理。
• 模型配置：配置全局模型行为与模型部署。
• 计费与支付配置：配置额度单位、模型与分组价格。
• 计费表达式：为任务模型配置使用插件计费参数的任务表达式。