浏览器扩展:看 PDF 时框选一段,AI 结合整篇全文给你讲透 —— 多 Agent、多轮对话、流式输出
Manifest V3 · Side Panel 模式 · 当前版本 v0.4
在网页端浏览 PDF 时框选任意段落,右键唤起 AI;AI 看到的不只是那几句话,而是整篇 PDF 全文 + 选中段落,在侧边栏里流式输出解释,同一引用下可连续追问。普通英文网页还支持「操作引导」模式:输入目标,AI 逐步高亮按钮带你操作。
|
AI 的上下文是全文而非孤立的选中段——它能说明这段话在文档中的位置、作用,并关联其它章节。 |
右键菜单挂多个 AI agent 子菜单(预置 MiniMax / DeepSeek,OpenAI 兼容协议可扩展);同一引用段落下连续追问,流式打字渲染。 |
|
在英文网页输入操作目标(如「如何在 GitHub 创建仓库」),AI 生成最多 8 步教程并逐步高亮元素,每一步由你点「下一步」确认——插件绝不自动提交密码、付款或删除数据。 |
无框架、无打包步骤,原生 ES Module + PDF.js,clone 下来直接「加载已解压的扩展程序」即可运行。快捷键 |
sequenceDiagram
participant U as 用户
participant C as Content Script
participant B as Background (Service Worker)
participant S as Side Panel
participant A as AI Endpoint
U->>C: 在 PDF 中框选段落并右键
C->>B: 推送选区文本 (chrome.runtime.sendMessage)
B->>B: 写入 chrome.storage.session (pendingSelection)
B->>S: sidePanel.open() 自动打开侧边栏
U->>S: 手动选择同一份 PDF 文件
S->>S: PDF.js 逐页解析全文并缓存
U->>S: 输入问题并回车
S->>B: ai/stream 请求 (全文 + 选区 + 问题)
B->>A: OpenAI 兼容流式调用 (SSE)
A-->>B: 流式 chunk
B-->>S: 逐 chunk 转发
S-->>U: 打字机效果渲染,可多轮追问
为什么全文要手动选一次文件:Chrome PDF viewer 中 content script 进不去、background fetch
file://也被安全策略拦截。用户手动选文件(FileReader → PDF.js)是绕过限制后 100% 可靠的路径。
- 打开
chrome://extensions,右上角开启 「开发者模式」 - 点 「加载已解压的扩展程序」 → 选择本项目根目录
- 重要:在扩展卡片里打开 「允许访问文件 URL」(用于读本地 PDF)
- 把扩展图标 📌 钉到工具栏
- 点 ⚙ 进入选项页 → 选择 MiniMax 或 DeepSeek,填入你自己的 API Key
1️⃣ 打开 PDF(拖入 Chrome / Cmd+O / 地址栏 file://...pdf)
2️⃣ 框选一行/一段
3️⃣ 右键 → "AI 解释整篇" → 选择 Agent(如 DeepSeek)
4️⃣ 右键菜单会自动打开 PDF AI 侧边栏
5️⃣ 侧边栏里点 [📁 选择 PDF 文件],选同一份
6️⃣ 等全文加载(变绿点 ✓)
7️⃣ 在底部输入框输问题 → 回车 → AI 基于整篇 PDF 流式回答
- 阅读英文论文时选中关键段 → AI 翻译并解释
- 阅读法律合同选中某条 → AI 解释其在整篇合同里的作用
- 阅读技术文档选中一个术语 → AI 解释并关联文档其它章节
pdf-ai-sidebar/
├── manifest.json # MV3 配置(side_panel + 快捷键 + 右键菜单)
├── icons/ # 16/48/128 PNG 图标
├── src/
│ ├── sidepanel/ # ⭐ v0.4 主界面:Chrome Side Panel
│ │ ├── sidepanel.html
│ │ ├── sidepanel.css
│ │ └── sidepanel.js # 选区显示 + PDF 上传 + 全文解析 + 多轮对话 + 网页 Guide
│ ├── content/
│ │ ├── content.js # 监听右键,把选区推给 background
│ │ └── content.css
│ ├── background/
│ │ └── background.js # 右键菜单 + storage + 流式 AI 调用转发
│ ├── options/ # 设置页(agent 配置 + 自定义 prompt)
│ ├── lib/
│ │ ├── ai-client.js # 统一 AI 调用(OpenAI / Anthropic / Gemini 流式 SSE)
│ │ ├── prompt.js # 全文 + 选区 prompt 拼装
│ │ └── pdf-parser.js # PDF.js 解析封装
│ └── vendor/
│ └── pdfjs/ # PDF.js 4.0.379(本地打包,无外部依赖)
├── test-fixtures/ # Playwright E2E(mock DeepSeek)+ 测试 PDF
├── scripts/make_icons.py # 图标生成脚本
└── README.md
| Agent | Endpoint | 默认 Model |
|---|---|---|
| MiniMax | https://api.minimaxi.com/v1/chat/completions |
MiniMax-M3 |
| DeepSeek | https://api.deepseek.com/v1/chat/completions |
deepseek-chat |
API Key 由用户自行在选项页配置,不打包进扩展。底层客户端兼容 OpenAI / Anthropic / Gemini 三种流式协议,可自行扩展更多 agent。
{fullDoc} = 整篇 PDF 全文,{context} = 选中段落,{question} = 你的问题。默认模板:
你是我的 PDF 阅读助手。我会给你一篇文档的全文(可能截断),以及我特别想理解的一段话。
请基于文档的整体内容,帮我解释选中这段话。回答时:
1. 简要说明这段话在文档中的位置和作用
2. 解释它的核心意思
3. 关联文档中其他相关段落(如果有)
4. 如果我附加了问题,优先回答问题
【文档全文】
"""{fullDoc}"""
【我选中的内容】
"""{context}"""
【我的问题】
{question}
test-fixtures/run_e2e.py 提供完整链路测试(使用 mock DeepSeek,无需真实 Key):启动 mock server → Playwright 以 --load-extension 启动 Chrome → 配置 mock key → 打开测试 PDF 框选 → 右键 → 验证侧边栏流式响应与多轮对话。
不同 Chrome 版本或本机扩展加载环境可能需要手动重新加载扩展后再运行。
| 浏览器 | 支持情况 |
|---|---|
| Chrome 116+ | ✅ 完整支持 |
| Edge 116+ | ✅ 完整支持 |
| Firefox | |
| Safari | ❌ MV3 支持不完整 |
- 全文需要手动选一次文件(原因见「工作原理」,同会话内会缓存不重复解析)
- Side Panel 会占用浏览器右侧空间(但便于和 PDF 并排对照)
- 少数加密/损坏的 PDF 解析会失败(PDF.js 在 service worker 环境的兼容问题)
- AI 流式连接偶发断开时需要重试(自动重试机制尚未实现)
- 排查错误的主入口:
chrome://extensions的 service worker console
- API Key 仅保存在
chrome.storage.sync(同步到你自己的浏览器账号) - 选中段落和 PDF 全文只发往你自己选择的 AI endpoint
- 网页 Guide 模式仅在你主动生成教程时,将当前页面正文和可操作元素索引发送给你选择的 AI
- 不收集任何遥测数据
| 版本 | 改动 |
|---|---|
| v0.1 | 初始版,side panel + 选中段(无全文) |
| v0.2 | side panel + 全文上下文(自动 fetch PDF 失败) |
| v0.4 | Side Panel 模式 + 手动选 PDF 文件(当前) |
Q:支持哪些浏览器?
A:Chrome 116+ 与 Edge 116+(Manifest V3 + Side Panel API,manifest 中 minimum_chrome_version: 116)。Firefox 的 Side Panel API 不兼容、Safari 的 MV3 支持不完整,均暂不支持。
Q:要付费吗?API Key 怎么配置?
A:扩展本身免费开源(MIT),AI 调用走 BYOK(Bring Your Own Key):点侧边栏 ⚙ 进入选项页,选择预置的 MiniMax 或 DeepSeek 并粘贴你自己的 API Key;也可以新增任意 OpenAI 兼容的 endpoint / 模型(底层客户端同时兼容 OpenAI、Anthropic、Gemini 三种流式协议)。Key 只保存在 chrome.storage.sync(同步到你自己的浏览器账号),不打包进扩展、作者也拿不到。
Q:我的 PDF 内容会被上传给第三方吗?
A:扩展不收集任何遥测数据。选中段落、PDF 全文和你的问题,只会发往你自己配置的那个 AI endpoint;PDF 文件本身在你浏览器内用本地打包的 PDF.js 解析,不经过任何中转服务器。详见 PRIVACY_POLICY.md。
Q:支持本地 PDF 还是仅在线 PDF?
A:都支持——只要 PDF 在浏览器标签页里打开(地址栏 file:// 本地文件、.pdf 结尾的在线链接、或页面内嵌的 <embed>/<iframe> PDF)都能框选提问。读本地文件前记得在扩展卡片里开启「允许访问文件 URL」。
Q:为什么加载全文还要再手动选一次同一份文件?
A:Chrome 的原生 PDF 查看器不允许扩展读取其内容,后台自动抓取 file:// 也被安全策略拦截,所以需要你在侧边栏手动选一次文件(FileReader → PDF.js 本地解析 → 缓存,同一会话内不重复解析)。
Q:超长 PDF 会怎样?
A:送入模型的全文默认上限 24000 字符(约 8K-12K tokens)。超出时按优先级智能截断:文档开头(约 30% 预算)+ 选中段落所在页前后(约 50%)+ 文档结尾(约 20%),保证你选中的位置上下文最完整。
除上文「
- 全文有硬截断上限:发送给模型的全文默认 24000 字符封顶(
src/lib/prompt.js的maxChars),超长文档不会完整进入上下文,中段内容可能被采样省略。 - 「多轮追问」不携带历史:每次提问独立拼接「全文 + 选段 + 当前问题」发送(
src/background/background.js的 ask 处理),AI 看不到自己上一轮的回答;侧边栏的对话记录仅用于本地展示与复制。 - 扫描版 / 纯图片 PDF 提取不到全文:PDF.js 只提取文本层,没有文字层的扫描件会得到空全文,此时自动退回「仅基于选段」模式(选段同样依赖文本层)。
- 对话与全文缓存是会话级:聊天记录与解析出的全文存放在
chrome.storage.session,浏览器关闭即清空、不跨设备同步(仅 API Key 走storage.sync)。 - 网页 Guide 模式依赖 DOM 索引:只在普通网页可用(PDF 页面不显示入口);页面结构动态变化后原高亮目标会失效,需要重新生成教程。