AI 驱动的 Chrome Extension — 项目参考方案
📖 蒸馏产物 — 本文件是从开源项目蒸馏提炼的参考方案，不是可执行的 skill。
供开发同类项目时参考查阅，包含完整的架构设计、功能模块说明和代码参考。
从 zhuweileo/Monkey 蒸馏提炼，提供可复用的架构模式和实现参考。
一、项目定位
浏览器侧边栏里的 AI 助手 — 用户用自然语言描述需求，AI 感知当前页面结构，生成脚本并直接在页面上执行。
核心亮点
| 亮点 |
说明 |
| 看到就能改 |
AI 感知当前页面的真实 DOM 结构，生成的脚本精准匹配页面元素 |
| 说了就生效 |
对话完成后代码直接在页面执行，无需复制粘贴 |
| 一键配置可用 |
填入 API Key → 测试连通性 → 确认 Key 有效 → 立即开始使用 |
| 多服务商自由切换 |
OpenAI / Claude / Gemini 等随时切换，插件式扩展 |
典型使用场景
| 用户说 |
效果 |
| "把页面右侧的广告栏隐藏掉" |
AI 根据真实 DOM 找到广告容器并隐藏 |
| "帮我把这个表单自动填上测试数据" |
AI 识别表单字段并填入数据 |
| "提取这个页面所有商品价格" |
AI 生成脚本抓取价格信息并展示 |
| "这个按钮太丑了，帮我换个样式" |
AI 修改目标元素的 CSS |
| "帮我监控这个页面的价格变化" |
AI 生成定时检查脚本 |
| "提取这个页面的所有联系方式" |
AI 扫描页面结构，抓取邮箱/电话等信息 |
二、功能模块总览
┌──────────────────────────────────────────────────────────────┐
│ Chrome Extension 架构 │
│ │
│ ┌───────────────────┐ │
│ │ 侧边栏 SidePanel │ ← 用户主界面 │
│ │ │ │
│ │ ┌─────────────┐ │ │
│ │ │ 对话界面 │ │ · 流式消息渲染 │
│ │ │ (ChatView) │ │ · 图片输入支持 │
│ │ └─────────────┘ │ · 多轮对话上下文 │
│ │ ┌─────────────┐ │ │
│ │ │ 代码预览 │ │ · 自动检测 AI 生成的脚本 │
│ │ │ (CodePreview)│ │ · 一键在页面中执行 │
│ │ └─────────────┘ │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌─────────┴─────────┐ ┌─────────────────┐ │
│ │ 设置面板 Options │ │ 后台服务 SW │ │
│ │ │ │ │ │
│ │ · 服务商选择 │ │ · 消息路由 │ │
│ │ · API Key 配置 │ │ · Tab 管理 │ │
│ │ · 连通性测试 ✓ │ │ · 生命周期 │ │
│ │ · 模型选择 │ │ (不做 AI 调用) │ │
│ └─────────┬─────────┘ └────────┬────────┘ │
│ │ │ │
│ ┌─────────┴──────────────────────┴──────────────────┐ │
│ │ AI 服务层 │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Provider │ │ Provider │ │ Provider │ ... │ │
│ │ │ 注册中心 │ │ OpenAI │ │ Claude │ │ │
│ │ │ (插件式) │ │ │ │ │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ · Prompt 构建（注入真实 DOM 快照 → 防幻觉） │ │
│ │ · 流式调用（Vercel AI SDK 统一接口） │ │
│ └────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────────────┴───────────────────────────────┐ │
│ │ 页面交互层 │ │
│ │ │ │
│ │ · Content Script → DOM 快照提取 │ │
│ │ - 交互元素（input/button/select） │ │
│ │ - ID 元素（精准定位） │ │
│ │ - 页面正文（Turndown → Markdown） │ │
│ │ - 标题/地标（页面结构概览） │ │
│ │ │ │
│ │ · world:MAIN 注入 → 在页面全局作用域执行代码 │ │
│ └────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 目标网页（用户正在浏览的页面） │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
核心数据流
用户输入："把这个页面的广告隐藏掉"
│
▼
① 提取页面信息
Content Script 扫描当前 Tab：
· 交互元素 → 选择器信息
· ID 元素 → 精准定位依据
· 页面正文 → Turndown 转 Markdown
· 标题/地标 → 页面结构概览
│
▼
② 构建 AI Prompt
System Prompt = 角色定义 + 真实 DOM 快照 + 页面正文
（AI 看到真实的元素 ID 和 class，不会编造）
│
▼
③ 流式调用 AI
Vercel AI SDK → 自动选对应服务商的 SSE 格式
侧边栏实时显示回复（一个字一个字出来）
│
▼
④ 检测代码块
AI 回复包含 ==UserScript== 代码块
→ 展示代码预览 + "在页面执行"按钮
│
▼
⑤ 用户点击执行
chrome.scripting.executeScript({ world: 'MAIN' })
代码在目标页面全局作用域运行
→ 广告消失，用户直接看到效果
三、模块功能详解
3.1 侧边栏模块（SidePanel）
侧边栏是用户的主操作界面，核心是对话式交互：
| 功能 |
说明 |
| 流式对话界面 |
支持文本输入和图片上传，AI 回复一个字一个字显示 |
| 多轮对话上下文 |
AI 能理解之前的对话历史，持续优化脚本 |
| 代码预览组件 |
自动检测 AI 生成的 ==UserScript== 代码块并展示 |
| 一键执行 |
点击按钮，代码直接在当前页面执行 |
| 页面感知 |
每次调用 AI 前自动提取当前页面的 DOM 快照 |
3.2 设置面板（Options）
设置面板是用户首次使用的入口，核心是让用户确认 API Key 可用：
选择服务商 → 填入 API Key → 选择模型 → 点击"测试连接"
│
实际调用一次 API
│
┌──────────┴──────────┐
│ │
✓ 连接成功 ✗ 连接失败
（显示延迟） （Key无效/网络错误/频率限制）
│ │
│ 429 也算成功 ✓
│ （频率限制，但 Key 有效）
│
保存设置 → 进入侧边栏
设计要点：
- 429 也算成功：频率限制说明 Key 有效，显示"(频率限制，但 Key 有效)"
- 切换不丢失：服务商之间切换时，内存缓存保存各家的输入内容
- 首安装引导：扩展安装后自动打开设置页
3.3 AI 服务层
| 功能 |
说明 |
| Provider 注册中心 |
插件式架构，新增服务商只需写一个 Provider 文件并注册 |
| DOM 感知 Prompt |
每次调用前注入真实 DOM 快照到 System Prompt，防止 AI 编造选择器 |
| 流式调用 |
Vercel AI SDK 统一处理各服务商的 SSE 格式差异 |
| 多模态支持 |
支持文本 + 图片输入 |
3.4 页面交互层
| 功能 |
说明 |
| DOM 快照提取 |
Content Script 提取交互元素、ID、标题、正文等结构信息 |
| world:MAIN 注入 |
绕过 CSP 限制，在页面全局作用域执行代码 |
| Turndown 转换 |
HTML → Markdown，给 AI 精简的页面结构 |
| Readability 提取 |
提取页面正文（去广告、去导航） |
四、关键设计决策
| 问题 |
解决方案 |
参考 |
| CSP 绕过 |
world:'MAIN' + 间接 eval (0,eval)(src) |
references/architecture-decisions.md |
| MV3 SW 超时 |
AI 调用放 SidePanel，SW 只做消息路由 |
references/architecture-decisions.md |
| AI 幻觉选择器 |
每次调用前注入真实 DOM 快照到 System Prompt |
references/dom-snapshot.md |
| 多服务商适配 |
Provider 注册中心模式，统一接口 |
references/ai-provider-registry.md |
| Tab 定位问题 |
使用 lastFocusedWindow 而非 currentWindow |
references/architecture-decisions.md |
五、技术栈
| 维度 |
选择 |
选择理由 |
| 扩展框架 |
Plasmo |
HMR + 自动 manifest + React+TS 开箱即用 |
| AI SDK |
Vercel AI SDK |
useChat hook 直连 React，自动兼容各服务商 SSE |
| 页面感知 |
Turndown + Readability |
轻量纯浏览器端，HTML→Markdown 成熟 |
| 样式 |
Tailwind CSS |
原子化，快速迭代 |
| 包管理 |
pnpm |
速度快、磁盘小 |
六、从 Monkey 蒸馏的能力映射
| Monkey 原有能力 |
处理方式 |
理由 |
| DOM 快照提取 |
保留 |
核心能力，让 AI 看到真实页面 |
| world:MAIN 注入 |
保留 |
核心能力，绕过 CSP 执行代码 |
| System Prompt 构建 |
保留 |
核心能力，注入 DOM 防幻觉 |
| SSE 流式解析（手写） |
用 AI SDK 替代 |
SDK 自动处理各服务商差异 |
| 多服务商存储 |
改造 |
从硬编码改为 Provider 注册模式 |
| 脚本持久化自动注入 |
去除 |
新项目不需要 |
| URL glob 匹配 |
去除 |
新项目不需要 |
| 脚本管理 CRUD |
去除 |
新项目不需要 |
| 设计令牌 tokens.css |
用 Tailwind 替代 |
更灵活 |
七、项目目录结构（参考）
src/
├── background/index.ts # Service Worker（消息路由 + 存储）
├── contents/dom-snapshot.ts # Content Script（DOM 快照提取）
├── sidepanel/ # 侧边栏主界面
│ ├── ChatView.tsx # 对话界面
│ ├── CodePreview.tsx # 代码预览组件
│ ├── providers/ # AI 服务商配置
│ └── hooks/ # AI 对话和 DOM 快照 hooks
├── lib/ # 核心库
│ ├── ai/ # AI 能力层
│ │ ├── providers/ # 各服务商适配器
│ │ ├── provider-registry.ts # 插件化注册中心
│ │ └── prompt-builder.ts # System Prompt 构建
│ ├── dom/ # 页面感知层
│ │ ├── extractor.ts # 轻量选择器提取
│ │ └── snapshot.ts # 页面快照
│ ├── injection/ # 代码执行层
│ └── storage/ # 存储层
└── package.json
八、快速启动
# 1. 创建项目
pnpm create plasmo script-copilot
cd script-copilot
# 2. 安装核心依赖
pnpm add ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
pnpm add turndown @mozilla/readability
pnpm add -D @types/turndown
# 3. 启动开发
pnpm dev
References
详细实现代码和设计决策见 references/ 目录：
| 文件 |
内容 |
references/architecture-decisions.md |
关键架构决策（CSP 绕过、MV3 超时、Tab 定位等） |
references/dom-snapshot.md |
DOM 快照提取器代码 + Turndown/Readability 整合 |
references/world-main-injection.md |
world:MAIN 脚本注入代码 |
references/ai-provider-registry.md |
Provider 注册中心代码 |
references/streaming-chat.md |
流式对话实现（Vercel AI SDK）+ Prompt 模板构建 |
references/tech-stack-setup.md |
技术栈选型理由 + 初始化命令 |
wangjs-jacky