# agent项目
**Repository Path**: hadlooop/simon-agent
## Basic Information
- **Project Name**: agent项目
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-20
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Multi-Agent
基于 FastAPI、LangChain、LangGraph 的多 Agent 服务。Supervisor 根据用户意图在
`research`、`coding`、`writing`、`wechat_writer`、`analyst` 五个专业 Agent 之间路由。
开发环境、代码边界、扩展流程和迁移规范见 [DEVELOPMENT.md](DEVELOPMENT.md)。
## 核心能力
- Supervisor 结构化路由，不依赖关键词硬编码
- Research Agent：Tavily Web 搜索、文件读取
- Coding Agent：代码生成、受限 Python 执行、文件读取、计算器
- Writing Agent：中文与英文写作、改写和润色
- WeChat Writer Agent：微信公众号选题、标题、长文写作和移动端排版
- Analyst Agent：计算器、只读 SQLite 查询
- 短期会话记忆、JSON 长期记忆和轻量向量检索
- OpenAI、Qwen、DeepSeek 兼容模型工厂
- 同步聊天接口、异步任务接口、Agent 路由与信息接口
- 可选 MySQL、Redis 和 Docker Compose 部署
## 软件架构
核心设计思路是：Supervisor 不直接处理具体业务，不调用业务工具，也不生成最终业务答案。
它只判断用户问题属于哪类任务，并分派给对应的专业 Agent；专业 Agent 再按自己的 Prompt 处理
任务，并按需调用统一工具层，最终由所选模型生成结果。
```mermaid
flowchart TB
User[用户] --> API[FastAPI]
API --> ChatService[ChatService]
ChatService --> Supervisor[Supervisor Agent
任务分析 / 路由]
Supervisor --> Research[Research Agent]
Supervisor --> Coding[Coding Agent]
Supervisor --> Writing[Writing Agent]
Supervisor --> WeChatWriter[WeChat Writer Agent]
Supervisor --> Analyst[Analyst Agent]
Research --> Tools[Tools]
Coding --> Tools
Writing --> Tools
WeChatWriter --> Tools
Analyst --> Tools
Tools --> ToolList[Web Search / Database / Calculator
File Reader / Code Executor]
ToolList --> LLM[LLM
DeepSeek / Qwen / OpenAI]
ChatService -.会话与长期记忆.-> Memory[Short / Long / Vector Memory]
Tools -.可选 MCP 适配.-> MCP[MCP Servers]
API -.异步任务.-> Queue[(Redis Queue)]
Queue --> Worker[Task Worker]
Worker --> ChatService
```
Supervisor 路由规则：
| 任务类型 | 路由目标 | 处理范围 |
| --- | --- | --- |
| `research` | `ResearchAgent` | 搜索、资料收集、事实核验和综合 |
| `coding` | `CodingAgent` | 软件开发、代码生成、调试和受限代码执行 |
| `writing` | `WritingAgent` | 写作、改写、编辑和语气调整 |
| `wechat_writer` | `WechatWriterAgent` | 微信公众号选题、标题、长文写作和移动端排版 |
| `analyst` | `AnalystAgent` | 计算、数据查询和定量分析 |
数据库表：
| 表名 | 说明 |
| --- | --- |
| `ai_users` | 用户账号 |
| `ai_tasks` | AI 任务主表 |
| `ai_task_executions` | 任务执行记录 |
| `ai_agents` | Agent 目录 |
| `ai_agent_executions` | Agent 执行记录 |
| `ai_node_executions` | 工作流节点执行记录 |
| `ai_llm_models` | LLM 模型目录 |
| `ai_llm_calls` | LLM 调用明细 |
| `ai_tools` | 工具目录 |
| `ai_tool_calls` | 工具调用明细 |
| `ai_messages` | 任务消息记录 |
字段含义和数据库注释统一维护在 `app/db/models/comments.py`。
MCP 通过 `app/mcp/` 接入外部工具、资源和业务系统。Agent 之间仍由 LangGraph 和 Supervisor
负责编排，MCP 不用于 Agent-to-Agent 路由。
MCP 配置示例：
```dotenv
MCP_ENABLED=true
MCP_SERVERS={"filesystem":{"transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}}
MCP_AGENT_SERVERS={"research":["filesystem"],"coding":["filesystem"],"writing":[],"wechat_writer":[],"analyst":[]}
```
也可以使用 `sse`、`http`、`streamable_http` 或 `websocket` transport。只有
`MCP_AGENT_SERVERS` 中明确授权的 Server 才会暴露给对应 Agent。
## 用户与历史
注册或登录后会签发 JWT，同时写入 `HttpOnly` Cookie。浏览器页面使用 Cookie 认证，
API 客户端仍可使用 `Authorization: Bearer `。登录状态下：
- `/api/v1/chat` 创建的调用会归属当前用户。
- `/agent` 和 `/` 页面只允许登录用户访问。
- `/agent` 页面会加载当前用户的历史任务。
- 点击历史任务可以查看结果，并继续向同一任务发送消息。
- `/api/v1/tasks`、任务详情和 trace 只允许访问当前用户自己的任务。
密码使用带随机盐的 `scrypt` 哈希保存，接口只返回用户公开信息。
请求链路：
1. API 层使用 Pydantic 校验请求，并调用对应 Service。
2. `ChatService` 读取短期历史、长期记忆和向量记忆，构造 LangChain 消息。
3. LangGraph 进入 Supervisor Agent，只返回结构化路由决策，不处理具体业务。
4. 被选中的专业 Agent 使用各自 Prompt 和 Tool 完成任务。
5. 工具结果返回 Agent，并通过统一 LLM 工厂生成最终回答。
6. `finalize` 节点统一输出，聊天历史写回短期和长期记忆。
7. API 返回回答、路由 Agent、路由原因、模型名和工具调用记录。
## 目录结构
```text
.
├── app/
│ ├── main.py # FastAPI 应用工厂、生命周期、路由注册和全局异常处理
│ │
│ ├── api/ # HTTP 接口层，只负责请求校验、调用 Service 和返回响应
│ │ ├── router.py # API 总路由，统一挂载 v1
│ │ └── v1/
│ │ ├── chat.py # 对话、清除会话接口
│ │ ├── agent.py # Agent 列表、Supervisor 路由测试接口
│ │ └── task.py # 异步任务创建和状态查询接口
│ │
│ ├── agents/ # Agent 领域层，定义 Agent 基类、注册中心和专业 Agent
│ │ ├── base.py # Agent 公共构建、执行和结果解析逻辑
│ │ ├── registry.py # Agent 注册、查找和元数据描述
│ │ ├── supervisor/ # Supervisor Agent：任务分析、专业 Agent 路由
│ │ ├── research/ # Research Agent：搜索、资料整理和事实综合
│ │ ├── coding/ # Coding Agent：代码生成、调试和受限代码执行
│ │ ├── writing/ # Writing Agent：写作、改写和语气调整
│ │ ├── wechat_writer/ # Wechat Writer Agent：微信公众号文章写作
│ │ └── analyst/ # Analyst Agent：计算、数据查询和定量分析
│ │
│ ├── workflows/ # LangGraph 多 Agent 工作流
│ │ ├── state.py # 图状态：消息、路由结果、最终答案和工具调用
│ │ ├── nodes.py # Supervisor、专业 Agent、finalize 节点
│ │ └── graph.py # 编译并连接完整 LangGraph 主流程
│ │
│ ├── mcp/ # MCP Server 注册、连接和工具适配
│ │ ├── registry.py # MCP Server 与 Agent 权限映射
│ │ └── client.py # MCP Client 生命周期和工具加载
│ │
│ ├── llm/ # 大模型工厂，统一模型参数和供应商切换
│ │ ├── factory.py # 根据 LLM_PROVIDER 选择具体模型
│ │ ├── openai.py # OpenAI 模型配置
│ │ ├── qwen.py # 通义千问兼容接口配置
│ │ └── deepseek.py # DeepSeek 模型配置
│ │
│ ├── tools/ # LangChain 工具层，供专业 Agent 按需调用
│ │ ├── web_search.py # Tavily Web 搜索
│ │ ├── calculator.py # 安全算术计算
│ │ ├── database.py # 只读 SQLite 查询
│ │ ├── code_executor.py # 默认关闭的受限 Python 执行
│ │ └── file_reader.py # 限制目录范围的文本文件读取
│ │
│ ├── memory/ # 记忆层
│ │ ├── short_term.py # 会话短期记忆，支持内存或 Redis
│ │ ├── long_term.py # JSON 长期记忆
│ │ └── vector.py # 轻量向量相似度检索
│ │
│ ├── models/ # 跨层数据模型
│ │ ├── request.py # Chat、Agent 路由和 Task 请求模型
│ │ ├── response.py # API 响应、任务状态和健康检查模型
│ │ └── message.py # 会话消息、角色和工具调用模型
│ │
│ ├── services/ # 业务编排层，连接 API、工作流、记忆和任务
│ │ ├── chat_service.py # 对话主流程和记忆读写
│ │ ├── agent_service.py # Agent 元数据与单次路由
│ │ ├── task_service.py # 任务持久化、调度和执行协调
│ │ ├── task_queue.py # Redis 可靠任务队列
│ │ ├── readiness.py # 服务和依赖就绪检查
│ │ └── observability/ # trace、回调、序列化和持久化实现
│ ├── repositories/ # 任务等持久化仓储
│ ├── worker.py # 独立 Redis 任务 Worker
│ │
│ ├── config/ # 环境变量和应用配置
│ │ └── settings.py # Pydantic Settings 配置中心
│ │
│ ├── db/ # 数据库基础设施
│ │ ├── mysql.py # SQLAlchemy 异步 MySQL 连接
│ │ ├── redis.py # Redis 异步客户端
│ │ └── models/ # 按表拆分的 SQLAlchemy 持久化模型
│ │
│ └── utils/ # 通用工具
│ ├── logger.py # 日志初始化
│ ├── json_utils.py # JSON 序列化辅助
│ └── token_utils.py # Token 估算
│
├── tests/ # 自动化测试，按主要业务层组织
│ ├── agents/ # Agent 注册中心测试
│ ├── workflows/ # Supervisor 和 Graph 节点测试
│ ├── api/ # FastAPI 接口测试
│ └── tools/ # 工具安全性和行为测试
│
├── prompts/ # 公共 Prompt 资源
│ ├── system/ # 多 Agent 全局系统约束
│ └── templates/ # Supervisor 和各专业 Agent 的提示词模板
│
├── scripts/ # 运维和调试脚本
│ ├── init_db.py # 初始化 MySQL 数据表
│ └── test_agent.py # 调用运行中 Agent 的命令行脚本
│
├── .env # 本地运行配置，不提交敏感内容
├── .env.example # 环境变量模板
├── requirements.txt # pip 运行依赖
├── pyproject.toml # 项目、uv、Pytest 和 Ruff 配置
├── Makefile # 常用开发命令
├── Dockerfile # 应用镜像构建配置
├── docker-compose.yml # FastAPI、MySQL、Redis 编排
├── LICENSE # MIT 开源协议
├── DEVELOPMENT.md # 开发环境、架构边界和扩展流程
└── README.md # 项目说明和接口示例
```
## 开源协议
本项目采用 [MIT License](LICENSE)。
## 快速开始
要求 Python 3.13.8 和 `uv`。项目通过 `.python-version` 固定 Python 版本。
```bash
cp .env.example .env
# 编辑 .env，配置所选模型供应商的 API Key
make install
make migrate
make run
```
默认地址：
- API 文档：http://127.0.0.1:8000/docs
- 任务监控页面：http://127.0.0.1:8000/
- Agent 调用页面：http://127.0.0.1:8000/agent
- 登录注册页面：http://127.0.0.1:8000/login
- 用户注册页面：http://127.0.0.1:8000/register
- 健康检查：http://127.0.0.1:8000/health
- 就绪检查：http://127.0.0.1:8000/ready
- Agent 列表：http://127.0.0.1:8000/api/v1/agents
服务默认监听 `8000` 端口。可通过 `.env` 中的 `APP_PORT` 修改，本地运行和
Docker Compose 会使用同一端口：
```dotenv
APP_PORT=9000
```
## API
同步对话：
```bash
curl -X POST http://127.0.0.1:8000/api/v1/chat \
-H "Content-Type: application/json" \
-d '{"session_id":"demo","message":"计算 (128 + 72) * 3"}'
```
仅测试 Supervisor 路由：
```bash
curl -X POST http://127.0.0.1:8000/api/v1/agents/route \
-H "Content-Type: application/json" \
-d '{"message":"帮我写一篇产品发布公告"}'
```
创建异步任务：
```bash
curl -X POST http://127.0.0.1:8000/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{"message":"分析这份销售数据"}'
```
查询任务：
```bash
curl http://127.0.0.1:8000/api/v1/tasks/
```
清除会话：
```bash
curl -X DELETE http://127.0.0.1:8000/api/v1/chat/sessions/demo
```
## 模型配置
通过 `.env` 中的 `LLM_PROVIDER` 选择实际使用的模型，并填写对应供应商的 API Key。
OpenAI：
```dotenv
LLM_PROVIDER=openai
OPENAI_API_KEY=your-key
OPENAI_MODEL=gpt-4o-mini
```
Qwen：
```dotenv
LLM_PROVIDER=qwen
QWEN_API_KEY=your-key
QWEN_MODEL=qwen-plus
```
DeepSeek：
```dotenv
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-key
DEEPSEEK_MODEL=deepseek-chat
```
## 安全边界
- Python 代码执行默认关闭，仅在 `ALLOW_CODE_EXECUTION=true` 时启用。
- 文件读取被限制在 `FILE_READER_ROOT_PATH` 下。
- SQLite 工具只允许只读 `SELECT` 或 `WITH` 查询。
- `.env`、长期记忆、向量数据和本地数据库目录已加入 `.gitignore`。
## Docker
```bash
make docker-up
```
Compose 会启动迁移任务、FastAPI、独立 Worker、MySQL 和 Redis。迁移服务会先执行 Alembic，
成功后再启动 API 和 Worker。
本地不使用 Docker 时，默认 `TASK_QUEUE_ENABLED=false`，任务在当前 API 进程内执行。需要
Redis 队列模式时设置 `TASK_QUEUE_ENABLED=true`，并额外运行 `make run-worker`。
生产部署前必须替换 Compose 中的默认数据库密码，并根据需要调整端口、认证、限流、日志和监控。
常用 Docker 命令：
```bash
make docker-build # 构建应用镜像
make docker-up-d # 后台启动 FastAPI、MySQL 和 Redis
make docker-logs # 跟踪容器日志
make docker-down # 停止并移除容器
```
## 开发命令
```bash
make test
make lint
make format
make check
make build
make migrate
make init-db
make run-worker
make docker-up
```