AI Helper 文档中心

主题

工具面板集成 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与扩展性
  8. 故障排查指南
  9. 结论
  10. 附录：新增工具类别与权限控制示例

引言 ​

本文件面向“工具面板集成”的完整技术文档，覆盖以下目标：

  • 工具面板整体架构、工具分类、动态加载与状态管理。
  • 内置工具的注册机制、定义格式、参数验证与执行框架。
  • MCP 工具集成：远程工具发现、协议适配、错误处理与服务级开关。
  • RAG 知识库配置界面：知识库选择、检索参数调整与结果预览。
  • Skill 技能系统的面板集成：列表展示、执行控制与结果输出。
  • 工具权限控制：安全检查与用户确认流程。
  • 工具配置的持久化存储与版本迁移策略。

本项目采用双进程架构：Chrome 扩展端（Manifest V3）与独立本地代理端 Agent（Node.js）。两端通过本地 HTTP/WebSocket 通信；Agent 源码修改后必须重启进程，新接口才生效。

项目结构 ​

工具面板相关代码分布在三个层次：

  • 侧边栏 UI：工具弹窗、分类筛选、MCP/RAG/Skill 入口。
  • 选项页工具箱：MCP 服务器管理、Skill 管理、RAG 能力探测与安装引导、知识库管理。
  • Background 执行层：工具定义、动态注册、执行调度与安全校验。
  • Agent 服务端：MCP 注册表、Skill 加载器、RAG 能力检测与索引。
graph TB
subgraph "扩展端"
SP["侧边栏<br/>tool-panel.js"]
OPT["选项页工具箱<br/>toolbox-config.js / toolbox-mcp.js / toolbox-skills.js / toolbox-rag.js"]
KB["知识库面板<br/>knowledge-panel.js"]
BG["Background 执行层<br/>tool-executor.js / rag-tools.js"]
end
subgraph "Agent 端"
MCP["MCP 注册表<br/>registry.js"]
SKILL["Skill 加载器<br/>loader.js"]
RAG["RAG 能力与索引"]
end
SP --> BG
OPT --> BG
KB --> BG
BG --> MCP
BG --> SKILL
BG --> RAG

图表来源

章节来源

核心组件 ​

  • 工具面板（Side Panel）：负责工具弹窗渲染、分类筛选、搜索、MCP 服务分组、RAG 工具缓存、全局开关与 Agent 连接状态感知。
  • 选项页工具箱：统一入口，聚合 MCP 服务器管理、Skill 管理与 RAG 能力探测；提供全局开关与统计计数。
  • Background 执行层：集中维护工具定义、动态注册（MCP/RAG）、执行映射、并行与确认标记、安全校验与审计。
  • Agent 服务端：MCP 注册表管理多客户端连接与工具调用；Skill 加载器扫描并校验 Workflow/Agent 技能；RAG 能力检测与安装引导。

关键职责边界：

  • 侧边栏仅做展示与轻量交互，不直接执行业务逻辑。
  • 选项页负责配置与远端 API 调用，Background 负责工具注册与执行。
  • Agent 端暴露 REST 接口，供扩展端查询与操作。

章节来源

架构总览 ​

下图展示从用户操作到工具执行的端到端流程，包括 MCP 工具动态注册与 RAG 工具条件注册。

sequenceDiagram
participant User as "用户"
participant SP as "侧边栏 tool-panel.js"
participant BG as "Background tool-executor.js"
participant AG as "Agent registry.js / loader.js"
participant EXT as "chrome.storage.local"
User->>SP : 打开工具弹窗
SP->>EXT : 读取 mcpTools / ragTools / 全局开关
SP->>BG : 发送 GET_MCP_TOOLS优先
BG-->>SP : 返回工具列表或失败
SP->>SP : 渲染分类、MCP 服务分组、RAG 工具缓存
User->>SP : 勾选工具 / 切换 MCP 服务
SP->>EXT : 更新 enabledTools / mcpClosedServers
User->>BG : 触发工具执行由 ReAct 循环调用
BG->>AG : 调用 MCP 工具或 RAG 接口
AG-->>BG : 返回执行结果
BG-->>User : 写入会话消息与审计日志

图表来源

详细组件分析 ​

工具面板（Side Panel） ​

  • 工具分类与排序：使用 CATEGORY_ORDER 与 BUILTIN_TOOLS 快照，补充 'mcp' 与 'knowledge' 动态分类。
  • 动态加载：
    • MCP 工具：优先从 Background 获取，否则回退 chrome.storage.local.mcpTools。
    • RAG 工具：从 storage.ragTools 同步，由 Background 在注册/卸载时更新。
  • 状态管理：
    • 全局开关：mcpEnabled、skillsEnabled。
    • 工具启用：state.enabledTools。
    • MCP 服务关闭列表：state.mcpClosedServers。
    • 助手排除列表：activeAgentMcpExcludedServerIds。
  • 交互：
    • 分类折叠、全选/取消全选、搜索过滤。
    • MCP 服务行展开只读工具列表。
    • 预筛选与敏感操作确认开关状态实时同步。
flowchart TD
Start(["打开工具弹窗"]) --> Load["加载 MCP/RAG 缓存与全局开关"]
Load --> Render["按分类渲染工具与 MCP 服务"]
Render --> Filter{"分类/搜索匹配？"}
Filter --> |否| Empty["显示无匹配提示"]
Filter --> |是| Toggle["勾选/取消勾选工具"]
Toggle --> Update["更新 state.enabledTools 与分类计数"]
Update --> Badge["刷新角标与标题计数"]
Badge --> End(["完成"])

图表来源

章节来源

选项页工具箱（Options Toolbox） ​

  • 统一入口：refreshToolbox 并行加载 MCP 与 Skill，渲染列表并更新统计。
  • MCP 管理：
    • 增删改查、连接/断开、启用/禁用、环境变量与请求头编辑。
    • 传输方式支持 stdio、SSE、Streamable HTTP、WebSocket。
    • 添加/编辑成功后通知 Background 重新加载 MCP 工具。
  • Skill 管理：
    • 列表展示（Workflow/Agent），启用/停用、删除、运行、导入（JSON/Markdown/Zip/URL）。
    • 参数解析与输入弹窗，执行结果分步展示。
  • RAG 能力探测：
    • 读取 /api/status 的 ragAvailable 与 nodeVersion。
    • 未就绪时展示安装引导与进度轮询，完成后通知 Background 重新注册 RAG 工具。
classDiagram
class ToolboxConfig {
+refreshToolbox()
+initToolbox()
-notifyMcpChange()
-updateMcpToolCount(servers)
-updateSkillCount(skills)
}
class ToolboxMcp {
+loadMcpServers()
+renderMcpServers(servers)
+addMcpServer(serverData)
+connectMcpServer(id)
+disconnectMcpServer(id)
+toggleMcpServer(id, enabled)
}
class ToolboxSkills {
+loadSkills()
+renderSkills(skills)
+runSkill(name, params)
+importSkill(skillDef)
+showSkillParamsDialog(name, paramsDef)
+showSkillRunResult(name, skillInfo, result)
}
class ToolboxRag {
+loadRagStatus()
+startRagInstall()
+redetectRag()
+refreshRagSection()
}
ToolboxConfig --> ToolboxMcp : "调用"
ToolboxConfig --> ToolboxSkills : "调用"
ToolboxConfig --> ToolboxRag : "调用"

图表来源

章节来源

MCP 工具集成 ​

  • 远程工具发现：Background 调用 AgentClient.getMcpTools() 与 getMcpServers()，构建 RAW_TOOLS/BUILTIN_TOOLS/TOOL_EXECUTION_MAP/TOOL_HANDLERS。
  • 协议适配：支持多种传输方式（stdio/SSE/streamableHttp/websocket），由选项页表单配置 env/headers。
  • 错误处理：
    • 全局开关关闭时跳过加载。
    • 禁用服务器工具被过滤。
    • schema 压缩（限制 description 长度、嵌套深度、参数数量）。
    • 服务级 deny-list（弹窗层关闭 + 助手编辑器排除）。
  • 服务级开关：
    • 弹窗层 mcpClosedServers 与服务是否被助手排除 activeAgentMcpExcludedServerIds 共同决定最终开放状态。
    • 强制下发：会话内可通过手动指定强制包含某服务的工具。
sequenceDiagram
participant BG as "Background tool-executor.js"
participant AG as "Agent registry.js"
participant EXT as "chrome.storage.local"
BG->>AG : getMcpTools() / getMcpServers()
AG-->>BG : tools[] / servers[]
BG->>BG : 过滤禁用服务器、去重、schema 压缩
BG->>EXT : set({ mcpTools : [...] })
BG->>BG : rebuildBgHandlers()
Note over BG,AG : 后续工具调用走 TOOL_HANDLERS -> AgentClient.callMcpTool

图表来源

章节来源

RAG 知识库工具与配置界面 ​

  • 工具定义：RAG_TOOLS 包含 knowledge_search、knowledge_ingest、knowledge_list，仅在 ragEnabled=true 且 agent /api/status ragAvailable=true 时动态注册。
  • 配置界面：
    • 门控：Agent 未连接 / RAG 总开关未启用 / 代理端能力未就绪。
    • 知识库列表：新建/编辑/删除/启停/导入文档/文档管理/检索测试。
    • 向量配置：本地或 OpenAI 兼容模式，支持 endpoint/apiKey/modelName/dimensions 测试连通性与自动维度填充。
    • 导入：支持文件/文本/URL，分块参数可调整，进度阶段可视化。
    • 检索：默认 topK/threshold，支持集合 ID 限定检索。
flowchart TD
Gate["门控检查"] --> Ready{"Agent 连接 & RAG 可用？"}
Ready --> |否| Guide["安装引导 / Node 版本提示"]
Ready --> |是| List["加载知识库列表"]
List --> Ops["新建/编辑/导入/检索/启停/删除"]
Ops --> Vector["向量配置本地/OpenAI 兼容"]
Vector --> Test["连通性测试与维度自动填充"]
Test --> Ingest["导入文档文件/文本/URL"]
Ingest --> Search["检索可选 collectionId/topK"]

图表来源

章节来源

Skill 技能系统面板集成 ​

  • 列表展示：区分 Workflow 与 Agent 类型，显示名称/版本/描述/步骤数/资源数/启用状态。
  • 执行控制：
    • 参数解析（JSON Schema properties/required），必填项校验与默认值提示。
    • 运行按钮触发 /api/skill/run，返回 steps/results。
  • 结果输出：
    • 分步展示成功/失败/跳过状态与输出内容，过长截断。
    • 支持查看/编辑 Agent Skill Markdown，导入 JSON/Zip/URL。
sequenceDiagram
participant UI as "选项页 toolbox-skills.js"
participant AG as "Agent /api/skill/*"
UI->>AG : GET /api/skill/list
AG-->>UI : skills[]
UI->>UI : 渲染卡片Workflow/Agent
UI->>AG : POST /api/skill/run {name, params}
AG-->>UI : {success, results}
UI->>UI : showSkillRunResult(name, skillInfo, result)

图表来源

章节来源

依赖关系分析 ​

  • 侧边栏依赖 Background 的工具注册与状态同步（storage.onChanged）。
  • 选项页依赖 Agent REST 接口（/api/mcp/、/api/skill/、/api/rag/*）。
  • Background 依赖 Agent Client 进行 MCP 工具拉取与调用。
  • Agent 端 MCP 注册表管理多个 McpClient 实例，提供扁平化工具列表与调用。
  • Skill 加载器扫描文件系统，校验 Workflow 定义并合并 Agent Markdown 技能。
graph LR
SP["side_panel/tool-panel.js"] --> BG["background/tool-executor.js"]
OPT["options/toolbox-*.js"] --> BG
BG --> AG["agent/src/mcp/registry.js"]
BG --> SKILL["agent/src/skill/loader.js"]
BG --> RAG["agent/src/rag/*"]

图表来源

章节来源

性能与扩展性 ​

  • MCP schema 压缩：限制 description 长度、properties 嵌套深度与参数数量，避免上下文膨胀。
  • 并发保护：MCP/RAG 动态注册使用互斥锁防止并发 load/unload。
  • 批量重建：RAW_TOOLS/BUILTIN_TOOLS/TOOL_HANDLERS 变化后统一重建 BG_HANDLERS 与并行/确认集合。
  • 前端缓存：MCP/RAG 工具缓存于 chrome.storage.local，减少重复请求。
  • 可扩展点：
    • 新增工具分类：在 constants.js 中追加分类 key，并在 tool-panel.js 的分类渲染逻辑中保持兼容。
    • 新增动态工具：在 background/tools 下定义工具数组，并在 tool-executor.js 中实现执行函数与注册逻辑。

[本节为通用指导，无需具体文件引用]

故障排查指南 ​

  • 工具弹窗无数据：
    • 检查 Background 是否已加载 MCP/RAG 工具缓存（storage.mcpTools/storage.ragTools）。
    • 确认全局开关 mcpEnabled/skillsEnabled 与 Agent 连接状态。
  • MCP 工具不可用：
    • 检查服务是否被禁用（servers[].enabled=false）或弹窗层关闭（mcpClosedServers）。
    • 检查助手编辑器排除列表（activeAgentMcpExcludedServerIds）。
  • RAG 功能不可用：
    • 检查 /api/status 的 ragAvailable 与 nodeVersion。
    • 若依赖未安装，进入安装引导并轮询 /api/rag/install/status。
  • Skill 执行失败：
    • 检查参数必填项是否填写，查看执行结果弹窗中的步骤状态与错误信息。
  • 命令执行被拒绝：
    • 检查是否需要用户确认（requiresConfirmation），以及网络访问白名单与内网地址策略。

章节来源

结论 ​

工具面板集成以“侧边栏展示 + 选项页配置 + Background 执行 + Agent 能力”的分层架构实现，具备完善的动态加载、分类管理、权限控制与错误处理机制。MCP 工具以服务级开关与 schema 压缩保障安全与性能；RAG 知识库提供完整的配置界面与安装引导；Skill 系统支持 Workflow 与 Agent 两种形态，并提供参数校验与结果可视化。扩展时可遵循现有模式新增工具类别与动态工具，同时注意 MV3 Service Worker 生命周期约束与 Agent 进程重启要求。

[本节为总结，无需具体文件引用]

附录：新增工具类别与权限控制示例 ​

新增工具类别的步骤 ​

  • 在 side_panel/constants.js 中追加分类 key（如 'custom_tool'）。
  • 在 background/constants.js 或对应工具文件中定义 BUILTIN_TOOLS_UI 条目，确保 category 为新分类。
  • 在 tool-panel.js 的分类渲染逻辑中保持兼容（CATEGORY_ORDER 已动态补充 'mcp'/'knowledge'，新增分类需显式加入）。
  • 如需动态注册，参考 RAG_TOOLS 与 tool-executor.js 的动态注册模式。

章节来源

工具执行状态与用户反馈 ​

  • 执行前校验：参数缺失、协议限制、网络白名单、内网地址策略。
  • 执行中：并行执行标记（parallelizable）、超时控制、审计日志记录。
  • 执行后：成功/失败/跳过状态展示，长输出截断，下载/截图等动作反馈。

章节来源

工具权限控制机制 ​

  • 安全检查：
    • 网络访问范围（decideNetworkAccess）。
    • 内网地址白名单与总开关。
    • 系统页面与 tab 访问限制。
  • 用户确认流程：
    • requiresConfirmation 工具触发 requestToolConfirmation。
    • 命令执行需要确认但流程不可用时中止执行并提示替代方案。

章节来源

工具配置的持久化与版本迁移 ​

  • 持久化存储：
    • chrome.storage.local：mcpEnabled、skillsEnabled、ragEnabled、mcpTools、ragTools、enabledTools、mcpClosedServers、enableToolPreselect、toolConfirmationEnabled。
    • Agent 端：MCP 服务器配置、Skill 文件（JSON/YAML/Markdown）、RAG 集合与索引。
  • 版本迁移：
    • Skill 种子写入（skill-creator）版本号比较，自动更新。
    • RAG 依赖安装与重新检测，Node 版本前置检查。
    • 工具定义与 handler 重建（rebuildBgHandlers）保证一致性。

章节来源