manifest 清单配置

manifest.json 是插件的唯一身份与能力声明文件。客户端在不加载插件代码的前提下读取它，用于展示插件信息、渲染配置表单、决定如何启动服务、注入 UI 组件。

PluginManifest（TypeScript 类型定义见 @aweeclaw 客户端 shared/plugin-sdk/types.ts）

顶层字段

字段	类型	必需	说明
`id`	string	✅	插件唯一标识，小写字母/数字/连字符，字母开头，3–64 字符。发布后不可修改（即后端 `pluginKey`）
`name`	string	✅	英文显示名（≤ 64 字符）
`nameZh`	string	✅	中文显示名（≤ 64 字符）
`description`	string	✅	英文描述（≤ 2000 字符）
`descriptionZh`	string	✅	中文描述（≤ 2000 字符）
`type`	string	✅	插件类型，见插件类型；创建后不可改
`version`	string	✅	semver，如 `1.0.0`；发布新版本必须递增
`main`	string	⚠️	入口文件相对路径。MCP 型且为空 → ConfigOnly 插件；非 MCP 型必填
`icon`	string	❌	Lucide 图标名（如 `Package`）/ 远程 URL / 本地相对路径（`icon/icon.png`），默认 `Package`
`category`	string	❌	分类，见分类，默认 `productivity`
`tags`	string[]	❌	标签数组，用于市场搜索
`lifecycle`	string	❌	`singleton` / `per-account` / `per-session`，默认 `singleton`
`capabilities`	object	✅	能力声明，见 capabilities
`configSchema`	object	❌	用户配置表单，见配置表单
`permissions`	string[]	❌	权限声明，见权限
`contributes`	object	❌	UI 扩展点声明，见 UI 扩展
`platforms`	string[]	❌	`darwin` / `win32` / `linux`，默认三者全支持
`isFree`	boolean	❌	是否免费，默认 `true`
`price`	number	❌	价格（元），`isFree: false` 时须大于 0
`validityDays`	number	❌	有效期（天）：`0` / 不传 = 永久买断；`> 0` = 按天计费
`minAppVersion`	string	❌	要求的最低客户端版本
`author` / `homepage` / `repository` / `license`	string	❌	作者、主页、仓库、许可证（默认 `MIT`）
`builtin`	boolean	❌	标记为内置插件（平台自用，市场不展示）
`inlineCode` / `inlineUiCode`	string	⛔	发布脚本自动写入，禁止手填

插件类型

类型	典型形态	说明
`mcp`	stdio 子进程 / in-process / 远程 SSE	通过 MCP 协议向智能体暴露工具，最主流
`tool`	in-process	工具型插件，可附 UI 扩展
`channel`	内置适配器打包	消息渠道（飞书、微信、钉钉…）
`provider`	内置适配器打包	模型服务商接入
`hook`	in-process	生命周期钩子，可拦截/改写调用流程
`composite`	组合	聚合多个子插件
`scenario`	场景包	以插件形式分发的场景
`skill`	技能包	提示词/流程类技能

分类

category 必须取自后端维护的分类表（发布脚本会自动拉取校验）：

值	名称
`productivity`	效率
`development`	开发
`automation`	自动化与集成
`database`	数据库
`design`	设计
`frontend`	前端设计
`office`	办公
`ai`	AI 与搜索
`utility`	实用工具
`channel`	消息渠道

该表是全系统唯一数据源（后端 PLUGIN_CATEGORIES）。新增分类需后端先维护，否则 publish 接口会报 Invalid category。

capabilities

capabilities 按插件类型声明对应能力块，只需声明自己用到的那些。

mcp

json

{
  "capabilities": {
    "mcp": {
      "transport": "stdio",
      "command": "node",
      "args": ["{{pluginDir}}/index.js"],
      "env": { "DEBUG": "{{config.DEBUG}}" },
      "autoConnect": true,
      "timeout": 30000
    }
  }
}

字段	适用 transport	说明
`transport`	全部	`in-process` / `stdio` / `sse`
`inProcessExport`	in-process	出口工厂函数名，缺省按 `default` → `createMcpServer` → `create` 顺序识别
`command`	stdio	启动命令：`node` / `npx` / `uvx` / `python3` 等
`args`	stdio	参数数组，支持 `{{pluginDir}}`、`{{dataDir}}`、`{{config.KEY}}`
`env`	stdio	环境变量，支持 `{{config.KEY}}`
`url`	sse	远程服务 URL
`autoConnect`	全部	是否在应用启动时自动连接
`timeout`	全部	单次工具调用超时（毫秒），默认 30000；视频生成等长任务需显式放大（如 `660000`）

详见传输模式。

channel

json

{
  "capabilities": {
    "channel": {
      "connectionModes": ["websocket", "webhook"],
      "defaultConnectionMode": "websocket",
      "chatTypes": ["direct", "group"],
      "media": true,
      "reactions": true,
      "threads": true,
      "edit": true,
      "streaming": true,
      "voice": false,
      "files": true
    }
  }
}

tool

json

{
  "capabilities": {
    "tool": {
      "concurrency": "parallel-safe",
      "sandboxed": false,
      "requiresApproval": false
    }
  }
}

concurrency 取值：parallel-safe（可并发）/ serialized（串行）/ approval-gated（需用户审批）。

hook

json

{
  "capabilities": {
    "hook": {
      "events": ["before-tool-call", "after-tool-call", "after-agent-reply"]
    }
  }
}

可用事件：Hook 事件一节列出全部取值。

provider

json

{
  "capabilities": {
    "provider": {
      "protocols": ["openai-compatible"],
      "streaming": true,
      "toolCalling": true,
      "embedding": false,
      "multimodal": true
    }
  }
}

desktop

json

{
  "capabilities": {
    "desktop": {
      "operations": ["screen_capture", "mouse_click", "keyboard_type"],
      "requiresAccessibility": true,
      "requiresScreenCapture": true,
      "workflowSteps": false,
      "recordingEvents": false
    }
  }
}

权限

permissions 声明插件需要访问的宿主能力。in-process 插件通过 ctx.host 访问时受此清单校验，未声明的能力会抛 PermissionDeniedError。

权限	说明
`network`	发起网络请求
`filesystem.read`	读取文件
`filesystem.write`	写入文件
`shell.execute`	执行 Shell 命令
`clipboard.read` / `clipboard.write`	读写剪贴板
`notification`	发送系统通知
`system.info`	读取系统信息
`desktop.input`	模拟鼠标/键盘输入
`desktop.screen`	屏幕截图
`desktop.windows`	窗口管理
`desktop.apps`	应用启动/退出
`desktop.recording`	操作录制
`desktop.workflow`	工作流执行
`desktop.visual-agent`	视觉智能体
`ui.render`	在客户端渲染 UI 组件（使用 `contributes` 时必须声明）

Hook 事件

hook 能力与 ctx.registerHook 支持的事件：

before-agent-start      after-agent-reply
before-tool-call        after-tool-call
before-message-send     after-message-receive
on-session-create       on-session-reset
on-channel-connect      on-channel-disconnect     on-channel-error
on-config-change        on-cron-trigger
before-desktop-action   after-desktop-action
before-recording-start  after-recording-stop
before-workflow-run     after-workflow-complete
before-replay           after-replay
on-visual-agent-step

钩子处理函数返回 { proceed: boolean, modified?: unknown, reason?: string }：proceed: false 可中断后续流程，modified 可改写即将执行的输入。

完整示例

一个带配置表单与 UI 扩展的 in-process 工具插件：

json

{
  "id": "ai-macro-recorder",
  "name": "AI Macro Recorder",
  "nameZh": "AI 宏录制器",
  "description": "Record user input via native system hooks, auto-generate action steps.",
  "descriptionZh": "基于原生输入钩子录制用户操作，自动生成操作步骤。",
  "type": "tool",
  "version": "4.0.3",
  "main": "index.js",
  "icon": "Video",
  "category": "automation",
  "tags": ["automation", "macro", "recorder"],
  "capabilities": {
    "mcp": {
      "transport": "in-process",
      "autoConnect": true
    }
  },
  "configSchema": {
    "fields": [
      {
        "key": "default_interval_ms",
        "label": "Default Sampling Interval (ms)",
        "labelZh": "默认采样间隔（毫秒）",
        "type": "number",
        "required": false,
        "default": "1000"
      }
    ]
  },
  "permissions": [
    "desktop.screen",
    "desktop.input",
    "desktop.windows",
    "filesystem.read",
    "filesystem.write",
    "ui.render"
  ],
  "contributes": {
    "ui": { "entry": "ui.js" },
    "sidebarPanels": [
      {
        "id": "ai-macro-recorder:panel",
        "icon": "Video",
        "label": "Macros",
        "labelZh": "宏管理",
        "component": "macro-panel",
        "position": 50
      }
    ]
  },
  "platforms": ["darwin", "win32", "linux"],
  "license": "MIT"
}

校验规则

发布脚本与后端会依次校验：

必需字段齐全（id / name / nameZh / description / descriptionZh / type / version / capabilities）
id 匹配 ^[a-z][a-z0-9-]*$，且与后端 pluginKey 一致
version 匹配 semver，且与上传参数一致
category 在后端分类表内
MCP 型插件声明了 capabilities.mcp
type 与后端已有记录一致（不一致需删除重建）

下一步

传输模式 — 三种运行方式怎么选
配置表单 — configSchema 完整字段
UI 扩展 — contributes 完整说明

manifest 清单配置 ​

顶层字段 ​

插件类型 ​

分类 ​

capabilities ​

mcp ​

channel ​

tool ​

hook ​

provider ​

desktop ​

权限 ​

Hook 事件 ​

完整示例 ​

校验规则 ​

下一步 ​

manifest 清单配置

顶层字段

插件类型

分类

capabilities

mcp

channel

tool

hook

provider

desktop

权限

Hook 事件

完整示例

校验规则

下一步