aiagent/docs/architecture.md

🏛️ 架构设计文档

Architecture Design Document

---

一、系统概述

天工智能体平台是一个企业级 AI 智能体（Agent）平台，提供智能对话、知识库管理、智能体编排等核心能力，采用前后端分离 + 异步任务队列 的架构设计。

---

二、技术选型

层级	技术	版本	选型理由
前端框架	Vue 3 (Composition API)	3.4+	轻量、响应式、TypeScript 友好
前端构建	Vite	5+	极速 HMR，开发体验优异
状态管理	Pinia	2+	Vue 3 官方推荐，TypeScript 支持完善
路由	Vue Router	4+	SPA 路由，支持导航守卫
HTTP 客户端	Axios	1+	请求/响应拦截，统一错误处理
后端框架	FastAPI	0.110+	高性能异步框架，自动生成 OpenAPI 文档
ORM	SQLAlchemy	2.0+	成熟的 Python ORM，异步支持
数据验证	Pydantic	2+	类型安全，与 FastAPI 深度集成
数据库迁移	Alembic	1.13+	版本化管理数据库变更
数据库	MySQL (腾讯云)	8.0+	稳定可靠的关系型数据库
缓存	Redis	7+	高性能缓存 + 消息队列
任务队列	Celery	5.3+	分布式异步任务处理
认证	JWT	—	无状态认证，支持 Token 刷新
容器化	Docker + Docker Compose	最新	简化部署，环境一致

---

三、架构分层

┌─────────────────────────────────────────────────────────────┐
│                   客户端层 (Client Layer)                     │
│  浏览器 (Chrome/Edge)  │  移动端  │  第三方 API 调用         │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                  接入层 (Gateway Layer)                      │
│  Nginx 反向代理 │  SSL 终止 │ 静态资源服务 │ 端口 8038/8037  │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                 前端应用层 (Frontend Layer)                   │
│  Vue 3 SPA  │  Pinia Store  │  Vue Router  │  Axios Client   │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Views   │  │Components│  │  Stores  │  │   Utils      │  │
│  │ 页面组件 │  │ 公共组件  │  │ 状态管理  │  │ 工具/请求封装│  │
│  └─────────┘  └──────────┘  └──────────┘  └──────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP/JSON
┌───────────────────────▼─────────────────────────────────────┐
│                 后端服务层 (Backend Layer)                    │
│  FastAPI  │  中间件  │  路由  │  依赖注入                    │
│  ┌──────────────┐  ┌──────────────────┐                    │
│  │  API 路由层   │  │  认证/授权中间件  │                    │
│  │  (api/v1/*)  │  │  (JWT、CORS)     │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Service 层   │  │  任务调度         │                    │
│  │  (业务逻辑)   │  │  (Celery 任务)   │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Models 层    │  │  Schemas 层       │                    │
│  │  (ORM 定义)   │  │  (数据验证)      │                    │
│  └──────────────┘  └──────────────────┘                    │
└──────┬────────────────────────────┬─────────────────────────┘
       │                            │
       ▼                            ▼
┌──────────────┐          ┌──────────────────┐
│  MySQL 8.0   │          │    Redis 7        │
│ (腾讯云)     │          │ 缓存 / 任务队列   │
│ 持久化存储   │          │ 会话 / 锁        │
└──────────────┘          └──────────────────┘
                                │
                                ▼
                      ┌──────────────────┐
                      │   Celery Worker   │
                      │ 异步任务处理       │
                      │ 文件处理 / 通知   │
                      └──────────────────┘

---

四、核心业务模块

1. 用户与权限模块

• 注册/登录：用户名 + 密码，JWT Token 发放
• Token 刷新：Access Token (30min) + Refresh Token (7d)
• 个人中心：信息查看与修改
• 角色权限：admin / workspace_admin / member，支持 14 个权限端点
• 多租户：Workspace 级数据隔离，飞书应用按 workspace 隔离

2. 智能体模块 (Agent)

• 智能体的创建、配置、发布、下架
• Agent 类型：specialist（专家）/ main（主路由）
• 工作流配置 workflow_config（nodes + edges）
• 执行预算 budget_config（max_steps / max_llm_invocations / max_tool_calls）
• 输入/输出 Schema 约束（JSON Schema）
• Agent 市场：发布/安装/评分(Fork)/收藏/升级
• Agent 编排：5 种模式（route / sequential / debate / pipeline / graph）
• Agent 蜂群：Swarm Leader 分解任务 → Teammate 并行执行 → 聚合结果

3. 知识库模块

• 文档上传与解析（PDF、TXT、Markdown、HTML、CSV、JSON）
• 文档分块 → 向量嵌入（支持 OpenAI / DeepSeek Embedding）
• 语义检索（余弦相似度 + 混合检索）
• RAG 增强生成：检索 → 增强 Prompt → 生成
• 知识图谱：KnowledgeEntity（节点）+ KnowledgeRelation（关系边）
• 知识进化：Celery Beat 定时提取 → LLM 提炼 → 入库
• 知识仪表盘：增长曲线、复用排行、类别分布

4. 对话模块

• 用户与智能体的实时对话（SSE 流式输出）
• 事件类型：plan / think / tool_call / tool_result / final / done
• 上下文管理与会话恢复（session_id）
• 对话分支（Branch）：分支创建 / 查看 / 恢复
• 记忆系统：短期记忆（向量 RAG）+ 长期记忆（PersistentUserMemory）+ 全局知识池

5. 工作流模块

• 可视化 DAG 工作流（开始 → LLM/工具/条件/循环 → 结束）
• 节点类型：start / llm / tool / condition / code / switch / parallel / subworkflow / orchestrator / evaluator
• 节点配置：提示词模板（支持 {{variable}} 变量）、工具列表、模型参数
• 节点级功能：自动重试（retry_config）、错误处理（error_handler）、人工审批（HITL）
• 版本管理（WorkflowVersion）：保存 / 列表 / 回滚
• 版本对比：节点变更可视化
• 节点搜索/筛选、自动布局（Dagre 算法）
• 工作流验证：死循环检测、孤立节点检测、类型兼容性检查
• Subworkflow：嵌套子工作流，含深度防护

6. 工具系统

• 内置工具：56 个开箱即用工具（文件 / 文本 / HTTP / 代码 / 搜索 / 计算 / 日期 / JSON / 知识图谱 等）
• 工具分类：file_ops / text_processing / web / code / data / knowledge / search / math
• 工具参数过滤：防止注入、类型校验
• 工具动态注册：HTTP 工具 / 代码工具 / 工作流工具，支持热更新
• 工具市场：发布 / 安装 / 版本管理

7. 监控与告警

• 系统监控：概览 / 执行统计 / 节点类型用量 / 最近动态
• Agent 监控：LLM 调用统计 / Agent 统计 / 工具用量 / 每日趋势
• 告警系统：规则 CRUD + 告警日志 + 通知（邮件/Webhook/站内）
• Prometheus 指标：/metrics 端点，业务指标 + 系统指标
• Grafana 仪表板：系统/业务双面板
• ELK 日志聚合：Filebeat → Logstash → Elasticsearch → Kibana

8. 商业化模块

• 模板市场：11 个行业模板（客服/研发/PR Review/面试调度/竞品监控/测试报告/入职引导/风险预警/学习助手/日报/日志分析）
• 场景契约 DSL：统一输入契约（目标/约束/产物/验收），模板复用
• 定时任务：Cron 表达式，支持手动触发
• Android App：原生 Kotlin + Compose，对话/历史/语音/TTS/推送
• 飞书 Bot：6 个 Bot，WebSocket 长连接，交互卡片，对话上下文连续性
• PWA 移动端：manifest + Service Worker + 离线缓存 + 浏览器推送

9. 集成与通知

• 第三方集成：飞书 / 微信 / Slack（Webhook）
• 推送通知：PushSubscription 模型 + push_service + 浏览器 Push API
• FCM 推送：Firebase Cloud Messaging for Android
• WebSocket 实时推送：执行状态实时更新
• 审批系统：approval_manager + 危险工具自动审批流程

---

五、Agent 运行时架构

ReAct 循环

用户输入 → [Think → Act → Observe] × N → Final Answer

每个迭代：
1. Think: LLM 分析当前状态，决定下一步
2. Act:  调用工具或执行操作
3. Observe: 获取工具结果，更新上下文

核心执行流程

AgentRuntime.execute()
├── 加载 Agent 配置（workflow_config, system_prompt, tools）
├── 初始化上下文（memory, conversation_history, session_state）
├── ReAct 循环（最多 max_iterations 轮）
│   ├── _think(): LLM 推理，决定调用哪个工具
│   ├── _act():  执行工具调用
│   │   ├── 参数过滤（防止注入）
│   │   ├── 审批检查（HITL — 危险工具需人工审批）
│   │   └── 执行工具（内置 / HTTP / 代码 / 工作流）
│   ├── _observe(): 记录结果，更新记忆
│   └── _should_continue(): 判断是否继续（任务完成？达到上限？）
├── 聚合结果 → Final Answer
└── 记录执行日志（AgentLLMLog + AgentExecutionLog + ExecutionLog）

记忆系统三层架构

┌──────────────────────────────────────────┐
│  第一层：短期记忆（对话上下文）             │
│  • 当前会话的历史消息                       │
│  • memory_max_history 条消息              │
│  • 滑动窗口自动截断                        │
├──────────────────────────────────────────┤
│  第二层：向量记忆（语义检索）               │
│  • AgentVectorMemory 表                   │
│  • Embedding → 向量相似度检索              │
│  • 跨会话语义相关性查找                    │
│  • 配置：memory_vector_top_k 条           │
├──────────────────────────────────────────┤
│  第三层：长期记忆（持久化）                 │
│  • PersistentUserMemory 表               │
│  • 关键信息跨会话保存                      │
│  • 用户画像、偏好、学习进度                 │
│  • memory_persist + memory_learning       │
└──────────────────────────────────────────┘

多 Agent 编排模式

模式	描述	API
route	主 Agent 分析输入 → 路由到最合适的子 Agent	/agent-chat/orchestrate
sequential	多个 Agent 按顺序执行，前者输出为后者输入	/agent-chat/orchestrate
debate	多个 Agent 同时回答，汇总比较	/agent-chat/orchestrate
pipeline	流水线模式，每个 Agent 处理一个阶段	/agent-chat/orchestrate
graph	DAG 图模式，任意拓扑结构，并行分支	/agent-chat/orchestrate/graph
swarm	Leader 分解 → Teammate 并行 → 聚合	/swarm/run

---

六、实时通信架构

SSE（Server-Sent Events）

Client                          Server
  │                                │
  │  POST /agent-chat/{id}/stream  │
  │  Accept: text/event-stream     │
  │───────────────────────────────>│
  │                                │
  │  event: plan                   │
  │  data: {"title":"...",         │
  │         "steps":[...]}         │
  │<───────────────────────────────│
  │                                │
  │  event: think                  │
  │  data: {"content":"...",       │
  │         "iteration":0}         │
  │<───────────────────────────────│
  │                                │
  │  event: tool_call              │
  │  data: {"tool_name":"...",     │
  │         "tool_input":"..."}    │
  │<───────────────────────────────│
  │                                │
  │  event: tool_result            │
  │  data: {"tool_name":"...",     │
  │         "tool_result":"..."}   │
  │<───────────────────────────────│
  │                                │
  │  event: final                  │
  │  data: {"content":"...",       │
  │         "iterations_used":3}   │
  │<───────────────────────────────│
  │                                │
  │  event: done                   │
  │  data: {"session_id":"..."}    │
  │<───────────────────────────────│

WebSocket

Client                               Server
  │                                     │
  │  WS /ws/executions/{execution_id}   │
  │────────────────────────────────────>│
  │                                     │
  │  {"type":"progress","pct":50}       │
  │<────────────────────────────────────│
  │                                     │
  │  {"type":"node_start",              │
  │   "node_id":"llm-1"}               │
  │<────────────────────────────────────│
  │                                     │
  │  {"type":"node_complete",           │
  │   "node_id":"llm-1",               │
  │   "output":"..."}                   │
  │<────────────────────────────────────│
  │                                     │
  │  {"type":"execution_complete",      │
  │   "status":"success"}                │
  │<────────────────────────────────────│

---

七、数据库架构

核心表关系

users (用户)
├── agents (智能体)
│   ├── agent_ratings (评分)
│   ├── agent_favorites (收藏)
│   ├── agent_schedules (定时任务)
│   ├── agent_llm_logs (LLM 调用日志)
│   ├── agent_vector_memories (向量记忆)
│   └── agent_learning_patterns (学习模式)
├── workflows (工作流)
│   └── workflow_versions (版本历史)
├── executions (执行记录)
│   └── execution_logs (执行日志)
├── knowledge_bases (知识库)
│   ├── documents (文档)
│   └── document_chunks (文档分块)
├── notifications (通知)
├── feedback_records (用户反馈)
├── conversation_branches (对话分支)
├── goals (目标)
│   └── tasks (任务)
├── orchestration_templates (编排模板)
├── node_templates (节点模板)
├── plugins (插件)
├── alert_rules (告警规则)
│   └── alert_logs (告警日志)
├── persistent_user_memories (长期记忆)
├── knowledge_entities (知识图谱节点)
├── knowledge_relations (知识图谱关系)
├── push_subscriptions (推送订阅)
├── fcm_tokens (FCM Token)
├── user_feishu_open_ids (飞书绑定)
├── scene_contracts (场景契约 DSL)
└── workspaces (工作区)
    └── workspace_memberships (成员关系)

数据库索引策略

• 所有外键列均有索引
• 常用查询列（status / category / is_public / created_at）索引
• 时间范围查询列（timestamp / triggered_at）索引
• 复合索引用于高频组合查询（agent_id + created_at）

---

八、安全架构

安全措施	实现方式	位置
JWT 认证	HS256 签名，30min Access + 7d Refresh	auth.py middleware
密码安全	bcrypt 哈希（12 rounds）	auth.py
CORS 保护	FastAPI CORSMiddleware，白名单域名	main.py
输入验证	Pydantic v2 严格验证所有 endpoint 输入	全部 schemas
SQL 注入防护	SQLAlchemy 2.0+ 参数化查询	全部 models
XSS 防护	CSP 头 + 输出转义（前端 Vue 3）	前端 index.html
CSRF 防护	SameSite Cookie + Token Header	前端 axios 配置
Rate Limiting	Redis 滑动窗口（登录 5/min，Webhook 60/min）	rate_limiter.py
安全头	HSTS / X-Content-Type-Options / X-Frame-Options	security_headers.py
文件上传安全	类型检查 + 大小限制 + 病毒扫描	uploads.py
HTTPS	Nginx 侧 SSL 终止	nginx.conf
密钥管理	.env 文件 + .env.example 模板，不提交 Git	root

---

九、可扩展性设计

• 水平扩展：FastAPI 无状态 → 多实例 + Nginx 负载均衡
• 数据库读写分离：MySQL 主从复制（生产环境可配置）
• 缓存策略：Redis 缓存热点数据（用户信息、Agent 配置）
• 异步任务：Celery Worker 独立扩展，处理 LLM 调用、文件处理、通知推送
• 日志聚合：ELK Stack（Filebeat → Elasticsearch → Kibana）
• 监控告警：Prometheus + Grafana，业务/系统双面板
• CI/CD：GitHub Actions（ci.yml + deploy.yml + security.yml）
• 容器化部署：Docker Compose（dev/staging/prod 三套环境）
• 多环境管理：ENVIRONMENT 变量驱动的配置切换

---

十、前端架构

src/
├── api/              # API 调用封装（axios 实例 + 拦截器）
├── components/       # 公共组件库
│   ├── chat/         # 聊天相关（StreamingText, MarkdownRenderer）
│   ├── workflow/     # 工作流编辑器（DAG 画布、节点面板）
│   ├── charts/       # 图表组件（ECharts）
│   └── common/       # 通用组件（按钮、表单、弹窗）
├── composables/      # 组合式 API（useSpeechRecognition, useTTS, usePWA）
├── layouts/          # 布局组件（MainLayout, AdminLayout）
├── router/           # 路由配置（32 个路由，全部懒加载）
├── stores/           # Pinia 状态管理
├── views/            # 页面组件（28 个页面）
│   ├── MainConsole   # 主控台仪表盘
│   ├── AgentDesigner # Agent 设计器
│   ├── WorkflowEditor# 工作流编辑器
│   ├── TemplateMarket# 模板市场
│   ├── AgentMarket   # Agent 市场
│   ├── KnowledgeBase # 知识库管理
│   ├── Monitoring    # 系统监控
│   └── ...           # 更多
└── utils/            # 工具函数

---

相关文档：项目结构概览 | 开发指南 | API 参考 | 插件开发指南