HTTP/WebSocket 服务器

本文引用的源码文件

本文引用的文件

简介

本文面向 Agent 端的本地 HTTP/WebSocket 服务，基于 Node.js 原生 http 模块和 ws 库实现。该服务是 Chrome 扩展与本机能力之间的桥梁：扩展通过本地端口调用 Agent 的文件读写、命令执行、长期记忆、RAG、MCP 工具、技能系统等功能；Agent 负责安全校验、路径沙箱、命令分级、进程管理、流式输出、配置持久化以及优雅关闭。

关键约束：

双进程架构：Chrome 扩展端（Manifest V3）与独立本地 Agent 进程（Node.js）。
修改 Agent 源码后必须重启进程，新接口才生效。
默认监听 127.0.0.1:18910，仅本机可访问；若绑定到 0.0.0.0，远程请求仍需认证。
所有业务接口统一返回 { success, ... } JSON 结构，错误信息使用 i18n 文案。

章节来源

项目结构

Agent 的 HTTP/WebSocket 入口位于 agent/src/server.js，它同时承担以下职责：

启动 Node.js HTTP 服务器并注册路由。
解析请求体、处理 CORS、国际化语言切换。
执行认证、配对、工作目录切换、文件操作、命令执行、Skill/MCP/RAG/Memory 路由分发。
创建 WebSocket 升级处理器，用于命令执行结果流式推送。
管理进程生命周期、优雅关闭、信号处理和全局异常捕获。

graph TB
Client["客户端<br/>Chrome 扩展 / CLI / 脚本"] --> HTTP["HTTP 服务器<br/>server.js"]
HTTP --> Router["请求路由与中间件<br/>server.js"]
Router --> Auth["认证与配对<br/>auth.js"]
Router --> Security["路径与命令安全<br/>security.js"]
Router --> Config["配置加载与保存<br/>config.js"]
Router --> FS["文件系统接口<br/>server.js"]
Router --> Exec["命令执行器<br/>executor.js"]
Router --> Memory["长期记忆路由<br/>memory/routes.js"]
Router --> RAG["RAG 路由按需加载"]
Router --> MCP["MCP 工具路由"]
Router --> Skill["技能路由"]
HTTP --> WS["WebSocket 升级<br/>server.js"]
WS --> ExecWS["命令执行 WebSocket 广播<br/>executor.js"]

图表来源

章节来源

核心组件

组件	职责	关键行为
HTTP 服务器	监听端口、接收请求、触发路由	使用 `http.createServer`，在 `handleRequest` 中完成 i18n、CORS、认证、路由分发
认证模块	配对码生成、Token 验证、活跃连接窗口	支持连续失败锁定、一次性配对码、最近认证时间戳
安全模块	路径白名单、硬阻止目录、命令黑白名单	跨平台路径规整、符号链接 realpath 校验、链式命令拆分、解释器内联载荷检测
配置模块	配置文件加载、写入锁、内存缓存	默认端口 18910、host 127.0.0.1、workdir、allowedPaths、pairCodeTTL、commandTimeout
命令执行器	子进程执行、流式 stdout/stderr、超时策略	支持同步等待、异步 WebSocket 广播、受管模式超时延长、进程树终止
记忆路由	`/api/memory/*` 业务分发	store/recall/manage/inject/reindex，embedding 配置与探活
WebSocket 服务器	命令执行结果实时推送	按 execId 关联进程、心跳 ping/pong、半开连接检测、断开清理

章节来源

架构总览

下图展示一次典型请求的生命周期：从 HTTP 请求进入、i18n 初始化、CORS 预检、认证、路由匹配、安全检查、业务处理，到最终 JSON 响应或 WebSocket 流式输出。

sequenceDiagram
participant C as "客户端"
participant H as "HTTP 服务器"
participant R as "请求处理器"
participant A as "认证模块"
participant S as "安全模块"
participant E as "命令执行器"
participant W as "WebSocket 服务器"
C->>H : "POST /api/exec"
H->>R : "handleRequest(req,res)"
R->>R : "解析 Accept-Language<br/>设置各模块语言"
R->>R : "CORS OPTIONS 预检"
R->>A : "验证 Authorization Bearer Token"
A-->>R : "extId 或 401/403"
R->>S : "检查 cwd 与 command"
S-->>R : "allow / confirm / deny"
alt "deny"
R-->>C : "403 {success : false,error}"
else "confirm"
R-->>C : "200 {level : 'confirm',reason}"
else "allow"
R->>E : "executeCommand(command,cwd,timeoutMs)"
E-->>R : "execId + wsUrl"
R-->>C : "200 {success : true,execId,wsUrl}"
C->>W : "WebSocket /ws/exec/{execId}?token=..."
W->>E : "addWsClient(execId,ws)"
E-->>W : "stdout/stderr/exit/error 广播"
W-->>C : "实时消息流"
end

图表来源

章节来源

详细组件分析

HTTP 路由与中间件管道

HTTP 服务器在 startServer 中创建，并通过 handleRequest 实现统一的请求处理流程：

初始化 i18n，将当前请求语言同步到 config、auth、security、executor、memory、rag、skill、mcp 等模块。
处理 CORS 预检请求，仅放行 chrome-extension:// 来源。
解析 URL，每次请求重新加载配置，确保 workdir 切换后立即生效。
先处理无需认证的接口：/api/pair、/api/status、/api/shutdown。
再处理需认证的接口：/api/heartbeat、/api/agent/restart、/api/agent/update、文件接口、命令接口、Skill、MCP、RAG、Memory。
未匹配的路径返回 404。

flowchart TD
Start(["HTTP 请求进入"]) --> I18n["初始化 i18n<br/>同步各模块语言"]
I18n --> Options{"OPTIONS 预检?"}
Options --> |是| Cors["设置 ACAO<br/>仅 chrome-extension"]
Options --> |否| ParseURL["解析 URL<br/>重新加载配置"]
Cors --> RouteMatch["路由匹配"]
ParseURL --> RouteMatch
RouteMatch --> PairCheck{"/api/pair ?"}
PairCheck --> |是| Pair["handlePairRequest"]
PairCheck --> |否| StatusCheck{"/api/status ?"}
StatusCheck --> |是| Status["返回平台信息"]
StatusCheck --> |否| ShutdownCheck{"/api/shutdown ?"}
ShutdownCheck --> |是| Shutdown["本机免认证<br/>远程需 Bearer"]
ShutdownCheck --> |否| AuthCheck{"Authorization Bearer ?"}
AuthCheck --> |否| NoToken["401 noToken"]
AuthCheck --> |是| Verify["verifyToken"]
Verify --> Valid{"extId 有效?"}
Valid --> |否| InvalidToken["403 invalidToken"]
Valid --> |是| Business["业务路由分发"]
Business --> End(["JSON 响应"])

图表来源

章节来源

agent/src/server.js#L427-L548

认证与配对机制

认证模块维护以下状态：

当前配对码：定时刷新，插件在线时停止刷新，离线超时后恢复刷新。
最近认证时间：用于判断扩展是否仍在线。
配对失败计数：连续失败达到阈值后临时锁定，并立即轮换配对码。
配对记录：存储扩展 ID 与 token，落盘前对 token 加密。

stateDiagram-v2
[*] --> Generating : "启动时生成配对码"
Generating --> Rotating : "定时器轮询"
Rotating --> Active : "检测到已配对且最近有认证"
Active --> Rotating : "插件离线超时"
Rotating --> Locked : "连续失败达到阈值"
Locked --> Rotating : "锁定期结束"
Rotating --> Paired : "配对成功"
Paired --> Rotating : "成功后立即轮换配对码"

图表来源

章节来源

路径与命令安全模型

安全模块提供两层保护：

路径沙箱：通过 checkPath 校验目标路径是否在 allowedPaths 或 workdir 内，防止符号链接绕过，拦截硬阻止目录。
命令分级：通过 checkCommand 对命令进行黑名单（deny）、灰名单（confirm）、允许（allow）分类，支持链式命令拆分、解释器内联载荷、命令替换检测。

flowchart TD
Input["输入路径或命令"] --> Normalize["路径规整<br/>normalizePathFormat"]
Normalize --> HardBlock{"命中硬阻止目录?"}
HardBlock --> |是| Deny["deny / forbiddenAgentFile"]
HardBlock --> |否| WorkdirCheck{"是否 workdir?"}
WorkdirCheck --> |是| AllowWorkdir["允许 workdir"]
WorkdirCheck --> |否| AllowedPaths{"是否在 allowedPaths?"}
AllowedPaths --> |否| NotAllowed["pathNotInAllowedDir"]
AllowedPaths --> |是| Realpath["realpath 校验"]
Realpath --> FinalCheck{"realpath 再次白名单?"}
FinalCheck --> |是| Allowed["allowed"]
FinalCheck --> |否| OutOfRange["pathOutOfRange"]

图表来源

agent/src/security.js#L109-L229

章节来源

命令执行与 WebSocket 流式输出

命令执行器负责：

选择合适 shell（cmd/powershell/bash/zsh/fish/sh）。
创建子进程，隔离环境变量，限制输出缓冲区上限。
支持同步等待模式和异步 WebSocket 流式输出。
管理超时策略：旧模式到期直接杀，受管模式根据输出情况决定是否延长。
多客户端广播：同一 execId 可被多个 WebSocket 客户端订阅。
进程终止：Windows 用 taskkill，Unix 用进程组 SIGTERM/SIGKILL。

sequenceDiagram
participant API as "HTTP 接口"
participant EX as "命令执行器"
participant PROC as "子进程"
participant WS as "WebSocket 客户端"
API->>EX : "executeCommand(command,cwd,timeoutMs)"
EX->>PROC : "spawn(shell,args,command)"
PROC-->>EX : "stdout/stderr 数据流"
EX->>WS : "broadcast(stdout/stderr)"
PROC-->>EX : "close(exitCode)"
EX->>WS : "broadcast(exit)"
WS-->>API : "前端收到实时输出"

图表来源

章节来源

WebSocket 握手与连接管理

WebSocket 升级由 server.on('upgrade') 处理，仅允许 /ws/exec/{execId} 路径：

解析 URL，提取 execId。
同步语言到 executor、security、config 模块。
认证：优先使用 Authorization: Bearer，回退到 ?token= query。
验证失败直接返回 403。
验证通过后，将 WebSocket 客户端加入进程的 wsClients 集合。
启动心跳：每 30 秒 ping，未 pong 则 terminate。
客户端断开时移除连接，并在无客户端且非受管模式下取消超时。

sequenceDiagram
participant Browser as "浏览器 WebSocket"
participant Server as "HTTP 服务器"
participant WSS as "WebSocketServer"
participant EXEC as "命令执行器"
Browser->>Server : "GET /ws/exec/{execId}?token=..."
Server->>Server : "验证 Authorization / token"
alt "认证失败"
Server-->>Browser : "403 Forbidden"
else "认证成功"
Server->>WSS : "handleUpgrade(request,socket,head)"
WSS->>EXEC : "addWsClient(execId,ws)"
EXEC-->>WSS : "true/false"
WSS->>WSS : "启动心跳 ping/pong"
WSS-->>Browser : "连接建立"
EXEC-->>WSS : "stdout/stderr/exit 广播"
WSS-->>Browser : "实时消息"
end

图表来源

章节来源

配置选项与服务发现

配置模块提供默认值与持久化：

默认端口：18910
默认 host：127.0.0.1
workdir：用户工作目录
allowedPaths：允许访问的目录列表
pairCodeTTL：配对码过期时间
commandTimeout：命令默认超时
fileMaxSize：文件读取大小限制
memoryEmbedding：长期记忆语义召回配置

健康检查接口 /api/status 返回版本、运行状态、平台信息、搜索工具可用性、RAG 可用性。

章节来源

反向代理与 SSL/TLS 支持

当前实现直接使用 Node.js 原生 http 模块，未内置 SSL/TLS 支持。推荐部署方式：

使用 Nginx、Apache、Caddy 等反向代理提供 HTTPS。
反向代理转发到 127.0.0.1:18910。
注意 CORS 策略：仅放行 chrome-extension:// 来源，普通网页无法跨域读取响应。
若暴露到公网，务必通过防火墙或反向代理限制来源 IP。

章节来源

服务健康检查、优雅关闭与资源清理

健康检查：

/api/status：无认证，返回基础平台信息。
/api/status/detail：需认证，返回内存、CPU、运行进程、RAG 状态等详细信息。
/api/heartbeat：需认证，刷新 lastAuthTime。

优雅关闭：

监听 SIGINT、SIGTERM。
停止配对码轮换、回收站清理、RAG 安装。
终止所有运行中的命令进程。
关闭 MCP 连接。
强制断开所有 WebSocket 客户端。
销毁活跃 HTTP socket。
10 秒超时兜底，防止 server.close() 挂起。

资源清理：

PID 文件删除。
全局 uncaughtException、unhandledRejection 捕获，记录日志但不退出进程。

章节来源

agent/src/server.js#L2239-L2308

依赖关系分析

graph LR
Server["server.js"] --> Config["config.js"]
Server --> Auth["auth.js"]
Server --> Security["security.js"]
Server --> Executor["executor.js"]
Server --> MemoryRoutes["memory/routes.js"]
Server --> RAG["rag/* (按需加载)"]
Server --> MCP["mcp/*"]
Server --> Skill["skill/*"]
Executor --> ChildProcess["child_process"]
Server --> WS["ws"]
Server --> FS["fs/fs/promises"]

图表来源

章节来源

性能与并发特性

请求体大小限制：JSON body 最大 200MB，multipart/form-data 同样限制。
流式上传：/api/fs/upload-stream 使用 createWriteStream，避免 base64 膨胀。
流式下载：/api/fs/download-stream 使用 createReadStream，分块 64KB 写出，避免 OOM。
ZIP 打包：使用 archiver，压缩级别 9，临时文件写入 tmpdir，完成后删除。
命令输出缓冲：stdout/stderr 最大 5MB，超限标记 truncated 并广播提示。
超时策略：受管模式支持最多 5 次延长，总预算封顶 600 秒。
配置缓存：内存缓存 + mtime 检测，写入加锁防并发覆盖。
WebSocket 心跳：30 秒 ping，检测半开连接。
进程树终止：Windows 用 taskkill /T，Unix 用负 PID 进程组信号。

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

API 端点规范

认证与配对

方法	路径	认证	说明
POST	`/api/pair`	无	提交 code 和 extensionId，返回 token
GET	`/api/status`	无	返回版本、平台、searchTools、ragAvailable
GET	`/api/heartbeat`	Bearer	刷新 lastAuthTime
POST	`/api/shutdown`	本机免认证，远程需 Bearer	停止 Agent
POST	`/api/agent/restart`	Bearer	重启 Agent
POST	`/api/agent/update`	Bearer	更新并重启 Agent

章节来源

文件操作

方法	路径	认证	说明
POST	`/api/files/upload`	Bearer	multipart/form-data 上传
POST	`/api/fs/upload-stream`	Bearer	原始二进制流式上传
GET/POST	`/api/fs/read`	Bearer	读取文件内容
POST	`/api/fs/write`	Bearer	写入文件，支持 utf-8/base64
POST	`/api/fs/list`	Bearer	列出目录
POST	`/api/fs/stat`	Bearer	获取文件详情
POST	`/api/fs/delete`	Bearer	移至回收站
POST	`/api/fs/download`	Bearer	返回 base64 内容
POST	`/api/fs/download-multi`	Bearer	批量打包 ZIP
POST	`/api/fs/download-stream`	Bearer	流式下载
POST	`/api/fs/preview-xlsx`	Bearer	服务端解析 XLSX 前 500 行
POST	`/api/fs/mkdir`	Bearer	创建目录
POST	`/api/fs/rename`	Bearer	重命名
POST	`/api/fs/move`	Bearer	移动文件/目录
POST	`/api/browser/open`	Bearer	本地浏览器打开文件

章节来源

命令执行

方法	路径	认证	说明
POST	`/api/exec`	Bearer	执行命令，返回 execId 和 wsUrl
POST	`/api/exec/stop`	Bearer	停止命令
POST	`/api/exec/detach`	Bearer	显式 daemon 化

WebSocket 地址：ws://{host}:{port}/ws/exec/{execId}?token={token}

章节来源

长期记忆

方法	路径	认证	说明
POST	`/api/memory/store`	Bearer	存储记忆
POST	`/api/memory/recall`	Bearer	检索记忆
POST	`/api/memory/manage`	Bearer	管理记忆
POST	`/api/memory/injectSelect`	Bearer	注入选择
POST	`/api/memory/reindex`	Bearer	重建向量缓存
GET	`/api/memory/embedding-config`	Bearer	读取 embedding 配置
POST	`/api/memory/embedding-config`	Bearer	保存 embedding 配置
POST	`/api/memory/test-embedding`	Bearer	测试 embedding 连通性
GET	`/api/memory/vector-status`	Bearer	向量缓存状态

章节来源

其他功能

方法	路径	认证	说明
POST	`/api/config/workdir`	Bearer	切换工作目录
POST	`/api/config/allowed-paths/remove`	Bearer	移除允许目录
GET	`/api/trash/list`	Bearer	回收站列表
POST	`/api/trash/restore`	Bearer	恢复回收站文件
GET	`/api/logs/query`	Bearer	查询审计日志
GET/POST	`/api/skill/*`	Bearer	技能管理
GET/POST/DELETE	`/api/mcp/*`	Bearer	MCP 工具管理
GET/POST	`/api/rag/*`	Bearer	RAG 知识库（可选依赖）

章节来源

错误码与响应约定

所有接口统一返回 JSON 结构：

成功：{ success: true, ... }
失败：{ success: false, error: "错误文案" }

常见 HTTP 状态码：

200：成功
400：参数错误、JSON 解析失败、文件大小超限
401：缺少 Authorization 或 Bearer Token
403：Token 无效、路径不在白名单、命令被拒绝
404：未知 API 路径
409：操作进行中、目标已存在
429：操作过于频繁
500：内部错误、RAG 路由加载失败
503：RAG 依赖不可用

错误文案来自 i18n，键名如 error.bodyTooLarge、error.invalidToken、security.pathNotInAllowedDir 等。

章节来源

故障排查指南

现象	可能原因	排查建议
端口占用	已有 Agent 进程	检查 `.ai-helper-agent/agent.pid`，或使用 `/api/shutdown` 停止
认证失败	Token 无效或过期	重新配对，检查 `pairings.json`
路径被拒绝	不在 allowedPaths 或 workdir	检查 `config.json` 的 allowedPaths 和 workdir
命令被拒绝	命中黑名单或灰名单	查看 security.js 的 BLACKLIST_PATTERNS 和 GRAYLIST_PATTERNS
WebSocket 断连	浏览器空闲、网络闪断、心跳未 pong	检查前端心跳逻辑，确认 `/ws/exec/{execId}` 连接存活
命令无输出	子进程静默失败、输出缓冲截断	查看 stderr 和 truncated 提示
RAG 不可用	依赖未安装或 Node 版本不兼容	调用 `/api/rag/install` 和 `/api/rag/detect`
优雅关闭卡住	仍有活跃 socket 或子进程	检查 activeSockets 和 runningProcesses

章节来源

结论

Agent 的 HTTP/WebSocket 服务器以 Node.js 原生模块为基础，实现了完整的安全控制、文件操作、命令执行、长期记忆、RAG、MCP 和 Skill 管理能力。其设计强调：

安全优先：路径白名单、硬阻止目录、命令黑白名单、配对码轮换、Token 认证。
可扩展：模块化路由、按需加载 RAG、MCP、Skill。
健壮性：优雅关闭、全局异常捕获、进程树终止、心跳检测。
可观测：审计日志、平台信息、资源使用统计。

对于生产部署，建议通过反向代理提供 HTTPS，严格限制来源 IP，并配合防火墙和监控告警。对于开发者，应遵循 i18n 文案、统一响应格式和安全校验流程，避免绕过 checkPath 和 checkCommand。

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

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

HTTP/WebSocket 服务器

目录

简介

项目结构

核心组件

架构总览

详细组件分析

HTTP 路由与中间件管道

认证与配对机制

路径与命令安全模型

命令执行与 WebSocket 流式输出

WebSocket 握手与连接管理

配置选项与服务发现

反向代理与 SSL/TLS 支持

服务健康检查、优雅关闭与资源清理

依赖关系分析

性能与并发特性

API 端点规范

认证与配对

文件操作

命令执行

长期记忆

其他功能

错误码与响应约定

故障排查指南

结论

Markdown 渲染引擎

HTTP/WebSocket 服务器 ​

目录 ​

简介 ​

项目结构 ​

核心组件 ​

架构总览 ​

详细组件分析 ​

HTTP 路由与中间件管道 ​

认证与配对机制 ​

路径与命令安全模型 ​

命令执行与 WebSocket 流式输出 ​

WebSocket 握手与连接管理 ​

配置选项与服务发现 ​

反向代理与 SSL/TLS 支持 ​

服务健康检查、优雅关闭与资源清理 ​

依赖关系分析 ​

性能与并发特性 ​

API 端点规范 ​

认证与配对 ​

文件操作 ​

命令执行 ​

长期记忆 ​

其他功能 ​

错误码与响应约定 ​

故障排查指南 ​

结论 ​

HTTP/WebSocket 服务器

目录

简介

项目结构

核心组件

架构总览

详细组件分析

HTTP 路由与中间件管道

认证与配对机制

路径与命令安全模型

命令执行与 WebSocket 流式输出

WebSocket 握手与连接管理

配置选项与服务发现

反向代理与 SSL/TLS 支持

服务健康检查、优雅关闭与资源清理

依赖关系分析

性能与并发特性

API 端点规范

认证与配对

文件操作

命令执行

长期记忆

其他功能

错误码与响应约定

故障排查指南

结论