插件服务指南 - 基础使用

本篇将带您快速上手 OPENUGC 插件系统，学会创建和使用插件。

什么是插件服务？

插件系统允许您：

为任意网站开发自定义工具
注入 JavaScript 代码执行高级操作
实现网页 HOOK 和数据抓取
扩展 AI 助手的自动化能力
创建复杂的工作流程

插件由插件和工具两部分组成：

插件：定义注入脚本和基础配置
工具：定义具体的执行逻辑和参数

创建插件

步骤 1：进入插件管理页面

点击左侧【插件服务】菜单，进入插件管理页面。

插件服务界面

步骤 2：创建插件

点击【创建插件】，填写插件基本信息：

插件信息

插件名称：为您的插件起一个有意义的名称
插件备注：描述插件的功能和用途

高级配置

注入脚本：可选填写 JavaScript 代码
运行周期：选择脚本注入时机
- document-start：页面开始加载时
- document-end：页面加载完成后

说明：配置的注入脚本会在打开网页后自动注入执行，实现更高级的 HOOK 等操作。

步骤 3：保存插件

点击保存，进入插件详情页面。

添加工具

步骤 1：添加工具

在插件详情页面，点击工具列表旁边的 + 按钮，添加工具：

工具信息

工具名称：使用英文、大小写命名或下划线命名
- ✅ 推荐：getNews、search_web、getWeather
- ❌ 不推荐：获取新闻、搜索、天气查询
工具介绍：认真填写，让大模型理解工具功能

步骤 2：保存工具

保存后，进入工具编辑界面。

编辑工具 - 基础配置

基础配置选项

页面输入框

调用工具时打开的目标 URL 地址
不填写则在当前 AI 客户端执行（高级用法）

新窗打开【开关】

开启后，页面在新窗口打开
不影响 AI 助手继续执行

注入脚本【开关】

开启后，打开目标页面时注入脚本内容
执行助手设置的注入脚本

结束关闭【开关】

工具执行并返回内容后自动关闭页面窗口

显示日志【开关】

开启后，显示连接和任务执行日志
方便调试和排查问题

参数列表

支持以下类型的参数：

字符串 (String)

参数名称：search_keyword、noteId、url
参数介绍：请精准填写，让大模型理解参数作用

布尔值 (Boolean)

参数名称：is_filter、has_image、enable_cache
参数介绍：true/false，启用或禁用某项功能

整数 (Integer)

参数名称：count、max_results、timeout
参数介绍：数值参数，控制数量或限制

执行代码 - 快速入门

使用 JavaScript 编写，遵循以下规范：

核心要求

定义一个 Tool 类
实现异步的 run 函数
接收 args 参数（对象类型）
返回数据（JSON 或字符串）

模板代码 1：继承父类（推荐）

// 创建一个 Tool 类，可继承 OPENUGC_API_V2 父类
// 调用更多高级接口
class Tool extends OPENUGC_API_V2 {
  // 接收 args 参数
  constructor(args) {
    super(args);  // 必须调用 super(args) 才能使用 this.args
    this.COUNT = args.count || 10;
  }

  // 工具执行入口函数
  async run() {
    // 如果用户在工具配置中设置了"页面输入框"URL，
    // 系统会自动打开该页面，此处代码直接在目标页面执行
    // 无需手动调用 OpenUrl()

    // 从页面获取数据
    return JSON.parse(
      document.querySelector('#hotsearch_data').innerText
    ).hotsearch.slice(0, this.COUNT).map(h => ({
      title: h.card_title,
      score: h.heat_score
    }));
  }
}

📌 重要说明：页面执行机制

情况1：配置了页面URL（常用）

在工具配置的"页面输入框"中设置目标URL
系统自动打开页面并执行工具代码
无需在代码中调用 OpenUrl()
代码中的 document 对象就是目标页面

情况2：未配置页面URL

代码在当前AI助手页面执行
可以调用 this.OpenUrl() 动态打开其他页面（高级用法）

情况3：工具内部逻辑

某些工具可能需要打开其他页面完成操作
此时可以使用 this.OpenUrl() 打开新页面（高级用法）

模板代码 2：独立实现

class Tool {
  async run(args) {
    // 解析页面数据
    const data = JSON.parse(
      document.querySelector('pre').outerText
    );
    return data;
  }
}

关键要点

Tool 类名固定，不可更改
run 函数：异步函数，接受 args 参数
返回值：JSON 对象或字符串
可以继承 OPENUGC_API_V2 获得更多接口
也可不继承父类独立实现

测试执行

配置好工具和代码后，需要手动测试：

在【输入】表单中输入工具参数
点击【运行】按钮
查看下方的【输出】结果

确认工具能正确调用并获取结果，即可使用。

⚠️ 重要：记得在工具右上角启用该工具和插件！

使用插件

启用插件服务

在对话输入框中：

点击插件下拉选择框
选择已启用的插件服务
通过自然语言与大模型交流

调用示例

用户：请帮我抓取今天热搜榜前10条信息
AI：正在调用"热搜抓取"工具...

返回结果：
1. 某明星恋情曝光 - 热度：98.5
2. 新电影票房破纪录 - 热度：95.2
3. 科技公司发布新品 - 热度：89.7
...

常见问题

Q: 工具名称为什么必须用英文？ A: 工具名称会作为函数名在代码中使用，JavaScript 不支持中文函数名。

Q: 如何让大模型更好地理解我的工具？ A: 工具介绍非常重要！详细说明工具的功能、参数和使用场景。

Q: 注入脚本不执行怎么办？ A: 检查：

注入脚本开关是否开启
脚本语法是否正确
运行周期设置是否合理

Q: 工具执行失败如何调试？ A: 开启【显示日志】开关，查看执行日志定位问题。

Q: 可以抓取需要登录的页面吗？ A: 可以，通过注入脚本实现登录，再执行工具代码。

Q: 工具返回值有什么要求？ A: 可以返回 JSON 对象或字符串。JSON 对象便于大模型理解和处理。

Q: 如何处理跨域问题？ A: 工具在浏览器环境中运行，不存在跨域问题。

Q: 一个插件可以有多个工具吗？ A: 可以！一个插件可以包含多个工具，各自独立配置和使用。

下一步

深入开发：阅读 API 详解，了解 OPENUGC_API_V2 高级接口
实战案例：查看案例1：热搜数据抓取，学习最佳实践
助手配置：助手配置 - 了解如何配置 AI 助手
MCP配置：MCP配置 - 了解 MCP 服务配置

插件服务指南 - 基础使用 ​

什么是插件服务？ ​

创建插件 ​

步骤 1：进入插件管理页面 ​

步骤 2：创建插件 ​

步骤 3：保存插件 ​

添加工具 ​

步骤 1：添加工具 ​

步骤 2：保存工具 ​

编辑工具 - 基础配置 ​

基础配置选项 ​

参数列表 ​

执行代码 - 快速入门 ​

核心要求 ​

模板代码 1：继承父类（推荐） ​

📌 重要说明：页面执行机制 ​

模板代码 2：独立实现 ​

关键要点 ​

测试执行 ​

使用插件 ​

启用插件服务 ​

调用示例 ​

常见问题 ​

下一步 ​