# email_agent

**Repository Path**: yeguangsen/email_agent

## Basic Information

- **Project Name**: email_agent
- **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-07-02
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Email Agent

基于 Python + PySide6 的智能邮件助手桌面应用，集成 LLM 推理引擎，支持邮件处理、Excel 操作等多种工具。

## ✨ 功能特性

- **智能邮件处理**: 通过 Outlook COM 接口读取和回复邮件
- **ReAct 推理引擎**: 支持多步推理和工具调用，实现复杂任务自动化
- **Skill 管理**: 可配置多个技能（System Prompt），支持启用/禁用
- **工具集成**: 邮件工具、Excel 工具，支持扩展
- **LLM 配置**: 支持 OpenAI/Azure/Ollama/vLLM/DeepSeek 等多种 provider
- **任务调度**: 支持定时任务和手动触发
- **实时日志**: 完整的运行日志和推理过程展示

## 📁 项目结构

```
email_agent/
├── main.py                    # 程序入口
├── build.py                   # PyInstaller 打包脚本
├── requirements.txt           # 依赖清单
├── core/                      # 核心模块
│   ├── abc.py                 # 抽象基类（LlmProvider）
│   ├── config_models.py       # 配置数据模型（Pydantic）
│   ├── email_monitor.py       # 邮件监听线程
│   ├── factory.py             # 组件工厂（依赖注入）
│   ├── llm_client.py          # LLM 客户端
│   ├── log_bus.py             # 日志总线（Qt Signal）
│   ├── models.py              # 数据模型（EmailData）
│   ├── prompt_builder.py      # 提示词构建器
│   ├── react_engine.py        # ReAct 推理引擎
│   ├── resource_manager.py    # 资源管理器
│   ├── signal_connector.py    # 信号连接器
│   ├── task_scheduler.py      # 任务调度器
│   └── tool_registry.py       # 工具注册表
├── gui/                       # GUI 模块
│   ├── main_window.py         # 主窗口
│   ├── input_analysis_page.py # 信息输入/对话页面
│   ├── skill_manager.py       # Skill 管理页面
│   ├── llm_config.py          # LLM 配置页面
│   ├── scheduler_config.py    # 调度器配置页面
│   ├── log_viewer.py          # 日志查看页面
│   └── styles.py              # 样式定义
├── tools/                     # 工具模块
│   ├── base.py                # 工具基类（BaseTool）
│   ├── mail_tool.py           # 邮件工具（Outlook）
│   └── excel_tool.py          # Excel 工具（xlwings）
├── utils/                     # 工具函数
│   ├── config_manager.py      # 配置管理器
│   ├── path_utils.py          # 路径工具
│   └── yaml_utils.py          # YAML 读写工具
├── adapters/                  # 适配器层（预留）
├── config/                    # 配置文件目录
└── tests/                     # 测试模块
```

## 🛠️ 技术栈

| 模块 | 技术 | 版本要求 |
|------|------|----------|
| GUI 框架 | PySide6 | >= 6.5.0 |
| LLM SDK | openai | >= 1.30.0 |
| 邮件客户端 | win32com | >= 306 |
| Excel 操作 | xlwings | >= 0.30.0 |
| 配置管理 | pyyaml | >= 6.0 |
| 数据验证 | pydantic | >= 2.0.0 |
| 路径处理 | appdirs | >= 1.4.4 |
| Excel 读写 | openpyxl, xlrd | >= 3.1.0 |
| Markdown | markdown | >= 3.4.0 |

## 🚀 快速开始

### 环境要求

- Python 3.10+
- Windows 10/11
- Outlook 2016+（邮件功能）
- Excel 2016+（Excel 功能）

### 安装依赖

```bash
cd email_agent
pip install -r requirements.txt
```

### 运行应用

```bash
python main.py
```

### 打包构建

```bash
python build.py
```

打包产物位于 `dist/` 目录。

## 🔧 配置说明

配置文件存储在用户 AppData 目录：

```
%APPDATA%\EmailAgent\config.yaml
```

### 主要配置项

```yaml
llm:
  provider: "openai"
  api_key: "your-api-key"
  api_base: "https://api.openai.com/v1"
  model: "gpt-4o-mini"
  temperature: 0.7
  max_tokens: 1000
  timeout: 60

skills:
  default:
    system_prompt: "你是一位专业的邮件客服助手..."
    enabled_tools: ["send_email_reply", "get_unread_emails"]

active_skill: "default"

polling_interval: 30
dry_run: false
save_as_draft: true
monitor_email: false
```

## 📖 使用指南

### 1. 信息输入页面

- 与 LLM 进行对话
- 支持多对话管理
- 实时显示推理过程和工具调用

### 2. Skill 管理页面

- 创建/删除/编辑技能
- 设置默认技能
- 启用/禁用技能
- 实时预览 Markdown 格式

### 3. LLM 配置页面

- 配置 API Key 和 Base URL
- 设置模型参数（温度、最大令牌数等）
- 测试连接

### 4. 调度器页面

- 配置定时任务间隔
- 手动触发任务
- 查看调度器状态

### 5. 运行日志页面

- 实时查看系统日志
- 查看推理过程（Thought/Action/Observation）
- 查看错误信息

## 🧠 ReAct 推理引擎

ReAct（Reasoning + Acting）引擎支持：

- **多步推理**: 最多 30 步推理深度
- **工具调用**: 自动调用注册的工具
- **重复检测**: 防止无限循环调用同一工具
- **结果缓存**: 邮件数据缓存机制
- **超时控制**: 每步推理超时保护

### 工具列表

| 工具 | 功能 |
|------|------|
| `get_unread_emails` | 获取未读邮件列表 |
| `get_email_details` | 获取邮件详细信息 |
| `send_email_reply` | 回复邮件 |
| `send_new_email` | 创建新邮件（支持附件） |
| `send_email_directly` | 直接发送邮件 |
| `mark_email_as_read` | 标记邮件已读 |
| `open_excel_workbook` | 打开 Excel 工作簿 |
| `excel_read_range` | 读取 Excel 数据范围 |
| `excel_add_row` | 追加 Excel 行 |
| `excel_find_row` | 查找 Excel 行 |
| `excel_update_cell` | 更新 Excel 单元格 |

## 🏗️ 架构设计

### 核心设计原则

1. **依赖注入**: 通过 `factory.py` 集中创建组件
2. **事件驱动**: 通过 `log_bus.py` 和 Qt Signal 实现解耦
3. **线程安全**: GUI 更新通过信号机制确保线程安全
4. **可扩展性**: 工具通过 `BaseTool` 基类扩展
5. **配置热更新**: 运行时修改配置立即生效

### 模块依赖关系

```
main.py
  ├── factory.py          # 创建核心组件
  ├── MainWindow          # GUI 主窗口
  ├── SignalConnector     # 信号连接
  └── ResourceManager     # 资源管理

core/
  ├── ReActEngine         # 推理引擎
  │   ├── LlmClient       # LLM 调用
  │   ├── ToolRegistry    # 工具注册
  │   └── LogBus          # 日志总线
  ├── TaskScheduler       # 任务调度
  └── EmailMonitor        # 邮件监听

gui/
  ├── InputAnalysisPage   # 对话页面
  ├── SkillManagerPage    # Skill 管理
  ├── LlmConfigPage       # LLM 配置
  ├── SchedulerConfigPage # 调度器配置
  └── LogViewerPage       # 日志查看

tools/
  ├── MailTool            # Outlook 邮件工具
  └── ExcelTool           # Excel 工具
```

## 🧪 测试

```bash
cd email_agent
python -m pytest tests/ -v
```

## 📝 开发规范

- **代码风格**: 遵循 PEP 8
- **类型提示**: 使用 Python 类型注解
- **日志记录**: 使用 `log_bus` 或 `logger` 记录日志
- **异常处理**: 捕获具体异常类型，避免裸 `except`
- **线程安全**: GUI 更新必须通过 Qt Signal

## � 常见问题

### Outlook 连接失败
- **原因**: Outlook 未运行或未正确安装
- **解决方案**: 确保 Outlook 2016+ 已安装并正在运行

### Excel 工具不可用
- **原因**: Excel 未安装或 xlwings 未正确安装
- **解决方案**: 
  - 确保 Excel 2016+ 已安装
  - 执行 `pip install xlwings>=0.30.0`

### LLM 连接失败
- **原因**: API Key 无效或网络问题
- **解决方案**:
  - 检查 API Key 是否正确配置
  - 检查网络连接是否正常
  - 检查 API Base URL 是否正确

### SSL 验证警告
- **说明**: 默认 SSL 验证配置为 `False`，这可能存在安全风险
- **建议**: 在生产环境中设置 `llm.ssl_verify: true`

### 邮件监听无反应
- **原因**: 邮件监听功能未启用
- **解决方案**: 在主窗口勾选"监听邮件"复选框

## �📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 GitHub Issue