aiagent/docs/architecture/(红头)项目初始文档.md

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 标准启动（弹窗模式）

cd D:\aaa\aiagent
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1

会打开 4 个 PowerShell 窗口：Redis、API、Celery、前端。

4.2 停止

powershell -ExecutionPolicy Bypass -File .\stop_aiagent.ps1

4.3 仅重启后端+Celery（最常用，改 .env / 依赖 / 工具后）

powershell -ExecutionPolicy Bypass -File .\restart_backend_celery.ps1

4.4 手动应急启动（脚本不可用时）

4 个终端分别执行:

# 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 验证

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