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/            # 工具函数
```

---

> 相关文档：[项目结构概览](./project-structure.md) | [开发指南](./development-guide.md) | [API 参考](./api-reference.md) | [插件开发指南](./plugin-development-guide.md)