插件开发指南

AiVerse 提供 脚本插件 系统：用 JavaScript 编写插件，向 AI Agent 注册自定义工具，并借助 ctx API 访问宿主能力（网络、文件、剪贴板、状态存储等）。本文先介绍插件能干什么与最小插件写法，帮助快速上手。

提示

本文是简明入门。插件清单字段与 ctx API 与 OpenX 插件规范对齐，但以 AiVerse 实际实现为准；App 内「插件管理」与插件详情可查看已安装插件。

插件能干什么

• 注册自定义工具：向 AI Agent 增加可调用工具，AI 依据 description 与 parameters 决定是否调用。

• 网络请求：ctx.httpFetch 支持自定义请求头/请求体——这是 TTS 接口插件化的基础。

• 文件读写：在插件目录沙箱内读写、删除、列出文件，防目录穿越。

• 状态与存储：state（会话级内存）、store（持久化到 store.properties）。

• 剪贴板与通知：读写剪贴板、发 Toast 与系统通知。

• 调用已有工具：ctx.callTool 调用 AiVerse 自动授权工具。

• 多插件隔离：每个插件独立 QuickJS 运行时，互不干扰。

一个最小插件

插件是一个目录：

hello/├── plugin.json   # 清单（必需）└── main.js       # 工具入口（必需）

plugin.json：

{"package": "my.hello","name": "Hello 插件","version": "1.0.0","description": "我的第一个插件","main": "main.js","permissions": ["network"]}

main.js 注册工具：

var $ptools = $ptools || [];$ptools.push({  name: 'greet',  description: '向某人问好。',  parameters: {    type: 'object',    properties: { who: { type: 'string', description: '打招呼的对象' } },    required: ['who']  },  handler: function (args) {    return JSON.stringify({ ok: true, message: '你好，' + args.who });  }});

打包成 zip，在 插件管理 → 右上角「+」→ 添加压缩包插件 导入。工具名规则：{包名}_{工具名}（如 my_hello_greet），包名前缀用于整体卸载。

TTS 接口插件化

用 ctx.httpFetch 可适配任意 TTS 接口：自定义请求头（鉴权 Key 等）与请求体（模型、音色、文本），把任意 /v1/tts 类接口接入朗读。App 内置在线 TTS 已支持 OpenAI 兼容与 Fish Audio 协议；更多接口可在「设置 → 朗读 → 在线 TTS 接口」通过自定义请求头/请求体覆盖。

ctx API 一览

方法	说明	权限
showToast(msg)	弹短提示	—
notify(title, body)	发通知	notify
httpFetch(url, options)	HTTP 请求（method/headers/body）	network
fileRead / fileWrite / fileDelete / fileList	插件沙箱内文件操作	file / file:write
stateGet / stateSet	会话级状态	—
storeGet / storeSet / storeRemove	持久化存储	—
clipboardGet / clipboardSet	剪贴板	clipboard
callTool(name, args)	调已有自动授权工具	—

权限

在 plugin.json 的 permissions 声明，不声明则不可用：network、file、file:write、clipboard、notify（server 预留）。危险权限（network / file:write / clipboard）安装时橙色提示需用户确认。