t33w411/agentic-browser-chat

# Agentic Browser 聊天 [](https://chromewebstore.google.com/detail/bmkiakodphbdicdfbajbcjemccacihcd) [](./LICENSE) [](https://developer.chrome.com/docs/extensions/mv3/intro/) [](./CONTRIBUTING.md) ## 这是什么 Agentic Browser Chat 是一个 Chrome 扩展，它将 AI 助手放置在一个注入到每个页面的悬浮面板中（页面顶部的 shadow-DOM UI，**不是** Chrome 内置的侧边栏 API）。它可以： - 读取您当前所在页面的任何内容，并回答相关问题。 - 进行长时间运行的对话，支持可搜索的历史记录、收藏夹以及针对单个聊天的模型覆盖。 - 通过内置的 tool registry 为您执行操作：页面查询、表单填写、在沙盒 worker 中执行代码、网络搜索、网络抓取、文档和图像生成等。 - 跨聊天记住关于您的事实，将可重用的流程保存为 **skills**，并将您自己的 **custom instructions** 应用到每个聊天中。 - 管理您自己的笔记（带有版本历史和弹出式编辑器）、任务（带有提醒）和测验——所有这些都与聊天并排进行。 - 附加文件（PDF、DOCX、PPTX、XLSX、CSV、图像）、浏览器标签页、其他聊天、其他笔记、截图和粘贴的电子表格。 它被设计为 **local-first**：您的所有数据都保存在您的浏览器中。没有后端，没有分析，没有开发者控制的服务器。网络请求仅发送到此扩展使用的唯一 LLM 提供商 OpenRouter。 ## 截图

Chat — start a conversation about the current page	Page context — ask anything about what's on screen	Attachments — PDF, DOCX, PPTX, XLSX, CSV, images
Notes — build a personal knowledge base	Tasks — with due dates and reminders	Quizzes — practice from your notes
Image generation — inline via your selected model	Setup — paste your OpenRouter key once	Settings — model, theme, data management

## 亮点 一个纯粹的浏览器端 agent，它可以读取当前页面、搜索网络和抓取 URL（在 guardrails 保护下）、在沙盒 Web Worker 中运行 JavaScript 以进行精确计算、通过确认步骤填写表单，以及生成 Office 文档（DOCX、PPTX、XLSX、PDF、CSV）和图像。它带有一个持久化的 **memory**（模型可对其进行写入）、一个可重用的 **skills** 库（您或模型可以保存）以及您自己的 **custom instructions**（会附加到每次聊天中）。笔记、任务和测验位于同一面板中，因此您可以在不离开页面的情况下捕获、安排和复习知识。所有数据都本地存储在 IndexedDB 中；唯一的外部网络目标是 OpenRouter，使用的是您自己的 API key。 ## 功能 ### 与任何页面聊天 - 与 LLM 进行 **按页面聊天**，具有完整的 markdown、代码、图表和数学公式渲染。 - **持久化聊天历史记录**：可搜索、可排序、可置顶。旧的聊天可以根据您设定的阈值自动清理。 - 每个新聊天都有 **建议提示词**（*为我总结*、*向我解释这个*、*帮助我完成此任务/问题*）。 - **按聊天覆盖模型**：为单个对话选择任何 OpenRouter 模型，而无需更改您的默认设置。 - **收藏**：置顶您经常访问的聊天，并切换到“收藏”视图以过滤列表。 - **Quick Question**：通过右键单击选中文本触发的轻量级模态框。每个 Quick Question 都会在单独的 **Quick Q** 日志中成为其自己的简短聊天，因此不会弄乱您的主要历史记录。 - **复制原始聊天** 用于导出或分享。 - **Reduce-to-float / Expand** 面板模式：将面板缩小为浮动气泡，或将其展开以接管整个视口。 ### 右键菜单和内容选择器 - **右键菜单** 条目： - 选中文本时：*解释所选内容*、*总结所选内容*、*校对所选内容*、*关于所选内容的 Quick Question*、*将所选内容添加到聊天*。 - 选中图像时：*将图像添加到聊天*。 - **内容选择器**：一种可以切换打开的悬停高亮模式。单击任何页面元素可将其内容添加到聊天中。右键单击高亮部分会打开一个小菜单，让您选择 **Add simple HTML to chat**（清理、扁平化后的表示）或 **Add raw HTML to chat**（字面标记）。 - **离开警告**：如果您在 agent 执行任务中途尝试离开，扩展程序会在页面卸载前警告您。 ### 附件 通过输入区域中的 **`+`** 按钮将上下文附加到聊天中： | 来源 | 备注 | |---|---| | **图像上传** | `.png`, `.jpg`, `.webp`, `.gif` | | **文件上传** | `.txt`, `.md`, `.json`, `.csv`, `.pdf`, `.docx`, `.xlsx`, `.xls`, `.ods`, `.pptx`（以及其他 `text/*`） | | **截图** | 捕获当前标签页并内联附加图像 | | **浏览器标签页内容** | 选择另一个打开的标签页；其内容将被扁平化并附加 | | **笔记** | 附加现有的笔记作为上下文 | | **聊天摘要** | 附加另一个聊天的摘要 | | **来自剪贴板的电子表格** | 粘贴剪贴板中的表格数据并将其视为电子表格附件 | 在 **Notes** 编辑器内部，您也可以将文件附加到笔记本身（文件类型与聊天输入相同）。 ### 笔记 - 面板内的完整笔记编辑器，具有 **Edit** 模式和独立的 **read view**。 - **Pop-out**：在独立的浮动窗口中打开任何笔记，以便您可以在主面板中浏览和聊天时继续编辑。 - **版本历史记录**：更改会被记录版本，以便您恢复以前的草稿。 - **收藏** 和 **搜索**。 - 每个笔记上的 **文件附件**。 - **Skill notes**：一个笔记可以被标记为一个 skill，并带有一个类似 `calculate-worksheet-discrepancy` 的 slug。然后，agent 可以通过 `skill` 工具按需加载它。请参阅 [Memory, Skills, and Custom Instructions](#memory-skills-and-custom-instructions)。 ### 任务 - 标题、可选描述、**`dueAt`**、**`reminderAt`**。 - 按 **All / Pending / Completed** 过滤。 - 触发提醒时的 **Chrome notifications**。 - 伴随通知播放的可选 **alert sound**。 - 在“设置”中具有 **可配置的提醒提前时间**（到期前的默认分钟数）。 - service worker 每分钟检查一次提醒闹钟。 ### 测验 - 通过 `generate_questions` 工具从任何源材料（粘贴的文本、附加的笔记或聊天）生成问题。 - 支持 **MCQ**（多项选择）、**FITB**（填空题）以及两者的 **mix**。 - 可选的 **focus** 参数将生成范围限定在特定主题。 - **Spaced practice**：每个问题都有一个 `pausedUntil` 字段，因此您可以将其标记为已回答，并让它在选定的时间段内从活跃池中消失。 ### Agent 工具 Agent 会在对话中途调用这些工具。按用途分组，并强调了安全保护措施： **针对笔记语料库的类文件系统操作** - `read`、`write`、`edit` — 读取、创建和修改笔记内容。 - `grep`、`ls` — 通过正则表达式（内容或标题范围）发现笔记或列出它们。 **页面交互** - `page_query` — 使用选择器查询当前页面上的元素并返回其内容/状态。其 `select_option` 子操作还驱动 **custom dropdowns**（div/ARIA 组合框，如 React Select、MUI、Headless UI）：它会打开下拉菜单并单击匹配的选项，能够处理 portal-rendered 列表、type-to-filter 和虚拟化列表。 - `page_fill_form` — 填写原生表单字段（input、textarea、单选 ``、复选框、单选按钮、contenteditable）。**安全防护措施：**绝不提交、单击或导航；敏感字段（密码、OTP/2FA、卡号、CVV、IBAN、SSN 等）以及 disabled、readonly、hidden 和不可见的字段都会被阻止；逗号分隔且非唯一的选择器会被拒绝（每个字段仅限一个确认的选择器）；每次写入都会通过回读值进行验证。自定义 div/ARIA 下拉菜单是通过 `page_query` 的 `select_option` 子操作设置的，而不是此工具。 - `take_screenshot` — 捕获当前页面视口，并获取视觉模型对其的文本描述。这是当 DOM 工具给出令人困惑或不充分信号，或者问题本质上是视觉问题时（例如覆盖字段的悬浮层、自定义小部件、布局故障）的一种自由裁量后备方案。扩展自身的面板 UI 在捕获期间会被隐藏，因此它绝不会出现在截图中。 - `eval` — 在 **sandboxed Web Worker** 中运行 JavaScript。可以通过 `blob_ids` 加载附件内容（作为保留的 `blobs` 数组注入），并通过返回 `__document__` spec（xlsx / docx / pdf / csv / pptx，通过与 `create_document` 相同的生成器构建）来发出可下载的文件。**安全防护措施：**没有 DOM，没有 `chrome` API，没有网络（fetch / XHR / WebSocket / importScripts / caches / IndexedDB / BroadcastChannel 全部被阻止）。5–30 秒的严格超时。输出上限为 200 KB；输入变量上限为 1 MB；`blob_ids` payload 和任何 `__document__` spec 各自享有独立的 50 MB 预算。 **网络** - `web_search` — 搜索网络。必需的 gateway：agent 必须先进行搜索，然后才能抓取它以前未曾见过的任何 URL。 - `web_fetch` — 抓取 URL 并对其进行总结，或针对特定 prompt 回答问题。处理 HTML、纯文本、JSON、图像（通过视觉模型）和文档（PDF、DOCX、XLSX、PPTX）。**安全防护措施：**runtime **会拒绝任何未出现在对话上下文中的 URL**（用户消息或先前的工具结果）。模型无法伪造 URL 并抓取它。每个请求有 15 秒的超时。 **浏览器标签页** - `list_tabs` — 列出用户在所有窗口中打开的标签页（id、title、url、active、window、discarded，以及用于扩展程序无法读取的页面的 `accessible` 标志）。只读：它从不切换、打开或关闭标签页。 - `read_tab` — 读取一个打开的标签页的实时内容（通过 `list_tabs` 获取的 id）并获取其摘要。快速的二级模型会回答提供的 prompt 或总结整个标签页，因此大型页面永远不会被转储到上下文中。与 `web_fetch`（向 URL 发出新的网络请求）不同，此工具读取的是实际打开的页面，包括登录状态和客户端渲染状态。读取处于休眠状态的标签页会将其唤醒；返回的内容将被视为不受信任的外部数据。 **生成** - `create_document` — 生成具有结构化内容（标题、项目符号、表格、工作表、幻灯片）的可下载 DOCX、XLSX、PDF、PPTX 或 CSV 文件。文件存储为 blob 并内联显示。 - `generate_image` — 通过配置的图像模型进行图像生成。 - `generate_questions` — 生成测验项目并直接将其保存到 Quiz 标签页中。 **上下文感知** - `get_environment` — 当前日期、时间、时区、locale 和 OS/platform。 - `memory` — 读取/写入持久化的 memory 笔记（见下文）。 - `skill` — 创建、读取、更新或删除 skill 笔记（见下文）。 ### Memory、Skills 和 Custom Instructions 扩展支持三种不同的机制来向 agent 注入上下文。了解它们的区别至关重要。 | 机制 | 谁来编写 | 引用方式 | 模型何时能看到它 | |---|---|---|---| | **Custom instructions** | 您，在 Settings → Agent 中 | 输入一次的静态文本 | 自动注入到每个聊天的系统 prompt 中 | | **Memory** | Agent（通过 `memory` 工具）根据您的请求，或者您自己在 Settings → Agent → Manage Memory 中 | 一条持久化的 memory 笔记，每行一条 | 自动注入到每个聊天中 | | **Skills** | Agent（通过 `skill` 工具），或者您自己在 Settings → Agent → Manage Skills 中 | 每个 skill 都有一个唯一的 slug，例如 `calculate-worksheet-discrepancy`。模型会列出可用的 skill，但**仅在需要时**才加载 skill 的主体内容 | 在每个聊天中列出；主体内容按需加载 | 在实践中： - **Custom instructions** 是设置全局偏好的地方：*"Always respond in British English"*（始终用英式英语回答）、*"Keep answers concise"*（保持回答简洁）、*"When showing code, prefer TypeScript"*（展示代码时，优先使用 TypeScript）。 - **Memory** 用于存放 agent 应该一直记住的关于您的事实*"User's name is Tayo"*（用户名是 Tayo）、*"User uses VS Code"*（用户使用 VS Code）、*"User's pets are named Bo and Lyra"*（用户的宠物叫 Bo 和 Lyra）。您要求 agent 记住；它会调用 `memory` 工具并将条目附加（以第三人称表述）。您也可以自己通过 **Settings → Agent → Manage Memory** 添加、编辑和删除条目。 - **Skills** 用于存放您不想反复重新输入的流程：agent 可以在请求时重新应用的分步过程。您说 *"remember how to do X"*（记住如何做 X）；agent 会保存为一个 skill。稍后您可以说 *"do X for this data"*（为这些数据执行 X），agent 就会加载 `/x` 并遵循它。您也可以自己通过 **Settings → Agent → Manage Skills** 创建、编辑和删除 skill。 ### API 调用日志 内置的 **API Logs** 视图会捕获对 OpenRouter 的每一个请求（prompt、工具调用、原始响应、token 计数、成本估算）。它旨在作为一项 **power-user 和调试** 功能——当答案错误时，您想确切检查模型接收到了什么，或者当您正在调整 custom instructions 并希望查看组装好的系统 prompt 时，它会非常有用。 通过 **Settings → View API logs** 打开。日志可以作为渲染文本或原始 JSON 查看。可以从同一视图清除它们。 ### 跨标签页同步 面板状态在不同标签页之间保持一致： - 在标签页 A 上打开面板，切换到标签页 B，面板会出现并显示相同的对话、选定的笔记和标签页焦点。 - 面板工具栏中的 **Sync all** 按钮可在需要时（例如在修复陈旧的草稿后）强制手动重新同步各标签页间的聊天、笔记、任务和测验问题。 - service worker 会跟踪活动标签页并将状态更新推送到相关的 content scripts。 ### 渲染 聊天界面使用以下组件渲染模型输出： - 通过 `marked` 渲染 **Markdown**，并通过 `DOMPurify` 进行清理。 - 通过 `highlight.js` 对代码进行 **语法高亮**。 - 内联的 **Mermaid** 图表。 - 通过带有 TeX-SVG 输出的 MathJax 支持 **LaTeX / 数学公式**。 - 一个 **多幻灯片新手引导轮播** 会在首次运行时介绍这些功能（上面的截图即取自此处）。 ## 安装 ### 从 Chrome Web Store 直接从商店安装已发布的构建版本： **[➜ Chrome Web Store 上的 Agentic Browser Chat](https://chromewebstore.google.com/detail/bmkiakodphbdicdfbajbcjemccacihcd)** 1. 打开列表，然后点击 **Add to Chrome**。 2. 确认权限提示。 3. 将扩展程序固定到工具栏以便访问。 适用于任何支持 Chrome Web Store 的基于 Chromium 的浏览器（Chrome、Edge、Brave、Arc、Vivaldi）。 ### 从源码安装（开发者模式） 如果您想运行最新的未发布更改或修改代码，这是推荐的路径。 1. 克隆仓库： git clone https://github.com/t33w411/agentic-browser-chat.git cd agentic-browser-chat 2. 在 Chrome（或任何基于 Chromium 的浏览器：Edge、Brave、Arc、Vivaldi）中打开 `chrome://extensions`。 3. 打开右上角的 **Developer mode**。 4. 点击 **Load unpacked**。 5. 选择克隆的 `agentic-browser-chat` 目录。 6. 将扩展程序固定到工具栏以便访问。 **无需构建步骤**。扩展会直接加载源文件。拉取新更改后，点击 `chrome://extensions` 中扩展的重载图标，并重载您希望应用更改的任何打开的标签页。 ## 快速开始 1. 点击扩展的工具栏图标，在任何页面上打开侧边栏面板。 2. 浏览新手引导轮播，或跳过直接进入 **Settings**（齿轮图标）。 3. 粘贴您的 **[OpenRouter](https://openrouter.ai) API key** 并选择一个默认模型。 4. 可选：在 **Settings → Agent** 中，添加一两行 **custom instructions**（例如 *"Be concise. Answer in British English."*（保持简洁。用英式英语回答。））。 5. 关闭设置并尝试： - “总结这个页面。” - 选择一个段落，右键单击 → **Quick Question about selection**。 - 将 PDF 拖入输入框并询问相关内容。 - 询问：*"Remember that my name is Tayo and I prefer concise responses."*（记住我的名字是 Tayo，并且我偏好简洁的回答。）Agent 会将其写入 **memory**，从而跨聊天持久化。 6. 打开 **Notes** 标签页；agent 也可以通过其类文件系统工具对您的笔记进行写入和读取。 7. 打开 **Tasks** 标签页并创建一个具有到期时间的任务——当它触发时，您将收到 Chrome 通知。 ## 配置 所有配置都位于面板的 **Settings** 标签页中。没有单独的选项页面。 | 设置 | 作用 | |---|---| | **Theme** | 浅色、深色或跟随系统。 | | **OpenRouter API Key** | 您的 OpenRouter API key。本地存储在 `chrome.storage` 中。除 OpenRouter API 调用的 `Authorization` header 外，绝不会传输到任何地方。 | | **Default chat model** | 用于新对话。可以在任何聊天内部使用按聊天覆盖。 | | **Image generation model** | 供 `generate_image` 工具使用。 | | **Custom instructions** (Agent) | 注入到每个新聊天的系统 prompt 中的自由文本指令。 | | **Manage Skills** | 创建、编辑和删除 agent 的 skills（可重用的 `/command` 指令）。该按钮显示当前的 skill 计数。 | | **Manage Memory** | 创建、编辑和删除 memory 条目（agent 跨聊天保留的事实）。该按钮显示当前的条目计数。 | | **Alert sound** | 切换任务提醒和 agent 确认提示的音效。 | | **Reminder lead time** | 在 `dueAt` 之前多少分钟触发提醒的默认值（0–1440）。 | | **Storage used** | 扩展程序当前占用的浏览器存储空间的实时估算。 | | **Delete chats older than** | 自动清理超过阈值的聊天（30 / 60 / 90 / 180 / 365 天，或 *Never*）。被置顶的聊天不受影响。 | | **Prune orphaned blobs** | 手动回收不再被任何聊天或笔记引用的附件 blob 所占用的空间。 | | **View API logs** | 打开 API 调用检查器（见 [API 调用日志](#api-call-logs)）。 | ### LLM 提供商 扩展使用 **[OpenRouter](https://openrouter.ai)** 作为其单一提供商。OpenRouter 在一个 API 和一个密钥之后聚合了来自 OpenAI、Anthropic、Google、Meta、Mistral、DeepSeek 等众多提供商的模型，因此您可以自由切换模型，而无需费心管理多个独立账户。 **不**支持与 OpenAI、Anthropic 或其他提供商 API 的直接集成。 **扩展程序不附带任何 API key。请自带您的 OpenRouter 密钥。** ## 权限：每个权限的用途 Manifest V3 要求预先声明每个权限。以下是每个权限存在的原因： | 权限 | 原因 | |---|---| | `` host access | 扩展程序需要（在您要求时）读取页面内容，并在任何站点上注入面板 + 内容选择器。仅在您调用某项功能时激活。 | | `activeTab`、`tabs` | 识别当前标签页并跨标签页同步面板。 | | `scripting` | 动态注入面板和工具脚本（并在扩展重载后重新注入）。 | | `contextMenus` | 右键单击选择的操作（解释、总结等）。 | | `clipboardRead`、`clipboardWrite` | 在您粘贴到面板时读取剪贴板；在您从中复制时写入格式化的输出。 | | `storage` | 持久化设置、API key 和偏好。 | | `alarms` | 安排任务提醒。 | | `notifications` | 在任务到期时显示提醒通知。 | | `offscreen` | 在 MV3 下运行依赖于 DOM 的实用程序，因为 MV3 剥离了 service worker 的 DOM。 | 如果未来的功能需要新的权限，它将首先在更新日志中注明并在 issue 中讨论。 ## 隐私 **简而言之：** 您的所有数据都保留在您的设备上。唯一的网络目标是 OpenRouter，您使用自己的密钥进行身份验证。 该扩展**不会**： - 运营任何开发者控制的服务器。 - 发送分析、遥测或崩溃报告到任何地方。 - 跨设备同步数据。 - 回连进行许可证检查、超出标准 Chrome Web Store 机制之外的更新或其他任何事情。 该扩展**会**： - 将聊天、笔记、任务、测验、设置、memory、skills 和附件 blob 存储在您浏览器的 IndexedDB 和 `chrome.storage` 中。 - 在您发起的每个轮次中，通过 HTTPS 将您的对话、附件和 API key 发送到 OpenRouter。 完整详情：[PRIVACY.md](./PRIVACY.md)。 ## 架构 该扩展是单进程的 Manifest V3 设置： - **Service worker**（`background/service-worker.js`）协调一切：存储、标签页消息传递、上下文菜单、闹钟、IndexedDB 处理程序和 agent 的 API 日志记录器。 - **Content scripts** 被注入到每个标签页中。它们在 shadow DOM 内部渲染侧边栏面板，驱动内容选择器和选择操作，并桥接发往 service worker 的消息。 - **面板** 使用原生 JS 构建，没有框架也没有打包器。UI 位于 `mode: 'open'` 的 shadow root 内部；查询通过 shadow root 进行，从不使用 `document`。 - **Agent** 位于客户端。它构建系统 prompt + 工具列表（`agent/contextBuilder.js`），调用 LLM（`agent/client.js`），执行工具调用（`agent/toolExec.js`），并在上下文窗口填满时压缩历史记录（`agent/compactor.js`）。 - 所有持久状态都位于 **通过 Dexie 实现的 IndexedDB**（`shared/db.js`）中，通过 service-worker 处理程序进行代理，从而确保 content scripts 具有单一、无竞态条件的数据库访问路径。 ### 为什么没有框架？ - Manifest V3 禁止远程加载代码；所有内容都必须打包。 - 框架会增加复杂性（打包器、构建、source map），而对于这种规模来说收益甚微。 - 原生 JS 保持了代码的可审查性，并使扩展体积保持小巧。 ## 项目布局 ``` agentic-browser-chat/ ├── manifest.json # MV3 manifest; declares scripts, permissions, web-accessible resources ├── background/ # Service worker and its modules │ ├── service-worker.js # Entry point: wires up everything below │ ├── dbHandler.js # IndexedDB proxy for content scripts │ ├── tabMessaging.js # Cross-tab/content messaging + script re-injection │ ├── contextMenus.js # Right-click menu setup │ ├── commands.js # Keyboard command handlers │ ├── panelDataRepoImpl.js # Repository functions backing the panel (notes, chats, tasks, blobs) │ └── apiLoggerImpl.js # Persistent log of LLM API calls ├── content/ # Content-script bootstrap │ ├── preInit.js # First in the load order; bumps the listener-generation counter │ ├── keyboardShield.js # Captures keys early to protect panel inputs │ ├── agentLeaveWarning.js # Warns on navigate-away while agent is working │ └── main.js # Last in the load order; runs re-init recovery ├── panel/ # The injected overlay panel (shadow-DOM UI) │ ├── panel.js # Boot controller; attaches the shadow root │ ├── panelTemplate.js # HTML template │ ├── panelData.js # Static reference data (templates, defaults) │ ├── panelRuntime.js # All UI logic, tab routing, data-action delegation │ ├── panelStateSync.js # Cross-tab state sync │ ├── panelIcons.js # Icon SVGs │ ├── images/ # Static images used inside the panel │ └── panel.css ├── agent/ # The LLM agent loop │ ├── client.js # Provider-agnostic HTTP client │ ├── contextBuilder.js # Builds the system prompt + message list per turn │ ├── tools.js # Tool definitions (schemas) │ ├── toolExec.js # Executes tool calls in the page/extension │ ├── documentGeneration.js # Generated-doc support │ ├── fileParsing.js # PDF/DOCX/XLSX/etc. parsing pipeline │ ├── compactor.js # History compaction when context fills │ └── apiLogger.js # Client side of the API log ├── shared/ # Code used by both content scripts and the service worker │ ├── db.js # Dexie schema │ ├── messages.js # Message-type constants │ ├── storage.js # chrome.storage wrapper │ ├── search.js # FlexSearch index helpers │ ├── runtimeRequest.js # Promise-based chrome.runtime.sendMessage wrapper │ ├── panelDataRepo.js # Proxy that forwards repo calls to the service worker │ └── toolRegistry.js # Lookup for available tools ├── tools/ # Page-interaction tools │ ├── contentSelector.js # Hover-highlight + click-to-attach │ ├── selectionContextActions.js # Right-click actions on selected text │ └── flattenedContent.js # Clean HTML extraction ├── ui/ # Shared UI primitives │ ├── floatingPanel.js # Panel host element + show/hide │ └── toast.js # Toast notifications ├── utils/ # Pure utilities │ ├── dom.js │ └── clipboard.js ├── offscreen/ # MV3 offscreen document (needed for DOM-only APIs) ├── lib/ # Vendored third-party libraries (see THIRD_PARTY_NOTICES.md) ├── sounds/ # Notification sounds ├── styles.css # Page-side CSS (toast host etc.) ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── SECURITY.md ├── PRIVACY.md ├── THIRD_PARTY_NOTICES.md └── LICENSE ``` ## 捆绑库 为了符合 MV3 合规性（无远程代码），所有第三方 JS 都内嵌在 `lib/` 下。每个库都保留了其自身的许可证。包含版本和上游 URL 的完整表格：[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。 亮点： | 库 | 在此项目中的作用 | |---|---| | Dexie.js | IndexedDB 的封装库 | | FlexSearch | 对聊天/笔记进行全文搜索索引 | | marked + highlight.js + DOMPurify | 安全地渲染助手的 Markdown | | Mermaid + MathJax | 内联渲染图表和数学公式 | | PDF.js, mammoth.js, SheetJS, PapaParse, JSZip | 解析附件文件 | ## 开发 ### 前置条件 - **Chrome** 或其他基于 Chromium 的浏览器（需要 Manifest V3）。 - **Node.js 18+**，用于 `node --check` 语法验证步骤。不需要进行 npm install；扩展程序本身没有运行时的 npm 依赖。 ### 循环 1. 编辑文件。 2. `node --check path/to/file.js`（每次编辑 JS 后必做）。 3. 点击 `chrome://extensions` 中扩展旁边的重载图标。 4. 重新加载您正在测试的标签页。 5. 在页面**和** service worker（`chrome://extensions` 中的链接）上打开 DevTools，以同时观察两个控制台。 ### 架构规则 一些能帮您节省时间的模式： - 每个新的 content script 必须以匹配的顺序注册到 `manifest.json` 和 `background/tabMessaging.js` **两者**中。 - 面板位于 shadow DOM 中；所有面板查询都通过 `ABChatContent.ui.panelShadowRoot` 进行，从不使用 `document`。 - 任何地方都不允许内联事件处理程序。在面板的挂载节点上使用 `data-action` 委托。 - 持久的 DOM 监听器必须在每次触发时检查 listener-generation 计数器，以便在扩展重载后停止操作。 - 添加新的 chip field 需要同步四个调用点（DOM 写入、DOM 读取、DB 写入、DB 读取）。 - 添加新的 repo 函数需要在 `background/panelDataRepoImpl.js` **和** `shared/panelDataRepo.js` 中的 proxy table 进行注册。 ### 调试技巧 - Service 日志：`chrome://extensions` → 点击扩展下的 **Service worker**。 - Content-script 日志：常规页面 DevTools。 - IndexedDB 检查：DevTools → Application → IndexedDB → `agentic-browser-chat`。 - API 调用日志：可在面板的 Settings → View API logs 下查看。 ## 故障排除 | 症状 | 可能的原因/修复方法 | |---|---| | 面板无法打开 | 在 `chrome://extensions` 处重载扩展，然后重新加载页面。在更改扩展代码后，这两个重载操作都是必需的。 | | 重载后出现 "Extension context invalidated" 错误 | 预计在扩展重载后会出现一次；重新加载页面以重新注入 content scripts。 | | LLM 调用因 401 错误而失败 | 缺少 OpenRouter API key 或其无效。请在设置中重新输入。 | | 当被要求抓取页面时，Agent 提示 "URL not allowed" | 预期行为。`web_fetch` 仅接受已经出现在对话或先前工具结果中的 URL——要求 agent 先进行 `web_search`，或将 URL 粘贴到聊天中。 | | 任务提醒未触发 | Chrome 可能已挂起 service worker。下一次浏览器活动将恢复闹钟；操作系统级别的通知权限也很重要。 | ## 路线图与状态 这是一个**作为开源发布的个人项目**。维护属于尽力而为，在 v2.0 之前，次要版本之间可能会发生重大更改。当前的重点： - 稳定性和 bug 修复 - 更多 agent 工具 - 更好的跨标签页同步 不在计划范围内（目前）： - 云同步 - 移动端 - 用更繁重的多提供商抽象取代 OpenRouter ## 贡献 欢迎提交 PR。在开启 PR 之前，请阅读： 1. [CONTRIBUTING.md](./CONTRIBUTING.md) — 设置、约定、PR 检查清单。 2. [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。 优秀的首次贡献：带有清晰重现步骤的 bug 修复、文档改进、遵循现有模式的新的 agent 工具、可访问性、性能。 ## 安全 请**私下**报告安全问题，不要作为公开 issue 提交。请参阅 [SECURITY.md](./SECURITY.md)。 ## 许可证 [MIT](./LICENSE) © 2026 Tayo Olusiyan. 捆绑的第三方库受其自身许可证的约束；请参阅 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。 ## 鸣谢 建立在 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) 中列出的开源项目的基础之上。特别感谢 Dexie、marked、highlight.js、Mermaid、MathJax、PDF.js、mammoth.js、SheetJS、PapaParse、DOMPurify、FlexSearch 和 JSZip——没有它们，这一切都不会存在。

标签：AI助手, Chrome插件, 个人知识管理, 数据可视化, 本地优先, 浏览器扩展, 自动化Agent, 自定义脚本