Skip to content

script_injection_guide.md

Latest commit

 

History

History
141 lines (93 loc) · 4.6 KB

script_injection_guide.md

File metadata and controls

141 lines (93 loc) · 4.6 KB

油猴脚本动态挂载功能使用指南

概述

本功能允许您动态挂载油猴脚本来增强 AI Studio 的模型列表，支持自定义模型注入和配置管理。系统采用 Playwright 原生网络拦截技术，直接从油猴脚本解析模型列表，确保了 100% 的可靠性和前后端数据的一致性。

功能特性

  • ✅ Playwright 原生拦截 - 使用 Playwright 路由拦截，不受浏览器安全策略影响
  • ✅ 双重保障机制 - 网络拦截 + 脚本注入，确保万无一失
  • ✅ 直接脚本解析 - 从油猴脚本中自动解析模型列表，无需额外配置文件
  • ✅ 前后端同步 - 前端和后端使用相同的模型数据源
  • ✅ 自动适配 - 脚本更新时自动获取新的模型列表
  • ✅ 静默失败 - 脚本文件不存在时静默跳过，不影响主要功能

配置说明

环境变量配置

在 .env 文件中添加以下配置：

# 是否启用脚本注入功能
ENABLE_SCRIPT_INJECTION=true

# 油猴脚本文件路径（相对于项目根目录）
# 模型数据直接从此脚本文件中解析
USERSCRIPT_PATH=browser_utils/more_models.js

工作原理

油猴脚本 → Playwright 网络拦截 (后端) + 脚本注入 (前端) → API同步
  1. 后端 (Playwright): 在网络层拦截 /api/models 请求，直接注入解析出的模型数据。这是核心机制，确保可靠性。
  2. 前端 (浏览器): 辅助注入原始油猴脚本到页面，确保 UI 显示一致。
  3. 同步: 前后端使用同一份脚本数据源，保持完全一致。

核心优势

  • 🎯 高可靠性 - 不受浏览器安全限制
  • ⚡ 更早拦截 - 在网络层面拦截，优于 JavaScript 注入
  • 🛡️ 双重保障 - 网络拦截 + 脚本注入
  • 🔄 单一数据源 - 油猴脚本是唯一的模型定义源

使用方法

1. 启用脚本注入

确保在 .env 文件中设置：

ENABLE_SCRIPT_INJECTION=true

2. 准备脚本文件

将您的油猴脚本放在 browser_utils/more_models.js（或您在 USERSCRIPT_PATH 中指定的路径）。

⚠️ 脚本文件必须存在，否则不会执行任何注入操作。

3. 启动服务

正常启动 AI Studio Proxy 服务，系统将自动处理注入和解析。

4. 验证注入效果

  • 前端: 在 AI Studio 页面上可以看到注入的模型
  • API: 通过 /v1/models 端点可以获取包含注入模型的完整列表

日志输出示例

启用脚本注入后，您将在日志中看到类似输出：

# 网络拦截相关日志
设置网络拦截和脚本注入...
成功设置模型列表网络拦截
成功解析 6 个模型从油猴脚本

# 模型列表响应处理时的日志
捕获到潜在的模型列表响应来自: https://alkalimakersuite.googleapis.com/...
添加了 6 个注入的模型到API模型列表
成功解析和更新模型列表。总共解析模型数: 12

# 解析出的模型示例
👑 Kingfall (Script v1.6)
✨ Gemini 1.5 Pro (Script v1.6)
🦁 Goldmane (Script v1.6)

故障排除

脚本注入失败

  1. 检查文件路径 - 确保 USERSCRIPT_PATH 指向的文件存在
  2. 检查文件权限 - 确保脚本文件可读
  3. 查看日志 - 检查详细的错误信息

模型解析失败

  1. 脚本格式 - 确保油猴脚本中的 MODELS_TO_INJECT 数组格式正确
  2. 必需字段 - 确保每个模型都有 name 和 displayName 字段
  3. JavaScript语法 - 确保脚本文件是有效的 JavaScript 格式

禁用脚本注入

如果遇到问题，可以临时禁用脚本注入：

ENABLE_SCRIPT_INJECTION=false

高级用法

自定义脚本路径

您可以使用不同的脚本文件：

USERSCRIPT_PATH=custom_scripts/my_script.js

版本管理

系统会自动解析脚本中的版本信息，保持与油猴脚本完全一致的显示效果，包括 emoji 和版本标识。

注意事项

  1. 重启生效 - 脚本文件更新后需要重启服务
  2. 浏览器缓存 - 如果模型列表没有更新，尝试刷新页面或清除浏览器缓存
  3. 兼容性 - 确保您的油猴脚本与当前的 AI Studio 页面结构兼容

技术细节

  • 核心实现 - browser_utils/initialization/network.py 实现了 Playwright 网络拦截逻辑。
  • 脚本注入 - browser_utils/initialization/scripts.py 负责将脚本注入到浏览器上下文。
  • 脚本管理 - browser_utils/script_manager.py 负责加载和解析脚本内容。
  • 脚本解析 - browser_utils/operations_modules/parsers.py 负责从脚本中提取模型数据。