主题
系统架构设计
本文引用的源码文件
本文引用的文件
目录
引言
本架构文档面向 AI Helper 2.3.1 的双进程系统：Chrome 扩展端（Manifest V3 Service Worker，位于 src/）与独立本地 Agent 服务（Node.js，入口为 agent/src/server.js）。两端版本号保持同步，通过 HTTP 与 WebSocket 通信契约协作。扩展端负责用户界面、浏览器能力、会话编排和 ReAct 执行循环；Agent 端提供文件系统、命令执行、MCP 工具、技能、长期记忆与 RAG 等本地能力。
关键约束包括：
- MV3 Service Worker 可被 Chrome 空闲回收，必须通过 keepalive 长连接保活，并通过 checkpoint 实现自动续跑。
- 扩展端与 Agent 端的认证基于配对码 + Bearer Token，所有需认证接口均要求
Authorization: Bearer <token>。 - Agent 端修改源码后必须重启进程，新接口才生效。
- 安全边界由扩展权限模型、CORS 白名单、路径沙箱、命令分级策略共同构成。
项目结构
仓库采用“扩展端 + 独立 Agent 包”的双根结构：
- 扩展端根目录包含 Manifest、Vite 构建配置、background、content、side_panel、options、shared、storage 等模块。
- Agent 子目录是一个独立的 npm 包
ai-helper-agent，提供 CLI、HTTP/WebSocket 服务器、安全控制、MCP、Skill、RAG、Memory 等子系统。
graph TB subgraph "Chrome 扩展端" M["manifest.json"] SW["Service Worker<br/>src/background/index.js"] SP["Side Panel<br/>src/side_panel/*"] CT["Content Script<br/>src/content/*"] SH["共享层<br/>src/shared/*"] end subgraph "本地 Agent 服务" AGP["agent/package.json"] SRV["HTTP/WebSocket 服务器<br/>agent/src/server.js"] AUTH["认证模块<br/>agent/src/auth.js"] SEC["安全沙箱<br/>agent/src/security.js"] end M --> SW SP --> SW CT --> SW SW --> SH SW --> |"HTTP /api/*"<br/>"WebSocket /ws/*"| SRV SRV --> AUTH SRV --> SEC
图表来源
- manifest.json#L1-L76
- src/background/index.js#L1-L120
- agent/src/server.js#L1-L60
- agent/package.json#L1-L20
章节来源
核心组件
- Chrome 扩展端 Service Worker：作为扩展后台进程，承担消息路由、侧边栏生命周期、ReAct 循环调度、工具预筛选、Token 记录、自动续跑、通知与面板可见性判定。
- 本地 Agent 客户端：封装与 Agent 的 HTTP/WebSocket 调用，管理多代理配对、可达性缓存、请求超时、语言头、Bearer Token 注入。
- Agent 服务端：提供配对、健康检查、文件操作、命令执行、MCP、Skill、RAG、Memory 等 API，并实现 CORS、认证、限流、重启/更新流程。
- 安全与认证模块：Agent 端维护配对码轮换、Token 校验、路径白名单、硬阻止目录、符号链接防护、命令分级与安全日志。
- UI 主题与国际化：扩展端使用 CSS Token 体系支持亮/暗/跟随系统三态；i18n 覆盖扩展
_locales/与 Agentagent/src/locales。
章节来源
- src/background/index.js#L1-L120
- src/background/local-agent-client.js#L40-L98
- agent/src/server.js#L388-L448
- agent/src/auth.js#L30-L102
- agent/src/security.js#L62-L100
- src/shared/theme.css#L1-L10
架构总览
AI Helper 的整体交互分为三层：
- 用户界面层：Side Panel 与 Content Script 负责用户输入、页面上下文、截图、书签、历史、知识库选择等。
- 扩展后台层：Service Worker 维护会话状态、ReAct 循环、工具执行、Agent 客户端、通知与面板保活。
- 本地 Agent 层：提供文件系统、命令执行、MCP、Skill、RAG、Memory 等能力，并对访问进行安全校验。
sequenceDiagram participant UI as "Side Panel" participant BG as "Service Worker" participant AC as "Agent 客户端" participant AG as "Agent 服务" participant FS as "文件系统" participant EX as "命令执行器" UI->>BG : "发送聊天/工具调用" BG->>AC : "构造带 Bearer Token 的请求" AC->>AG : "HTTP /api/fs|/api/exec|/api/mcp|/api/rag" AG->>FS : "路径安全检查 + 读写" AG->>EX : "命令分级 + 超时控制" FS-->>AG : "结果" EX-->>AG : "stdout/stderr/exitCode" AG-->>AC : "JSON 响应或 WebSocket 流" AC-->>BG : "统一错误包装" BG-->>UI : "渲染结果/流式输出"
图表来源
- src/background/local-agent-client.js#L399-L443
- agent/src/server.js#L537-L548
- agent/src/security.js#L109-L160
章节来源
- src/background/index.js#L120-L218
- src/background/local-agent-client.js#L399-L443
- agent/src/server.js#L416-L448
详细组件分析
Chrome 扩展端 Service Worker 与保活机制
Service Worker 是 MV3 扩展的核心后台进程，具有以下职责：
- 初始化 i18n、定时任务、自动续跑、DB 自检、旧格式迁移。
- 管理 Side Panel 打开/关闭、作用域模式、Tab 分组、快捷键切换。
- 维护 keepalive 端口注册表，防止 SW 空闲被 Chrome 回收。
- 检测 SW 重启并通知 Side Panel，携带 checkpoint 元数据供恢复。
- 处理面板断开延迟复核，避免误报任务仍在执行。
flowchart TD
Start(["Service Worker 启动"]) --> Init["初始化 i18n/闹钟/DB 自检"]
Init --> Keepalive["注册 keepalive 端口监听"]
Keepalive --> Identity["接收实例身份 windowId/hostTabId"]
Identity --> DetectRestart{"是否重连且无活跃循环?"}
DetectRestart --> |是| NotifySW["发送 SW_RESTARTED + checkpoint"]
DetectRestart --> |否| WaitMsg["等待 Side Panel 消息"]
NotifySW --> WaitMsg
WaitMsg --> Disconnect{"keepalive 断开?"}
Disconnect --> |是| DelayCheck["延迟复核面板断开"]
DelayCheck --> NotifyPanel["必要时弹出桌面通知"]
NotifyPanel --> End(["结束"])
图表来源
章节来源
Agent 客户端与通信协议
Agent 客户端封装了扩展端对 Agent 的所有网络调用，包括：
- 多代理配置、可达性缓存、配对/解绑/切换。
- HTTP 请求统一注入
Authorization: Bearer <token>与Accept-Language。 - WebSocket 连接用于命令执行实时输出，Token 通过 URL 参数传递。
- MCP 工具列表、调用、Server 管理。
- RAG 知识库集合查询与检索。
classDiagram
class AgentClient {
+getAgentConfig()
+pairWithAgent(url, code, name)
+unpairAgent(id)
+switchActiveAgent(id)
+agentRequest(path, body, method, timeout)
+agentGet(path, timeout)
+uploadFile(file)
+execCommand(command, cwd, force, timeoutMs)
+createExecWebSocket(wsUrl, onMessage, onClose, onError)
+getMcpTools(serverId)
+callMcpTool(serverId, toolName, args)
+ragListCollections()
}
图表来源
- src/background/local-agent-client.js#L185-L212
- src/background/local-agent-client.js#L275-L330
- src/background/local-agent-client.js#L399-L443
- src/background/local-agent-client.js#L662-L728
章节来源
- src/background/local-agent-client.js#L40-L98
- src/background/local-agent-client.js#L399-L443
- src/background/local-agent-client.js#L662-L728
Agent 服务端与认证流程
Agent 服务端提供 HTTP 路由与 WebSocket 支持，核心流程包括：
- 配对接口
/api/pair：验证一次性配对码，返回 Bearer Token。 - 健康检查
/api/status：无需认证，仅返回平台信息。 - 认证拦截：除少数公开接口外，所有请求需携带
Authorization: Bearer <token>。 - 心跳
/api/heartbeat：刷新最后认证时间，维持插件在线状态。 - 重启/更新：受冷却时间与防重入保护，支持两阶段进程替换。
sequenceDiagram
participant Ext as "扩展端"
participant AC as "Agent 客户端"
participant S as "Agent 服务"
participant A as "认证模块"
Ext->>AC : "pairWithAgent(code)"
AC->>S : "POST /api/pair {code, extensionId}"
S->>A : "handlePairRequest(code, extensionId)"
A-->>S : "{success, token}"
S-->>AC : "{success, token}"
AC-->>Ext : "保存 token 到 storage"
Ext->>AC : "后续 API 调用"
AC->>S : "GET/POST ... Authorization : Bearer <token>"
S->>A : "verifyToken(token)"
A-->>S : "extId 或 null"
S-->>AC : "业务响应"
图表来源
章节来源
安全边界与沙箱隔离
Agent 端的安全策略包括：
- CORS 限制：仅允许
chrome-extension://<id>来源跨域读取响应。 - 路径沙箱：硬阻止
.ai-helper-agent敏感文件/目录，工作目录放行，其他路径需命中allowedPaths。 - 符号链接防护：使用
realpath解析真实路径后再做白名单与硬阻止检查。 - 命令分级：命令执行需经过安全分级与用户确认，支持强制模式与超时控制。
- 上传大小限制：JSON body 与 multipart 上传均有上限，防止内存耗尽。
flowchart TD
PathReq["文件路径请求"] --> Normalize["路径规范化"]
Normalize --> HardBlock{"是否命中硬阻止目录?"}
HardBlock --> |是| Deny["拒绝访问"]
HardBlock --> |否| WorkdirCheck{"是否在工作目录?"}
WorkdirCheck --> |是| Realpath["realpath 校验"]
Realpath --> Allowed["放行"]
WorkdirCheck --> |否| Allowlist["匹配 allowedPaths"]
Allowlist --> Realpath
Deny --> End(["结束"])
Allowed --> End
图表来源
章节来源
用户界面与后台交互
Side Panel 通过 chat-manager 协调聊天、流式输出、工具调用、知识库、书签、历史、导出等功能。Service Worker 负责：
- 接收 Side Panel 消息并路由到工具执行器。
- 维护 ReAct 循环、子任务、取消控制、AbortController。
- 通过 keepalive 端口向发起实例定向发送澄清/确认对话框。
- 处理面板断开后的延迟通知，避免误判任务状态。
sequenceDiagram participant SP as "Side Panel" participant BG as "Service Worker" participant TE as "工具执行器" participant AC as "Agent 客户端" SP->>BG : "CALL_API / CHAT_SEND" BG->>TE : "preselect + execute tool" TE->>AC : "HTTP/WebSocket 调用" AC-->>TE : "结果/流" TE-->>BG : "工具结果/错误" BG-->>SP : "渲染消息/执行日志" Note over BG,SP : "keepalive 端口用于定向澄清/确认"
图表来源
- src/side_panel/chat-manager.js#L1-L50
- src/background/tool-executor.js#L1-L23
- src/background/state.js#L227-L305
章节来源
- src/side_panel/chat-manager.js#L1-L50
- src/background/tool-executor.js#L1-L23
- src/background/state.js#L227-L305
依赖关系分析
扩展端与 Agent 端的依赖关系如下：
- manifest.json 声明 MV3 Service Worker 入口、权限、内容脚本、侧边栏、命令与图标。
- src/background/index.js 依赖 state、tool-executor、local-agent-client、scheduler、notifier、panel-visibility 等模块。
- agent/src/server.js 依赖 auth、security、executor、mcp、skill、rag、memory、logger 等子系统。
- agent/package.json 定义 npm 包名、版本、CLI 入口、依赖与引擎要求。
graph LR M["manifest.json"] --> SW["src/background/index.js"] SW --> ST["state.js"] SW --> TE["tool-executor.js"] SW --> AC["local-agent-client.js"] AC --> AG["agent/src/server.js"] AG --> AU["auth.js"] AG --> SE["security.js"]
图表来源
- manifest.json#L47-L49
- src/background/index.js#L1-L20
- agent/src/server.js#L1-L56
- agent/package.json#L1-L10
章节来源
- manifest.json#L1-L76
- src/background/index.js#L1-L20
- agent/src/server.js#L1-L56
- agent/package.json#L1-L10
性能与可扩展性
- Service Worker 保活：通过 keepalive 长连接防止空闲回收，结合闹钟与 checkpoint 实现自动续跑，避免长时间任务中断。
- 请求超时与 AbortController：扩展端为每个会话创建 AbortController，支持用户取消与工具级终止等待。
- Agent 端限流与防重入：重启/更新接口有冷却时间与操作进行中标志，防止 DoS 与并发写冲突。
- 主题与国际化：CSS Token 体系支持亮/暗主题，i18n 覆盖扩展与 Agent 两端，避免硬编码色值与文案。
- 可扩展点：MCP 工具注册、Skill 加载、RAG 索引、Memory 服务均可按需启用或禁用，不影响核心文件与命令执行。
[本节为通用指导，不直接分析具体文件]
故障排查指南
常见故障与定位建议：
- Side Panel 无法打开：检查 Service Worker 是否被回收，确认 keepalive 端口是否正常建立；查看
chrome.sidePanel.open()是否在用户手势同步栈内调用。 - Agent 未配对：确认
/api/pair是否成功，检查配对码是否过期或被锁定；查看agent/src/auth.js中的失败计数与锁定逻辑。 - 请求超时：检查
local-agent-client.js中的超时设置与网络可达性；确认 Agent 服务是否运行在预期端口。 - 路径访问被拒：检查
agent/src/security.js的路径白名单与硬阻止目录；确认工作目录与allowedPaths配置。 - SW 重启导致任务中断：查看 Side Panel 是否收到
SW_RESTARTED消息，并根据 checkpoint 元数据决定是否继续执行。
章节来源
- src/background/index.js#L140-L218
- agent/src/auth.js#L138-L179
- src/background/local-agent-client.js#L399-L443
- agent/src/security.js#L109-L160
结论
AI Helper 2.3.1 采用清晰的双进程架构：Chrome 扩展端负责用户交互与任务编排，Agent 端提供本地能力与安全控制。通过 keepalive 保活、checkpoint 续跑、Bearer Token 认证、路径沙箱与命令分级，系统在可用性、安全性与可扩展性之间取得平衡。未来可在 MCP 工具、Skill、RAG 与 Memory 模块上进一步扩展，同时保持 MV3 Service Worker 的生命周期约束与安全边界不变。
[本节为总结性内容，不直接分析具体文件]