系统架构总览¶

📎 引用文件

本文引用的文件 - agent/api_server.py - agent/mcp_server.py - frontend/src/main.tsx - desktop/electron/src/main.ts - docker-compose.yml - agent/src/agent/__init__.py - agent/src/agent/loop.py - agent/src/tools/__init__.py - agent/src/agent/tools.py - agent/src/memory/persistent.py - agent/src/session/service.py

简介¶

本文件为 Vibe-Trading 的系统架构总览，面向产品、研发与运维读者，说明前后端分离的设计模式：React 前端通过 REST API 和 WebSocket/SSE 与 FastAPI 后端通信；Electron 桌面应用作为本地客户端封装并管理后端进程。文档重点阐述 API 网关、Agent 核心、工具注册表、记忆系统与会话管理等关键组件，解释数据流向（用户请求→API 路由→Agent 处理→工具调用→数据获取→结果返回），并给出生产部署拓扑与可观测性建议。

项目结构¶

前端（React + Vite）：提供 Web UI，负责页面路由、状态管理与与后端的 HTTP/WebSocket 通信。
后端（FastAPI）：统一 API 网关，挂载安全中间件、CORS、SPA 静态资源托管，按功能域注册路由模块（运行、会话、设置、上传、通道、群智、实盘、Alpha 等）。
Agent 核心：ReAct 循环驱动 LLM 推理与工具编排，内置上下文压缩、心跳、追踪与使用量统计。
工具注册表：自动发现 BaseTool 子类，支持本地工具与远程 MCP 工具合并注册，具备白名单过滤与安全策略。
记忆系统：基于文件的跨会话持久化记忆，含重要性衰减、去重、索引与并发锁。
会话管理：会话生命周期、消息持久化、SSE 事件总线、尝试（Attempt）调度与并发控制。
Electron 桌面：启动/停止后端进程、注入鉴权头、安全限制渲染进程权限、日志与凭据管理。
容器化：Docker Compose 编排后端服务与可选的前端开发服务，卷持久化关键数据，运行时加固。

graph TB FE["前端 React Vite"] --> |REST / SSE| API["FastAPI 网关 api_server.py"] DESK["Electron 桌面 main.ts"] --> |进程管理+鉴权| API API --> |路由分发| ROUTES["业务路由模块"] ROUTES --> SESS["会话服务 service.py"] SESS --> LOOP["Agent 核心循环 loop.py"] LOOP --> REG["工具注册表 tools/__init__.py"] REG --> TOOLS["工具实现 BaseTool/ToolRegistry"] LOOP --> MEM["记忆系统 persistent.py"] API --> MCP["MCP 服务器 mcp_server.py"]

图表来源 - agent/api_server.py:163-239 - agent/src/session/service.py:53-91 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115 - agent/mcp_server.py:1-50

章节来源 - agent/api_server.py:163-239 - frontend/src/main.tsx:1-36 - desktop/electron/src/main.ts:65-117 - docker-compose.yml:1-66

核心组件¶

API 网关（FastAPI）
职责：创建应用、挂载 CORS/安全中间件、注册各功能路由、提供 SPA 静态资源、启动/关闭后台任务（定时研究、通道运行时）。
关键点：生命周期钩子执行预检、迁移与启动；访问日志脱敏；端口/主机绑定与开发模式联动 Vite。
Agent 核心（ReAct 循环）
职责：五层上下文管理（微紧凑、折叠、自动摘要、显式压缩、迭代更新）、工具并行执行、心跳与进度事件、LLM 用量聚合与持久化。
关键点：超时、重试、内容过滤、Token 预算与尾保护。
工具注册表
职责：自动发现 BaseTool 子类，构建 ToolRegistry；支持本地工具与远程 MCP 工具合并；白名单过滤与安全策略（如禁用 shell 工具）。
关键点：MCP 服务器隔离、失败不扩散、活券商通道包装与授权检查。
记忆系统
职责：跨会话持久化存储、重要性衰减、去重、搜索索引、并发锁。
关键点：文件级锁、滑动窗口去重、非拉丁字符分词、截断与清理。
会话管理
职责：会话创建/查询/删除、消息追加、SSE 事件发布、尝试调度与并发控制（每会话单实例）。
关键点：抢占式预留防止并发冲突、线程池限制 Agent 并发、终端状态事件映射。

章节来源 - agent/api_server.py:127-183 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115 - agent/src/memory/persistent.py:196-200 - agent/src/session/service.py:53-91

架构总览¶

整体采用前后端分离与模块化微服务思想： - 前端（React）通过 REST 与 SSE/WebSocket 与后端交互，Electron 作为本地客户端封装后端进程并提供安全边界。 - 后端以 FastAPI 为统一入口，按领域拆分路由模块，内部通过会话服务协调 Agent 循环与工具执行。 - 工具体系支持本地与远程 MCP 工具，便于扩展第三方能力并保持安全隔离。 - 记忆与会话提供跨会话状态与事件流，支撑长时研究与多轮对话。

sequenceDiagram participant U as "用户" participant FE as "前端 React" participant API as "FastAPI 网关" participant S as "会话服务" participant A as "Agent 核心" participant R as "工具注册表" participant T as "工具实现" participant M as "记忆系统" U->>FE : 输入问题/指令 FE->>API : POST /sessions/{id}/messages (REST) API->>S : send_message(session_id, content) S->>A : 调度 AgentLoop A->>R : 解析意图并选择工具 R->>T : 执行工具(读/写批量并行) T-->>A : 工具结果 A->>M : 写入/检索记忆 A-->>S : 生成助手消息/进度 S-->>FE : SSE 事件推送 FE-->>U : 展示结果

图表来源 - agent/src/session/service.py:158-200 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115 - agent/src/memory/persistent.py:196-200

详细组件分析¶

API 网关（FastAPI）¶

启动流程：生命周期钩子执行预检、配置迁移、启动定时研究与可选通道运行时。
中间件：CORS、安全头、SPA 深链回退、拒绝不可信回环主机。
路由挂载：运行、会话、系统、设置、上传、通道、群智、实盘、Alpha、认证、OpenBB 桥接等。
静态资源：生产环境挂载前端 dist，开发模式启动 Vite 并输出调试信息。
日志：安装访问日志脱敏过滤器，避免敏感参数泄露。

flowchart TD Start(["启动 serve_main"]) --> Preflight["运行预检与迁移"] Preflight --> MountRoutes["挂载各功能路由模块"] MountRoutes --> Static["挂载前端静态资源或启动 Vite"] Static --> RunServer["启动 Uvicorn 服务"] RunServer --> Shutdown{"关闭信号?"} Shutdown --> |是| Stop["停止通道与定时任务"] Shutdown --> |否| RunServer

图表来源 - agent/api_server.py:127-183 - agent/api_server.py:321-395

章节来源 - agent/api_server.py:127-183 - agent/api_server.py:321-395

Agent 核心（ReAct 循环）¶

上下文管理：五层压缩策略，降低长上下文成本，保留最近片段与结构化摘要。
工具执行：连续只读工具并行执行，提升吞吐；支持超时与重试。
可观测性：心跳、进度事件、TraceWriter、LLM 用量聚合与持久化。
安全与合规：内容过滤、结果脱敏、Token 预算与尾保护。

classDiagram class AgentLoop { +run() +build_context() +execute_tools_parallel() +record_llm_usage() } class ContextBuilder { +build() } class WorkspaceMemory { +read() +write() } class ToolRegistry { +get_definitions() +execute(name, params) } AgentLoop --> ContextBuilder : "构建上下文" AgentLoop --> WorkspaceMemory : "读写记忆" AgentLoop --> ToolRegistry : "调用工具"

图表来源 - agent/src/agent/loop.py:1-12 - agent/src/agent/tools.py:54-95

章节来源 - agent/src/agent/loop.py:1-12 - agent/src/agent/tools.py:54-95

工具注册表¶

自动发现：扫描 src/tools 包下所有 BaseTool 子类，缓存结果。
构建策略：优先注册本地工具，再根据配置附加远程 MCP 工具；失败隔离，不影响其他服务器。
安全策略：默认禁用 shell 工具；对活券商通道进行包装与授权检查；支持白名单过滤。
接口：提供 get_definitions 与 execute，统一错误封装。

flowchart TD Build["build_registry()"] --> Discover["扫描 BaseTool 子类"] Discover --> RegisterLocal["注册本地工具"] RegisterLocal --> CheckMCP{"是否配置 MCP 服务器?"} CheckMCP --> |否| ReturnReg["返回 ToolRegistry"] CheckMCP --> |是| WrapMCP["构建 MCP 工具包装器"] WrapMCP --> LiveCheck{"是否为活券商通道?"} LiveCheck --> |是| WrapLive["包装并授权检查"] LiveCheck --> |否| AppendMCP["直接追加到注册表"] WrapLive --> AppendMCP AppendMCP --> ReturnReg

图表来源 - agent/src/tools/__init__.py:66-115 - agent/src/tools/__init__.py:155-245

章节来源 - agent/src/tools/__init__.py:66-115 - agent/src/tools/__init__.py:155-245

记忆系统¶

存储模型：MemoryEntry 包含标题、描述、类型、正文、时间戳、质量分、访问计数、重要性、相关记忆等。
并发与一致性：文件级独占锁，超时释放；Windows 兼容路径。
去重与检索：滑动窗口去重、非拉丁字符分词、搜索索引。
重要性衰减：Ebbinghaus 风格衰减公式，结合访问奖励。

flowchart TD Write["写入记忆"] --> Lock["获取文件锁"] Lock --> Dedup{"去重命中?"} Dedup --> |是| Update["更新元数据/时间戳"] Dedup --> |否| Create["创建新条目"] Update --> Index["更新索引"] Create --> Index Index --> Unlock["释放锁"]

图表来源 - agent/src/memory/persistent.py:41-73 - agent/src/memory/persistent.py:196-200

章节来源 - agent/src/memory/persistent.py:41-73 - agent/src/memory/persistent.py:196-200

会话管理¶

生命周期：创建、查询、列表、删除；消息追加与搜索索引更新。
并发控制：每会话单实例，抢占式预留防止并发冲突；线程池限制 Agent 并发。
事件流：SSE 事件总线，将消息接收、尝试完成/取消/失败等事件推送至前端。
错误处理：SessionBusyError 用于 409 冲突提示；异常捕获与状态回滚。

sequenceDiagram participant API as "API 路由" participant S as "会话服务" participant E as "事件总线" participant A as "AgentLoop" API->>S : send_message(session_id, content) S->>S : _reserve_session() S->>E : emit("message.received") S->>A : 调度执行 A-->>S : 进度/结果 S->>E : emit("attempt.completed/cancelled/failed")

图表来源 - agent/src/session/service.py:53-91 - agent/src/session/service.py:158-200

章节来源 - agent/src/session/service.py:53-91 - agent/src/session/service.py:158-200

MCP 服务器（可选扩展点）¶

传输方式：stdio、SSE（遗留）、Streamable HTTP（当前默认）。
安全加固：Host/Origin 白名单中间件，防御 DNS 重绑定；默认仅允许回环地址。
工具暴露：技能、目标、回测、因子、市场数据、基本面、新闻、发现、交易连接器读取、群智编排、影子账户分析等；明确禁止下单/撤单工具。
会话隔离：进程级会话 ID 默认稳定，支持客户端传入会话标识。

graph LR Client["MCP 客户端"] --> |HTTP/SSE| HostGuard["Host 守卫中间件"] HostGuard --> OriginGuard["Origin 守卫中间件"] OriginGuard --> FastMCP["FastMCP 应用"] FastMCP --> Tools["工具集合 本地+远程"]

图表来源 - agent/mcp_server.py:131-317 - agent/mcp_server.py:1-50

章节来源 - agent/mcp_server.py:131-317 - agent/mcp_server.py:1-50

前端与 Electron 客户端¶

前端：React 入口初始化路由、错误边界、通知与懒加载优化。
Electron：主进程创建窗口、注入安全偏好、拦截导航与外链、IPC 通信、后端进程管理、凭据存储、日志与菜单。
安全：渲染进程禁用 Node 集成与沙箱启用；仅向可信后端源注入 Bearer Token；外部链接白名单校验。

graph TB Main["Electron 主进程 main.ts"] --> Window["BrowserWindow"] Main --> Backend["BackendManager"] Backend --> API["FastAPI 后端"] Window --> FE["React 前端"] FE --> |REST/SSE| API

图表来源 - desktop/electron/src/main.ts:65-117 - desktop/electron/src/main.ts:159-192 - frontend/src/main.tsx:1-36

章节来源 - desktop/electron/src/main.ts:65-117 - desktop/electron/src/main.ts:159-192 - frontend/src/main.tsx:1-36

依赖关系分析¶

组件耦合
API 网关依赖会话服务、工具注册表、MCP 服务器与各类路由模块。
会话服务依赖事件总线、存储与 Agent 核心。
Agent 核心依赖上下文构建、记忆系统与工具注册表。
工具注册表依赖 BaseTool 与 MCP 适配器。
外部依赖
FastAPI/Uvicorn 提供 ASGI 服务。
Docker Compose 编排服务与卷持久化。
可选 Ollama 本地 LLM 服务。
潜在循环依赖
通过分层与延迟导入避免循环；例如在路由中按需导入模块。

graph TB API["API 网关"] --> SESS["会话服务"] SESS --> LOOP["Agent 核心"] LOOP --> REG["工具注册表"] REG --> TOOLS["工具实现"] API --> MCP["MCP 服务器"] API --> ROUTES["路由模块"]

图表来源 - agent/api_server.py:163-239 - agent/src/session/service.py:53-91 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115

章节来源 - agent/api_server.py:163-239 - agent/src/session/service.py:53-91 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115

性能与可扩展性¶

性能
工具并行执行：连续只读工具批量并行，提升吞吐。
上下文压缩：多层压缩减少 LLM 输入长度，降低成本。
资源限制：容器内 CPU/内存/PID 限制，防止失控。
可扩展性
模块化路由：新增功能只需注册路由模块。
工具注册表：新增工具即插即用，支持远程 MCP 扩展。
独立部署：各组件可通过容器或服务网格独立扩缩容。

[本节提供通用指导，无需特定文件引用]

可观测性与监控¶

日志
访问日志脱敏：避免 API Key/Ticket 泄露。
工具执行异常：统一记录工具失败与堆栈。
前端错误边界：捕获渲染期异常并提示。
指标
LLM 用量：逐迭代累计输入/输出/总 Token 数与调用次数，持久化为 JSON 工件。
心跳与进度：AgentLoop 定期发出心跳与阶段事件，便于 UI 与监控采集。
追踪
TraceWriter：记录工具调用链路与结果，便于回溯。
SSE 事件：会话级事件流，便于实时观察与审计。

章节来源 - agent/api_server.py:384-387 - agent/src/agent/loop.py:175-200 - frontend/src/main.tsx:28-35

故障排查指南¶

常见问题
会话忙：409 冲突，等待或取消当前尝试。
工具不可用：依赖缺失或安全检查未通过，查看日志中的跳过原因。
MCP 连接失败：网络或鉴权问题，检查 Host/Origin 白名单与凭据。
前端无法加载：确认后端静态资源挂载或 Vite 开发服务器状态。
定位步骤
查看后端访问日志与工具异常日志。
检查容器资源限制与卷挂载是否正确。
验证环境变量与凭据存储状态。

章节来源 - agent/src/session/service.py:43-50 - agent/src/tools/__init__.py:136-153 - agent/mcp_server.py:229-286 - agent/api_server.py:371-377

结论¶

Vibe-Trading 采用前后端分离与模块化设计，通过 FastAPI 统一网关、ReAct Agent 核心、工具注册表、记忆系统与会话管理，实现了高内聚、低耦合的金融研究与交易辅助平台。其优势在于： - 模块化：按领域拆分路由与组件，易于维护与测试。 - 可扩展性：工具注册表支持本地与远程 MCP 工具，灵活接入第三方能力。 - 独立部署：容器化与资源限制保障稳定性，便于横向扩展。 - 可观测性：日志、指标与事件流覆盖全链路，便于监控与排障。

[本节总结性内容，无需特定文件引用]

附录：部署拓扑图¶

生产环境建议拓扑： - 反向代理（Nginx/云厂商 LB）：终止 TLS，转发至后端与前端。 - 后端服务（FastAPI）：单实例或多副本，共享卷持久化 runs/sessions/uploads。 - 前端服务（React 静态资源）：由后端或 CDN 托管。 - 数据库/缓存（可选）：会话索引或缓存加速。 - 外部服务：LLM（本地 Ollama 或云端）、数据源（交易所/行情 API）。

graph TB subgraph "客户端" FE["浏览器/桌面 Electron"] end subgraph "边缘" LB["负载均衡/反向代理"] end subgraph "后端" API["FastAPI 网关"] AGENT["Agent 核心"] REG["工具注册表"] MEM["记忆系统"] SES["会话服务"] end subgraph "外部" LLM["LLM 服务"] DATA["数据源/交易所"] end FE --> LB LB --> API API --> SES SES --> AGENT AGENT --> REG REG --> DATA AGENT --> MEM AGENT --> LLM

图表来源 - docker-compose.yml:1-66 - agent/api_server.py:163-239 - agent/src/session/service.py:53-91 - agent/src/agent/loop.py:1-12 - agent/src/tools/__init__.py:66-115 - agent/src/memory/persistent.py:196-200

← 技术栈概览项目介绍与目标 →