# ai-agent-email

**Repository Path**: notperfunctory/ai-agent-email

## Basic Information

- **Project Name**: ai-agent-email
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent Email - 自然语言驱动的分布式定时任务调度系统

## 项目简介

用户通过自然语言描述需求（如"帮我在12点半给xxx@qq.com发送一封主题为XXX的邮件"），Python Agent 负责任务解析与时间推理，Java 后端负责持久化调度与邮件发送。

## 技术栈

| 端      | 技术                                              | 角色        |
| ------- | ------------------------------------------------- | ----------- |
| Python  | FastAPI + LangChain + OpenAI/Qwen API             | 敏态大脑    |
| Java    | Spring Boot 3.x + WebFlux + MyBatis-Plus + XXL-JOB | 稳态核心    |
| 存储    | MySQL                                             | 任务持久化  |
| 调度    | XXL-JOB                                           | 分布式定时  |

## 目录结构

```
ai-agent-email/
├── python-agent/                    # Python 敏态大脑
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py                  # FastAPI 入口
│   │   ├── config.py                # 配置（模型 API Key 等）
│   │   ├── schemas.py               # Pydantic 数据模型
│   │   ├── agent/
│   │   │   ├── __init__.py
│   │   │   ├── react_agent.py       # LangChain ReAct Agent 核心
│   │   │   ├── tools.py             # 工具定义（get_current_time）
│   │   │   └── output_parser.py     # JSON 解析 + 兜底逻辑
│   │   └── routers/
│   │       ├── __init__.py
│   │       └── agent_router.py      # /api/v1/parse 接口
│   ├── requirements.txt
│   └── Dockerfile
│
├── java-scheduler/                  # Java 稳态核心
│   ├── pom.xml
│   ├── src/main/java/com/agent/scheduler/
│   │   ├── SchedulerApplication.java
│   │   ├── config/
│   │   │   ├── WebClientConfig.java       # WebFlux HTTP Client
│   │   │   ├── Resilience4jConfig.java    # 熔断降级配置
│   │   │   └── XxlJobConfig.java          # XXL-JOB 注册配置
│   │   ├── controller/
│   │   │   └── TaskController.java        # 统一入口 /api/v1/task
│   │   ├── service/
│   │   │   ├── TaskService.java           # 任务编排（WAL 落库）
│   │   │   ├── EmailService.java          # 邮件发送
│   │   │   └── AgentClient.java           # 调用 Python Agent 的 Feign 式客户端
│   │   ├── handler/
│   │   │   └── EmailJobHandler.java       # XXL-JOB Handler（定时触发）
│   │   ├── entity/
│   │   │   └── TaskRecord.java            # 数据库实体
│   │   ├── mapper/
│   │   │   └── TaskRecordMapper.java      # MyBatis-Plus Mapper
│   │   └── dto/
│   │       ├── TaskRequest.java           # 用户请求 DTO
│   │       └── AgentResponse.java         # Python 返回 JSON 映射
│   └── src/main/resources/
│       ├── application.yml
│       └── db/
│           └── schema.sql                 # 建表语句
│
└── docker-compose.yml               # 整体编排
```

## 核心时序图

```mermaid
sequenceDiagram
    actor User
    participant Java as Java Controller<br/>(Spring WebFlux)
    participant Python as Python Agent<br/>(FastAPI + LangChain)
    participant LLM as 大模型 API<br/>(OpenAI / Qwen)
    participant DB as MySQL
    participant XXL as XXL-JOB
    participant Email as SMTP Server

    User->>Java: POST /api/v1/task<br/>{"prompt": "12点半给x@q.com发一封主题为XXX的邮件"}

    Note over Java: 【Step 1: WAL 预写日志】<br/>先创建一条 PENDING 记录落库<br/>防止丢失

    Java->>DB: INSERT task (status=PENDING, prompt=...)
    DB-->>Java: OK, task_id=42

    Java->>Python: POST /api/v1/parse<br/>{"prompt": "...", "current_time": "2024-05-20 11:00:00"}

    Note over Python: 【Step 2: ReAct Agent 推理】

    Python->>LLM: System: 你是任务解析助手，当前时间=...<br/>User: 帮我在12点半...

    LLM-->>Python: 我需要获取当前时间

    Python->>Python: Tool: get_current_time() → "2024-05-20 11:00:00"

    Python->>LLM: 当前时间是2024-05-20 11:00:00<br/>继续推理...

    LLM-->>Python: {"action": "send_email",<br/>"params": {"to": "x@q.com", "subject": "XXX"},<br/>"schedule_time": "2024-05-20T12:30:00"}

    Note over Python: 【Step 3: JSON 解析 + 兜底】<br/>正则提取 + Pydantic 校验

    Python-->>Java: 200 OK<br/>{"success": true, "task": {...}}

    Note over Java: 【Step 4: 时间戳合法校验】<br/>防历史时间 / 防异常时间

    Java->>DB: UPDATE task SET status=REGISTERED,<br/>schedule_time='2024-05-20T12:30:00'

    Java->>XXL: 注册一次性定时任务<br/>触发时间: 2024-05-20 12:30:00

    Java-->>User: 200 OK<br/>{"task_id": 42, "status": "REGISTERED"}

    Note over XXL,DB: ⏰ 时间到达 12:30:00

    XXL->>Java: 触发 Handler: emailJobHandler(task_id=42)

    Note over Java: 【Step 5: 防重复执行】<br/>CAS 更新状态 REGISTERED→RUNNING

    Java->>DB: UPDATE task SET status=RUNNING<br/>WHERE id=42 AND status=REGISTERED

    Java->>Email: SMTP 发送邮件

    Email-->>Java: 发送成功

    Java->>DB: UPDATE task SET status=SUCCESS

    Java->>XXL: 任务完成回调
```

## 核心工程亮点

| 机制            | 所在层         | 解决的问题                       |
| --------------- | -------------- | -------------------------------- |
| WAL 预写日志    | Java Service   | 任务防丢失：先落库再调用 Agent   |
| CAS 状态机      | XXL-JOB Handler | 防重复执行：REGISTERED→RUNNING   |
| 时间注入 + Tool | Python Agent   | 大模型时间幻觉：注入系统时间      |
| JSON 兜底解析   | Python Parser  | Agent 输出不可控时正则兜底提取   |
| 熔断降级        | Java AgentClient | Python 不可用时的快速失败        |

## 快速启动

```bash
# 1. 启动 Python Agent
cd python-agent
pip install -r requirements.txt
uvicorn app.main:app --port 8000

# 2. 启动 Java 服务
cd java-scheduler
mvn spring-boot:run
```