AI Helper 文档中心

主题

Agent 服务通信协议 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性
  8. 故障排查指南
  9. 结论
  10. 附录：API 契约与消息协议

引言 ​

本文件定义 Chrome 扩展端与本地 Agent 服务之间的完整通信协议，覆盖 HTTP REST API、WebSocket 流式命令输出、认证配对码与 Token 管理、文件操作、命令执行、长期记忆存储与 RAG 检索。文档同时说明连接池与重试策略、错误恢复机制、流式数据传输、进度回调、取消机制、安全性与审计追踪，并提供客户端集成要点与排障建议。

Agent 为独立 Node.js 进程（版本 2.3.1），Chrome 扩展为 Manifest V3 背景脚本（版本 2.3.1）。两端通过本地 HTTP/WebSocket 通信；Agent 源码修改后必须重启进程，新接口才生效。

项目结构 ​

  • 扩展侧客户端封装位于 src/background/local-agent-client.js，负责配对、Token 管理、HTTP 请求与 WebSocket 建连。
  • Agent 服务端入口位于 agent/src/server.js，统一处理 HTTP 路由、CORS、认证、文件、命令、Skill、MCP、RAG、Memory、日志等。
  • 安全与路径沙箱在 agent/src/security.js；命令分级在 checkCommand。
  • 命令执行与 WebSocket 输出在 agent/src/executor.js。
  • 长期记忆路由在 agent/src/memory/routes.js。
  • RAG 配置与默认值在 agent/src/rag/config.js。
  • 扩展侧工具执行与超时/取消逻辑在 src/background/tool-executor.js，取消事件由 src/background/index.js 分发。
graph TB
subgraph "Chrome 扩展"
BG["background/local-agent-client.js"]
TE["background/tool-executor.js"]
IDX["background/index.js"]
end
subgraph "本地 Agent 服务"
S["server.js<br/>HTTP + WebSocket 路由"]
A["auth.js<br/>配对码与 Token"]
SEC["security.js<br/>路径与命令安全"]
EXE["executor.js<br/>命令执行与 WS 输出"]
MEM["memory/routes.js<br/>长期记忆"]
RAGCFG["rag/config.js<br/>RAG 配置"]
end
BG --> |HTTP / WebSocket| S
TE --> BG
IDX --> TE
S --> A
S --> SEC
S --> EXE
S --> MEM
S --> RAGCFG

图示来源

章节来源

核心组件 ​

  • 认证与配对：Agent 生成一次性配对码，扩展提交配对码与 extensionId，成功后获得 Bearer Token；后续所有受保护接口均携带该 Token。
  • 文件操作：读、写、列目录、删除（回收站）、下载（base64 或流式）、搜索文件名与内容、预览 XLSX、批量打包 ZIP。
  • 命令执行：支持同步等待与异步流式；灰名单需用户确认；黑名单绝对禁止；支持停止、daemon 化、超时预算协商。
  • 长期记忆：store/recall/inject/reindex 等接口，embedding 配置与探活。
  • RAG：知识库增删改查、导入、检索、安装可选依赖、检测可用性。
  • Skill/MCP：技能列表、详情、运行、导入、Markdown 管理；MCP Server 管理、工具调用。
  • 审计日志：查询最近 7 天日志条目。

章节来源

架构总览 ​

扩展侧通过 local-agent-client.js 统一发起 HTTP 请求与 WebSocket 连接；Agent 侧 server.js 作为唯一入口，完成认证、鉴权、安全校验、业务路由与响应。命令执行采用“HTTP 初始化 + WebSocket 流式输出”的混合模式。

sequenceDiagram
participant Ext as "扩展 background/local-agent-client.js"
participant Srv as "Agent server.js"
participant Auth as "auth.js"
participant Sec as "security.js"
participant Exec as "executor.js"
Ext->>Srv : POST /api/pair {code, extensionId}
Srv->>Auth : handlePairRequest(code, extensionId)
Auth-->>Srv : {success, token}
Srv-->>Ext : {success, token}
Ext->>Srv : GET /api/status/detail (Authorization : Bearer token)
Srv->>Auth : verifyToken(token)
Auth-->>Srv : extId
Srv-->>Ext : {version, workdir, allowedPaths, ...}
Ext->>Srv : POST /api/exec {command, cwd, timeoutMs}
Srv->>Sec : checkCommand(command, force)
Sec-->>Srv : {level : allow|confirm|deny}
Srv->>Exec : executeCommand(...)
Exec-->>Srv : execId
Srv-->>Ext : {execId, wsUrl}
Ext->>Srv : WebSocket /ws/exec/{execId}?token=...
Srv->>Exec : addWsClient(execId, ws)
Exec-->>Ext : stdout/stderr/error/exit

图示来源

详细组件分析 ​

认证流程、配对码与 Token 管理 ​

  • 配对码生成：Agent 启动时生成 6 位字母数字配对码，周期性刷新；若存在已配对且 5 分钟内有过活跃认证，则暂停刷新。
  • 配对请求：扩展发送 {code, extensionId}；失败超过阈值会临时锁定并轮换配对码；成功即保存扩展 ID 与随机 Token。
  • Token 验证：所有受保护接口要求 Authorization: Bearer <token>；WebSocket 优先使用 Authorization Header，回退到 URL query ?token=。
  • 心跳：GET /api/heartbeat 仅刷新最后认证时间，不返回敏感信息。
flowchart TD
Start(["开始"]) --> Gen["生成配对码并定时刷新"]
Gen --> PairReq{"收到 /api/pair ?"}
PairReq --> |否| KeepAlive["维持当前配对码"]
PairReq --> |是| Validate["校验 code 与 extensionId"]
Validate --> Valid{"配对码正确？"}
Valid --> |否| Lock["累计失败 → 锁定并轮换配对码"]
Valid --> |是| Save["保存 extensionId 与 token"]
Save --> Rotate["立即轮换配对码"]
Rotate --> Done(["结束"])
KeepAlive --> Done

图示来源

章节来源

文件操作 API ​

  • 上传：POST /api/files/upload（multipart）与 POST /api/fs/upload-stream（raw binary，path 通过 query 传递）。
  • 读取/写入/列出/删除：/api/fs/read、/api/fs/write、/api/fs/list、/api/fs/delete（移入回收站）。
  • 统计/下载：/api/fs/stat、/api/fs/download（base64）、/api/fs/download-stream（二进制流）、/api/fs/download-multi（多文件 zip base64）。
  • 搜索：/api/fs/search_files、/api/fs/search_content。
  • 其他：/api/fs/mkdir、/api/fs/rename、/api/fs/move、/api/fs/preview-xlsx。
  • 安全：所有路径先经 checkPath，工作目录永远放行，但符号链接最终 realpath 仍受硬阻止目录限制。
flowchart TD
In(["请求进入"]) --> Check["checkPath(path)"]
Check --> Allowed{"允许？"}
Allowed --> |否| Deny["返回 403 + reason"]
Allowed --> |是| Op{"操作类型"}
Op --> Read["read / stat / list"]
Op --> Write["write / mkdir / rename / move"]
Op --> Delete["delete → moveToTrash"]
Op --> Download["download / download-stream / download-multi"]
Op --> Search["search_files / search_content"]
Read --> Out(["JSON 响应"])
Write --> Out
Delete --> Out
Download --> Out
Search --> Out

图示来源

章节来源

命令执行与 WebSocket 流式协议 ​

  • HTTP 初始化：POST /api/exec 返回 {execId, wsUrl}；若 level=confirm 需要前端弹窗确认后再以 force=true 重新初始化。
  • WebSocket 输出：/ws/exec/{execId}?token=...，消息包括 stdout、stderr、error、exit（含 exitCode、killed、timedOut）。
  • 控制面：/api/exec/stop 终止进程；/api/exec/detach 显式 daemon 化豁免超时。
  • 超时与空闲：扩展侧计算 idleTimeout，Agent 侧支持受管模式 timeoutMs；断开所有 WS 客户端后按旧语义或受管语义处理。
sequenceDiagram
participant FE as "tool-executor.js"
participant AC as "local-agent-client.js"
participant S as "server.js"
participant E as "executor.js"
FE->>AC : execCommand(command, cwd, force, timeoutMs)
AC->>S : POST /api/exec
S->>E : executeCommand(...)
E-->>S : execId
S-->>AC : {execId, wsUrl}
AC->>S : WebSocket /ws/exec/{execId}?token=...
E-->>AC : stdout/stderr/error/exit
FE->>AC : stopCommand(execId) | detachCommand(execId)
AC->>S : /api/exec/stop | /api/exec/detach

图示来源

章节来源

长期记忆与 RAG 查询 ​

  • 长期记忆：/api/memory/store、/api/memory/recall、/api/memory/injectSelect、/api/memory/reindex；embedding 配置与探活 /api/memory/embedding-config、/api/memory/test-embedding、/api/memory/vector-status。
  • RAG：知识库集合、导入、检索、安装依赖、检测可用性；默认 embedding 模型与分块参数见 rag/config.js。
flowchart TD
MIn(["/api/memory/*"]) --> Dispatch["memoryDispatch"]
Dispatch --> EmbedCfg{"embedding-config/test-embedding/vector-status ?"}
EmbedCfg --> |是| HandleEmbed["handleEmbeddingEndpoints"]
EmbedCfg --> |否| Route["ROUTE_METHODS 映射 store/recall/inject/reindex"]
Route --> Service["service.* 调用"]
Service --> Resp(["{success,...}"])

图示来源

章节来源

连接池管理、重试策略与错误恢复 ​

  • 可达性缓存：扩展侧按 agentId 维护 _agentReachability，已知不可达直接返回错误，避免阻塞等待超时。
  • 请求超时：agentRequest/agentGet 使用 AbortController 超时；上传单独 60s 超时。
  • WebSocket 保活：Agent 侧每 30s ping，两拍未 pong 则 terminate；扩展侧 tool-executor 维护 idleTimeout 与正常退出标记。
  • 优雅关闭：Agent 关闭时终止进程、关闭 MCP、强制断开 WS 与 HTTP socket，10s 兜底退出。
flowchart TD
Reachable{"代理可达？"}
Reachable --> |否| FastFail["快速失败，提示未连接"]
Reachable --> |是| HttpReq["HTTP 请求带超时"]
HttpReq --> WsConn{"WebSocket 建连？"}
WsConn --> |否| RetryOrFail["根据场景重试或直接失败"]
WsConn --> |是| Heartbeat["Agent 侧 30s ping/pong"]
Heartbeat --> Close{"连接关闭？"}
Close --> |正常| Finish["正常结束"]
Close --> |异常| Cleanup["清理资源/终止进程"]

图示来源

章节来源

安全性、权限控制与审计追踪 ​

  • CORS：仅对 chrome-extension:// Origin 返回 ACAO，防止恶意网页跨域读取无认证端点。
  • 路径沙箱：checkPath 支持白名单、工作目录放行、realpath 防符号链接绕过、硬阻止系统目录。
  • 命令分级：黑名单绝对禁止，灰名单需用户确认；支持包装器剥壳、内联载荷解析、替换特征送检。
  • 审计日志：/api/logs/query 返回最近 7 天最多 500 条记录。

章节来源

依赖关系分析 ​

  • server.js 聚合 auth、security、executor、memory、rag、skill、mcp、logger、trash、config、i18n 等模块。
  • 扩展侧 local-agent-client.js 暴露统一 API，被 tool-executor.js 与 UI 层调用。
  • tool-executor.js 实现 ReAct 执行循环中的命令执行、超时、取消与结果上报。
  • background/index.js 分发取消事件，触发 tool-executor 取消正在运行的 Agent 命令。
graph LR
LAC["local-agent-client.js"] --> S["server.js"]
TE["tool-executor.js"] --> LAC
IDX["background/index.js"] --> TE
S --> AUTH["auth.js"]
S --> SEC["security.js"]
S --> EXE["executor.js"]
S --> MEM["memory/routes.js"]
S --> RAG["rag/config.js"]

图示来源

章节来源

性能与可靠性 ​

  • 大文件传输：提供流式上传与流式下载，避免 base64 膨胀与内存峰值。
  • 搜索上限：单次搜索最大结果数限制，防止大量 IO。
  • 命令执行：支持同步等待与异步流式；idleTimeout 与受管超时协同；WS 心跳保活。
  • 优雅关闭：10s 强制退出兜底，确保端口释放与子进程清理。

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

故障排查指南 ​

  • 无法连接 Agent：检查代理是否启动、端口占用、CORS 与 Origin；扩展侧可达性缓存可能快速失败。
  • 配对失败：核对配对码、extensionId；连续失败会被锁定并轮换配对码。
  • 文件操作失败：确认 path 是否在允许目录、是否存在、大小限制；注意脚本文件写入后会剥离执行权限。
  • 命令执行被拒绝：查看 level=deny/confirm 原因；黑名单不可绕过，灰名单需用户确认。
  • WebSocket 断连：检查网络、代理保活；Agent 侧 30s ping/pong 可检测半开连接。
  • RAG 不可用：先调用 /api/rag/install 与 /api/rag/detect；依赖加载失败需重启 Agent。

章节来源

结论 ​

本协议以 HTTP REST 为主、WebSocket 为辅，结合配对码与 Bearer Token 完成双向可信通信。Agent 侧通过严格的路径与命令安全策略保障宿主环境安全；扩展侧通过可达性缓存、请求超时与 WS 心跳提升鲁棒性。长期记忆与 RAG 能力通过模块化路由接入，便于按需启用与扩展。

[本节为总结，不直接分析具体文件]

附录：API 契约与消息协议 ​

HTTP REST API 摘要 ​

  • 认证与会话
    • POST /api/pair：配对认证，请求体 {code, extensionId}，返回 {success, token, message?}。
    • GET /api/status：健康检查，无需认证，返回平台信息与能力标志。
    • GET /api/status/detail：需认证，返回 pairCodeTTL、workdir、allowedPaths、runningProcesses、resourceUsage 等。
    • GET /api/heartbeat：需认证，刷新 lastAuthTime。
  • 文件操作
    • POST /api/files/upload：multipart 上传。
    • POST /api/fs/upload-stream：raw binary 上传，query 传 path。
    • POST /api/fs/read、/api/fs/write、/api/fs/list、/api/fs/delete、/api/fs/stat、/api/fs/download、/api/fs/download-stream、/api/fs/download-multi、/api/fs/search_files、/api/fs/search_content、/api/fs/mkdir、/api/fs/rename、/api/fs/move、/api/fs/preview-xlsx。
  • 命令执行
    • POST /api/exec：返回 {execId, wsUrl} 或 {level: confirm|deny}。
    • POST /api/exec/stop、POST /api/exec/detach。
  • 长期记忆
    • POST /api/memory/store、/api/memory/recall、/api/memory/injectSelect、/api/memory/reindex。
    • GET/POST /api/memory/embedding-config、POST /api/memory/test-embedding、GET /api/memory/vector-status。
  • RAG
    • POST /api/rag/install、GET /api/rag/install/status、POST /api/rag/detect。
    • 动态路由 /api/rag/*：集合、导入、检索、状态等。
  • Skill/MCP/日志/回收站
    • Skill：/api/skill/list、/api/skill/detail、/api/skill/run、/api/skill/import、/api/skill/delete、/api/skill/toggle、/api/skill/save-markdown、/api/skill/markdown、/api/skill/resource、/api/skill/import-zip、/api/skill/import-url、/api/skill/agent-prompts、/api/skill/agent-prompt。
    • MCP：/api/mcp/tools、/api/mcp/call、/api/mcp/servers、/api/mcp/servers/connect、/api/mcp/servers/disconnect、/api/mcp/servers/toggle。
    • 日志：POST /api/logs/query。
    • 回收站：GET /api/trash/list、POST /api/trash/restore。

章节来源

WebSocket 消息协议 ​

  • 连接地址：ws://{host}:{port}/ws/exec/{execId}?token={token}。
  • 消息类型
    • stdout：标准输出片段。
    • stderr：标准错误片段。
    • error：执行错误，包含 error 与 execId。
    • exit：执行结束，包含 exitCode、killed、timedOut、execId。
  • 保活：Agent 每 30s ping，客户端应回复 pong；两拍未回则 terminate。

章节来源

客户端集成示例（步骤） ​

  1. 获取 Agent 地址与配对码，调用 POST /api/pair 获得 token。
  2. 将 token 存入扩展存储，并在后续请求中附加 Authorization: Bearer <token>。
  3. 文件操作：使用 uploadFile、readFile、writeFile、listDir、deleteFile、downloadFile 等封装方法。
  4. 命令执行：调用 execCommand 获取 execId 与 wsUrl，建立 WebSocket 接收 stdout/stderr/error/exit；必要时调用 stopCommand 或 detachCommand。
  5. 长期记忆与 RAG：调用 memory 与 rag 相关封装方法；RAG 首次导入可能耗时较长，注意超时设置。
  6. 取消与恢复：通过 CANCEL_REACT 消息触发 background 取消，tool-executor 关闭 WS 并终止进程。

章节来源