> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 核心架构

> Zeus 系统架构 — 双层后端、多客户端、通信协议与数据流

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

## 概览

```mermaid theme={null}
graph TB
    subgraph Clients["客户端"]
        web["Web App<br/>(Next.js)"]
        desktop["Desktop App<br/>(Electron)"]
        ios["iOS App"]
        android["Android App"]
        ext["Browser Extension"]
        feishu["飞书 Bot"]
    end

    subgraph WebAPI["Web API (Next.js)"]
        auth["认证<br/>Better Auth + JWT"]
        api_routes["API Routes<br/>/api/sessions, /api/tools, /api/credits, ..."]
        db_layer["数据库层<br/>Drizzle ORM (Service → Model → Schema)"]
        storage_layer["存储层<br/>Supabase Storage / S3"]
        forward["Agent 转发<br/>/api/agent/invoke → AI Backend"]
    end

    subgraph AIBackend["AI Backend (FastAPI)"]
        agent_api["Agent API<br/>/api/agent/invoke, /api/agent/resume"]
        gateway["WebSocket Gateway<br/>/ws/extension, /ws/desktop, /ws/web"]
        service["Agent Service<br/>AgentService, RAGService"]
        tools["工具体系<br/>Built-in, MCP, OAuth, Connector"]
    end

    subgraph Infra["基础设施"]
        pg["PostgreSQL<br/>应用 DB + pgvector + Checkpointer"]
        redis["Redis<br/>缓存 + Result Backend"]
        rabbitmq["RabbitMQ<br/>消息队列"]
        s3["Supabase Storage / S3 (MinIO)<br/>工作空间文件"]
        llm["LLM Provider<br/>OpenAI / Custom"]
        sandbox["Sandbox<br/>E2B / OpenSandbox / Daytona"]
    end

    web -->|"HTTP"| api_routes
    desktop -->|"HTTP"| api_routes
    ios -->|"HTTP"| api_routes
    android -->|"HTTP"| api_routes
    feishu -->|"Webhook"| api_routes

    ext -->|"WebSocket"| gateway
    desktop -->|"WebSocket"| gateway

    api_routes --> db_layer
    api_routes --> storage_layer
    forward -->|"HTTP SSE"| agent_api

    db_layer --> pg
    storage_layer --> s3
    api_routes --> redis

    agent_api --> service
    gateway --> service
    service --> tools
    service --> pg
    service --> redis
    service --> rabbitmq
    tools --> llm
    tools --> sandbox
    tools -->|"JSON-RPC 2.0"| gateway
```

* **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 调用

```mermaid theme={null}
sequenceDiagram
    participant Client as 客户端<br/>(Web / Desktop / iOS / Android)
    participant WebAPI as Web API<br/>(Next.js)
    participant DB as PostgreSQL
    participant AIBackend as AI Backend<br/>(FastAPI)
    participant Node as 节点<br/>(Extension / Desktop)

    Client->>WebAPI: POST /api/agent/invoke<br/>{message, sessionId, ...}

    Note over WebAPI: 1. 认证（JWT）
    Note over WebAPI: 2. 检查并扣除积分
    WebAPI->>DB: 查询 LLM 配置、工具、技能
    DB-->>WebAPI: 用户配置

    Note over WebAPI: 3. 组装上下文<br/>(LLM 配置、工具、技能、环境变量)
    WebAPI->>AIBackend: 转发 POST /api/agent/invoke<br/>{message, llm_config, tools, session_id, ...}

    Note over AIBackend: 4. Agent 循环开始
    AIBackend-->>WebAPI: SSE: TextMessage（流式）
    WebAPI-->>Client: SSE: TextMessage（透传）

    AIBackend-->>WebAPI: SSE: ToolCallMessage
    WebAPI-->>Client: SSE: ToolCallMessage

    opt Connector Tool
        AIBackend->>Node: JSON-RPC 工具调用（WebSocket）
        Node-->>AIBackend: JSON-RPC 结果
    end

    AIBackend-->>WebAPI: SSE: ToolCallResult
    WebAPI-->>Client: SSE: ToolCallResult

    AIBackend-->>WebAPI: SSE: CompleteMessage
    WebAPI-->>Client: SSE: CompleteMessage
```

### WebSocket Gateway（网关）

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

```mermaid theme={null}
graph LR
    subgraph Gateway["ConnectionManager"]
        ext_pool["extension_connections<br/>user_id → {node_id → WS}"]
        desktop_pool["desktop_connections<br/>user_id → {node_id → WS}"]
        web_pool["web_connections<br/>user_id → {WS Set}"]
        pending["pending_requests<br/>request_id → Future"]
    end

    ext["Browser Extension"] -->|"/ws/extension"| ext_pool
    desktop["Desktop App"] -->|"/ws/desktop"| desktop_pool
    web["Web Client"] -->|"/ws/web"| web_pool

    pending -->|"resolve"| ext_pool
    pending -->|"resolve"| desktop_pool
```

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

### Agent Service（Agent 服务）

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

```mermaid theme={null}
graph TD
    invoke["invoke()"] --> init["_init_context()"]

    init --> load_tools["加载工具"]
    init --> build_prompt["组装 System Prompt"]
    init --> init_llm["初始化 LLM"]

    load_tools --> mcp["MCP Tools"]
    load_tools --> oauth["OAuth Tools"]
    load_tools --> browser["Browser Tools"]
    load_tools --> desktop_tools["Desktop Tools"]
    load_tools --> builtin["Built-in Tools<br/>(RAG, Memory, Sandbox, Web Search)"]

    build_prompt --> core["CORE.md"]
    build_prompt --> soul["SOUL.md"]
    build_prompt --> tools_prompt["TOOLS.md"]
    build_prompt --> workflow["WORKFLOW.md"]
    build_prompt --> memory_prompt["MEMORY.md"]
    build_prompt --> dynamic["动态注入<br/>(Profile, Memories, Skills)"]

    init --> create["_create_deep_agent()"]
    create --> stream["_astream_events()"]
    stream --> sse["SSE 响应流"]

    sse --> text["TextMessage"]
    sse --> tool_call["ToolCallMessage"]
    sse --> tool_result["ToolCallResultMessage"]
    sse --> complete["CompleteMessage"]
```

**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 的工具分为四层：

```mermaid theme={null}
graph LR
    subgraph L1["Built-in Tools"]
        memory["Memory Tools<br/>CRUD 操作"]
        rag["RAG Tools<br/>知识库检索"]
        sandbox["Sandbox Tools<br/>代码执行"]
        search["Web Search<br/>Tavily / DuckDuckGo"]
        skill_tool["Skill Tools<br/>动态技能加载"]
    end

    subgraph L2["MCP Tools"]
        mcp_tavily["Tavily MCP"]
        mcp_custom["Custom MCP Servers"]
    end

    subgraph L3["OAuth Tools"]
        github["GitHub"]
        gmail["Gmail"]
        gdrive["Google Drive"]
        notion["Notion"]
        slack["Slack"]
    end

    subgraph L4["Connector Tools"]
        browser_ops["Browser Automation<br/>(via Extension Node)"]
        desktop_ops["Desktop Automation<br/>(via Desktop Node)"]
    end
```

| 层级            | 来源                      | 注册方式                     | 执行位置                    |
| ------------- | ----------------------- | ------------------------ | ----------------------- |
| **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）** 规范：

**请求：**

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

**响应（成功）：**

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

**响应（错误）：**

```json theme={null}
{
  "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 启动

```mermaid theme={null}
graph TD
    start["uvicorn 启动"] --> env["load_dotenv()"]
    env --> langsmith["init_langsmith()"]
    langsmith --> lifespan["lifespan() 启动"]
    lifespan --> node_mgr["NodeManager.start()<br/>启动心跳清理循环"]
    lifespan --> feishu_init["FeishuService.initialize()<br/>初始化飞书"]
    lifespan --> scheduler_start["TaskScheduler.start()<br/>启动定时任务 + 同步"]
    scheduler_start --> ready["服务就绪"]
```

### 关键环境变量

**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/                    # 渠道集成
```

<CardGroup cols={2}>
  <Card title="Agent Runtime" icon="bolt" href="/zh/documentation/fundamentals/agent-runtime">
    运行时详细设计 — Workspace、Session、Modes
  </Card>

  <Card title="渠道与网关" icon="tower-broadcast" href="/zh/documentation/channels/overview">
    渠道与网关 — 飞书、WebSocket 节点通信
  </Card>

  <Card title="工具体系" icon="wrench" href="/zh/documentation/core-capabilities/tools">
    四层工具体系 — Built-in、MCP、OAuth、Connector
  </Card>

  <Card title="文件系统" icon="folder-open" href="/zh/documentation/core-capabilities/file-system/overview">
    存储架构 — CloudDriveBackend、Checkpoint
  </Card>
</CardGroup>