在问 OneAPI 文档中心

Appearance

调试台插件系统 ​

实验性功能

插件系统当前处于快速迭代阶段，API 可能会在后续版本中调整。

调试台插件系统让你可以为 Agent 安装新的工具和能力。插件是 Agent 的"手脚"——提供新的动作和展示方式，思考和决策仍由 Agent 完成。

当前插件系统定位为内部受信扩展机制。插件代码直接在浏览器中运行，manifest.capabilities 用于声明插件会使用哪些宿主能力，便于界面展示、人工审查和统一治理，不构成浏览器级安全沙箱。

插件能做什么 ​

插件可以为 Agent 注册新的工具和Widget：

  • 工具：Agent 可以调用的能力，比如"查询天气"、"创建 GitHub Issue"、"生成 PDF"
  • Widget：自定义的结果展示方式，比如"Mermaid 流程图"、"数据图表"

此外，插件还可以在受控环境下使用以下能力：

能力说明
网络请求通过 api.fetch() 发起 HTTP 请求
文件操作通过 api.workspace.* 读写文件（用户工作区或插件沙箱）
Python 运行时通过 api.runPython() 在浏览器端执行 Python 代码
WASM 运行时通过 api.runWasm() 等方法加载和调用 WASM 模块
用户交互通过 api.askUser() 向用户提问并获取回答
Widget 展示通过 api.showWidget() 返回自定义展示内容
通知通过 api.showNotification() 显示通知
持久化存储通过 api.storage.* 进行插件作用域的 KV 存储
插件资源通过 api.readPluginAsset() 读取插件自身的静态文件

安装插件 ​

插件以 .zip 包的形式分发。你可以通过两种方式安装：

  1. 上传文件：从本地上传 .zip 包
  2. URL 下载：输入插件包的下载地址

安装后，插件代码存储在浏览器本地文件系统（OPFS）中，不依赖后端，页面刷新后自动恢复。

官方示例插件下载 ​

你可以直接下载下面这些示例插件进行安装测试：

插件说明下载
Weather查询实时天气与未来天气预报weather-plugin.zip
Three.js在消息流中展示可交互 3D 场景threejs-plugin.zip
FFmpeg在浏览器中处理音视频文件ffmpeg-plugin.zip

启用工具 ​

安装完成后，插件注册的工具默认不启用。你需要在插件管理面板中手动启用。

每个工具可以独立开关，而不是整个插件一刀切。启用时如果插件有必填配置项未完成（比如 API Key），会提示你先去配置。

能力声明 ​

插件需要在 manifest.json 中声明它会使用哪些宿主能力，运行时通过统一的 PluginRuntimeAPI 入口进行检查和治理：

能力说明典型用途
network.fetch发起网络请求调用外部 API
workspace.user读写用户工作区文件处理用户上传的文件
workspace.plugin读写插件沙箱目录插件内部文件管理
workspace.python使用 Python 运行时数据处理
workspace.wasm运行 WASM 模块高性能计算
user_interact向用户提问获取用户输入
ui.widget显示自定义组件可视化展示
ui.notification显示通知状态提醒
storage持久化存储数据保存插件配置

能力声明写在 manifest.json 的 capabilities 数组中。未声明的对应 API 调用会在运行时被拦截并报错。

插件不能做什么 ​

作为内部受信扩展，插件仍然受到调试台运行时边界约束，但这不是一个面向第三方不受信代码的安全沙箱。当前有以下限制：

  • 不能调用 LLM（不持有 API Key）
  • 不能访问对话历史和会话状态
  • 不能拦截或修改其他工具的调用
  • 不能通过 PluginRuntimeAPI 访问未声明的能力
  • 插件工具的执行结果会作为 tool_result 返回给 Agent，但插件无法控制 Agent 的后续决策

插件生命周期 ​

插件从安装到卸载经历以下阶段：

安装 ZIP → 解压到 OPFS → 校验 manifest → 探测工具名（probe）
                                        ↓
                                    写入注册表
                                        ↓
                                    加载插件（load）
                                        ↓
                          创建 PluginContext → 注册顶层 tools → 调用 install(ctx)
                                        ↓
                              注册工具到全局 registry
                                        ↓
                              会话切换时 restore（从 OPFS 重新加载）
                                        ↓
                              卸载：调用 destroy() → 注销工具 → 删除 OPFS 文件

安装阶段 ​

  1. ZIP 解压到 OPFS 临时目录
  2. 读取并校验 manifest.json（必须包含 name 和 version）
  3. 检查 SDK 版本兼容性（sdkVersion 字段）
  4. 移动到正式目录 {PLUGIN_ROOT}/{name}/src/
  5. 探测工具名：优先从 manifest.tools 静态元数据读取；通常这些元数据由插件顶层 tools 自动派生
  6. 写入注册表（包含探测到的工具名列表）
  7. 尝试加载插件（如果运行时上下文可用）

加载阶段 ​

  1. 从 OPFS 读取 JS 文件 → 创建 Blob URL → 重写相对 import 路径 → import(blobUrl) 动态加载
  2. 校验 SDK 版本兼容性
  3. 创建 PluginContextImpl，加载插件配置
  4. 如果插件定义了顶层 tools，先自动注册这些工具
  5. 调用 plugin.install(ctx) 处理额外初始化逻辑（如注册 Widget）
  6. 仅在兼容旧写法或纯 manifest 场景下，才使用 ctx.registerTool() / manifest.tools 补齐工具注册
  7. 同步已注册工具到全局状态

推荐模式是：工具定义只写在顶层 plugin.tools，manifest.tools 由 SDK 自动派生，避免静态声明与运行时实现双写漂移。

恢复阶段 ​

页面刷新或会话切换时，PluginManager 会从 OPFS 注册表中恢复所有已启用的插件，重新执行加载流程。

卸载阶段 ​

  1. 调用 plugin.destroy()（如果定义了）
  2. 注销所有已注册的工具和 Widget
  3. 撤销 Blob URL
  4. 删除 OPFS 中的插件目录
  5. 从注册表中移除条目

插件配置 ​

插件可以通过 configSchema 在 manifest.json 中声明配置界面。声明后，用户可以在插件管理面板中填写配置项（如 API Key、默认参数等）。

配置项支持以下类型：string、number、boolean、select、password，并支持验证规则（正则、范围等）。

插件代码中可以通过 ctx.getConfig() 获取当前配置，也可以通过 ctx.onConfigChange(handler) 监听配置变化。

多文件插件 ​

插件支持多文件结构。安装时，系统会：

  1. 递归读取 src/ 目录下所有 .js / .mjs 文件
  2. 重写文件之间的相对 import/export 路径为 Blob URL
  3. 为每个文件创建 Blob URL
  4. 返回 index.js 的 Blob URL 作为入口点

这意味着你可以将插件拆分为多个模块文件，构建时无需内联到一个文件中。

管理插件 ​

点击侧边栏底部的插件管理按钮，打开管理面板。在这里你可以：

  • 查看已安装的插件列表
  • 按工具粒度启用/禁用
  • 配置插件参数（如 API Key、默认设置）
  • 卸载插件
  • 安装新插件

开发插件 ​

如果你想开发自己的插件，请参考 插件开发指南。