UnityAI 第三方插件开发指南

版本: 5.0
更新日期: 2026-06-16
适用对象: 第三方开发者、社区/官方精选审核员

---

插件部署模式

UnityAI 插件系统支持两种部署模式，开发者在提交时选择：

模式	说明	适合场景
托管 (managed)	上传代码包，由 UnityAI 平台部署和管理	轻量插件、初创开发者
自托管 (self-hosted)	开发者自行部署服务，提供访问 URL	有独立服务器、需要自主控制

托管模式

• 提交 .tar.gz / .zip 压缩包 + process_config
• 平台审核通过后自动部署，分配端口，管理进程生命周期
• 平台负责健康检查、自动重启、资源限制

自托管模式

• 开发者自行部署 HTTP 服务到公网
• 提交时提供 self_hosted_url（HTTPS 生产环境必须）
• 可选提供 API Key（平台加密存储，运行时解密使用）
• 平台每 5 分钟做一次可用性检查，状态显示在插件详情页

---

安全模型（完全隔离）

iframe 第三方插件与 UnityAI 主应用 完全隔离：

插件 不能 获得	插件 只能 通过宿主代理
Bearer token / plugin_token	AI_CHAT_REQUEST → 宿主代为调 AI
用户 ID、邮箱、头像等 PII	AI_MODEL_CONFIG_REQUEST → 宿主返回模型列表
API 端点 URL	CONFIG → 仅 { ai: true, aiMode: 'host-proxy' }
消息、联系人、日历、存储等数据	无其他数据通道

插件在用户打开时才能通过宿主使用 AI；宿主关闭 iframe 后会发送 DESTROY，代理通道终止。

---

通信协议（postMessage）

插件 → 宿主

// 1. 就绪
window.parent.postMessage({ type: 'PLUGIN_READY', version: '1.0.0' }, '*');

// 2. 请求 AI（流式）
const requestId = crypto.randomUUID();
window.parent.postMessage({
  type: 'AI_CHAT_REQUEST',
  requestId,
  body: {
    model: 'gpt-4o',
    messages: [{ role: 'user', content: '你好' }],
  },
}, '*');

// 3. 请求可用模型
window.parent.postMessage({ type: 'AI_MODEL_CONFIG_REQUEST', requestId: crypto.randomUUID() }, '*');

宿主 → 插件

// CONFIG — 无 token、无用户信息
{ type: 'CONFIG', capabilities: { ai: true, aiMode: 'host-proxy' } }

// AI 流式响应（SSE 原文分块）
{ type: 'AI_CHAT_CHUNK', requestId, chunk: 'data: {...}\n\n' }
{ type: 'AI_CHAT_DONE', requestId }
{ type: 'AI_CHAT_ERROR', requestId, code, message }

// 模型列表
{ type: 'AI_MODEL_CONFIG', requestId, config: { default_model, available_models, aiMode: 'host-proxy' } }

// 关闭
{ type: 'DESTROY' }

插件侧监听示例

window.addEventListener('message', (event) => {
  const data = event.data;
  if (!data?.type) return;

  switch (data.type) {
    case 'CONFIG':
      // capabilities.aiMode === 'host-proxy'
      break;
    case 'AI_CHAT_CHUNK':
      // 解析 SSE chunk，更新 UI
      break;
    case 'AI_CHAT_DONE':
      break;
    case 'AI_MODEL_CONFIG':
      break;
  }
});

---

提交与上架流程

托管模式提交

# Multipart POST
curl -X POST https://api.unityai.chat/api/plugin-store/submit \
  -H "Authorization: Bearer <your-token>" \
  -F 'metadata={"id":"my-plugin","name":"我的插件","version":"1.0.0","plugin_type":"process","hosting_mode":"managed","process_config":{"runtime":"python","entry_point":"main.py","port":8000,"ui":{"type":"iframe","width":1200,"height":800}}}' \
  -F "file=@my-plugin.tar.gz"

自托管模式提交

curl -X POST https://api.unityai.chat/api/plugin-store/submit \
  -H "Authorization: Bearer <your-token>" \
  -F 'metadata={"id":"my-plugin","name":"我的插件","version":"1.0.0","plugin_type":"process","hosting_mode":"self_hosted","self_hosted_url":"https://my-plugin.example.com","self_hosted_api_key":"sk-optional-key"}'

自托管无需上传代码包

自托管模式下 file 字段可选。如果你有文档/图标等附件可以一并上传，但不强制。

提交字段说明

字段	类型	必需	说明
id	string	是	唯一标识，字母/数字/连字符/下划线
name	string	是	显示名称
version	string	是	semver 版本号
plugin_type	string	是	固定为 "process"
hosting_mode	string	是	"managed" 或 "self_hosted"
process_config	object	托管必填	runtime / entry_point / port / ui
self_hosted_url	string	自托管必填	你的服务访问地址（HTTPS）
self_hosted_api_key	string	否	访问你服务需要的 API Key（加密存储）

审核流程

提交 (pending) → 审核中 (reviewing) → 发布 (published) / 驳回 (rejected)
                                         ↓
                                     可下架 (unpublished)

• 审核通过后：托管模式自动部署；自托管模式做一次连通性验证
• 驳回后可修改重新提交

---

自托管插件要求

必须实现的端点

GET /health
Response: 200 OK（任意 body）

平台每 5 分钟检查此端点，超时 3 秒视为 offline。

可用性状态

状态	含义
online	健康检查通过
offline	健康检查失败（超时或非 2xx）
degraded	返回 5xx 服务端错误
unknown	尚未检查

用户启动 offline 状态的插件时会收到 503 错误提示。

API Key 安全

• 提交时提供的 API Key 使用 AES-256-GCM 加密存储
• 运行时解密后仅用于服务端请求你的服务，不会暴露给前端
• 日志中仅记录前 4 位字符

---

用户侧 API

操作	API
浏览	GET /api/plugins/catalog
安装	POST /api/plugins/:id/install
启动	POST /api/plugin/launch/:id → 返回 iframe URL
卸载	DELETE /api/plugins/:id/uninstall

---

权限与数据

• Unity Lab 全部插件 permissions = []（零数据权限）
• 不要尝试直连 https://your-unityai-host/api/* — 无凭证且会被拒绝
• 本地子进程插件（官方托管）可使用 plugin_token 与本地后端通信；iframe 远程插件不适用

---

相关文档

• 安全规范
• Plugin Bridge SDK — 可复制到插件项目的 postMessage 封装
• Process 插件开发 — 本地进程插件详细开发指南
• plugin.json 规范 — 配置校验
• 托管与部署 — 部署模式详解