插件开发概述
插件（Plugin）是 AweeClaw 的能力扩展单元。与场景不同，插件不定义 AI 的身份与人设，而是为客户端和场景提供可复用的能力：一个工具、一个消息渠道、一个模型服务商、一段生命周期钩子，或者一块注入客户端的 UI。
如果你要做的是一套完整的 AI 应用（角色设定 + 对话流 + 界面），请看场景开发指南；如果你要做的是"给平台加一个能力，让所有场景都能用"，那就是插件。
开发插件需要 Node.js ≥ 18 与基本 JavaScript / TypeScript 能力。
插件与场景的区别
| 维度 | 插件（Plugin） | 场景（Scenario） |
|---|---|---|
| 本质 | 能力供给单元 | 完整的 AI 应用 |
| 清单文件 | manifest.json | scenario.json |
| 定义内容 | 能力声明、配置表单、UI 扩展点 | 身份、提示词、工具、UI 布局 |
| 运行位置 | 客户端主进程 / 子进程 / 远程服务 | 客户端渲染进程 + 沙箱 |
| 复用方式 | 被多个场景、智能体共享调用 | 被用户直接使用 |
| UI 能力 | 侧边栏面板、顶部按钮、设置页 Tab、工作台卡片 | 完整自定义面板 |
| 发布接口 | /api/v1/developer/plugins | /api/v1/marketplace/developer |
| 分发渠道 | 插件市场 | 场景市场 |
一个插件由什么组成
最小可用的插件只有一个 manifest.json + 一个入口文件：
my-plugin/
├── manifest.json # 必需：插件元数据与能力声明
├── index.js # 必需：入口（除了 ConfigOnly 插件）
├── package.json # 可选：声明 ESM 与依赖
├── ui-src/ # 可选：UI 扩展源码（React + TS）
│ └── index.tsx
├── ui.js # 可选：ui-src 构建产物
└── icon/
└── icon.png # 可选：本地图标（≤ 256KB，建议 128×128）| 文件 | 作用 |
|---|---|
manifest.json | 插件唯一标识、名称描述、类型、版本、能力声明、配置表单、UI 扩展点 |
index.js | 插件逻辑入口：导出 MCP 工厂函数（in-process）或作为 stdio 服务启动 |
package.json | 声明 "type": "module"（ESM）；stdio 插件声明 SDK 依赖 |
ui.js | 由 scripts/build-ui.mjs 打包出的 ESM bundle，向客户端注入 UI 组件 |
插件类型
后端 PluginType 枚举定义了市场可发布的插件类型：
| 类型 | 说明 |
|---|---|
mcp | MCP 协议插件，通过 capabilities.mcp 声明传输方式，是最常见的一类 |
tool | 工具型插件，通常以 in-process 方式运行，可附带 UI 扩展 |
channel | 消息渠道插件（飞书、微信、钉钉等） |
provider | 模型服务商插件 |
hook | 生命周期钩子插件（拦截/改写智能体与工具调用流程） |
composite | 组合插件，聚合多个子插件 |
scenario | 以插件形式分发的场景包 |
skill | 技能包插件 |
本仓库（
aweeclaw-plugins）当前的主力形态是mcp与tool，二者都通过 MCP 协议被智能体调用。channel/provider类插件由客户端内置适配器打包生成，走平台侧构建流程。
三种分发模式
插件如何分发由 manifest.json 的 main 字段自动决定，开发者无需手动指定：
| 模式 | 触发条件 | 存储位置 | 适用场景 |
|---|---|---|---|
| Tarball 模式 | main 非空（有本地入口代码） | 对象存储（MinIO/S3）存 .tar.gz | 自研代码插件（in-process / 本地 stdio） |
| ConfigOnly 模式 | main 为空 + 有 MCP 能力 | 数据库直接存 manifest | 通过 npx/uvx 调用外部包的 MCP 插件 |
| 内联代码模式 | Tarball 上传失败时自动降级 | 数据库存 manifest（含 inlineCode） | 对象存储不可达时的降级；也用于 in-process 插件 |
客户端 PluginInstaller 三种模式全部兼容：Tarball 解压安装，ConfigOnly 仅写 manifest，内联模式把 inlineCode / inlineUiCode 还原成本地文件。
端到端流程
mermaid
graph TD
A[本地开发<br/>manifest.json + index.js + 可选 ui-src] --> B[本地测试<br/>node --check / MCP Inspector]
B --> C[构建 UI<br/>node scripts/build-ui.mjs]
C --> D[打包 tar.gz<br/>脚本自动完成]
D --> E[发布<br/>脚本 / 开发者中心]
E --> F[审核<br/>pending → approved]
F --> G[用户安装<br/>下载 → 校验 → 解压 → 注入配置]
G --> H[运行<br/>注册 MCP 服务 → 自动连接]仓库结构
插件源码统一放在 aweeclaw-plugins/ 仓库：
aweeclaw-plugins/
├── plugins/ # 所有插件源码（每个插件一个子目录）
│ ├── mcp-brave-search/ # ConfigOnly MCP 插件（npx 调用外部包）
│ ├── util-uuid-gen/ # in-process 工具插件
│ ├── ai-macro-recorder/ # in-process 工具插件 + UI 扩展
│ └── ...
├── templates/
│ └── mcp-plugin/ # 插件开发模板（含 icon/ 目录）
├── scripts/
│ ├── build-ui.mjs # 构建 UI bundle（ui-src/index.tsx → ui.js）
│ ├── publish-plugin.mjs # 发布单个插件（推荐入口）
│ ├── publish-all-plugins.mjs # 批量发布
│ └── generate-plugins.mjs # 从清单批量生成插件目录
├── package.json # 仓库依赖（esbuild / typescript）
└── tsconfig.json # UI 源码类型检查配置新插件一律放在 plugins/ 目录下，目录名与 manifest.id 保持一致。