docs/script_injection_guide.md

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

概述

本功能允许您动态挂载油猴脚本来增强 AI Studio 的模型列表，支持自定义模型注入和配置管理。脚本更新后只需重启服务即可生效，无需手动修改代码。

⚠️ 重要更新 (v3.0):

• 革命性改进 - 使用 Playwright 原生网络拦截，彻底解决时序和可靠性问题
• 双重保障 - Playwright 路由拦截 + JavaScript 脚本注入，确保万无一失
• 完全改变工作机制 - 现在直接从油猴脚本解析模型列表
• 移除配置文件依赖 - 不再需要手动维护模型配置文件
• 自动同步 - 前端和后端使用相同的模型数据源
• 无适配负担 - 油猴脚本更新时无需手动更新配置

功能特性

• ✅ Playwright 原生拦截 - 使用 Playwright 路由拦截，100% 可靠
• ✅ 双重保障机制 - 网络拦截 + 脚本注入，确保万无一失
• ✅ 直接脚本解析 - 从油猴脚本中自动解析模型列表
• ✅ 前后端同步 - 前端和后端使用相同的模型数据源
• ✅ 零配置维护 - 无需手动维护模型配置文件
• ✅ 自动适配 - 脚本更新时自动获取新的模型列表
• ✅ 灵活配置 - 支持环境变量配置
• ✅ 静默失败 - 脚本文件不存在时静默跳过，不影响主要功能

配置说明

环境变量配置

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

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

# 油猴脚本文件路径（相对于项目根目录）
# 模型数据直接从此脚本文件中解析，无需额外配置文件
USERSCRIPT_PATH=browser_utils/more_modles.js

工作原理说明

新的工作机制 (v2.0):

油猴脚本 → 前端直接注入 + 后端解析模型列表 → API同步

1. 前端: 直接注入原始油猴脚本到浏览器页面
2. 后端: 解析脚本中的 MODELS_TO_INJECT 数组
3. 同步: 将解析出的模型添加到API模型列表

优势:

• ✅ 单一数据源 - 模型数据直接从油猴脚本解析，无需配置文件
• ✅ 自动同步 - 脚本更新时自动获取新模型，保持前后端一致
• ✅ 完美适配 - 与油猴脚本显示效果100%一致（emoji、版本号等）
• ✅ 零维护成本 - 无需为脚本更新做任何适配工作

使用方法

1. 启用脚本注入

确保在 .env 文件中设置：

ENABLE_SCRIPT_INJECTION=true

2. 准备脚本文件 (必需)

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

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

3. 启动服务

正常启动 AI Studio Proxy 服务，系统将：

1. 前端注入 - 直接将油猴脚本注入到浏览器页面
2. 后端解析 - 自动解析脚本中的模型列表
3. API同步 - 将解析出的模型添加到API响应中

就这么简单！ 无需任何配置文件维护。

4. 验证注入效果

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

注意: 如果脚本文件不存在，系统会静默跳过注入操作，不会显示错误信息。

🚀 革命性改进 (v3.0)

问题: JavaScript 脚本拦截存在时序问题和浏览器安全限制，可能无法可靠地拦截网络请求。

解决方案: 使用 Playwright 原生的网络拦截功能 (context.route())，在网络层面直接拦截和修改响应，彻底解决可靠性问题。

技术细节:

• 使用 context.route("**/*", handler) 拦截所有请求
• 在网络层面识别和修改模型列表响应
• 不依赖浏览器 JavaScript 环境
• 同时保留脚本注入作为备用方案

核心优势:

• 🎯 100% 可靠 - 不受浏览器安全策略影响
• ⚡ 更早拦截 - 在网络层面拦截，比 JavaScript 更早
• 🛡️ 双重保障 - 网络拦截 + 脚本注入，确保万无一失

工作原理

🔄 双重拦截机制

1. 启用检查 - 检查 ENABLE_SCRIPT_INJECTION 环境变量
2. 脚本存在性验证 - 检查油猴脚本文件是否存在
3. Playwright 路由拦截 - 使用 context.route() 拦截所有网络请求
4. 模型列表请求识别 - 检测包含 alkalimakersuite 和 ListModels 的请求
5. 响应修改 - 直接修改模型列表响应，注入自定义模型
6. 脚本注入备用 - 同时注入 JavaScript 脚本作为备用方案
7. 后端解析 - 使用JSON解析技术解析脚本中的 MODELS_TO_INJECT 数组
8. API集成 - 将解析出的模型（保留原始emoji和版本信息）添加到后端模型列表

🎯 技术优势

• ✅ Playwright 原生拦截 - 不受浏览器安全限制，100% 可靠
• ✅ 更早的拦截时机 - 在网络层面拦截，比 JavaScript 更早
• ✅ 双重保障 - 网络拦截失败时，JavaScript 脚本作为备用
• ✅ 单一数据源 - 油猴脚本是唯一的模型定义源
• ✅ 自动同步 - 前端和后端自动保持一致
• ✅ 零维护 - 脚本更新时无需任何手动操作
• ✅ 向后兼容 - 支持现有的油猴脚本格式

重要说明 ⚠️

前端和后端双重注入

本功能实现了前端和后端的双重模型注入：

1. 前端注入 - 油猴脚本在浏览器页面上显示注入的模型
2. 后端注入 - API服务器的模型列表也包含注入的模型

这确保了：

• ✅ 在AI Studio页面上可以看到注入的模型
• ✅ 通过API调用时可以使用注入的模型
• ✅ 前端显示和后端API保持一致

模型调用说明

注入的模型可以正常通过API调用，例如：

curl -X POST http://localhost:2048/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "kingfall-ab-test",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

日志输出

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

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

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

# 解析出的模型示例
👑 Kingfall (Script v1.6)
✨ Gemini 2.5 Pro 03-25 (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

多套脚本

通过修改 USERSCRIPT_PATH 可以使用不同的油猴脚本：

USERSCRIPT_PATH=custom_scripts/production_models.js

版本管理

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

注意事项

1. 重启生效 - 脚本文件更新后需要重启服务
2. 浏览器缓存 - 如果模型列表没有更新，尝试刷新页面或清除浏览器缓存
3. 兼容性 - 确保您的油猴脚本与当前的 AI Studio 页面结构兼容
4. 性能影响 - 大量模型注入可能影响页面加载性能
5. 显示一致性 - 系统确保前端显示与油猴脚本效果100%一致

示例配置

完整的 .env 配置示例：

# 基础配置
PORT=2048
ENABLE_SCRIPT_INJECTION=true

# 脚本配置
USERSCRIPT_PATH=browser_utils/more_modles.js

# 其他配置...

技术细节

• 脚本管理器类 - ScriptManager 负责所有脚本相关操作
• 配置集成 - 与现有的配置系统无缝集成
• 错误恢复 - 脚本注入失败不会影响主要功能
• 日志记录 - 详细的操作日志便于调试