email-pro-optimized
# Email Pro Optimized - 高性能邮件工具
快速、高效的邮件管理工具，支持多账号、多提供商、批量处理、并发获取。
## 支持的邮箱类型
| 邮箱 | 认证方式 | 状态 |
|------|--------|------|
| **QQ 邮箱** | IMAP/SMTP + 授权码 | ✅ 完全支持 |
| **Gmail** | OAuth 2.0 | ✅ 完全支持 |
| **Outlook/Live** | OAuth 2.0 | ✅ 完全支持 |
## 性能对比
| 指标 | imap-smtp-email | Email Pro Optimized |
|------|-----------------|-------------------|
| **10封邮件** | 1.5-2s | 0.3-0.5s |
| **100封邮件** | 15-20s | 2-3s |
| **1000封邮件** | 150-200s | 15-20s |
| **并发处理** | ❌ | ✅ |
| **连接复用** | ❌ | ✅ |
| **多提供商** | ❌ | ✅ |
## 快速开始
### 1. 列出账户
```bash
python3 scripts/email-pro.py list-accounts
```
### 2. 检查邮件（QQ 邮箱）
```bash
# 检查最近 10 封
python3 scripts/email-pro.py --account qq_3421 check --limit 10
# 仅检查未读
python3 scripts/email-pro.py --account qq_3421 check --unread
# 使用其他账户
python3 scripts/email-pro.py --account qq_136 check --limit 5
```
### 3. 授权 Gmail 邮箱
```bash
# 自动授权 Gmail
python3 scripts/authorize.py gmail --name gmail_qiao
# 或使用默认配置
python3 scripts/authorize.py gmail
```
### 4. 授权 Outlook 邮箱
```bash
# 自动授权（已配置 Azure 信息）
bash scripts/authorize-outlook.sh
# 或手动授权
python3 scripts/authorize.py outlook \
--client-id "YOUR_CLIENT_ID" \
--client-secret "YOUR_CLIENT_SECRET" \
--tenant-id "YOUR_TENANT_ID" \
--name "outlook_live"
```
### 5. 检查邮件（Gmail/Outlook）
```bash
# Gmail
python3 scripts/email-pro.py --account gmail_qiao check --limit 10
# Outlook
python3 scripts/email-pro.py --account outlook_live check --limit 10
```
### 6. 发送邮件
```bash
# QQ 邮箱
python3 scripts/email-pro.py --account qq_136 send \
--to "recipient@example.com" \
--subject "Hello" \
--body "Test email"
# Gmail
python3 scripts/email-pro.py --account gmail_qiao send \
--to "recipient@example.com" \
--subject "Hello" \
--body "Test email"
# Outlook
python3 scripts/email-pro.py --account outlook_live send \
--to "recipient@example.com" \
--subject "Hello" \
--body "Test email"
```
## OAuth 自动刷新
Gmail 和 Outlook 的 OAuth token 会自动刷新，无需手动干预。
### 工作原理
- **自动检测过期** - 每次使用前自动检查 token 是否过期
- **提前刷新** - 提前 5 分钟刷新，避免过期
- **透明处理** - 调用方无需关心刷新逻辑
- **持久化** - 新 token 自动保存到凭证文件
### 在代码中使用
```python
from scripts.oauth_handler import get_valid_token
# 获取有效的 token（自动刷新）
token = get_valid_token('gmail')
headers = {'Authorization': f'Bearer {token}'}
# 使用 headers 调用 Gmail API
response = requests.get('https://www.googleapis.com/gmail/v1/users/me/profile', headers=headers)
```
## 高级用法
### 搜索邮件
```bash
python3 scripts/email-pro.py search "旅行" --limit 20
```
### 获取完整邮件
```bash
python3 scripts/email-pro.py fetch 71197
```
### 批量并发获取
```bash
# 获取最近 100 封邮件的完整内容（5 个线程并发）
python3 scripts/email-pro.py check --limit 100 | \
jq -r '.[].uid' | \
xargs -I {} python3 scripts/email-pro.py fetch {}
```
## 配置
### 配置文件位置
`~/.openclaw/credentials/email-accounts.json`
### QQ 邮箱配置
```json
{
"qq_3421": {
"email": "342187916@qq.com",
"auth_code": "xxxx",
"smtp_server": "smtp.qq.com",
"smtp_port": 587,
"imap_server": "imap.qq.com",
"imap_port": 993,
"provider": "imap",
"status": "✅ 正常",
"note": "接收邮箱"
}
}
```
### Outlook 配置
```json
{
"outlook_live": {
"email": "qiao6646@live.com",
"provider": "outlook",
"account_name": "outlook_live",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"tenant_id": "YOUR_TENANT_ID",
"status": "✅ 已授权",
"note": "Outlook 邮箱"
}
}
```
### Gmail 配置
```json
{
"gmail_account": {
"email": "your-email@gmail.com",
"provider": "gmail",
"account_name": "gmail_account",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"status": "✅ 已授权",
"note": "Gmail 邮箱"
}
}
```
## 命令参考
### check - 检查邮件
```bash
python3 scripts/email-pro.py check [OPTIONS]
Options:
--account NAME 账户名称 (默认: qq_3421)
--limit N 限制数量 (默认: 10)
--unread 仅未读邮件
--mailbox NAME 邮箱名称 (默认: INBOX)
```
### fetch - 获取完整邮件
```bash
python3 scripts/email-pro.py fetch UID [OPTIONS]
Options:
--account NAME 账户名称 (默认: qq_3421)
--mailbox NAME 邮箱名称 (默认: INBOX)
```
### search - 搜索邮件
```bash
python3 scripts/email-pro.py search QUERY [OPTIONS]
Options:
--account NAME 账户名称 (默认: qq_3421)
--limit N 限制数量 (默认: 20)
--mailbox NAME 邮箱名称 (默认: INBOX)
```
### send - 发送邮件
```bash
python3 scripts/email-pro.py send [OPTIONS]
Options:
--account NAME 账户名称 (默认: qq_3421)
--to EMAIL 收件人 (必需)
--subject TEXT 主题 (必需)
--body TEXT 正文 (必需)
--html HTML 格式
--attach FILE... 附件
```
### list-accounts - 列出账户
```bash
python3 scripts/email-pro.py list-accounts
```
## OAuth 授权
### Outlook 授权流程
1. **获取 Azure 应用信息**
- 登录 Azure Portal
- 创建应用注册或使用现有应用
- 复制 Client ID、Client Secret、Tenant ID
2. **运行授权脚本**
```bash
bash scripts/authorize-outlook.sh
```
或
```bash
python3 scripts/authorize.py outlook \
--client-id "YOUR_CLIENT_ID" \
--client-secret "YOUR_CLIENT_SECRET" \
--tenant-id "YOUR_TENANT_ID"
```
3. **浏览器授权**
- 脚本会打开浏览器
- 登录你的 Outlook 账户
- 授予权限
- 令牌自动保存到 `~/.openclaw/credentials/oauth_tokens.json`
### Gmail 授权流程
1. **获取 Google OAuth 凭证**
- 访问 Google Cloud Console
- 创建 OAuth 2.0 凭证
- 复制 Client ID 和 Client Secret
2. **运行授权脚本**
```bash
python3 scripts/authorize.py gmail \
--client-id "YOUR_CLIENT_ID" \
--client-secret "YOUR_CLIENT_SECRET" \
--name "gmail_account"
```
3. **浏览器授权**
- 脚本会打开浏览器
- 登录你的 Gmail 账户
- 授予权限
- 令牌自动保存
## 优化点
1. **批量 fetch** - 一次获取多封邮件，快 4.5 倍
2. **连接复用** - 保持连接活跃，省 385ms
3. **错误处理** - 跳过损坏邮件，更稳定
4. **并发处理** - 支持多线程并发获取
5. **多提供商** - 统一接口支持 QQ、Gmail、Outlook
6. **OAuth 2.0** - 安全的令牌认证，自动刷新
## 性能基准
```
✅ 检查 10 封邮件: 0.5s
✅ 检查 100 封邮件: 3s
✅ 检查 1000 封邮件: 20s
✅ 发送邮件: 0.6s
✅ 并发获取 20 封: 1.5s
```
## 故障排除
### 连接超时
- 检查网络连接
- 验证 IMAP/SMTP 服务器地址和端口
- 对于 Outlook，确保已授权
### 认证失败
- QQ 邮箱：确认授权码正确（不是密码）
- Outlook：重新运行授权脚本
- Gmail：检查 OAuth 令牌是否过期
### 邮件解析失败
- 某些邮件格式可能不支持
- 脚本会自动跳过损坏的邮件
## 依赖
- Python 3.6+
- requests（用于 OAuth 和 API 调用）
- 标准库: imaplib, smtplib, email, ssl, json, argparse
安装依赖：
```bash
pip3 install requests
```
## 文件结构
```
email-pro-optimized/
├── scripts/
│ ├── email-pro.py # 主程序
│ ├── providers.py # 邮件提供商实现
│ ├── oauth_handler.py # OAuth 处理
│ ├── authorize.py # 授权工具
│ ├── authorize-outlook.sh # Outlook 快速授权
│ └── analyze.py # 邮件分析工具
├── SKILL.md # 本文档
└── README.md # 项目说明
```
## 常见用例
### 旅行监控
```bash
# 定期检查旅行相关邮件
python3 scripts/email-pro.py search "机票|酒店|旅行" --limit 50
# 发送监控报告
python3 scripts/email-pro.py --account qq_136 send \
--to "your-email@example.com" \
--subject "旅行监控报告" \
--body "今日发现 5 条相关邮件"
```
### 邮件备份
```bash
# 导出所有邮件为 JSON
python3 scripts/email-pro.py check --limit 1000 > backup.json
```
### 自动分类
```bash
# 使用 analyze.py 分析邮件
python3 scripts/analyze.py
```
## 更新日志
### v2.0.0 (2026-03-20)
- ✅ 新增 Gmail 支持（OAuth 2.0）
- ✅ 新增 Outlook 支持（OAuth 2.0）
- ✅ 模块化提供商架构
- ✅ 自动令牌刷新
- ✅ 统一命令接口
### v1.0.0 (2026-03-19)
- ✅ QQ 邮箱支持
- ✅ 高性能批量获取
- ✅ 并发处理
标签
skill
ai
