AI Helper 文档中心

主题

内置工具注册机制 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与扩展性
  8. 故障排查指南
  9. 结论

引言 ​

本文面向“内置工具注册机制”，系统性说明以下主题：

  • BUILTIN_TOOLS 数组的结构定义，包括工具 ID、名称、分类、描述和参数 schema。
  • 工具分类体系 CATEGORY_ORDER 的组织逻辑，以及浏览器工具、存储工具、标签页管理等分类的语义划分。
  • 工具权限控制机制：Agent 工具限制、安全分级、用户确认流程。
  • 工具启用状态管理：enabledTools 的持久化存储与状态同步。
  • 如何添加新内置工具，以及如何定义参数验证规则和处理执行结果。
  • 工具预筛选机制：意图识别、工具选择优化策略与降级路径。

本项目的扩展端采用 Manifest V3 双进程架构，工具定义集中在 background 侧，并通过 side panel 暴露给用户进行启用/禁用配置；Agent 端通过本地 HTTP/WebSocket 接口提供文件、命令、记忆与 RAG 能力，但 Agent 端源码修改后必须重启进程才生效。

项目结构 ​

内置工具注册相关代码主要分布在 background 与 side panel 两个区域：

  • background 层负责工具定义聚合、类别映射、执行调度、权限校验与预筛选。
  • side panel 层负责展示工具分类、维护 enabledTools 并持久化到 chrome.storage.local。
graph TB
subgraph "Background 服务"
C["constants.js<br/>工具定义聚合与类别映射"]
BT["browser-tools.js<br/>页面交互/表单/内容提取"]
ST["storage-tools.js<br/>存储/网络请求"]
TT["tab-tools.js<br/>标签页/书签历史"]
AT["agent-tools.js<br/>本地 Agent 工具"]
TE["tool-executor.js<br/>工具执行与安全门控"]
RL["react-loop.js<br/>ReAct 循环与用户确认"]
PS["tool-preselector.js<br/>工具预筛选"]
BI["background/index.js<br/>主入口与预筛选集成"]
end
subgraph "Side Panel 界面"
TP["tool-panel.js<br/>分类渲染与全选/折叠"]
AM["agent-manager.js<br/>enabledTools 初始化与持久化"]
end
C --> BT
C --> ST
C --> TT
C --> AT
C --> TE
C --> RL
C --> PS
BI --> PS
TP --> AM

图表来源

章节来源

核心组件 ​

本节聚焦内置工具注册的核心数据结构与派生映射表：

  • RAW_TOOLS：按类别导入各 tools 模块，合并为统一工具清单。
  • BUILTIN_TOOLS：由 RAW_TOOLS 派生，供外部模型或调用方使用，包含 id、type、function。
  • TOOL_CATEGORY_MAP：工具 ID 到 category 的映射。
  • TOOL_EXECUTION_MAP：工具 ID 到 execution（content_script/background）的映射。
  • PARALLELIZABLE_TOOLS：可并行执行的工具集合。
  • CONFIRMATION_REQUIRED_TOOLS：需要用户确认的工具集合。
  • CONFIRMATION_ACTION_MAP：工具级 action 级别确认映射，例如 manage_tab 的 close 动作。
  • BUILTIN_TOOLS_UI：用于 UI 展示的工具元数据，包含 id、name、description、category、execution、parallelizable、requiresConfirmation、enabled。
  • CATEGORY_WEIGHT 与 CATEGORY_ORDER：类别权重与排序后的分类列表。

这些结构共同构成“单一数据源”：新增工具只需在对应 tools 文件中声明，即可自动进入聚合、UI 展示、权限判断与预筛选等所有环节。

章节来源

架构总览 ​

下图展示从工具定义到执行与用户确认的关键链路：

sequenceDiagram
participant User as "用户"
participant Panel as "Side Panel"
participant BG as "Background"
participant Pre as "ToolPreselector"
participant Exec as "ToolExecutor"
participant Loop as "ReactLoop"
participant Model as "大模型"
User->>Panel : 打开工具面板
Panel->>BG : 读取/保存 enabledTools
BG-->>Panel : 返回已启用工具列表
User->>BG : 发送任务消息
BG->>Pre : preselectTools(可选)
Pre-->>BG : 返回筛选后的工具或直接回答
BG->>Model : 带工具定义的函数调用
Model-->>BG : 返回 tool_calls
BG->>Exec : 分发工具执行
Exec->>Loop : 敏感操作需确认时触发
Loop->>Panel : 弹出确认对话框
Panel-->>Loop : 用户确认/拒绝
Loop-->>Exec : 继续或取消
Exec-->>BG : 返回执行结果
BG-->>User : 输出最终结果

图表来源

详细组件分析 ​

工具定义结构与 BUILTIN_TOOLS 生成 ​

每个工具定义对象包含以下关键字段：

  • id：工具唯一标识。
  • category：分类键，如 page_interaction、form_operation、content_extraction、tab_management、bookmark_history、storage_management、network_request、media_output、debug_dev、ai_collaboration、local_agent、mcp、knowledge。
  • execution：执行环境，content_script 或 background。
  • parallelizable：是否允许并行执行。
  • requiresConfirmation：是否需要用户确认。
  • confirmationActions：特定 action 级别的确认白名单，例如 manage_tab.close、manage_storage.clear、agent_file.delete。
  • type：通常为 function。
  • function.name：对外暴露给模型的函数名。
  • function.description：对模型的解释文本。
  • function.parameters：JSON Schema 风格的参数定义，包含 type、properties、required、enum、description 等。

BUILTIN_TOOLS 由 RAW_TOOLS 映射生成，仅保留 id、type、function，便于直接作为模型可用的工具定义。BUILTIN_TOOLS_UI 则补充 UI 所需字段，如 name、description、category、execution、parallelizable、requiresConfirmation、enabled。

示例参考路径：

章节来源

工具分类体系 CATEGORY_ORDER ​

CATEGORY_WEIGHT 定义了各类别的显示顺序权重，数字越小越靠前。CATEGORY_ORDER 从 RAW_TOOLS 动态派生，去重并按权重排序，从而保证分类顺序稳定且无需手动维护。

分类语义说明：

  • page_interaction：页面元素交互、滚动等待、对话框处理。
  • form_operation：表单填写、键盘输入、文件上传、下拉选择。
  • content_extraction：页面内容获取、结构化数据提取、元素查询、页面搜索、iframe 内容、无限滚动采集。
  • tab_management：标签页打开、切换、关闭、刷新、历史前进后退。
  • bookmark_history：书签与浏览历史搜索。
  • storage_management：localStorage/sessionStorage 读写、Cookie 管理。
  • network_request：HTTP GET/POST 请求。
  • media_output：媒体与输出类工具（由 media-tools.js 提供）。
  • debug_dev：调试与开发工具（由 debugger-tools.js 提供）。
  • ai_collaboration：AI 协作工具，如 clarify_question、plan_task、take_note 等。
  • local_agent：本地 Agent 工具，如 agent_file、agent_trash、agent_exec、agent_search、agent_skill 等。
  • mcp：MCP 协议动态扩展工具。
  • knowledge：知识库检索工具（由 memory-tools.js 提供）。

UI 文案通过 i18n 的 toolCategory 映射显示，避免硬编码中文。

章节来源

工具权限控制机制 ​

权限控制分为三层：

  1. 工具级 requiresConfirmation：标记该工具整体需要用户确认。
  2. action 级 confirmationActions：针对某个工具的特定 action 要求确认，例如 manage_tab.close、manage_storage.clear、agent_file.delete。
  3. Agent 命令安全分级：agent_exec 走灰名单/黑名单机制，结合 reactConfig.toolConfirmationEnabled 开关决定是否需要真实用户确认弹窗。

关键行为：

  • react-loop 在执行 tool_calls 前检查 CONFIRMATION_REQUIRED_TOOLS 与 CONFIRMATION_ACTION_MAP，若命中且总开关开启，则调用 requestToolConfirmation 弹出确认框。
  • 确认框使用 correlationId 与 sessionId 做唯一关联，避免并行子任务串扰。
  • 确认超时默认 5 分钟，fail-closed：未确认即视为拒绝。
  • Agent 命令中，force 参数不可信，仅在用户点击确认后由扩展端补发；黑名单始终不可绕过。
flowchart TD
Start(["收到 tool_calls"]) --> CheckTool["检查工具级 requiresConfirmation"]
CheckTool --> |是| CheckAction["检查 action 级 confirmationActions"]
CheckTool --> |否| CheckSwitch["检查 reactConfig.toolConfirmationEnabled"]
CheckAction --> CheckSwitch
CheckSwitch --> |关闭| Execute["直接执行"]
CheckSwitch --> |开启| Confirm["弹出用户确认框"]
Confirm --> Confirmed{"用户确认?"}
Confirmed --> |是| Execute
Confirmed --> |否| Cancel["记录 cancelled 并返回错误"]

图表来源

章节来源

工具启用状态管理 enabledTools ​

enabledTools 的持久化与同步流程：

  • 首次加载或配置缺失时，默认启用全部内置工具。
  • 若存在已保存的 enabledTools，则优先使用；空数组表示用户显式“全部禁用”。
  • 对于 Agent 专用工具，使用 agent-specific key 存储；全局降级时保留自动添加新 builtin 的行为。
  • RAG 知识库工具首次引入时默认启用，之后完全跟随用户勾选。
  • Side Panel 工具面板按分类渲染，支持折叠、全选、计数显示。
sequenceDiagram
participant AM as "agent-manager.js"
participant Storage as "chrome.storage.local"
participant Panel as "tool-panel.js"
AM->>Storage : 读取 enabledTools
alt 存在 Agent 专用 key
Storage-->>AM : 返回 agent-specific enabledTools
else 全局降级
Storage-->>AM : 返回旧 enabledTools
end
AM->>AM : 补齐新内置工具 / 引入 RAG 工具
AM->>Storage : 保存 enabledTools
AM->>Panel : 通知刷新工具面板
Panel->>Panel : 按 CATEGORY_ORDER 渲染分类与工具项

图表来源

章节来源

工具预筛选机制 ​

预筛选的目标是在工具数量较多时减少传递给模型的 tool definitions，降低 token 消耗并提高响应质量。

核心逻辑：

  • 当工具总数超过 PRESELECT_MIN_TOOL_COUNT（固定阈值 10）时启动预筛选。
  • 提取最后一条用户问题与最近对话历史，构建系统提示词，让模型判断是直接回答还是选择工具。
  • 解析模型返回：优先 JSON 格式 {type, data}，兜底旧格式提取工具数组。
  • 若模型返回空工具集或无法匹配，回退到全量工具。
  • 强制保留 mustKeepToolIds（如用户通过 / 手动指定的 MCP 服务工具），防止预筛选丢弃。
  • 预筛选日志通过 STREAM_PRESELECT 发送到 Side Panel，便于流式输出过程中观察。
flowchart TD
Start(["preselectTools 入口"]) --> CountCheck{"工具数 <= 阈值?"}
CountCheck --> |是| ReturnAll["返回全部工具"]
CountCheck --> |否| ExtractQuestion["提取最后一条用户问题"]
ExtractQuestion --> HasQuestion{"是否成功提取?"}
HasQuestion --> |否| ReturnAll
HasQuestion --> |是| BuildPrompt["构建预筛选提示词"]
BuildPrompt --> CallModel["调用模型 API"]
CallModel --> ParseResult["解析返回 JSON 或兜底提取"]
ParseResult --> TypeAnswer{"type=answer?"}
TypeAnswer --> |是| ReturnAnswer["返回直接回答"]
TypeAnswer --> |否| FilterTools["按工具名过滤"]
FilterTools --> ForceKeep["强制保留 mustKeepToolIds"]
ForceKeep --> EmptyCheck{"筛选结果为空?"}
EmptyCheck --> |是| ReturnAll
EmptyCheck --> |否| ReturnFiltered["返回筛选后的工具"]

图表来源

章节来源

如何添加新的内置工具 ​

步骤建议：

  1. 在合适的 tools 文件中新增工具定义对象，确保 id、category、execution、parallelizable、requiresConfirmation、confirmationActions、type、function.name、function.description、function.parameters 完整。
  2. 如果新增分类，需在 constants.js 的 CATEGORY_WEIGHT 中添加权重，CATEGORY_ORDER 会自动排序。
  3. 如需将该工具纳入 UI 展示，确保其出现在 RAW_TOOLS 聚合中；BUILTIN_TOOLS_UI 会自动派生。
  4. 如需用户确认，设置 requiresConfirmation 或在 confirmationActions 中列出特定 action。
  5. 如需 Agent 工具，注意 agent_exec 的安全语义：force 不向模型暴露，灰名单命令需真实用户确认。
  6. 运行单元测试验证工具定义聚合与 schema 合规性。

参考路径：

章节来源

工具参数验证规则与执行结果处理 ​

参数验证基于 JSON Schema 风格：

  • properties：参数对象属性定义。
  • required：必填参数数组。
  • enum：枚举值约束。
  • description：参数说明，帮助模型理解。
  • type：基础类型 string、integer、boolean、array、object。

执行结果处理：

  • 普通工具：tool-executor 根据 execution 环境分发执行，返回标准结果。
  • 敏感工具：react-loop 在需要确认时暂停循环计时，弹出确认框；用户拒绝则记录 cancelled 并返回错误。
  • Agent 命令：executeAgentExecCommand 处理黑名单拦截、灰名单确认与普通命令执行；force 仅由用户确认后授予。

参考路径：

章节来源

依赖关系分析 ​

工具注册机制的关键依赖如下：

  • constants.js 聚合各 tools 模块，导出 RAW_TOOLS、BUILTIN_TOOLS、TOOL_CATEGORY_MAP、TOOL_EXECUTION_MAP、PARALLELIZABLE_TOOLS、CONFIRMATION_REQUIRED_TOOLS、CONFIRMATION_ACTION_MAP、BUILTIN_TOOLS_UI、CATEGORY_ORDER。
  • tool-executor.js 消费 enabledTools 配置，并在执行 Agent 命令时应用安全分级。
  • react-loop.js 消费 CONFIRMATION_REQUIRED_TOOLS 与 CONFIRMATION_ACTION_MAP，实现用户确认流程。
  • tool-preselector.js 消费 PRESELECT_MIN_TOOL_COUNT 与工具列表，实现预筛选。
  • side panel 的 tool-panel.js 与 agent-manager.js 消费 CATEGORY_ORDER 与 BUILTIN_TOOLS_UI，完成 UI 渲染与状态持久化。
graph LR
Constants["constants.js"] --> Executor["tool-executor.js"]
Constants --> ReactLoop["react-loop.js"]
Constants --> Preselector["tool-preselector.js"]
Constants --> Panel["tool-panel.js"]
Constants --> AgentMgr["agent-manager.js"]
Index["background/index.js"] --> Preselector

图表来源

章节来源

性能与扩展性 ​

  • 预筛选阈值固定为 10，避免过多工具导致 prompt 膨胀；当工具数较少时直接跳过预筛选。
  • 预筛选失败或模型返回异常时，回退到全量工具，保证功能可用性。
  • 工具定义集中管理，新增工具无需改动多处逻辑，降低维护成本。
  • UI 分类渲染与计数逻辑与 CATEGORY_ORDER 联动，新增分类自动排序。
  • Agent 命令执行具备超时与取消机制，避免长时间阻塞。

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

故障排查指南 ​

常见问题与建议：

  • 工具未显示：检查是否在 RAW_TOOLS 聚合中；确认 category 已在 CATEGORY_WEIGHT 中定义。
  • 工具未被启用：检查 chrome.storage.local 中的 enabledTools；确认 agent-manager.js 的初始化逻辑是否正确补齐新工具。
  • 敏感操作未弹确认：检查 requiresConfirmation 或 confirmationActions；确认 reactConfig.toolConfirmationEnabled 开关状态。
  • Agent 命令被拒绝：检查黑名单/灰名单规则；确认 force 是否由用户确认后授予。
  • 预筛选无效：检查工具总数是否超过阈值；查看预筛选日志 STREAM_PRESELECT；确认模型返回是否可解析。

参考路径：

章节来源

结论 ​

内置工具注册机制以 constants.js 为核心，通过 RAW_TOOLS 聚合各 tools 模块，派生出 BUILTIN_TOOLS、分类映射、权限集合与 UI 元数据。CATEGORY_ORDER 提供稳定的分类顺序，side panel 据此渲染工具面板并持久化 enabledTools。权限控制通过工具级与 action 级确认、Agent 命令安全分级与用户确认流程共同保障安全性。预筛选机制在工具数量较多时优化模型输入，同时提供健壮的回退策略。整体设计强调单一数据源、可扩展性与安全性，便于后续新增工具与维护。

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