AI Helper 文档中心

主题

API 参考文档 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性
  8. 故障排查指南
  9. 版本管理与迁移
  10. 结论

引言 ​

本参考文档面向扩展开发者、Agent 集成方和 MCP/Skill/RAG 能力使用者，覆盖以下范围：

  • Chrome Extension API：权限模型、消息通信、侧边栏控制、Service Worker 生命周期约束。
  • Agent HTTP API：RESTful 接口规范、认证机制、错误码约定、文件上传与命令执行。
  • WebSocket 协议：命令流式输出连接、鉴权参数、事件语义。
  • MCP 协议：传输方式、工具发现与调用、注册表管理、语言与错误处理。
  • 内部 API：扩展端与 Agent 端的通信契约、数据交换格式、状态同步机制。
  • 使用示例、最佳实践、错误处理模式、版本兼容与迁移建议。

本项目采用双进程架构：Chrome 扩展端（Manifest V3，src/）与独立本地代理端 Agent（Node.js，agent/src/server.js）。两端版本号保持同步，当前以 2.3.1 为准。Agent 源码修改后必须重启进程，新接口才生效。

项目结构 ​

  • 扩展端入口与服务 Worker：manifest.json 声明 background service_worker 为 src/background/index.js；side panel 默认路径为 side_panel.html。
  • 扩展端后台逻辑：background/index.js 负责 Service Worker 保活、侧边栏开关、快捷键、面板可见性、自动续跑等；local-agent-client.js 封装与 Agent 的 HTTP/WebSocket 通信；tool-executor.js 动态加载 MCP/RAG 工具并路由到 Agent。
  • Agent 服务端：agent/src/server.js 提供 HTTP Router + WebSocket，承载配对、健康检查、文件、命令、MCP、Skill、Memory/RAG 等能力。
  • MCP 子系统：agent/src/mcp/client.js 实现多种传输（stdio/sse/streamableHttp/websocket），agent/src/mcp/registry.js 维护已连接 Server 与工具列表。
  • Memory/RAG：agent/src/memory/routes.js 暴露 /api/memory/* 业务端点；RAG 安装与探测在 agent/src/rag 下。
  • Skill 系统：agent/src/skill/registry.js 管理 Workflow/Agent Skill 的加载、启用、执行与 Prompt 注入。
  • 共享常量与工具定义：src/background/constants.js 与 src/shared/tools.js 提供内置工具分类、默认配置与 UI 映射。
graph TB
A["浏览器页面<br/>Side Panel"] --> B["Background Service Worker<br/>src/background/index.js"]
B --> C["Agent 客户端<br/>src/background/local-agent-client.js"]
C --> D["Agent HTTP 服务<br/>agent/src/server.js"]
D --> E["MCP 注册表<br/>agent/src/mcp/registry.js"]
D --> F["记忆/Memory 路由<br/>agent/src/memory/routes.js"]
D --> G["Skill 注册表<br/>agent/src/skill/registry.js"]
B --> H["工具执行器<br/>src/background/tool-executor.js"]
B --> I["常量与工具定义<br/>src/background/constants.js"]

图表来源

章节来源

核心组件 ​

  • Chrome Extension API 与权限
    • manifest.json 声明 MV3、permissions、host_permissions、content_scripts、background service_worker、side_panel、commands、action 等。
    • 关键权限包括 activeTab、storage、unlimitedStorage、sidePanel、scripting、bookmarks、history、downloads、notifications、tabs、tabGroups、cookies、offscreen、clipboardRead/Write、commands、alarms、debugger、webNavigation。
  • Background Service Worker 生命周期
    • 通过 keepalive port 维持 SW 存活；监听 sidePanel.onOpened/onClosed；快捷键切换侧边栏需用户手势上下文；SW 被回收后由闹钟恢复 ReAct checkpoint。
  • Agent HTTP API
    • 统一 JSON 响应体 { success, ... }，CORS 仅放行 chrome-extension:// 来源；/api/pair 无认证，其余多数接口需要 Authorization: Bearer <token>。
  • MCP 协议
    • 支持 stdio/sse/streamableHttp/websocket 四种传输；Server 连接后 listTools/callTool；扩展端动态注册 MCP 工具并压缩 schema。
  • Memory/RAG
    • /api/memory/* 提供 store/recall/manage/inject/reindex 等；embedding-config/test-embedding/vector-status 为配置与探活端点。
  • Skill 系统
    • 支持 Workflow JSON 与 Agent SKILL.md；可导入/删除/启用/禁用；Agent Skill 通过 prompt 注入给 AI，Workflow 可直接 run。

章节来源

架构总览 ​

扩展端通过 local-agent-client.js 向 Agent 发起 HTTP 请求或建立 WebSocket 连接；Background 将工具调用转发到 Agent 的文件、命令、MCP、Skill、Memory/RAG 等能力；Side Panel 负责聊天、流式渲染、任务恢复与交互确认。

sequenceDiagram
participant UI as "Side Panel"
participant BG as "Background"
participant AC as "AgentClient"
participant AG as "Agent Server"
participant MCP as "MCP Registry"
UI->>BG : 发送消息/触发工具
BG->>AC : 构造请求(携带 Bearer Token)
AC->>AG : HTTP POST/GET
AG-->>AC : JSON {success,...}
AC-->>BG : 返回结果
BG->>UI : 流式/最终结果
Note over BG,MCP : 动态注册 MCP 工具时从 Agent 拉取工具列表

图表来源

详细组件分析 ​

Chrome Extension API 与权限 ​

  • 权限清单
    • 页面访问：activeTab、tabs、webNavigation、cookies、history、bookmarks。
    • 存储与持久化：storage、unlimitedStorage、offscreen。
    • UI 与交互：sidePanel、notifications、clipboardRead/Write、commands、alarms。
    • 调试与网络：debugger、scripting。
  • Content Scripts
    • 匹配所有 URL，注入 libs/qrcode.min.js、libs/marked.min.js、src/content/index.js，CSS 样式 styles.css。
  • Background Service Worker
    • 入口 src/background/index.js；侧边栏行为 setPanelBehavior(openPanelOnActionClick=false)，手动 open/close。
    • 快捷键 _toggle_sidepanel 绑定 Ctrl+Shift+Y（mac 为 Command+Shift+Y）。
    • 侧边栏作用域：global 或 tab-specific；全局模式下所有 tab 可用面板，tab-specific 模式下仅显式打开的 tab 可见。
    • 窗口分组：可选自动将带面板的 tab 归入“AI Helper”分组，便于识别。
    • SW 保活：keepalive port 防止空闲被杀；SW 重启检测并通知 Side Panel。
    • 自动续跑：基于 reactCheckpoints 定时闹钟恢复中断任务，达到最大尝试次数后提示人工介入。
flowchart TD
Start(["扩展启动"]) --> Init["初始化 i18n/闹钟/DB自检"]
Init --> Keepalive["注册 keepalive port"]
Keepalive --> Panel["设置 sidePanel 行为与默认 path"]
Panel --> Scope["读取 sidePanelScope 并应用"]
Scope --> Events["监听 onOpened/onClosed/tabs/windows"]
Events --> Shortcut["注册快捷键 _toggle_sidepanel"]
Shortcut --> AutoResume["注册自动续跑闹钟处理器"]

图表来源

章节来源

Agent HTTP API 规范 ​

  • 通用响应体
    • 成功：
    • 失败：
    • 附加 httpStatus：扩展端在 fetch 响应后附加 HTTP 状态码，用于区分“文件不存在 404”与“Agent 离线/网络错误”。
  • CORS 策略
    • 仅允许 chrome-extension:// 来源跨域读取响应；OPTIONS 预检同样遵循该规则。
  • 认证机制
    • 除 /api/pair 与 /api/status 外，其他接口需在 Authorization 头携带 Bearer token。
    • /api/shutdown 对本地来源免认证，远程来源仍需认证。
  • 主要 REST 端点（扩展端注释汇总）
    • 配对与会话：POST /api/pair，GET /api/status，GET /api/status/detail
    • 文件系统：POST /api/fs/read/write/list/delete/search_files/search_content/files/upload
    • 浏览器：POST /api/browser/open
    • 命令执行：POST /api/exec，POST /api/exec/stop
    • MCP：GET /api/mcp/tools，POST /api/mcp/call，GET/POST/DELETE /api/mcp/servers，POST /api/mcp/servers/connect/disconnect，PUT /api/mcp/servers/toggle
    • Skill：GET /api/skill/list/detail，POST /api/skill/run/import/save-markdown/import-zip/import-url，DELETE /api/skill/delete，POST /api/skill/toggle，GET /api/skill/markdown/resource，GET /api/skill/agent-prompts/agent-prompt
    • 记忆：/api/memory/store/recall/manage/inject/reindex，以及 embedding-config/test-embedding/vector-status
  • 文件大小限制
    • JSON body 上限 MAX_BODY_SIZE=200MB；流式上传 /api/fs/upload-stream 也受相同上限保护。
  • 操作冷却与防重入
    • /api/agent/restart/update/shutdown 等敏感操作有 OPERATION_COOLDOWN_MS=10s 冷却，并发操作返回 409，频繁请求返回 429。
flowchart TD
Req["HTTP 请求"] --> Parse["解析 URL/Body"]
Parse --> Pair{"/api/pair ?"}
Pair --> |是| PairHandler["处理配对"]
Pair --> |否| Status{"/api/status ?"}
Status --> |是| StatusHandler["返回平台信息"]
Status --> |否| Auth{"Authorization Bearer ?"}
Auth --> |否| Err401["返回 401 noToken"]
Auth --> |是| Verify["verifyToken(extId)"]
Verify --> Valid{"有效 ?"}
Valid --> |否| Err403["返回 403 invalidToken"]
Valid --> Route["分发到具体端点"]
Route --> Resp["jsonResponse(success,...)"]

图表来源

章节来源

WebSocket 协议（命令执行流式输出） ​

  • 连接地址
    • 由扩展端根据 Agent 配置的 url 替换 wsUrl 中的本地地址（0.0.0.0/127.0.0.1/localhost → 实际 hostname），并在查询串追加 token。
  • 鉴权
    • 通过 URL 查询参数 token 传递 Bearer token；扩展端在创建连接前从 getAgentConfig() 获取。
  • 消息格式
    • 服务端推送 JSON 对象；若无法解析则回退为 raw 类型。
  • 生命周期
    • onopen：连接成功；onmessage：接收命令输出；onclose：连接关闭；onerror：连接错误。
  • 超时
    • 空闲超时由调用方统一管理，避免双重超时冲突。
sequenceDiagram
participant BG as "Background"
participant AC as "AgentClient"
participant WS as "WebSocket"
participant AG as "Agent Server"
BG->>AC : createExecWebSocket(wsUrl,onMessage,onClose,onError)
AC->>AC : 解析 config.url 并替换 localhost
AC->>WS : new WebSocket(token=...)
WS-->>AC : onopen
AC-->>BG : resolve(ws)
WS-->>AC : onmessage(JSON/raw)
AC-->>BG : onMessage(data)
WS-->>AC : onclose/onerror
AC-->>BG : onClose()/onError(error)

图表来源

章节来源

MCP 协议规范 ​

  • 传输方式
    • stdio：command/args/env/cwd；sse/streamableHttp：url+headers；websocket：url。
  • 连接流程
    • McpClient.connect() 创建 Client，选择 transport，连接后获取 serverInfo/capabilities，listTools 缓存 tools。
  • 工具调用
    • callTool(toolName,args) 返回 { success,content,raw } 或 { success:false,error }。
  • 注册表
    • initializeMcpRegistry() 启动时连接所有 enabled servers；getMcpServersStatus() 返回服务器状态与工具数量；getMcpTools(serverId?) 扁平化工具列表；callMcpTool(serverId,toolName,args) 转发调用。
  • 扩展端动态注册
    • tool-executor.js 从 Agent 拉取 MCP 工具，压缩 inputSchema（限制嵌套深度、参数数量、description 长度），注入 RAW_TOOLS/BUILTIN_TOOLS/TOOL_HANDLERS，并更新 storage.mcpTools。
classDiagram
class McpClient {
+serverId
+serverName
+connected
+tools
+serverInfo
+connect()
+callTool(toolName,args)
+disconnect()
+getStatus()
}
class Registry {
+initializeMcpRegistry()
+getMcpServersStatus()
+getMcpTools(serverId)
+callMcpTool(serverId,toolName,args)
+connectMcpServer(serverId)
+disconnectMcpServer(serverId)
+shutdownMcpRegistry()
}
Registry --> McpClient : "管理实例"

图表来源

章节来源

内部 API 接口（扩展端与 Agent 端） ​

  • 通信封装
    • agentRequest(path,body,method,timeoutMs) 统一添加 Authorization、Accept-Language，附加 httpStatus；agentGet(path,timeoutMs) 用于 GET。
    • uploadFile(file) 使用 FormData 调用 /api/files/upload，超时 60s。
  • 文件与搜索
    • readFile/statFile/writeFile/listDir/deleteFile/downloadFile/searchFiles/searchContent。
  • 命令执行
    • execCommand/execCommandWait/stopCommand/detachCommand。
  • MCP 与 Skill
    • getMcpTools/callMcpTool/getMcpServers/addMcpServer/removeMcpServer/connectMcpServer/disconnectMcpServer/toggleMcpServer。
  • RAG 知识库
    • ragListCollections 等（见注释与调用处）。
flowchart TD
Call["调用方"] --> AC["agentRequest/agentGet"]
AC --> Fetch["fetch(url, headers={Authorization,Bearer})"]
Fetch --> Resp["response.json()"]
Resp --> Attach["附加 httpStatus"]
Attach --> Return["返回 {success,...,httpStatus}"]

图表来源

章节来源

事件监听机制与状态同步 ​

  • Side Panel 与 Background 的消息通道
    • 通过 chrome.runtime.sendMessage/chrome.runtime.connect 进行消息传递；keepalive port 用于保活与实例身份上报。
  • 面板可见性与通知
    • isPanelVisibleToUser 结合窗口焦点、活跃 tab、面板打开状态判断是否弹通知；面板断开延迟复核避免误报。
  • 会话恢复与 Checkpoint
    • 自动续跑扫描 reactCheckpoints，按 interruptedReason 与重试次数决定是否恢复；到达最大尝试次数后通知人工介入。
stateDiagram-v2
[*] --> Idle
Idle --> Running : "CALL_API"
Running --> Paused : "用户取消/超时"
Running --> Completed : "完成"
Running --> Error : "异常"
Paused --> Resuming : "自动续跑"
Resuming --> Running : "恢复成功"
Resuming --> Exhausted : "尝试耗尽"
Completed --> Idle : "清理"
Error --> Idle : "清理"
Exhausted --> Idle : "人工介入"

图表来源

章节来源

依赖关系分析 ​

  • 扩展端依赖
    • background/index.js 依赖 state/config/notifier/panel-visibility/auto-resume/context-compactor/token-recorder/react-loop/tool-executor/local-agent-client。
    • tool-executor.js 依赖 constants.js、agent-dispatcher、stream-controller、tool-helpers、activity-store、network-scope、tool-memory、tool-debugger、snapshot-orchestrator、notifier、react-loop、RAG_TOOLS。
  • Agent 端依赖
    • server.js 聚合 auth/security/trash/executor/search/rag/install/memory/routes/mcp/registry/skill/registry/i18n/logger/process-tree。
    • mcp/client.js 依赖 @modelcontextprotocol/sdk 的多种传输；registry.js 依赖 client.js 与 mcp-config.js。
    • memory/routes.js 依赖 service.js/embedding-config.js/rag/embedding/index.js。
    • skill/registry.js 依赖 loader.js/executor.js/path/fs/i18n。
graph LR
BGIndex["background/index.js"] --> LocalAgent["local-agent-client.js"]
BGIndex --> ToolExec["tool-executor.js"]
ToolExec --> Constants["constants.js"]
ToolExec --> AgentDispatch["agent-dispatcher.js"]
ToolExec --> StreamCtrl["stream-controller.js"]
ToolExec --> Snapshot["snapshot-orchestrator.js"]
Server["agent/src/server.js"] --> MCPReg["mcp/registry.js"]
Server --> MemoryRoutes["memory/routes.js"]
Server --> SkillReg["skill/registry.js"]
MCPReg --> MCPClient["mcp/client.js"]

图表来源

章节来源

性能与可靠性 ​

  • Service Worker 生命周期
    • 通过 keepalive port 保活；SW 被回收后由闹钟恢复任务；面板断开延迟复核减少误判。
  • 大消息截断
    • chrome.runtime.sendMessage 单条消息最大 64MiB，日志条目超过阈值时保留尾部 N 条并保留 subtask_plan。
  • MCP Schema 压缩
    • 限制 description 长度、properties 嵌套深度、参数数量，避免撑爆上下文。
  • Agent 操作冷却
    • restart/update/shutdown 等接口 10s 冷却，防 DoS；并发操作返回 409，频繁请求返回 429。
  • 文件上传大小限制
    • JSON body 与 multipart/form-data 均受 MAX_BODY_SIZE 保护；流式上传也受相同上限保护。

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

故障排查指南 ​

  • 常见错误码与含义
    • 401：缺少 token（noToken）。
    • 403：token 无效（invalidToken）。
    • 409：操作进行中（operationInProgress）。
    • 429：请求过于频繁（tooFrequent）。
    • 500：内部错误（internal）。
  • 诊断步骤
    • 检查 Authorization 头是否正确携带 Bearer token。
    • 检查 Origin 是否为 chrome-extension://，否则 CORS 会阻止跨域读取。
    • 对于 /api/status 与 /api/status/detail，确认 Agent 是否在线且端口可达。
    • 对于 MCP 工具不可用，检查 registry 中服务器是否 connected，工具是否被禁用。
    • 对于命令执行超时，检查扩展端 toolTimeout 与 Agent 端 commandTimeout 预算是否合理。

章节来源

版本管理与迁移 ​

  • 版本同步
    • 扩展端 manifest.json version 与 Agent package.json version 保持一致，当前为 2.3.1。
  • 向后兼容
    • Agent 端对旧版扩展的兼容性体现在：/api/status 返回 platform/nodeVersion/searchTools/ragAvailable；/api/status/detail 返回 pairCodeTTL/workdir/allowedPaths/commandTimeout/fileMaxSize/uploadMaxSize/runningProcesses/resourceUsage。
    • Memory 路由对未知路径返回 404，扩展端据此探测旧版本 Agent 无记忆端点。
  • 迁移指南
    • 旧格式 Agent 配置（agentUrl/agentToken/agentPlatform）在启动时迁移到 pairedAgents/activeAgentId，token 加密存储。
    • MCP 工具动态注册：若 Agent 不支持 MCP，扩展端静默跳过并记录日志。
    • Skill 系统：内置 skill-creator 标记为 builtin/editable=false/deletable=false；用户停用状态持久化到 disabled_skills.json。

章节来源

结论 ​

本 API 参考文档梳理了 Chrome Extension API、Agent HTTP API、WebSocket 协议、MCP 协议与内部通信契约，明确了权限模型、认证机制、错误码约定与状态同步机制。通过动态工具注册、Schema 压缩、操作冷却与大消息截断，系统在可扩展性与可靠性之间取得平衡。建议在集成时严格遵循认证与 CORS 策略，合理使用超时与冷却机制，并结合 Checkpoint 与自动续跑提升长任务鲁棒性。