核心架构

Zeus 采用双层后端架构：Web API (Next.js) 作为中央网关，负责用户管理、数据库操作，并为所有客户端提供统一的 API 入口；AI Backend (FastAPI) 专注于 AI Agent 编排、工具执行和节点通信。

概览

Web API 是所有客户端的统一入口 — 负责认证、用户数据、会话/消息持久化、积分、工具配置等
AI Backend 接收 Web API 转发的 Agent 请求，执行 Agent 循环（LLM 推理 + 工具调用）
Extension / Desktop 节点 与 AI Backend 的 Gateway 保持直接 WebSocket 连接，用于实时工具执行（浏览器自动化、桌面控制）
每个用户拥有独立的云端工作空间（Supabase Storage / S3）和会话状态（PostgreSQL Checkpointer）

双层后端

Web API (Next.js) — 网关与数据层

Web API 是一个 Next.js 应用，作为所有客户端的中央 API 网关，拥有数据库并处理所有非 AI 相关的业务：

职责	详情
认证	Better Auth（OAuth、邮箱密码、SSO），JWT 签发与验证
用户管理	用户资料、头像、设置、Agent 偏好
数据库	PostgreSQL via Drizzle ORM — 会话、消息、工具、技能、知识库、项目、积分、案例
存储	Supabase Storage / S3 (MinIO) — 工作空间文件、技能文件、zeus 配置
积分系统	用量计量 — 在转发 Agent 调用前检查并扣除积分
工具配置	用户工具设置的 CRUD（MCP 服务器、OAuth Token 等）
技能管理	技能 CRUD、文件上传/下载、资源内容预取
知识库	知识库元数据 CRUD、文档上传、分块预览
会话管理	创建/列表/删除会话、消息持久化、事件追踪
Agent 转发	组装上下文（LLM 配置、工具、技能、环境变量）并通过 HTTP SSE 转发到 AI Backend

主要 API 路由（共 93 个）：

路由分组	示例	说明
`/api/auth/*`	登录、注册、JWT、SSO、device-code	认证
`/api/sessions/*`	CRUD、消息、事件、检查点	会话与消息管理
`/api/tools/*`	CRUD、MCP 验证	工具配置
`/api/skills/*`	CRUD、文件、开关、导入	技能管理
`/api/knowledge-base/*`	CRUD、文档、搜索、上传	知识库
`/api/projects/*`	CRUD、资源、会话	项目管理
`/api/credits/*`	余额、交易记录	积分系统
`/api/agent/invoke`	POST → 转发到 AI Backend	Agent 调用（转发）
`/api/agent/resume`	POST → 转发到 AI Backend	HITL 恢复（转发）
`/api/config/*`	LLM、嵌入模型、沙盒	用户配置
`/api/memory/*`	CRUD、搜索、Profile	记忆管理
`/api/scheduled-tasks/*`	CRUD、回调	定时任务管理
`/api/deploy/*`	部署、重启开发服务器	部署
`/api/storage/*`	文件、URL	文件存储

AI Backend (FastAPI) — Agent 执行引擎

AI Backend 是一个 FastAPI 服务，专注于 AI Agent 编排。它接收 Web API 转发的请求，处理所有 AI 相关的操作。 Agent Runtime 是 AI Backend 的核心，其他模块围绕它提供基础设施支撑：

AI Backend (FastAPI)
├── Agent Runtime（核心）
│   ├── AgentService / BaseService — invoke/resume 入口、上下文初始化
│   ├── DeepAgents 框架 — 基于 LangGraph 的 Agent 循环
│   ├── Tool System — Built-in、MCP、OAuth、Connector（四层工具体系）
│   ├── Prompt Assembly — CORE / SOUL / TOOLS / WORKFLOW / MEMORY + 动态注入
│   ├── Session & Checkpointer — 状态持久化、隔离、HITL 恢复
│   └── HITL — 敏感工具执行前的人工审批
├── WebSocket Gateway — 与 Extension / Desktop 节点的实时通信
├── RAG Service — 知识库检索（向量 + BM25 混合搜索）
├── Sandbox — 代码执行环境（E2B / OpenSandbox / Daytona）
├── Scheduler — 定时任务执行（TaskIQ + RabbitMQ）
└── Channels — 飞书等渠道集成

职责	详情
Agent Runtime	核心 Agent 循环 — LLM 推理、工具规划、多步执行、提示词组装、会话管理
WebSocket 网关	与 Extension/Desktop 节点的实时双向通信
RAG Service	知识库检索（向量 + BM25 混合搜索）
沙盒	代码执行环境管理（E2B / OpenSandbox / Daytona）
定时任务	任务调度与异步执行（via TaskIQ + RabbitMQ）
渠道	飞书 Bot 等渠道集成

AI Backend API 路由：

路由	说明	协议
`/api/agent/invoke`	Agent 对话调用	HTTP POST → SSE Stream
`/api/agent/resume`	HITL 恢复执行	HTTP POST → SSE Stream
`/api/knowledge-base/*`	知识库 RAG 操作	HTTP REST
`/api/node/*`	节点设备查询	HTTP REST
`/api/scheduled-task/*`	定时任务管理	HTTP REST
`/api/deploy/*`	编程项目部署	HTTP REST
`/api/sandbox/*`	沙盒管理	HTTP REST
`/ws/extension`	浏览器扩展 WebSocket	WebSocket
`/ws/desktop`	桌面应用 WebSocket	WebSocket
`/ws/web`	Web 客户端 WebSocket	WebSocket

组件与数据流

请求流程 — Agent 调用

WebSocket Gateway（网关）

网关通过 ConnectionManager 管理所有 WebSocket 连接，支持三种节点类型：

Extension / Desktop 节点：每个节点通过 node_id 唯一标识，支持一个用户多个节点
Web 客户端：按 user_id 管理，同一用户可有多个 Web 连接
工具调用：Agent 通过 call_tool() 发起 JSON-RPC 请求，Gateway 将请求路由到对应节点并等待响应（Future-based）

Agent Service（Agent 服务）

Agent 服务是核心编排层，基于 DeepAgents 框架（LangGraph 上层封装）： Service 层分工：

服务	文件	职责
BaseService	`services/base.py`	上下文初始化、工具装配、提示词组装、SSE 事件流
AgentService	`services/agent.py`	Agent 模式的 invoke/resume 入口
RAGService	`services/rag.py`	知识库检索（向量 + BM25 混合搜索）
DocumentService	`services/document.py`	文档处理与切块
FeishuService	`services/feishu.py`	飞书渠道集成
SchedulerService	`services/scheduler.py`	定时任务调度

Tool System（工具体系）

Zeus 的工具分为四层：

层级	来源	注册方式	执行位置
Built-in	`utils/tools/built_in/`	代码内直接注册	AI Backend 本地
MCP	前端配置传入	`langchain_mcp_adapters`	MCP Server（远程）
OAuth	前端配置传入	动态构建 LangChain Tool	AI Backend → OAuth API
Connector	WebSocket 节点上报	SessionManager 绑定	远程节点（Extension/Desktop）

Connector Tools 的调用链路：Agent → ToolRouter → Gateway → WebSocket → Node → 执行 → 原路返回。

Node Management（节点管理）

节点管理由三个组件协同完成：

组件	说明
NodeManager	节点注册/注销、心跳 TTL（60s）、周期性清理（30s）
SessionManager	将 Session 绑定到具体节点，支持 `preferred_node_id` 指定
ToolRouter	根据 Session 绑定决定工具调用路由到哪个节点

每个用户最多 10 个节点，超时未心跳的节点自动标记离线并注销。

Storage & State（存储与状态）

存储	技术	归属	用途
应用数据库	PostgreSQL (Drizzle ORM)	Web API	用户、会话、消息、工具、技能、积分、项目、案例
Checkpointer	PostgreSQL（`PostgresSaver`）	AI Backend	会话级 Agent 状态持久化，支持 HITL 恢复
Memory	PostgreSQL + pgvector	AI Backend	长期记忆（向量 + 元数据），三级作用域
Knowledge Base	PostgreSQL + pgvector + BM25	AI Backend	RAG 文档存储与混合检索
Workspace	Supabase Storage / S3 (MinIO)	Web API	用户文件（产出、上传、沙盒结果），配置 `S3_ENDPOINT` 时自动切换到 S3
Cache	Redis	双方	工作空间缓存（5min）、记忆缓存（10min）、TaskIQ 结果后端
消息队列	RabbitMQ (TaskIQ)	AI Backend	异步任务代理，用于定时任务、RAG 处理、云同步

通信协议

HTTP SSE（Agent 响应流）

Agent 调用返回 text/event-stream，SSE 事件类型：

事件类型	data 字段	说明
`text`	`{type, content}`	流式文本 token
`tool_call`	`{type, tool_name, tool_args, tool_call_id}`	Agent 发起工具调用
`tool_call_result`	`{type, tool_name, result, ...}`	工具执行结果
`interrupt`	`{type, tool_calls, ...}`	HITL 中断，等待用户审批
`complete`	`{type, finish_reason}`	流结束
`error`	`{type, error}`	错误信息

WebSocket JSON-RPC 2.0（节点工具调用）

节点工具调用遵循 MCP（Model Context Protocol） 规范： 请求：

{
  "jsonrpc": "2.0",
  "id": "uuid-string",
  "method": "tools/call",
  "params": {
    "name": "browser_click",
    "arguments": { "selector": "#submit-btn" },
    "session_id": "session_abc123"
  }
}

响应（成功）：

{
  "jsonrpc": "2.0",
  "id": "uuid-string",
  "result": {
    "content": [
      { "type": "text", "text": "Clicked element successfully" },
      { "type": "image", "data": "base64...", "mimeType": "image/jpeg" }
    ],
    "isError": false
  }
}

响应（错误）：

{
  "jsonrpc": "2.0",
  "id": "uuid-string",
  "error": {
    "code": -32603,
    "message": "Element not found"
  }
}

WebSocket 消息类型（非 JSON-RPC）

方向	type	说明
Node → Gateway	`register`	节点注册（capabilities, tools）
Gateway → Node	`registered`	注册确认
Node → Gateway	`heartbeat`	心跳上报（status, current_tasks）
Gateway → Node	`heartbeat_ack`	心跳确认
Node ↔ Gateway	`ping` / `pong`	Keepalive
Web → Gateway	`get_workflows`	请求工作流列表（转发至 Extension）
Web → Gateway	`execute_workflow`	执行工作流
Node → Gateway	`task_complete`	工作流执行完成

启动与生命周期

Web API 启动

Next.js 应用自动启动并提供：

所有 API 路由 /api/*
Web 前端页面 /[locale]/*
通过 Better Auth 中间件处理认证

AI Backend 启动

关键环境变量

Web API (Next.js)：

变量	说明
`DATABASE_URL`	PostgreSQL 连接串（应用数据库）
`BACKEND_URL`	AI Backend URL，用于 Agent 转发（默认：`http://localhost:8000`）
`BETTER_AUTH_SECRET`	Better Auth 密钥
`SUPABASE_URL` / `SUPABASE_SERVICE_KEY`	Supabase Storage 配置
`S3_ENDPOINT` / `S3_ACCESS_KEY` / `S3_SECRET_KEY`	S3/MinIO 存储（替代 Supabase，可选）

AI Backend (FastAPI)：

变量	说明
`DATABASE_URL`	PostgreSQL 连接串（Checkpointer + pgvector）
`NEXTJS_API_URL`	Web API URL，用于回调（用户数据、配置查询）
`OPENAI_API_KEY` / `OPENAI_BASE_URL`	默认 LLM 配置
`REDIS_URL`	Redis 缓存和 TaskIQ 结果后端（可选）
`RABBITMQ_URL`	RabbitMQ 消息队列，用于异步任务（可选）
`LANGCHAIN_API_KEY`	LangSmith 追踪（可选）

健康检查

AI Backend: GET /health → {"status": "ok"}
AI Backend: GET / → {"name": "Zeus Backend API", "version": "1.0.0", "status": "running"}

系统不变量

JWT 认证：所有 Web API 路由必须携带有效 JWT Token；AI Backend 接收 Web API 转发的 Token
Session 隔离：每个 session_id 对应独立的 Checkpointer 状态，不同 Session 互不干扰
节点心跳：超过 60 秒未心跳的节点自动标记离线；Gateway 在节点断连时立即注销
工具调用超时：WebSocket 工具调用默认 60 秒超时，工作流执行 300 秒超时
SSE 不重放：Agent 调用的 SSE 流是一次性的，断连后需通过 Checkpointer 恢复上下文
积分门控：Web API 在转发任何 Agent 请求到 AI Backend 之前，先检查并扣除积分
单实例 Gateway：当前 ConnectionManager 为进程内单例，WebSocket 连接不跨进程共享

目录结构

Web API (Next.js)：

apps/web/src/
├── app/
│   ├── [locale]/                    # 页面路由（i18n）
│   └── api/                         # API 路由（共 93 个）
│       ├── agent/                   # Agent 转发 → AI Backend
│       ├── auth/                    # 认证
│       ├── sessions/                # 会话管理
│       ├── tools/                   # 工具配置
│       ├── skills/                  # 技能管理
│       ├── knowledge-base/          # 知识库
│       ├── projects/                # 项目管理
│       ├── credits/                 # 积分系统
│       ├── memory/                  # 记忆管理
│       ├── config/                  # LLM / 嵌入模型 / 沙盒配置
│       └── ...
├── db/
│   ├── schema/                      # Drizzle ORM 表结构定义
│   ├── model/                       # 数据访问层（CRUD）
│   ├── service/                     # 业务逻辑层
│   └── storage/                     # 存储操作
├── lib/auth/                        # 认证（Better Auth, JWT）
└── ...

AI Backend (FastAPI)：

apps/ai-backend/src/
├── api/                             # FastAPI 路由层
│   ├── main.py                      # 入口 & 生命周期
│   ├── gateway.py                   # WebSocket 网关
│   ├── agent.py                     # Agent API（invoke/resume）
│   ├── mcp_gateway.py               # MCP 协议网关
│   ├── skill.py                     # 技能 API
│   ├── tools.py                     # 工具 API
│   ├── knowledge_base.py            # 知识库 RAG API
│   ├── node.py                      # 节点查询 API
│   ├── scheduled_task.py            # 定时任务 API
│   ├── deploy.py                    # 部署 API
│   ├── sandbox.py                   # 沙盒 API
│   └── channels/                    # 渠道（飞书）
├── services/                        # 业务逻辑层
│   ├── base.py                      # BaseService（Agent 核心）
│   ├── agent.py                     # AgentService
│   ├── rag.py                       # RAG 检索
│   ├── document.py                  # 文档处理
│   ├── sandbox.py                   # 沙盒管理
│   ├── notification.py              # 通知服务
│   ├── feishu.py                    # 飞书服务
│   └── scheduler.py                 # 定时任务
├── repository/                      # 数据模型 & 提示词
│   ├── models/                      # Pydantic Models
│   ├── prompts/                     # System Prompts (.md)
│   └── skills/                      # 技能定义
└── utils/                           # 工具层
    ├── core/                        # LLM, Memory, Skills, HITL
    ├── infra/                       # Backend, Checkpoint, Node, Redis, Auth
    ├── tools/                       # 工具实现
    │   ├── built_in/                # 内置工具
    │   └── plugin/                  # 插件工具（飞书）
    ├── sandbox/                     # 沙盒 Provider（E2B, OpenSandbox, Daytona）
    ├── knowledge_base/              # 向量存储 & 切块
    └── channels/                    # 渠道集成

Agent Runtime

运行时详细设计 — Workspace、Session、Modes

渠道与网关

渠道与网关 — 飞书、WebSocket 节点通信

工具体系

四层工具体系 — Built-in、MCP、OAuth、Connector

文件系统

存储架构 — CloudDriveBackend、Checkpoint

开始使用

基础概念

核心能力

基础设施

渠道

概览

双层后端

Web API (Next.js) — 网关与数据层

AI Backend (FastAPI) — Agent 执行引擎

组件与数据流

请求流程 — Agent 调用

WebSocket Gateway（网关）

Agent Service（Agent 服务）

Tool System（工具体系）

Node Management（节点管理）

Storage & State（存储与状态）

通信协议

HTTP SSE（Agent 响应流）

WebSocket JSON-RPC 2.0（节点工具调用）

WebSocket 消息类型（非 JSON-RPC）

启动与生命周期

Web API 启动

AI Backend 启动

关键环境变量

健康检查

系统不变量

目录结构

Agent Runtime

渠道与网关

工具体系

文件系统

​概览

​双层后端

​Web API (Next.js) — 网关与数据层

​AI Backend (FastAPI) — Agent 执行引擎

​组件与数据流

​请求流程 — Agent 调用

​WebSocket Gateway（网关）

​Agent Service（Agent 服务）

​Tool System（工具体系）

​Node Management（节点管理）

​Storage & State（存储与状态）

​通信协议

​HTTP SSE（Agent 响应流）

​WebSocket JSON-RPC 2.0（节点工具调用）

​WebSocket 消息类型（非 JSON-RPC）

​启动与生命周期

​Web API 启动

​AI Backend 启动

​关键环境变量

​健康检查

​系统不变量

​目录结构

Agent Runtime

渠道与网关

工具体系

文件系统

概览

双层后端

Web API (Next.js) — 网关与数据层

AI Backend (FastAPI) — Agent 执行引擎

组件与数据流

请求流程 — Agent 调用

WebSocket Gateway（网关）

Agent Service（Agent 服务）

Tool System（工具体系）

Node Management（节点管理）

Storage & State（存储与状态）

通信协议

HTTP SSE（Agent 响应流）

WebSocket JSON-RPC 2.0（节点工具调用）

WebSocket 消息类型（非 JSON-RPC）

启动与生命周期

Web API 启动

AI Backend 启动

关键环境变量

健康检查

系统不变量

目录结构