DevHelper AI 助手能力检索与网页分析方案设计

归类：开发工具 / AI 插件

发生时间：2026-07-08

状态：✅ 已解决 | 📝 持续维护

---

一、 问题背景与现状

在 DevHelper 插件中，内置了“AI 智能分析面板”（如网速分析、诊断等）和“AI 助手”。但目前在实际交互中存在如下两个方面的感知盲区：

1. 工具能力感知盲区：用户直接询问“你有哪些已经实现的能力”时，大模型由于只拥有预训练知识，无法感知到 DevHelper 已经搭载了哪些已实现的工具集。
2. 网页分析盲区：用户要求 AI 分析当前网页的健康度、网络情况或提取特定内容时，AI 无法读取当前浏览器活跃标签页的运行时数据。

---

二、 业内的常见解决方案对比

业内外实现此类检索或查询通常有四种演进路径：

1. 静态上下文注入 (Static Context Injection)

   • 原理：在 AI 会话初始化时，将当前的工具列表（如 JSON 格式的 Schema）作为系统级上下文硬编码写入 System Prompt 中。
   • 优缺点：极其轻量，本地零延迟、零服务器成本，但受限于 LLM 上上文窗口，无法应对海量知识库。

2. 客户端工具调用 (Client-side Tools / Function Calling)

   • 原理：当 AI 发现需要调用某些特定能力或检索当前页面时，通过返回 tool_calls 发起函数回调。插件前端拦截并执行相应的 JS 脚本（如 chrome.tabs.query 读取 DOM，或调用其他检测工具），再将返回结果作为 tool 消息提供给 AI 发起第二轮生成。
   • 优缺点：完美支持动态交互，不消耗云端存储，但对大模型自身的 Tool Calling 稳定性有一定要求。

3. 向量检索增强生成 (RAG 架构)

   • 原理：将大型的参考文档、故障 FAQ 或 API 手册进行分片（Chunking），做向量化（Embedding）后存入向量数据库，问答时先进行相似度搜索，把最相关的片段拼入 Prompt 中。
   • 优缺点：适合海量、非结构化知识的精确问答，但需要额外部署向量库与计算服务。

4. 状态化协作 Agent (Stateful Agent Workflow)

   • 原理：构建常驻云端的 Agent 服务（如使用 Cloudflare Agents SDK），提供长连接、工作流编排和离线定时任务调度。
   • 优缺点：功能最为强大，可以实现后台定时监控和主动提醒，但架构相对最重。

---

三、 推荐的最佳实施路线

从轻量化、快速落地以及高扩展性出发，我们制定了三阶段演进方案：

🚀 第一阶段：Native Agent (本地 Function Calling 零成本快速落地)

• 工具感知：在 AI 助手初始化时将包含工具清单的静态 JSON Manifest 注入 System Prompt，使大模型天然具备功能轮廓认知。
• 网页抓取：在 AI 服务中支持 Tool Calling 并在底层拦截。注册一个 fetch_active_tab_context 的工具，当用户触发需要分析页面的指令时，AI 发出 Tool Call，插件底层通过 Chrome Extension API（chrome.tabs.query 和 chrome.scripting.executeScript）实时抓取当前活跃标签页的性能指标或 DOM 信息，返回给 AI 进行第二轮诊断。
• 架构特点：完全在本地客户端运行，服务器成本为零，交互响应极快。

☁️ 第二阶段：Cloudflare 轻量级 RAG 部署 (面向海量外部文档扩展)

当需要 AI 助手感知企业庞大的技术文档、开发规范或 GitHub 仓库代码时，利用 Cloudflare 边缘计算栈实现免费且极速的 RAG：

• 计算与网关：Cloudflare Workers。
• 向量库：Cloudflare Vectorize，支持高达几百万条向量免费存储。
• 数据库：Cloudflare D1 (Serverless SQLite)，存储用户会话历史。
• AI 推理：Cloudflare Workers AI 运行 bge-large 向量化模型及大模型，免去昂贵的 GPU 托管开销。
• 数据源同步：通过 GitHub Actions 在文档仓库 push 时自动触发 REST API 生成向量并推入 Vectorize，实现完全自动化。

🤖 第三阶段：基于 Cloudflare Agents SDK 的全功能协同 Agent

当需要 AI 支持“在后台每隔 5 分钟帮我监控某 IP，并在出现延迟抖动时主动通过邮件通知”等定时自动化任务时，可采用 Cloudflare Agents SDK 部署状态化 Agent，以获得原生 SQLite 状态持久化、scheduleEvery 任务调度及背景 Workflows 编排能力。

---

四、 阶段一 (Native Agent) 插件核心实现逻辑

要在 Chrome 插件底层实现自动化的多轮 Tool Calling 路由，其核心代码设计如下：

1. AI 服务层封装 (ai-service.js)

在 callOpenAI 请求体中注入 tools，并在 SSE 接收循环中识别并拼接 tool_calls。流式接收完成后，如果检测到 tool 调用，则自动通过 toolHandlers 执行本地工具并将结果追加到 message 数组中进行第二轮 AI 会话，从而对前端保持无缝流式返回：

// 支持 tools 的底层请求体
const body = {
  model: config.model,
  messages: [...],
  stream: true,
  tools: options.tools // 传入工具声明
};

// 并在流式结束后自动识别和执行：
if (accumulatedToolCalls.length > 0) {
  const toolMessages = [];
  for (const tc of accumulatedToolCalls) {
    const handler = toolHandlers[tc.function.name];
    const args = JSON.parse(tc.function.arguments || '{}');
    const result = await handler(args);
    toolMessages.push({
      role: 'tool',
      tool_call_id: tc.id,
      name: tc.function.name,
      content: JSON.stringify(result)
    });
  }
  // 携带 tool 执行结果发起第二轮请求
  return callOpenAIInternal(config, [...originalMessages, assistantMessage, ...toolMessages], onChunk);
}

2. Frontend 业务层绑定 (ai-assistant.js)

注册网页抓取 Handler，利用 Chrome API 动态注入脚本读取网页指标：

const handlers = {
  fetch_active_tab_context: async (args) => {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (!tab) return { error: 'No active tab found' };
    
    // 注入脚本以提取当前页面的核心 Timing 数据和主要文本
    const results = await chrome.scripting.executeScript({
      target: { tabId: tab.id },
      func: () => {
        return {
          title: document.title,
          url: window.location.href,
          performanceTiming: {
            navigationStart: performance.timing.navigationStart,
            domComplete: performance.timing.domComplete,
            loadEventEnd: performance.timing.loadEventEnd
          },
          bodyText: document.body.innerText.slice(0, 1000) // 限制长度
        };
      }
    });
    return results[0]?.result;
  }
};