主题
项目概览与快速开始
本文引用的源码文件
本文引用的文件
目录
引言
AI Helper 是一个让大语言模型真正操作网页的开源浏览器扩展。它不只是聊天，还能点击、填写表单、拖拽、上传文件、执行终端命令，并通过 MCP 协议动态扩展工具；可选本地 Agent 服务进一步提供文件读写、命令执行、长期记忆与知识库检索能力。
项目的核心价值可以概括为：
- 可操作的 AI 助手：从“读网页”升级到“亲手操作网页”。
- 双进程架构：Chrome 扩展端负责用户界面、页面交互与任务编排；独立 Node.js Agent 服务负责本地文件系统、命令执行、RAG 知识库和外部工具集成。
- 可控且可扩展：内置 40+ 工具、Skill 技能系统、MCP 协议、多智能体协作、定时任务、审计日志与回收站等生产级能力。
- 数据本地优先：知识库索引和本地文件操作运行在用户本机，便于隐私控制和离线场景。
当前文档以版本 2.3.1 为准，对应扩展端 package.json、Agent 包 ai-helper-agent、Manifest 版本号以及构建产物中的版本信息保持一致。
章节来源
- README.md#L39-L75
- README.zh-CN.md#L39-L75
- package.json#L1-L10
- agent/package.json#L1-L10
- manifest.json#L1-L10
- src/config/version.json#L1-L7
项目结构
仓库采用“扩展端 + Agent 子工程”的组织方式：
- 根目录是 Chrome 扩展工程，包含 Manifest V3 配置、Vite 构建脚本、背景脚本、内容脚本、侧边栏、选项页、共享模块和测试。
agent/是独立的 Node.js 代理服务工程，暴露 HTTP/WebSocket API，并提供 MCP、Skill、RAG、命令执行、文件管理、安全策略和日志子系统。docs/存放产品文档、架构图、商店素材、文章和演示资源。scripts/包含构建、打包、主题审计、图标生成等工程脚本。test/是扩展端的单元测试与端到端测试；Agent 端测试位于agent/test/。
graph TB Root["仓库根目录<br/>Chrome 扩展工程"] --> Src["src/<br/>扩展源代码"] Root --> Docs["docs/<br/>文档与素材"] Root --> Scripts["scripts/<br/>构建与发布脚本"] Root --> Test["test/<br/>扩展端测试"] Root --> Agent["agent/<br/>Node.js 代理服务"] Agent --> AgentSrc["agent/src/<br/>HTTP 服务器、MCP、Skill、RAG、安全、日志"] Agent --> AgentTest["agent/test/<br/>代理端测试"]
图表来源
章节来源
核心组件
本项目由两个主要进程组成：
| 组件 | 职责 | 关键入口或文件 | 技术要点 |
|---|---|---|---|
| Chrome 扩展端 | 用户界面、页面注入、工具调用、会话管理、调度、通知、主题与国际化 | manifest.json、src/background/index.js、src/side_panel.html、src/options.html | Manifest V3 Service Worker、Side Panel、Content Script、MV3 生命周期保活 |
| 本地 Agent 服务 | 文件读写、命令执行、MCP 工具注册、Skill 执行、RAG 知识库、认证与日志 | agent/src/server.js、agent/package.json | Node.js HTTP/WebSocket、CORS 白名单、Bearer Token、路径与命令安全分级 |
扩展端通过本地 HTTP 和 WebSocket 调用 Agent 提供的能力；Agent 修改源码后必须重启进程，新接口才会生效。
章节来源
架构总览
AI Helper 的双进程架构可以理解为“浏览器内的智能助手 + 本机上的可信代理”：
graph TB User["用户"] --> SidePanel["侧边栏界面<br/>side_panel.html"] SidePanel --> Background["Background Service Worker<br/>src/background/index.js"] Background --> ContentScript["Content Script<br/>src/content/index.js"] Background --> LocalAgentClient["本地 Agent 客户端<br/>src/background/local-agent-client.js"] LocalAgentClient --> AgentServer["Agent HTTP/WebSocket 服务器<br/>agent/src/server.js"] AgentServer --> FileSystem["本地文件系统"] AgentServer --> Shell["系统命令执行"] AgentServer --> RAG["RAG 知识库"] AgentServer --> MCP["MCP 工具注册与调用"] AgentServer --> Skill["Skill 技能系统"]
图表来源
该架构的关键设计原则包括：
- 扩展端专注浏览器上下文、UI 和任务编排。
- Agent 端专注本地资源和外部系统能力。
- 两端通过明确的 API 契约通信，而不是直接共享内存。
- 安全边界由 CORS、Origin 校验、Bearer Token、路径白名单和命令安全检查共同构成。
章节来源
详细组件分析
Chrome 扩展端
扩展端基于 Manifest V3，核心职责包括：
- 定义扩展权限、内容脚本、Service Worker、选项页和侧边栏。
- 管理用户会话、消息流、工具调用、截图、调试器、调度器和通知。
- 通过
local-agent-client.js封装与 Agent 的 HTTP/WebSocket 通信。 - 提供内置 Agent 模板和多 Agent 调度能力。
classDiagram
class BackgroundService {
+启动服务Worker
+处理扩展消息
+管理会话状态
+协调工具执行
+触发通知
}
class LocalAgentClient {
+pairWithAgent()
+agentRequest()
+agentGet()
+uploadFile()
+execCommand()
+createExecWebSocket()
+getMcpTools()
+callMcpTool()
}
class AgentDispatcher {
+executeDispatchSubAgent()
+loadAgent()
+buildSubAgentPrompt()
}
class SharedAgentDefaults {
+BUILTIN_AGENTS
+AGENT_TEMPLATES
+generateAgentId()
}
BackgroundService --> LocalAgentClient : "调用"
BackgroundService --> AgentDispatcher : "派生子任务"
AgentDispatcher --> SharedAgentDefaults : "读取内置Agent"
图表来源
- manifest.json#L47-L53
- src/background/local-agent-client.js#L40-L93
- src/background/agent-dispatcher.js#L1-L28
- src/shared/agent-defaults.js#L1-L21
章节来源
- manifest.json#L1-L76
- src/background/local-agent-client.js#L40-L93
- src/background/agent-dispatcher.js#L1-L28
- src/shared/agent-defaults.js#L1-L21
本地 Agent 服务
Agent 服务是扩展端能力的延伸，核心职责包括：
- 启动 HTTP 服务器并路由
/api/*请求。 - 实现配对认证、健康检查、心跳、重启、更新和关闭。
- 提供文件读写、目录列表、搜索、ZIP 打包、流式上传。
- 执行系统命令，支持异步、等待、停止、分离模式。
- 注册 MCP 工具、Skill 技能、RAG 知识库。
- 输出结构化日志，支持审计与安全事件记录。
flowchart TD
Start["Agent 进程启动"] --> LoadConfig["加载配置"]
LoadConfig --> InitSearch["初始化搜索工具检测"]
InitSearch --> InitRAG["检测 RAG 可用性"]
InitRAG --> CreateServer["创建 HTTP 服务器"]
CreateServer --> HandleRequest["处理 /api/* 请求"]
HandleRequest --> PairCheck{"是否配对接口？"}
PairCheck --> |是| PairHandler["处理 /api/pair"]
PairCheck --> |否| AuthCheck{"是否需要认证？"}
AuthCheck --> |否| PublicHandler["公开接口：status、pair 等"]
AuthCheck --> |是| TokenVerify["验证 Bearer Token"]
TokenVerify --> RouteHandler["路由到具体功能"]
RouteHandler --> FileOps["文件操作"]
RouteHandler --> ExecOps["命令执行"]
RouteHandler --> McpOps["MCP 工具"]
RouteHandler --> SkillOps["Skill 技能"]
RouteHandler --> RagOps["RAG 知识库"]
图表来源
章节来源
子代理调度与内置 Agent
扩展端支持主 Agent 派生子 Agent，用于分工完成复杂任务。调度器会：
- 限制嵌套深度，防止 ReAct 循环无限递归。
- 加载内置或自定义 Agent 定义。
- 根据 Agent 的工具集合和技能提示词构建系统提示。
- 使用派生 sessionId 隔离子 Agent 的信令与日志。
- 对返回结果进行 token 预算截断。
sequenceDiagram participant Main as "主 Agent" participant Dispatcher as "AgentDispatcher" participant Model as "大模型 API" participant Tools as "工具集合" Main->>Dispatcher : 调用 dispatch_task Dispatcher->>Dispatcher : 检查嵌套深度 Dispatcher->>Dispatcher : 加载子 Agent 定义 Dispatcher->>Tools : 获取子 Agent 工具 Dispatcher->>Model : 发送带系统提示的消息 Model-->>Dispatcher : 工具调用或最终答案 Dispatcher->>Tools : 执行工具如有 Tools-->>Dispatcher : 工具结果 Dispatcher-->>Main : 返回子 Agent 执行结果
图表来源
- src/background/agent-dispatcher.js#L100-L155
- src/background/agent-dispatcher.js#L157-L218
- src/shared/agent-defaults.js#L6-L21
章节来源
- src/background/agent-dispatcher.js#L1-L28
- src/background/agent-dispatcher.js#L100-L218
- src/shared/agent-defaults.js#L1-L145
依赖关系分析
扩展端与 Agent 端的依赖关系不是代码导入关系，而是运行时通信契约：
graph LR Extension["Chrome 扩展<br/>manifest_version=3"] --> Client["LocalAgentClient<br/>HTTP/WebSocket 客户端"] Client --> Server["Agent 服务器<br/>/api/* 路由"] Server --> Security["安全策略<br/>路径/命令校验"] Server --> Memory["长期记忆"] Server --> RAG["RAG 知识库"] Server --> MCP["MCP 工具"] Server --> Skill["Skill 技能"] Server --> Logger["日志与审计"]
图表来源
需要注意：
- 扩展端不直接访问 Agent 的内部模块，只通过 API 调用。
- Agent 内部模块之间耦合较高，例如 server.js 同时引入安全、日志、MCP、Skill、RAG、命令执行等。
- 扩展端与 Agent 端的版本号应保持一致，避免契约不一致。
章节来源
性能与运行时约束
- Service Worker 生命周期：Chrome MV3 的 Service Worker 可能被空闲终止，需要保活机制；background 与 side panel 的消息传递是常见故障点。
- Agent 进程重启：Agent 源码修改后必须重启进程，新接口才生效；服务端提供
/api/agent/restart和/api/agent/update接口。 - 请求超时：扩展端对 HTTP 请求设置默认超时，WebSocket 连接空闲超时由调用方统一管理，避免双重超时冲突。
- Token 预算管理：扩展端按 Token 数而非消息数截断上下文，避免拆分 tool_calls 与 tool 消息。
- 文件大小限制：Agent 对 JSON body、流式上传、文件读取分别设置大小上限，防止内存爆炸。
章节来源
- src/background/local-agent-client.js#L393-L443
- src/background/local-agent-client.js#L652-L728
- agent/src/server.js#L132-L137
- agent/src/server.js#L555-L603
安装指南与系统要求
官方安装渠道以 GitHub Releases 自动构建产物为主：
- 从 Chrome Web Store 或 Microsoft Edge Add-ons 商店安装。
- Chromium 用户可从 GitHub Releases 下载
ai-helper-*.zip，解压后在开发者模式下加载已解压扩展程序。 - 开发者可从源码构建，但推荐普通用户直接使用官方构建产物。
系统要求：
- Chrome / Edge / Chromium 114+，因为需要使用 Side Panel API。
- 若启用本地 Agent 能力，需要 Node.js 环境安装
ai-helper-agent。
章节来源
快速开始
推荐的新手流程如下：
- 安装扩展：从应用商店或 GitHub Releases 安装。
- 打开侧边栏：使用快捷键或扩展图标打开侧边栏。
- 配置大模型厂商：在选项页添加 OpenAI 兼容端点和密钥，保存多个厂商配置。
- 可选：启动本地 Agent：一键安装代理端或使用命令行启动，将配对码填入选项页 → Agent。
章节来源
基本使用示例
以下是几个适合入门的典型场景：
| 场景 | 说明 | 相关能力 |
|---|---|---|
| 网页信息提取 | 让 AI 读取当前标签页内容，总结长文、表格或链接列表 | 页面内容、元素查询、数据提取 |
| 任务自动化 | 自动点击、填表、滚动、上传文件，甚至处理弹窗 | 页面交互、表单填充、文件上传 |
| 知识检索 | 导入 PDF、Word、Excel、PPT、Markdown、HTML、CSV，构建本地知识库并提问 | RAG、混合检索、引用溯源 |
| 本地文件与命令 | 让 AI 读取本地文件、列出目录、执行终端命令 | Agent 文件 API、命令执行、安全分级 |
| 定时任务 | 每天固定时间针对某个 URL 重跑指令，结果写入指定会话 | 调度器、通知、会话管理 |
这些场景在 README 中都有明确描述，可作为上手起点。
章节来源
扩展端与 Agent 端通信机制
扩展端通过 local-agent-client.js 封装与 Agent 的通信，核心契约包括：
| 类别 | 端点或行为 | 用途 |
|---|---|---|
| 配对与会话 | /api/pair、/api/status、/api/status/detail | 配对认证、健康检查、平台信息 |
| 文件系统 | /api/fs/read、/api/fs/write、/api/fs/list、/api/fs/delete、/api/files/upload | 文件读写、目录操作、上传 |
| 命令执行 | /api/exec、/api/exec/stop | 异步执行、等待结果、停止进程 |
| MCP | /api/mcp/tools、/api/mcp/call、/api/mcp/servers/* | 工具发现与调用 |
| Skill | /api/skill/list、/api/skill/run、/api/skill/import* | 技能管理与执行 |
| 实时输出 | WebSocket | 命令执行的实时流式输出 |
通信安全机制包括：
- 仅允许 Chrome 扩展来源跨域访问。
- 需认证的接口使用
Authorization: Bearer <token>。 - 配对码一次性使用，已配对后不再下发敏感信息。
- 心跳接口仅刷新在线状态，不泄露宿主敏感信息。
sequenceDiagram participant UI as "扩展侧边栏" participant Client as "LocalAgentClient" participant Server as "Agent 服务器" UI->>Client : 发起配对请求 Client->>Server : POST /api/pair Server-->>Client : 返回 token Client->>Server : GET /api/status Server-->>Client : 返回版本与平台信息 UI->>Client : 调用文件/命令/MCP/Skill/RAG Client->>Server : 带 Bearer Token 的 HTTP 请求 Server-->>Client : 返回结构化结果 Client-->>UI : 渲染结果或错误提示
图表来源
- src/background/local-agent-client.js#L40-L93
- src/background/local-agent-client.js#L275-L330
- agent/src/server.js#L471-L548
章节来源
- src/background/local-agent-client.js#L40-L93
- src/background/local-agent-client.js#L275-L330
- agent/src/server.js#L471-L548
版本同步策略
项目采用“扩展端与 Agent 端版本号保持同步”的策略：
- 扩展端版本定义在根
package.json和manifest.json中。 - Agent 端版本定义在
agent/package.json中。 - 构建产物中的版本信息来自
src/config/version.json。 - CI 通过
.github/workflows/release.yml构建扩展 zip 并发布到 GitHub Releases。
建议维护者：
- 升级版本时同步更新扩展端与 Agent 端版本号。
- 发布前确认
npm run build:silent能成功构建。 - 用户安装时应优先选择与扩展版本匹配的 Agent 版本。
章节来源
- package.json#L1-L10
- manifest.json#L1-L10
- agent/package.json#L1-L10
- src/config/version.json#L1-L7
- .github/workflows/release.yml#L55-L127
常见故障排查
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 侧边栏打不开 | Service Worker 被终止或消息未正确传递 | 重新打开侧边栏，检查 background 与 side panel 消息 |
| Agent 显示未配对 | 未输入配对码或 Agent 未启动 | 启动 Agent，复制配对码到选项页 → Agent |
| 文件操作失败 | 路径不在允许范围或 Agent 不可达 | 检查工作目录、允许路径、Agent 是否运行 |
| 命令执行无输出 | WebSocket 连接断开或超时 | 查看命令执行日志，确认 Agent 进程存活 |
| 知识库不可用 | RAG 依赖未安装或 Node 版本不满足 | 检查 Node.js 版本，按提示恢复 RAG 依赖 |
| 主题异常 | 样式未使用 CSS 变量 Token 体系 | 遵循主题 Token 规范，避免硬编码色值 |
章节来源
- src/background/local-agent-client.js#L393-L443
- agent/src/server.js#L471-L548
- agent/src/server.js#L555-L603
开源协议、贡献方式与社区支持
- 开源协议：MIT License。
- 贡献方式：欢迎提交 PR，建议在动手前阅读架构总览文档。
- 社区支持：GitHub Discussions 和 Issues，每个 Issue 会在 24 小时内回复。
- 文档渠道：中文文档、英文文档、Wiki、文档站和产品介绍文档。
章节来源
结论
AI Helper 的核心价值在于把“聊天型 AI”升级为“可操作、可编排、可审计”的浏览器智能助手。其双进程架构清晰分离了浏览器上下文和本地系统能力，既降低了扩展端的权限风险，又保留了强大的本地执行能力。对于初学者，可以从网页信息提取和表单自动化入手；对于有经验的开发者，可以深入 MCP、Skill、RAG、多 Agent 协作和 Agent 安全策略。
在使用时，请始终注意：
- 优先通过官方渠道安装扩展和 Agent。
- 保持扩展端与 Agent 端版本一致。
- 理解 Service Worker 生命周期和 Agent 进程重启约束。
- 使用内置的安全策略、回收站和审计日志保护本地数据。