# Email 适配器

Email 适配器允许 Nekro Agent 通过 IMAP/SMTP 协议收发邮件，将邮件转换为聊天消息进行处理，并提供丰富的邮件操作 API 供 AI 调用。

## 功能特性

- ✅ IMAP 邮件接收（轮询方式）
- ✅ SMTP 邮件发送
- ✅ 多账户支持
- ✅ 国内常见邮箱服务商自动配置（QQ邮箱、163邮箱）
- ✅ 邮件格式化为 Markdown 内容
- ✅ 邮件附件自动下载与管理
- ✅ 邮箱账户聊天管理（同一邮箱账户的邮件归属到同一聊天中）
- ✅ AI 可调用的邮件操作方法（发送邮件、转发附件、查询邮件、总结邮件等）
- ✅ 新邮件通知功能（可配置自动通知到指定聊天频道）

## 未来开发方向

- 国外邮箱适配

## 配置说明

### 邮箱账户配置

在配置界面中，您可以添加多个邮箱账户：

- **账户名称**: 用于在配置界面作为该账户的展示名称
- **邮箱账户**: 选择邮箱服务商（QQ邮箱、163邮箱），系统会自动匹配对应的IMAP/SMTP服务器地址和端口，无需手动填写。
- **启用账户**: 是否启用此邮箱账户，设置为否时将跳过连接和轮询
- **邮箱用户名**: 填写完整邮箱地址
- **邮箱密码/授权码**: 建议使用应用专用密码或 IMAP 授权码
- **启用发信**: 是否允许该邮箱账户用于SMTP发信
- **默认发件人**: 设为默认发件人

### 全局配置

- **轮询间隔(秒)**: 每次轮询之间的等待时长，默认30秒
- **仅拉取未读**: 启用后仅处理未读邮件，避免重复
- **每次最大抓取数**: 单次轮询最大抓取的邮件数量上限
- **读取后标记已读**: 启用后在读取并收集消息后将邮件标记为已读
- **IMAP 连接超时(秒)**: IMAP 连接和操作的超时时间
- **启用新邮件通知**: 是否在接收到新邮件后自动触发通知和 AI 处理
- **新邮件通知聊天频道**: 接收新邮件通知的聊天频道标识（例如 `onebot_v11-group_123456`）

## 使用说明

1. 在配置界面添加邮箱账户信息
2. 启用需要收发邮件的账户
3. 设置默认发件人（用于发送邮件）
4. 根据需要调整轮询间隔和其他参数
5. 保存配置并重启 Nekro Agent

## 聊天管理

Email 适配器将每个邮箱账户视为一个独立的聊天渠道。同一邮箱账户收到的所有邮件都会归属到同一个聊天中，方便统一管理和回复。

- 每个启用的邮箱账户都会自动创建一个对应的聊天ID
- 聊天ID格式为 `email-{邮箱地址}`
- 用户可以在聊天界面中查看来自特定邮箱账户的邮件

## 附件处理

邮件附件会自动下载到项目数据目录：

- **保存路径**: `data/uploads/email_attachment/{邮箱账户}/{邮件UID}/{附件文件名}`
- **文件名处理**: 保留原始文件名，非法字符会被自动清理
- **路径隔离**: 每个邮箱账户和邮件 UID 都有独立的目录，确保文件组织清晰
- **安全保护**: 使用路径验证机制防止路径穿越攻击

## AI 可用方法

Email 适配器配套的插件提供了以下方法供 AI 调用：

### 1. 获取邮箱账户列表
```python
get_email_accounts()
```
返回当前配置的所有邮箱账户信息，包括账户地址、服务商、是否启用发信等。

### 2. 发送邮件
```python
send_email()
```
通过指定或默认的发件人账户发送邮件。

### 3. 发送邮件附件
```python
send_email_attachment()
```
将邮件附件转发到指定的聊天频道。适配器会自动处理文件复制和路径转换。

### 4. 总结最近邮件
```python
summarize_recent_emails()
```
使用指定模型组总结最近1天内的邮件内容，可按账户筛选和限制数量。

### 5. 获取邮件详情
```python
get_email_content()
```
获取指定邮件的完整内容，包括主题、发件人、正文（纯文本和HTML）、附件列表等详细信息。

## 注意事项

- 建议使用应用专用密码或 IMAP 授权码，而不是邮箱登录密码
- 轮询间隔不宜设置过短，以免被邮箱服务商限制
- 邮件内 HTML 内容会被转换为 Markdown 格式进行处理
- 附件下载功能需要确保项目有写入权限