第28期 自定义插件开发：从需求到上线全流程

IMA实操系列 · 第28期 / 共30期 · 第六篇章：系统与软件开发

🎯 本期你将学到

插件vs Skill vs SDK的区别 · 插件清单文件(manifest) · 接口设计与参数规范 · 代码实现与测试 · 上架发布全流程

一、插件是什么？Skill/SDK/插件三者关系

第三篇章做了Skill（平台内原子能力），上期做了SDK（把IMA嵌入你的产品），本期做插件——它是为IMA平台开发扩展功能，让IMA能调用你的外部服务。

举个例子：你公司有内部ERP系统，你开发一个"查询库存"插件，IMA用户在对话中就能直接查你们ERP的库存数据——IMA调用你的插件API。

二、插件清单文件：manifest.json

每个插件需要一个清单文件，告诉IMA这个插件叫什么、能做什么、接受什么参数、调哪个URL。类似Chrome扩展的manifest：

{   "name": "库存查询",   "version": "1.0.0",   "description": "查询公司ERP系统库存数据",   "functions": [     {       "name": "query_stock",       "description": "根据商品名查询库存数量",       "parameters": {         "type": "object",         "properties": {           "product_name": {"type": "string", "description": "商品名称"},           "warehouse": {"type": "string", "description": "仓库ID，可选"}         },         "required": ["product_name"]       },       "endpoint": "https://your-server.com/api/stock"     }   ] }

核心字段：name（插件名）、functions（功能列表）、parameters（参数schema，JSON Schema格式）、endpoint（你的服务URL）。IMA会把这个schema注册成可调用的工具。

三、接口设计：参数与返回规范

插件接口要遵循IMA的调用规范——入参标准化、返回标准化、错误标准化：

入参：IMA POST请求，body为JSON，含function参数

返回：JSON格式，必须有 success 字段 + data 字段

错误：HTTP 200 + body里 success:false + error_msg，而非HTTP 4xx

# 成功返回 {   "success": true,   "data": {"product": "iPhone 16", "stock": 128, "warehouse": "SH-01"} }  # 失败返回（HTTP仍为200） {   "success": false,   "error_msg": "商品不存在",   "error_code": "PRODUCT_NOT_FOUND" }

四、代码实现：库存查询插件

用FastAPI实现这个插件，30行代码搞定：

from fastapi import FastAPI, Request from pydantic import BaseModel  app = FastAPI()  class StockQuery(BaseModel):     function: str     parameters: dict  @app.post("/api/stock") async def query_stock(req: StockQuery):     if req.function != "query_stock":         return {"success": False, "error_msg": "未知函数"}     product = req.parameters.get("product_name")     # 查ERP数据库（简化示例）     result = db.query("SELECT stock FROM inventory WHERE name=?", product)     if not result:         return {"success": False, "error_msg": "商品不存在",                 "error_code": "PRODUCT_NOT_FOUND"}     return {"success": True, "data": {         "product": product,         "stock": result[0]["stock"],         "warehouse": "SH-01"     }}

部署到服务器，确保公网可访问。IMA注册时会验证endpoint连通性。

五、上架发布：六步流程

Step 1：在开发者后台 → 插件管理 → 创建插件

Step 2：上传 manifest.json + 填写插件描述+图标

Step 3：配置鉴权方式（API Key / OAuth）

Step 4：提交审核（IMA团队验证安全+合规）

Step 5：审核通过 → 灰度发布 → 全量上线

Step 6：在插件市场可被搜索和安装

审核要点：安全性（不能有SQL注入等漏洞）、合规性（不涉及敏感数据泄露）、稳定性（endpoint 99.5%可用率）。审核通常3-5个工作日。

📌 本期核心要点

1. 插件 = 让IMA调用你的外部服务（Skill是平台内，SDK是你调IMA，插件是IMA调你）2. manifest.json定义插件名/功能/参数schema/endpoint URL3. 接口规范：入参JSON、返回 success+data、错误返回 success:false4. FastAPI 30行代码实现一个库存查询插件5. 上架六步：创建→上传manifest→配置鉴权→审核→灰度→全量上线

📖 下期预告

第29期：系统部署与运维：上线后的保障体系

插件上线只是开始。下期聚焦运维——灰度发布、监控告警、日志收集、故障排查、版本迭代，确保系统稳定运行。

📋 IMA实操系列 · 目录

第一~五篇章 ✅ 已完结

第六篇章：系统与软件开发 🔄 进行中 ✅ 第26期 IMA API入门 ✅ 第27期 SDK集成与开发 ✅ 第28期 自定义插件开发（本期） ⬜ 第29期 系统部署与运维 ⬜ 第30期 终极架构与未来展望