工具生态系统

本文引用的源码文件

本文引用的文件

引言

本文件面向“AI Helper”工具生态系统的开发者与高级用户，系统性说明扩展端内置工具集、MCP（Model Context Protocol）协议扩展、Skill 技能系统、工具注册与动态发现机制，以及 Agent 本地代理端的职责边界。文档同时给出架构图、调用时序图、流程图和扩展开发建议，帮助读者在不直接阅读源码的情况下理解并安全扩展该生态。

本项目采用双进程架构：

Chrome 扩展端（Manifest V3，Service Worker 背景脚本）负责浏览器能力、ReAct 执行循环、工具预筛选、UI 交互与消息路由。
独立本地代理端（Node.js）提供文件读写、命令执行、长期记忆、RAG、Skill 与 MCP 工具扩展能力。两端通过 HTTP/WebSocket 通信，Agent 修改后必须重启进程才能生效。

项目结构

仓库按功能域分层组织：

src/background：扩展端主逻辑，包括工具定义、执行器、MCP/RAG 动态注入、侧边栏生命周期等。
src/shared：跨模块共享常量、主题、i18n、工具分类导出等。
agent/src：本地代理服务端，包含 HTTP 路由、认证、安全沙箱、命令执行、Memory/RAG、Skill、MCP 注册表等。
docs、test、scripts 等用于文档、测试与构建发布。

graph TB
subgraph "Chrome 扩展端"
BG["background/index.js<br/>Service Worker 入口"]
CONST["background/constants.js<br/>工具定义与分类"]
EXEC["background/tool-executor.js<br/>工具执行与动态注册"]
SHARED["shared/tools.js<br/>工具分类导出"]
TOOLS["background/tools/*<br/>浏览器/存储/标签页/调试等工具"]
end
subgraph "本地代理端"
SERVER["agent/src/server.js<br/>HTTP + WebSocket 服务器"]
MCP_REG["agent/src/mcp/registry.js<br/>MCP 注册表"]
MCP_CLI["agent/src/mcp/client.js<br/>MCP 客户端"]
SKILL_REG["agent/src/skill/registry.js<br/>Skill 注册表"]
SKILL_LOAD["agent/src/skill/loader.js<br/>Skill 加载器"]
MD_LOAD["agent/src/skill/markdown-loader.js<br/>Markdown 技能加载"]
TPL["agent/src/skill/template.js<br/>模板引擎"]
end
BG --> EXEC
BG --> CONST
EXEC --> TOOLS
EXEC --> SHARED
BG --> |"HTTP/WebSocket"| SERVER
SERVER --> MCP_REG
MCP_REG --> MCP_CLI
SERVER --> SKILL_REG
SKILL_REG --> SKILL_LOAD
SKILL_LOAD --> MD_LOAD
SKILL_LOAD --> TPL

图示来源

章节来源

核心组件

本节聚焦工具生态的关键构件：内置工具集、MCP 协议扩展、Skill 技能系统、工具注册与动态发现。

内置工具集
- 类别覆盖：页面交互、表单操作、内容提取、标签页管理、书签历史、存储管理、网络请求、媒体输出、调试开发、AI 协作、本地代理、MCP、知识库等。
- 统一由 background/constants.js 聚合为 RAW_TOOLS，并派生 BUILTIN_TOOLS、分类映射、并行与确认标记等。
- 具体实现位于 src/background/tools/*，例如浏览器工具、存储工具、标签页工具、调试工具等。
MCP 协议扩展
- Agent 启动时根据配置自动连接启用的 MCP Server，建立 JSON-RPC over stdio 通道，自动发现工具。
- 扩展端通过 loadMcpTools() 从 Agent 拉取工具列表，压缩 schema 后动态注入到 RAW_TOOLS 与处理器映射中，支持服务级开关与会话强制下发。
Skill 技能系统
- 支持 Workflow Skill（JSON/YAML）与 Agent Skill（SKILL.md）。
- 注册表扫描 ~/.ai-helper-agent/skills/，加载工作流与 Markdown 技能，持久化启用状态，并提供执行、导入、删除、切换启用等接口。
- Markdown 技能支持 frontmatter、资源清单、模板渲染与提示词注入。
工具注册与动态发现
- 扩展端在运行时合并 MCP/RAG 工具；Agent 端暴露 /api/mcp/tools、/api/skill/list 等接口供扩展查询。
- 工具变更触发处理器重建，保证新工具立即参与 ReAct 推理与预筛选。

章节来源

架构总览

下图展示扩展端与 Agent 端在工具调用中的交互路径，包括内置工具、MCP 工具与 Skill 的调用链路。

sequenceDiagram
participant UI as "侧边面板/用户"
participant BG as "background/index.js"
participant EXEC as "tool-executor.js"
participant AG as "agent/src/server.js"
participant MCP as "mcp/registry.js"
participant CLI as "mcp/client.js"
participant SK as "skill/registry.js"
UI->>BG : 发起任务含工具选择
BG->>EXEC : 解析参数/预筛选/校验
alt 内置工具
EXEC->>EXEC : 执行浏览器/存储/标签页/调试等
else MCP 工具
EXEC->>AG : GET /api/mcp/tools
AG-->>EXEC : 返回扁平化工具列表
EXEC->>AG : POST 调用 MCP 工具
AG->>MCP : callMcpTool(serverId, toolName, args)
MCP->>CLI : client.callTool()
CLI-->>MCP : 结果
MCP-->>AG : 结果
AG-->>EXEC : 结果
else Skill 执行
EXEC->>AG : POST /api/skill/ : name/run
AG->>SK : runSkill(name, params)
SK-->>AG : 步骤执行结果
AG-->>EXEC : 结果
end
EXEC-->>BG : 结果回传
BG-->>UI : 展示结果/继续推理

图示来源

详细组件分析

内置工具集

浏览器工具：读取页面、点击、填写表单、上传文件、截图、处理弹窗等。
存储工具：扩展存储读写、键值管理、批量操作。
标签页管理：打开/关闭/切换/分组/导航等待等。
调试工具：调试会话、日志、断点辅助等。

这些工具以声明式方式定义在 background/constants.js 中，并通过 tools/* 模块实现具体逻辑。扩展端在执行时根据工具元数据决定是否需要确认、是否可并行、超时策略等。

classDiagram
class BrowserTools {
+readPage()
+clickElement()
+fillForm()
+uploadFile()
+takeScreenshot()
}
class StorageTools {
+get(key)
+set(key, value)
+remove(key)
+clear()
}
class TabTools {
+openTab(url)
+closeTab(tabId)
+switchTab(tabId)
+navigateWait(timeout)
}
class DebuggerTools {
+startSession()
+stopSession()
+getLogs()
}

图示来源

章节来源

src/background/constants.js#L87-L149

MCP 协议扩展

MCP 扩展允许第三方工具以标准协议接入 Agent，并由扩展端动态发现与调用。

客户端连接：Agent 启动时根据 config.json 中的 mcpServers 配置自动连接启用的 MCP Server，使用 JSON-RPC over stdio。
工具自动发现：initializeMcpRegistry() 收集已连接 Client 的工具列表，getMcpTools() 返回扁平化工具元信息。
远程工具调用：callMcpTool() 转发调用至对应 Client，封装成功/失败结果。
协议兼容性处理：扩展端对 inputSchema 进行压缩（限制嵌套深度、参数数量、description 长度），避免上下文膨胀；对禁用服务进行过滤，支持会话级强制下发。

flowchart TD
Start(["Agent 启动"]) --> LoadCfg["加载 MCP 配置"]
LoadCfg --> Connect["逐个连接启用的 MCP Server"]
Connect --> Discover["获取工具列表"]
Discover --> Register["注册到 MCP 注册表"]
Register --> Ready(["就绪"])
Ready --> CallTool["扩展端调用 MCP 工具"]
CallTool --> Registry["registry.callMcpTool()"]
Registry --> Client["client.callTool()"]
Client --> Result["返回结果"]

图示来源

章节来源

Skill 技能系统

Skill 系统将工作流与知识沉淀为可复用、可执行的技能单元。

技能定义格式
- Workflow Skill：JSON/YAML，包含 name、description、version、parameters、steps 等字段。
- Agent Skill：SKILL.md，frontmatter 描述名称、描述、启用状态，正文包含使用说明、示例、资源清单等。
Markdown 技能加载：markdown-loader.js 扫描子目录，解析 frontmatter 与正文，生成完整提示词。
模板引擎支持：template.js 提供模板渲染能力，便于在 Skill 中嵌入变量与结构化输出。
执行框架：executor.js 驱动 Workflow Skill 的步骤执行，支持回调进度更新；Agent Skill 由 AI 在对话中按需加载完整内容。

flowchart TD
Init["初始化 Skill 注册表"] --> Scan["扫描 skills 目录"]
Scan --> LoadWF["加载 Workflow Skill (JSON/YAML)"]
Scan --> LoadMD["加载 Agent Skill (SKILL.md)"]
LoadWF --> Validate["校验定义"]
LoadMD --> Parse["解析 frontmatter 与正文"]
Validate --> Register["注册到内存 Map"]
Parse --> Register
Register --> List["提供 getSkillList/getSkill"]
Register --> Run["runSkill(name, params)"]
Run --> Exec["executor.executeSkill()"]

图示来源

章节来源

工具注册机制、动态发现与生命周期

扩展端
- 静态工具：background/constants.js 聚合所有内置工具，派生分类、执行映射、并行与确认标记。
- 动态工具：tool-executor.js 的 loadMcpTools() 从 Agent 拉取 MCP 工具，压缩 schema 后注入 RAW_TOOLS，并重建处理器映射；unloadMcpTools() 清理动态注册。
- 会话强制下发：支持在会话内强制指定 MCP 服务，绕过全局关闭或排除列表，确保关键工具不被预筛选丢弃。
Agent 端
- MCP 注册表：维护已连接 Client，提供工具列表与调用接口。
- Skill 注册表：扫描文件系统，加载 Workflow/Agent 技能，持久化启用状态，提供执行与元信息查询。

sequenceDiagram
participant BG as "background/tool-executor.js"
participant AG as "agent/src/server.js"
participant MCP as "agent/src/mcp/registry.js"
BG->>AG : GET /api/mcp/tools
AG-->>BG : 返回工具列表
BG->>BG : 压缩 schema / 去重 / 注入 RAW_TOOLS
BG->>BG : rebuildBgHandlers()
Note over BG : 动态工具可并行/无需确认
BG->>AG : 调用 MCP 工具
AG->>MCP : callMcpTool()
MCP-->>AG : 结果
AG-->>BG : 结果

图示来源

章节来源

依赖关系分析

扩展端依赖
- background/index.js 作为 Service Worker 入口，负责侧边栏生命周期、保活端口、快捷键、通知、自动续跑等。
- background/constants.js 是工具定义的单一数据源，派生出 UI 展示、分类顺序、执行映射等。
- background/tool-executor.js 是工具执行中枢，集成 MCP/RAG 动态注册、参数校验、错误处理、审计记录等。
- shared/tools.js 提供工具分类与预设模式的共享导出。
Agent 端依赖
- server.js 提供 HTTP 路由、认证、CORS、日志、文件上传、命令执行、RAG、Skill、MCP 等能力。
- mcp/registry.js 与 mcp/client.js 实现 MCP 协议客户端与注册表。
- skill/registry.js、skill/loader.js、skill/markdown-loader.js、skill/template.js 共同构成 Skill 系统。

graph LR
BG_INDEX["background/index.js"] --> CONST["background/constants.js"]
BG_INDEX --> EXEC["background/tool-executor.js"]
EXEC --> TOOLS["background/tools/*"]
EXEC --> SHARED["shared/tools.js"]
EXEC --> AG_SERVER["agent/src/server.js"]
AG_SERVER --> MCP_REG["agent/src/mcp/registry.js"]
MCP_REG --> MCP_CLI["agent/src/mcp/client.js"]
AG_SERVER --> SKILL_REG["agent/src/skill/registry.js"]
SKILL_REG --> SKILL_LOAD["agent/src/skill/loader.js"]
SKILL_LOAD --> MD_LOAD["agent/src/skill/markdown-loader.js"]
SKILL_LOAD --> TPL["agent/src/skill/template.js"]

图示来源

章节来源

性能与扩展性

工具预筛选与 Token 预算
- 当工具数量超过阈值时启用预筛选，减少 LLM 上下文压力；工具定义集中管理，便于扩展新增工具而不破坏现有行为。
MCP Schema 压缩
- 限制 properties 嵌套深度、参数数量与 description 长度，避免 MCP 工具定义撑爆上下文。
并行与确认控制
- 工具元数据标记 parallelizable 与 requiresConfirmation，执行器据此决定是否并行与是否需要用户确认。
Agent 端健壮性
- 请求级异常捕获、URL 解析保护、全局未捕获异常处理、文件 I/O 保护、进程管理保护，防止单点错误导致服务崩溃。
Skill 执行优化
- Workflow Skill 支持步骤回调，便于前端展示进度；Agent Skill 按需加载完整提示词，减少系统提示占用。

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

故障排查指南

Service Worker 生命周期问题
- 侧边栏与 background 的消息传递需通过保活端口维持 SW 存活；SW 被回收后通过闹钟恢复 checkpoint 自动续跑。
- 若出现“无 Side Panel”或“API 调用丢失”，检查 keepalive 端口连接与 SW 重启检测逻辑。
MCP 工具不可用
- 检查 Agent 是否连通、MCP 全局开关是否开启、目标服务是否启用；查看扩展端日志中 load MCP tool failed 提示。
Skill 加载失败
- 检查 ~/.ai-helper-agent/skills/ 下文件权限与格式；Workflow Skill 需满足校验规则，Agent Skill 需存在 SKILL.md。
Agent 端错误
- 查看审计日志 /api/logs，关注 security、exec、fs 等类别；确认配对码有效、Token 正确、端口可达。

章节来源

结论

AI Helper 的工具生态系统以扩展端为中心，结合 Agent 本地代理能力，实现了浏览器自动化、本地文件与命令执行、长期记忆与 RAG、Skill 技能编排与 MCP 协议扩展的统一入口。通过声明式工具定义、动态注册与压缩策略、Skill 文件系统与模板引擎，系统在可扩展性与安全性之间取得平衡。开发者可基于本文档快速定位核心模块，安全地扩展新工具、实现 MCP 协议工具与编写自定义 Skill。

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

附录：扩展开发指南

开发新的内置工具

在 src/background/tools/ 下新增工具模块，实现具体逻辑。
在 src/background/constants.js 中引入并加入 RAW_TOOLS，设置 id、category、execution、parallelizable、requiresConfirmation 等元数据。
如需用户确认或动作级确认，补充 confirmationActions。
测试用例应覆盖参数校验、错误分支与 i18n 文案。

章节来源

src/background/constants.js#L87-L149

实现 MCP 协议工具

在 Agent 端实现 MCP Server，遵循 JSON-RPC over stdio 协议。
在 ~/.ai-helper-agent/config.json 中添加 mcpServers 配置，启用服务。
扩展端会自动拉取工具列表并注入；如需会话强制下发，使用 setSessionForcedMcpServers。
注意 inputSchema 复杂度，避免深层嵌套与过长 description。

章节来源

编写自定义 Skill

Workflow Skill：创建 JSON/YAML 文件，包含 name、description、version、parameters、steps。
Agent Skill：创建 SKILL.md，frontmatter 描述名称、描述、启用状态，正文包含使用说明与示例。
使用 template.js 提供的模板能力，在 Skill 中嵌入变量与结构化输出。
通过 /api/skill/import 导入，/api/skill/:name/toggle 切换启用状态，/api/skill/:name/run 执行 Workflow Skill。

章节来源

最佳实践与注意事项

工具调用前进行参数校验，避免空值或非法类型。
对敏感操作启用确认流程，必要时提供动作级确认。
合理使用并行执行，避免阻塞长任务。
MCP 工具 schema 尽量扁平，description 简洁明确。
Skill 设计遵循最小可用原则，Workflow 步骤清晰，Agent Skill 描述准确。
Agent 修改后必须重启进程，新接口才生效。

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

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

工具生态系统

目录

引言

项目结构

核心组件

架构总览

详细组件分析

内置工具集

MCP 协议扩展

Skill 技能系统

工具注册机制、动态发现与生命周期

依赖关系分析

性能与扩展性

故障排查指南

结论

附录：扩展开发指南

开发新的内置工具

实现 MCP 协议工具

编写自定义 Skill

最佳实践与注意事项

Markdown 渲染引擎

工具生态系统 ​

目录 ​

引言 ​

项目结构 ​

核心组件 ​

架构总览 ​

详细组件分析 ​

内置工具集 ​

MCP 协议扩展 ​

Skill 技能系统 ​

工具注册机制、动态发现与生命周期 ​

依赖关系分析 ​

性能与扩展性 ​

故障排查指南 ​

结论 ​

附录：扩展开发指南 ​

开发新的内置工具 ​

实现 MCP 协议工具 ​

编写自定义 Skill ​

最佳实践与注意事项 ​

工具生态系统

目录

引言

项目结构

核心组件

架构总览

详细组件分析

内置工具集

MCP 协议扩展

Skill 技能系统

工具注册机制、动态发现与生命周期

依赖关系分析

性能与扩展性

故障排查指南

结论

附录：扩展开发指南

开发新的内置工具

实现 MCP 协议工具

编写自定义 Skill

最佳实践与注意事项