通信协议设计

本文引用的源码文件

本文引用的文件

引言
项目结构与通信边界
核心组件与职责
架构总览
详细协议规范
认证与 Token 交换流程
MCP 协议集成与工具发现
命令执行与 WebSocket 流式输出
依赖关系分析
性能、连接管理与重连策略
错误处理与状态码约定
版本兼容性与迁移指南
故障排查清单
结论

引言

本文件面向扩展端（Chrome 扩展，Manifest V3）与 Agent 端（独立 Node.js 进程）之间的通信契约。当前稳定版本为 2.3.1，两端版本号保持同步。扩展端通过本地 HTTP REST API 和 WebSocket 双通道调用 Agent 的文件系统、命令执行、长期记忆、RAG、Skill 与 MCP 工具能力；Agent 源码修改后必须重启进程，新接口才生效。

项目结构与通信边界

扩展端：src/background/local-agent-client.js 封装所有 HTTP/WebSocket 请求，负责配对、Token 管理、可达性缓存、超时控制、MCP/Skill/RAG 客户端封装。
Agent 端：agent/src/server.js 提供 HTTP Router 与 WebSocket Server，统一鉴权、安全校验、日志、国际化、MCP 注册表、Skill 注册表、RAG 路由转发。
安全层：agent/src/security.js 提供路径白名单、硬阻止目录、命令黑白名单与分级管控。
认证层：agent/src/auth.js 实现配对码轮换、一次性配对、Token 验证与活跃窗口。
执行层：agent/src/executor.js 负责命令子进程、超时策略、WebSocket 广播与完成回放。
MCP 层：agent/src/mcp/client.js 与 agent/src/mcp/registry.js 管理多传输 MCP Client 实例、工具发现与调用。

graph TB
Extension["扩展端<br/>background/local-agent-client.js"] --> HTTP["HTTP REST API<br/>server.js 路由"]
Extension --> WS["WebSocket 命令流<br/>server.js upgrade"]
HTTP --> Auth["认证模块<br/>auth.js"]
HTTP --> Security["安全模块<br/>security.js"]
HTTP --> Executor["命令执行器<br/>executor.js"]
HTTP --> MCPRegistry["MCP 注册表<br/>mcp/registry.js"]
MCPRegistry --> MCPClient["MCP 客户端<br/>mcp/client.js"]

图表来源

章节来源

核心组件与职责

扩展端客户端：维护已配对代理列表、活跃代理 ID、可达性缓存；统一发送带 Bearer Token 的请求；封装文件、命令、MCP、Skill、RAG、审计日志、回收站等 API。
Agent 服务端：解析请求、按路径分发到文件系统、命令、MCP、Skill、RAG、Memory、配置管理等子系统；统一 JSON 响应格式；支持 CORS 仅放行 Chrome 扩展来源。
认证模块：生成 6 位配对码，支持失败锁定与成功后立即轮换；持久化 extensionId → token 映射；verifyToken 更新 lastAuthTime。
安全模块：路径规范化、硬阻止目录、realpath 防符号链接绕过、allowedPaths 前缀校验；命令分级 deny/confirm/allow。
执行模块：spawn shell 子进程，stdout/stderr 流式广播，超时受管模式与旧语义兼容，完成结果回放给延迟连接的 WebSocket 客户端。
MCP 模块：支持 stdio、SSE、Streamable HTTP、WebSocket 四种传输；自动 listTools；合并多服务器工具并注入扩展端工具列表。

章节来源

架构总览

扩展端通过 local-agent-client.js 发起请求；Agent 端由 server.js 统一鉴权与安全校验后分发给具体业务模块。命令执行使用 HTTP 返回 execId 与 wsUrl，随后通过 WebSocket 实时推送 stdout/stderr/exit/error。MCP 工具在 Agent 端自动发现，扩展端按需拉取并动态注册为 AI 工具。

sequenceDiagram
participant UI as "扩展界面"
participant Client as "扩展端客户端<br/>local-agent-client.js"
participant Server as "Agent 服务端<br/>server.js"
participant Exec as "命令执行器<br/>executor.js"
participant WS as "WebSocket 通道"
UI->>Client : "提交任务或执行命令"
Client->>Server : "POST /api/exec (Bearer Token)"
Server->>Exec : "executeCommand(command, cwd, timeoutMs)"
Exec-->>Server : "返回 execId 与 wsUrl"
Server-->>Client : "{success : true, level : 'allow', execId, wsUrl}"
Client->>WS : "连接 ws : //{host} : {port}/ws/exec/{execId}?token=..."
WS-->>Client : "stdout/stderr/exit/error 流式消息"

图表来源

详细协议规范

通用响应结构

所有 HTTP 响应统一为 JSON，包含以下字段：

success: boolean，表示业务是否成功。
error: string，失败时的用户可读错误信息（国际化）。
httpStatus: number，扩展端附加的 HTTP 状态码，用于区分“Agent 离线”与“资源不存在”。
其他业务字段：如 version、platform、execId、content、tools、servers 等。

示例（健康检查）：

请求：GET /api/status
响应：{ success: true, version: "2.3.1", running: true, platform: "...", ... }

示例（需认证的状态详情）：

请求：GET /api/status/detail，Header：Authorization: Bearer <token>
响应：{ success: true, pairCodeTTL, workdir, allowedPaths, commandTimeout, fileMaxSize, uploadMaxSize, resourceUsage, ... }

章节来源

认证头与跨域

认证方式：Authorization: Bearer <token>。
跨域限制：仅允许 chrome-extension:// 来源；非浏览器客户端不受 CORS 限制。
预检请求：OPTIONS 返回允许的 Header 与方法。

章节来源

文件操作 API

/api/fs/read：读取文件，返回 content、size、path。
/api/fs/write：写入文件，支持 utf-8 与 base64。
/api/fs/list：列出目录条目。
/api/fs/stat：获取文件详细信息。
/api/fs/delete：移至回收站。
/api/fs/download：单文件或目录打包 zip，返回 base64。
/api/fs/download-stream：二进制流下载，避免 base64 膨胀。
/api/files/upload：multipart/form-data 上传。
/api/fs/upload-stream：raw binary 流式上传。

路径安全：所有路径先经 checkPath，命中硬阻止或不在 allowedPaths 则返回 403。

章节来源

命令执行 API

/api/exec：异步或同步执行命令。
- 异步：返回 execId 与 wsUrl。
- 同步：wait=true，返回完整 stdout/stderr。
/api/exec/stop：停止运行中的命令。
/api/exec/detach：显式 daemon 化，豁免超时。

命令安全：checkCommand 返回 level='deny' 或 'confirm'；deny 不可绕过，confirm 可 force 跳过。

章节来源

MCP 管理 API

/api/mcp/servers：添加/删除 MCP Server。
/api/mcp/servers/connect：连接指定 Server。
/api/mcp/servers/disconnect：断开 Server。
/api/mcp/servers/toggle：启用/禁用 Server。
/api/mcp/tools：获取工具列表，可选 serverId 过滤。
/api/mcp/call：调用工具，参数 serverId、toolName、args。

章节来源

Skill API

/api/skill/list、/api/skill/detail、/api/skill/run、/api/skill/import、/api/skill/delete、/api/skill/toggle、/api/skill/reload。
Agent Skill Markdown：/api/skill/save-markdown、/api/skill/markdown、/api/skill/resource、/api/skill/agent-prompts、/api/skill/agent-prompt。

章节来源

agent/src/server.js#L1727-L2002

RAG 与 Memory API

RAG：/api/rag/install、/api/rag/install/status、/api/rag/detect、/api/rag/collections、/api/rag/search、/api/rag/collections/{id}/ingest。
Memory：/api/memory/* 由 memoryRouter 转发。

章节来源

agent/src/server.js#L2023-L2072

认证与 Token 交换流程

配对码机制防止未授权扩展绑定 Agent。配对成功后，扩展端保存 token，后续所有需认证请求携带 Bearer Token。

sequenceDiagram
participant Ext as "扩展端"
participant Agent as "Agent 端"
participant Auth as "认证模块"
Ext->>Agent : "POST /api/pair {code, extensionId}"
Agent->>Auth : "handlePairRequest(code, extensionId)"
Auth-->>Agent : "{success, token|error}"
Agent-->>Ext : "{success, token}"
Ext->>Agent : "GET /api/status/detail (Authorization : Bearer token)"
Agent->>Auth : "verifyToken(token)"
Auth-->>Agent : "extensionId"
Agent-->>Ext : "{success, detail}"

图表来源

章节来源

MCP 协议集成与工具发现

Agent 端启动时加载启用的 MCP Server，建立连接并调用 listTools，将工具聚合为 {serverId, serverName, name, description, inputSchema}。扩展端通过 /api/mcp/tools 拉取工具列表，并动态注册为 AI 工具，ID 格式为 mcp_{serverId}_{toolName}。

classDiagram
class McpClient {
+string serverId
+string serverName
+boolean connected
+array tools
+connect()
+callTool(toolName, args)
+disconnect()
+getStatus()
}
class Registry {
+initializeMcpRegistry()
+getMcpTools(serverId?)
+callMcpTool(serverId, toolName, args)
+connectMcpServer(serverId)
+disconnectMcpServer(serverId)
+toggleMcpServer(serverId, enabled)
}
Registry --> McpClient : "管理多个实例"

图表来源

章节来源

命令执行与 WebSocket 流式输出

命令执行采用 HTTP + WebSocket 双通道：

HTTP 返回 execId 与 wsUrl。
WebSocket URL 为 ws://{host}:{port}/ws/exec/{execId}，认证通过 Authorization Header 或 query ?token=。
服务端每 30 秒 ping 检测半开连接，两拍无 pong 则 terminate。
执行器广播 stdout/stderr/exit/error，支持完成回放。

flowchart TD
Start["HTTP POST /api/exec"] --> CheckSecurity["安全检查 checkCommand"]
CheckSecurity --> |deny| Deny["返回 403 deny"]
CheckSecurity --> |confirm| Confirm["返回 confirm 提示"]
CheckSecurity --> |allow| Spawn["spawn 子进程"]
Spawn --> ReturnWS["返回 execId 与 wsUrl"]
ReturnWS --> ConnectWS["客户端连接 WebSocket"]
ConnectWS --> Stream["stdout/stderr 流式推送"]
Stream --> Exit["exit/error 结束"]

图表来源

章节来源

依赖关系分析

server.js 依赖 auth.js、security.js、executor.js、mcp/registry.js、skill/registry.js、memory/routes.js、rag/detect.js、logger.js、i18n.js。
local-agent-client.js 依赖扩展端存储、i18n、secret 加密，对外暴露统一 API。
tool-executor.js 从 Agent 拉取 MCP 工具并注入 RAW_TOOLS 与 TOOL_HANDLERS。
agent-dispatcher.js 负责子 Agent 调度，使用派生 sessionId 隔离信令。

graph LR
Server["server.js"] --> Auth["auth.js"]
Server --> Security["security.js"]
Server --> Executor["executor.js"]
Server --> MCPReg["mcp/registry.js"]
Server --> SkillReg["skill/registry.js"]
Server --> MemoryRoute["memory/routes.js"]
Server --> RagDetect["rag/detect.js"]
LocalClient["local-agent-client.js"] --> ToolExecutor["tool-executor.js"]
ToolExecutor --> MCPReg
Dispatcher["agent-dispatcher.js"] --> LocalClient

图表来源

章节来源

性能、连接管理与重连策略

请求超时：agentRequest 默认 60s，agentGet 默认 30s；文件上传 60s；下载 120s；RAG 搜索 180s；RAG 导入 600s。
可达性缓存：按 agentId 缓存 null/true/false，已知不可达直接返回错误，避免阻塞等待超时。
WebSocket 心跳：服务端每 30 秒 ping，无 pong 则 terminate；客户端空闲超时由调用方统一管理，避免双重超时冲突。
命令超时：支持受管模式（timeoutMs 协商）与旧语义（commandTimeout），期内有输出可延长，静默即杀。
优雅关闭：shutdown 终止进程、关闭 MCP、断开 WebSocket、销毁活跃 socket，10s 强制退出。

章节来源

错误处理与状态码约定

400：请求参数无效、JSON 解析失败、文件大小超限、路径缺失。
401：缺少 Authorization Header。
403：Token 无效、路径被拒绝、命令 deny、CORS 来源不被允许。
404：API 路径不存在、文件/目录不存在。
409：操作进行中、目标已存在。
429：操作过于频繁（冷却期）。
500：内部异常、RAG 路由加载失败、下载失败。
503：RAG 依赖不可用。

扩展端附加 httpStatus 字段，便于区分“Agent 离线/网络错误”与“业务 404”。

章节来源

版本兼容性与迁移指南

版本号：扩展端与 Agent 端均为 2.3.1，通过 /api/status 与 /api/status/detail 暴露。
向后兼容：
- 命令执行支持受管模式（timeoutMs）与旧语义（commandTimeout），保证新 Agent × 旧插件行为不变。
- 扩展端保留 legacy 存储格式迁移逻辑，自动升级到 pairedAgents 数组。
- WebSocket 认证优先 Authorization Header，回退到 query token，兼容浏览器 WebSocket API 限制。
迁移建议：
- 升级 Agent 后必须重启进程，新接口才生效。
- 若使用远程 Agent，注意 wsUrl 中本地地址替换为配置的 hostname。
- MCP 工具 ID 格式固定为 mcp_{serverId}_{toolName}，扩展端工具名变更需重新加载。

章节来源

故障排查清单

无法连接 Agent：检查 /api/status 是否可达，确认扩展来源是否为 chrome-extension://。
认证失败：确认 /api/pair 成功后 token 已保存，后续请求携带 Authorization: Bearer <token>。
文件操作 403：检查路径是否在 allowedPaths 内，是否命中硬阻止目录。
命令执行被拒绝：查看 checkCommand 返回 level，deny 不可绕过，confirm 可 force。
WebSocket 断连：检查服务端心跳是否正常，客户端是否长时间无输出导致超时。
MCP 工具未显示：确认 MCP Server 已连接且 enabled，扩展端已调用 /api/mcp/tools。
RAG 不可用：调用 /api/rag/detect 探测依赖，必要时安装依赖并重启 Agent。

章节来源

结论

扩展端与 Agent 端的通信协议以 HTTP REST API 为主、WebSocket 为辅，兼顾安全性、可扩展性与可观测性。认证通过配对码与 Bearer Token 实现，安全层提供路径与命令双重防护，MCP 协议标准化外部工具接入，命令执行支持流式输出与超时策略。文档明确了协议序列图、消息格式、错误码、连接管理与兼容性策略，可作为扩展端与 Agent 端开发、集成与排障的权威参考。

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

通信协议设计

目录

引言

项目结构与通信边界

核心组件与职责

架构总览

详细协议规范

通用响应结构

认证头与跨域

文件操作 API

命令执行 API

MCP 管理 API

Skill API

RAG 与 Memory API

认证与 Token 交换流程

MCP 协议集成与工具发现

命令执行与 WebSocket 流式输出

依赖关系分析

性能、连接管理与重连策略

错误处理与状态码约定

版本兼容性与迁移指南

故障排查清单

结论

Markdown 渲染引擎

通信协议设计 ​

目录 ​

引言 ​

项目结构与通信边界 ​

核心组件与职责 ​

架构总览 ​

详细协议规范 ​

通用响应结构 ​

认证头与跨域 ​

文件操作 API ​

命令执行 API ​

MCP 管理 API ​

Skill API ​

RAG 与 Memory API ​

认证与 Token 交换流程 ​

MCP 协议集成与工具发现 ​

命令执行与 WebSocket 流式输出 ​

依赖关系分析 ​

性能、连接管理与重连策略 ​

错误处理与状态码约定 ​

版本兼容性与迁移指南 ​

故障排查清单 ​

结论 ​

通信协议设计

目录

引言

项目结构与通信边界

核心组件与职责

架构总览

详细协议规范

通用响应结构

认证头与跨域

文件操作 API

命令执行 API

MCP 管理 API

Skill API

RAG 与 Memory API

认证与 Token 交换流程

MCP 协议集成与工具发现

命令执行与 WebSocket 流式输出

依赖关系分析

性能、连接管理与重连策略

错误处理与状态码约定

版本兼容性与迁移指南

故障排查清单

结论