
# Design: Chrome AI Agent — BYOK 浏览器 AI 插件

Generated by /office-hours on 2026-04-15
Branch: main
Repo: claude_workspace
Status: APPROVED
Mode: Builder

## Problem Statement

用户已经习惯了 Chrome 浏览器的操作逻辑、扩展生态和同步体系，但缺少类似 Dia/Atlas/Comet 等 AI 浏览器的智能能力。现有的 AI 浏览器需要额外订阅、界面不习惯、迁移成本高。而 Sider/Monica 等 Chrome AI 插件虽然存在，但也需要额外付费订阅。

用户已经在为 Claude Max / ChatGPT Plus / Codex 等 LLM 服务付费，不应该再为浏览器 AI 能力重复买单。

## What Makes This Cool

**BYOK（Bring Your Own Key）模式** — 用户插入自己已有的 API key（Claude、GPT、Gemini、本地模型），零额外成本获得完整的 AI 浏览器体验。

三层能力叠加：
1. **页面理解** — 分析当前页面数据、内容、结构
2. **Agent 操控** — 自然语言描述任务，AI 拆解成多步操作自动执行（点击、填表、导航）
3. **智能标签管理** — 分析所有打开的标签页，自动分组/关闭无用页面/追踪关注趋势

## Constraints

- Chrome Extension Manifest V3 架构约束
- Service Worker 5 分钟超时限制（长时间自动化需拆成短任务链）
- Content Script 运行在隔离环境，无法直接访问页面 window 对象
- 用户需要信任插件处理其 API key（安全存储是硬需求）

## Premises

1. Chrome Extension API 有足够的权限实现页面操控能力（点击按钮、填表单、读取页面内容）— **已验证可行**，chrome.scripting + Content Scripts 提供完整 DOM 访问和操控
2. 用户（技术人群）愿意把自己的 API key 填进浏览器插件 — **已确认**，目标用户能接受这个模式
3. BYOK + Agent 操控 + 标签管理的组合足以与 Sider/Nanobrowser 等现有产品差异化 — **已确认**

## Recommended Approach: Agent 工作台

Agent 操控 + 标签管理是用户最想要的核心能力，也是跟现有产品差异化最大的点。定时工作流可以作为后续迭代加上去。

### 技术架构

```
┌─────────────────────────────────────────┐
│ Chrome Extension (MV3)                  │
├──────────┬──────────┬───────────────────┤
│ Sidebar  │ Content  │ Service Worker    │
│ UI       │ Scripts  │ (Background)      │
│ (React)  │ (DOM     │                   │
│          │  操控)   │ ┌───────────────┐ │
│ 对话界面 │          │ │ Agent Engine  │ │
│ 标签管理 │ 页面分析 │ │ - 任务拆解    │ │
│ 模型配置 │ 元素操作 │ │ - 步骤执行    │ │
│          │ 数据提取 │ │ - 状态管理    │ │
│          │          │ └───────────────┘ │
│          │          │ ┌───────────────┐ │
│          │          │ │ Model Router  │ │
│          │          │ │ - Claude      │ │
│          │          │ │ - GPT         │ │
│          │          │ │ - Gemini      │ │
│          │          │ │ - Local LLM   │ │
│          │          │ └───────────────┘ │
│          │          │ ┌───────────────┐ │
│          │          │ │ Tab Manager   │ │
│          │          │ │ - 分析/分组   │ │
│          │          │ │ - 智能关闭    │ │
│          │          │ │ - 趋势追踪   │ │
│          │          │ └───────────────┘ │
└──────────┴──────────┴───────────────────┘
         │                    │
         ▼                    ▼
    页面 DOM              外部 LLM API
```

### 核心模块

**1. Model Router（模型路由器）**
- 统一的 LLM 接口抽象层
- 支持 OpenAI / Anthropic / Google / OpenRouter / 本地 Ollama
- API key 安全存储：使用 Web Crypto API (AES-GCM + 随机 IV) 加密后存入 chrome.storage.local，密钥派生自用户设置的 PIN 或首次使用时随机生成
- Ollama 本地模型：需在 manifest 声明 `http://localhost/*` host_permission，直接 fetch localhost:11434
- 模型切换不影响上层逻辑

**2. Agent Engine（Agent 引擎）**
- 接收用户自然语言指令
- 调用 LLM 进行任务规划（拆解成多步操作）
- 每步操作通过 Content Script 执行（点击、填表、提取数据、导航）
- **元素定位策略**：采用 accessibility tree + DOM 混合定位（参考 Nanobrowser），优先使用 aria label / role，fallback 到 CSS selector + 文本匹配。Phase 1 启动前需 spike 1-2 天验证此方案在 SPA 页面（React/Vue）上的可靠性
- 执行状态实时反馈到侧边栏 UI
- **任务状态持久化**：每步执行结果序列化到 chrome.storage.session，Service Worker 重启后可恢复中断的任务链
- 错误恢复：某步失败时 LLM 重新规划

**3. Tab Manager（标签管理器）**
- chrome.tabs API 获取所有标签信息（URL、标题、最后访问时间）
- LLM 分析标签内容，自动分类/分组（chrome.tabGroups API）
- 识别并建议关闭长时间未访问的标签
- **关注趋势分析**：基于当前打开的标签页 URL + 标题进行主题聚类（由 LLM 完成），输出文字摘要。数据仅来源于当前 tabs，不使用 chrome.history API（避免额外权限申请）

**4. Sidebar UI（侧边栏界面）**
- React + TailwindCSS
- 对话模式：与当前页面交互
- Agent 模式：显示任务执行进度和步骤
- 标签视图：标签分析和管理面板
- 设置：API key 配置、模型选择、偏好

### 安全设计

- API key 使用 Web Crypto API (AES-GCM) 加密后存入 chrome.storage.local，不上传任何服务器
- 所有 LLM 调用直接从用户浏览器发出，插件不做中转
- 开源代码，用户可审计
- Content Script 权限策略：使用 `activeTab` + `chrome.scripting.executeScript()` 动态注入，仅在用户主动触发时获取当前页面权限，不在 manifest 声明 `<all_urls>`

### 开发分期

**Phase 0（Day 1-2）：前置验证 [BLOCKER]**
- Spike：在 3-5 个真实网站（含 React SPA）上验证 accessibility tree + DOM 混合定位方案的可靠性
- 结论决定 Phase 1 的页面理解方案（纯 DOM vs DOM + 截图多模态）

**Phase 1（Week 1-2）：基础能力**
- Chrome Extension 脚手架（MV3 + React Sidebar）
- Model Router：支持 OpenAI 和 Anthropic
- 基础对话：读取当前页面内容 → 发送 LLM → 展示回答
- API key 配置界面

**Phase 2（Week 3）：Agent 能力**
- Agent Engine：任务拆解 + 多步执行
- Content Script 操作集：click、fill、extract、scroll、navigate
- 任务状态持久化（应对 Service Worker 重启）
- 执行状态可视化 + 错误处理和重试

**Phase 3（Week 4）：标签管理 + 打磨**
- Tab Manager：标签分析、分组、清理建议
- 关注趋势分析
- 更多模型支持（Gemini、Ollama）
- UI 打磨、快捷键支持

## 竞品参考

- **Nanobrowser** — 开源，BYOK，多 Agent 工作流，GitHub 7k+ star
- **Mendis** — 开源，自然语言控制浏览器，70+ 动作
- **HARPA AI** — 商业产品，多 LLM 支持
- **Sider / Monica** — 商业产品，侧边栏 AI 助手（需额外订阅）

## Success Criteria

- 能用自然语言让 AI 完成一个跨多步的页面操作任务
- 标签管理能准确识别和分组相关标签
- 支持至少 3 个 LLM provider（Claude、GPT、Gemini）
- Agent 完成 3 步以上页面操作任务的成功率 > 80%

## Next Steps

1. 调研 Nanobrowser 和 Mendis 的源码架构
2. 执行 Phase 0 spike：验证元素定位方案（1-2 天）
3. 搭建 Chrome Extension MV3 + React Sidebar 脚手架
4. 实现 Model Router，先接通 Claude API
5. 跑通最小闭环
6. 发布：GitHub 开源 + Chrome Web Store 上架（免费）
