OpenTiny NEXT

Appearance

AI Extension

AI Extension 扩展插件安装指南 ​

本文档将详细介绍如何在 Chrome/Edge 浏览器中通过本地安装模式安装和使用 AI Extension 浏览器扩展插件。

概述 ​

AI Extension 是一个基于 WXT 框架开发的浏览器扩展插件，它提供了 MCP（Model Context Protocol）工具调用功能，允许 AI 助手通过浏览器扩展与网页进行交互。本文档介绍的是本地安装模式，即不通过浏览器插件市场安装，而是直接下载并安装扩展文件。

前置要求 ​

在开始安装之前，请确保你的浏览器满足以下要求：

浏览器要求 ​

由于扩展使用了 userScripts API，需要以下最低浏览器版本：

  • Chrome：>= 120.0.0
  • Microsoft Edge：>= 120.0.0
  • 其他基于 Chromium 的浏览器：版本 >= 120.0.0（基于 Chromium 120+）

重要提示：userScripts API 是 Chrome 120 中引入的新特性，用于在页面的主世界（Main World）中执行脚本。如果你的浏览器版本低于 120，请先更新浏览器。

下载扩展 ​

获取扩展文件 ​

访问扩展下载地址，下载扩展 ZIP 文件：

下载地址：https://docs.opentiny.design/download/extension.zip

下载完成后，你会得到一个 ZIP 压缩文件，例如 extension.zip。

解压扩展文件 ​

  1. 找到下载的 ZIP 文件
  2. 右键点击 ZIP 文件，选择"解压到当前文件夹"或"解压到..."
  3. 解压后会得到一个文件夹，例如 extension 或 chrome-mv3

注意：请记住解压后的文件夹位置，后续安装时需要选择这个文件夹。

安装扩展 ​

Chrome 浏览器安装步骤 ​

步骤一：打开扩展管理页面 ​

  1. 打开 Chrome 浏览器
  2. 在地址栏输入 chrome://extensions/ 并回车
  3. 或者点击浏览器右上角的三点菜单 → 更多工具 → 扩展程序

步骤二：启用开发者模式 ​

  1. 在扩展管理页面的右上角，找到"开发者模式"开关
  2. 将开关切换到"开启"状态

步骤三：加载扩展 ​

  1. 点击"加载已解压的扩展程序"按钮
  2. 在文件选择对话框中，导航到解压后的扩展文件夹
  3. 选择扩展文件夹（包含 manifest.json 文件的文件夹）并点击"选择文件夹"

步骤四：开启 User Scripts 权限（重要） ​

如果扩展中使用了 pageMcpServer 类型的 MCP 工具，必须开启 User Scripts 权限：

  1. 在扩展管理页面，找到已安装的扩展卡片
  2. 点击扩展卡片上的"详细信息"或展开按钮
  3. 找到"User Scripts"或"用户脚本"选项
  4. 将开关切换到"开启"状态

注意：如果未开启 User Scripts 权限，pageMcpServer 类型的工具将无法正常工作，扩展会显示通知提示你开启此权限。

步骤五：确认安装 ​

  1. 扩展加载成功后，会在扩展管理页面显示
  2. 检查扩展是否已启用（开关处于开启状态）
  3. 检查 User Scripts 权限是否已开启（如果使用了 pageMcpServer 类型的工具）
  4. 如果扩展图标显示在浏览器工具栏，说明安装成功

Microsoft Edge 浏览器安装步骤 ​

步骤一：打开扩展管理页面 ​

  1. 打开 Microsoft Edge 浏览器
  2. 在地址栏输入 edge://extensions/ 并回车
  3. 或者点击浏览器右上角的三点菜单 → 扩展

步骤二：启用开发人员模式 ​

  1. 在扩展管理页面的左侧边栏，找到"开发人员模式"开关
  2. 将开关切换到"开启"状态

步骤三：加载扩展 ​

  1. 点击"加载解压缩的扩展"按钮
  2. 在文件选择对话框中，导航到解压后的扩展文件夹
  3. 选择扩展文件夹（包含 manifest.json 文件的文件夹）并点击"选择文件夹"

步骤四：开启 User Scripts 权限（重要） ​

如果扩展中使用了 pageMcpServer 类型的 MCP 工具，必须开启 User Scripts 权限：

  1. 在扩展管理页面，找到已安装的扩展卡片
  2. 点击扩展卡片上的"详细信息"或展开按钮
  3. 找到"User Scripts"或"用户脚本"选项
  4. 将开关切换到"开启"状态

注意：如果未开启 User Scripts 权限，pageMcpServer 类型的工具将无法正常工作，扩展会显示通知提示你开启此权限。

步骤五：确认安装 ​

  1. 扩展加载成功后，会在扩展管理页面显示
  2. 检查扩展是否已启用（开关处于开启状态）
  3. 检查 User Scripts 权限是否已开启（如果使用了 pageMcpServer 类型的工具）
  4. 如果扩展图标显示在浏览器工具栏，说明安装成功

其他 Chromium 浏览器 ​

其他基于 Chromium 的浏览器（如 Brave、Opera 等）的安装步骤与 Chrome 类似：

  1. 打开浏览器的扩展管理页面（通常在设置或菜单中）
  2. 启用开发者模式
  3. 加载已解压的扩展程序
  4. 选择解压后的扩展文件夹

扩展权限说明 ​

扩展需要以下权限才能正常工作，安装扩展时会自动请求这些权限：

  • storage：用于存储扩展数据
  • tabs：用于管理浏览器标签页
  • activeTab：用于访问当前活动标签页
  • scripting：用于注入脚本
  • contextMenus：用于添加上下文菜单
  • userScripts：用于执行用户脚本（重要：如果使用了 pageMcpServer 类型的工具，必须手动开启此权限）
  • notifications：用于显示通知
  • host_permissions：*://*/*（访问所有网站，用于支持在不同网站上使用 MCP 工具）

安装扩展时，浏览器会提示你授予这些权限，请点击"允许"以完成安装。

User Scripts 权限说明 ​

重要：如果扩展中使用了 pageMcpServer 类型的 MCP 工具，必须在扩展管理页面手动开启 User Scripts 权限。

为什么需要开启 User Scripts 权限？

  • pageMcpServer 类型的工具需要在页面的主世界（Main World）中执行脚本
  • 传统的 Content Script 运行在隔离环境中，无法访问页面的全局变量和 JavaScript 上下文
  • User Scripts API 允许扩展在页面的主世界中执行脚本，从而可以访问页面的完整 JavaScript 环境

如何开启 User Scripts 权限？

  1. 打开扩展管理页面（chrome://extensions/ 或 edge://extensions/）
  2. 找到已安装的扩展卡片
  3. 点击扩展卡片上的"详细信息"或展开按钮
  4. 找到"User Scripts"或"用户脚本"选项
  5. 将开关切换到"开启"状态

如何判断是否需要开启 User Scripts 权限？

  • 如果扩展中使用了 pageMcpServer 类型的工具，需要开启此权限
  • 如果扩展中只使用了 contentScriptMcpServer 类型的工具，不需要开启此权限

未开启 User Scripts 权限会怎样？

  • 扩展会显示通知提示你开启 User Scripts 权限
  • pageMcpServer 类型的工具将无法正常工作
  • 工具调用会失败，并显示错误信息

使用扩展 ​

打开侧边栏 ​

  1. 在任意网页上，点击浏览器工具栏中的扩展图标
  2. 或者右键点击扩展图标，选择"打开侧边栏"
  3. 侧边栏会在浏览器右侧打开，显示 AI 对话框

使用 AI 助手 ​

  1. 在侧边栏的 AI 对话框中输入你的问题或指令
  2. AI 助手会根据当前网页的上下文，调用相应的 MCP 工具
  3. 工具执行完成后，AI 助手会返回执行结果

工具调用示例 ​

以下是一些工具调用的示例：

示例一：获取页面标题 ​

用户：获取当前页面的标题
AI：调用 get-page-title 工具，返回页面标题

示例二：填充搜索框 ​

用户：在搜索框中输入"OpenTiny"
AI：调用 fill-search-box 工具，填充搜索框

示例三：操作画布（Excalidraw） ​

用户：在画布上添加一个矩形
AI：调用 chrome_send_command_to_inject_script 工具，添加矩形元素

更新扩展 ​

更新步骤 ​

  1. 访问扩展下载地址，下载最新版本的扩展 ZIP 文件
  2. 在扩展管理页面，找到已安装的扩展
  3. 点击扩展卡片上的"移除"按钮，卸载旧版本的扩展
  4. 解压新下载的 ZIP 文件
  5. 按照"安装扩展"步骤重新加载新版本的扩展

注意：更新扩展会清除扩展的存储数据，如果扩展使用了 localStorage 或 chrome.storage，数据会被清除。

调试扩展 ​

查看扩展日志 ​

后台脚本日志 ​

  1. 在扩展管理页面，找到扩展卡片
  2. 点击"背景页"或"Service Worker"链接
  3. 在打开的开发者工具中查看控制台日志

内容脚本日志 ​

  1. 在任意网页上，按 F12 打开开发者工具
  2. 在控制台中查看内容脚本的日志
  3. 日志前缀通常包含扩展名称

侧边栏日志 ​

  1. 打开扩展侧边栏
  2. 在侧边栏中右键点击，选择"检查"
  3. 在打开的开发者工具中查看控制台日志

使用 Chrome DevTools ​

  1. 在扩展管理页面，找到扩展卡片
  2. 点击"检查视图"链接
  3. 在打开的开发者工具中调试扩展

常见问题排查 ​

问题一：扩展无法加载 ​

可能原因：

  1. 扩展文件夹路径错误或文件夹不存在
  2. manifest.json 文件格式错误
  3. 扩展文件损坏或不完整

解决方法：

  1. 检查扩展文件夹是否存在且路径正确
  2. 检查 manifest.json 文件是否存在且格式正确
  3. 重新下载扩展 ZIP 文件并解压

问题二：扩展无法正常工作 ​

可能原因：

  1. 扩展权限未授予
  2. 网页不支持扩展功能
  3. 浏览器版本过低

解决方法：

  1. 检查扩展权限是否已授予
  2. 检查当前网页是否支持扩展功能
  3. 检查浏览器版本是否满足要求（>= 88.0.0）

问题三：工具调用失败 ​

可能原因：

  1. MCP 服务器工具未正确注册
  2. 工具参数不正确
  3. 网页 DOM 结构发生变化

解决方法：

  1. 查看扩展日志，检查 MCP 服务器工具是否正确注册
  2. 检查工具参数是否正确
  3. 检查网页 DOM 结构是否匹配

卸载扩展 ​

临时卸载 ​

  1. 在扩展管理页面，找到扩展卡片
  2. 点击扩展卡片上的开关，将扩展切换到"关闭"状态
  3. 扩展会被禁用，但不会删除

永久卸载 ​

  1. 在扩展管理页面，找到扩展卡片
  2. 点击"移除"按钮
  3. 在确认对话框中点击"移除"
  4. 扩展会被完全移除

安全注意事项 ​

1. 权限请求 ​

扩展会请求访问所有网站的权限（*://*/*），这是为了支持在不同网站上使用 MCP 工具。如果你对扩展的权限有疑问，可以在安装前查看扩展的权限说明。

2. 来源可信 ​

请从官方提供的下载地址下载扩展，确保扩展文件来源可信，避免安装恶意扩展。

3. 定期更新 ​

定期检查扩展更新，下载最新版本的扩展，以确保使用最新功能和安全补丁。

常见问题 FAQ ​

Q1: 扩展安装后无法使用怎么办？ ​

A: 检查以下几点：

  1. 扩展是否已启用
  2. 扩展权限是否已授予
  3. 浏览器版本是否满足要求（>= 120.0.0）
  4. 如果使用了 pageMcpServer 类型的工具，是否已开启 User Scripts 权限
  5. 查看扩展日志是否有错误信息

Q2: 如何更新扩展？ ​

A: 更新扩展的步骤如下：

  1. 访问扩展下载地址，下载最新版本的扩展 ZIP 文件
  2. 卸载旧版本的扩展
  3. 解压新下载的 ZIP 文件
  4. 按照"安装扩展"步骤重新加载新版本的扩展

Q3: 扩展会影响网页性能吗？ ​

A: 扩展在后台运行，对网页性能的影响很小。但如果扩展执行大量 DOM 操作或网络请求，可能会影响网页性能。

Q4: 可以在多个浏览器中安装扩展吗？ ​

A: 可以，扩展支持所有基于 Chromium 的浏览器，包括 Chrome、Edge、Brave、Opera 等。你可以在每个浏览器中单独安装扩展。

Q5: 扩展数据会丢失吗？ ​

A: 以下情况会导致扩展数据丢失：

  1. 卸载扩展
  2. 清除浏览器数据
  3. 更新扩展（部分数据可能会丢失）

建议定期备份重要的扩展数据。

Q6: 扩展支持哪些浏览器？ ​

A: 扩展支持所有基于 Chromium 的浏览器，包括：

  • Google Chrome
  • Microsoft Edge
  • Brave
  • Opera
  • 其他 Chromium 浏览器

A: 你可以通过以下方式判断：

  1. 查看扩展的 MCP 工具配置（如果有访问权限）
  2. 如果扩展中包含了需要访问页面全局变量的工具（如访问 React/Vue 组件、操作页面 DOM 等），通常会使用 pageMcpServer 类型
  3. 如果扩展显示通知提示你开启 User Scripts 权限，说明扩展中使用了 pageMcpServer 类型的工具

Q9: 下载的扩展文件在哪里？ ​

A: 扩展 ZIP 文件通常下载到浏览器的默认下载目录。解压后，你可以将扩展文件夹放在任意位置，但建议放在一个固定的位置，方便后续更新。

Q10: 扩展需要网络连接吗？ ​

A: 扩展需要网络连接才能使用 AI 助手功能。扩展会连接到配置的 LLM API 服务，以提供 AI 对话和工具调用功能。

总结 ​

通过本文档，你应该已经了解了如何：

  1. 下载扩展 ZIP 文件
  2. 解压扩展文件
  3. 在 Chrome/Edge 浏览器中安装扩展
  4. 使用扩展功能
  5. 更新和卸载扩展
  6. 调试扩展问题

如果你在安装或使用过程中遇到问题，可以参考本文档的"常见问题"部分，或查看扩展的日志信息进行排查。

相关文档 ​

技术支持 ​

如果你需要技术支持或反馈问题，可以通过以下方式联系：

  • 提交 Issue 到项目仓库
  • 查看项目文档
  • 联系项目维护者