AI Helper 文档中心

主题

内置工具集 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录：最佳实践与示例路径

引言 ​

本文件面向 AI Helper 扩展（Manifest V3，版本 2.3.1）的“内置工具集”，聚焦浏览器工具、内容提取工具、存储工具、标签页管理工具、调试工具、媒体工具与 AI 工具。文档从执行环境、参数契约、并行能力、确认机制、错误处理、分类体系与设计原则出发，给出可操作的调用模式与优化建议，帮助读者在页面交互、表单自动化、数据抓取和跨进程协作中稳定工作。

项目结构 ​

内置工具以“定义 + 执行”双层组织：

  • 定义层：按类别拆分到 background/tools/*.js，集中声明 id、category、execution、parallelizable、requiresConfirmation、function.name/description/parameters。
  • 执行层：background/tool-executor.js 负责注册、调度、参数校验、确认弹窗、截图、Agent 通信、MCP/RAG 动态注入等；content/* 提供页面侧 DOM 操作与提取实现。
graph TB
subgraph "Background 服务"
C["constants.js<br/>工具定义聚合与元数据"]
E["tool-executor.js<br/>工具注册/调度/确认/截图/MCP/RAG"]
BT["browser-tools.js"]
ST["storage-tools.js"]
TT["tab-tools.js"]
MT["media-tools.js"]
AT["ai-tools.js"]
AGT["agent-tools.js"]
MEM["memory-tools.js"]
DBG["debugger-tools.js"]
end
subgraph "Content Script"
PI["page-interaction.js<br/>元素快照/ref/滚动收集"]
PE["page-extract.js<br/>元数据/链接/表单/图片/搜索/iframe"]
end
C --> E
BT --> C
ST --> C
TT --> C
MT --> C
AT --> C
AGT --> C
MEM --> C
DBG --> C
E --> PI
E --> PE

图表来源

章节来源

核心组件 ​

  • 工具定义聚合：background/constants.js 汇总各模块导出，生成 RAW_TOOLS、BUILTIN_TOOLS、CATEGORY_ORDER、TOOL_EXECUTION_MAP、PARALLELIZABLE_TOOLS、CONFIRMATION_REQUIRED_TOOLS 等单一数据源映射。
  • 工具执行器：background/tool-executor.js 解析参数、路由到 content_script 或 background 处理器，处理确认弹窗、超时、截图、Agent 命令、MCP/RAG 动态注入等。
  • 页面交互与提取：content/page-interaction.js 提供 query_elements、interact_element、scroll_collect 等；content/page-extract.js 提供 page_content、extract_data、search_in_page、iframe_content 等。

章节来源

架构总览 ​

工具调用通常经历以下阶段：

  1. LLM 选择工具并传入参数。
  2. tool-executor.js 校验参数、判断是否需要用户确认。
  3. 根据 execution 字段分发到 content_script 或 background 处理器。
  4. content_script 执行 DOM 操作或提取；background 执行浏览器 API、网络请求、截图、Agent 命令等。
  5. 结果回传，必要时触发截图下载、通知或流式输出。
sequenceDiagram
participant LLM as "大模型"
participant Exec as "tool-executor.js"
participant CS as "content_script"
participant BG as "background"
participant Agent as "本地代理"
LLM->>Exec : 调用工具(名称+参数)
Exec->>Exec : 参数校验/确认检查
alt 需要确认
Exec-->>LLM : 弹出确认/澄清
LLM-->>Exec : 用户决策
end
alt execution=content_script
Exec->>CS : 执行页面交互/提取
CS-->>Exec : 返回结构化结果
else execution=background
Exec->>BG : 执行浏览器API/网络/截图/Agent
BG-->>Exec : 返回结果
opt 需要访问本地代理
BG->>Agent : 文件/命令/记忆/RAG
Agent-->>BG : 返回结果
end
end
Exec-->>LLM : 最终结果/截图/通知

图表来源

详细组件分析 ​

浏览器工具（页面交互、表单、内容提取） ​

覆盖 interact_element、scroll_to、wait_element、fill_form、keyboard_input、file_upload、select_dropdown、page_content、extract_data、query_elements、search_in_page、iframe_content、scroll_collect。

  • 执行环境
    • content_script：interact_element、scroll_to、wait_element、fill_form、keyboard_input、file_upload、select_dropdown、search_in_page、iframe_content、scroll_collect。
    • background：page_content、extract_data、query_elements。
  • 并行能力
    • page_content、extract_data、query_elements、search_in_page、iframe_content 标记为可并行。
  • 定位策略
    • 优先使用 query_elements 返回的 ref 编号进行 interact_element/fill_form/select_dropdown，避免脆弱 CSS selector。
    • 当 ref 失效时，会尝试基于缓存 selector 重查，失败则提示重新查询。
  • 表单自动化
    • fill_form 批量填写，支持 text/select/checkbox/radio/contenteditable。
    • keyboard_input 绕过 React/Vue 受控组件，适合单字段输入或快捷键。
    • file_upload 通过 DataTransfer 注入文件。
    • select_dropdown 兼容原生 select 与自定义下拉。
  • 内容提取
    • page_content 获取文本或 HTML，支持 selector 与长度限制。
    • extract_data 结构化提取 table/metadata/links/forms/images。
    • query_elements 返回树形快照，包含可见 iframe 子帧与打开的弹层。
    • search_in_page 支持 plain/regex、大小写敏感、上下文片段与高亮。
    • iframe_content 仅同源可读取，支持嵌套。
    • scroll_collect 滚动收集长内容，去重拼接。
flowchart TD
Start(["开始"]) --> Choose["选择工具类型"]
Choose --> |页面交互| IE["interact_element<br/>ref/text/selector"]
Choose --> |表单| FF["fill_form / keyboard_input<br/>file_upload / select_dropdown"]
Choose --> |内容提取| PQ["query_elements / page_content<br/>extract_data / search_in_page<br/>iframe_content / scroll_collect"]
IE --> RefCheck{"ref 是否有效?"}
RefCheck --> |是| DoAction["点击/悬停/输入"]
RefCheck --> |否| Fallback["用缓存 selector 重试"]
Fallback --> ActionDone["完成"]
DoAction --> ActionDone
FF --> DoneFF["完成"]
PQ --> DonePQ["完成"]

图表来源

章节来源

存储工具 ​

  • manage_storage：读写 localStorage/sessionStorage，clear 需确认。
  • manage_cookies：CRUD 与按域名清除 Cookie，requiresConfirmation=true。
  • fetch_url：HTTP GET/POST，仅允许 http/https，内网地址需用户明确授权白名单。
flowchart TD
SStart["manage_storage/manage_cookies/fetch_url"] --> CheckScope{"是否涉及敏感操作?"}
CheckScope --> |是| Confirm["用户确认"]
CheckScope --> |否| Proceed["直接执行"]
Confirm --> Proceed
Proceed --> Result["返回结果/错误"]

图表来源

章节来源

标签页管理工具 ​

  • manage_tab：open/switch/close/reload/navigate，close 需确认。
  • list_tabs：all/active 模式，可选 includeUrl/includeTitle。
  • search_browser_data：书签/历史搜索。

章节来源

调试工具（DevTools Protocol） ​

  • debug_page：attach/detach/evaluate/input/network/screenshot/emulate。
  • 设计原则：仅在常规工具无法满足时使用（如原生事件、抓包、最早时机 JS、全屏截图、设备模拟）。
  • attach 需要用户确认，并在标签页显示黄色调试栏，完成后应 detach。

章节来源

媒体工具 ​

  • notify：桌面通知，支持声音类型。
  • clipboard：copy/paste/get_selected。
  • download_file：下载文件，requiresConfirmation=true。
  • qrcode：生成二维码。
  • capture_page：download/analyze/both，支持视觉模型分析。

章节来源

AI 工具 ​

  • clarify_question：向用户提问并暂停执行直到响应。
  • plan_task：复杂任务拆解，支持 sequential/parallel/dependency 策略与失败策略、并发上限、重试次数。
  • search_chats：对话历史检索。
  • preview_ui：预览/加载 UI 原型。
  • dispatch_task：派发子任务给子代理。
  • doneCriteria：plan_task 的子任务达标断言 schema，由 completion verification 控制动态注入。

章节来源

本地代理工具 ​

  • agent_file：read/write/list/delete/download。
  • agent_trash：list/restore。
  • agent_exec：shell 命令执行，带超时与多端安全约束。
  • agent_search：file/content 搜索。
  • agent_skill：load/run Skill。
  • manage_agent：list/switch 已配对代理。
  • exec_log：提取历史执行日志。
  • take_note：记录短期工作笔记。

章节来源

长期记忆工具 ​

  • agent_memory：store/recall/manage，支持 fact/summary、importance 范围、tags 过滤、limit 等。

章节来源

依赖关系分析 ​

  • 工具定义聚合：background/constants.js 导入 browser-tools、tab-tools、storage-tools、media-tools、ai-tools、agent-tools、memory-tools、debugger-tools，合并为 RAW_TOOLS，并派生 BUILTIN_TOOLS、CATEGORY_ORDER、TOOL_EXECUTION_MAP、PARALLELIZABLE_TOOLS、CONFIRMATION_REQUIRED_TOOLS、CONFIRMATION_ACTION_MAP、BUILTIN_TOOLS_UI。
  • 执行器依赖：tool-executor.js 依赖 constants.js 提供的元数据，同时依赖 local-agent-client、stream-controller、tool-screenshot、tool-memory、tool-debugger、notifier、react-loop、snapshot-orchestrator 等。
  • 页面侧依赖：content/page-interaction.js 与 content/page-extract.js 被 background 工具在执行期调用。
graph LR
CT["constants.js<br/>RAW_TOOLS/CATEGORY_ORDER/..."] --> EX["tool-executor.js<br/>注册/调度/确认/截图/MCP/RAG"]
BT["browser-tools.js"] --> CT
ST["storage-tools.js"] --> CT
TT["tab-tools.js"] --> CT
MT["media-tools.js"] --> CT
AT["ai-tools.js"] --> CT
AGT["agent-tools.js"] --> CT
MEM["memory-tools.js"] --> CT
DBG["debugger-tools.js"] --> CT
EX --> PI["page-interaction.js"]
EX --> PE["page-extract.js"]

图表来源

章节来源

性能考虑 ​

  • 优先使用 query_elements 的 ref 定位，减少 CSS selector 复杂度与匹配成本。
  • 对长列表/无限滚动使用 scroll_collect，合理设置 maxScrolls 与 pauseMs，避免频繁滚动导致卡顿。
  • 并行工具（page_content、extract_data、query_elements、search_in_page、iframe_content）可在同一轮中并发调用，但注意目标页面状态一致性。
  • 控制 page_content/extract_data 的输出规模（maxLength、maxResults），避免过大结果影响上下文预算。
  • 截图 analyze 模式有额外视觉模型开销，按需启用 visionMaxDim/visionQuality。
  • 使用 wait_navigation/wait_element 等待关键状态后再继续，减少无效重试。
  • 对耗时较长的 Agent 命令，合理设置 timeoutMs，避免长时间占用资源。

[本节为通用指导，不直接分析具体文件]

故障排查指南 ​

  • 未知工具/未知 action：检查工具定义与参数枚举是否匹配。
  • 标签页不可用：确认 tabId 是否存在且可访问；系统页面不允许使用工具。
  • Content Script 注入失败：检查页面是否允许注入，或目标是否为错误页。
  • 内网地址访问被拒：fetch_url 与 manage_tab(open) 均受内网访问策略限制，需在扩展设置开启“内网地址访问”并将主机加入允许列表。
  • 用户未确认：requiresConfirmation 或 confirmationActions 触发的操作需用户确认，否则中止。
  • 导航/DOM 变化导致 ref 失效：重新调用 query_elements 获取最新快照。
  • 截图分析失败：检查视觉模型 API 配置与可用性。
  • 命令执行超时/无 exitCode：查看命令输出与退出码，必要时缩短命令或调整超时。

章节来源

结论 ​

内置工具集以清晰的分类与统一的定义-执行分离架构，提供了从页面交互、表单自动化、内容提取到存储、标签页、媒体、AI 协作与本地代理的全链路能力。通过 ref 定位、并行化、确认机制与安全边界，既提升了自动化效率，也保障了安全性与稳定性。建议在复杂任务中使用 plan_task 分解步骤，结合 query_elements 与 scroll_collect 提升鲁棒性，并通过截图与日志辅助排障。

[本节为总结性内容，不直接分析具体文件]

附录：最佳实践与示例路径 ​

章节来源