打造你的 AI 浏览器助手：从零到一的完整实践

一个支持智谱、通义、DeepSeek、MiniMax 四大平台的智能浏览器扩展 ------ 开发实录 + 完全使用指南，一篇读完。

---

目录

• 写在前面
• 一、项目概览
• 二、五分钟快速开始
• 三、配置指南
• 四、日常使用教程
• 五、实用场景详解
• 六、开发历程
• 七、技术架构深度解析
• 八、实战技巧与最佳实践
• 九、常见问题与解决
• 十、项目数据与成果
• 十一、未来规划
• 十二、开发感悟
• 结语

---

写在前面

你是否想过让 AI 帮你自动浏览网页、总结内容、操作电商网站？是否想在浏览器侧边栏拥有一个像 Cursor 编辑器那样的智能助手？

经过两周的开发和迭代，我打造了一个功能完整的 Chrome 浏览器扩展 ------ AI 浏览器助手。它支持四大主流 AI 平台，采用侧边栏设计，能够理解自然语言并自动操作网页。

本文将完整的使用指南 与开发实录合二为一：既能帮你 5 分钟装好、用起来，也能让你理解背后的架构决策与工程细节。
AI 浏览器助手
功能
智能对话
页面总结
电商助手
房产搜索
数据提取
网页自动化
平台
智谱 GLM
通义千问
DeepSeek
MiniMax
技术
Manifest V3
Side Panel API
Function Calling
视觉 OCR 兜底
体验
侧边栏设计
Auto 模式
实时进度反馈
轻量 50KB

---

一、项目概览

核心特性

AI 浏览器助手是一个基于 Chrome Manifest V3 开发的智能浏览器扩展，主要特点：

特性	说明
多平台支持	一键切换智谱 GLM、通义千问、DeepSeek、MiniMax
侧边栏设计	类似 Cursor/Kimi 的侧栏体验，与网页并排显示
Function Calling	支持 8 个工具函数，实现真正的网页自动化
轻量高效	纯 JavaScript 实现，体积仅 50KB
安全可靠	API Key 本地存储，不上传第三方服务器
开源免费	MIT 协议，完全开源

能做什么？

知识问答
打开网站
总结页面
搜索商品
提取数据
操作页面
用户自然语言输入
AI 意图识别
直接回答
open_url
get_page_content
fill_input + click_element
extract_data
click / scroll / wait
返回结果给用户

1. 智能对话 --- 与 AI 自然语言交流，支持多轮对话
2. 页面总结 --- 一键总结任何网页内容（新闻、博客、文档）
3. 电商助手 --- 在淘宝、京东自动搜索商品、筛选价格
4. 房产搜索 --- 在链家、贝壳自动填写筛选条件
5. 数据提取 --- 提取页面结构化数据（价格、标题、评价）
6. 网页操作 --- 自动点击、填表、滚动页面

为什么选择这个扩展？

• 无需为每个模型单独装扩展；一个扩展接入四大平台，按需切换
• 侧边栏常驻，比传统 Popup 更适合长对话与对照网页
• Auto 模式根据问题类型自动选择最合适的模型
• 开源（MIT），可自行审计权限与网络行为

---

二、五分钟快速开始

系统要求

• 浏览器：Chrome（版本 ≥ 114）或 Edge（Chromium 内核）
• 操作系统：Windows / macOS / Linux
• 网络：能访问对应 AI 平台的 API

浏览器兼容性：

• ✅ Chrome（推荐，版本 ≥ 114）
• ✅ Edge（Chromium 版本）
• ✅ Brave、Vivaldi 等 Chromium 内核浏览器
• ❌ Firefox（不支持 Side Panel API）
• ❌ Safari（API 不兼容）

安装步骤

下载源码
打开 chrome://extensions/
开启开发者模式
加载已解压的扩展程序
选择项目文件夹
图标出现 = 安装成功!

1. 下载扩展

# 克隆仓库
git clone https://gitee.com/quyixiao/feifei.git
cd feifei/zhipu-browser-assistant

# 或直接下载 ZIP 并解压

2. 加载到浏览器

1. 打开 Chrome，在地址栏输入：chrome://extensions/
2. 开启右上角的「开发者模式」开关
3. 点击「加载已解压的扩展程序」
4. 选择 zhipu-browser-assistant 文件夹
5. 看到扩展图标出现在工具栏，安装成功！

3. 验证安装

• 点击工具栏的扩展图标
• 浏览器右侧会打开侧边栏
• 显示「输入任意指令...」提示即表示安装成功

如何打开侧边栏？

这里有个关键技巧很多人不知道：

❌ 左键点击扩展图标 → Popup 弹窗（有边框）
✅ 右键点击扩展图标 → 选择「在侧边栏中打开」（无边框）

在 manifest.json 中配置：

{
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "action": {
    "default_title": "AI 浏览器助手"
  }
}

---

三、配置指南

获取 API Key

根据你想使用的平台，访问对应网站获取 API Key：
智谱
通义
DeepSeek
MiniMax
选择 AI 平台
哪个平台？
open.bigmodel.cn
dashscope.console.aliyun.com
platform.deepseek.com
platform.minimax.io
注册 → 创建 API Key → 复制
在扩展选项页粘贴 Key
测试 Key → 保存设置

智谱 GLM

1. 访问 智谱开放平台
2. 注册/登录账号
3. 进入「API Keys」→「创建新的 API Key」
4. 复制 Key（格式：xxxxxxxx.xxxxxxxx）

推荐模型：

• GLM-4-Flash --- 速度快、价格低（推荐日常使用）
• GLM-5 --- 旗舰模型，性能强大
• GLM-4.7 --- 最新稳定版

通义千问（DashScope）

1. 访问 阿里云 DashScope
2. 开通模型服务
3. 创建 API-Key
4. 复制 Key（格式：sk-xxxxxxxx）

推荐模型：

• qwen-flash --- 快速响应
• qwen-plus --- 综合性能
• qwen-max --- 最强模型

DeepSeek

1. 访问 DeepSeek 开放平台
2. 注册账号并充值
3. 创建 API Key
4. 复制 Key

推荐模型：

• deepseek-chat --- V3 对话模型
• deepseek-reasoner --- 思考推理模式

MiniMax

1. 访问 MiniMax 开放平台
2. 注册账号并获取 API Key
3. 复制 Key

推荐模型：

• MiniMax-M2.7 --- 最新模型（约 60 tps）
• MiniMax-M2.7-highspeed --- 高速版本（约 100 tps）
• MiniMax-M2.5 --- 稳定版本

配置 API Key

方法一：通过侧边栏设置

1. 点击工具栏的扩展图标打开侧边栏
2. 点击右上角的「⚙️」设置按钮
3. 跳转到选项页面

方法二：直接打开选项页

1. 在 chrome://extensions/ 找到本扩展
2. 点击「详细信息」→「扩展程序选项」
3. 或右键扩展图标 →「选项」

在选项页面：

1. 选择对话模型 --- 在每个平台的下拉框中选择模型
2. 填写 API Key --- 粘贴对应平台的 Key
3. 测试 Key --- 点击「测试 Key」按钮验证（会发送一个极小请求）
4. 默认模型 --- 选择侧栏默认使用的模型（推荐选 Auto）
5. 保存设置 --- 点击「保存设置」按钮

提示：

• 可以同时配置多个平台的 Key，按需切换
• Auto 模式会根据问题类型自动选择最合适的模型
• API Key 仅保存在本地浏览器，不会上传

自定义模型

如果官方新增了模型，可以在「自定义模型 ID」中添加：

1. 在对应平台区块找到「自定义模型 ID」输入框
2. 输入模型 ID（如 glm-6、qwen-ultra 等）
3. 点击「添加」
4. 模型会出现在下拉列表中

API 集成示例

各平台的请求格式：

智谱 GLM：

POST https://open.bigmodel.cn/api/paas/v4/chat/completions
Authorization: Bearer <API_KEY>

{
  "model": "glm-4-flash",
  "messages": [...],
  "tools": [...],
  "temperature": 0.7
}

通义千问：

POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
Authorization: Bearer <API_KEY>

{
  "model": "qwen-flash",
  "messages": [...],
  "temperature": 0.7
}

DeepSeek：

POST https://api.deepseek.com/chat/completions
Authorization: Bearer <API_KEY>

{
  "model": "deepseek-chat",
  "messages": [...],
  "temperature": 0.7
}

MiniMax：

POST https://api.minimax.io/v1/chat/completions
Authorization: Bearer <API_KEY>

{
  "model": "MiniMax-M2.7",
  "messages": [...],
  "temperature": 1.0  // MiniMax 推荐 (0, 1]
}

---

四、日常使用教程

基础对话

打开侧边栏，直接输入问题：

你：你好
AI：你好！我是 AI 浏览器助手，可以帮你浏览网页、总结内容、自动操作等。有什么我可以帮你的吗？

你：今天是星期几？
AI：今天是 2026 年 4 月 5 日，星期天。

总结网页

在任意网页上输入：

你：总结这个页面
AI：[自动读取页面内容]
这是一篇关于人工智能发展的文章，主要内容包括：
1. AI 技术的最新突破
2. 大语言模型的应用场景
3. 未来发展趋势展望
...

打开网站

你：打开淘宝
AI：[自动打开 https://www.taobao.com]
已为你打开淘宝首页。

你：去百度搜索"人工智能"
AI：[打开百度 → 填写搜索框 → 点击搜索]
已在百度搜索"人工智能"，找到相关结果。

切换模型

点击侧边栏底部的模型选择器（如「Auto ▾」），可以手动切换模型：

• Auto --- 自动选择（推荐）
• 智谱系列 --- GLM-5、GLM-4-Flash 等
• 通义系列 --- Qwen-Flash、Qwen-Plus 等
• DeepSeek --- DeepSeek-Chat、DeepSeek-Reasoner
• MiniMax --- MiniMax-M2.7、M2.7-highspeed 等

清空对话 & 停止生成

• 点击「清空」按钮可清除当前对话历史，开始新对话
• 如果 AI 回复太长或需要中断，点击「停止」按钮（发送按钮变为停止图标）

---

五、实用场景详解

场景 1：淘宝购物

淘宝页面 AI API Background 侧栏 用户 淘宝页面 AI API Background 侧栏 用户 "打开淘宝搜索电动车" sendMessage 发送对话 + 工具定义 tool_call: open_url("taobao.com") chrome.tabs.create 工具结果 tool_call: fill_input(" 注入脚本填写搜索框 click_element("搜索按钮") 操作成功 工具结果 "已在淘宝搜索电动车" 显示回复 展示结果

对话示例：

你：打开淘宝搜索电动车
AI：[打开淘宝 → 填写搜索框 → 点击搜索]
已在淘宝搜索"电动车"，找到 2000+ 个相关商品。

你：筛选价格 2000-5000 元的
AI：当前页面显示的电动车中，价格在 2000-5000 元的有：
1. 小牛电动车 UQi+ - 3999 元
2. 雅迪电动车 F7 - 2899 元
3. 爱玛电动车 A500 - 4599 元
...

你：向下滚动看更多
AI：[调用 scroll_page(500)]
已向下滚动页面，可以看到更多商品了。

场景 2：京东比价

你：在京东搜索 iPhone 15 Pro Max
AI：[打开京东 → 搜索商品]
已找到 iPhone 15 Pro Max 的相关商品。

你：提取前 10 个商品的价格
AI：[调用 extract_data 提取]
前 10 个商品价格如下：
1. Apple iPhone 15 Pro Max 256GB - 9999 元
2. Apple iPhone 15 Pro Max 512GB - 11999 元
3. Apple iPhone 15 Pro Max 1TB - 13999 元
...

场景 3：链家找房

你：在链家帮我找北京朝阳区的两居室
AI：好的！我来帮你在链家搜索。请问预算范围是多少？

你：总价 500-800 万
AI：[打开链家 → 选择北京 → 选择朝阳区 → 筛选两居室 → 设置价格范围]
已为你筛选出符合条件的房源，共找到 120 套...

场景 4：新闻总结

打开任意新闻网站（如 36氪、虎嗅）：

你：总结本页的核心内容
AI：[读取页面正文]
这篇文章的核心内容：

标题：《AI 大模型竞争进入下半场》

要点：
1. 国内大模型厂商开始从"参数竞赛"转向"应用落地"
2. 多模态能力成为新的竞争焦点
3. 企业级市场需求快速增长
4. 成本控制和推理效率是关键挑战

结论：行业正在从技术驱动向商业价值驱动转型。

场景 5：数据提取

在商品列表页：

你：提取这个页面所有商品的标题和价格
AI：[调用 extract_data]
已提取当前页面的商品信息：

1. 小米 14 Ultra - 5999 元
2. 华为 Mate 60 Pro - 6999 元
3. iPhone 15 Pro - 7999 元
4. OPPO Find X7 - 4999 元
...
共 48 个商品

场景 6：自动填表

你：帮我在这个表单填写信息：姓名张三，手机号 13800138000，邮箱 test@example.com
AI：[识别表单字段 → 逐个填写]
已为你填写表单：
- 姓名：张三 ✓
- 手机号：13800138000 ✓
- 邮箱：test@example.com ✓
请检查信息是否正确，确认后可以提交。

---

六、开发历程

从 Popup 到 Side Panel

最初的版本使用传统的 Popup 弹窗，但很快发现问题：
✅ Side Panel 方案
❌ Popup 方案
Chrome 114 Side Panel API
空间有限
对话体验差
点击才显示
无法持久
与网页分离
切换不便
右侧滑出
类似 Cursor 侧栏
可拖动宽度
空间充裕
与网页并排
方便对照
持久显示
不会自动关闭

转折点：Chrome 114 引入了 Side Panel API！侧边栏的优势显而易见：从右侧滑出、可拖动调整宽度、与网页并排显示、持久显示不会自动关闭。

从单平台到多平台

最初只支持智谱 GLM，但随着使用发现：

• 不同模型适合不同场景（速度 vs 质量）
• 用户可能已经有其他平台的账号
• 成本考虑（各平台定价不同）

解决方案：设计统一的 Provider 抽象层
glm-*
qwen-*
deepseek-*
MiniMax-*
用户选择模型
getProviderForModel
智谱 Provider
通义 Provider
DeepSeek Provider
MiniMax Provider
open.bigmodel.cn/api/paas/v4/...
dashscope.aliyuncs.com/...
api.deepseek.com/...
api.minimax.io/...
统一返回格式

function getProviderForModel(modelId) {
  if (modelId.startsWith('glm-')) return 'zhipu';
  if (/^qwen/i.test(modelId) || modelId.startsWith('Qwen')) return 'qwen';
  if (/^deepseek/i.test(modelId)) return 'deepseek';
  if (/^MiniMax/i.test(modelId)) return 'minimax';
  return 'zhipu';
}

function resolveProviderEndpoint(modelId) {
  const provider = getProviderForModel(modelId);
  const endpoints = {
    zhipu: 'https://open.bigmodel.cn/api/paas/v4/chat/completions',
    qwen: 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
    deepseek: 'https://api.deepseek.com/chat/completions',
    minimax: 'https://api.minimax.io/v1/chat/completions'
  };
  return endpoints[provider];
}

这样设计的好处：

• 用户可以随时切换平台和模型
• 新增平台只需添加配置，无需修改核心逻辑
• 支持自定义模型 ID（当官方发布新模型时）

Auto 模式的智能选择

面对多个模型，用户如何选择？我实现了 Auto 模式：

function pickAutoModel(userMessages) {
  const last = userMessages[userMessages.length - 1].content;
  const totalLen = userMessages.join('').length;
  
  if (totalLen > 4500 || /总结|归纳|详细分析/.test(last)) {
    return { id: 'deepseek-chat', reason: '偏重理解、长文或分析' };
  }
  
  if (/^(打开|跳转|去|搜)/.test(last.trim()) && last.length < 80) {
    return { id: 'qwen-flash', reason: '短指令、导航类' };
  }
  
  return { id: 'glm-4-flash', reason: '默认快速' };
}

实际效果：

• 「打开淘宝」→ 使用 qwen-flash（响应快）
• 「总结这个页面」→ 使用 deepseek-chat（理解强）
• 普通对话 → 使用 glm-4-flash（性价比高）

---

七、技术架构深度解析

整体架构

AI API 平台
Chrome 浏览器
Content Script (content.js)
Background Service Worker (background.js)
Side Panel (sidepanel.js)
chrome.runtime.sendMessage
chrome.tabs.sendMessage
sendResponse
port.postMessage
用户输入
对话历史
状态显示
API 调用
工具路由
消息中转
限流控制
DOM 读取
元素点击
数据提取
表单填写
智谱 GLM
通义千问
DeepSeek
MiniMax

扩展文件结构

zhipu-browser-assistant/
├── manifest.json          # 扩展配置文件（Manifest V3）
├── background.js          # 后台脚本（API 调用、工具执行）
├── content.js             # 内容脚本（页面操作、数据提取）
├── sidepanel.html         # 侧边栏界面
├── sidepanel.js           # 侧边栏逻辑
├── sidepanel.css          # 侧边栏样式
├── options.html           # 选项页面
├── options.js             # 选项页逻辑
├── popup.html             # 弹窗（已禁用，使用侧边栏）
├── icons/                 # 图标资源
└── vendor/                # 第三方库（marked、DOMPurify）

核心数据流

Content Script AI API Background 侧边栏 用户 Content Script AI API Background 侧边栏 用户 loop [每个工具调用] alt [AI 返回工具调用] [AI 直接回复] 输入指令 chrome.runtime.sendMessage POST /chat/completions (带 tools 定义) tool_calls: [open_url, fill_input...] chrome.tabs.sendMessage 执行 DOM 操作 操作结果 messages.push(tool result) 再次调用（含工具结果） 最终文本回复 文本回复 返回结果 显示回复

核心模块详解

1. Background Service Worker --- 限流处理

各平台都有 RPM（每分钟请求数）限制，频繁调用会触发 429 错误。
delay 结束
HTTP 200
HTTP 429
extraGapMs * 0.62 - 120
extraGapMs += 500 * 1.5^attempt
下次请求
重试
等待槽位
发送请求
成功
限流
减少惩罚
增加惩罚

const zhipuThrottle = {
  nextAllowedAt: 0,
  baseGapMs: 800,
  extraGapMs: 0
};

async function waitThrottleSlot(signal) {
  const now = Date.now();
  const delay = Math.max(0, zhipuThrottle.nextAllowedAt - now);
  
  if (delay > 0) {
    await sleepWithCountdown(delay, '节流等待', signal);
  }
}

function onZhipuRateLimited(attempt) {
  zhipuThrottle.extraGapMs += 500 * Math.pow(1.5, attempt);
}

function onZhipuSuccess() {
  zhipuThrottle.extraGapMs = Math.max(0, Math.floor(zhipuThrottle.extraGapMs * 0.62) - 120);
}

结果：将 429 错误率从 30% 降至 < 1%。

2. Function Calling 实现

这是扩展最核心的功能。定义 8 个工具供 AI 调用：
8 个工具函数
open_url

打开 URL
get_page_info

页面基本信息
get_page_content

页面完整正文
click_element

点击元素
fill_input

填写输入框
scroll_page

滚动页面
extract_data

提取数据
wait_time

等待延时

工具定义示例：

const TOOLS = [
  {
    type: "function",
    function: {
      name: "open_url",
      description: "在新标签页打开指定 URL",
      parameters: {
        type: "object",
        properties: {
          url: { type: "string", description: "要打开的完整 URL" }
        },
        required: ["url"]
      }
    }
  },
  {
    type: "function",
    function: {
      name: "get_page_content",
      description: "获取当前页面的完整正文，用于总结或分析",
      parameters: { type: "object", properties: {} }
    }
  },
  // ... 其他 6 个工具
];

执行流程：

// 1. 调用 AI API 并传入工具定义
const response = await fetch(apiUrl, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    model,
    messages,
    tools: TOOLS,
    temperature: 0.7
  })
});

// 2. AI 返回工具调用
const message = response.choices[0].message;
if (message.tool_calls) {
  // 3. 执行每个工具调用
  for (const call of message.tool_calls) {
    const result = await executeToolCall(call.function.name, call.function.arguments);
    
    // 4. 将结果添加到对话历史
    messages.push({
      role: 'tool',
      content: JSON.stringify(result),
      tool_call_id: call.id
    });
  }
  
  // 5. 再次调用 AI 生成最终回复
  const finalResponse = await fetch(apiUrl, {
    body: JSON.stringify({ model, messages })
  });
}

3. Content Script --- 智能元素查找

负责实际的页面操作，支持多种元素定位方式：

function findElement(selector) {
  // 方式 1: 直接 CSS 选择器
  let el = document.querySelector(selector);
  if (el) return el;
  
  // 方式 2: 按文本内容查找（模糊匹配）
  const allElements = document.querySelectorAll('button, a, input, [role="button"]');
  for (const elem of allElements) {
    if (elem.textContent.includes(selector) || elem.value === selector) {
      return elem;
    }
  }
  
  return null;
}

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.action === 'clickElement') {
    const el = findElement(msg.selector);
    if (el) {
      el.scrollIntoView({ behavior: 'smooth', block: 'center' });
      setTimeout(() => el.click(), 300);
      sendResponse({ success: true });
    } else {
      sendResponse({ success: false, error: '未找到元素' });
    }
  }
});

4. 视觉识别兜底

当 DOM 读取失败时（如复杂 SPA 或防爬虫网站），自动启用视觉识别：
成功且长度 ≥ 140 字
失败或太短
请求页面内容
DOM 读取
返回正文
启用视觉兜底
滚动页面 + 截图

每次 600px, 最多 10 张
压缩图片

JPEG quality=42
调用 glm-4v-flash

OCR 识别每张截图
拼接所有文字
返回完整正文

async function getPageContentViaVisionScroll(tabId, apiKey) {
  const windowId = (await chrome.tabs.get(tabId)).windowId;
  
  // 1. 滚动页面并截图
  const dataUrls = [];
  const step = 600;
  let y = 0;
  
  while (y < totalHeight && dataUrls.length < 10) {
    await chrome.scripting.executeScript({
      target: { tabId },
      func: (yPos) => window.scrollTo(0, yPos),
      args: [y]
    });
    
    await sleep(380);
    
    const url = await chrome.tabs.captureVisibleTab(windowId, {
      format: 'jpeg',
      quality: 42
    });
    
    dataUrls.push(url);
    y += step;
  }
  
  // 2. 使用智谱视觉模型 OCR 识别
  const pieces = [];
  for (let i = 0; i < dataUrls.length; i++) {
    const data = await callZhipuVision('glm-4v-flash', [
      { type: 'text', text: `这是第 ${i+1}/${dataUrls.length} 张截图，请 OCR 提取文字` },
      { type: 'image_url', image_url: { url: dataUrls[i] } }
    ]);
    pieces.push(data.choices[0].message.content);
  }
  
  return pieces.join('\n\n');
}

效果：成功率从 70% 提升至 95%+。

---

八、实战技巧与最佳实践

1. 如何写好 Function 描述？

工具函数的 description 直接影响 AI 的调用准确性。

❌ 不好的描述：

{
  name: "get_page_content",
  description: "获取页面内容"
}

✅ 好的描述：

{
  name: "get_page_content",
  description: "仅当用户明确要求总结/分析「本页、当前页、这个页面」的正文时使用。扩展会注入脚本或滚动截图识别文字。禁止用于小说剧情、百科、与当前页无关的问答。"
}

关键点：

1. 明确使用场景（「仅当...」）
2. 说明实现方式（「注入脚本或截图」）
3. 列出禁用场景（「禁止用于...」）

2. 系统 Prompt 的重要性

不同场景需要不同的系统 Prompt：

// 纯知识问答
const SYSTEM_PROMPT_QA = `
你是友好的中文助手，擅长知识问答、闲聊与创作建议。
【本轮】用户未要求操作浏览器或读取当前网页。
请仅用自身知识直接回答，不要调用任何工具。
`;

// 浏览器操作
const SYSTEM_PROMPT_BROWSER = `
你是智能浏览器助手，能操作用户正在使用的 Chrome 标签页。

【先判断意图】
- 百科、小说、翻译、解题等：直接回答，不调用工具
- 明确要打开网站、搜索商品、总结本页：使用工具

【使用规则】
- 操作当前页前可先用 get_page_info 了解页面
- 电商搜索框常用选择器：淘宝 #q，京东 #key
- 用户指定网站但不在该站时，先用 open_url
`;

// 根据用户输入动态选择
function shouldAttachBrowserTools(messages) {
  const last = messages[messages.length - 1].content;
  return /本页|打开|搜索|总结/.test(last);
}

3. 错误处理与用户体验

实时进度反馈：

const progressPort = chrome.runtime.connect({ name: 'chat-progress' });

function chatProgress(text) {
  progressPort.postMessage({
    type: 'log',
    text,
    ts: Date.now()
  });
}

// 使用示例
chatProgress('正在读取页面内容...');
chatProgress('已获取 12,345 字，正在分析...');
chatProgress('调用工具：click_element');

超时控制：
总时长 > 2 分钟
无进度 > 10 秒
正常
是
否
开始对话
设置计时器
检查超时
抛出总超时错误
抛出空闲超时错误
继续执行
AI 返回?
更新进度时间
返回结果

const CHAT_MAX_WALL_MS = 120_000;  // 总超时 2 分钟
const CHAT_IDLE_DEADLINE_MS = 10_000;  // 无进度超时 10 秒

async function chatWithTimeout(messages) {
  const startTime = Date.now();
  let lastProgressTime = Date.now();
  
  const checkTimeout = () => {
    const now = Date.now();
    if (now - startTime > CHAT_MAX_WALL_MS) {
      throw new Error('对话总时长超过 2 分钟');
    }
    if (now - lastProgressTime > CHAT_IDLE_DEADLINE_MS) {
      throw new Error('无新进度超过 10 秒');
    }
  };
  
  const timer = setInterval(checkTimeout, 1000);
  
  try {
    const result = await callAI(messages);
    lastProgressTime = Date.now();
    return result;
  } finally {
    clearInterval(timer);
  }
}

4. 性能优化 --- 按需加载 Content Script

async function ensureContentScript(tabId) {
  try {
    await chrome.tabs.sendMessage(tabId, { action: 'ping' });
    return;  // 已注入
  } catch {
    await chrome.scripting.executeScript({
      target: { tabId },
      files: ['content.js']
    });
    await sleep(120);
  }
}

效果：减少不必要的内存占用（< 20MB）。

5. 处理不同网站的选择器差异

function generateSearchSelector(siteName) {
  const selectors = {
    'taobao.com': '#q',
    'jd.com': '#key',
    'tmall.com': '#mq',
    'pinduoduo.com': 'input[placeholder*="搜索"]'
  };
  
  for (const [domain, selector] of Object.entries(selectors)) {
    if (location.hostname.includes(domain)) {
      return selector;
    }
  }
  
  // 通用回退
  return 'input[type="text"][placeholder*="搜索"], input[name*="search"]';
}

6. 智能等待与点击

async function waitForElement(selector, timeout = 5000) {
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeout) {
    const el = document.querySelector(selector);
    if (el && el.offsetParent !== null) {
      return el;
    }
    await new Promise(r => setTimeout(r, 100));
  }
  
  throw new Error(`元素未找到：${selector}`);
}

async function clickWithScroll(selector) {
  const el = await waitForElement(selector);
  el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  await sleep(300);
  el.click();
}

7. 降低 API 成本

模型分级：

场景	推荐模型	参考价格
日常对话	glm-4-flash	0.1 元/百万 token
长文总结	qwen-plus	0.8 元/百万 token
深度分析	deepseek-chat	1 元/百万 token

优化上下文：

function trimMessages(messages, maxTokens = 4000) {
  let totalTokens = 0;
  const trimmed = [];
  
  for (let i = messages.length - 1; i >= 0; i--) {
    const msg = messages[i];
    const tokens = estimateTokens(msg.content);
    
    if (totalTokens + tokens > maxTokens) break;
    
    trimmed.unshift(msg);
    totalTokens += tokens;
  }
  
  return trimmed;
}

function estimateTokens(text) {
  const cnChars = (text.match(/[\u4e00-\u9fa5]/g) || []).length;
  const enWords = text.split(/\s+/).length - cnChars;
  return Math.ceil(cnChars * 1.5 + enWords * 0.25);
}

缓存常用查询：

const pageContentCache = new Map();

async function getPageContentCached(tabId) {
  const cacheKey = `${tabId}:${Date.now() / 60000 | 0}`;  // 1 分钟缓存
  
  if (pageContentCache.has(cacheKey)) {
    return pageContentCache.get(cacheKey);
  }
  
  const content = await getPageContent(tabId);
  pageContentCache.set(cacheKey, content);
  
  setTimeout(() => pageContentCache.delete(cacheKey), 60000);
  
  return content;
}

---

九、常见问题与解决

Q1: 提示「请先填写 API Key」

需要在选项页面配置至少一个平台的 API Key。点击侧边栏右上角的设置按钮跳转到选项页。

Q2: 提示「API Key 无效」或「HTTP 401」

可能原因：

• API Key 填写错误（检查是否完整复制）
• Key 已过期或被删除（到平台重新生成）
• 余额不足（到平台充值）
• 模型未开通（检查平台是否开通该模型的权限）

解决：在选项页点击「测试 Key」→ 查看错误信息 → 到平台检查 Key 状态。

Q3: 页面总结失败或返回空白

可能原因：

• 页面使用了复杂的 iframe 或动态加载
• 网站禁止脚本注入（如银行、支付类网站）
• 页面正文太短（少于 140 字符）

解决：等待完全加载 → 刷新页面 → 扩展会自动尝试滚动截图+视觉识别（需要智谱 API Key）。

Q4: 点击/填写操作失败

可能原因：

• 页面元素动态生成，选择器失效
• 网站结构更新，元素位置改变
• 页面有反爬虫机制

解决：先手动操作一次 → 更具体描述元素（如「点击红色的搜索按钮」）→ 尝试分步操作。

Q5: 侧边栏太窄/太宽

鼠标悬停在侧边栏左边缘，出现拖动光标时按住鼠标左键，左右拖动调整宽度（最小约 360px）。

Q6: Auto 模式如何选择模型？

场景	选择的模型	原因
短指令（如「打开淘宝」）	qwen-flash	快速响应
中等对话	qwen-flash 或 glm-4-flash	均衡
长文本（如「总结本页」）	qwen-plus	理解能力
深度分析	deepseek-chat	推理能力

你也可以手动切换到固定模型，避免自动选择。

Q7: 如何降低 API 费用？

• 使用 Auto 模式（自动选择最经济的模型）
• 日常对话选 GLM-4-Flash 或 qwen-flash（价格便宜）
• 避免频繁总结超长页面
• 清空不需要的对话历史（减少上下文 token）

Q8: 扩展会收集我的数据吗？

不会。

• API Key 仅保存在浏览器本地 chrome.storage.sync
• 不会上传到任何第三方服务器
• 唯一的网络请求是调用你配置的 AI 平台 API
• 页面内容仅在你主动要求总结时发送给 API

Q9: 提示「速率限制」或「429 错误」

API 调用频率超过限制。各平台有 RPM 和 TPM 限制。

• 等待 1-2 分钟后重试
• 减少并发请求
• 升级 API 套餐

Q10: 支持其他浏览器吗？

• ✅ Chrome（推荐，版本 ≥ 114）
• ✅ Edge（Chromium 版本）
• ✅ Brave、Vivaldi 等 Chromium 内核浏览器
• ❌ Firefox（不支持 Side Panel API）
• ❌ Safari（API 不兼容）

---

十、项目数据与成果

开发周期

2026-03-22 2026-03-23 2026-03-24 2026-03-25 2026-03-26 2026-03-27 2026-03-28 2026-03-29 2026-03-30 2026-03-31 2026-04-01 2026-04-02 2026-04-03 2026-04-04 2026-04-05 Side Panel API & Function Calling 基础功能 & 多平台支持 限流、视觉识别、错误处理 使用文档 & 技术文档 调研 核心开发 优化 文档 开发周期（共 14 天）

• 前期调研：2 天（调研 Side Panel API、Function Calling）
• 核心开发：7 天（实现基础功能和多平台支持）
• 优化迭代：3 天（限流、视觉识别、错误处理）
• 文档编写：2 天（完整的使用和技术文档）

代码统计

Language      Files    Lines    Code    Comments    Blanks
─────────────────────────────────────────────────────────
JavaScript       6     1,853    1,542      142        169
HTML             4       589      589        0          0
CSS              1       784      784        0          0
Markdown         4     1,520    1,520        0          0
JSON             1        38       38        0          0
─────────────────────────────────────────────────────────
Total           16     4,784    4,473      142        169

性能指标

95% 5% 关键性能指标 操作成功率 95%+ 失败/兜底 5%

指标	数值
响应时间	800ms - 3s（取决于模型和任务复杂度）
操作成功率	95%+（含视觉识别兜底）
限流错误率	< 1%（智能退避算法）
内存占用	< 20MB（按需注入 Content Script）

用户反馈

通过内测收集到的典型场景：

1. 电商比价 --- "在京东和淘宝同时搜索，比较价格"
2. 新闻摘要 --- "每天早上总结科技新闻"
3. 房产筛选 --- "按地铁线路和学区筛选房源"
4. 数据收集 --- "提取招聘网站的职位信息"

---

十一、未来规划

v2.3 短期 更多 AI 平台（Gemini、Claude） 历史对话管理（分组、搜索、导出） 快捷指令（预设常用操作） 多标签页协同 v3.0 中期 浏览器历史记录分析 网页监控提醒（价格降到 X 元通知） 视觉识别增强（图表、表格） 插件市场（社区贡献工具函数） 长期愿景 理解浏览习惯，主动推荐 跨网站数据整合分析 自动化操作流程编排 个人信息管理中心 产品路线图

短期计划（v2.3）

• 支持更多 AI 平台（Gemini、Claude）
• 历史对话管理（分组、搜索、导出）
• 快捷指令（预设常用操作）
• 多标签页协同（在多个页面间切换操作）

中期计划（v3.0）

• 浏览器历史记录分析（"我昨天看了什么新闻？"）
• 网页监控提醒（"价格降到 500 元时通知我"）
• 视觉识别增强（识别图表、表格）
• 插件市场（社区贡献工具函数）

长期愿景

打造一个真正的"浏览器级 AI 助手"：

• 理解你的浏览习惯，主动推荐内容
• 跨网站数据整合与分析
• 自动化常见的浏览器操作流程
• 成为你的个人信息管理中心

---

十二、开发感悟

1. API 设计的重要性

一个好的抽象层可以让代码更灵活。getProviderForModel 这个简单的函数，让扩展轻松支持了 4 个平台，未来添加新平台也只需几行配置。

2. 用户体验细节

• 实时进度反馈（不要让用户干等）
• 清晰的错误提示（不要只说"失败了"）
• 智能兜底策略（DOM 读取失败 → 视觉识别）
• 快捷操作（右键菜单、键盘快捷键）

3. 限流是真实存在的

不要忽视 API 限流问题。智能退避算法不仅提升了成功率，也让用户体验更稳定。

4. 文档的价值

完善的文档不仅帮助用户，也帮助自己回顾设计思路。这次项目，文档与代码同步更新，最终形成了完整的知识体系。

技术栈总结

技术	选择理由
Chrome Manifest V3	最新标准，长期支持
Side Panel API	侧边栏体验，类似 Cursor
Vanilla JavaScript	轻量，无框架依赖
Function Calling	实现真正的 AI Agent
chrome.storage.sync	跨设备同步配置
chrome.scripting	动态注入脚本

没有使用的技术（及原因）：

• ❌ React/Vue --- 对于这个项目来说过重
• ❌ Webpack/Vite --- 纯 JS 无需打包
• ❌ TypeScript --- 快速迭代阶段，类型检查不是首要

---

安全与隐私

数据安全

• ✅ API Key 本地存储 --- 仅保存在浏览器的 chrome.storage.sync
• ✅ 不上传第三方 --- 扩展不会将数据发送到任何第三方服务器
• ✅ HTTPS 加密 --- 所有 API 请求均通过 HTTPS 加密传输
• ⚠️ 页面内容处理 --- 当你要求总结页面时，页面内容会发送给对应的 AI 平台

权限说明

权限	用途
storage	保存 API Key、模型选择等配置
tabs	获取当前标签页信息、创建新标签页
activeTab	读取当前标签页的 URL 和标题
scripting	注入脚本以操作页面元素
sidePanel	显示侧边栏界面
<all_urls>	允许在所有网站上运行（用于页面操作）

敏感网站提示

以下类型网站不建议使用总结功能（可能涉及隐私）：银行/支付、邮箱/聊天记录、个人账户后台、内部办公系统。

---

开源与贡献

项目已开源，欢迎贡献：

• Gitee ：https://gitee.com/quyixiao/feifei/tree/master/zhipu-browser-assistant
• License：MIT
• 贡献指南 ：查看 CONTRIBUTING.md

如何参与？

1. 报告 Bug --- 提交详细的错误描述和复现步骤
2. 提出建议 --- 讨论新功能或改进点
3. 贡献代码 --- Fork → 修改 → Pull Request
4. 完善文档 --- 修正错误或补充示例
5. 分享经验 --- 写博客、制作视频教程

开发环境

git clone https://gitee.com/quyixiao/feifei.git
cd feifei/zhipu-browser-assistant
# 加载到 Chrome（参考「快速安装」章节）

修改代码后：在 chrome://extensions/ 点击「重新加载」→ 刷新侧边栏测试。

---

资源链接

官方文档

• Chrome Extensions 官方文档
• Side Panel API
• Scripting API

AI 平台

• 智谱 AI 开放平台
• 阿里云 DashScope
• DeepSeek 开放平台
• MiniMax 开放平台

项目文档

• 完全指南 --- 详细的使用手册
• 技术架构 --- 深入技术细节
• 故障排查 --- 常见问题解决
• 更新日志 --- 版本历史

---

结语

从零到一开发一个 AI 浏览器扩展，是一次非常有趣的经历。它不仅让我深入理解了 Chrome 扩展的开发，也对 AI Agent 的实现有了更直观的认识。

最让我兴奋的是看到 AI 真正"理解"了我的意图，并能自动执行复杂的操作。当我说"在淘宝搜索电动车，价格 2000-5000 元"，它能准确地打开网站、填写搜索框、筛选价格，这种体验是传统脚本无法比拟的。

如果你也对 AI + 浏览器自动化感兴趣，不妨动手试试。代码已开源在 Gitee，欢迎一起探索 AI Agent 的更多可能性！

---

感谢阅读！如果这篇文章对你有帮助，欢迎点赞、收藏、分享。

有任何问题或建议，欢迎在评论区讨论，或在 Gitee 仓库 提交 Issue。

---