📖 参考方案 | AI 驱动的 Chrome Extension 架构方案：Plasmo + Vercel AI SDK，侧边栏对话生成并执行页面脚本。此为蒸馏产物，供开发时参考查阅。触发词：Chrome 扩展参考、AI 脚本方案、Plasmo 参考、侧边栏脚本方案
Scanned 5/27/2026
Install via CLI
Skills Directoryopenskills install wangjs-jacky/jacky-skills---
name: chrome-ext-ai-script
description: "📖 参考方案 | AI 驱动的 Chrome Extension 架构方案：Plasmo + Vercel AI SDK，侧边栏对话生成并执行页面脚本。此为蒸馏产物，供开发时参考查阅。触发词：Chrome 扩展参考、AI 脚本方案、Plasmo 参考、侧边栏脚本方案"
---
# AI 驱动的 Chrome Extension — 项目参考方案
> 📖 **蒸馏产物** — 本文件是从开源项目蒸馏提炼的参考方案，不是可执行的 skill。
> 供开发同类项目时参考查阅，包含完整的架构设计、功能模块说明和代码参考。
> 从 [zhuweileo/Monkey](https://github.com/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
```
---
## 八、快速启动
```bash
# 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` | 技术栈选型理由 + 初始化命令 |
No comments yet. Be the first to comment!
