Wegent 系统架构全景报告

深度拆解：AI-native 智能体团队操作系统

执行摘要

Wegent 是一个基于 Kubernetes 风格 CRD 设计的 AI-native 操作系统，用于定义、组织和运行智能体团队。系统采用分层微服务架构，支持多种执行引擎和协作模式。

核心架构决策

决策方案理由
API 设计Kubernetes 风格 CRD声明式资源管理，云原生兼容
存储策略双表存储 (kinds + tasks)性能优化，Task/Workspace 高频写入分离
实时通信Socket.IO + Redis Adapter水平扩展，房间路由
执行隔离Docker 容器安全沙箱，资源隔离
流式架构HTTP SSE + WebSocket BridgeChat Shell 直连，兼顾效率与兼容性

1. 领域模型与 CRD 架构

1.1 资源层次结构

Ghost (提示词 + MCP + Skills)
  ↓
Model (AI 模型配置)
  ↓
Shell (执行环境)
  ↓
Bot = Ghost + Model + Shell            ← 可复用构建块
  ↓
Team = Bot(s) + 协作模式               ← 用户面对智能体
  ↓
Task = Team + Workspace                ← 执行单元

1.2 存储设计

资源类型存储表说明
Ghost/Model/Shell/Bot/Team/SkillkindsJSON spec 字段存储配置
Task/Workspacetasks独立表，高频查询优化
Skill 二进制skill_binariesZIP 包存储

1.3 关键技术特点

  • 单表继承 (STI)：kind 字段作为鉴别器
  • 引用模式：Namespace + Name 元组，兼容 Kubernetes
  • 软删除：is_active 标志，无外键约束
  • 多态上下文：SubtaskContext 支持附件/知识库/表格

2. 后端 API 架构

2.1 双 API 策略

API 类型路径用途
传统 REST/api/teams前端兼容性
CRD API/api/v1/namespaces/{ns}/teams/{name}Kubernetes 风格

2.2 WebSocket 架构

命名空间：

  • /chat - 用户聊天界面
  • /local-executor - 本地设备连接

房间路由：

  • user:{user_id} - 用户通知
  • task:{task_id} - 任务聊天和更新

事件系统：

  • chat:start - AI 开始响应
  • chat:chunk - 流式内容块
  • chat:done - 响应完成
  • chat:error - 错误处理

2.3 复杂子系统

  1. Skill 系统：动态加载，按需注入提示词，节省 40-80% Token
  2. RAG 流水线：可配置分块存储（DB vs 向量）
  3. 调度系统：可插拔后端（Celery/APScheduler/XXL-JOB）

3. 执行层架构

3.1 组件结构

Executor Manager
├── TaskScheduler (APScheduler)
├── ExecutorDispatcher
├── DockerExecutor (容器生命周期)
├── TaskQueueService (Redis 队列)
└── RunningTaskTracker (心跳监控)

Executor (Docker 容器内)
├── FastAPI Server
├── AgentFactory
│   ├── ClaudeCodeAgent
│   ├── AgnoAgent
│   ├── DifyAgent
│   └── ImageValidatorAgent
└── CallbackClient (进度上报)

3.2 调度模式

模式机制适用场景
Pull定时轮询 Backend API默认模式
PushRedis 队列 + 异步消费低延迟要求
服务池default/canary灰度发布

3.3 关键机制

  • 会话持久化：task_id:bot_id 作为 Redis Key，支持对话复用
  • 心跳检测：容器心跳上报，OOM 自动检测
  • 自定义镜像：Init Container 模式，Named Volume 挂载
  • 取消流：状态机防止竞态，不同 Agent 类型不同策略

4. 前端架构

4.1 技术栈

  • 框架：Next.js 15 + React 19 + TypeScript
  • 样式：Tailwind CSS + shadcn/ui
  • 状态：React Context（无 Redux）
  • 实时：Socket.IO 客户端
  • i18n：i18next，13 个命名空间

4.2 响应式架构

移动优先，组件分离：

// 路由组件动态导入
const ChatPageDesktop = dynamic(() => import('./ChatPageDesktop'))
const ChatPageMobile = dynamic(() => import('./ChatPageMobile'))

export default function ChatPage() {
  const isMobile = useIsMobile()
  return isMobile ? <ChatPageMobile /> : <ChatPageDesktop />
}

断点系统：

  • Mobile: ≤767px - 抽屉式侧边栏
  • Tablet: 768px-1023px - 桌面布局
  • Desktop: ≥1024px - 可调整侧边栏

4.3 状态管理层次

Global Contexts
├── ThemeProvider
├── I18nProvider
└── AuthGuard
    └── UserProvider
        └── SocketProvider
            ├── DeviceProvider
            ├── PetProvider
            └── TaskContextProvider
                └── ChatStreamProvider
                    └── TaskStateManager
                        └── TaskStateMachine #1..N

5. 数据流与通信

5.1 任务执行完整流程

5.2 Chat Shell 流式架构

独特设计：HTTP SSE + WebSocket Bridge

Chat Shell ──► RedisPublishingEmitter ──► Redis Pub/Sub ──► WebSocketBridge ──► 前端

优势：

  • HTTP SSE 对 LLM 流式最优（代理友好、简单）
  • WebSocket 对前端最优（双向、有状态）
  • Bridge 模式解决阻抗不匹配

6. 多智能体协作

6.1 协作模式

模式执行方式适用场景
Pipeline顺序执行，数据传递代码审查工作流
RouteLeader 路由到专家技术支持问答
CoordinateLeader 协调并行执行综合代码审查
Collaborate共享上下文讨论头脑风暴

6.2 Pipeline 阶段状态机

人参与环设计：

  • requireConfirmation 标志创建检查点
  • WebSocket 驱动用户交互
  • 支持"继续"和"重试"操作
  • 可编辑提示词后重试

7. 深度技术专题

7.1 Skill 系统与 MCP

核心创新：

  1. 按需加载：LLM 通过 load_skill() 工具调用显式请求技能
  2. Token 效率：节省 40-80% 提示词 Token
  3. 安全隔离：仅公共技能可执行动态代码
  4. 回合保留：加载的技能在 5 回合后过期
  5. 前端交互：PendingRequestRegistry 实现异步 UI 渲染

MCP 集成：

  • 支持 stdio、SSE、streamable-http 传输
  • 优雅降级机制
  • GitHub App 集成用于 MCP 服务器

7.2 TaskStateMachine 恢复机制

设计原则：单一数据源

⚠️ 永远使用 useUnifiedMessages() 返回的 messages
⚠️ selectedTaskDetail.subtasks 仅用于刷新/同步

关键机制：

  • Temp ID → Real ID 迁移：确保流式连续性
  • 内容优先级：Redis 缓存 > WebSocket > Backend DB
  • 待处理块队列：同步期间缓存 chunk 事件
  • 块级架构：混合内容（文本 + 工具调用）按 block_id 合并

8. 架构优势与挑战

8.1 核心优势

  1. 声明式 API：Kubernetes 风格，云原生友好
  2. 模块化设计：6 个独立模块，清晰职责边界
  3. 可扩展执行：支持多种执行引擎（Claude Code、Agno、Dify）
  4. 人参与环：Pipeline 确认机制，适合生产环境
  5. Token 效率：Skill 动态加载，MCP 按需调用
  6. 水平扩展：Redis Adapter 支持多 Worker

8.2 技术挑战

挑战现状潜在改进
JSON 列查询无 DB 级索引添加生成列索引
Skill 二进制存储影响备份对象存储 + 引用
状态枚举同步跨模块可能不一致统一状态定义
外键约束缺失，孤儿引用风险选择性添加

9. 关键文件索引

9.1 后端核心

backend/
├── app/models/kind.py              # CRD 基础模型
├── app/models/task.py              # Task/Workspace 模型
├── app/api/ws/chat_namespace.py    # WebSocket 聊天命名空间
├── app/services/adapters/          # 适配器模式
│   ├── skills.py                   # Skill 系统
│   ├── pipeline_stage.py           # Pipeline 阶段管理
│   └── chat_shell.py               # Chat Shell 集成

9.2 执行层核心

executor_manager/
├── scheduler/task_scheduler.py     # 任务调度器
├── executors/docker_executor.py    # Docker 执行器
└── executors/task_queue_service.py # Redis 任务队列

executor/
├── agents/claude_code/             # Claude Code Agent
├── agents/agno/                    # Agno Agent
└── main.py                         # FastAPI 服务器

9.3 前端核心

frontend/src/
├── features/tasks/state/
│   ├── TaskStateMachine.ts         # 任务状态机
│   └── TaskStateManager.ts         # 状态管理器
├── features/tasks/hooks/
│   └── useUnifiedMessages.ts       # 单一数据源
└── app/(tasks)/                    # 任务路由组

9.4 Chat Shell

chat_shell/
├── routers/response.py             # 流式响应路由
├── workflows/                      # LangGraph 工作流
└── main.py                         # FastAPI 入口

10. 结论

Wegent 是一个架构精良的 AI-native 操作系统，其设计体现了以下核心思想：

  1. 云原生优先：Kubernetes 风格 CRD，声明式 API
  2. 人智协作：Pipeline 确认机制，人参与环工作流
  3. Token 效率：Skill 动态加载，按需注入
  4. 扩展性：多执行引擎，可插拔调度器
  5. 生产就绪：Docker 隔离，水平扩展，状态恢复

系统的分层清晰、职责明确，是构建企业级 AI Agent 平台的优秀参考架构。

报告生成时间：2026-02-01分析文档库：index.md