Wegent 文档库索引

AI-native 智能体团队操作系统 - 深度架构分析

📋 文档库概览

属性值
项目名称Wegent
项目描述开源 AI-native 操作系统，用于定义、组织和运行智能体团队
技术栈Next.js 15 + FastAPI + Docker + MySQL + Redis
分析日期2026-02-01
文档版本1.0

📊 分析统计

类别数量说明
一级分析任务6并行执行，覆盖核心架构维度
深挖任务4基于一级分析发现的高价值点
最终整合报告1全景架构报告
总文档数11含分析日志和索引

📁 文档结构

~/dev/documents/weagent/
├── index.md                              # 📍 本文件 - 文档库入口
├── final/
│   └── system-architecture-overview.md   # 🏗️ 全景架构报告
└── tasks/
    ├── analysis_log.md                   # 📋 分析执行日志
    │
    ├── Level 1 分析产物
    ├── crd-domain-model.md               # CRD 领域模型
    ├── backend-api-architecture.md       # 后端 API 架构
    ├── execution-layer.md                # 执行层架构
    ├── frontend-architecture.md          # 前端架构
    ├── dataflow-communication.md         # 数据流与通信
    └── multi-agent-collaboration.md      # 多智能体协作
    │
    └── 深挖产物
        ├── dig-skill-system.md           # Skill 系统与 MCP
        ├── dig-pipeline-state-machine.md # Pipeline 阶段状态机
        ├── dig-chat-shell-streaming.md   # Chat Shell 流式架构
        └── dig-task-state-machine.md     # TaskStateMachine 恢复机制

📖 阅读指南

快速入门（30 分钟）

  1. 全景架构报告 - 系统全貌
  2. 核心概念 - CRD 领域模型
  3. 数据流 - 通信架构概览

深度研究（2-4 小时）

按模块选择阅读：

角色推荐阅读
后端开发backend-api-architecture.md → dig-skill-system.md → execution-layer.md
前端开发frontend-architecture.md → dig-task-state-machine.md
DevOpsexecution-layer.md → dataflow-communication.md → dig-chat-shell-streaming.md
架构师全部文档，重点 dig-*.md

🔍 核心发现

架构亮点

  1. 双表存储设计：kinds + tasks 表分离高频写入操作
  2. Skill 动态加载：按需注入，节省 40-80% Token
  3. HTTP+Bridge 流式：Chat Shell SSE 与 WebSocket 桥接
  4. Pipeline 人参与环：确认检查点机制
  5. Temp→Real ID 迁移：前端状态机无缝过渡

设计模式

  • CRD 声明式 API：Kubernetes 风格资源管理
  • 适配器模式：传统 REST 与 CRD API 并存
  • 状态机模式：TaskStateMachine、Pipeline Stage
  • 桥接模式：Chat Shell 流式桥接
  • 策略模式：多种执行引擎、协作模式

🗂️ 文档详情

一级分析（Level 1）

文档页数估算核心内容
crd-domain-model.md~50CRD 层次、双表存储、状态机、引用模式
backend-api-architecture.md~60FastAPI 路由、WebSocket、双 API 策略、认证
execution-layer.md~70Executor Manager、Docker 编排、Agent 类型
frontend-architecture.md~80Next.js App Router、响应式、状态管理
dataflow-communication.md~60Socket.IO、房间路由、Redis Adapter
multi-agent-collaboration.md~504 种协作模式、Agno/Claude 实现

深度分析（Deep Dive）

文档页数估算核心内容
dig-skill-system.md~40Skill 加载、MCP 集成、PendingRequestRegistry
dig-pipeline-state-machine.md~35Pipeline 阶段、确认机制、WebSocket 交互
dig-chat-shell-streaming.md~35HTTP SSE、Bridge 模式、多 LLM 支持
dig-task-state-machine.md~35状态机、ID 迁移、恢复机制、单一数据源

🎯 使用场景

1. 新成员入职

阅读顺序：

  1. 本索引
  2. 全景架构报告
  3. 对应角色的 Level 1 文档
  4. 相关 Deep Dive 文档

2. 功能开发参考

功能参考文档
新增 CRD 类型crd-domain-model.md
新增 API 端点backend-api-architecture.md
新增 Shell 类型execution-layer.md + multi-agent-collaboration.md
新增协作模式multi-agent-collaboration.md + dig-pipeline-state-machine.md
前端响应式调整frontend-architecture.md
实时功能开发dataflow-communication.md + dig-task-state-machine.md

3. 故障排查

问题类型参考文档
任务调度失败execution-layer.md
消息不同步dig-task-state-machine.md
流式中断dig-chat-shell-streaming.md
Skill 加载失败dig-skill-system.md
WebSocket 连接dataflow-communication.md

🔗 外部资源

项目资源

  • 源码仓库：/home/sujie/dev/github/Wegent
  • 官方文档：docs/en/ 和 docs/zh/
  • API 文档：http://localhost:8000/docs (本地启动后)

参考文档

📌 方法论说明

本分析遵循价值驱动递归深挖方法论：

  1. 并行启动：6 个一级分析任务同时执行
  2. 实时审阅：每个任务完成后立即审阅结果
  3. 价值识别：识别复杂度高、设计精妙、与众不同的代码
  4. 触发深挖：立即启动深度分析，不限层级
  5. 及时写入：每个分析完成后立即生成文档
  6. 整合索引：最终生成统一入口和全景报告

分析维度

  • ✅ 架构设计（分层、模块、依赖）
  • ✅ 领域模型（聚合根、实体、状态机）
  • ✅ 核心业务（算法、流程、事务边界）
  • ✅ 数据流（流转、状态管理、持久化）
  • ✅ 运行机制（启动流程、生命周期、后台任务）
  • ✅ 扩展机制（Skill、MCP、Hook、配置）

📝 版本历史

版本日期变更
1.02026-02-01初始版本，完成 6 Level 1 + 4 Deep Dive 分析

🤝 贡献

本文档库由 AI 辅助生成，基于 Wegent 开源项目代码分析。

如需更新或补充：

  1. 修改对应模块的源码
  2. 重新运行分析任务
  3. 更新相关文档
  4. 同步更新本索引

Wegent 架构分析文档库
Understanding the architecture is key to mastering Wegent! 🚀