常见问题 | New API

排查任务插件的权限、导入、兼容、路由、渠道、计费与产物问题。

为什么看不到任务插件页面，或返回 403？

插件管理页 /task-plugins 和 /api/plugin/task 管理接口要求 Root。具有普通管理员角色或模型 API 密钥并不足够。还需确认部署版本包含任务插件功能。

管理员在渠道中选择插件则使用独立的插件绑定权限。参见渠道配置。

点击「重新加载」。市场数据按文档域名从对应官网读取：.pro 使用 www.newapi.pro，.ai 使用 www.newapi.ai，本地预览默认使用 .ai。中文语言本身不会切换数据源。

站点暂时无法读取数据时，安装和开发教程仍然可用。部署文档站的管理员应检查服务端到对应官网的网络，及公开 /api/v1/plugins 接口是否可达。

确认粘贴的是完整 plugin.js 地址，而非 HTML 市场页或 GitHub 的 blob 页面。检查浏览器能否读取该地址、源站是否允许跨域请求，以及源码是否超过 1 MiB。

使用文档站市场的复制按钮可以获得官网托管地址。若剪贴板权限不足，复制失败后会显示可手动选中的地址。

不要绕过校验继续安装。刷新市场目录后重新读取源码，检查源站是否正在发布，或镜像是否缓存了不匹配的版本。市场发布者应确认源码与生成的索引一同发布，已发布版本没有被覆盖。

手动上传和普通 URL 导入不应被描述成已完成市场索引哈希校验。完整流程见安装与管理。

API v1 中可能增加 usageProfiles、unitLabel、requiredCapabilities 或 SSE 能力。旧宿主会拒绝不支持的字段和能力，即使版本号同为 1。

先阅读发布日志，再升级到支持这些能力的宿主；或者选用与当前宿主兼容的插件版本。不要简单删除能力声明来绕过校验。

查看错误中指出的另一插件，核对双方 channelTypes 与原生路由。旧渠道类型的所有权必须唯一，原生路由也不能注册冲突的 HTTP 方法与路径形状。

同一宿主协议下共享模型本身是允许的，不必仅因模型名相同就移除插件。先确认冲突的实际类型，再调整版本或插件配置。

依次检查：

安装插件不会自动创建可用渠道，也不会替管理员决定价格。

查看实际执行插件为当前模型声明的 schema。共享模型的不同提供方可能报告不同字段；模型默认表达式不兼容时，为该插件保存独立表达式。

升级引起用量字段或 profile 变化时，旧表达式不会自动迁移。对照 Migration 修改相关价格，详见用量与计费。

检查任务日志、上游认证和响应状态。404/410 会进入失败退款；401/403、429、5xx 或网络失败会累计轮询失败。未知任务状态也算失败，不应被插件强行转换成 IN_PROGRESS。

宿主默认在连续 20 次轮询失败后将任务标记失败，还受 TASK_TIMEOUT_MINUTES 控制的任务超时机制约束。先定位上游错误或解析问题，不要只调大失败次数。

Root 可以读取各节点的 GET /api/plugin/task/runtime/status，查看当前 generation、数据库 override revision、最近重建结果和插件级错误。

generation 是节点本地编号，不同节点间应比较数据库 revision。数据库暂时不可读时，接口仍会返回节点已有状态，并带有 database_error。新版本也必须继续解析进行中任务的数据，因为后台轮询可能使用新激活的版本。

以 DEBUG=true 启动 New API，并按 task_plugin 过滤日志，可查看注册、路由、渠道选择、提交、轮询与协议观察事件。请求相关事件带 request id，后台事件可能标记为 SYSTEM。

插件 console.log 在 DEBUG 模式也可能被转发。不要输出密钥、认证头、请求 body、完整上游 payload 或私有 URL。单个钩子的验证可使用开发指南中的沙盒与 fixture。

先确认任务成功且插件实现了产物钩子，再使用实际返回的 artifact key 或 content_url。检查 TaskPublicAddress；未设置时宿主回退到 ServerAddress。

多节点部署需要共享有效 CRYPTO_SECRET。已签发的产物访问链接没有过期时间，但轮换密钥会使旧链接失效；请求时仍需要能加载任务及相应插件。不要公开传播带访问凭据的产物链接。

如果同 key 存在内置插件，停用或删除自定义覆盖版本会恢复内置实现。内置插件不能单独删除或停用；关闭总开关则会停止整个插件系统，包括其他插件。