开发者指南

本文引用的源码文件

本文引用的文件

简介

AI Helper 是一个双进程架构的开源浏览器助手：Chrome 扩展端（Manifest V3，src/，版本 2.3.1）负责页面交互、侧边栏 UI、工具调度与本地 Agent 通信；独立 Node.js 代理端 Agent（agent/src/server.js，npm 包名 ai-helper-agent，版本 2.3.1）提供本地文件读写、系统命令执行、长期记忆、RAG 知识库、Skill 系统与 MCP 协议扩展。两端版本号保持一致，文档以 2.3.1 为准。

官方安装渠道为 Chrome Web Store、Microsoft Edge Add-ons 或 GitHub Releases 自动构建产物；源码构建仅面向开发者。Agent 源码修改后必须重启进程，新接口才生效。

章节来源

项目结构

仓库采用“扩展端 + Agent 子包”的双根结构：

根目录：Chrome 扩展源码、Vite 构建配置、ESLint/Vitest/Playwright 测试配置、发布脚本与文档资源。
agent/：独立的 Node.js 服务包，包含 HTTP/WebSocket 服务器、安全策略、MCP 注册表、Skill 系统、长期记忆与 RAG。
src/：扩展端模块，按运行上下文划分为 background、content、side_panel、options、offscreen、shared、storage。
test/：扩展端单元测试与 Playwright e2e 测试。
agent/test/：Agent 端单元测试、集成测试与 Skill 示例。
scripts/：构建修复、打包、主题审计、图标生成等自动化脚本。
docs/、icons/、libs/、styles/、_locales/：静态资源与多语言文案。

graph TB
Root["仓库根目录"]
Src["src/ 扩展端源码"]
Agent["agent/ Node.js 代理端"]
Test["test/ 扩展端测试"]
AgentTest["agent/test/ Agent 端测试"]
Scripts["scripts/ 自动化脚本"]
Docs["docs/ 产品文档"]
Manifest["manifest.json 扩展清单"]
Vite["vite.config.js 构建配置"]
Eslint["eslint.config.js 代码检查"]
Vitest["vitest.config.js 单测配置"]
Playwright["playwright.config.js e2e 配置"]
Root --> Manifest
Root --> Vite
Root --> Eslint
Root --> Vitest
Root --> Playwright
Root --> Src
Root --> Agent
Root --> Test
Root --> AgentTest
Root --> Scripts
Root --> Docs

图表来源

章节来源

开发环境搭建

前置要求

Node.js：扩展端依赖由 npm 管理；Agent 端要求 Node.js >=18.0.0，RAG 功能推荐 >=22.13.0。
浏览器：Chrome / Edge / Chromium 114+，支持 Side Panel API。
可选系统工具：Agent 的文件搜索优先使用 fd 与 rg（ripgrep），未安装时回退到 Node.js 实现。

依赖安装

扩展端依赖安装：

bash

npm install

Agent 端依赖安装（开发时建议全局安装以便 CLI 调试）：

bash

cd agent
npm install

若启用 RAG 知识库，可通过 Agent CLI 一键检测并安装可选依赖：

bash

ai-helper-agent rag status
ai-helper-agent rag install

章节来源

开发服务器启动

扩展端开发模式使用 Vite：

bash

npm run dev

Vite 默认监听 5173，HMR 通过 WebSocket 在 localhost:5173 推送更新。构建产物输出到 dist/，入口包括 background、content、side_panel、options。

Agent 端开发模式：

bash

cd agent
npm start

或前台调试：

bash

ai-helper-agent start

后台运行：

bash

ai-helper-agent start --background

加载扩展：

从 Chrome Web Store 或 Microsoft Edge Add-ons 安装。
开发者可从 GitHub Releases 下载自动构建 zip，解压后在 chrome://extensions/ 开启开发者模式并加载 dist/。
也可运行 npm run build 后加载 dist/。

章节来源

调试技巧

扩展端：打开 Chrome DevTools，分别调试 Service Worker（background）、Side Panel、Options 页面与 Content Script。
Agent 端：前台启动会实时输出文件操作、命令执行与安全拦截日志；生产场景使用后台模式。
配对流程：Agent 启动后终端显示 6 位配对码，在扩展设置页 “Agent” 标签粘贴完成配对。
断点调试：Node.js 调试器可直接附加 agent/bin/agent.js；扩展端可在 Vite HMR 下打断点。

章节来源

热重载配置

Vite 已启用 HMR，端口与协议配置如下：

开发服务器端口：5173
HMR 端口：5173
HMR 协议：ws
HMR 主机：localhost

注意：构建产物关闭 sourcemap，避免将源码与注释随扩展包发布；调试应直接查看 src/ 或使用测试套件。

章节来源

vite.config.js#L18-L32

代码规范与标准

ESLint 配置

项目使用基于 @antfu/eslint-config 的 ESLint 规则，并通过根级 eslint.config.js 显式纳入 agent/ 子包，避免历史遗留的忽略问题。当前规则重点禁止 debugger、重复参数、函数赋值与对象调用等基础错误。

扫描范围：

包含 src/ 与 agent/。
忽略 dist/**、libs/**、scripts/**、agent/node_modules/**、agent/dist/**。

章节来源

代码风格指南

模块类型：扩展端与 Agent 端均声明 "type": "module"，使用 ES Module 导入导出。
命名约定：文件名与模块职责对应，如 server.js、executor.js、tool-executor.js、memory-tools.js。
错误处理：Agent 端对请求体大小、JSON 解析、URL 解析、CORS、认证、命令执行、文件 I/O 进行分层保护；扩展端对 Service Worker 生命周期、面板状态、消息通道做降级处理。
国际化：扩展端使用 _locales/ 与 src/shared/i18n.js；Agent 端使用 agent/src/locales 与 agent/src/i18n.js。UI 名称应在渲染时动态查询 i18n，不应缓存硬编码文案。

章节来源

提交规范与代码审查流程

仓库 README 鼓励 PR 贡献，并要求在开始开发前阅读架构总览。虽然仓库未定义严格的 commit message 格式，但结合 ESLint 与测试脚本，建议遵循以下实践：

提交前运行 npm run lint 确保无 ESLint 错误。
提交前运行 npm run build:silent 验证构建可用。
提交前运行 npm run test 执行单元与 e2e 测试。
PR 描述应说明改动范围、影响模块、测试覆盖与风险点。
涉及 Agent 接口变更时，需同步确认扩展端调用方与 Agent 端路由。

章节来源

扩展开发指南

新工具开发

扩展端工具体系位于 src/background/tools/，由 tool-executor.js 统一调度，并通过 local-agent-client.js 与 Agent 通信。新增工具建议：

在 src/background/tools/ 中创建工具模块，封装浏览器能力或 Agent 调用。
在 tool-executor.js 中注册工具元数据与执行逻辑。
如需 Agent 能力，调用 /api/fs/*、/api/exec/*、/api/memory/*、/api/rag/*、/api/mcp/*、/api/skill/*。
为工具编写单元测试，放在 test/unit/ 下。
如涉及 UI，使用 src/shared/theme.css 中的 CSS Token，不硬编码色值。

章节来源

MCP 协议实现

Agent 端支持 Model Context Protocol（MCP），通过 agent/src/mcp/registry.js 自动发现并转发第三方 MCP Server 提供的工具。扩展端通过 loadMcpTools 获取 MCP 工具列表并参与工具预筛选。

开发 MCP Server 的步骤：

在 ~/.ai-helper-agent/config.json 的 mcpServers 中添加 server 配置，指定 id、name、command 与 enabled。
启动 Agent，Agent 会在启动时连接启用的 MCP Server。
通过 /api/mcp/status、/api/mcp/tools 查看状态与工具列表。
扩展端调用工具时，Agent 会将工具调用转发给对应 MCP Server。

章节来源

Skill 编写规范

Agent 端内置 Skill 系统，支持两类 Skill：

Workflow Skill：JSON/YAML 定义，直接执行。
Agent Skill：SKILL.md 定义，由 AI 在对话中自主触发。

Skill 目录位于 ~/.ai-helper-agent/skills/，SKILL.md 需包含 name、description、enabled、使用场景、核心能力、步骤与示例。扩展端通过 Skill 选择器与工具面板展示可用 Skill。

最佳实践：

description 明确“做什么”和“何时触发”。
步骤可复现，示例贴近真实工作流。
敏感操作应配合 Agent 的安全分级与用户确认机制。
使用 /api/skill/list、/api/skill/:name/run 等接口管理 Skill。

章节来源

agent/README.md#L290-L365

最佳实践

所有 Agent 能力调用都应考虑网络失败、超时、认证失效与服务端版本不匹配。
长任务使用 checkpoint 与自动续跑机制，避免 Service Worker 被回收导致中断。
工具调用前尽量使用工具预筛选减少模型 token 消耗。
界面文案一律走 i18n，避免硬编码中文。
样式使用 CSS Token，保持亮/暗/跟随系统三态一致。

章节来源

架构总览

AI Helper 采用双进程架构：

graph TB
Browser["浏览器"]
Extension["Chrome 扩展<br/>Service Worker + Side Panel + Options + Content Script"]
Background["background/index.js<br/>ReAct 循环、工具调度、会话恢复"]
Tools["tools/*<br/>浏览器与 Agent 工具"]
AgentClient["local-agent-client.js<br/>HTTP/WebSocket 客户端"]
AgentServer["agent/src/server.js<br/>HTTP Router + WebSocket"]
Security["security.js<br/>路径与命令安全"]
Executor["executor.js<br/>命令执行与进程树"]
Memory["memory/*<br/>长期记忆与注入"]
Rag["rag/*<br/>知识库检索"]
Mcp["mcp/*<br/>MCP 工具注册"]
Skill["skill/*<br/>Skill 加载与执行"]
Browser --> Extension
Extension --> Background
Background --> Tools
Background --> AgentClient
AgentClient --> AgentServer
AgentServer --> Security
AgentServer --> Executor
AgentServer --> Memory
AgentServer --> Rag
AgentServer --> Mcp
AgentServer --> Skill

图表来源

核心组件分析

扩展端背景脚本入口

src/background/index.js 是 Service Worker 入口，负责：

初始化 i18n 与定时任务闹钟。
注册自动续跑处理器，从 checkpoint 恢复 ReAct 循环。
清理过期 checkpoint 并校验数据库可用性。
维护 keepalive 端口，防止 SW 空闲被终止。
管理 Side Panel 打开/关闭、作用域模式与 tab 分组。
处理快捷键切换侧边栏，兼容冷启动与手势约束。
缓存 MCP 工具与 Skill Prompt，减少重复网络请求。

sequenceDiagram
participant User as "用户"
participant SW as "Service Worker"
participant Panel as "Side Panel"
participant DB as "IndexedDB"
participant Agent as "Agent 服务端"
User->>SW : 快捷键切换侧边栏
SW->>SW : 判断面板是否已打开
alt 面板未打开
SW->>Panel : open({tabId|windowId})
else 面板已打开
SW->>Panel : close({tabId|windowId})
end
User->>Panel : 发送任务
Panel->>SW : 消息通道
SW->>DB : 读取/保存 checkpoint
SW->>Agent : 调用工具或 Agent 接口
Agent-->>SW : 返回结果或流式输出
SW-->>Panel : 推送任务状态

图表来源

章节来源

Agent 服务端入口

agent/src/server.js 是 HTTP 与 WebSocket 服务器，负责：

启动 HTTP 服务，注册无需认证与需要认证的接口。
处理配对、健康检查、关闭、重启、更新。
解析 JSON body 与 multipart/form-data，限制请求体大小。
校验 CORS，仅放行 Chrome 扩展来源。
路由文件操作、命令执行、长期记忆、RAG、MCP、Skill。
记录审计日志，支持分类查询与自动清理。
管理进程树，防止孤儿进程。

flowchart TD
Start["服务器启动"] --> Init["加载配置<br/>初始化日志语言<br/>检测搜索工具与 RAG"]
Init --> Listen["监听 HTTP 端口"]
Listen --> Request["接收请求"]
Request --> Parse["解析 URL 与 Body"]
Parse --> Auth{"是否需要认证"}
Auth --> |否| Public["配对/状态/关闭"]
Auth --> |是| Secure["认证后接口"]
Public --> Route["路由分发"]
Secure --> Route
Route --> FS["文件操作"]
Route --> Exec["命令执行"]
Route --> Memory["长期记忆"]
Route --> Rag["RAG 知识库"]
Route --> Mcp["MCP 工具"]
Route --> Skill["Skill 系统"]
FS --> Log["写入审计日志"]
Exec --> Log
Memory --> Log
Rag --> Log
Mcp --> Log
Skill --> Log
Log --> Response["返回 JSON 响应"]

图表来源

章节来源

依赖关系分析

扩展端依赖

构建工具：Vite、CRXJS、静态资源复制插件。
测试工具：Vitest、Playwright、jsdom。
运行时依赖：DOMPurify、PDF.js、docx、xlsx、mammoth 等用于文档处理与内容提取。

Agent 端依赖

核心依赖：http、ws、archiver、zod、xlsx。
MCP SDK：@modelcontextprotocol/sdk。
RAG 可选依赖：vectra、@huggingface/transformers、pdf-parse、mammoth、officeparser、cheerio。

graph LR
Ext["扩展端 package.json"]
AgentPkg["agent/package.json"]
Vite["Vite 构建"]
CRX["CRXJS 插件"]
Vitest["Vitest 单测"]
Playwright["Playwright e2e"]
Http["Node http 模块"]
Ws["ws WebSocket"]
McpSdk["@modelcontextprotocol/sdk"]
RagDeps["RAG 可选依赖"]
Ext --> Vite
Ext --> CRX
Ext --> Vitest
Ext --> Playwright
AgentPkg --> Http
AgentPkg --> Ws
AgentPkg --> McpSdk
AgentPkg --> RagDeps

图表来源

章节来源

性能与调试

构建优化

Vite 构建关闭 sourcemap，避免发布源码与注释。
静态资源通过 vite-plugin-static-copy 复制到构建目录。
构建入口限定为 background、content、side_panel、options。

测试体系

扩展端单元测试：npm run test:unit，使用 Vitest，环境为 node，部分 content 测试通过 jsdom 环境。
e2e 测试：npm run test:e2e，使用 Playwright，默认 headless，CI 环境下允许重试。
Agent 端测试：使用 node --test，限定 test/unit 目录。
统一验证：npm run build:silent 调用 scripts/silent-build.js 执行构建并输出成功标志。

章节来源

调试建议

扩展端：使用 Chrome DevTools 的 Application 面板检查 IndexedDB、Storage、Service Worker 状态。
Agent 端：前台启动查看实时日志；生产环境查看 ~/.ai-helper-agent/logs/ 下的审计日志。
性能分析：Agent 端 /api/status/detail 返回内存、CPU、uptime 等资源使用情况。
问题定位：关注 Service Worker 保活、Side Panel 可见性、Agent 配对与认证、RAG 依赖可用性。

章节来源

常见问题与故障排除

扩展无法加载

确认已从 Chrome Web Store 或 GitHub Releases 安装。
开发者模式加载的是 dist/ 而非 src/。
检查 manifest 权限与 CSP 配置。

章节来源

Agent 无法配对

确认 Agent 已启动并显示 6 位配对码。
确认扩展设置页 “Agent” 标签已粘贴配对码。
检查防火墙与端口占用（默认 18910）。

章节来源

命令执行被拒绝

高危命令会被黑名单直接阻止。
灰色命令需要用户确认。
检查命令是否包含危险语法或绕过尝试。

章节来源

agent/README.md#L106-L139

RAG 功能不可用

检查 RAG 依赖是否安装：ai-helper-agent rag status。
若依赖缺失，执行 ai-helper-agent rag install。
查看 /api/rag/status 与 /api/rag/install/status。

章节来源

Service Worker 被回收

确认 side panel 通过 keepalive 端口保活。
检查自动续跑机制是否从 checkpoint 恢复。
避免长时间无响应的工具调用阻塞 SW。

章节来源

贡献指南

通过 GitHub Discussions 提问，Issues 报告问题。
提交 PR 前阅读架构总览，确保改动符合双进程契约。
新增功能需配套单元测试与 e2e 测试。
涉及 Agent 接口变更时，同步更新扩展端调用与文档。
遵守 ESLint 规则，提交前运行 lint 与构建脚本。

章节来源

附录：命令速查

扩展端命令

npm run dev：启动 Vite 开发服务器。
npm run build：构建扩展包。
npm run build:silent：静默构建，用于 CI 或自动化脚本。
npm run lint：执行 ESLint。
npm run test：运行单元与 e2e 测试。
npm run test:unit：运行 Vitest 单元测试。
npm run test:e2e：运行 Playwright e2e 测试。

章节来源

package.json#L6-L23

Agent 端命令

ai-helper-agent start：前台启动。
ai-helper-agent start --background：后台启动。
ai-helper-agent stop：停止服务。
ai-helper-agent restart：重启服务。
ai-helper-agent status：查看状态。
ai-helper-agent paircode：显示配对码。
ai-helper-agent config：查看配置。
ai-helper-agent rag status：检测 RAG 依赖。
ai-helper-agent rag install：安装 RAG 依赖。
ai-helper-agent update：检查并更新版本。

章节来源

agent/README.md#L47-L63

Markdown 渲染引擎

开发者指南 ​

目录 ​

简介 ​

项目结构 ​

开发环境搭建 ​

前置要求 ​

依赖安装 ​

开发服务器启动 ​

调试技巧 ​

热重载配置 ​

代码规范与标准 ​

ESLint 配置 ​

代码风格指南 ​

提交规范与代码审查流程 ​

扩展开发指南 ​

新工具开发 ​

MCP 协议实现 ​

Skill 编写规范 ​

最佳实践 ​

架构总览 ​

核心组件分析 ​

扩展端背景脚本入口 ​

Agent 服务端入口 ​

依赖关系分析 ​

扩展端依赖 ​

Agent 端依赖 ​

性能与调试 ​

构建优化 ​

测试体系 ​

调试建议 ​

常见问题与故障排除 ​

扩展无法加载 ​

Agent 无法配对 ​

命令执行被拒绝 ​

RAG 功能不可用 ​

Service Worker 被回收 ​

贡献指南 ​

附录：命令速查 ​

扩展端命令 ​

Agent 端命令 ​

开发者指南

目录

简介

项目结构

开发环境搭建

前置要求

依赖安装

开发服务器启动

调试技巧

热重载配置

代码规范与标准

ESLint 配置

代码风格指南

提交规范与代码审查流程

扩展开发指南

新工具开发

MCP 协议实现

Skill 编写规范

最佳实践

架构总览

核心组件分析

扩展端背景脚本入口

Agent 服务端入口

依赖关系分析

扩展端依赖

Agent 端依赖

性能与调试

构建优化

测试体系

调试建议

常见问题与故障排除

扩展无法加载

Agent 无法配对

命令执行被拒绝

RAG 功能不可用

Service Worker 被回收

贡献指南

附录：命令速查

扩展端命令

Agent 端命令