feat: add AI学习助手 agent (KG+RAG ideal) and renshenguo feishu bot
- Add AI学习助手 agent creation script with all 39 tools, 3-layer KG+RAG memory - Add renshenguo (人参果) feishu bot integration (app_service + ws_handler) - Register renshenguo WS client in main.py startup - Add RENSHENGUO_APP_ID / RENSHENGUO_APP_SECRET / RENSHENGUO_AGENT_ID config - Reorganize docs from root into docs/ subdirectories - Move startup scripts to scripts/startup/ - Various backend optimizations and tool improvements Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
468
docs/architecture/(红头)项目初始文档.md
Normal file
468
docs/architecture/(红头)项目初始文档.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# AIAgent 项目初始文档
|
||||
|
||||
> 大模型重启后，读此文档即可快速了解项目全貌。最后更新: 2026-05-02。
|
||||
|
||||
---
|
||||
|
||||
## 1. 一句话概括
|
||||
|
||||
**低代码智能体搭建与工作流编排平台** — 可视化拖拽配置 30+ 种节点类型，集成多种 AI 模型，支持复杂业务流程自动化执行。
|
||||
|
||||
---
|
||||
|
||||
## 2. 速查卡片
|
||||
|
||||
| 项目 | 值 |
|
||||
|---|---|
|
||||
| 代码路径 | `D:\aaa\aiagent` |
|
||||
| Git 分支 | `main` |
|
||||
| 数据库 | MySQL 腾讯云 `gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936` / `agent_db` |
|
||||
| Redis | 本地 `localhost:6379` |
|
||||
| 前端端口 | `3001` (Vite dev) |
|
||||
| 后端端口 | `8037` (uvicorn) |
|
||||
| 外部地址 | `http://101.43.95.130:8038` |
|
||||
| 健康检查 | `GET http://127.0.0.1:8037/health` |
|
||||
| API 文档 | `http://127.0.0.1:8037/docs` |
|
||||
| 启动脚本 | `start_aiagent.ps1` (弹窗) / `start_aiagent_background.ps1` (静默) |
|
||||
| 停止脚本 | `stop_aiagent.ps1` |
|
||||
| 重启后端 | `restart_backend_celery.ps1` |
|
||||
| 开机自启 | `install_autostart.ps1` (需管理员) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构总览
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 用户浏览器 │
|
||||
│ http://localhost:3001 │
|
||||
└─────────────┬────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────┴──────────┐
|
||||
│ Frontend (Vite) │ Vue 3 + Pinia + Element Plus + Vue Flow
|
||||
│ :3001 │
|
||||
└─────────┬──────────┘
|
||||
│ /api/v1/* (Vite proxy → :8037)
|
||||
│ /api/v1/ws (WebSocket)
|
||||
┌─────────┴──────────┐
|
||||
│ Backend (FastAPI) │ Python + SQLAlchemy + Celery
|
||||
│ :8037 │
|
||||
│ ├─ 26 API 路由 │
|
||||
│ ├─ 33 服务模块 │
|
||||
│ └─ 启动时: 注册内置工具 + 飞书 WS 长连接
|
||||
└──┬───────┬─────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────┐ ┌──────┐ ┌──────────────┐
|
||||
│MySQL │ │Redis │────▶│Celery Worker │ 异步执行工作流/Agent
|
||||
│(云) │ │:6379 │ │(threads×8) │
|
||||
└──────┘ └──────┘ └──────┬───────┘
|
||||
│ Redis Pub/Sub
|
||||
▼
|
||||
WebSocket → 前端实时状态推送
|
||||
```
|
||||
|
||||
**关键设计**:
|
||||
- 用户请求 → FastAPI 创建执行记录 → Celery 任务入 Redis 队列 → Worker 消费执行 → WebSocket 推送进度
|
||||
- 工作流在 Celery Worker 中异步运行，支持暂停/恢复/取消
|
||||
- API 和 Worker 共用同一个 venv 和工具注册逻辑
|
||||
|
||||
---
|
||||
|
||||
## 4. 启动 / 停止
|
||||
|
||||
### 4.1 标准启动（弹窗模式）
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1
|
||||
```
|
||||
|
||||
会打开 4 个 PowerShell 窗口：Redis、API、Celery、前端。
|
||||
|
||||
### 4.2 停止
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\stop_aiagent.ps1
|
||||
```
|
||||
|
||||
### 4.3 仅重启后端+Celery（最常用，改 .env / 依赖 / 工具后）
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\restart_backend_celery.ps1
|
||||
```
|
||||
|
||||
### 4.4 手动应急启动（脚本不可用时）
|
||||
|
||||
4 个终端分别执行:
|
||||
|
||||
```powershell
|
||||
# 1) Redis
|
||||
cd D:\aaa\aiagent\backend\redis
|
||||
.\redis-server.exe --port 6379
|
||||
|
||||
# 2) API
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8037
|
||||
|
||||
# 3) Celery
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8
|
||||
|
||||
# 4) 前端
|
||||
cd D:\aaa\aiagent\frontend
|
||||
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
|
||||
pnpm dev --port 3001
|
||||
```
|
||||
|
||||
### 4.5 验证
|
||||
|
||||
```powershell
|
||||
netstat -ano | findstr :6379
|
||||
netstat -ano | findstr :8037
|
||||
netstat -ano | findstr :3001
|
||||
curl.exe http://127.0.0.1:8037/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 项目目录结构（关键路径）
|
||||
|
||||
```
|
||||
D:\aaa\aiagent\
|
||||
├── backend/
|
||||
│ ├── .env # ★ 环境变量 (DB/Redis/API Keys/CORS)
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ ├── venv/ # Python 虚拟环境
|
||||
│ ├── redis/ # Windows Redis 可执行文件
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── alembic.ini
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # ★ FastAPI 入口 (startup 事件 + 路由注册)
|
||||
│ │ ├── core/
|
||||
│ │ │ ├── config.py # Pydantic Settings (环境变量读取)
|
||||
│ │ │ ├── database.py # SQLAlchemy 引擎 + 会话
|
||||
│ │ │ ├── celery_app.py # Celery 应用实例
|
||||
│ │ │ ├── security.py # JWT 工具
|
||||
│ │ │ ├── redis_client.py # Redis 客户端
|
||||
│ │ │ ├── tools_bootstrap.py # 内置工具注册逻辑
|
||||
│ │ │ ├── exceptions.py # 自定义异常类
|
||||
│ │ │ └── error_handler.py # 全局异常处理器
|
||||
│ │ ├── models/ # SQLAlchemy 数据模型 (14个)
|
||||
│ │ ├── api/ # REST 路由 (26个文件)
|
||||
│ │ ├── services/ # 业务逻辑 (33个文件)
|
||||
│ │ │ ├── workflow_engine.py # ★ 工作流执行引擎 (~5700行)
|
||||
│ │ │ ├── workflow_validator.py # 工作流校验
|
||||
│ │ │ ├── llm_service.py # LLM 调用 (OpenAI/DeepSeek 兼容)
|
||||
│ │ │ ├── tool_registry.py # 工具注册表
|
||||
│ │ │ ├── builtin_tools.py # 内置工具实现
|
||||
│ │ │ └── ... # 其他服务
|
||||
│ │ ├── tasks/ # Celery 异步任务
|
||||
│ │ ├── websocket/ # WebSocket 管理
|
||||
│ │ └── utils/ # 工具函数
|
||||
│ ├── scripts/ # 运维脚本
|
||||
│ │ └── check_ocr_env.py
|
||||
│ └── tests/
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── package.json
|
||||
│ ├── vite.config.ts # Vite 配置 (proxy → :8037)
|
||||
│ ├── src/
|
||||
│ │ ├── main.ts # Vue 入口
|
||||
│ │ ├── api/index.ts # Axios 封装 + 拦截器
|
||||
│ │ ├── router/index.ts # 路由 (20条)
|
||||
│ │ ├── stores/ # Pinia 状态管理 (5个)
|
||||
│ │ ├── views/ # 页面视图 (18个)
|
||||
│ │ ├── components/ # 组件
|
||||
│ │ │ └── WorkflowEditor/ # 工作流编辑器核心
|
||||
│ │ └── types/index.ts # TS 类型定义
|
||||
│ └── node_modules/
|
||||
│
|
||||
├── scripts/ # 种子数据脚本
|
||||
│ ├── seed_tools.py
|
||||
│ ├── seed_agents.py
|
||||
│ ├── seed_coding_agent.py
|
||||
│ ├── seed_scenario_agents.py
|
||||
│ └── seed_extra_agents.py
|
||||
│
|
||||
├── start_aiagent.ps1 # 一键启动 (弹窗)
|
||||
├── stop_aiagent.ps1 # 一键停止
|
||||
├── restart_backend_celery.ps1 # 仅重启后端+Celery
|
||||
├── start_aiagent_background.ps1 # 后台静默启动 (开机自启用)
|
||||
├── install_autostart.ps1 # 安装/卸载开机自启任务
|
||||
├── agent_workspaces/ # 文件工具沙箱目录
|
||||
├── uploads/ # 上传文件存储
|
||||
├── tessdata/ # Tesseract OCR 语言包
|
||||
├── (红头)Windows服务器启动与重启唯一指南.md # ★ 运维权威文档
|
||||
└── aiagent项目架构文档.md # 架构详解
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 技术栈
|
||||
|
||||
| 层 | 技术 |
|
||||
|---|---|
|
||||
| 前端框架 | Vue 3 (Composition API) + TypeScript |
|
||||
| 构建 | Vite 5 |
|
||||
| UI 库 | Element Plus |
|
||||
| 流程图 | Vue Flow (基于 React Flow) |
|
||||
| 状态管理 | Pinia |
|
||||
| HTTP | Axios |
|
||||
| 后端框架 | FastAPI (Python) |
|
||||
| ORM | SQLAlchemy 2.0 + PyMySQL |
|
||||
| 异步任务 | Celery 5.3 (Redis Broker) |
|
||||
| 迁移 | Alembic |
|
||||
| AI SDK | OpenAI Python SDK (兼容 DeepSeek/SiliconFlow 等) |
|
||||
| 加密 | cryptography (Fernet) |
|
||||
| 实时推送 | WebSocket + Redis Pub/Sub |
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据库模型 (14 个表)
|
||||
|
||||
| 表 | 模型 | 用途 |
|
||||
|---|---|---|
|
||||
| `users` | User | 用户 (含 role 字段) |
|
||||
| `workflows` | Workflow | 工作流定义 (nodes+edges JSON) |
|
||||
| `workflow_versions` | WorkflowVersion | 版本历史 + 回滚 |
|
||||
| `workflow_templates` | WorkflowTemplate | 预制模板 |
|
||||
| `agents` | Agent | 智能体 (workflow_config JSON) |
|
||||
| `executions` | Execution | 执行记录 (pending/running/completed/failed/paused) |
|
||||
| `execution_logs` | ExecutionLog | 节点级执行日志 |
|
||||
| `model_configs` | ModelConfig | AI 模型配置 (API Key Fernet 加密) |
|
||||
| `tools` | Tool | 工具定义 |
|
||||
| `data_sources` | DataSource | 外部数据源连接 |
|
||||
| `permissions` | Permission | RBAC 权限 |
|
||||
| `alert_rules` | AlertRule | 监控告警规则 |
|
||||
| `node_templates` | NodeTemplate | 节点配置模板 |
|
||||
| `persistent_user_memories` | PersistentUserMemory | 跨会话持久化记忆 |
|
||||
|
||||
---
|
||||
|
||||
## 8. API 路由清单 (26 个模块, `/api/v1/*`)
|
||||
|
||||
| 路由模块 | 文件 | 功能 |
|
||||
|---|---|---|
|
||||
| auth | `auth.py` | 注册/登录/JWT |
|
||||
| workflows | `workflows.py` | 工作流 CRUD + 执行 + 版本 |
|
||||
| executions | `executions.py` | 执行记录 + 暂停/恢复/取消 |
|
||||
| execution_logs | `execution_logs.py` | 执行日志查询 |
|
||||
| agents | `agents.py` | Agent CRUD + 场景模板 |
|
||||
| agent_chat | `agent_chat.py` | Agent 对话 API (SSE 流式) |
|
||||
| agent_monitoring | `agent_monitoring.py` | Agent 监控统计 |
|
||||
| agent_schedules | `agent_schedules.py` | Agent 定时任务 (cron) |
|
||||
| tools | `tools.py` | 工具市场 CRUD |
|
||||
| model_configs | `model_configs.py` | 模型配置管理 |
|
||||
| data_sources | `data_sources.py` | 数据源管理 |
|
||||
| uploads | `uploads.py` | 文件上传 |
|
||||
| websocket | `websocket.py` | WebSocket 实时推送 |
|
||||
| webhooks | `webhooks.py` | 外部 Webhook 接收 |
|
||||
| template_market | `template_market.py` | 模板市场 |
|
||||
| platform_templates | `platform_templates.py` | 平台预置模板 |
|
||||
| node_templates | `node_templates.py` | 节点模板 |
|
||||
| node_test | `node_test.py` | 单节点测试 |
|
||||
| batch_operations | `batch_operations.py` | 批量操作 |
|
||||
| collaboration | `collaboration.py` | 多用户协作 |
|
||||
| permissions | `permissions.py` | RBAC 权限管理 |
|
||||
| monitoring | `monitoring.py` | 系统监控 |
|
||||
| alert_rules | `alert_rules.py` | 告警规则 |
|
||||
| notifications | `notifications.py` | 通知推送 |
|
||||
| knowledge_base | `knowledge_base.py` | 知识库 (RAG) |
|
||||
| feishu_bind | `feishu_bind.py` | 飞书用户绑定 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 前端路由清单 (20 条)
|
||||
|
||||
| 路径 | 视图 | 说明 |
|
||||
|---|---|---|
|
||||
| `/login` | Login.vue | 登录 |
|
||||
| `/` | Home.vue | 首页仪表盘 |
|
||||
| `/console` | MainConsole.vue | 主控制台 |
|
||||
| `/workflow/:id?` | WorkflowDesigner.vue | 工作流编辑器 |
|
||||
| `/agents` | Agents.vue | Agent 管理 |
|
||||
| `/agents/:id/design` | WorkflowDesigner.vue | Agent 工作流设计 |
|
||||
| `/agents/:id/config` | AgentConfig.vue | Agent 配置 |
|
||||
| `/executions` | Executions.vue | 执行记录 |
|
||||
| `/executions/:id` | ExecutionDetail.vue | 执行详情 |
|
||||
| `/execution-board` | ExecutionBoard.vue | 执行看板 |
|
||||
| `/data-sources` | DataSources.vue | 数据源管理 |
|
||||
| `/model-configs` | ModelConfigs.vue | 模型配置 |
|
||||
| `/template-market` | TemplateMarket.vue | 模板市场 |
|
||||
| `/permissions` | PermissionManagement.vue | 权限管理 (admin) |
|
||||
| `/monitoring` | Monitoring.vue | 监控面板 |
|
||||
| `/agent-monitoring` | AgentDashboard.vue | Agent 仪表盘 |
|
||||
| `/alert-rules` | AlertRules.vue | 告警规则 |
|
||||
| `/node-templates` | NodeTemplates.vue | 节点模板 |
|
||||
| `/tools` | Tools.vue | 工具市场 |
|
||||
| `/agent-chat` | AgentChat.vue | Agent 对话 |
|
||||
| `/agent-chat/:id` | AgentChat.vue | 指定 Agent 对话 |
|
||||
|
||||
**路由守卫**: 除 `/login` 外均需 JWT；`/permissions` 额外要求 admin 角色。
|
||||
|
||||
---
|
||||
|
||||
## 10. 节点类型 (30+ 种)
|
||||
|
||||
### 控制流
|
||||
`start` `end/output` `condition` `switch` `merge` `loop/foreach` `wait`
|
||||
|
||||
### AI 能力
|
||||
`llm` `template` `code`
|
||||
|
||||
### 数据
|
||||
`data/transform` `json` `text` `csv` `excel` `cache` `vector_db`
|
||||
|
||||
### 存储
|
||||
`database/db` `file/file_operation` `object_storage` `pdf` `image`
|
||||
|
||||
### 网络
|
||||
`http/request` `webhook` `oauth`
|
||||
|
||||
### 消息
|
||||
`email/mail` `message_queue/mq/rabbitmq/kafka` `sms`
|
||||
|
||||
### 办公协同
|
||||
`slack` `dingtalk/dingding` `wechat_work/wecom`
|
||||
|
||||
### 高级
|
||||
`subworkflow/invoke_agent` `batch` `validator` `approval` `error_handler` `log` `schedule/delay/timer`
|
||||
|
||||
核心执行逻辑在 `backend/app/services/workflow_engine.py` 的 `execute_node` 方法中。
|
||||
|
||||
---
|
||||
|
||||
## 11. 核心服务模块 (33 个)
|
||||
|
||||
| 服务 | 文件 | 职责 |
|
||||
|---|---|---|
|
||||
| 工作流引擎 | `workflow_engine.py` | 拓扑排序 + 节点执行 + 预算熔断 + 断点恢复 |
|
||||
| 工作流校验 | `workflow_validator.py` | 结构/连接/配置合法性检查 |
|
||||
| 工作流模板 | `workflow_templates.py` | 预置模板生成 |
|
||||
| LLM 服务 | `llm_service.py` | OpenAI 兼容 SDK 调用 + 流式 + 工具调用 |
|
||||
| 工具注册表 | `tool_registry.py` | 内置/HTTP/工作流工具管理 |
|
||||
| 内置工具 | `builtin_tools.py` | file_read/write/system_info/datetime 等 |
|
||||
| 条件解析 | `condition_parser.py` | 条件表达式求值 + 分支裁剪 |
|
||||
| 数据转换 | `data_transformer.py` | 数据格式转换 |
|
||||
| 执行日志 | `execution_logger.py` | 节点级日志记录 |
|
||||
| 执行预算 | `execution_budget.py` | 步数/LLM/工具三重熔断 |
|
||||
| 加密服务 | `encryption_service.py` | Fernet 加密/解密 |
|
||||
| 持久记忆 | `persistent_memory_service.py` | 跨会话用户记忆 |
|
||||
| 权限服务 | `permission_service.py` | RBAC 检查 |
|
||||
| 监控服务 | `monitoring_service.py` | 系统指标采集 |
|
||||
| 告警服务 | `alert_service.py` | 告警规则评估 + 通知 |
|
||||
| 数据源连接器 | `data_source_connector.py` | 外部数据源连接 |
|
||||
| 场景模板 | `scene_templates.py` | 场景化模板 |
|
||||
| 场景 DSL | `scenario_dsl.py` | DSL 解析/校验 |
|
||||
| Agent 学习 | `agent_learning_service.py` | 从历史执行中优化工具选择 |
|
||||
| Agent 监控 | `agent_monitoring_service.py` | Agent 运行指标 |
|
||||
| Agent 调度 | `agent_schedule_service.py` | 定时任务 cron 调度 |
|
||||
| 知识库 | `knowledge_service.py` | 向量检索 RAG |
|
||||
| 嵌入服务 | `embedding_service.py` | Embedding 向量化 |
|
||||
| 文档解析 | `document_parser.py` | PDF/Word/Excel 解析 |
|
||||
| 文本分块 | `text_chunker.py` | 长文本分块 |
|
||||
| 飞书通知 | `feishu_notifier.py` | 飞书消息推送 |
|
||||
| 飞书 WebSocket | `feishu_ws_handler.py` | 飞书机器人长连接 |
|
||||
| 飞书应用 | `feishu_app_service.py` | 飞书应用逻辑 |
|
||||
| 橙子 WebSocket | `orange_ws_handler.py` | 第二个飞书机器人 |
|
||||
| 橙子应用 | `orange_app_service.py` | 第二个飞书应用 |
|
||||
| 通知服务 | `notification_service.py` | 统一通知推送 |
|
||||
| Agent 工作区日志 | `agent_workspace_chat_log.py` | 对话日志落盘 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 关键配置项 (`.env`)
|
||||
|
||||
```
|
||||
DATABASE_URL=mysql+pymysql://root:***@gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936/agent_db
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
CORS_ORIGINS=http://localhost:3001,... (多地址逗号分隔)
|
||||
DEEPSEEK_API_KEY=sk-fdf7cc1c73504e628ec0119b7e11b8cc
|
||||
SILICONFLOW_API_KEY=sk-xpptixobqxshkmikjvjeoltekytqmmresfndhoivezomuobn
|
||||
FEISHU_APP_ID=cli_a97f3e2ecaf81cba # 飞书机器人
|
||||
ORANGE_APP_ID=cli_a97f1271ec345cc6 # 橙子飞书机器人
|
||||
EXTERNAL_URL=http://101.43.95.130:8038
|
||||
TESSERACT_CMD=C:/Program Files/Tesseract-OCR/tesseract.exe
|
||||
```
|
||||
|
||||
**重要**: 修改 `.env` 后至少需要 `restart_backend_celery.ps1`。
|
||||
|
||||
---
|
||||
|
||||
## 13. 安全机制
|
||||
|
||||
- **JWT 认证** — 所有 API Bearer Token（`/login` 除外），`app.core.security`
|
||||
- **模型密钥加密** — API Key Fernet 加密存储，仅创建者可调用
|
||||
- **RBAC** — 角色级权限 (`admin` / `user`)
|
||||
- **执行预算** — 步数上限(2000)、LLM 调用上限(200)、工具调用上限(500)
|
||||
- **代码沙箱** — `code` 节点禁用 `open`/`eval`/`__import__`
|
||||
- **文件沙箱** — 操作限制在 `LOCAL_FILE_TOOLS_ROOT` 目录内
|
||||
|
||||
---
|
||||
|
||||
## 14. 外部集成
|
||||
|
||||
| 集成 | 说明 |
|
||||
|---|---|
|
||||
| 飞书 | 2 个机器人 — 应用通知 + 对话交互 (WebSocket 长连接) |
|
||||
| DeepSeek | AI 模型 (DSML 协议支持, reasoning_content) |
|
||||
| SiliconFlow | Embedding 模型 (bce-embedding-base_v1) |
|
||||
| 腾讯云 MySQL | 生产数据库 |
|
||||
| Tesseract OCR | 图片文字识别 (Windows 安装路径) |
|
||||
|
||||
---
|
||||
|
||||
## 15. Git 历史摘要 (最近 20 次提交)
|
||||
|
||||
```
|
||||
7ee80c7 feat: 集成飞书通知和机器人对话系统
|
||||
0bbf68d feat: 实现 Agent 定时任务系统 — cron 表达式周期执行
|
||||
e3802ef feat: 实现 Agent 自主学习 — 从历史执行中优化工具选择
|
||||
c28cf40 feat: 添加更多场景专用 Agent 种子脚本
|
||||
5a52dac feat: 添加 5 个场景专用 Agent 种子脚本
|
||||
5423aca feat: 新增 Pipeline 流水线编排模式 (Planner→Executor→Reviewer)
|
||||
7aba0f9 fix: 修复 Agent 流式对话无响应和工具 schema 兼容性问题
|
||||
342f3fc chore: 添加工具市场种子脚本
|
||||
4c1b5b2 fix: 工具市场 categories 路由被 /{tool_id} 拦截
|
||||
30dad00 fix: 工具市场页面缺少 MainLayout 导入
|
||||
9400cf9 refactor: 优化工具市场 UI — 卡片视图、统计概览、分步表单
|
||||
cd83090 feat: 添加工具市场前端页面
|
||||
7b9e082 feat: 向量记忆 RAG、工具市场、SSE 流式响应、前端集成与测试覆盖
|
||||
036f533 feat: Agent 监控与编排、仪表盘/配置页及文档更新
|
||||
0946756 feat: Agent 运行时、对话 API、作业助手与引擎修复
|
||||
4366312 feat: DeepSeek v4 模型对齐、作业助手脚本与 Agent 对比测试
|
||||
cadeb2d fix: 修复热点摘要超长上下文并统一 Windows 启动文档
|
||||
63b5411 图片上传识别功能
|
||||
df4fab1 feat: Agent 批量测试、作业助手与上传预览
|
||||
0608161 feat: 完善企业场景多线路由与执行稳定性
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 16. 常见问题速查
|
||||
|
||||
| 症状 | 根因 | 解决 |
|
||||
|---|---|---|
|
||||
| `timeout of 30000ms exceeded` | Redis 端口不匹配或 Celery 未运行 | 检查 `.env` 中 `REDIS_URL` 端口与 `netstat` 一致 |
|
||||
| Celery 任务卡住 | Windows prefork 池问题 | 使用 `--pool=threads` (脚本已配置) |
|
||||
| 前端 401 | Token 过期或未登录 | 重新登录获取 Token |
|
||||
| OCR 不工作 | Tesseract 未安装或路径不对 | 检查 `TESSERACT_CMD` 路径 |
|
||||
| 内置工具未注册 | Worker 与 API 使用不同启动逻辑 | 确认 Worker 日志中有"内置工具就绪" |
|
||||
| 工作流执行超时 | 循环节点未终止或 LLM 调用过多 | 检查执行日志，调整预算上限 |
|
||||
| `.env` 改完不生效 | 仅重启了 API，Celery 未重启 | 执行 `restart_backend_celery.ps1` |
|
||||
|
||||
---
|
||||
|
||||
## 17. 开发工作流
|
||||
|
||||
```
|
||||
改前端代码 → Vite HMR 自动生效
|
||||
改后端 API 代码 → uvicorn --reload 自动重启
|
||||
改 .env / 依赖 → restart_backend_celery.ps1
|
||||
改工具实现 → restart_backend_celery.ps1
|
||||
改工作流引擎 → restart_backend_celery.ps1
|
||||
加新节点类型 → 修改 workflow_engine.py + 前端 NodeTypes.ts + restart
|
||||
```
|
||||
600
docs/architecture/(红头)项目核心文档汇总.md
Normal file
600
docs/architecture/(红头)项目核心文档汇总.md
Normal file
@@ -0,0 +1,600 @@
|
||||
# 低代码智能体平台 - 核心文档汇总
|
||||
|
||||
## 项目概述
|
||||
|
||||
### 项目背景
|
||||
低代码智能体平台旨在让非技术用户通过可视化拖拽的方式，快速构建和部署AI智能体，降低AI应用开发门槛，提高开发效率。
|
||||
|
||||
### 核心价值
|
||||
- **零代码/低代码**：通过可视化界面配置智能体，无需编写代码
|
||||
- **快速部署**：一键部署到多种环境（云服务、本地、边缘设备）
|
||||
- **灵活扩展**：支持自定义组件和插件机制
|
||||
- **多模型支持**：集成主流AI模型（OpenAI、Claude、DeepSeek等）
|
||||
- **工作流编排**：支持复杂的工作流设计和执行
|
||||
- **Agent协作**：支持多Agent协作和工具链管理
|
||||
- **自主 AI Agent 运行时**：支持 ReAct 自主循环的 Agent Runtime，可独立对话或嵌入工作流
|
||||
|
||||
### 目标用户
|
||||
- 产品经理和业务人员
|
||||
- 初级开发者
|
||||
- 企业数字化转型团队
|
||||
- AI应用开发者
|
||||
|
||||
## 系统架构设计
|
||||
|
||||
### 整体架构
|
||||
采用前后端分离的微服务架构：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 前端层 (Frontend) │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ 可视化编辑器 │ │ 智能体管理 │ │ 监控面板 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ HTTP/WebSocket
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ API网关层 (Gateway) │
|
||||
│ 认证、限流、路由、负载均衡 │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 业务服务层 (Services) │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
|
||||
│ │智能体引擎 │ │工作流引擎 │ │模型管理 │ │数据管理 ││
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
|
||||
│ │任务调度 │ │日志监控 │ │用户管理 │ │权限管理 ││
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 数据存储层 (Storage) │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
|
||||
│ │ MySQL │ │ │ │ Redis │ │ ││
|
||||
│ │(元数据) │ │ │ │(缓存) │ │ ││
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 外部服务层 (External) │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
|
||||
│ │ OpenAI │ │ DeepSeek │ │ 本地模型 │ │ 其他API ││
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 技术栈选型
|
||||
|
||||
#### 前端技术栈
|
||||
- **框架**: Vue 3 + TypeScript + Vite
|
||||
- **状态管理**: Pinia
|
||||
- **UI组件库**: Element Plus
|
||||
- **工作流可视化**: Vue Flow
|
||||
- **HTTP客户端**: Axios
|
||||
- **WebSocket**: 原生WebSocket API
|
||||
|
||||
#### 后端技术栈
|
||||
- **框架**: Python FastAPI
|
||||
- **数据库**: MySQL（腾讯云数据库）
|
||||
- **缓存/消息队列**: Redis
|
||||
- **异步任务**: Celery
|
||||
- **AI框架**: LangChain
|
||||
- **Agent Runtime**: 自研 ReAct 循环（零重构，寄生式复用现有服务）
|
||||
- **Agent Orchestrator**: 多 Agent 编排引擎（路由/顺序/辩论三种模式）
|
||||
- **Agent 监控**: LLM 调用埋点 + 专属 Dashboard（Token/工具/Agent 用量统计）
|
||||
- **数据库ORM**: SQLAlchemy
|
||||
- **迁移工具**: Alembic
|
||||
- **认证**: JWT
|
||||
|
||||
## 核心功能模块
|
||||
|
||||
### 1. 用户认证系统
|
||||
- 用户注册、登录
|
||||
- JWT Token认证
|
||||
- 密码加密（bcrypt）
|
||||
- 获取当前用户信息
|
||||
|
||||
### 2. 工作流管理
|
||||
- 工作流CRUD（创建、读取、更新、删除）
|
||||
- 可视化编辑器（拖拽节点、连线）
|
||||
- 节点配置面板
|
||||
- 工作流版本管理
|
||||
- 工作流导入导出
|
||||
- 工作流模板市场
|
||||
|
||||
### 3. 工作流执行引擎
|
||||
- DAG构建和拓扑排序
|
||||
- 节点执行器（支持多种节点类型）
|
||||
- 数据流管理（节点间数据传递）
|
||||
- Celery异步任务集成
|
||||
- 执行状态管理
|
||||
- 错误处理和重试机制
|
||||
|
||||
### 4. 节点类型支持
|
||||
- **基础节点**: 开始、输入、输出、结束
|
||||
- **AI节点**: LLM（支持OpenAI、DeepSeek等）
|
||||
- **逻辑节点**: 条件、循环
|
||||
- **数据节点**: 转换、数据库查询、文件操作
|
||||
- **集成节点**: HTTP请求、Webhook、邮件、消息队列
|
||||
- **工具节点**: 定时任务、Agent节点
|
||||
|
||||
### 5. 内置工具调用
|
||||
平台提供10个内置工具，可在LLM节点中启用：
|
||||
1. 🌐 **http_request** - HTTP请求工具
|
||||
2. 📖 **file_read** - 文件读取工具
|
||||
3. ✍️ **file_write** - 文件写入工具
|
||||
4. 📊 **text_analyze** - 文本分析工具
|
||||
5. 🕐 **datetime** - 日期时间工具
|
||||
6. 🔢 **math_calculate** - 数学计算工具
|
||||
7. 💻 **system_info** - 系统信息工具
|
||||
8. 📦 **json_process** - JSON处理工具
|
||||
9. 🗄️ **database_query** - 数据库查询工具（只读查询场景）
|
||||
10. 📱 **adb_log** - Android/设备日志工具
|
||||
|
||||
### 6. 执行管理
|
||||
- 创建执行任务
|
||||
- 获取执行记录列表
|
||||
- 获取执行详情
|
||||
- 执行状态实时推送（WebSocket）
|
||||
- 执行结果可视化
|
||||
- 执行日志和监控
|
||||
|
||||
### 7. 数据源管理
|
||||
- 数据源模型和CRUD API
|
||||
- 数据源连接测试
|
||||
- 数据查询功能
|
||||
|
||||
### 8. 模型配置管理
|
||||
- 模型配置CRUD API（API Key 等在服务端加密存储；工作流 LLM 节点可绑定 `model_config_id` 由可信所有者运行时解密注入）
|
||||
- 多模型支持（OpenAI、Anthropic 兼容路径、DeepSeek 等）
|
||||
- 模型切换和配置
|
||||
|
||||
**DeepSeek API（OpenAI 兼容格式）**
|
||||
与 [DeepSeek API 文档](https://api-docs.deepseek.com/) 对齐的常用参数如下（密钥需在控制台申请，勿写入文档或仓库）：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| **base_url** | `https://api.deepseek.com`（OpenAI 兼容；Anthropic 兼容格式为 `https://api.deepseek.com/anthropic`） |
|
||||
| **主推模型** | `deepseek-v4-flash`、`deepseek-v4-pro` |
|
||||
| **兼容旧名（计划弃用）** | `deepseek-chat`、`deepseek-reasoner` 计划于 **2026/07/24** 弃用；二者分别对应 `deepseek-v4-flash` 的非思考与思考模式 |
|
||||
|
||||
本平台侧：**新建 LLM 节点、节点模板及后端未显式指定模型时的 DeepSeek 默认值**为 **`deepseek-v4-flash`**；工作流编辑器与「模型配置」页下拉仍可选择兼容旧模型名并标注弃用时间。
|
||||
|
||||
### Agent管理
|
||||
- Agent CRUD API
|
||||
- Agent管理页面
|
||||
- Agent协作功能
|
||||
- 批量场景Agent脚本（教育/企业/政务/媒体）
|
||||
|
||||
### 10. Agent Runtime（自主 AI Agent）
|
||||
- **ReAct 自主循环**：LLM 思考→工具调用→观察结果→再思考，支持最多 N 步迭代
|
||||
- **分层记忆**：短期（会话上下文）+ 长期（MySQL 持久化），LLM 自动压缩总结
|
||||
- **执行追踪**：每步迭代记录 think/tool_call/tool_result/final，返回 steps 供前端展开
|
||||
- **工具管理**：白名单/黑名单过滤，包装已有 ToolRegistry
|
||||
- **工作流桥接**：Agent 节点可嵌入工作流 DAG，复用工作流引擎
|
||||
- **独立对话**：通过专用 API 直接与 Agent 对话，不依赖工作流
|
||||
- **LLM 调用埋点**：每次 LLM 调用自动记录模型、tokens、耗时到 AgentLLMLog 表
|
||||
- **Agent 监控**：专属 Dashboard 展示 Agent 用量排行、LLM 调用记录、Token 统计、工具调用频次
|
||||
- **多 Agent 编排**：三种协作模式：
|
||||
- **route** — Router Agent 分析问题，分发到最匹配的 Specialist Agent
|
||||
- **sequential** — Agent 流水线执行，前者输出作为后者输入
|
||||
- **debate** — 多个 Agent 独立回答，Aggregator 汇总为最终答案
|
||||
- **自主学习**：Agent 从历史执行中自动优化工具选择策略，基于 AgentLearningPattern 模型记录和累计工具使用模式，执行前注入历史模式到 system prompt
|
||||
|
||||
### 11. Agent 定时任务系统
|
||||
- **cron 调度**：支持标准 cron 表达式，按周期自动触发 Agent 执行
|
||||
- **Celery Beat 集成**：每分钟检查到期任务，到期自动触发
|
||||
- **执行管理**：支持手动触发、暂停/恢复、执行状态跟踪
|
||||
- **飞书推送**：定时任务执行结果自动推送到飞书（Webhook + 应用消息）
|
||||
|
||||
### 12. 飞书集成和通知系统
|
||||
- **通知系统**：统一的通知管理（notifications 表、通知服务、API）
|
||||
- **飞书定时任务推送**：定时任务执行结果自动推送飞书
|
||||
- **飞书应用消息**：通过飞书应用 API 发送消息通知
|
||||
- **飞书账号绑定**：用户可绑定飞书账号，接收个性化通知
|
||||
- **橙子飞书机器人**：独立 WebSocket 连接的飞书机器人，固定路由到橙子助手 Agent
|
||||
- **飞书事件监听**：WebSocket 长连接监听飞书 IM 事件
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
aiagent/
|
||||
├── frontend/ # 前端项目（Vue 3 + TypeScript）
|
||||
│ ├── src/
|
||||
│ │ ├── assets/ # 静态资源
|
||||
│ │ ├── components/ # 组件
|
||||
│ │ ├── router/ # 路由
|
||||
│ │ ├── stores/ # 状态管理（Pinia）
|
||||
│ │ ├── views/ # 页面
|
||||
│ │ └── App.vue # 根组件
|
||||
│ ├── package.json # 依赖配置
|
||||
│ ├── vite.config.ts # Vite配置
|
||||
│ └── Dockerfile.dev # 开发环境Dockerfile
|
||||
├── backend/ # 后端项目（Python FastAPI）
|
||||
│ ├── app/
|
||||
│ │ ├── agent_runtime/ # Agent Runtime（新增，自主 ReAct 循环）
|
||||
│ │ │ ├── __init__.py # 包导出
|
||||
│ │ │ ├── schemas.py # Agent 配置 Schema + AgentStep 执行追踪
|
||||
│ │ │ ├── context.py # 会话上下文（消息历史、迭代追踪）
|
||||
│ │ │ ├── memory.py # 分层记忆管理器 + LLM 自动压缩总结
|
||||
│ │ │ ├── tool_manager.py# 工具管理器（包装 ToolRegistry）
|
||||
│ │ │ ├── core.py # AgentRuntime 主循环（ReAct 核心）+ 自主学习集成
|
||||
│ │ │ ├── orchestrator.py# 多 Agent 编排引擎（route/sequential/debate/pipeline）
|
||||
│ │ │ └── workflow_integration.py # 工作流桥接
|
||||
│ │ ├── api/ # API路由
|
||||
│ │ │ ├── agent_chat.py # Agent 聊天 + 多 Agent 编排 + LLM 调用日志 + SSE 流式
|
||||
│ │ │ ├── agent_monitoring.py # Agent 监控 API 5 个端点
|
||||
│ │ │ ├── agent_schedules.py # Agent 定时任务 CRUD API + 手动触发
|
||||
│ │ │ ├── feishu_bind.py # 飞书账号绑定/解绑 API
|
||||
│ │ │ └── notifications.py # 通知系统 API
|
||||
│ │ ├── core/ # 核心模块
|
||||
│ │ ├── models/ # 数据库模型
|
||||
│ │ │ ├── agent_llm_log.py # Agent LLM 调用日志模型
|
||||
│ │ │ ├── agent_learning_pattern.py # Agent 学习模式模型（自主学习）
|
||||
│ │ │ ├── agent_schedule.py # Agent 定时任务调度模型
|
||||
│ │ │ ├── notification.py # 通知模型
|
||||
│ │ │ └── agent_vector_memory.py # Agent 向量记忆表模型
|
||||
│ │ ├── schemas/ # Pydantic模式
|
||||
│ │ ├── services/ # 业务逻辑
|
||||
│ │ │ ├── agent_monitoring_service.py # Agent 监控服务
|
||||
│ │ │ ├── agent_learning_service.py # 自主学习服务（工具选择优化）
|
||||
│ │ │ ├── agent_schedule_service.py # 定时任务调度服务
|
||||
│ │ │ ├── notification_service.py # 通知服务
|
||||
│ │ │ ├── feishu_app_service.py # 飞书应用消息发送
|
||||
│ │ │ ├── feishu_notifier.py # 飞书通知器
|
||||
│ │ │ ├── feishu_ws_handler.py # 飞书 WebSocket 事件处理
|
||||
│ │ │ ├── orange_app_service.py # 橙子飞书机器人服务
|
||||
│ │ │ ├── orange_ws_handler.py # 橙子机器人 WS 处理
|
||||
│ │ │ ├── knowledge_service.py # 知识库 RAG 服务
|
||||
│ │ │ ├── embedding_service.py # Embedding 生成服务
|
||||
│ │ │ ├── document_parser.py # 文档解析器
|
||||
│ │ │ └── text_chunker.py # 文本分块器
|
||||
│ │ └── main.py # 应用入口
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── tests/ # 测试
|
||||
│ ├── requirements.txt # Python依赖
|
||||
│ ├── Dockerfile.dev # 开发环境Dockerfile
|
||||
│ └── alembic.ini # Alembic配置
|
||||
├── docker-compose.dev.yml # 开发环境Docker Compose配置
|
||||
├── README.md # 项目说明
|
||||
├── QUICKSTART.md # 快速启动指南
|
||||
├── 使用指南.md # 用户使用指南
|
||||
├── 方案-优化版.md # 完整技术方案
|
||||
├── 开发进度.md # 开发进度跟踪
|
||||
├── 内置工具列表.md # 内置工具文档
|
||||
└── 项目核心文档汇总.md # 本文档
|
||||
```
|
||||
|
||||
## 部署指南
|
||||
|
||||
### 前置要求
|
||||
- Node.js 18+ 和 pnpm
|
||||
- Python 3.11+
|
||||
- Docker 和 Docker Compose
|
||||
- MySQL（使用腾讯云数据库）
|
||||
- Redis 7+（或使用Docker）
|
||||
|
||||
### 使用 Docker Compose 启动（推荐）
|
||||
```bash
|
||||
# 启动所有服务
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
|
||||
# 查看服务状态
|
||||
docker-compose ps
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 停止服务
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 本地开发部署
|
||||
|
||||
#### 后端服务
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# 创建虚拟环境
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 配置环境变量
|
||||
cp env.example .env
|
||||
# 编辑 .env 文件（数据库已配置为腾讯云MySQL）
|
||||
|
||||
# 运行数据库迁移
|
||||
alembic upgrade head
|
||||
|
||||
# 启动开发服务器
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# 启动 Celery Worker（新终端）
|
||||
celery -A app.core.celery_app worker --loglevel=info
|
||||
```
|
||||
|
||||
#### 前端服务
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 启动开发服务器
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### 服务访问地址
|
||||
- **前端（本地开发推荐）**: http://localhost:3001
|
||||
- **前端（Docker方案）**: http://localhost:8038
|
||||
- **后端API**: http://localhost:8037
|
||||
- **API文档**: http://localhost:8037/docs
|
||||
- **Redis**: localhost:6379
|
||||
|
||||
## API 文档摘要
|
||||
|
||||
### 认证API
|
||||
- `POST /api/v1/auth/register` - 用户注册
|
||||
- `POST /api/v1/auth/login` - 用户登录（获取JWT Token）
|
||||
- `GET /api/v1/auth/me` - 获取当前用户信息
|
||||
|
||||
### 工作流API
|
||||
- `GET /api/v1/workflows` - 获取工作流列表
|
||||
- `POST /api/v1/workflows` - 创建工作流
|
||||
- `GET /api/v1/workflows/{id}` - 获取工作流详情
|
||||
- `PUT /api/v1/workflows/{id}` - 更新工作流
|
||||
- `DELETE /api/v1/workflows/{id}` - 删除工作流
|
||||
- `POST /api/v1/workflows/{id}/execute` - 执行工作流
|
||||
|
||||
### 执行管理API
|
||||
- `GET /api/v1/executions` - 获取执行记录列表
|
||||
- `GET /api/v1/executions/{id}` - 获取执行详情
|
||||
- `GET /api/v1/executions/{id}/status` - 获取执行状态
|
||||
|
||||
### 数据源API
|
||||
- `GET /api/v1/data-sources` - 获取数据源列表
|
||||
- `POST /api/v1/data-sources` - 创建数据源
|
||||
- `POST /api/v1/data-sources/{id}/test` - 测试数据源连接
|
||||
- `POST /api/v1/data-sources/{id}/query` - 执行数据查询
|
||||
|
||||
### Agent 与编排 API（新增）
|
||||
- `POST /api/v1/agent-chat/bare` - 默认 Agent 直接对话（无需预配置）
|
||||
- `POST /api/v1/agent-chat/{agent_id}` - 与指定 Agent 对话（复用工作流配置）
|
||||
- `POST /api/v1/agent-chat/orchestrate` - 多 Agent 编排（route/sequential/debate 三种模式）
|
||||
- 请求体: `{ message, mode, agents[] }` 每个 Agent 可独立配置 system_prompt/model/temperature/tools
|
||||
- 返回: `{ final_answer, steps[], agent_results[] }`
|
||||
|
||||
### Agent 监控 API（新增）
|
||||
- `GET /api/v1/agent-monitoring/overview` - Agent 概览统计（Agent 数、对话/LLM/工具调用次数、Token 用量）
|
||||
- `GET /api/v1/agent-monitoring/llm-calls?days=7&limit=50` - LLM 调用记录列表（模型、tokens、耗时、状态）
|
||||
- `GET /api/v1/agent-monitoring/agents-stats?days=7` - 各 Agent 用量排行（调用次数、Token、延迟）
|
||||
- `GET /api/v1/agent-monitoring/tool-usage?days=7` - 工具调用频次统计
|
||||
- `GET /api/v1/agent-monitoring/daily-trend?days=7` - 每日 LLM 调用趋势
|
||||
|
||||
### WebSocket API
|
||||
- `ws://localhost:8037/ws/execution/{execution_id}` - 执行状态实时推送
|
||||
|
||||
完整API文档请访问：http://localhost:8037/docs
|
||||
|
||||
## 用户指南摘要
|
||||
|
||||
### 快速开始使用
|
||||
1. **登录系统**：访问 http://localhost:8038，注册并登录
|
||||
2. **创建工作流**：点击"创建工作流"按钮进入可视化编辑器
|
||||
3. **拖拽节点**：从左侧工具箱拖拽节点到画布
|
||||
4. **连接节点**：点击节点的连接点并拖拽到目标节点
|
||||
5. **配置节点**：点击节点，在右侧配置面板设置参数
|
||||
6. **保存工作流**：点击工具栏的"保存"按钮
|
||||
7. **执行工作流**：点击工具栏的"运行"按钮
|
||||
|
||||
### 节点类型说明
|
||||
- **开始节点**：工作流起始节点
|
||||
- **输入节点**：数据输入节点，可配置输入参数
|
||||
- **LLM节点**：AI 模型处理节点，支持 OpenAI、DeepSeek 等；DeepSeek 推荐选用 **`deepseek-v4-flash`** 或 **`deepseek-v4-pro`**（旧名 `deepseek-chat` / `deepseek-reasoner` 仍可兼容使用，计划 **2026/07/24** 弃用）
|
||||
- **条件节点**：条件判断节点，支持表达式配置
|
||||
- **转换节点**：数据转换节点，支持JSONPath、模板等
|
||||
- **输出节点**：数据输出节点，可配置输出格式
|
||||
- **结束节点**：工作流结束节点
|
||||
|
||||
### 工具调用功能
|
||||
在LLM节点中启用工具调用，AI可以调用内置工具处理任务：
|
||||
1. 选择LLM节点，打开"工具"标签页
|
||||
2. 启用"启用工具调用"开关
|
||||
3. 选择需要的工具（可多选）
|
||||
4. 保存配置
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 开发规范
|
||||
- **前端代码规范**：ESLint + Prettier
|
||||
- **后端代码规范**：PEP 8 + Black
|
||||
- **Git提交规范**：Conventional Commits
|
||||
- **代码审查**：必须通过Code Review
|
||||
|
||||
### 测试指南
|
||||
```bash
|
||||
# 前端测试
|
||||
cd frontend
|
||||
pnpm test
|
||||
|
||||
# 后端测试
|
||||
cd backend
|
||||
pytest
|
||||
```
|
||||
|
||||
### 数据库迁移
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# 创建新的迁移
|
||||
alembic revision --autogenerate -m "描述"
|
||||
|
||||
# 应用迁移
|
||||
alembic upgrade head
|
||||
|
||||
# 回退迁移
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
### 添加新节点类型
|
||||
1. 后端：在 `backend/app/services/workflow_engine.py` 的 `execute_node` 中增加节点类型分支；如需校验，可扩展 `workflow_validator.py`
|
||||
2. 前端：在 `frontend/src/components/nodes/`（或工作流编辑器关联组件）中增加节点展示与配置
|
||||
3. 前端：在 `frontend/src/stores/workflowStore.ts` 等处注册节点类型与默认数据
|
||||
|
||||
## 测试指南
|
||||
|
||||
### 单元测试
|
||||
- 使用 pytest 框架
|
||||
- 测试核心功能和工作流引擎
|
||||
- 测试API端点
|
||||
|
||||
### 集成测试
|
||||
- 测试数据库操作
|
||||
- 测试外部API集成
|
||||
- 测试工作流执行
|
||||
|
||||
### 端到端测试
|
||||
- 测试用户界面交互
|
||||
- 测试完整工作流执行
|
||||
- 测试跨浏览器兼容性
|
||||
|
||||
## 内置工具列表
|
||||
|
||||
平台提供10个内置工具，详细功能如下：
|
||||
|
||||
| 工具名称 | 功能描述 | 主要参数 |
|
||||
|---------|---------|---------|
|
||||
| http_request | 发送HTTP请求 | url, method, headers, body |
|
||||
| file_read | 读取文件内容 | file_path |
|
||||
| file_write | 写入文件内容 | file_path, content, mode |
|
||||
| text_analyze | 分析文本内容 | text, operation |
|
||||
| datetime | 处理日期时间 | operation, format |
|
||||
| math_calculate | 执行数学计算 | expression |
|
||||
| system_info | 获取系统信息 | 无 |
|
||||
| json_process | 处理JSON数据 | json_string, operation |
|
||||
| database_query | 只读数据库查询 | datasource/query(按工具schema) |
|
||||
| adb_log | 设备日志读取 | command/serial/lines(按工具schema) |
|
||||
|
||||
> 说明：`http_request` 已加入响应体截断与头部精简机制（支持 `max_body_chars`），用于避免大页面导致 LLM 上下文超限。
|
||||
|
||||
详细使用示例请参考：[内置工具列表.md](./内置工具列表.md)
|
||||
|
||||
## 开发进度和路线图
|
||||
|
||||
### 当前完成度
|
||||
- **第一阶段MVP**: 100% ✅
|
||||
- **第二阶段核心功能**: 100% ✅
|
||||
- **第三阶段核心功能**: 100% ✅
|
||||
- **第四-七阶段功能**: 100% ✅
|
||||
- **自主 Agent Runtime**: 100% ✅（2026-04 新增）
|
||||
- **多 Agent 编排**: 100% ✅（2026-05 新增）
|
||||
- **Agent 监控 Dashboard**: 100% ✅（2026-05 新增）
|
||||
- **SSE 流式输出**: 100% ✅（2026-05 新增）
|
||||
- **向量记忆 + 知识库 RAG**: 100% ✅（2026-05 新增）
|
||||
- **工具市场**: 100% ✅（2026-05 新增）
|
||||
- **工作流预算接入**: 100% ✅（2026-05 新增）
|
||||
- **Agent 自主学习**: 100% ✅（2026-05 新增）
|
||||
- **Agent 定时任务系统**: 100% ✅（2026-05 新增）
|
||||
- **飞书通知与机器人对话**: 100% ✅（2026-05 新增）
|
||||
- **整体项目**: 约 99.9%
|
||||
|
||||
### 已完成核心功能
|
||||
1. **完整的用户认证系统** - 注册、登录、JWT认证
|
||||
2. **工作流CRUD** - 创建、读取、更新、删除工作流
|
||||
3. **工作流执行引擎** - DAG构建、拓扑排序、节点执行
|
||||
4. **可视化编辑器** - 拖拽节点、连线、配置面板
|
||||
5. **异步任务处理** - Celery集成，支持长时间运行的任务
|
||||
6. **多模型支持** - OpenAI、DeepSeek 等（DeepSeek 主推 `deepseek-v4-flash` / `deepseek-v4-pro`）
|
||||
7. **内置工具调用** - 10 个内置工具支持
|
||||
8. **实时状态推送** - WebSocket实时推送执行状态
|
||||
9. **批量Agent场景生成** - 教育与政务/媒体场景批量创建脚本
|
||||
10. **Windows运维文档统一** - 启停/重启流程合并为单一权威文档
|
||||
11. **自主 AI Agent 运行时** - 新增 `agent_runtime` 模块（~1020 行），实现 ReAct 自主循环、工具调用、分层记忆管理
|
||||
12. **Agent 独立对话** - `POST /api/v1/agent-chat/bare` 和 `/{agent_id}` API，前端 AgentChat.vue 页面
|
||||
13. **工作流 Agent 节点** - 工作流引擎新增 `agent` 节点类型，Agent 可嵌入 DAG 执行
|
||||
14. **执行追踪与思考链** - 后端 steps 记录每步迭代，前端可展开显示思考链
|
||||
15. **记忆压缩总结** - LLM 自动提取用户画像/关键事实/话题，去重后存入长期记忆
|
||||
16. **Agent 配置页面** - AgentConfig.vue 可视化编辑 System Prompt / 模型 / Temperature / 工具
|
||||
17. **多 Agent 编排** - AgentOrchestrator 三种模式（route/sequential/debate），前端编排 UI 支持模式切换和动态 Agent 编辑
|
||||
18. **Agent 监控 Dashboard** - 实时 LLM 调用埋点（AgentLLMLog 表）、Agent 用量排行、Token 统计、工具调用频次、日趋势图
|
||||
19. **SSE 流式输出** - Agent 思考过程实时推送到前端
|
||||
20. **向量记忆** - Embedding API + 余弦相似度 Top-K 语义检索
|
||||
21. **知识库 RAG** - 文件上传 → 5 种格式解析 → 分块 → 向量化 → 检索增强
|
||||
22. **工具市场** - HTTP/Code 工具 CRUD + 沙箱测试 + 分类浏览
|
||||
23. **工作流预算接入** - Agent LLM/工具调用计入 WorkflowEngine 全局预算
|
||||
24. **Agent 自主学习** - 从历史执行中自动优化工具选择策略（AgentLearningPattern）
|
||||
25. **Agent 定时任务系统** - cron 表达式定时触发 Agent 执行，集成 Celery Beat
|
||||
26. **飞书通知与机器人对话** - 通知系统、飞书定时任务推送、橙子飞书机器人
|
||||
|
||||
### 近期规划
|
||||
1. **多租户支持** - 租户模型、数据隔离、资源配额管理
|
||||
2. **插件系统** - 插件注册机制、自定义节点插件开发框架
|
||||
3. **性能优化** - 工作流执行性能优化、前端性能优化
|
||||
4. **用户体验优化** - 工作流编辑器优化、Agent使用体验优化
|
||||
|
||||
详细开发进度请参考：[开发进度.md](./开发进度.md)
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 数据库连接失败
|
||||
- 检查MySQL数据库是否可访问（腾讯云数据库）
|
||||
- 检查数据库连接信息是否正确（.env 文件）
|
||||
- 检查网络连接是否正常
|
||||
|
||||
### 2. Redis 连接失败
|
||||
- 检查Redis是否正在运行
|
||||
- 检查Redis URL是否正确
|
||||
|
||||
### 3. 前端无法连接后端
|
||||
- 检查后端服务是否正在运行
|
||||
- 检查前端配置的API URL是否正确（vite.config.ts）
|
||||
- 检查CORS配置是否正确
|
||||
|
||||
### 4. Celery 任务不执行
|
||||
- 检查Celery Worker是否正在运行
|
||||
- 检查Redis连接是否正常
|
||||
- 检查任务是否正确注册
|
||||
|
||||
### 5. 工作流执行失败
|
||||
- 检查节点配置是否正确
|
||||
- 检查LLM API密钥是否有效
|
||||
- 查看执行日志获取详细错误信息
|
||||
|
||||
## 联系和支持
|
||||
|
||||
- **API文档**：http://localhost:8037/docs
|
||||
- **前端服务（本地开发）**：http://localhost:3001
|
||||
- **前端服务（Docker）**：http://localhost:8038
|
||||
- **问题反馈**：查看项目文档或联系开发团队
|
||||
|
||||
## 关键文档索引（建议）
|
||||
|
||||
- Windows 启停唯一文档：[`(红头)Windows服务器启动与重启唯一指南.md`](./(红头)Windows服务器启动与重启唯一指南.md)
|
||||
- 上传图片与OCR实现：[`(红头)上传图片和识别的实现文档.md`](./(红头)上传图片和识别的实现文档.md)
|
||||
- 教育行业批量Agent脚本：`backend/scripts/create_education_agents_batch.py`
|
||||
- 政务/媒体批量Agent脚本：`backend/scripts/create_gov_media_agents_batch.py`
|
||||
- 企业场景批量Agent脚本：`backend/scripts/create_enterprise_scenario_agents.py`
|
||||
- 自主 AI Agent 改造完成情况：[`自主AI Agent改造完成情况.md`](./自主AI%20Agent改造完成情况.md)
|
||||
- Agent Runtime 源码入口：`backend/app/agent_runtime/core.py`
|
||||
- Agent 聊天 API 路由：`backend/app/api/agent_chat.py`
|
||||
- Agent 聊天前端页面：`frontend/src/views/AgentChat.vue`
|
||||
- Agent 配置页面：`frontend/src/views/AgentConfig.vue`
|
||||
- 多 Agent 编排引擎：`backend/app/agent_runtime/orchestrator.py`
|
||||
- Agent 监控 Dashboard：`frontend/src/views/AgentDashboard.vue`
|
||||
- Agent LLM 调用日志模型：`backend/app/models/agent_llm_log.py`
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-05-02
|
||||
**文档版本**: 1.7
|
||||
|
||||
*本文档基于项目现有文档整理生成，涵盖项目核心信息。详细技术方案请参考[方案-优化版.md](./方案-优化版.md)。DeepSeek 模型名与 Base URL 以官方文档为准，变更时请同步修订本节。*
|
||||
213
docs/architecture/AI agent改造计划.md
Normal file
213
docs/architecture/AI agent改造计划.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
从工作流引擎到自主 AI Agent：改造方案
|
||||
|
||||
核心思路：不要重构，要"寄生式"生长
|
||||
|
||||
现有引擎 5788 行，WorkflowEditor.vue 9140 行——不要重构它们。而是寄生在已有的 ToolRegistry、LLM Service、Memory Service
|
||||
之上，新建一个独立的 Agent Runtime。
|
||||
|
||||
---
|
||||
第一步：构建 Agent Runtime 内核（1 周）
|
||||
|
||||
新建 backend/app/agent_runtime/ 包：
|
||||
|
||||
backend/app/agent_runtime/
|
||||
├── __init__.py
|
||||
├── core.py # Agent 主循环
|
||||
├── context.py # Agent 上下文（会话状态）
|
||||
├── memory.py # 记忆管理（连接已有记忆服务）
|
||||
├── tool_manager.py # 工具选择与执行（连接已有 ToolRegistry）
|
||||
└── schemas.py # Agent 配置 Schema
|
||||
|
||||
核心循环 (core.py)：
|
||||
|
||||
class AgentRuntime:
|
||||
"""
|
||||
自主 Agent 循环（ReAct）
|
||||
|
||||
loop:
|
||||
1. LLM 思考 → 返回文本或工具调用
|
||||
2. 如果返回文本 → 结束，返回最终回答
|
||||
3. 如果调用工具 → 执行工具 → 结果追加到 messages → 回到 1
|
||||
4. 超过 max_iterations → 强制结束
|
||||
"""
|
||||
|
||||
async def run(self, user_input: str) -> AgentResult:
|
||||
while self.iteration < self.max_iterations:
|
||||
response = await self.llm.chat(messages, tools)
|
||||
if response.has_tool_calls:
|
||||
for tool_call in response.tool_calls:
|
||||
result = tool_registry.execute(tool_call)
|
||||
messages.append(tool_result_message)
|
||||
else:
|
||||
return AgentResult(text=response.content)
|
||||
return AgentResult(text="已达最大迭代次数", truncated=True)
|
||||
|
||||
关键设计点：
|
||||
|
||||
┌────────────┬─────────────────────────────────────────────────┬───────────────────────┐
|
||||
│ 组件 │ 复用什么 │ 新写什么 │
|
||||
├────────────┼─────────────────────────────────────────────────┼───────────────────────┤
|
||||
│ LLM 调用 │ llm_service.call_openai_with_tools() 已有 ReAct │ 不用写 │
|
||||
├────────────┼─────────────────────────────────────────────────┼───────────────────────┤
|
||||
│ 工具执行 │ ToolRegistry.get_tool_function() │ 不用写 │
|
||||
├────────────┼─────────────────────────────────────────────────┼───────────────────────┤
|
||||
│ 记忆存储 │ persistent_memory_service.py │ 记忆检索 + 自动压缩 │
|
||||
├────────────┼─────────────────────────────────────────────────┼───────────────────────┤
|
||||
│ 系统提示词 │ — │ Agent 人格/指令系统 │
|
||||
├────────────┼─────────────────────────────────────────────────┼───────────────────────┤
|
||||
│ 会话管理 │ — │ 状态保持 + 多轮上下文 │
|
||||
└────────────┴─────────────────────────────────────────────────┴───────────────────────┘
|
||||
|
||||
工作量：约 300 行代码。已有轮子都在，只要串起来。
|
||||
|
||||
---
|
||||
第二步：让 Agent Runtime 能用上已有工具（3 天）
|
||||
|
||||
现有 ToolRegistry 有 20+ 内置工具，但只通过 llm_service.py 的 _execute_tool 私有方法调用。需要：
|
||||
|
||||
# 新增 agent_runtime/tool_manager.py
|
||||
class AgentToolManager:
|
||||
def __init__(self, tool_registry):
|
||||
self.registry = tool_registry
|
||||
|
||||
def get_tools_for_llm(self) -> list:
|
||||
# 把 ToolRegistry 的 schema 转为 OpenAI tool format
|
||||
return self.registry.get_all_tool_schemas()
|
||||
|
||||
async def execute(self, name: str, args: dict) -> str:
|
||||
func = self.registry.get_tool_function(name)
|
||||
if func is None:
|
||||
return f"错误：工具 {name} 不存在"
|
||||
result = await func(**args) # 已有，直接复用
|
||||
return str(result)
|
||||
|
||||
注意：现有 _execute_tool 在 llm_service.py 中，需要提取成公共方法或让 ToolManager 直接调用已有实现。
|
||||
|
||||
---
|
||||
第三步：接入记忆系统（3 天）
|
||||
|
||||
现有记忆系统已经可以读写用户画像和对话历史（persistent_memory_service.py），但只在 Cache 节点中被动使用。
|
||||
|
||||
需要：
|
||||
|
||||
# agent_runtime/memory.py
|
||||
class AgentMemory:
|
||||
"""
|
||||
分层记忆：
|
||||
- 工作记忆：当前会话的 messages
|
||||
- 长期记忆：从 DB/Redis 加载的历史画像 + 重要事实
|
||||
- 工具记忆：哪些工具调用成功/失败（辅助 LLM 决策）
|
||||
"""
|
||||
|
||||
async def load_context(self, user_id: str) -> str:
|
||||
# 从 persistent_memory_service 加载用户画像
|
||||
profile = get_user_profile(user_id)
|
||||
# 从数据库加载最近对话摘要
|
||||
history = get_conversation_summary(user_id)
|
||||
return f"用户画像：{profile}\n历史记录：{history}"
|
||||
|
||||
async def save(self, messages: list):
|
||||
# 自动总结关键信息写入长期记忆
|
||||
summary = await self.llm.summarize(messages)
|
||||
save_user_profile(user_id, summary)
|
||||
|
||||
---
|
||||
第四步：在现有工作流中启用 Agent 节点（3 天）
|
||||
|
||||
在 workflow_engine.py 的 execute_node 中新增 agent 类型：
|
||||
|
||||
# 现有 5788 行引擎只需加一个分支
|
||||
elif node_type == 'agent':
|
||||
# 初始化 Agent Runtime
|
||||
runtime = AgentRuntime(
|
||||
system_prompt=node_data.get('system_prompt'),
|
||||
tools=node_data.get('tools', []), # 可选，默认全部
|
||||
memory_enabled=node_data.get('memory', True),
|
||||
)
|
||||
result = await runtime.run(input_data.get('query', ''))
|
||||
|
||||
这样不用动现有任何节点，用户可以在工作流中拖一个 Agent 节点，它就能：
|
||||
1. 自动 ReAct 循环
|
||||
2. 调用任意内置工具
|
||||
3. 使用长期记忆
|
||||
4. 自我纠错
|
||||
|
||||
---
|
||||
第五步：独立 Agent 运行模式（1 周）
|
||||
|
||||
不依赖工作流 DAG，可以直接启动 Agent：
|
||||
|
||||
POST /api/v1/agents/{id}/chat
|
||||
{"message": "帮我写一个Python脚本读取日志"}
|
||||
|
||||
后端：
|
||||
runtime = AgentRuntime(agent_config)
|
||||
result = await runtime.run(message)
|
||||
return result
|
||||
|
||||
前端可以加一个聊天界面（类似 ChatGPT）：
|
||||
- 已有 AgentChatPreview.vue 可以改造
|
||||
- 复用现有 Agents.vue 的列表和配置
|
||||
|
||||
---
|
||||
第六步：多智能体编排（2 周）
|
||||
|
||||
# agent_runtime/orchestrator.py
|
||||
class AgentOrchestrator:
|
||||
"""
|
||||
多 Agent 协作模式：
|
||||
|
||||
1. 路由模式：用户问题 → Router Agent → 分发到子 Agent
|
||||
2. 顺序模式：Agent A 输出 → Agent B 输入
|
||||
3. 辩论模式：多个 Agent 独立回答 → 汇总
|
||||
"""
|
||||
|
||||
async def route(self, question: str) -> str:
|
||||
# Router Agent 判断应该用哪个 Specialist Agent
|
||||
specialist = await self.router_agent.choose(question)
|
||||
return await specialist.run(question)
|
||||
|
||||
---
|
||||
整体路线图
|
||||
|
||||
┌──────┬────────────────────────┬──────┬────────────┐
|
||||
│ 阶段 │ 内容 │ 时间 │ 前提 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P0 │ Agent Runtime 内核 │ 1 周 │ 无，纯新增 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P0 │ 工具接入 │ 3 天 │ P0 完成 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P1 │ 记忆接入 │ 3 天 │ P0 完成 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P1 │ Agent 节点（工作流内） │ 3 天 │ P0+P1 完成 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P2 │ 独立 Agent 聊天模式 │ 1 周 │ P0+P1 完成 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P3 │ 多 Agent 编排 │ 2 周 │ P0-P2 完成 │
|
||||
├──────┼────────────────────────┼──────┼────────────┤
|
||||
│ P3 │ Agent 工作台/监控 │ 1 周 │ P0-P2 完成 │
|
||||
└──────┴────────────────────────┴──────┴────────────┘
|
||||
|
||||
---
|
||||
为什么这个方案可行
|
||||
|
||||
你代码库中 关键能力已经就绪：
|
||||
|
||||
┌─────────────────────────┬─────────────────────────────────────┬──────────────────┬────────────────┐
|
||||
│ 已有能力 │ 位置 │ 当前用途 │ 新计划用途 │
|
||||
├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤
|
||||
│ ReAct 循环 │ llm_service.py:646 │ LLM 节点单次调用 │ Agent 核心循环 │
|
||||
├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤
|
||||
│ ToolRegistry + 20+ 工具 │ tool_registry.py + builtin_tools.py │ 工作流内使用 │ Agent 自主调用 │
|
||||
├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤
|
||||
│ 持久化记忆 │ persistent_memory_service.py │ Cache 节点 │ 长期记忆层 │
|
||||
├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤
|
||||
│ 对话历史注入 │ workflow_engine.py:986 │ LLM 节点 │ Agent 上下文 │
|
||||
├─────────────────────────┼─────────────────────────────────────┼──────────────────┼────────────────┤
|
||||
│ Agent 配置 │ models/agent.py │ 工作流包装 │ Agent 本体配置 │
|
||||
└─────────────────────────┴─────────────────────────────────────┴──────────────────┴────────────────┘
|
||||
|
||||
新增代码控制在 1500 行以内，不动现有 5788 行的引擎和 9140 行的编辑器。
|
||||
|
||||
需要我从第一步的 Agent Runtime 核心代码开始写吗？
|
||||
500
docs/architecture/aiagent项目架构文档.md
Normal file
500
docs/architecture/aiagent项目架构文档.md
Normal file
@@ -0,0 +1,500 @@
|
||||
# AIAgent 低代码智能体平台 — 项目架构文档
|
||||
|
||||
## 1. 概述
|
||||
|
||||
**AIAgent** 是一个低代码智能体 (Agent) 搭建与工作流编排平台，支持通过可视化拖拽方式配置工作流节点，集成多种 AI 模型、数据源、消息中间件、办公协同工具，实现复杂业务流程的自动化执行。
|
||||
|
||||
- **前端**: Vue 3 + TypeScript + Vite + Pinia + Element Plus + Vue Flow
|
||||
- **后端**: Python FastAPI + SQLAlchemy + Celery + MySQL + Redis
|
||||
- **异步任务**: Celery (Redis 作为 Broker)
|
||||
- **AI 模型**: 支持 OpenAI、DeepSeek、Anthropic 等多种大模型
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```
|
||||
aiagent/
|
||||
├── frontend/ # Vue 3 前端项目
|
||||
│ ├── src/
|
||||
│ │ ├── api/index.ts # Axios 封装 + 请求/响应拦截器
|
||||
│ │ ├── router/index.ts # Vue Router 路由配置
|
||||
│ │ ├── stores/ # Pinia 状态管理
|
||||
│ │ │ ├── index.ts # Store 入口
|
||||
│ │ │ ├── user.ts # 用户认证 Store
|
||||
│ │ │ ├── workflow.ts # 工作流 CRUD Store
|
||||
│ │ │ ├── agent.ts # Agent CRUD Store
|
||||
│ │ │ ├── execution.ts # 执行记录 Store
|
||||
│ │ │ └── modelConfig.ts # 模型配置 Store
|
||||
│ │ ├── views/ # 页面视图组件
|
||||
│ │ │ ├── Login.vue # 登录页
|
||||
│ │ │ ├── Home.vue # 首页
|
||||
│ │ │ ├── MainConsole.vue # 主控制台
|
||||
│ │ │ ├── WorkflowDesigner.vue # 工作流设计器
|
||||
│ │ │ ├── Agents.vue # Agent 管理
|
||||
│ │ │ ├── Executions.vue # 执行记录列表
|
||||
│ │ │ ├── ExecutionDetail.vue # 执行详情
|
||||
│ │ │ ├── ExecutionBoard.vue # 执行看板
|
||||
│ │ │ ├── DataSources.vue # 数据源管理
|
||||
│ │ │ ├── ModelConfigs.vue # 模型配置管理
|
||||
│ │ │ ├── TemplateMarket.vue # 模板市场
|
||||
│ │ │ ├── NodeTemplates.vue # 节点模板
|
||||
│ │ │ ├── Monitoring.vue # 监控面板
|
||||
│ │ │ ├── AlertRules.vue # 告警规则
|
||||
│ │ │ └── PermissionManagement.vue # 权限管理
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── MainLayout.vue # 主布局组件
|
||||
│ │ │ ├── AgentChatPreview.vue # Agent 聊天预览
|
||||
│ │ │ └── WorkflowEditor/ # 工作流编辑器核心组件
|
||||
│ │ │ ├── WorkflowEditor.vue # 编辑器主组件
|
||||
│ │ │ ├── NodeTypes.ts # 自定义节点类型定义
|
||||
│ │ │ └── NodeExecutionDetail.vue # 节点执行详情弹窗
|
||||
│ │ ├── types/index.ts # TypeScript 类型定义
|
||||
│ │ └── main.ts # 应用入口
|
||||
│ ├── vite.config.ts # Vite 构建配置
|
||||
│ └── package.json
|
||||
│
|
||||
├── backend/ # Python FastAPI 后端
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI 应用入口
|
||||
│ │ ├── core/
|
||||
│ │ │ ├── config.py # 配置管理 (Pydantic Settings)
|
||||
│ │ │ ├── database.py # 数据库引擎 + 会话管理
|
||||
│ │ │ ├── celery_app.py # Celery 异步任务应用
|
||||
│ │ │ ├── security.py # 安全/JWT 工具
|
||||
│ │ │ ├── exceptions.py # 自定义异常
|
||||
│ │ │ ├── error_handler.py # 全局异常处理器
|
||||
│ │ │ ├── redis_client.py # Redis 客户端
|
||||
│ │ │ └── tools_bootstrap.py # 内置工具启动注册
|
||||
│ │ ├── models/ # SQLAlchemy 数据模型
|
||||
│ │ │ ├── agent.py # Agent (智能体)
|
||||
│ │ │ ├── workflow.py # Workflow (工作流)
|
||||
│ │ │ ├── workflow_version.py # 工作流版本
|
||||
│ │ │ ├── workflow_template.py # 工作流模板
|
||||
│ │ │ ├── execution.py # 执行记录
|
||||
│ │ │ ├── execution_log.py # 执行日志
|
||||
│ │ │ ├── model_config.py # 模型配置 (加密存储)
|
||||
│ │ │ ├── tool.py # 工具定义
|
||||
│ │ │ ├── user.py # 用户
|
||||
│ │ │ ├── permission.py # 权限
|
||||
│ │ │ ├── alert_rule.py # 告警规则
|
||||
│ │ │ ├── data_source.py # 数据源
|
||||
│ │ │ ├── node_template.py # 节点模板
|
||||
│ │ │ └── persistent_user_memory.py # 持久化用户记忆
|
||||
│ │ ├── api/ # RESTful API 路由
|
||||
│ │ │ ├── auth.py # 用户认证 (JWT)
|
||||
│ │ │ ├── workflows.py # 工作流 CRUD
|
||||
│ │ │ ├── agents.py # Agent CRUD
|
||||
│ │ │ ├── executions.py # 执行管理
|
||||
│ │ │ ├── execution_logs.py # 执行日志
|
||||
│ │ │ ├── tools.py # 工具管理
|
||||
│ │ │ ├── model_configs.py # 模型配置
|
||||
│ │ │ ├── data_sources.py # 数据源
|
||||
│ │ │ ├── uploads.py # 文件上传
|
||||
│ │ │ ├── websocket.py # WebSocket 实时推送
|
||||
│ │ │ ├── webhooks.py # Webhook 接收
|
||||
│ │ │ ├── template_market.py # 模板市场
|
||||
│ │ │ ├── platform_templates.py # 平台模板
|
||||
│ │ │ ├── node_templates.py # 节点模板
|
||||
│ │ │ ├── node_test.py # 节点测试
|
||||
│ │ │ ├── batch_operations.py # 批量操作
|
||||
│ │ │ ├── collaboration.py # 协作
|
||||
│ │ │ ├── permissions.py # 权限管理
|
||||
│ │ │ ├── monitoring.py # 监控
|
||||
│ │ │ ├── alert_rules.py # 告警规则
|
||||
│ │ │ └── batch_operations.py # 批量操作
|
||||
│ │ ├── services/ # 业务逻辑层
|
||||
│ │ │ ├── workflow_engine.py # 工作流执行引擎 (核心)
|
||||
│ │ │ ├── workflow_validator.py # 工作流校验器
|
||||
│ │ │ ├── workflow_templates.py # 工作流模板
|
||||
│ │ │ ├── llm_service.py # LLM 调用服务
|
||||
│ │ │ ├── tool_registry.py # 工具注册表
|
||||
│ │ │ ├── builtin_tools.py # 内置工具实现
|
||||
│ │ │ ├── condition_parser.py # 条件表达式解析
|
||||
│ │ │ ├── data_transformer.py # 数据转换
|
||||
│ │ │ ├── execution_logger.py # 执行日志记录
|
||||
│ │ │ ├── execution_budget.py # 执行预算控制
|
||||
│ │ │ ├── encryption_service.py # 加密服务
|
||||
│ │ │ ├── persistent_memory_service.py # 持久化记忆
|
||||
│ │ │ ├── permission_service.py # 权限检查
|
||||
│ │ │ ├── monitoring_service.py # 监控服务
|
||||
│ │ │ ├── alert_service.py # 告警服务
|
||||
│ │ │ ├── data_source_connector.py # 数据源连接器
|
||||
│ │ │ ├── scene_templates.py # 场景模板
|
||||
│ │ │ └── scenario_dsl.py # 场景 DSL 解析
|
||||
│ │ ├── tasks/ # Celery 异步任务
|
||||
│ │ │ ├── workflow_tasks.py # 工作流执行任务
|
||||
│ │ │ └── agent_tasks.py # Agent 执行任务
|
||||
│ │ ├── websocket/ # WebSocket 管理
|
||||
│ │ │ ├── manager.py # WS 连接管理
|
||||
│ │ │ └── collaboration_manager.py # 协作 WS 管理
|
||||
│ │ └── utils/ # 工具函数
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── scripts/ # 脚本工具
|
||||
│ └── requirements.txt
|
||||
│
|
||||
├── docker-compose.dev.yml # Docker 开发环境配置
|
||||
├── start_windows.cmd / .ps1 # Windows 启动脚本
|
||||
├── start.sh / stop.sh # Linux 启动/停止脚本
|
||||
└── *.md # 项目文档/方案/报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 前端架构
|
||||
|
||||
### 3.1 技术栈
|
||||
|
||||
| 组件 | 技术选型 | 用途 |
|
||||
|------|---------|------|
|
||||
| 框架 | Vue 3 (Composition API) | UI 框架 |
|
||||
| 语言 | TypeScript | 类型安全 |
|
||||
| 构建 | Vite | 开发/构建 |
|
||||
| 状态管理 | Pinia | 全局状态 |
|
||||
| 路由 | Vue Router 4 | 前端路由 |
|
||||
| UI 库 | Element Plus | 组件库 |
|
||||
| 工作流 | Vue Flow | 可视化流程图编辑 |
|
||||
| HTTP | Axios | API 请求 |
|
||||
| WebSocket | 原生 WebSocket | 实时推送 |
|
||||
|
||||
### 3.2 路由设计
|
||||
|
||||
| 路径 | 视图 | 说明 |
|
||||
|------|------|------|
|
||||
| `/login` | Login.vue | 登录页 |
|
||||
| `/` | Home.vue | 首页仪表盘 |
|
||||
| `/console` | MainConsole.vue | 主控制台 |
|
||||
| `/workflow/:id?` | WorkflowDesigner.vue | 工作流编辑器 (创建/编辑) |
|
||||
| `/agents` | Agents.vue | Agent 管理列表 |
|
||||
| `/agents/:id/design` | WorkflowDesigner.vue | Agent 工作流设计 |
|
||||
| `/executions` | Executions.vue | 执行记录列表 |
|
||||
| `/executions/:id` | ExecutionDetail.vue | 执行详情 |
|
||||
| `/execution-board` | ExecutionBoard.vue | 执行看板 |
|
||||
| `/data-sources` | DataSources.vue | 数据源管理 |
|
||||
| `/model-configs` | ModelConfigs.vue | 模型配置 |
|
||||
| `/template-market` | TemplateMarket.vue | 模板市场 |
|
||||
| `/monitoring` | Monitoring.vue | 监控面板 |
|
||||
| `/alert-rules` | AlertRules.vue | 告警规则 |
|
||||
| `/node-templates` | NodeTemplates.vue | 节点模板 |
|
||||
| `/permissions` | PermissionManagement.vue | 权限管理 (需 admin) |
|
||||
|
||||
路由守卫逻辑：除登录页外均需 JWT 认证，权限页面额外检查 `admin` 角色。
|
||||
|
||||
### 3.3 状态管理 (Pinia Stores)
|
||||
|
||||
- **`user`** — 用户认证、Token 管理、用户信息
|
||||
- **`workflow`** — 工作流列表/详情 CRUD、执行操作
|
||||
- **`agent`** — Agent 列表/详情 CRUD、场景模板创建
|
||||
- **`execution`** — 执行记录跟踪
|
||||
- **`modelConfig`** — 模型配置 (API Key 管理)
|
||||
|
||||
### 3.4 工作流编辑器 (WorkflowEditor)
|
||||
|
||||
可视化拖拽编辑器，基于 **Vue Flow** (Vue 版的 React Flow):
|
||||
|
||||
- 自定义节点类型（通过 `NodeTypes.ts` 中的 `defineComponent` 定义）
|
||||
- 每个节点有执行状态动画（executing/executed/failed 三态指示器）
|
||||
- 支持：开始/LLM/条件/结束/默认 五种预制节点样式
|
||||
- 工具栏：保存、运行、清空、对齐、自动布局、泳道、缩放
|
||||
- 节点属性面板：支持配置 Prompt、模型选择、API Key、变量引用等
|
||||
|
||||
### 3.5 API 通信层
|
||||
|
||||
- Axios 封装 `api/index.ts`
|
||||
- 自动 Token 注入 (请求拦截器)
|
||||
- 统一错误处理 (响应拦截器): 401→重定向登录, 403→权限提示, 404/422/500→友好错误消息
|
||||
- 开发模式通过 Vite 代理将 `/api` 转发到后端 8037 端口
|
||||
- 生产环境自动探测后端地址
|
||||
|
||||
---
|
||||
|
||||
## 4. 后端架构
|
||||
|
||||
### 4.1 技术栈
|
||||
|
||||
| 组件 | 技术选型 | 用途 |
|
||||
|------|---------|------|
|
||||
| 框架 | FastAPI | Web 框架 |
|
||||
| 数据库 ORM | SQLAlchemy + PyMySQL | MySQL 操作 |
|
||||
| 数据库 | MySQL (腾讯云) | 持久化存储 |
|
||||
| 缓存/队列 | Redis | Celery Broker + 缓存 |
|
||||
| 异步任务 | Celery | 工作流/Agent 异步执行 |
|
||||
| AI SDK | OpenAI Python SDK | 大模型调用 |
|
||||
| 迁移 | Alembic | 数据库版本管理 |
|
||||
| 加密 | cryptography (Fernet) | API Key 加密存储 |
|
||||
|
||||
### 4.2 启动流程
|
||||
|
||||
1. FastAPI 应用初始化
|
||||
2. 配置 CORS 中间件
|
||||
3. 注册全局异常处理器
|
||||
4. 注册请求日志中间件
|
||||
5. **`startup` 事件**: 初始化数据库表 + 注册内置工具
|
||||
6. 注册 20 个 API 路由模块
|
||||
|
||||
### 4.3 API 设计
|
||||
|
||||
所有业务 API 以 `/api/v1/` 为前缀，通过 JWT Bearer Token 认证（`get_current_user` 依赖注入）。
|
||||
|
||||
主要路由模块：
|
||||
|
||||
| 模块 | 前缀 | 主要功能 |
|
||||
|------|------|---------|
|
||||
| `auth` | `/api/v1/auth` | 注册、登录、用户信息 |
|
||||
| `workflows` | `/api/v1/workflows` | 工作流 CRUD + 验证 + 模板 + 版本管理 |
|
||||
| `agents` | `/api/v1/agents` | Agent CRUD + 场景模板创建 + 执行 |
|
||||
| `executions` | `/api/v1/executions` | 执行记录 CRUD、启停、恢复 |
|
||||
| `execution_logs` | `/api/v1/execution-logs` | 执行日志查询/统计 |
|
||||
| `tools` | `/api/v1/tools` | 工具注册和查询 |
|
||||
| `model_configs` | `/api/v1/model-configs` | 模型配置管理 (加密存储) |
|
||||
| `data_sources` | `/api/v1/data-sources` | 数据源 CRUD + 连接测试 |
|
||||
| `websocket` | `/api/v1/ws` | WebSocket 实时推送 |
|
||||
| `webhooks` | `/api/v1/webhooks` | 外部 Webhook 接收 |
|
||||
| `template_market` | `/api/v1/template-market` | 模板市场 |
|
||||
| `node_test` | `/api/v1/node-test` | 节点独立测试 |
|
||||
| `monitoring` | `/api/v1/monitoring` | 系统监控 |
|
||||
| `alert_rules` | `/api/v1/alert-rules` | 告警规则 CRUD |
|
||||
| `permissions` | `/api/v1/permissions` | RBAC 权限管理 |
|
||||
| `collaboration` | `/api/v1/collaboration` | 多用户协作 |
|
||||
| `batch_operations` | `/api/v1/batch-operations` | 批量操作 |
|
||||
| `uploads` | `/api/v1/uploads` | 文件上传 |
|
||||
|
||||
### 4.4 数据库模型
|
||||
|
||||
| 表 | 模型 | 说明 |
|
||||
|----|------|------|
|
||||
| `users` | User | 用户账户，含角色字段 |
|
||||
| `workflows` | Workflow | 工作流定义 (nodes+edges JSON) |
|
||||
| `workflow_versions` | WorkflowVersion | 版本历史，支持回滚 |
|
||||
| `workflow_templates` | WorkflowTemplate | 预制工作流模板 |
|
||||
| `agents` | Agent | 智能体定义 (workflow_config JSON) |
|
||||
| `executions` | Execution | 执行记录，支持暂停/恢复 |
|
||||
| `execution_logs` | ExecutionLog | 节点级执行日志 |
|
||||
| `model_configs` | ModelConfig | 模型配置 (API Key 加密) |
|
||||
| `tools` | Tool | 工具定义 |
|
||||
| `data_sources` | DataSource | 外部数据源连接配置 |
|
||||
| `permissions` | Permission | RBAC 权限条目 |
|
||||
| `alert_rules` | AlertRule | 监控告警规则 |
|
||||
| `node_templates` | NodeTemplate | 节点配置模板 |
|
||||
| `persistent_user_memories` | PersistentUserMemory | 跨会话用户记忆 |
|
||||
|
||||
### 4.5 核心服务详解
|
||||
|
||||
#### 4.5.1 工作流执行引擎 (`workflow_engine.py`)
|
||||
|
||||
这是项目最核心的模块，约 5700+ 行代码。核心逻辑：
|
||||
|
||||
**初始化**:
|
||||
- 解析 nodes/edges，按 ID 建立索引
|
||||
- 设置执行预算（步数上限、LLM 调用上限、工具调用上限）
|
||||
|
||||
**执行流程 (`execute` 方法)**:
|
||||
1. 若包含 `scenario_dsl`，先进行 DSL 校验和标准化
|
||||
2. 按**拓扑排序**动态构建执行图
|
||||
3. 每轮循环选择"所有前驱已执行"的下一个节点
|
||||
4. 调用 `execute_node` 执行单个节点
|
||||
5. 根据节点类型处理结果（条件分支裁剪、循环控制等）
|
||||
6. 遇到审批节点时挂起（`WorkflowPaused` 异常），保存快照
|
||||
7. 支持断点恢复（`resume_snapshot`）
|
||||
|
||||
**执行预算熔断**:
|
||||
- 单执行最大步数 (默认 2000) → 防止死循环
|
||||
- 最大 LLM 调用次数 (默认 200) → 防止失控扣费
|
||||
- 最大工具调用次数 (默认 500) → 防止工具滥用
|
||||
|
||||
**节点输入数据解析**:
|
||||
- 支持 `{{variable}}` 和 `{{variable.path}}` 模板变量
|
||||
- 支持嵌套路径解析（如 `memory.conversation_history`）
|
||||
- 支持 `user_input` 等别名智能映射
|
||||
|
||||
#### 4.5.2 节点类型 (30+ 种)
|
||||
|
||||
| 分类 | 节点类型 | 功能 |
|
||||
|------|---------|------|
|
||||
| 控制流 | `start`, `end/output`, `condition`, `switch`, `merge`, `loop/foreach`, `wait` | 流程编排 |
|
||||
| AI 能力 | `llm`, `template`, `code` | 智能处理 |
|
||||
| 数据 | `data/transform`, `json`, `text`, `csv`, `excel`, `cache`, `vector_db` | 数据操作 |
|
||||
| 存储 | `database/db`, `file/file_operation`, `object_storage`, `pdf`, `image` | 文件/DB 操作 |
|
||||
| 网络 | `http/request`, `webhook`, `oauth` | HTTP 请求 |
|
||||
| 消息 | `email/mail`, `message_queue/mq/rabbitmq/kafka`, `sms` | 消息通知 |
|
||||
| 协同 | `slack`, `dingtalk/dingding`, `wechat_work/wecom` | 办公集成 |
|
||||
| 高级 | `subworkflow/invoke_agent`, `batch`, `validator`, `approval`, `error_handler`, `log`, `schedule/delay/timer` | 高级编排 |
|
||||
|
||||
其中 **LLM 节点**为核心 AI 节点：
|
||||
- 通过 OpenAI 兼容 SDK 调用模型
|
||||
- 支持从 `model_config_id` 加载加密凭据
|
||||
- 支持系统提示词 + 用户提示词模板变量注入
|
||||
- 支持工具调用 (Function Calling)
|
||||
- 支持 DeepSeek DSML 协议解析
|
||||
- 支持多轮对话历史注入
|
||||
- 支持用户画像提取与持久化记忆
|
||||
|
||||
#### 4.5.3 LLM 服务 (`llm_service.py`)
|
||||
|
||||
- 支持 OpenAI / DeepSeek / 自定义 OpenAI 兼容接口
|
||||
- 处理流式响应和工具调用
|
||||
- DeepSeek 特有的 `reasoning_content` 思考链处理
|
||||
- 支持 DSML 协议参数提取和工具调用
|
||||
- 超时重试：可重试的网络错误自动重试
|
||||
|
||||
#### 4.5.4 工具注册表 (`tool_registry.py`)
|
||||
|
||||
- 内置工具（file_read, file_write, system_info, datetime 等）
|
||||
- HTTP 工具（调用外部 API）
|
||||
- 工作流工具（嵌套调用其他工作流）
|
||||
- 支持通过数据库动态加载自定义工具
|
||||
|
||||
#### 4.5.5 模型配置 (`model_config.py`)
|
||||
|
||||
- API Key 使用 Fernet 对称加密存储于数据库
|
||||
- 执行时按需解密注入 LLM 节点
|
||||
- 校验归属：仅创建者可调用（白名单控制）
|
||||
|
||||
### 4.6 Celery 异步架构
|
||||
|
||||
```
|
||||
用户请求 → FastAPI (创建工作流执行记录, status=pending)
|
||||
↓
|
||||
Redis Queue (Celery Broker)
|
||||
↓
|
||||
Celery Worker
|
||||
├── workflow_tasks.py → WorkflowEngine.execute()
|
||||
└── agent_tasks.py → Agent 工作流执行
|
||||
↓
|
||||
实时状态推送 → Redis Pub/Sub → WebSocket → 前端
|
||||
```
|
||||
|
||||
- 每个执行任务在 Celery Worker 中异步运行
|
||||
- 执行进度通过 Redis Pub/Sub 实时推送到前端 WebSocket
|
||||
- 支持任务取消、暂停/恢复
|
||||
|
||||
### 4.7 后端配置 (Settings)
|
||||
|
||||
核心配置项通过环境变量 + `.env` 文件管理（`Pydantic Settings`）：
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `DATABASE_URL` | 腾讯云 MySQL | 数据库连接 |
|
||||
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接 |
|
||||
| `MEMORY_PERSIST_DB_ENABLED` | `True` | 跨会话记忆持久化 |
|
||||
| `LOCAL_FILE_TOOLS_ROOT` | 项目根目录 | 文件工具沙箱 |
|
||||
| `WORKFLOW_MAX_STEPS_PER_RUN` | 2000 | 执行步数上限 |
|
||||
| `WORKFLOW_MAX_LLM_INVOCATIONS_PER_RUN` | 200 | LLM 调用上限 |
|
||||
| `WORKFLOW_MAX_TOOL_CALLS_PER_RUN` | 500 | 工具调用上限 |
|
||||
| `CORS_ORIGINS` | localhost:3000/8038 | CORS 白名单 |
|
||||
| `JWT_SECRET_KEY` | dev-only | JWT 签名密钥 |
|
||||
| `TESSERACT_CMD` | (空) | OCR 引擎路径 (Windows) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据流
|
||||
|
||||
### 5.1 工作流执行完整链路
|
||||
|
||||
```
|
||||
前端拖拽设计 → 保存 Workflow (nodes + edges JSON)
|
||||
↓
|
||||
用户点击"运行" → POST /api/v1/workflows/{id}/execute
|
||||
↓
|
||||
后端创建 Execution 记录 (status=pending)
|
||||
↓
|
||||
Celery 任务入队 → Worker 消费
|
||||
↓
|
||||
WorkflowEngine.execute(input_data)
|
||||
↓
|
||||
拓扑排序构建执行顺序
|
||||
↓
|
||||
循环: 选下一个可执行节点
|
||||
↓
|
||||
execute_node(node, input_data)
|
||||
├── start → 透传输入
|
||||
├── llm/template → 调用 LLM (含工具调用)
|
||||
├── condition → 条件表达式求值 → 分支裁剪
|
||||
├── switch → 多分支路由
|
||||
├── database → SQL 查询/写入
|
||||
├── http → HTTP 请求外部 API
|
||||
├── email → 发送邮件
|
||||
├── code → 沙箱执行 Python 代码
|
||||
└── ... 其他 20+ 类型
|
||||
↓
|
||||
保存节点输出 → 继续下一节点或结束
|
||||
↓
|
||||
更新 Execution 状态 (completed/failed)
|
||||
↓
|
||||
Redis Pub/Sub → WebSocket → 前端实时更新
|
||||
```
|
||||
|
||||
### 5.2 条件节点数据流
|
||||
|
||||
```
|
||||
条件节点收到输入
|
||||
↓
|
||||
condition_parser 解析表达式 (如 {{score}} > 60)
|
||||
↓
|
||||
布尔结果 → true/false 分支
|
||||
↓
|
||||
配置化裁剪: 移除不符合的边
|
||||
↓
|
||||
后续执行不再经过被裁剪的分支
|
||||
```
|
||||
|
||||
### 5.3 审批节点 (HITL)
|
||||
|
||||
```
|
||||
执行到 approval 节点
|
||||
↓
|
||||
检查输入中是否有 __hil_decision
|
||||
↓
|
||||
有 → approved/rejected → 继续执行对应分支
|
||||
无 → 序列化快照 → 抛出 WorkflowPaused
|
||||
↓
|
||||
状态持久化为 awaiting_approval
|
||||
↓
|
||||
用户通过 API 审批 → 恢复执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 部署架构
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Nginx │ (可选, 反向代理)
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Frontend │ │ Backend │ │ Celery │
|
||||
│ Vue 3 App │ │ FastAPI │ │ Worker(s) │
|
||||
│ :8038 │ │ :8037 │ │ │
|
||||
└──────────────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ MySQL │ │ Redis │
|
||||
│ (腾讯云) │ │ (本地/Docker)│
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 安全机制
|
||||
|
||||
- **JWT 认证** — 所有 API 需 Bearer Token（登录页除外）
|
||||
- **模型配置加密** — API Key 使用 Fernet 加密存储，仅创建者可调用
|
||||
- **RBAC 权限** — 支持角色级别的权限控制
|
||||
- **执行预算** — 步数/LLM 调用/工具调用三重熔断
|
||||
- **代码沙箱** — `code` 节点在受限 `builtins` 环境执行（禁止 `open`/`eval`/`__import__`）
|
||||
- **文件沙箱** — 文件操作限制在 `LOCAL_FILE_TOOLS_ROOT` 目录内
|
||||
- **环境变量安全** — 敏感环境变量保护 (provider-managed)
|
||||
|
||||
---
|
||||
|
||||
## 8. 可扩展性
|
||||
|
||||
- **节点类型可扩展** — `execute_node` 方法通过 `elif` 链支持 30+ 类型，新增类型只需添加分支
|
||||
- **工具可注册** — `ToolRegistry` 支持内置/HTTP/工作流三类工具，可从数据库动态加载
|
||||
- **模型可配置** — 通过 `ModelConfig` 可管理任意多组 API Key + 模型，节点运行时按需选择
|
||||
- **提供商标配** — 使用 OpenAI 兼容 SDK，可接入 OpenAI、DeepSeek、Anthropic 等
|
||||
- **模板市场** — 预置工作流模板，支持社区分享
|
||||
245
docs/architecture/可执行的 90 天演进路线图.md
Normal file
245
docs/architecture/可执行的 90 天演进路线图.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 可执行的 90 天演进路线图
|
||||
|
||||
目标：在不推翻现有平台的前提下，演进为“可编排 + 可编程 + 可治理”的企业 Agent 平台。
|
||||
原则：保留现有优势（可视化流程、权限体系、执行日志/审计），做渐进增强。
|
||||
|
||||
---
|
||||
|
||||
## 一、90 天总目标（验收口径）
|
||||
|
||||
- 支持 **Main Agent -> 子 Agent** 的真实委派执行（非占位）。
|
||||
- 支持 **模板化创建场景 Agent**（复制模板 + 参数注入）。
|
||||
- 支持 **治理能力**（预算、审计、告警、人工确认）。
|
||||
- 前端提供可用的 **主控台入口**（路由、执行、追踪）。
|
||||
|
||||
---
|
||||
|
||||
## 二、阶段拆解
|
||||
|
||||
## 阶段 1（Day 1-30）：稳态自动化夯实
|
||||
|
||||
### 1) 子工作流真实执行（最小闭环）
|
||||
|
||||
**目标**
|
||||
- 将 `subworkflow` 从占位实现升级为真实执行能力。
|
||||
|
||||
**代码改动**
|
||||
- `backend/app/services/workflow_engine.py`
|
||||
- 实现 `subworkflow` 节点真实执行：
|
||||
- 读取目标 workflow/agent 配置。
|
||||
- 构造并执行子 `WorkflowEngine`。
|
||||
- 返回结构化 `output/status/error`。
|
||||
- 增加防护参数：`max_subworkflow_depth`（默认 2）。
|
||||
- `backend/app/tasks/workflow_tasks.py`
|
||||
- 透传嵌套执行上下文（`parent_execution_id`、`depth`）。
|
||||
- `backend/app/api/executions.py`
|
||||
- 扩展执行输出，保留父子执行关联字段。
|
||||
|
||||
**验收**
|
||||
- 一个 Agent 可在流程内调用另一个 Agent/Workflow 并拿到结果。
|
||||
- 执行日志可追踪父子链路。
|
||||
|
||||
---
|
||||
|
||||
### 2) 16 号稳定性与模板规范化
|
||||
|
||||
**目标**
|
||||
- 让 Loop 多段执行在生产可稳定运行并可复制。
|
||||
|
||||
**代码/文档改动**
|
||||
- `backend/scripts/create_zhini_kefu_16.py`
|
||||
- 固化 loop 数据路径与 merge 行为。
|
||||
- 支持 2 段/3 段模式开关。
|
||||
- `知你客服16号能力文档.md`
|
||||
- 增加“已知边界、推荐场景、故障排查”章节。
|
||||
- `知你客服15号_循环工作流设计.md`
|
||||
- 增补“跨轮状态传递策略”（文件接力/Cache接力）。
|
||||
|
||||
**验收**
|
||||
- 连续 20 次回归无 `loop_rounds` 空值类错误。
|
||||
- 常见问法稳定返回，不再出现异常回显。
|
||||
|
||||
---
|
||||
|
||||
### 3) 观测与失败重试
|
||||
|
||||
**目标**
|
||||
- 提高运行可观测性与容错能力。
|
||||
|
||||
**代码改动**
|
||||
- `backend/app/services/execution_logger.py`
|
||||
- 增加统一错误码（例如 `SUBFLOW_DEPTH_EXCEEDED`）。
|
||||
- `backend/app/tasks/workflow_tasks.py`
|
||||
- 增加可配置的退避重试（1-2 次）。
|
||||
- `backend/app/api/execution_logs.py`
|
||||
- 增加 parent/child 聚合查询接口。
|
||||
|
||||
**验收**
|
||||
- 失败能定位到“哪一层、哪个节点、哪次子调用”。
|
||||
- 重试行为可追踪可审计。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 2（Day 31-60）：多 Agent 协作
|
||||
|
||||
### 4) Main Agent 路由协议（结构化输出）
|
||||
|
||||
**目标**
|
||||
- 主入口 Agent 负责任务分解与路由决策。
|
||||
|
||||
**代码改动**
|
||||
- 新增：`backend/scripts/create_main_agent.py`
|
||||
- 创建主入口 Agent（仅输出结构化路由结果）。
|
||||
- `backend/app/services/workflow_engine.py`
|
||||
- 增加 `invoke_agent` 节点（推荐）或等价工具调用。
|
||||
- `backend/app/services/tool_registry.py` / `backend/app/services/builtin_tools.py`
|
||||
- 若走工具路线，注册 `invoke_agent` 工具与 schema。
|
||||
|
||||
**验收**
|
||||
- 用户一次输入，主 Agent 完成路由并触发子 Agent 执行。
|
||||
- 子执行结果可被主流程汇总输出。
|
||||
|
||||
---
|
||||
|
||||
### 5) 场景模板库（客服/研发/运维/数据）
|
||||
|
||||
**目标**
|
||||
- 形成可复用模板，降低搭建门槛。
|
||||
|
||||
**代码改动**
|
||||
- 新增目录：`backend/scripts/templates/`
|
||||
- `template_customer_service.py`
|
||||
- `template_dev_codegen.py`
|
||||
- `template_ops_log_analysis.py`
|
||||
- `backend/app/api/agents.py`
|
||||
- 增加“从模板创建 Agent”接口（可选）。
|
||||
- 前端模板入口（视项目结构放到 Agent 创建页对应组件）
|
||||
- 增加模板选择 + 参数表单。
|
||||
|
||||
**验收**
|
||||
- 至少 3 个模板可一键创建并执行。
|
||||
- 模板参数（工具白名单、段数、预算）可配置。
|
||||
|
||||
---
|
||||
|
||||
### 6) Human-in-the-loop（关键动作确认）
|
||||
|
||||
**目标**
|
||||
- 将危险操作纳入审批闭环。
|
||||
|
||||
**代码改动**
|
||||
- `backend/app/services/workflow_engine.py`
|
||||
- 增加 `approval` 节点，或在节点 data 中支持 `requires_approval`。
|
||||
- `backend/app/api/executions.py`
|
||||
- 增加“挂起等待审批 / 审批通过继续执行”接口。
|
||||
- 前端执行页面
|
||||
- 增加审批状态展示与操作入口。
|
||||
|
||||
**验收**
|
||||
- 高风险节点默认挂起，审批通过后继续。
|
||||
- 审批日志可追溯。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3（Day 61-90）：治理与平台化
|
||||
|
||||
### 7) 成本、预算与并发治理
|
||||
|
||||
**目标**
|
||||
- 防止执行失控，支持组织级运营。
|
||||
|
||||
**代码改动**
|
||||
- `backend/app/services/workflow_engine.py`
|
||||
- 增加预算控制：`max_steps`、工具调用上限、token 估算上限。
|
||||
- `backend/app/models/`（新增预算配置模型）
|
||||
- 按租户/项目/Agent 维度配置预算。
|
||||
- `backend/app/api/monitoring.py` / `backend/app/api/alert_rules.py`
|
||||
- 增加预算超限告警与熔断策略。
|
||||
|
||||
**验收**
|
||||
- 可按 Agent 设置预算阈值并生效。
|
||||
- 超限自动终止并记录可读原因。
|
||||
|
||||
---
|
||||
|
||||
### 8) 统一 DSL（场景可编程输入）
|
||||
|
||||
**目标**
|
||||
- 让不同模板复用统一输入契约。
|
||||
|
||||
**代码改动**
|
||||
- 新增：`backend/app/services/scenario_dsl.py`
|
||||
- 定义标准输入：目标、约束、产物、验收标准。
|
||||
- `backend/app/services/workflow_engine.py`
|
||||
- 在入口处做 DSL 校验与标准化映射。
|
||||
- 模板脚本
|
||||
- 全部迁移到 DSL 输入。
|
||||
|
||||
**验收**
|
||||
- 同一输入可驱动多模板运行。
|
||||
- 场景迁移与复用成本显著下降。
|
||||
|
||||
---
|
||||
|
||||
### 9) 主控台（应用商店 + 运行看板）
|
||||
|
||||
**目标**
|
||||
- 降低业务用户使用门槛，强化平台可运营性。
|
||||
|
||||
**前端改动（按现有结构落地）**
|
||||
- 新增页面：
|
||||
- `MainConsole`（主入口）
|
||||
- `TemplateMarket`（模板市场）
|
||||
- `ExecutionBoard`（父子执行链看板）
|
||||
- 新增 API 封装：
|
||||
- 模板创建、子执行追踪、审批操作。
|
||||
|
||||
**验收**
|
||||
- 业务用户流程：选模板 -> 填参数 -> 执行 -> 看结果。
|
||||
- 管理员可查看预算、告警、审计。
|
||||
|
||||
---
|
||||
|
||||
## 三、每周里程碑（12 周）
|
||||
|
||||
- W1-W2：`subworkflow` 真执行 + 深度防护。
|
||||
- W3-W4：日志链路 + 16 号稳定性回归。
|
||||
- W5-W6：Main Agent 路由 + `invoke_agent`。
|
||||
- W7-W8：模板库 + 审批节点。
|
||||
- W9-W10：预算治理 + DSL。
|
||||
- W11-W12：主控台 + UAT + 发布。
|
||||
|
||||
---
|
||||
|
||||
## 四、90 天成功指标（建议）
|
||||
|
||||
- 模板复用率 > 60%。
|
||||
- 核心场景自动化成功率 > 85%。
|
||||
- 平均处理时长下降 >= 30%。
|
||||
- 可审计执行覆盖率 = 100%。
|
||||
- 高风险动作审批覆盖率 = 100%。
|
||||
|
||||
---
|
||||
|
||||
## 五、本周可立刻开工的 3 件事
|
||||
|
||||
1. 完成 `subworkflow` 真执行（`workflow_engine.py`）。
|
||||
2. 定义 Main Agent 的路由 JSON 协议（先后端可消费）。
|
||||
3. 上线 3 个模板脚本（客服/研发/运维）并打通端到端回归。
|
||||
|
||||
---
|
||||
|
||||
## 六、风险与规避
|
||||
|
||||
- 风险：多 Agent 递归调用导致资源爆炸。
|
||||
规避：`max_subworkflow_depth` + `max_steps` + 预算熔断。
|
||||
|
||||
- 风险：模型动态创建 workflow JSON 质量不稳定。
|
||||
规避：优先“模板复制 + 参数注入”，减少从零生成。
|
||||
|
||||
- 风险：工具权限与合规风险。
|
||||
规避：工具白名单、审批节点、审计留痕。
|
||||
|
||||
---
|
||||
|
||||
> 说明：本路线图基于当前仓库已有能力（工作流引擎、Agent API、执行任务、日志与权限）制定，采用“可交付优先”的渐进式演进策略。
|
||||
364
docs/architecture/平台待完善功能清单.md
Normal file
364
docs/architecture/平台待完善功能清单.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Agent平台待完善功能清单
|
||||
|
||||
## 📊 总体状态
|
||||
|
||||
- **核心功能完成度**: 95% ✅
|
||||
- **高级功能完成度**: 30% ⚠️
|
||||
- **生产就绪度**: 40% ⚠️
|
||||
|
||||
---
|
||||
|
||||
## 🔴 高优先级（核心功能完善）
|
||||
|
||||
### 1. 数据库查询工具实现 ⭐⭐⭐ ✅
|
||||
|
||||
**当前状态**: ✅ 已完成
|
||||
|
||||
**已完成功能**:
|
||||
- [x] 实现真实的数据库查询逻辑（支持默认数据库和指定数据源）
|
||||
- [x] SQL注入防护（只允许SELECT查询，检查危险关键字）
|
||||
- [x] 查询结果格式化（JSON格式，包含行数和数据）
|
||||
- [x] 查询超时控制（默认30秒，最大300秒）
|
||||
- [x] 支持通过数据源ID查询外部数据库
|
||||
|
||||
**文件位置**: `backend/app/services/builtin_tools.py` (database_query_tool)
|
||||
|
||||
**实际工作量**: 约4小时
|
||||
|
||||
**测试状态**: ✅ 测试通过
|
||||
|
||||
---
|
||||
|
||||
### 2. 工具调用可视化 ⭐⭐⭐ ✅
|
||||
|
||||
**当前状态**: ✅ 已完成
|
||||
|
||||
**已完成功能**:
|
||||
- [x] 在工作流执行时显示工具调用过程 ✅
|
||||
- [x] 显示工具名称、参数、执行结果 ✅
|
||||
- [x] 显示工具调用状态（成功/失败/请求中）✅
|
||||
- [x] 工具调用日志查看 ✅
|
||||
- [x] 工具调用耗时统计 ✅
|
||||
|
||||
**实际工作量**: 约6小时
|
||||
|
||||
**详细文档**: 参见 `工具调用可视化实现总结.md`
|
||||
|
||||
---
|
||||
|
||||
### 3. 监控和告警前端界面 ⭐⭐⭐
|
||||
|
||||
**当前状态**: 后端API已完成，前端界面缺失
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 系统监控面板
|
||||
- [ ] 系统资源监控（CPU、内存、磁盘）
|
||||
- [ ] 执行统计图表（成功率、执行时间、错误率）
|
||||
- [ ] 实时执行状态看板
|
||||
- [ ] 告警规则管理页面
|
||||
- [ ] 告警规则列表
|
||||
- [ ] 告警规则创建/编辑表单
|
||||
- [ ] 告警规则启用/禁用
|
||||
- [ ] 告警日志页面
|
||||
- [ ] 告警列表和筛选
|
||||
- [ ] 告警详情查看
|
||||
- [ ] 告警通知配置（邮件、Webhook等）
|
||||
|
||||
**后端API状态**: ✅ 已完成
|
||||
- `GET /api/v1/monitoring/overview` - 系统概览
|
||||
- `GET /api/v1/monitoring/statistics` - 执行统计
|
||||
- `GET /api/v1/alert-rules` - 告警规则CRUD
|
||||
- `GET /api/v1/alert-rules/{id}/logs` - 告警日志
|
||||
|
||||
**预计工作量**: 12-16小时
|
||||
|
||||
---
|
||||
|
||||
## 🟡 中优先级（功能增强）
|
||||
|
||||
### 4. 工具动态注册机制 ⭐⭐
|
||||
|
||||
**当前状态**: 部分占位实现
|
||||
|
||||
**需要完成**:
|
||||
- [ ] HTTP工具的动态注册（从数据库加载）
|
||||
- [ ] 工作流工具的动态注册
|
||||
- [ ] 代码执行工具的动态注册
|
||||
- [ ] 工具版本管理
|
||||
- [ ] 工具热更新
|
||||
|
||||
**文件位置**: `backend/app/services/tool_registry.py`
|
||||
|
||||
**预计工作量**: 8-10小时
|
||||
|
||||
---
|
||||
|
||||
### 5. 节点配置页面增强 ⭐⭐ ✅
|
||||
|
||||
**当前状态**: ✅ 已完成（100%）
|
||||
|
||||
**已完成功能**:
|
||||
- [x] 变量自动补全功能（输入 `{{` 时自动提示）✅
|
||||
- [x] 上游节点的实时数据预览 ✅
|
||||
- [x] 缓存命中情况显示 ✅
|
||||
- [x] 场景化配置向导 ✅
|
||||
- [x] 完整的配置模板库（分类、搜索、收藏）✅
|
||||
|
||||
**实际工作量**: 已完成（之前已实现）
|
||||
|
||||
**详细文档**: 参见 `节点配置页面增强功能完成情况.md`
|
||||
|
||||
---
|
||||
|
||||
### 6. Agent快速测试功能 ⭐⭐
|
||||
|
||||
**当前状态**: 需要手动执行工作流测试
|
||||
|
||||
**需要完成**:
|
||||
- [ ] Agent快速测试界面
|
||||
- [ ] 测试结果实时显示
|
||||
- [ ] 测试历史记录
|
||||
- [ ] 测试用例管理
|
||||
- [ ] 批量测试功能
|
||||
|
||||
**预计工作量**: 6-8小时
|
||||
|
||||
---
|
||||
|
||||
### 7. 工作流编辑器优化 ⭐⭐
|
||||
|
||||
**当前状态**: 基础功能完成
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 节点对齐和自动布局
|
||||
- [ ] 工作流模板快速应用
|
||||
- [ ] 节点搜索和筛选
|
||||
- [ ] 工作流版本对比
|
||||
- [ ] 工作流导入/导出优化
|
||||
|
||||
**预计工作量**: 8-10小时
|
||||
|
||||
---
|
||||
|
||||
## 🟢 低优先级（高级功能）
|
||||
|
||||
### 8. 多租户支持 ⭐
|
||||
|
||||
**当前状态**: 未实现
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 租户模型和API
|
||||
- [ ] 租户隔离（数据隔离、资源隔离）
|
||||
- [ ] 租户管理界面
|
||||
- [ ] 资源配额管理
|
||||
- [ ] 租户计费系统
|
||||
|
||||
**预计工作量**: 20-30小时
|
||||
|
||||
---
|
||||
|
||||
### 9. 插件系统 ⭐
|
||||
|
||||
**当前状态**: 未实现
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 插件注册机制
|
||||
- [ ] 自定义节点插件开发框架
|
||||
- [ ] 插件市场（插件上传、下载、评分）
|
||||
- [ ] 插件版本管理
|
||||
- [ ] 插件安全沙箱
|
||||
|
||||
**预计工作量**: 30-40小时
|
||||
|
||||
---
|
||||
|
||||
### 10. 移动端适配 ⭐
|
||||
|
||||
**当前状态**: 未实现
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 响应式布局优化
|
||||
- [ ] 移动端工作流查看（只读）
|
||||
- [ ] 移动端执行状态查看
|
||||
- [ ] 移动端Agent测试
|
||||
|
||||
**预计工作量**: 15-20小时
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术债务和优化
|
||||
|
||||
### 11. 性能优化
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 工作流执行性能优化（并发执行、缓存）
|
||||
- [ ] 前端性能优化（懒加载、虚拟滚动）
|
||||
- [ ] 数据库查询优化（索引、查询优化）
|
||||
- [ ] API响应时间优化
|
||||
- [ ] WebSocket连接优化
|
||||
|
||||
**预计工作量**: 10-15小时
|
||||
|
||||
---
|
||||
|
||||
### 12. 安全加固
|
||||
|
||||
**需要完成**:
|
||||
- [ ] HTTP工具域名白名单
|
||||
- [ ] 文件操作路径验证增强
|
||||
- [ ] SQL注入防护（数据库查询工具）
|
||||
- [ ] XSS防护
|
||||
- [ ] CSRF防护
|
||||
- [ ] API限流
|
||||
- [ ] 敏感信息加密存储
|
||||
|
||||
**预计工作量**: 8-12小时
|
||||
|
||||
---
|
||||
|
||||
### 13. 测试覆盖
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 单元测试覆盖率提升（目标80%+）
|
||||
- [ ] 集成测试完善
|
||||
- [ ] E2E测试（Playwright/Cypress）
|
||||
- [ ] 性能测试
|
||||
- [ ] 安全测试
|
||||
|
||||
**预计工作量**: 20-30小时
|
||||
|
||||
---
|
||||
|
||||
## 🚀 生产环境准备
|
||||
|
||||
### 14. 生产环境配置
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 生产环境Docker配置优化
|
||||
- [ ] Kubernetes部署配置
|
||||
- [ ] 多环境配置管理（dev/staging/prod）
|
||||
- [ ] 配置文件加密
|
||||
- [ ] 环境变量管理
|
||||
- [ ] 密钥管理（Vault等）
|
||||
|
||||
**预计工作量**: 15-20小时
|
||||
|
||||
---
|
||||
|
||||
### 15. 监控和日志
|
||||
|
||||
**需要完成**:
|
||||
- [ ] Prometheus指标收集
|
||||
- [ ] 业务指标（执行数、成功率、耗时）
|
||||
- [ ] 系统指标（CPU、内存、网络）
|
||||
- [ ] Grafana仪表板
|
||||
- [ ] 系统监控仪表板
|
||||
- [ ] 业务监控仪表板
|
||||
- [ ] 日志聚合
|
||||
- [ ] ELK Stack集成
|
||||
- [ ] 日志查询和分析
|
||||
- [ ] 错误追踪
|
||||
- [ ] Sentry集成
|
||||
- [ ] 错误告警和通知
|
||||
|
||||
**预计工作量**: 20-25小时
|
||||
|
||||
---
|
||||
|
||||
### 16. CI/CD
|
||||
|
||||
**需要完成**:
|
||||
- [ ] GitHub Actions配置
|
||||
- [ ] 自动化测试流程
|
||||
- [ ] 自动化构建流程
|
||||
- [ ] 自动化部署流程
|
||||
- [ ] 代码质量检查（Linter、覆盖率）
|
||||
- [ ] 安全扫描
|
||||
|
||||
**预计工作量**: 10-15小时
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档完善
|
||||
|
||||
### 17. 用户文档
|
||||
|
||||
**需要完成**:
|
||||
- [ ] 用户使用手册
|
||||
- [ ] 视频教程
|
||||
- [ ] 常见问题FAQ
|
||||
- [ ] 最佳实践指南
|
||||
|
||||
**预计工作量**: 10-15小时
|
||||
|
||||
---
|
||||
|
||||
### 18. 开发者文档
|
||||
|
||||
**需要完成**:
|
||||
- [ ] API文档完善
|
||||
- [ ] 架构设计文档
|
||||
- [ ] 插件开发指南
|
||||
- [ ] 部署指南
|
||||
- [ ] 贡献指南
|
||||
|
||||
**预计工作量**: 8-12小时
|
||||
|
||||
---
|
||||
|
||||
## 📋 优先级建议
|
||||
|
||||
### 第一阶段（1-2周）：核心功能完善
|
||||
1. ✅ 数据库查询工具实现
|
||||
2. ✅ 工具调用可视化
|
||||
3. ✅ 监控和告警前端界面
|
||||
|
||||
### 第二阶段（2-3周）：功能增强
|
||||
4. ✅ 工具动态注册机制
|
||||
5. ✅ 节点配置页面增强
|
||||
6. ✅ Agent快速测试功能
|
||||
7. ✅ 工作流编辑器优化
|
||||
|
||||
### 第三阶段（3-4周）：技术债务
|
||||
8. ✅ 性能优化
|
||||
9. ✅ 安全加固
|
||||
10. ✅ 测试覆盖
|
||||
|
||||
### 第四阶段（按需）：高级功能
|
||||
11. 多租户支持
|
||||
12. 插件系统
|
||||
13. 移动端适配
|
||||
|
||||
### 第五阶段（生产准备）：部署运维
|
||||
14. 生产环境配置
|
||||
15. 监控和日志
|
||||
16. CI/CD
|
||||
|
||||
---
|
||||
|
||||
## 🎯 当前最紧急的任务
|
||||
|
||||
根据平台当前状态，建议优先完成以下任务：
|
||||
|
||||
1. **数据库查询工具实现** - 工具调用功能的核心缺失
|
||||
2. **监控和告警前端界面** - 后端已完成，前端缺失影响用户体验
|
||||
3. **工具调用可视化** - 提升工具调用的可观测性
|
||||
|
||||
---
|
||||
|
||||
## 📊 工作量估算
|
||||
|
||||
| 优先级 | 任务数 | 预计总工作量 |
|
||||
|--------|--------|--------------|
|
||||
| 高优先级 | 3 | 22-30小时 |
|
||||
| 中优先级 | 4 | 30-38小时 |
|
||||
| 低优先级 | 3 | 65-90小时 |
|
||||
| 技术债务 | 3 | 38-57小时 |
|
||||
| 生产准备 | 3 | 45-60小时 |
|
||||
| 文档 | 2 | 18-27小时 |
|
||||
| **总计** | **18** | **218-302小时** |
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-23
|
||||
**文档版本**: v1.0
|
||||
332
docs/architecture/开发进度.md
Normal file
332
docs/architecture/开发进度.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# 开发进度跟踪
|
||||
|
||||
## ✅ 已完成功能
|
||||
|
||||
### 1. 项目基础架构 ✅
|
||||
- [x] 前后端项目结构搭建
|
||||
- [x] Docker Compose 开发环境配置
|
||||
- [x] 数据库连接配置（MySQL）
|
||||
- [x] 端口配置（前端8038，后端8037）
|
||||
|
||||
### 2. 数据库模型 ✅
|
||||
- [x] 用户表（User）
|
||||
- [x] 工作流表（Workflow）
|
||||
- [x] 智能体表（Agent）
|
||||
- [x] 执行记录表（Execution）
|
||||
- [x] 模型配置表（ModelConfig）
|
||||
|
||||
### 3. 用户认证系统 ✅
|
||||
- [x] 用户注册API
|
||||
- [x] 用户登录API（JWT）
|
||||
- [x] 获取当前用户信息API
|
||||
- [x] 密码加密（bcrypt）
|
||||
- [x] JWT Token生成和验证
|
||||
|
||||
### 4. 工作流API ✅
|
||||
- [x] 获取工作流列表
|
||||
- [x] 创建工作流
|
||||
- [x] 获取工作流详情
|
||||
- [x] 更新工作流
|
||||
- [x] 删除工作流
|
||||
- [x] 执行工作流
|
||||
|
||||
### 5. 工作流执行引擎 ✅
|
||||
- [x] DAG构建和拓扑排序
|
||||
- [x] 节点执行器（支持start、input、llm、condition、transform、output、end）
|
||||
- [x] 数据流管理（节点间数据传递）
|
||||
- [x] Celery异步任务集成
|
||||
- [x] 执行状态管理
|
||||
|
||||
### 6. 执行管理API ✅
|
||||
- [x] 创建执行任务
|
||||
- [x] 获取执行记录列表
|
||||
- [x] 获取执行详情
|
||||
- [x] 获取执行状态（Celery任务状态）
|
||||
|
||||
### 7. 前端基础功能 ✅
|
||||
- [x] 登录/注册页面
|
||||
- [x] 用户状态管理（Pinia）
|
||||
- [x] 工作流状态管理（Pinia）
|
||||
- [x] 路由配置和守卫
|
||||
- [x] API请求封装和拦截器
|
||||
- [x] 工作流列表页面
|
||||
|
||||
### 8. 可视化编辑器 ✅
|
||||
- [x] Vue Flow集成
|
||||
- [x] 节点工具箱（拖拽添加节点）
|
||||
- [x] 节点配置面板
|
||||
- [x] 工作流设计器页面
|
||||
- [x] 节点类型：开始、输入、LLM、条件、转换、输出、结束
|
||||
|
||||
## 🚧 进行中
|
||||
|
||||
### 9. 核心节点实现
|
||||
- [x] LLM节点真实调用（OpenAI集成）✅
|
||||
- [x] 条件节点表达式解析 ✅
|
||||
- [x] 数据转换节点完整实现 ✅
|
||||
|
||||
## 📋 待开发功能
|
||||
|
||||
### 第一阶段 MVP（剩余任务）
|
||||
- [x] OpenAI模型真实集成 ✅
|
||||
- [x] DeepSeek模型集成 ✅
|
||||
- [x] 执行状态实时推送（WebSocket后端）✅
|
||||
- [x] 执行结果展示页面 ✅
|
||||
- [x] 执行状态实时推送（WebSocket前端集成）✅
|
||||
|
||||
### 第二阶段
|
||||
- [x] 工作流验证功能 ✅
|
||||
- [x] 工作流模板功能 ✅
|
||||
- [x] 工作流导入导出功能 ✅
|
||||
- [x] 执行历史优化（分页、筛选、搜索）✅
|
||||
- [x] 工作流列表优化（搜索、筛选、排序）✅
|
||||
- [x] 工作流运行功能（运行对话框、执行参数输入、跳转执行详情）✅
|
||||
- [x] 工作流版本管理（版本保存、版本列表、版本回滚）✅
|
||||
- [x] 执行日志和监控（日志记录、日志查询、监控指标）✅
|
||||
- [x] 数据源管理（数据源模型、CRUD API、连接测试、数据查询）✅
|
||||
- [x] 循环节点功能（循环节点实现、工作流引擎集成、前端配置）✅
|
||||
- [x] Agent节点功能（Agent节点实现、工作流引擎集成、前端配置）✅
|
||||
- [x] 错误处理和重试机制 ✅
|
||||
|
||||
### 第三阶段（第一阶段开发）
|
||||
- [x] Agent管理功能（Agent CRUD API、Agent管理页面）✅
|
||||
- [x] 数据源管理前端界面（数据源管理页面）✅
|
||||
- [x] 模型配置管理（ModelConfig CRUD API、模型配置管理页面）✅
|
||||
|
||||
### 第四阶段（更多节点类型）
|
||||
- [x] HTTP请求节点（GET/POST/PUT/DELETE、请求头配置、响应处理）✅
|
||||
- [x] 数据库操作节点（SQL查询、数据插入/更新/删除）✅
|
||||
- [x] 文件操作节点（文件读取、写入、上传/下载）✅
|
||||
|
||||
### 第五阶段（前端功能完善）
|
||||
- [x] 节点删除功能优化（防止删除开始/结束节点）✅
|
||||
- [x] 节点复制/粘贴功能（Ctrl+C/Ctrl+V、Delete删除）✅
|
||||
- [x] 执行结果可视化（JSON树形展示、树形/JSON视图切换）✅
|
||||
- [x] 执行日志实时查看界面（日志列表、筛选、自动刷新、统计信息）✅
|
||||
- [x] 画布缩放和平移优化（鼠标滚轮缩放、拖拽平移、键盘快捷键、缩放控制）✅
|
||||
- [x] 工作流保存提示优化（保存状态提示、自动保存、未保存提示、离开页面提示）✅
|
||||
- [x] 执行性能分析图表（总执行时间、节点性能对比、节点类型统计、执行时间线）✅
|
||||
|
||||
### 第六阶段（更多节点类型）
|
||||
- [x] 定时任务节点（固定延迟、秒/分钟/小时单位、延迟执行）✅
|
||||
- [x] Webhook节点（发送Webhook请求、接收Webhook触发工作流）✅
|
||||
|
||||
### 第七阶段（功能增强）
|
||||
- [x] 邮件节点（SMTP配置、发送邮件、支持HTML、附件）✅
|
||||
- [x] 消息队列节点（RabbitMQ/Kafka集成、发送消息）✅
|
||||
- [x] 工作流模板市场（模板分享、搜索、评分、收藏、前端界面）✅
|
||||
- [x] 批量操作（批量执行、批量导出、批量删除）✅
|
||||
- [x] 工作流协作（实时协作、冲突解决、多人编辑、WebSocket实时同步）✅
|
||||
- [x] 权限管理（RBAC、角色管理、权限分配、工作流/Agent权限控制、API权限检查集成）✅
|
||||
|
||||
## 🔧 技术债务
|
||||
|
||||
- [x] 数据库迁移脚本（Alembic）✅
|
||||
- [x] 单元测试（pytest框架、测试配置、核心功能测试）✅
|
||||
- [x] API文档完善（OpenAPI配置、API描述、完整文档）✅
|
||||
- [x] 错误处理优化 ✅
|
||||
- [x] 前端组件优化和样式完善 ✅
|
||||
|
||||
## 📝 下一步计划（待开发功能）
|
||||
|
||||
### 第八阶段：监控和告警前端界面（中优先级）
|
||||
|
||||
#### 后端状态 ✅
|
||||
- [x] 告警规则API（CRUD、启用/禁用）✅
|
||||
- [x] 告警服务（检查告警、触发告警）✅
|
||||
- [x] 告警日志API ✅
|
||||
|
||||
#### 前端待开发
|
||||
- [ ] 系统监控面板
|
||||
- [ ] 系统资源监控（CPU、内存、磁盘）
|
||||
- [ ] 执行统计图表（成功率、执行时间、错误率）
|
||||
- [ ] 实时执行状态看板
|
||||
- [ ] 告警规则管理页面
|
||||
- [ ] 告警规则列表
|
||||
- [ ] 告警规则创建/编辑表单
|
||||
- [ ] 告警规则启用/禁用
|
||||
- [ ] 告警日志页面
|
||||
- [ ] 告警历史列表
|
||||
- [ ] 告警详情查看
|
||||
- [ ] 告警通知配置（邮件、Webhook等）
|
||||
|
||||
### 第九阶段：用户体验优化（中优先级）
|
||||
|
||||
- [ ] 工作流编辑器优化
|
||||
- [ ] 节点连接线样式优化（已完成左右连接支持）
|
||||
- [ ] 节点对齐和自动布局
|
||||
- [ ] 工作流模板快速应用
|
||||
- [ ] 节点搜索和筛选
|
||||
- [ ] Agent使用体验优化
|
||||
- [ ] Agent快速测试功能
|
||||
- [ ] Agent使用统计和分析
|
||||
- [ ] Agent性能监控
|
||||
- [ ] 移动端适配
|
||||
- [ ] 响应式布局优化
|
||||
- [ ] 移动端工作流查看（只读）
|
||||
- [ ] 移动端执行状态查看
|
||||
|
||||
### 第十阶段：高级功能（低优先级，按需开发）
|
||||
|
||||
#### 多租户支持
|
||||
- [ ] 租户模型和API
|
||||
- [ ] 租户隔离（数据隔离、资源隔离）
|
||||
- [ ] 租户管理界面
|
||||
- [ ] 资源配额管理
|
||||
|
||||
#### 插件系统
|
||||
- [ ] 插件注册机制
|
||||
- [ ] 自定义节点插件开发框架
|
||||
- [ ] 插件市场（插件上传、下载、评分）
|
||||
- [ ] 插件版本管理
|
||||
|
||||
#### 性能优化
|
||||
- [ ] 工作流执行性能优化（并发执行、缓存）
|
||||
- [ ] 前端性能优化（懒加载、虚拟滚动）
|
||||
- [ ] 数据库查询优化（索引、查询优化）
|
||||
- [ ] API响应时间优化
|
||||
|
||||
### 第十一阶段：部署和运维（生产环境准备）
|
||||
|
||||
#### 生产环境配置
|
||||
- [ ] 生产环境Docker配置优化
|
||||
- [ ] Docker Compose生产配置
|
||||
- [ ] 多环境配置管理（dev/staging/prod）
|
||||
- [ ] 配置文件加密
|
||||
- [ ] Kubernetes部署配置
|
||||
- [ ] K8s部署清单（Deployment、Service、Ingress）
|
||||
- [ ] 水平扩展配置
|
||||
- [ ] 健康检查和就绪探针
|
||||
- [ ] 环境变量管理
|
||||
- [ ] 敏感信息管理（密钥管理）
|
||||
- [ ] 配置中心集成
|
||||
|
||||
#### 监控和日志
|
||||
- [ ] Prometheus指标收集
|
||||
- [ ] 业务指标（执行数、成功率、耗时）
|
||||
- [ ] 系统指标（CPU、内存、网络）
|
||||
- [ ] Grafana仪表板
|
||||
- [ ] 系统监控仪表板
|
||||
- [ ] 业务监控仪表板
|
||||
- [ ] 日志聚合
|
||||
- [ ] ELK Stack集成
|
||||
- [ ] 日志查询和分析
|
||||
- [ ] 错误追踪
|
||||
- [ ] Sentry集成
|
||||
- [ ] 错误告警和通知
|
||||
|
||||
#### CI/CD
|
||||
- [ ] GitHub Actions配置
|
||||
- [ ] 自动化测试流程
|
||||
- [ ] 自动化构建流程
|
||||
- [ ] 自动化部署流程
|
||||
- [ ] 代码质量检查
|
||||
- [ ] Linter配置（ESLint、Pylint）
|
||||
- [ ] 代码覆盖率检查
|
||||
- [ ] 安全扫描
|
||||
|
||||
### 第十二阶段：文档和测试完善
|
||||
|
||||
- [ ] 用户文档
|
||||
- [ ] 用户使用手册
|
||||
- [ ] 视频教程
|
||||
- [ ] 常见问题FAQ
|
||||
- [ ] 开发者文档
|
||||
- [ ] API文档完善
|
||||
- [ ] 架构设计文档
|
||||
- [ ] 插件开发指南
|
||||
- [ ] 测试覆盖
|
||||
- [ ] 单元测试覆盖率提升（目标80%+）
|
||||
- [ ] 集成测试完善
|
||||
- [ ] E2E测试（Playwright/Cypress）
|
||||
|
||||
## 🎯 当前状态
|
||||
|
||||
- **后端服务**: ✅ 运行正常（http://localhost:8037）
|
||||
- **前端服务**: ✅ 运行正常（http://localhost:8038）
|
||||
- **数据库**: ✅ 已配置（腾讯云MySQL）
|
||||
- **Redis**: ✅ 运行正常
|
||||
- **Celery**: ✅ 运行正常
|
||||
|
||||
## 📊 完成度
|
||||
|
||||
- **第一阶段MVP**: 100% ✅
|
||||
- **第二阶段核心功能**: 100% ✅
|
||||
- **第三阶段核心功能**: 100% ✅
|
||||
- **第四-七阶段功能**: 100% ✅
|
||||
- **整体项目**: 约 85-90%
|
||||
- 核心功能：100% ✅
|
||||
- 监控告警前端：0% ⚠️
|
||||
- 用户体验优化：60% 🚧
|
||||
- 高级功能（多租户、插件）：0% ⚠️
|
||||
- 部署运维：30% 🚧
|
||||
|
||||
## ✅ 最新测试结果
|
||||
|
||||
- **DeepSeek集成测试**: ✅ 全部通过 (5/5)
|
||||
- 直接API调用 ✅
|
||||
- LLM服务接口 ✅
|
||||
- DeepSeek Coder模型 ✅
|
||||
- 工作流引擎集成 ✅
|
||||
- Prompt模板变量替换 ✅
|
||||
|
||||
## 🎉 已实现的核心功能
|
||||
|
||||
1. **完整的用户认证系统** - 注册、登录、JWT认证
|
||||
2. **工作流CRUD** - 创建、读取、更新、删除工作流
|
||||
3. **工作流执行引擎** - DAG构建、拓扑排序、节点执行
|
||||
4. **可视化编辑器** - 拖拽节点、连线、配置面板
|
||||
5. **异步任务处理** - Celery集成，支持长时间运行的任务
|
||||
|
||||
## 🎯 当前优先级建议
|
||||
|
||||
### 高优先级（建议优先开发）
|
||||
|
||||
1. **监控和告警前端界面** ⭐⭐⭐
|
||||
- 系统监控面板
|
||||
- 告警规则管理页面
|
||||
- 告警日志查看
|
||||
- **预计工作量**: 1-2周
|
||||
|
||||
2. **用户体验优化** ⭐⭐
|
||||
- 工作流编辑器优化（节点对齐、自动布局）
|
||||
- Agent使用体验优化
|
||||
- **预计工作量**: 1-2周
|
||||
|
||||
### 中优先级（按需开发）
|
||||
|
||||
3. **性能优化** ⭐⭐
|
||||
- 工作流执行性能优化
|
||||
- 前端性能优化
|
||||
- **预计工作量**: 1-2周
|
||||
|
||||
4. **生产环境部署配置** ⭐⭐
|
||||
- Docker/K8s配置
|
||||
- 监控和日志集成
|
||||
- **预计工作量**: 2-3周
|
||||
|
||||
### 低优先级（长期规划）
|
||||
|
||||
5. **多租户支持** ⭐
|
||||
- 适用于SaaS场景
|
||||
- **预计工作量**: 3-4周
|
||||
|
||||
6. **插件系统** ⭐
|
||||
- 扩展性增强
|
||||
- **预计工作量**: 4-6周
|
||||
|
||||
## 📈 近期开发建议
|
||||
|
||||
**接下来1-2个月的重点**：
|
||||
1. 完成监控和告警前端界面（让系统可观测）
|
||||
2. 优化用户体验（提升使用体验）
|
||||
3. 完善生产环境部署配置（准备上线）
|
||||
|
||||
**长期规划**（3-6个月）：
|
||||
1. 多租户支持（如需要SaaS模式）
|
||||
2. 插件系统（增强扩展性）
|
||||
3. 性能优化（支持更大规模）
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-20
|
||||
1135
docs/architecture/方案-优化版.md
Normal file
1135
docs/architecture/方案-优化版.md
Normal file
File diff suppressed because it is too large
Load Diff
202
docs/architecture/缺失能力.md
Normal file
202
docs/architecture/缺失能力.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 缺失能力分析
|
||||
|
||||
## 概述
|
||||
|
||||
当前项目已有 34 个内置工具、自主进化系统（agent_create / tool_register / code_tool_create / capability_check / extension_log）、工作流引擎（DAG + HITL 审批节点）、Agent 记忆系统（RAG + 向量 + 持久化）、异步执行（Celery + Redis）等能力。但在生产级复杂任务执行方面，仍存在以下 10 项关键缺失。
|
||||
|
||||
---
|
||||
|
||||
## 第一梯队：复杂任务的硬伤（3 项）
|
||||
|
||||
### 1. 完全没有并行执行
|
||||
|
||||
**现象：**
|
||||
- 工作流 DAG 一次只执行一个节点，即使多个分支之间没有依赖关系
|
||||
- Orchestrator 的 debate 模式 3 个 Agent 逐个串行执行，而非并发
|
||||
- `orchestrator.py` 中 debate 用的是 `for agent in agents` 循环，而非 `asyncio.gather`
|
||||
|
||||
**影响：**
|
||||
- 复杂任务耗时 = 所有步骤耗时之和，而非最长路径耗时
|
||||
- 多 Agent 协作（并行分析、投票）形同虚设
|
||||
- 吞吐量瓶颈
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/services/workflow_engine.py` — DAG 执行循环（`execute()` 方法）
|
||||
- `backend/app/agent_runtime/orchestrator.py` — `_debate()` 方法
|
||||
|
||||
---
|
||||
|
||||
### 2. AgentOrchestrator 不进入工作流
|
||||
|
||||
**现象：**
|
||||
- Orchestrator 的 4 种模式（router / sequential / debate / pipeline）仅通过 API 端点 `/orchestrate` 暴露
|
||||
- 工作流引擎的节点类型只有 `start / llm / agent / approval / condition / end` 等，没有 `orchestrator`
|
||||
- 编排能力与工作流系统完全割裂
|
||||
|
||||
**影响：**
|
||||
- 无法在工作流中组合多 Agent 协作模式
|
||||
- 复杂场景需要外部脚本调用 API，无法在工作流中可视化编排
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/api/agent_chat.py` — Orchestrator API 入口
|
||||
- `backend/app/services/workflow_engine.py` — 缺少 orchestrator 节点类型
|
||||
- `backend/app/agent_runtime/workflow_integration.py` — 只有 `run_agent_node()`，无 `run_orchestrator_node()`
|
||||
|
||||
---
|
||||
|
||||
### 3. 输出质量验证完全缺失
|
||||
|
||||
**现象：**
|
||||
- 没有评判/评估节点检查 Agent 输出质量
|
||||
- 搜索 `evaluate_output`、`verify_result`、`quality_check`、`validate_node` — 零结果
|
||||
- Agent 执行完直接返回结果，不对质量做任何检查
|
||||
- `AgentLearningPattern` 只在后台统计成功率，不做实时检查
|
||||
|
||||
**影响：**
|
||||
- Agent 不知道自己做得好不好
|
||||
- 错误结果直接交付用户
|
||||
- 自我修正闭环缺失最关键的一环
|
||||
|
||||
**涉及文件：**
|
||||
- 无现有实现，需从零构建
|
||||
|
||||
---
|
||||
|
||||
## 第二梯队：生产可靠性（3 项）
|
||||
|
||||
### 4. 节点级自动重试是空壳
|
||||
|
||||
**现象：**
|
||||
- `error_handler` 节点类型存在，但只记录意图不实际重试（代码注释："实际重试需要重新执行前一个节点，这里只记录"）
|
||||
- 一个节点失败 → `WorkflowExecutionError` → 整个工作流停止
|
||||
- Celery 层面有任务级重试（指数退避），但节点级没有
|
||||
|
||||
**影响：**
|
||||
- LLM 调用偶发超时 = 整个工作流失败
|
||||
- 无法配置"这个节点失败后重试 3 次"
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/services/workflow_engine.py` — error_handler 节点（约 4068-4128 行）
|
||||
- `backend/app/tasks/workflow_tasks.py` — Celery 重试逻辑
|
||||
|
||||
---
|
||||
|
||||
### 5. 工具级人工审批缺失
|
||||
|
||||
**现象：**
|
||||
- 人工审批（HITL）只存在于工作流节点层面（`approval` 节点类型）
|
||||
- AgentRuntime 对所有工具自动执行，不暂停确认
|
||||
- `deploy_push`、`send_email`、`database_query`（写操作）、`schedule_create` 等风险工具无二次确认
|
||||
|
||||
**影响：**
|
||||
- Agent 可能执行危险操作而用户不知情
|
||||
- 缺少安全围栏
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/agent_runtime/core.py` — ReAct 循环中工具自动执行
|
||||
- `backend/app/agent_runtime/schemas.py` — `AgentToolConfig` 缺少审批配置
|
||||
- `backend/app/services/workflow_engine.py` — approval 节点（约 1374-1422 行，可复用逻辑）
|
||||
|
||||
---
|
||||
|
||||
### 6. 没有降级/回退链
|
||||
|
||||
**现象：**
|
||||
- 模型不可用 → Agent 直接报错
|
||||
- Agent 执行失败 → 无备选方案
|
||||
- 搜索 `fallback`、`degradation`、`backup` — 零结果
|
||||
|
||||
**影响：**
|
||||
- 单点故障无容错
|
||||
- 无法配置"主模型挂了自动切备用模型"
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/agent_runtime/schemas.py` — `AgentLLMConfig` 无 fallback 字段
|
||||
- `backend/app/agent_runtime/core.py` — ReAct 循环无模型切换逻辑
|
||||
|
||||
---
|
||||
|
||||
## 第三梯队：体验与效率（4 项）
|
||||
|
||||
### 7. 进度上报太粗糙
|
||||
|
||||
**现象：**
|
||||
- WebSocket 只推送 `status: "running"` 和 `status: "completed"`
|
||||
- 进度值固定：0 → 50 → 100，没有实际进度百分比
|
||||
- WebSocket 每 2 秒轮询 DB，而非主动推送
|
||||
|
||||
**影响：**
|
||||
- 用户看不到任务执行到哪一步
|
||||
- 复杂任务（7 步）和简单任务（2 步）进度条一样
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/websocket/manager.py` — WebSocket 管理器（轮询 DB）
|
||||
- `backend/app/services/workflow_engine.py` — 无进度回调钩子
|
||||
- `backend/app/tasks/workflow_tasks.py` — Celery 进度更新只调一次
|
||||
|
||||
---
|
||||
|
||||
### 8. Agent 间知识不共享
|
||||
|
||||
**现象：**
|
||||
- 每个 Agent 的 RAG 记忆按 `(scope_kind, scope_id)` 隔离
|
||||
- 学习模式也按 Scope 隔离
|
||||
- "SQL优化专家"学到的知识，"数据分析师"用不了
|
||||
|
||||
**影响：**
|
||||
- 知识孤岛，重复学习
|
||||
- 自主进化创建的 Agent 从零开始，无法继承父 Agent 经验
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/agent_runtime/memory.py` — 记忆隔离
|
||||
- `backend/app/services/agent_learning_service.py` — 学习模式隔离
|
||||
|
||||
---
|
||||
|
||||
### 9. 没有结果缓存
|
||||
|
||||
**现象：**
|
||||
- 相同查询发给同一 Agent，每次都完整执行 LLM + 工具
|
||||
- 工具结果、LLM 响应均不缓存
|
||||
- 搜索 `cache`、`redis_cache`、`ttl` — 仅在 Celery 配置中有 `result_backend`
|
||||
|
||||
**影响：**
|
||||
- 重复工作浪费 token 和时间
|
||||
- 同一用户反复问相似问题，每次都重新跑
|
||||
|
||||
**涉及文件：**
|
||||
- 无现有实现，需从零构建
|
||||
|
||||
---
|
||||
|
||||
### 10. Agent 独立异步执行是空壳
|
||||
|
||||
**现象：**
|
||||
- `execute_agent_task`（Celery 任务）返回 `{"status": "pending"}` 占位符
|
||||
- 代码注释：`# TODO: 实现Agent执行逻辑`
|
||||
- 非工作流的 Agent 执行没有真正的异步支持（只能同步调用 API）
|
||||
|
||||
**影响：**
|
||||
- Agent 聊天无法异步后台执行
|
||||
- 调度触发的 Agent 执行不会真正运行
|
||||
|
||||
**涉及文件：**
|
||||
- `backend/app/tasks/agent_tasks.py` — execute_agent_task 是空壳
|
||||
- `backend/app/tasks/scheduler_tasks.py` — 定时调度无法真正执行 Agent
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
| # | 缺失能力 | 梯队 | 复杂度 | 影响面 |
|
||||
|---|---------|------|--------|--------|
|
||||
| 1 | 并行执行 | 第一梯队 | 高 | 性能、吞吐量 |
|
||||
| 2 | Orchestrator 入工作流 | 第一梯队 | 中 | 编排能力整合 |
|
||||
| 3 | 输出质量验证 | 第一梯队 | 中 | 结果可靠性 |
|
||||
| 4 | 节点级自动重试 | 第二梯队 | 低 | 稳定性 |
|
||||
| 5 | 工具级人工审批 | 第二梯队 | 中 | 安全性 |
|
||||
| 6 | 降级/回退链 | 第二梯队 | 低 | 容错性 |
|
||||
| 7 | 粒度进度上报 | 第三梯队 | 低 | 用户体验 |
|
||||
| 8 | Agent 知识共享 | 第三梯队 | 高 | 知识利用率 |
|
||||
| 9 | 结果缓存 | 第三梯队 | 中 | 效率、成本 |
|
||||
| 10 | Agent 异步执行 | 第三梯队 | 低 | 调度可用性 |
|
||||
458
docs/architecture/自主AI Agent改造完成情况.md
Normal file
458
docs/architecture/自主AI Agent改造完成情况.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# 自主 AI Agent 改造完成情况
|
||||
|
||||
## 改造目标
|
||||
|
||||
在现有低代码智能体平台基础上，构建真正自主的 AI Agent 运行时（Agent Runtime），使平台从"DAG 工作流引擎"跨越到"支持 ReAct 自主循环的 Agent 平台"。
|
||||
|
||||
**核心原则**：零重构，寄生式复用——不动现有的 5788 行工作流引擎和 9140 行编辑器，全部新增代码独立部署。
|
||||
|
||||
---
|
||||
|
||||
## 已完成改造
|
||||
|
||||
### 新增文件 — 第一轮（22 个）
|
||||
|
||||
| 文件 | 行数 | 用途 |
|
||||
|------|------|------|
|
||||
| `backend/app/agent_runtime/__init__.py` | 45 | 包导出 |
|
||||
| `backend/app/agent_runtime/schemas.py` | 115 | Agent 配置 Schema + AgentStep 执行追踪 + 向量记忆配置 |
|
||||
| `backend/app/agent_runtime/context.py` | 85 | 会话上下文 |
|
||||
| `backend/app/agent_runtime/memory.py` | 200 | 分层记忆管理器 + LLM 自动压缩总结 + 向量记忆检索/保存 |
|
||||
| `backend/app/agent_runtime/tool_manager.py` | 77 | 工具管理器（精简，委托给 ToolRegistry） |
|
||||
| `backend/app/agent_runtime/core.py` | 290 | **AgentRuntime 主循环 + 执行追踪 + LLM 埋点 + 预算控制** |
|
||||
| `backend/app/agent_runtime/orchestrator.py` | 480 | **多 Agent 编排引擎（4 种模式：route / sequential / debate / pipeline）** |
|
||||
| `backend/app/agent_runtime/workflow_integration.py` | 100 | 工作流桥接 |
|
||||
| `backend/app/api/agent_chat.py` | 280 | Agent 聊天 + 多 Agent 编排 + LLM 调用日志 + SSE 流式输出 |
|
||||
| `backend/app/api/agent_monitoring.py` | 55 | **Agent 监控 API（5 个端点）** |
|
||||
| `backend/app/services/agent_monitoring_service.py` | 140 | **Agent 监控服务（5 个统计方法）** |
|
||||
| `backend/app/services/embedding_service.py` | 65 | **Embedding 生成服务（SiliconFlow / OpenAI 适配）** |
|
||||
| `backend/app/services/knowledge_service.py` | 180 | **知识库 RAG 服务（上传 → 解析 → 切片 → 向量化 → 检索）** |
|
||||
| `backend/app/services/document_parser.py` | 135 | **文档解析器（txt/pdf/docx/csv）** |
|
||||
| `backend/app/services/text_chunker.py` | 132 | **文本分块器（段落/句子的语义分块 + overlap）** |
|
||||
| `backend/app/services/tool_registry.py` | 361 | **工具注册表（内置 + HTTP 执行 + 代码沙箱执行）** |
|
||||
| `backend/app/api/tools.py` | 325 | **工具市场 API（CRUD + 测试沙箱 + 分类浏览 + 使用计数）** |
|
||||
| `backend/app/models/agent_llm_log.py` | 30 | **Agent LLM 调用日志模型** |
|
||||
| `backend/app/models/agent_vector_memory.py` | 30 | **Agent 向量记忆表模型** |
|
||||
| `backend/app/models/knowledge_base.py` | 80 | **知识库/文档/文档块三表模型** |
|
||||
| `frontend/src/views/AgentChat.vue` | 370 | Agent 聊天界面 + 多 Agent 编排 UI + SSE 流式渲染 |
|
||||
| `frontend/src/views/AgentDashboard.vue` | 260 | **Agent 监控 Dashboard** |
|
||||
| `scripts/seed_coding_agent.py` | 362 | 编程助手种子脚本（创建 4 个开发者工具 + 代码编程助手 Agent） |
|
||||
| `scripts/seed_agents.py` | 270 | 批量 Agent 种子脚本（创建 4 个常用自主 Agent） |
|
||||
| `scripts/test_coding_agent.py` | 150 | 编程助手自动化测试脚本（4 场景 × 2 端点 = 8 用例） |
|
||||
|
||||
### 新增文件 — 第二轮（2026-05-02 自主学习 + 定时任务 + 飞书集成）
|
||||
|
||||
| 文件 | 行数 | 用途 |
|
||||
|------|------|------|
|
||||
| `backend/app/services/agent_learning_service.py` | 340 | **自主学习服务** — 任务分类、工具序列提取/合并、有效性评分、学习模式注入 |
|
||||
| `backend/app/models/agent_learning_pattern.py` | 25 | Agent 学习模式模型（11 类任务 × 工具序列 × 频率/评分） |
|
||||
| `backend/app/services/agent_schedule_service.py` | 140 | **Agent 定时任务调度服务** — cron 解析、到期触发、执行跟踪 |
|
||||
| `backend/app/models/agent_schedule.py` | 28 | Agent 定时任务调度模型（cron 表达式、启用/禁用、执行记录） |
|
||||
| `backend/app/api/agent_schedules.py` | 200 | Agent 定时任务 CRUD API + 手动触发端点 |
|
||||
| `backend/app/tasks/scheduler_tasks.py` | 27 | Celery Beat 定时检查任务（每分钟扫描到期调度） |
|
||||
| `backend/app/services/notification_service.py` | 128 | 通知系统服务（通知创建、查询、已读标记） |
|
||||
| `backend/app/models/notification.py` | 24 | 通知模型 |
|
||||
| `backend/app/api/notifications.py` | 115 | 通知系统 API |
|
||||
| `backend/app/api/feishu_bind.py` | 243 | 飞书账号绑定/解绑 API（二维码 + 验证码） |
|
||||
| `backend/app/services/feishu_app_service.py` | 199 | 飞书应用消息发送服务 |
|
||||
| `backend/app/services/feishu_notifier.py` | 96 | 飞书通知器（Webhook + 应用消息推送） |
|
||||
| `backend/app/services/feishu_ws_handler.py` | 351 | 飞书 WebSocket 长连接事件监听 |
|
||||
| `backend/app/services/orange_app_service.py` | 137 | 橙子飞书机器人服务 |
|
||||
| `backend/app/services/orange_ws_handler.py` | 298 | 橙子机器人 WebSocket 处理
|
||||
|
||||
### 修改文件 — 第二轮（14 个原文件 + 新增 8 个修改）
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/services/workflow_engine.py` | `execute_node()` 新增 `agent` 节点类型分支（约 50 行）；Agent 节点注入 `budget_limits` + `_on_agent_llm` 预算回调 |
|
||||
| `backend/app/main.py` | 注册 `agent_chat` + `agent_monitoring` + `tools` + `knowledge_base` 路由模块 |
|
||||
| `backend/app/core/database.py` | `init_db` 导入 `agent_llm_log` + `agent_vector_memory` + `knowledge_base` 模型 |
|
||||
| `backend/app/models/__init__.py` | 导出 `AgentLLMLog`、`AgentVectorMemory`、`KnowledgeBase`、`Document`、`DocumentChunk` |
|
||||
| `backend/app/agent_runtime/core.py` | `_LLMClient.chat()` 埋点: timing + token 采集 + `on_completion` 回调；`AgentRuntime` 新增 `on_llm_call` 参数；预算检查移至 LLM 调用前；`on_tool_executed` 重抛 `WorkflowExecutionError` |
|
||||
| `backend/app/agent_runtime/orchestrator.py` | 四种编排模式透传 `on_llm_call` 到子 Agent；新增 Pipeline 模式（Planner → Executor 逐步骤执行 → Reviewer 审查）含 3 个内置系统提示词 + `_pipeline()` 方法 + `_parse_plan()` JSON 解析器 |
|
||||
| `backend/app/api/agent_chat.py` | 三个端点注入 `on_llm_call` 回调，写入 `AgentLLMLog` 表；添加 SSE 流式输出端点 |
|
||||
| `backend/app/agent_runtime/memory.py` | `initialize()` 注入向量记忆到 system prompt；`save_context()` 保存对话后生成 embedding 存入 `AgentVectorMemory` |
|
||||
| `backend/app/agent_runtime/schemas.py` | `AgentMemoryConfig` 新增 `vector_memory_enabled` / `vector_memory_top_k` |
|
||||
| `backend/app/agent_runtime/tool_manager.py` | 精简 `execute()` 直接委托 `tool_registry.execute_tool()` |
|
||||
| `frontend/src/router/index.ts` | 添加 `/agent-chat`、`/agent-chat/:id`、`/agents/:id/config`、`/agent-monitoring` 四条路由 |
|
||||
| `frontend/src/components/MainLayout.vue` | 导航栏添加"Agent对话"+"Agent监控"入口 |
|
||||
| `frontend/src/views/Agents.vue` | Agent 列表添加"配置"按钮跳转 AgentConfig |
|
||||
| `backend/app/services/llm_service.py` | `call_openai_with_tools()` 工具 schema 三路归一化（修复自定义工具缺失 `type` 字段导致 DeepSeek 拒请求） |
|
||||
| `frontend/src/views/AgentChat.vue` | SSE 流式修复：`receivedFirstEvent` 触发条件放宽到任意事件类型；空 think 内容显示"思考中..."；添加 60s AbortController 超时；流式失败自动回退到非流式 POST |
|
||||
|
||||
---
|
||||
|
||||
## 架构设计
|
||||
|
||||
### Agent Runtime 核心循环
|
||||
|
||||
```
|
||||
用户输入
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────┐
|
||||
│ AgentRuntime.run() │
|
||||
│ │
|
||||
│ 1. 加载长期记忆 → 注入 system prompt │
|
||||
│ 2. 追加用户消息 │
|
||||
│ 3. ReAct 循环 (最多 max_iterations 步) │
|
||||
│ ┌──────────────────────────────┐ │
|
||||
│ │ LLM 思考 → 返回文本或工具 │ │
|
||||
│ │ ├── 返回文本 → 跳出循环 │ │
|
||||
│ │ └── 调用工具 → 执行工具 │ │
|
||||
│ │ → 结果追加到消息 │ │
|
||||
│ │ → 回到 LLM 思考 │ │
|
||||
│ └──────────────────────────────┘ │
|
||||
│ 4. 保存长期记忆 │
|
||||
│ 5. 返回 AgentResult │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 复用关系图
|
||||
|
||||
```
|
||||
AgentRuntime (新增)
|
||||
│
|
||||
├── ToolManager ──────→ ToolRegistry + builtin_tools (已有)
|
||||
│ ├── HTTP 工具执行 ─→ httpx.AsyncClient
|
||||
│ └── 代码工具执行 ─→ 沙箱 exec (__builtins__ 禁用)
|
||||
│
|
||||
├── Memory ───────────→ persistent_memory_service (已有)
|
||||
│ ├── MySQL (已有) — 键值记忆
|
||||
│ └── AgentVectorMemory (新增) — 向量记忆语义检索
|
||||
│ └── EmbeddingService ─→ SiliconFlow / OpenAI API
|
||||
│
|
||||
├── _LLMClient ───────→ OpenAI SDK (已有)
|
||||
│ ├── on_completion → AgentLLMLog (新增) → MySQL
|
||||
│ └── AgentBudgetConfig → WorkflowEngine._llm_invocations (预算联动)
|
||||
│
|
||||
├── SSE Stream ───────→ POST .../bare/stream → text/event-stream
|
||||
│ └── AgentStep → 实时推送到前端
|
||||
│
|
||||
├── Context ──────────→ 纯内存，无外部依赖
|
||||
│
|
||||
├── AgentOrchestrator (新增)
|
||||
│ ├── route: Router Agent → Specialist Agent
|
||||
│ ├── sequential: Agent A → Agent B → Agent C
|
||||
│ ├── debate: Agent 独立回答 → Aggregator 汇总
|
||||
│ └── pipeline: Planner 制定计划 → Executor 逐步骤执行 → Reviewer 审查交付
|
||||
│
|
||||
├── KnowledgeBase RAG (新增)
|
||||
│ ├── DocumentParser → txt/pdf/docx/csv/md 解析
|
||||
│ ├── TextChunker → 段落/句子的语义分块 + overlap
|
||||
│ ├── EmbeddingService → 向量化
|
||||
│ └── 余弦相似度检索 → Top-K 上下文注入 system prompt
|
||||
│
|
||||
├── Tool Marketplace API (新增)
|
||||
│ ├── GET /tools + /categories — 市场浏览
|
||||
│ ├── POST /tools — 创建 HTTP/Code 工具
|
||||
│ ├── POST /tools/test/{http,code} — 沙箱测试
|
||||
│ └── POST /tools/{id}/use — 使用计数
|
||||
│
|
||||
└── AgentMonitoring API (新增)
|
||||
├── /overview → 概览统计
|
||||
├── /llm-calls → LLM 调用记录
|
||||
├── /agents-stats → Agent 用量排行
|
||||
├── /tool-usage → 工具调用频次
|
||||
└── /daily-trend → 日趋势图
|
||||
```
|
||||
|
||||
### 新增代码行数统计
|
||||
|
||||
```
|
||||
第一轮（Agent Runtime 核心）:
|
||||
agent_runtime/ → 约 1250 行 Python
|
||||
api/ → 约 660 行 Python
|
||||
services → 约 880 行 Python
|
||||
models → 约 140 行 Python
|
||||
frontend → 约 640 行 Vue/TypeScript
|
||||
修改（非新增） → 约 250 行
|
||||
─────────────────────────────────
|
||||
小计 → 约 3820 行
|
||||
|
||||
第二轮（自主学习 + 定时任务 + 飞书集成）:
|
||||
services → 约 1550 行 Python（学习/调度/通知/飞书/橙子）
|
||||
api → 约 560 行 Python
|
||||
models → 约 80 行 Python
|
||||
tasks → 约 30 行 Python
|
||||
修改（非新增） → 约 40 行
|
||||
─────────────────────────────────
|
||||
小计 → 约 2260 行
|
||||
|
||||
总计新增 → 约 6080 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 整体完成度
|
||||
|
||||
从最初 DAG 工作流引擎 → Agent Runtime → 多 Agent 编排 → Agent 监控 → 自主学习 → 定时任务 → 飞书集成，平台自主 AI Agent 能力已从 **0 → 完整闭环**：
|
||||
- 单 Agent ReAct 循环：✅ 完成
|
||||
- 工具调用与记忆管理：✅ 完成
|
||||
- 执行追踪与记忆压缩：✅ 完成
|
||||
- 配置页面与聊天界面：✅ 完成
|
||||
- SSE 流式输出：✅ 完成（Agent 思考过程实时推送到前端）
|
||||
- 多 Agent 编排（路由/顺序/辩论/流水线）：✅ 完成
|
||||
- 编排前端可视化界面：✅ 完成
|
||||
- LLM 调用埋点与日志：✅ 完成
|
||||
- Agent 监控 Dashboard：✅ 完成
|
||||
- 向量记忆（语义检索）：✅ 完成（Embedding + 余弦相似度 Top-K）
|
||||
- 知识库 RAG：✅ 完成（上传 → 解析 5 种格式 → 切片 → 向量化 → 检索）
|
||||
- 工作流预算接入：✅ 完成（Agent LLM/工具调用计入 WorkflowEngine 全局预算）
|
||||
- 工具市场：✅ 完成（HTTP/Code 工具 CRUD + 沙箱测试 + 市场浏览）
|
||||
- **Agent 自主学习**：✅ 完成（任务分类 → 工具序列提取 → 学习模式注入）
|
||||
- **Agent 定时任务系统**：✅ 完成（cron 表达式 → Celery Beat 到期触发）
|
||||
- **飞书通知与机器人对话**：✅ 完成（通知系统 + 飞书推送 + 橙子机器人）
|
||||
|
||||
**新增工具**：
|
||||
- 种子脚本批量创建 Agent + 开发者工具（代码编程助手 + 4 个自主 Agent + 5 个开发者工具）
|
||||
- 自动化测试脚本（8 用例全部通过，涵盖流式/非流式）
|
||||
- Frontend SSE 流式稳定化（超时保护 + 自动回退）
|
||||
|
||||
**新增编排模式**：
|
||||
- **Pipeline（流水线模式）**：Planner → Executor（逐步骤） → Reviewer
|
||||
- Planner 自动将问题拆解为 2-5 步可执行计划（JSON 格式）
|
||||
- Executor 使用用户提供的 Agent 配置逐步执行
|
||||
- Reviewer 审查所有步骤输出，生产最终答案
|
||||
- 测试通过（Python/JS 对比分析：Planner 生成 5 步计划 → Executor 执行 5 步 → Reviewer 输出 7541 字审查报告）
|
||||
|
||||
**第二轮新增功能**：
|
||||
- **Agent 自主学习**：11 类任务分类 × 工具序列提取/合并 × 有效性评分 × 学习模式注入 system prompt
|
||||
- **Agent 定时任务系统**：cron 表达式 + Celery Beat 每分钟扫描 + 到期自动触发执行
|
||||
- **飞书通知与机器人对话**：通知系统 + 飞书定时推送 + 橙子飞书机器人（独立 WS 连接）
|
||||
|
||||
整体完成度：**100%**（自主 AI Agent 全部能力完整闭环，无未完成核心项目）
|
||||
|
||||
---
|
||||
|
||||
## 关键设计决策
|
||||
|
||||
### 1. 外层 ReAct 控制
|
||||
|
||||
不使用 `llm_service.call_openai_with_tools()` 的内部 ReAct 循环（会导致循环嵌套冲突），而是由 AgentRuntime 自身控制循环，每次仅调一次 LLM，工具执行后自行追加结果到消息列表，再发起下一次 LLM 调用。这样粒度更细，可观察性更强。
|
||||
|
||||
### 2. 寄生式复用
|
||||
|
||||
| 已有能力 | 位置 | 复用方式 |
|
||||
|---------|------|---------|
|
||||
| ToolRegistry + 20+ 内置工具 | `tool_registry.py` + `builtin_tools.py` | 直接调用 `get_tool_function()`/`get_all_tool_schemas()` |
|
||||
| 持久化记忆 | `persistent_memory_service.py` | 直接调用 `load_persistent_memory()`/`save_persistent_memory()` |
|
||||
| OpenAI SDK 调用 | `llm_service.py` | 使用 `AsyncOpenAI` 直接调用（复用 API Key 配置） |
|
||||
| Agent 配置存储 | `models/agent.py` | Agent 聊天 API 通过 DB 查询读取 |
|
||||
|
||||
### 3. 零重构
|
||||
|
||||
工作流引擎 5788 行、编辑器 9140 行——**一行未改结构**，仅在 `execute_node()` 的 if-elif 链末尾新增了一个 `agent` 类型分支（约 50 行）。
|
||||
|
||||
---
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 方式一：工作流内 Agent 节点
|
||||
|
||||
在工作流编辑器中添加 `agent` 类型节点，支持配置：
|
||||
|
||||
```
|
||||
节点配置:
|
||||
system_prompt: "你是一个代码助手，可以帮助用户编写和调试代码。"
|
||||
model: gpt-4o-mini
|
||||
provider: openai
|
||||
max_iterations: 10
|
||||
tools: [file_read, file_write, http_request] # 白名单，默认全部
|
||||
memory: true # 是否启用长期记忆
|
||||
```
|
||||
|
||||
执行时输入数据中的 `query` 或 `input` 字段作为用户问题。
|
||||
|
||||
### 方式二：独立 Agent 对话
|
||||
|
||||
访问 `/agent-chat` 页面，选择一个已有 Agent 开始对话：
|
||||
|
||||
```
|
||||
POST /api/v1/agent-chat/{agent_id}
|
||||
{"message": "帮我写一个Python脚本读取日志文件"}
|
||||
|
||||
→ {
|
||||
"content": "...",
|
||||
"iterations_used": 3,
|
||||
"tool_calls_made": 5,
|
||||
"truncated": false,
|
||||
"session_id": "..."
|
||||
}
|
||||
```
|
||||
|
||||
也可无 Agent 配置直接对话（`POST /api/v1/agent-chat/bare`），使用默认设置。
|
||||
|
||||
### 方式三：Pipeline 流水线编排
|
||||
|
||||
访问 `/agent-chat` 页面切换至"编排"模式，选择"流水线模式"，配置一个执行 Agent 后发送问题。系统自动完成：
|
||||
1. **Planner** 分析问题并生成执行计划（JSON 格式，2-5 步）
|
||||
2. **Executor** 按计划逐步执行，上一步输出作为下一步上下文
|
||||
3. **Reviewer** 审查全部结果，输出最终答案
|
||||
|
||||
API 调用示例：
|
||||
|
||||
```
|
||||
POST /api/v1/agent-chat/orchestrate
|
||||
{
|
||||
"message": "比较复杂的技术问题",
|
||||
"mode": "pipeline",
|
||||
"agents": [{
|
||||
"id": "executor",
|
||||
"name": "分析助手",
|
||||
"system_prompt": "你是一个专业分析助手...",
|
||||
"model": "deepseek-v4-flash",
|
||||
"max_iterations": 10
|
||||
}]
|
||||
}
|
||||
|
||||
→ {
|
||||
"mode": "pipeline",
|
||||
"final_answer": "审查后的最终答案",
|
||||
"steps": [
|
||||
{"agent_name": "Planner", "output": "计划方案"},
|
||||
{"agent_name": "分析助手 (步骤1)", "output": "步骤1结果"},
|
||||
...
|
||||
{"agent_name": "Reviewer", "output": "审查报告"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
适合需要复杂分解 + 质量把关的场景，如技术调研、方案设计、数据分析报告等。
|
||||
|
||||
---
|
||||
|
||||
## 后续计划 — 全部已完成
|
||||
|
||||
### 第一阶段（短期 1-2 周）— 全部完成
|
||||
|
||||
| 项目 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 记忆压缩总结 | ✅ 完成 | LLM 自动总结对话提取用户画像/关键事实/话题，存入长期记忆 |
|
||||
| Agent 配置页面 | ✅ 完成 | 新增 AgentConfig.vue 页面，可视化编辑 System Prompt / 模型 / Temperature / 工具 |
|
||||
| 执行追踪 | ✅ 完成 | 后端返回 steps，前端 AgentChat.vue 可展开显示思考链 |
|
||||
| 多 Agent 编排 | ✅ 完成 | 四种模式：route（路由分发）、sequential（流水线）、debate（独立回答+汇总）、pipeline（规划→执行→审查） |
|
||||
| 编排前端 UI | ✅ 完成 | AgentChat.vue 新增模式切换、Agent 编辑弹窗、步骤展开 |
|
||||
| 预算接入 | ✅ 完成 | Agent 内部 LLM 调用也计入工作流执行预算 |
|
||||
| SSE 流式输出 | ✅ 完成 | 新增 `POST /api/v1/agent-chat/bare/stream` 端点 |
|
||||
|
||||
### 第二阶段（中期 1-2 月）— 全部完成
|
||||
|
||||
| 项目 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 向量记忆 | ✅ 完成 | SiliconFlow Embedding API + 余弦相似度 Top-K 检索 |
|
||||
| Agent Dashboard | ✅ 完成 | LLM 调用追踪、Token 统计、Agent 用量排行、工具调用频次、日趋势图 |
|
||||
| 工具市场 | ✅ 完成 | HTTP/Code 工具 CRUD + 沙箱测试 + 分类浏览 |
|
||||
| 知识库 RAG | ✅ 完成 | 5 种格式解析 → 分块 → 嵌入 → 语义检索 → 上下文注入 |
|
||||
|
||||
### 第三阶段（长期 3-6 月）— 全部完成
|
||||
|
||||
| 项目 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 自主学习 | ✅ 完成 | 11 类任务分类 × 工具序列提取/合并 × 有效性评分 × 学习模式注入 |
|
||||
| 定时任务系统 | ✅ 完成 | cron 表达式 + Celery Beat 每分钟扫描 + 到期自动触发执行 |
|
||||
| 飞书通知与机器人 | ✅ 完成 | 通知系统 + 飞书推送 + 橙子飞书机器人 |
|
||||
| 监控与告警 | ✅ 完成 | Agent 异常检测、通知推送 |
|
||||
|
||||
---
|
||||
|
||||
## 验证清单
|
||||
|
||||
- [x] 全部 Python 文件通过语法检查（`py_compile.compile`）
|
||||
- [x] 工作流引擎 `agent` 节点分支已添加
|
||||
- [x] Agent 聊天 API 路由已注册
|
||||
- [x] 前端路由和导航已配置
|
||||
- [x] Agent Runtime 核心循环实现（ReAct + 工具调用 + 记忆）
|
||||
- [x] `bun run dev` 启动前后端验证
|
||||
- [x] 测试 `POST /api/v1/agent-chat/bare` 返回正常
|
||||
- 使用 DeepSeek 模型，返回了正确的中文问候
|
||||
- 成功调用 `datetime` 工具获取当前时间（2026-05-01 11:23:56）
|
||||
- 成功调用 `system_info` 工具识别 Windows 10.0.26200
|
||||
- ReAct 循环正常（2 次迭代：思考→工具→结果→回答）
|
||||
- [x] 工具 schema 三路归一化修复（`core.py` + `llm_service.py`）
|
||||
- 自定义工具（DB 加载，缺 `type` 字段）→ 添加 `type: "function"`
|
||||
- 标准格式 → 原样通过
|
||||
- 扁平格式（name/parameters/description）→ 正确包装
|
||||
- [x] `load_tools_from_db()` 启动时自动调用（`main.py` startup 事件中）
|
||||
- 20 个自定义工具在重启后仍然可用
|
||||
- [x] 前端 SSE 流式修复（`AgentChat.vue`）
|
||||
- `receivedFirstEvent` 从"仅 think/tool_call/tool_result" 改为"任意事件"触发
|
||||
- 空 think 内容显示"思考中..."占位文本
|
||||
- 60s AbortController 超时保护
|
||||
- 流式失败后自动回退到非流式 POST
|
||||
- [x] 编程助手种子脚本（`seed_coding_agent.py`）
|
||||
- 创建 4 个开发者工具：execute_code、grep_search、list_files、git_log
|
||||
- 创建"代码编程助手"Agent（workflow_config + budget_config）
|
||||
- [x] 批量 Agent 种子脚本（`seed_agents.py`）
|
||||
- 创建 4 个常用自主 Agent：数据分析助手、运维监控助手、网络调试助手、全能助手
|
||||
- 全部已发布（published），可通过前端访问
|
||||
- [x] 编程助手自动化测试全部通过（`test_coding_agent.py`）
|
||||
- 问候场景：非流式 12.6s / 流式 10.3s ✅
|
||||
- 代码场景（素数判断）：非流式 48.3s / 流式 43.6s ✅
|
||||
- 搜索场景（grep_search）：非流式 23.2s / 流式 15.4s ✅
|
||||
- 文件读取场景：✅
|
||||
- [x] 数据分析助手测试通过（计算 1-10 平均值 = 5.5，含表格输出）
|
||||
- [x] Vite 前端开发服务器运行正常（`http://localhost:3002`）
|
||||
- [x] **测试工作流中放置 Agent 节点并执行**
|
||||
- 工作流 `Agent节点测试` (start → agent → end)
|
||||
- Agent 节点使用 `math_calculate` 工具计算 1+2+...+100 = 5050
|
||||
- ReAct 循环正常（2 次迭代：思考→工具→结果→回答）
|
||||
- 执行完成，状态 completed，耗时 7.45 秒
|
||||
- Agent 节点返回 agent_meta: iterations=2, tool_calls=1, truncated=false
|
||||
- [x] 测试 Agent 多轮工具调用
|
||||
- [x] Agent 配置页面（AgentConfig.vue + 路由 + 导航）
|
||||
- [x] 执行追踪（API steps 字段 + 前端思考链展开 UI）
|
||||
- [x] 记忆压缩总结（LLM 自动提取用户画像/关键事实/话题）
|
||||
- [x] 多 Agent 编排 API（`POST /api/v1/agent-chat/orchestrate`）
|
||||
- [x] 三种编排模式端到端测试通过（route / sequential / debate）
|
||||
- [x] **Pipeline 流水线模式端到端测试通过**
|
||||
- 问题："Python 和 JavaScript 的三大区别"
|
||||
- Planner 自动生成 5 步 JSON 执行计划
|
||||
- Executor 逐步骤执行 5 步（类型系统 → 类型系统 → 并发模型 → 生态工具链 → 整合报告）
|
||||
- Reviewer 审查全部执行结果，输出 7541 字质量审查报告
|
||||
- 总计 7 个步骤，全部成功
|
||||
- [x] 编排结果包含 steps 追踪和 agent_results
|
||||
- [x] 前端编排 UI（模式切换 + Agent 编辑弹窗 + 结果展开）
|
||||
- [x] Agent LLM 调用日志模型（`AgentLLMLog` 表创建成功，含 16 个字段）
|
||||
- [x] `_LLMClient.chat()` 埋点（timing + token 采集 + on_completion 回调）
|
||||
- [x] Agent 监控 API 5 个端点注册（overview / llm-calls / agents-stats / tool-usage / daily-trend）
|
||||
- [x] Agent 监控 Dashboard 前端路由和导航配置
|
||||
- [x] `on_llm_call` 回调在 /bare /{agent_id} /orchestrate 三个端点均注入
|
||||
- [x] 编排三种模式透传 `on_llm_call` 到子 AgentRuntime
|
||||
- [x] **SSE 流式输出**：`POST /api/v1/agent-chat/bare/stream` 返回 `text/event-stream`
|
||||
- [x] **向量记忆**：`AgentVectorMemory` 表自动创建；Embedding 生成 + 余弦相似度检索可用
|
||||
- [x] **工作流预算接入**：`AgentRuntime` 内 `AgentBudgetConfig` 限制 LLM/工具调用次数；外部 `on_llm_invocation` 回调同步到 `WorkflowEngine._llm_invocations`
|
||||
- [x] **知识库 RAG**：知识库/文档/文档块三表自动创建；支持 txt/pdf/docx/csv 解析；分块 + Embedding + 语义检索可用
|
||||
- [x] **工具市场**：
|
||||
- [x] `GET /api/v1/tools/categories` — 返回分类列表
|
||||
- [x] `GET /api/v1/tools` — scope/mine/public/all 筛选
|
||||
- [x] `POST /api/v1/tools` — 创建 HTTP 工具（ip_info_test）和代码工具（text_stats_test）
|
||||
- [x] `POST /api/v1/tools/test/http` — HTTP 沙箱测试（httpbin 请求 200/4239ms）
|
||||
- [x] `POST /api/v1/tools/test/code` — 代码沙箱测试（文本统计 0ms）
|
||||
- [x] `POST /api/v1/tools/{id}/use` — 使用计数自增
|
||||
- [x] `DELETE /api/v1/tools/{id}` — 删除自定义工具
|
||||
- [x] **Agent 自主学习**（2026-05-02 新增）
|
||||
- [x] `AgentLearningPattern` 模型（task_type / tool_sequence / frequency / score / keywords）
|
||||
- [x] `agent_learning_service.py` — `extract_pattern()` 从执行中提取工具序列
|
||||
- [x] `agent_learning_service.py` — `merge_pattern()` 合并相似模式（频率自增、评分加权）
|
||||
- [x] `agent_learning_service.py` — `get_relevant_patterns()` 按任务分类检索 Top-K 模式
|
||||
- [x] `agent_learning_service.py` — `inject_learning_hints()` 注入历史模式到 system prompt
|
||||
- [x] 集成到 `AgentRuntime.run()` 和 `run_stream()` —— 执行前注入、执行后保存
|
||||
- [x] 支持 bare chat 和 Agent 模式（通过 `enable_learning` / `learning_mode` 参数控制）
|
||||
- [x] **Agent 定时任务系统**（2026-05-02 新增）
|
||||
- [x] `AgentSchedule` 模型（agent_id / cron_expression / enabled / last_run_at / next_run_at）
|
||||
- [x] `agent_schedule_service.py` — `check_due_schedules()` 扫描到期任务
|
||||
- [x] `agent_schedules.py` API — CRUD + 手动触发 + 启用/禁用
|
||||
- [x] `scheduler_tasks.py` — Celery Beat 每分钟调度任务
|
||||
- [x] 集成到 `celery_app.py`（`app.conf.beat_schedule` 注册 `check-agent-schedules`）
|
||||
- [x] 依赖：`croniter`（cron 表达式解析）
|
||||
- [x] **飞书通知与机器人对话**（2026-05-02 新增）
|
||||
- [x] `Notification` 模型 + `notification_service.py` 通知服务
|
||||
- [x] `notifications.py` API — 通知查询、已读标记
|
||||
- [x] `feishu_bind.py` API — 飞书账号绑定/解绑
|
||||
- [x] `feishu_app_service.py` — 飞书应用消息发送（文本/富文本）
|
||||
- [x] `feishu_notifier.py` — 定时任务结果自动推送飞书
|
||||
- [x] `feishu_ws_handler.py` — 飞书 WebSocket 长连接事件监听（消息/进群/退群）
|
||||
- [x] `orange_app_service.py` — 橙子飞书机器人消息处理
|
||||
- [x] `orange_ws_handler.py` — 橙子机器人独立 WS 连接 + 固定路由到橙子助手 Agent
|
||||
- [x] 执行记录添加 `schedule_id` 字段，用户添加飞书绑定字段
|
||||
429
docs/architecture/解决缺失能力计划.md
Normal file
429
docs/architecture/解决缺失能力计划.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# 解决缺失能力计划
|
||||
|
||||
## 总体策略
|
||||
|
||||
按梯队分阶段实施。每个阶段聚焦 2-3 个能力，完成即可独立提升系统质量。
|
||||
每阶段包含：涉及文件、核心改动、验证方式。
|
||||
|
||||
---
|
||||
|
||||
## 第一阶段：闭环质量（1-2 周）
|
||||
|
||||
优先解决"输出质量验证"，这是连接自主进化系统的最后一环。
|
||||
|
||||
### 1.1 输出质量验证 → 新增 `evaluator` 节点 + `self_review` 工具
|
||||
|
||||
**目标：** Agent 执行完后自动检查输出质量，不达标则自我修正。
|
||||
|
||||
**方案：**
|
||||
|
||||
#### A. 新增 `self_review` 工具（第 35 个内置工具）
|
||||
|
||||
```
|
||||
self_review(content="...", criteria="回答必须包含SQL优化建议和执行计划")
|
||||
→ {
|
||||
"score": 0.75,
|
||||
"passed": true,
|
||||
"issues": ["缺少具体执行计划"],
|
||||
"suggestions": ["补充EXPLAIN输出分析"]
|
||||
}
|
||||
```
|
||||
|
||||
**实现：** 用 LLM 作为评判器（deepseek-v4-flash，轻量调用），根据 criteria 打分 0-1。
|
||||
|
||||
#### B. 新增 `evaluator` 工作流节点类型
|
||||
|
||||
在工作流引擎中添加 evaluator 节点：
|
||||
- 接收上游节点输出 + 评判标准（criteria）
|
||||
- 调用 LLM 评判输出质量
|
||||
- 输出 `{score, passed, issues, suggestions}`
|
||||
- 配合 condition 节点：`passed=false` → 走修正分支 → 重试
|
||||
|
||||
#### C. AgentRuntime 内建 self-review
|
||||
|
||||
在 AgentRuntime ReAct 循环末尾添加可选的 self-review 步骤：
|
||||
- `AgentConfig` 添加 `self_review: bool = False`
|
||||
- 启用后，Agent 在返回最终答案前自动调用 `self_review`
|
||||
- 评分 < 0.6 则追加一轮修正迭代
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/services/builtin_tools.py` | 新增 `self_review_tool` + `SELF_REVIEW_SCHEMA` |
|
||||
| `backend/app/core/tools_bootstrap.py` | 34→35，import + register |
|
||||
| `backend/app/services/workflow_engine.py` | 新增 `evaluator` 节点类型 |
|
||||
| `backend/app/agent_runtime/core.py` | 末尾添加 self-review 步骤 |
|
||||
| `backend/app/agent_runtime/schemas.py` | AgentConfig 添加 `self_review` 字段 |
|
||||
| `frontend/src/utils/agentSkills.ts` | 新增条目 |
|
||||
|
||||
**验证：**
|
||||
1. `self_review("SELECT * FROM t", "需要包含索引建议")` → score < 0.5
|
||||
2. 工作流：agent → evaluator(criteria="...") → condition(passed?) → 正常结束 / 修正重试
|
||||
3. 全能助手对话测试：问一个复杂问题，开启 self_review，确认输出质量提升
|
||||
|
||||
---
|
||||
|
||||
### 1.2 节点级自动重试
|
||||
|
||||
**目标：** error_handler 从空壳变为真正的重试机制。
|
||||
|
||||
**方案：**
|
||||
|
||||
修改 `error_handler` 节点执行逻辑：
|
||||
```
|
||||
当上游节点 status == "failed" 时：
|
||||
1. 检查 retry_count（剩余重试次数）
|
||||
2. 等待 retry_delay 秒
|
||||
3. 重新执行上游节点（复用 get_node_input + execute_node）
|
||||
4. 成功 → 继续流程
|
||||
5. 失败且 retry_count > 0 → 循环
|
||||
6. 失败且 retry_count == 0 → 触发 on_error 动作
|
||||
```
|
||||
|
||||
`on_error` 动作：
|
||||
- `stop`：抛出错误停止工作流
|
||||
- `notify`：发送告警继续
|
||||
- `skip`：跳过该节点继续
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/services/workflow_engine.py` | 重写 error_handler 节点逻辑 |
|
||||
| `backend/app/core/exceptions.py` | 添加 `NodeRetryExhausted` 异常 |
|
||||
|
||||
**验证：**
|
||||
1. 模拟 LLM 超时 → error_handler 重试 3 次 → 第 3 次成功 → 继续
|
||||
2. 模拟连续失败 → error_handler 耗尽重试 → 触发 on_error=notify → 告警记录
|
||||
|
||||
---
|
||||
|
||||
## 第二阶段：编排整合（2-3 周）
|
||||
|
||||
### 2.1 Orchestrator 进入工作流
|
||||
|
||||
**目标：** 4 种编排模式变为工作流节点类型。
|
||||
|
||||
**方案：**
|
||||
|
||||
新增 `orchestrator` 工作流节点类型，数据配置：
|
||||
```json
|
||||
{
|
||||
"mode": "route | sequential | debate | pipeline",
|
||||
"agents": ["agent_id_1", "agent_id_2", ...],
|
||||
"routing_prompt": "用于 route 模式的路由指令",
|
||||
"aggregation_prompt": "用于 debate 模式的汇总指令"
|
||||
}
|
||||
```
|
||||
|
||||
`workflow_integration.py` 添加 `run_orchestrator_node()`：
|
||||
- 解析 node_data 中的 agent 列表
|
||||
- 从 DB 加载 Agent 配置
|
||||
- 创建 AgentOrchestrator 实例
|
||||
- 执行对应模式，返回结构化结果
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/agent_runtime/workflow_integration.py` | 新增 `run_orchestrator_node()` |
|
||||
| `backend/app/services/workflow_engine.py` | 新增 orchestrator 节点类型 |
|
||||
| `frontend/src/utils/agentSkills.ts` | 无需改动（后端节点类型） |
|
||||
|
||||
**验证：**
|
||||
1. 创建工作流：start → orchestrator(debate, [AgentA, AgentB, AgentC]) → end
|
||||
2. 执行：确认 3 个 Agent 均被调用，结果被汇总
|
||||
3. 创建工作流：start → orchestrator(route, [代码助手, 数据分析师]) → end，确认按路由分发
|
||||
|
||||
---
|
||||
|
||||
### 2.2 工具级人工审批
|
||||
|
||||
**目标：** 危险工具执行前暂停等待用户确认。
|
||||
|
||||
**方案：**
|
||||
|
||||
#### A. AgentToolConfig 扩展
|
||||
```python
|
||||
class AgentToolConfig(BaseModel):
|
||||
include_tools: List[str] = []
|
||||
exclude_tools: List[str] = []
|
||||
require_approval: List[str] = [] # 新增：需要审批的工具名列表
|
||||
```
|
||||
|
||||
#### B. AgentRuntime 审批拦截
|
||||
在 ReAct 循环的工具执行环节（`core.py` 约 287 行）：
|
||||
```
|
||||
if tool_name in config.tools.require_approval:
|
||||
yield ApprovalRequest(tool_name, tool_args) # 暂停，等待外部确认
|
||||
decision = await wait_for_approval() # 阻塞等待
|
||||
if decision != "approved":
|
||||
continue # 跳过该工具调用
|
||||
```
|
||||
|
||||
#### C. WebSocket 审批通道
|
||||
- AgentRuntime 暂停时通过 WebSocket 推送审批请求
|
||||
- 用户通过 WebSocket 回复 approve/deny
|
||||
- 超时默认策略可配置（approve/deny/skip）
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/agent_runtime/schemas.py` | AgentToolConfig 添加 require_approval |
|
||||
| `backend/app/agent_runtime/core.py` | 工具执行前审批拦截 |
|
||||
| `backend/app/websocket/manager.py` | 添加审批消息类型 |
|
||||
|
||||
**验证：**
|
||||
1. 配置 Agent: `require_approval: ["deploy_push"]`
|
||||
2. Agent 调用 deploy_push → WebSocket 收到审批请求
|
||||
3. 用户 approve → Agent 继续执行
|
||||
4. 用户 deny → Agent 跳过该工具
|
||||
|
||||
---
|
||||
|
||||
## 第三阶段：性能与效率（2-3 周）
|
||||
|
||||
### 3.1 并行执行
|
||||
|
||||
**目标：** 无依赖节点并行执行，Orchestrator debate 并行。
|
||||
|
||||
**方案：**
|
||||
|
||||
#### A. 工作流 DAG 并行
|
||||
修改 `execute()` 主循环：
|
||||
```
|
||||
当前：每轮取 1 个节点执行
|
||||
改为：每轮取所有"前置节点全部完成"的节点，asyncio.gather 并行执行
|
||||
```
|
||||
|
||||
注意事项：
|
||||
- 并行节点不能有共享状态依赖
|
||||
- 需要分别捕获每个并行节点的异常
|
||||
- WebSocket 需支持多节点同时推送进度
|
||||
|
||||
#### B. Orchestrator debate 并行
|
||||
```python
|
||||
# 改前
|
||||
for agent in agents:
|
||||
result = await agent.run(query)
|
||||
|
||||
# 改后
|
||||
results = await asyncio.gather(*[agent.run(query) for agent in agents])
|
||||
```
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/services/workflow_engine.py` | execute() 并行执行 |
|
||||
| `backend/app/agent_runtime/orchestrator.py` | debate/sequential 并行 |
|
||||
| `backend/app/websocket/manager.py` | 支持多节点并发推送 |
|
||||
|
||||
**验证：**
|
||||
1. 3 个独立分支的 DAG → 总耗时 ≈ 最长分支耗时（而非三者之和）
|
||||
2. debate 模式 3 Agent → 总耗时 ≈ 最慢 Agent 耗时
|
||||
|
||||
---
|
||||
|
||||
### 3.2 粒度进度上报
|
||||
|
||||
**目标：** 实时推送"第 3/7 步完成"到前端。
|
||||
|
||||
**方案：**
|
||||
|
||||
#### A. WorkflowEngine 进度回调
|
||||
在 `execute()` 循环中添加钩子：
|
||||
```python
|
||||
async def on_progress(self, current_step, total_steps, node_name, status):
|
||||
# 推送到 WebSocket
|
||||
await ws_manager.broadcast(execution_id, {
|
||||
"type": "progress",
|
||||
"current": current_step,
|
||||
"total": total_steps,
|
||||
"node": node_name,
|
||||
"status": status,
|
||||
"percent": int(current_step / total_steps * 100),
|
||||
})
|
||||
```
|
||||
|
||||
#### B. 统计 DAG 总步数
|
||||
执行前遍历拓扑排序结果，计算可达节点总数作为 total_steps。
|
||||
|
||||
#### C. WebSocket 改为推送模式
|
||||
当前是轮询 DB，改为 WorkflowEngine 主动调用 WebSocket manager 推送。
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/services/workflow_engine.py` | 添加 on_progress 回调 + 步数统计 |
|
||||
| `backend/app/websocket/manager.py` | 添加 execution 进度推送方法 |
|
||||
| `backend/app/api/websocket.py` | 适配新的推送模式 |
|
||||
|
||||
**验证：**
|
||||
1. 执行 7 节点的 DAG → WebSocket 收到 7 条进度消息
|
||||
2. 前端进度条从 0% 逐步递增到 100%
|
||||
|
||||
---
|
||||
|
||||
### 3.3 结果缓存
|
||||
|
||||
**目标：** 相同输入不重复计算。
|
||||
|
||||
**方案：**
|
||||
|
||||
添加缓存层，使用 Redis：
|
||||
```python
|
||||
# 工具结果缓存
|
||||
cache_key = f"tool:{tool_name}:{hash(json.dumps(args))}"
|
||||
cached = await redis.get(cache_key)
|
||||
if cached:
|
||||
return cached.decode()
|
||||
|
||||
# LLM 响应缓存（相同 prompt + 相同 messages）
|
||||
cache_key = f"llm:{hash(messages_json)}"
|
||||
```
|
||||
|
||||
配置：
|
||||
- TTL 默认 1 小时
|
||||
- 工具维度可选开启/关闭
|
||||
- 确定性工具（file_read、math_calculate）默认开启
|
||||
- 非确定性工具（web_search、http_request）默认关闭
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/agent_runtime/tool_manager.py` | 工具执行前后加缓存层 |
|
||||
| `backend/app/agent_runtime/core.py` | LLM 调用前后加缓存层 |
|
||||
| `backend/app/core/config.py` | 添加缓存配置项 |
|
||||
|
||||
**验证：**
|
||||
1. 连续两次相同 file_read → 第二次命中缓存（耗时 < 1ms）
|
||||
2. 连续两次相同 math_calculate → 第二次命中缓存
|
||||
|
||||
---
|
||||
|
||||
## 第四阶段：容错与共享（2-3 周）
|
||||
|
||||
### 4.1 降级/回退链
|
||||
|
||||
**目标：** 模型/Agent 失败自动切换备用方案。
|
||||
|
||||
**方案：**
|
||||
|
||||
AgentLLMConfig 扩展：
|
||||
```python
|
||||
class AgentLLMConfig(BaseModel):
|
||||
provider: str = "openai"
|
||||
model: str = "gpt-4o-mini"
|
||||
fallback_llm: Optional['AgentLLMConfig'] = None # 降级模型
|
||||
```
|
||||
|
||||
Agent 节点 data 扩展：
|
||||
```json
|
||||
{
|
||||
"fallback_agent": "备选Agent的ID" // 可选
|
||||
}
|
||||
```
|
||||
|
||||
执行逻辑：
|
||||
1. 主模型调用失败 → 切换 fallback_llm 重试
|
||||
2. Agent 执行失败 → 查找 fallback_agent 重试
|
||||
3. 所有备用方案都失败 → 抛出错误
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/agent_runtime/schemas.py` | AgentLLMConfig 添加 fallback_llm |
|
||||
| `backend/app/agent_runtime/core.py` | LLM 调用失败后切换 fallback |
|
||||
| `backend/app/services/workflow_engine.py` | Agent 节点失败后切换 fallback_agent |
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Agent 间知识共享
|
||||
|
||||
**目标：** 打破记忆隔离，Agent 间共享知识。
|
||||
|
||||
**方案：**
|
||||
|
||||
添加全局知识索引层：
|
||||
```
|
||||
每个 Agent 执行完成后 → 提取关键知识 → 写入 global_knowledge 表
|
||||
Agent 初始化时 → 从 global_knowledge 加载相关条目
|
||||
```
|
||||
|
||||
实现：
|
||||
- 新增 `GlobalKnowledge` 模型（content, embedding, source_agent_id, tags, created_at）
|
||||
- `AgentMemory.initialize()` 添加全局知识检索步骤
|
||||
- 自主进化创建的 Agent 自动继承创建者的知识
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/models/agent.py` | 新增 GlobalKnowledge 模型 |
|
||||
| `backend/app/agent_runtime/memory.py` | initialize() 添加全局知识加载 |
|
||||
| `backend/app/agent_runtime/core.py` | 执行完毕提取知识写入全局 |
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Agent 异步执行实现
|
||||
|
||||
**目标：** 填空 `execute_agent_task`，支持真正异步 Agent 执行。
|
||||
|
||||
**方案：**
|
||||
|
||||
`execute_agent_task` 当前是空壳，需要实现：
|
||||
```python
|
||||
@celery_app.task
|
||||
def execute_agent_task(agent_id, query, user_id):
|
||||
db = SessionLocal()
|
||||
agent = db.query(Agent).filter(Agent.id == agent_id).first()
|
||||
config = build_agent_config_from_db(agent)
|
||||
runtime = AgentRuntime(config)
|
||||
result = asyncio.run(runtime.run(query))
|
||||
# 更新 execution 记录
|
||||
return {"status": "completed", "output": result.content}
|
||||
```
|
||||
|
||||
**涉及文件：**
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `backend/app/tasks/agent_tasks.py` | 实现 execute_agent_task |
|
||||
| `backend/app/tasks/scheduler_tasks.py` | 调度触发真正的异步执行 |
|
||||
|
||||
---
|
||||
|
||||
## 实施路线图总览
|
||||
|
||||
```
|
||||
第一阶段（1-2周）
|
||||
├── 1.1 输出质量验证：self_review工具 + evaluator节点 + AgentRuntime自检
|
||||
└── 1.2 节点级自动重试：error_handler从空壳到真正重试
|
||||
|
||||
第二阶段（2-3周）
|
||||
├── 2.1 Orchestrator进入工作流：新增orchestrator节点类型
|
||||
└── 2.2 工具级人工审批：AgentToolConfig审批标记 + WebSocket审批通道
|
||||
|
||||
第三阶段（2-3周）
|
||||
├── 3.1 并行执行：DAG并行 + Orchestrator debate并行
|
||||
├── 3.2 粒度进度上报：on_progress回调 + WebSocket推送
|
||||
└── 3.3 结果缓存：Redis缓存层
|
||||
|
||||
第四阶段（2-3周）
|
||||
├── 4.1 降级/回退链：fallback_llm + fallback_agent
|
||||
├── 4.2 Agent知识共享：GlobalKnowledge + 跨Agent检索
|
||||
└── 4.3 Agent异步执行：填空execute_agent_task
|
||||
```
|
||||
|
||||
## 优先级逻辑
|
||||
|
||||
- **第一阶段优先**：质量验证是自主进化的最后一环，没有它进化无方向；重试是稳定性基础
|
||||
- **第二阶段其次**：编排整合让复杂任务可视化、安全化
|
||||
- **第三阶段提速**：并行 + 缓存大幅提升性能（生产部署前必备）
|
||||
- **第四阶段收尾**：容错和共享让系统长期运行可持续
|
||||
289
docs/architecture/项目完成情况分析.md
Normal file
289
docs/architecture/项目完成情况分析.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 项目完成情况分析
|
||||
|
||||
## 📊 整体完成度
|
||||
|
||||
- **第一阶段MVP**: 100% ✅
|
||||
- **第二阶段核心功能**: 100% ✅
|
||||
- **第三阶段核心功能**: 100% ✅
|
||||
- **整体项目**: 约 95-98%
|
||||
|
||||
## ✅ 已完成的核心功能
|
||||
|
||||
### 后端功能
|
||||
1. ✅ 用户认证系统（注册、登录、JWT）
|
||||
2. ✅ 工作流CRUD API（创建、读取、更新、删除、执行）
|
||||
3. ✅ 工作流版本管理（版本保存、列表、回滚）
|
||||
4. ✅ 工作流模板功能
|
||||
5. ✅ 工作流导入导出
|
||||
6. ✅ 工作流验证功能
|
||||
7. ✅ 执行管理API（创建、查询、状态获取）
|
||||
8. ✅ 执行日志API（日志查询、统计）
|
||||
9. ✅ 数据源管理API（CRUD、连接测试、数据查询）
|
||||
10. ✅ Agent管理API（CRUD、部署/停止）
|
||||
11. ✅ 模型配置管理API（CRUD、测试连接）
|
||||
12. ✅ WebSocket实时推送
|
||||
13. ✅ 工作流执行引擎（支持多种节点类型）
|
||||
14. ✅ 数据库迁移脚本（Alembic）
|
||||
15. ✅ 单元测试框架
|
||||
16. ✅ API文档完善
|
||||
|
||||
### 前端功能
|
||||
1. ✅ 登录/注册页面
|
||||
2. ✅ 工作流列表页面
|
||||
3. ✅ 工作流设计器（可视化编辑器）
|
||||
4. ✅ 执行历史页面
|
||||
5. ✅ 执行详情页面
|
||||
6. ✅ WebSocket实时状态更新
|
||||
7. ✅ Agent管理页面
|
||||
8. ✅ 数据源管理页面
|
||||
9. ✅ 模型配置管理页面
|
||||
10. ✅ 执行日志实时查看界面
|
||||
11. ✅ 执行结果可视化（JSON树形展示）
|
||||
|
||||
### 节点类型
|
||||
1. ✅ 开始节点（start）
|
||||
2. ✅ 输入节点（input）
|
||||
3. ✅ LLM节点（llm）- 支持OpenAI和DeepSeek
|
||||
4. ✅ 条件节点（condition）
|
||||
5. ✅ 转换节点（transform）
|
||||
6. ✅ 循环节点（loop）
|
||||
7. ✅ Agent节点（agent）
|
||||
8. ✅ HTTP请求节点（http_request）
|
||||
9. ✅ 数据库操作节点（database_operation）
|
||||
10. ✅ 文件操作节点（file_operation）
|
||||
11. ✅ 输出节点（output）
|
||||
12. ✅ 结束节点（end）
|
||||
|
||||
## ❌ 未完成的功能
|
||||
|
||||
### 1. Agent管理功能 ✅ 已完成
|
||||
|
||||
#### 后端 ✅
|
||||
- [x] Agent CRUD API
|
||||
- [x] 获取Agent列表
|
||||
- [x] 创建Agent
|
||||
- [x] 获取Agent详情
|
||||
- [x] 更新Agent
|
||||
- [x] 删除Agent
|
||||
- [x] Agent部署/停止
|
||||
|
||||
#### 前端 ✅
|
||||
- [x] Agent管理页面
|
||||
- [x] Agent列表展示
|
||||
- [x] Agent创建/编辑表单
|
||||
- [x] Agent配置界面
|
||||
- [x] Agent工作流配置器（复用WorkflowDesigner）
|
||||
|
||||
**状态**: ✅ 已完成，功能正常使用
|
||||
|
||||
### 2. 模型配置管理功能 ✅ 已完成
|
||||
|
||||
#### 后端 ✅
|
||||
- [x] ModelConfig CRUD API
|
||||
- [x] 获取模型配置列表
|
||||
- [x] 创建模型配置
|
||||
- [x] 更新模型配置
|
||||
- [x] 删除模型配置
|
||||
- [x] 测试模型连接
|
||||
|
||||
#### 前端 ✅
|
||||
- [x] 模型配置管理页面
|
||||
- [x] 模型配置列表
|
||||
- [x] 模型配置表单
|
||||
- [x] API密钥管理界面
|
||||
|
||||
**状态**: ✅ 已完成，功能正常使用
|
||||
|
||||
### 3. 数据源管理前端界面 ✅ 已完成
|
||||
|
||||
#### 后端状态
|
||||
- ✅ 数据源CRUD API已完成
|
||||
- ✅ 连接测试API已完成
|
||||
- ✅ 数据查询API已完成
|
||||
|
||||
#### 前端 ✅
|
||||
- [x] 数据源管理页面
|
||||
- [x] 数据源列表
|
||||
- [x] 数据源创建/编辑表单
|
||||
- [x] 连接测试界面
|
||||
- [x] 数据预览界面
|
||||
|
||||
**状态**: ✅ 已完成，功能正常使用
|
||||
|
||||
### 4. 更多节点类型
|
||||
|
||||
#### 已实现 ✅
|
||||
- ✅ 基础节点（start、input、output、end）
|
||||
- ✅ LLM节点
|
||||
- ✅ 条件节点
|
||||
- ✅ 转换节点
|
||||
- ✅ 循环节点
|
||||
- ✅ Agent节点
|
||||
- ✅ HTTP请求节点 ✅
|
||||
- ✅ GET/POST/PUT/DELETE请求
|
||||
- ✅ 请求头配置
|
||||
- ✅ 响应处理
|
||||
- ✅ 数据库操作节点 ✅
|
||||
- ✅ SQL查询
|
||||
- ✅ 数据插入/更新/删除
|
||||
- ✅ 文件操作节点 ✅
|
||||
- ✅ 文件读取
|
||||
- ✅ 文件写入
|
||||
- ✅ 文件上传/下载
|
||||
|
||||
#### 未实现
|
||||
- [ ] 定时任务节点
|
||||
- [ ] Webhook节点
|
||||
|
||||
**状态**: HTTP请求、数据库操作、文件操作节点已完成，定时任务和Webhook节点待开发
|
||||
|
||||
### 5. 前端功能完善
|
||||
|
||||
#### 工作流设计器
|
||||
- [x] 基础拖拽功能
|
||||
- [x] 节点配置面板
|
||||
- [x] 节点删除功能（已优化，防止删除开始/结束节点）✅
|
||||
- [x] 节点复制/粘贴（Ctrl+C/Ctrl+V）✅
|
||||
- [x] 画布缩放和平移优化 ✅
|
||||
- [x] 工作流保存提示优化 ✅
|
||||
|
||||
#### 执行管理
|
||||
- [x] 执行历史列表
|
||||
- [x] 执行详情页面
|
||||
- [x] 执行结果可视化（JSON树形展示、树形/JSON视图切换）✅
|
||||
- [x] 执行日志实时查看界面（日志列表、筛选、自动刷新）✅
|
||||
- [x] 执行性能分析图表 ✅
|
||||
|
||||
### 6. 高级功能
|
||||
|
||||
#### 多租户支持
|
||||
- [ ] 租户隔离
|
||||
- [ ] 租户管理
|
||||
- [ ] 资源配额管理
|
||||
|
||||
#### 权限管理
|
||||
- [ ] RBAC（基于角色的访问控制）
|
||||
- [ ] 工作流权限管理
|
||||
- [ ] Agent权限管理
|
||||
|
||||
#### 监控和告警
|
||||
- [ ] 系统监控面板
|
||||
- [ ] 执行性能监控
|
||||
- [ ] 告警规则配置
|
||||
- [ ] 告警通知
|
||||
|
||||
#### 插件系统
|
||||
- [ ] 插件注册机制
|
||||
- [ ] 自定义节点插件
|
||||
- [ ] 插件市场
|
||||
|
||||
### 7. 部署和运维
|
||||
|
||||
#### 生产环境配置
|
||||
- [ ] 生产环境Docker配置
|
||||
- [ ] Kubernetes部署配置
|
||||
- [ ] 环境变量管理
|
||||
- [ ] 配置文件加密
|
||||
|
||||
#### 监控和日志
|
||||
- [ ] Prometheus指标收集
|
||||
- [ ] Grafana仪表板
|
||||
- [ ] 日志聚合（ELK Stack）
|
||||
- [ ] 错误追踪（Sentry等）
|
||||
|
||||
#### CI/CD
|
||||
- [ ] GitHub Actions配置
|
||||
- [ ] 自动化测试流程
|
||||
- [ ] 自动化部署流程
|
||||
|
||||
## 📋 优先级建议
|
||||
|
||||
### 高优先级（核心功能缺失）✅ 已完成
|
||||
|
||||
1. **Agent管理功能** ⭐⭐⭐ ✅
|
||||
- 后端：Agent CRUD API ✅
|
||||
- 前端：Agent管理页面 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
2. **数据源管理前端界面** ⭐⭐⭐ ✅
|
||||
- 前端：数据源管理页面 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
3. **模型配置管理** ⭐⭐ ✅
|
||||
- 后端：ModelConfig CRUD API ✅
|
||||
- 前端：模型配置管理页面 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
### 中优先级（功能增强）✅ 已完成
|
||||
|
||||
4. **HTTP请求节点** ⭐⭐ ✅
|
||||
- 后端：HTTP请求节点实现 ✅
|
||||
- 前端：HTTP节点配置面板 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
5. **数据库操作节点** ⭐⭐ ✅
|
||||
- 后端：数据库操作节点实现 ✅
|
||||
- 前端：数据库节点配置面板 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
6. **前端功能完善** ⭐ ✅
|
||||
- 节点删除/复制功能 ✅
|
||||
- 执行结果可视化 ✅
|
||||
- 执行日志实时查看 ✅
|
||||
- **状态**: 已完成
|
||||
|
||||
### 低优先级（高级功能）
|
||||
|
||||
7. **多租户支持**
|
||||
8. **权限管理（RBAC）**
|
||||
9. **监控和告警**
|
||||
10. **插件系统**
|
||||
|
||||
## 🎯 建议的开发顺序
|
||||
|
||||
### 第一阶段：补齐核心功能（1-2周）✅ 已完成
|
||||
1. ✅ Agent管理功能（后端API + 前端界面）
|
||||
2. ✅ 数据源管理前端界面
|
||||
3. ✅ 模型配置管理（后端API + 前端界面）
|
||||
|
||||
### 第二阶段：增强工作流能力（2-3周）✅ 已完成
|
||||
4. ✅ HTTP请求节点
|
||||
5. ✅ 数据库操作节点
|
||||
6. ✅ 文件操作节点
|
||||
|
||||
### 第三阶段：完善用户体验（1-2周）✅ 已完成
|
||||
7. ✅ 前端功能完善
|
||||
8. ✅ 执行结果可视化
|
||||
9. ✅ 执行日志实时查看
|
||||
|
||||
### 第四阶段：继续完善 ✅ 已完成
|
||||
10. ✅ 画布缩放和平移优化
|
||||
11. ✅ 工作流保存提示优化
|
||||
12. ✅ 执行性能分析图表
|
||||
13. ✅ 定时任务节点
|
||||
14. ✅ Webhook节点
|
||||
|
||||
### 第五阶段：高级功能（按需）
|
||||
15. 多租户支持
|
||||
16. 权限管理
|
||||
17. 监控和告警
|
||||
18. 插件系统
|
||||
|
||||
## 📝 总结
|
||||
|
||||
**当前状态**: 项目核心功能已基本完成，可以正常使用。已完成的功能包括：
|
||||
1. ✅ Agent管理功能（后端API + 前端界面）
|
||||
2. ✅ 数据源管理前端界面
|
||||
3. ✅ 模型配置管理（后端API + 前端界面）
|
||||
4. ✅ HTTP请求节点、数据库操作节点、文件操作节点
|
||||
5. ✅ 前端功能完善（节点删除/复制、执行结果可视化、执行日志实时查看）
|
||||
|
||||
**剩余待开发功能**:
|
||||
1. ✅ 画布缩放和平移优化 - 已完成
|
||||
2. ✅ 工作流保存提示优化 - 已完成
|
||||
3. ✅ 执行性能分析图表 - 已完成
|
||||
4. ✅ 定时任务节点 - 已完成
|
||||
5. ✅ Webhook节点 - 已完成
|
||||
6. 高级功能（多租户、权限管理、监控告警、插件系统）- 按需开发
|
||||
|
||||
**建议**: 继续完善用户体验和高级功能，使项目更加完善和易用。
|
||||
Reference in New Issue
Block a user