AI Helper 文档中心

主题

整体架构概览 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性特征
  8. 故障排查指南
  9. 结论
  10. 附录：版本同步与部署拓扑

引言 ​

本文件面向 AI Helper 系统的整体架构，重点解释双进程设计：**Chrome 扩展端（Manifest V3 Service Worker，版本 2.3.1）与独立 Node.js Agent 服务（版本 2.3.1）**的职责分离、协作方式、安全边界、保活机制、进程管理以及版本同步策略。

该架构的核心决策是：

  • 把浏览器上下文中的 UI 编排、工具调度、会话状态和页面交互放在 Chrome 扩展的 MV3 Service Worker 中；
  • 把本地文件系统访问、系统命令执行、长期记忆、RAG 索引、MCP 工具注册等需要操作系统权限或较重计算能力的逻辑交给独立 Agent 进程；
  • 两端通过本地 HTTP/WebSocket 接口通信，并使用 Bearer Token + Origin 白名单做基础隔离；
  • 版本号在扩展包与 Agent npm 包中保持一致，由 GitHub Actions Release 工作流统一构建和发布。

项目结构 ​

仓库采用“扩展根目录 + agent 子目录”的双工程结构：

  • 扩展根目录包含 Manifest、Vite 构建配置、background Service Worker、side panel、options、content script、shared 共享模块、测试脚本；
  • agent 子目录是一个独立的 Node.js npm 包，提供 ai-helper-agent CLI、HTTP+WebSocket 服务器、文件与命令执行、MCP、Skill、Memory/RAG 等能力；
  • .github/workflows/release.yml 负责构建扩展产物并生成 GitHub/Gitee Release。
graph TB
A["用户浏览器"] --> B["Chrome 扩展<br/>Manifest V3 Service Worker"]
B --> C["侧边栏界面<br/>side_panel.html"]
B --> D["内容脚本<br/>content scripts"]
B --> E["Agent 客户端<br/>local-agent-client.js"]
E --> F["本地 HTTP/WebSocket<br/>Agent 服务"]
F --> G["文件系统"]
F --> H["系统命令执行器"]
F --> I["长期记忆与 RAG"]
F --> J["MCP 工具注册中心"]
F --> K["Skill 注册中心"]

图表来源

章节来源

核心组件 ​

组件职责关键实现位置
Chrome 扩展入口声明 MV3 Service Worker、权限、Side Panel、Content Script、快捷键、Action 图标manifest.json
Background Service Worker会话管理、ReAct 循环、工具调度、面板可见性、保活连接、自动续跑、通知src/background/index.js
Agent 客户端封装配对、HTTP 请求、WebSocket、文件操作、命令执行、MCP、RAG 调用src/background/local-agent-client.js
工具执行层定义内置工具、网络访问控制、截图、快照编排、Agent 工具路由src/background/tool-executor.js
状态与取消控制按 sessionId 管理取消、AbortController、keepalive 端口、实例身份src/background/state.js
Agent CLIstart/stop/restart/status/paircode/config/update/uninstall/autostartagent/bin/agent.js
Agent 服务器HTTP 路由、认证、CORS、文件上传、命令执行、MCP、Skill、Memory/RAG、日志agent/src/server.js
主题 Token亮色/暗色 CSS 变量体系，WCAG AA 对比度校验src/shared/theme.css
版本元数据扩展版本号、标签、提交 ID、发布时间src/config/version.json
CI 发布流程构建扩展 zip、创建 GitHub Release、同步 Gitee、上传附件.github/workflows/release.yml

章节来源

架构总览 ​

AI Helper 的整体运行边界可以划分为四层：

  1. 用户界面层：Chrome 扩展 Action、Side Panel、Options 页面、Content Script 注入的页面工具。
  2. 扩展后台服务层：MV3 Service Worker，负责会话、工具调度、UI 状态、保活、通知、自动恢复。
  3. Agent 服务层：Node.js 进程，暴露本地 HTTP/WebSocket API，提供文件、命令、记忆、RAG、MCP、Skill 能力。
  4. 外部系统与 API 层：操作系统文件系统、Shell、模型提供商、MCP Server、RAG 向量存储、npm 源。
graph TB
subgraph "用户界面层"
UI_Action["扩展 Action"]
UI_Panel["侧边栏界面"]
UI_Options["设置页"]
UI_Content["网页内容脚本"]
end
subgraph "扩展后台服务层"
SW["Service Worker<br/>background/index.js"]
Tools["工具执行器<br/>tool-executor.js"]
State["状态与保活<br/>state.js"]
Client["Agent 客户端<br/>local-agent-client.js"]
end
subgraph "Agent 服务层"
CLI["CLI 进程管理<br/>agent/bin/agent.js"]
Server["HTTP/WebSocket 服务器<br/>agent/src/server.js"]
FS["文件系统"]
Exec["命令执行器"]
Memory["长期记忆"]
RAG["RAG 检索"]
MCP["MCP 工具"]
Skill["Skill 技能"]
end
subgraph "外部系统与 API 层"
OS["操作系统"]
Models["模型 API"]
NPM["npm 源"]
MCP_Server["外部 MCP Server"]
end
UI_Action --> SW
UI_Panel --> SW
UI_Options --> SW
UI_Content --> SW
SW --> Tools
Tools --> Client
Client --> Server
CLI --> Server
Server --> FS
Server --> Exec
Server --> Memory
Server --> RAG
Server --> MCP
Server --> Skill
Exec --> OS
MCP --> MCP_Server
RAG --> Models
Server --> NPM

图表来源

详细组件分析 ​

Chrome 扩展端：MV3 Service Worker 生命周期与保活 ​

MV3 Service Worker 不是常驻进程：当没有活跃任务时，Chrome 可能终止它；当被唤醒后，需要重建定时任务、恢复面板状态、清理过期 checkpoint。

关键约束与实现：

  • Service Worker 入口为 src/background/index.js，由 manifest 声明。
  • 启动时重建闹钟、迁移旧格式 Agent 配置、清理过期 ReAct checkpoint。
  • 通过 side panel 建立的 chrome.runtime.connect 长连接作为保活手段，防止 API 调用期间 SW 被判定空闲。
  • keepalive 端口按 sessionId 注册，支持重连检测、实例身份上报、SW 重启检测、面板断开延迟复核。
  • 侧边栏打开/关闭、全局/标签页绑定模式、Tab 分组、快捷键 toggle 都做了手势上下文保护。
sequenceDiagram
participant User as "用户"
participant Panel as "侧边栏"
participant SW as "Service Worker"
participant DB as "IndexedDB"
participant Agent as "Agent 服务"
User->>Panel : "打开侧边栏"
Panel->>SW : "建立 keepalive 连接"
SW->>SW : "注册 keepalive 端口"
Panel->>SW : "上报实例身份 windowId/hostTabId"
SW-->>Panel : "返回宿主 tab 权威值"
User->>SW : "发起工具调用"
SW->>Agent : "HTTP/WebSocket 请求"
Note over SW,Agent : "长连接存在时，SW 不易被系统回收"
SW->>DB : "保存 ReAct checkpoint"
SW->>SW : "闹钟触发自动续跑"
SW->>DB : "从 checkpoint 恢复会话"

图表来源

章节来源

Agent 服务：进程管理与运行时约束 ​

Agent 服务是一个独立 Node.js 进程，默认监听本地地址，对外暴露 HTTP 和 WebSocket 接口。

进程管理要点：

  • CLI 入口 agent/bin/agent.js 支持前台和后台模式。
  • 后台模式使用 spawn 拉起真实服务进程，写入 PID 文件，并通过轮询 /api/status 健康检查。
  • stop/restart 会先尝试优雅关闭，再回退到 SIGTERM/taskkill。
  • _restart-helper 是两阶段重启包装器：等待旧进程退出、端口释放，再启动新进程。
  • 服务端 /api/shutdown 写 .stopped 标记阻止 autostart 自动拉起。
  • 服务端 /api/agent/update 可触发 npm install -g ai-helper-agent@latest，失败不重启，成功则两阶段重启。
flowchart TD
Start(["用户或扩展触发更新"]) --> CheckRunning["检查 Agent 是否运行"]
CheckRunning --> Running{"已运行？"}
Running --> |是| GracefulStop["调用 /api/shutdown"]
Running --> |否| SkipStop["跳过优雅关闭"]
GracefulStop --> WaitExit["等待进程退出"]
SkipStop --> KillPID["读取 PID 并终止"]
WaitExit --> KillPID
KillPID --> InstallNpm["执行 npm 安装最新版本"]
InstallNpm --> InstallOk{"安装成功？"}
InstallOk --> |否| ReportFail["报告更新失败，保持老进程"]
InstallOk --> |是| SpawnHelper["spawn _restart-helper"]
SpawnHelper --> OldExit["等待旧进程退出"]
OldExit --> PortFree["等待端口释放"]
PortFree --> NewStart["启动新 Agent 进程"]
NewStart --> HealthCheck["健康检查"]
HealthCheck --> Done(["完成"])

图表来源

章节来源

扩展端与 Agent 端的通信契约 ​

扩展端通过 local-agent-client.js 封装所有 Agent 接口，包括：

  • 配对与会话：/api/pair、/api/status、/api/status/detail
  • 文件系统：读、写、列表、删除、搜索、上传、下载
  • 命令执行：异步执行、等待结果、停止、detach
  • MCP：工具列表、调用、Server 管理
  • RAG：知识库集合、检索、文档处理

认证与安全：

  • 需认证的请求携带 Authorization: Bearer <token>。
  • Agent 服务端对非 /api/pair、/api/status 等公开接口强制校验 token。
  • CORS 仅放行 chrome-extension:// 来源，避免恶意网页跨域读取响应。
  • 文件路径、命令执行、上传大小、body 大小均有安全检查。
sequenceDiagram
participant Panel as "侧边栏"
participant Executor as "工具执行器"
participant Client as "Agent 客户端"
participant Server as "Agent 服务器"
Panel->>Executor : "调用 Agent 相关工具"
Executor->>Client : "构造请求 path/body/method"
Client->>Client : "读取 pairedAgents + activeAgentId"
Client->>Server : "POST /api/fs/read 或 /api/exec"
Server->>Server : "校验 Authorization + Origin"
Server-->>Client : "返回 JSON 结果"
Client-->>Executor : "附加 httpStatus 并返回"
Executor-->>Panel : "渲染结果或错误"

图表来源

章节来源

安全隔离机制 ​

系统的安全边界体现在多个层面：

  1. 浏览器扩展边界：Manifest 声明最小权限，Content Security Policy 限制脚本来源。
  2. CORS 白名单：Agent 服务端只允许 chrome-extension:// 来源跨域读取响应。
  3. Token 认证：除配对和健康检查外，所有敏感接口要求 Bearer Token。
  4. 路径与命令校验：Agent 端使用 checkPath、checkCommand 等安全函数。
  5. 文件大小与 body 限制：JSON body 最大 200MB，上传流式接口也有上限。
  6. 进程隔离：命令执行通过子进程，Agent 提供 kill、detach、超时控制。
  7. 更新互斥：Agent 更新与 RAG 依赖安装互斥，避免并发写 node_modules。
flowchart TD
Request["来自浏览器的请求"] --> OriginCheck["Origin 是否为 chrome-extension://"]
OriginCheck --> |否| BlockCORS["不返回 Access-Control-Allow-Origin"]
OriginCheck --> |是| AllowCORS["允许扩展跨域读取"]
AllowCORS --> AuthCheck["是否携带有效 Bearer Token"]
AuthCheck --> |否| Return401["返回未认证"]
AuthCheck --> |是| PathCmdCheck["路径/命令安全检查"]
PathCmdCheck --> SizeLimit["body/文件大小限制"]
SizeLimit --> Execute["执行文件/命令/MCP/Skill/RAG"]

图表来源

章节来源

主题与国际化 ​

  • 主题采用 CSS 变量 Token 体系，支持亮色、暗色、跟随系统三态，暗黑模式经过对比度审计。
  • i18n 覆盖两层：扩展端 _locales/ 与 agent 端 agent/src/locales；背景脚本、工具执行器、Agent 客户端均注册翻译命名空间。
  • 文档示例不应体现缓存写法，UI 名称应在渲染时动态查询 i18n。

章节来源

依赖关系分析 ​

扩展端与 Agent 端的依赖关系如下：

graph LR
Manifest["manifest.json"] --> BGIndex["background/index.js"]
BGIndex --> ToolExecutor["tool-executor.js"]
BGIndex --> LocalAgentClient["local-agent-client.js"]
BGIndex --> State["state.js"]
LocalAgentClient --> AgentServer["agent/src/server.js"]
AgentCLI["agent/bin/agent.js"] --> AgentServer
AgentServer --> FS["文件系统"]
AgentServer --> Exec["命令执行"]
AgentServer --> Memory["记忆"]
AgentServer --> RAG["RAG"]
AgentServer --> MCP["MCP"]
AgentServer --> Skill["Skill"]

图表来源

章节来源

性能与可靠性特征 ​

  • Service Worker 保活：通过 side panel 长连接维持 SW 存活，避免频繁重建导致会话丢失。
  • 自动续跑：基于 ReAct checkpoint 和 chrome.alarms，SW 被回收后可自动恢复未完成任务。
  • 消息截断：chrome.runtime.sendMessage 有 64MiB 限制，大日志会被截断但保留子任务计划条目。
  • Agent 健康检查：CLI 启动后台服务后轮询 /api/status，确保服务真正就绪。
  • 更新互斥：Agent 更新与 RAG 安装互斥，避免并发破坏依赖。
  • 超时控制：HTTP 请求、WebSocket、命令执行、npm 安装均有超时保护。
  • 主题性能：CSS Token 在 :root 定义一次，暗色覆盖按需切换，减少重复样式计算。

[本节为通用性能讨论，不直接分析具体代码行]

故障排查指南 ​

常见故障点与建议：

  1. Service Worker 被终止：检查 side panel 是否仍保持 keepalive 连接；查看控制台是否有 SW_RESTARTED 或 checkpoint 恢复日志。
  2. Agent 未配对：确认扩展设置中已完成配对，且 Agent 服务正在运行；检查 /api/status 是否可达。
  3. CORS 拦截：确认请求来源是 chrome-extension://，不要从普通网页直接访问 Agent 接口。
  4. Token 无效：检查扩展存储中的 pairedAgents 是否包含有效 token；必要时重新配对。
  5. Agent 更新失败：查看 npm 安装输出；若失败，Agent 不会重启，应手动执行更新命令。
  6. RAG 依赖缺失：Agent 启动时会检测 RAG 可用性，失败时可能自动恢复依赖；若仍不可用，检查 Node 版本和网络源。
  7. 主题颜色异常：确认 data-theme 属性是否正确设置，避免硬编码色值，优先使用 CSS Token。

章节来源

结论 ​

AI Helper 的双进程架构将浏览器上下文中的交互与系统级能力解耦：

  • Chrome 扩展端负责用户体验、会话编排、工具调度和安全边界；
  • Agent 端负责本地资源访问、命令执行、知识检索和可扩展工具生态；
  • 两端通过标准化 HTTP/WebSocket 接口协作，配合 Token 认证和 CORS 白名单保障安全；
  • Service Worker 的生命周期约束通过 keepalive、checkpoint、闹钟自动续跑缓解；
  • Agent 进程通过 CLI、健康检查、两阶段重启、更新互斥提升可靠性；
  • 版本同步由 GitHub Actions Release 工作流统一管理，扩展与 Agent 版本号保持一致。

[本节为总结性内容，不直接分析具体代码行]

附录：版本同步与部署拓扑 ​

当前版本信息：

  • 扩展包版本：2.3.1
  • Agent npm 包版本：2.3.1
  • 扩展版本元数据包含 tag、commitId、publishedAt

发布流程：

  1. 推送 v* 标签或手动触发 Release 工作流。
  2. GitHub Actions 安装依赖、构建扩展、验证 dist/manifest.json。
  3. 打包扩展为 zip，排除 sourcemap。
  4. 创建 GitHub Release，附带安装说明。
  5. 同步 tag 到 Gitee，创建或更新发行版说明。
  6. 上传 zip 附件到 Gitee Release。
flowchart TD
PushTag["推送 v* 标签或手动触发"] --> Build["npm ci + npm run build"]
Build --> Verify["验证 dist/manifest.json"]
Verify --> Package["打包扩展 zip"]
Package --> GHRelease["创建 GitHub Release"]
GHRelease --> SyncGitee["同步 tag 到 Gitee"]
SyncGitee --> PublishGitee["创建/更新 Gitee 发行版说明"]
PublishGitee --> AttachZip["上传 zip 附件"]
AttachZip --> Done(["发布完成"])

图表来源

章节来源