Email Assistant

SKILL.md

---
name: email-assistant
description: Unified email management assistant supporting Outlook/M365 (OAuth2 via Microsoft Graph), 163, and QQ mailboxes. Use when the user wants to: (1) check/read/send emails across multiple accounts, (2) set up auto-reply rules, (3) summarize or draft emails with AI, (4) sync mailboxes on schedule, (5) manage attachments, CC/BCC, read/unread status, or filter/search emails by sender/keyword/date.
metadata:
  openclaw:
    requires:
      bins: [python3]
    install:
      - id: setup
        kind: shell
        label: "运行安装向导"
        command: "python3 skills/mail-assistant/scripts/setup_wizard.py"
        description: "交互式配置向导，添加邮箱账户并完成 OAuth 授权"
    settings:
      - key: accounts
        label: "已配置的邮箱账户"
        type: text
        readonly: true
        description: "查看当前已配置的邮箱账户。新增/删除邮箱由 Agent 自动处理，直接说出来即可"
      - key: sync
        label: "定时同步状态"
        type: text
        readonly: true
        description: "每小时自动同步，由 Agent 管理 cron 任务"
---

# Email Assistant

统一的邮箱管理助手，支持 **Outlook/Microsoft 365**（OAuth2）、**163 邮箱**、**QQ 邮箱**。

核心能力：收发邮件、AI 辅助撰写、自动回复规则、每小时定时同步。

---

## 📦 安装与配置（Agent 引导模式）

### 前置条件

- **Python 3.8+**（本 Skill 已安装 Python 脚本）
- **跨平台支持**：Windows / macOS / Linux 均可使用
- 无需手动运行脚本！Agent 会引导你完成设置

### 📋 配置流程（由 Agent 自动执行）

当用户说 "帮我配置邮箱" 时，Agent 按以下流程操作：

**1. 检查 accounts 目录**
```python
import os, json
accts_dir = "skills/mail-assistant/accounts"
if not os.path.exists(accts_dir):
    os.makedirs(accts_dir)
# 列出已有配置
configs = [f for f in os.listdir(accts_dir) if f.endswith(".json") and not f.endswith(".token.json")]
```

**2. Outlook — 创建账户配置**
```python
import json
# 内置 Azure client_id（无需用户配置）
BUILTIN_CLIENT_ID = "c31fd78c-6385-4fd2-9033-d0bd72b5ceb4"

account = {
    "id": "my-outlook",
    "type": "outlook",
    "user": "",  # 空，登录后自动获取
    "oauth": {
        "client_id": BUILTIN_CLIENT_ID,
        "tenant_id": "consumers",
        "scopes": ["User.Read", "Mail.ReadWrite", "Mail.Send", "MailboxSettings.Read"],
    },
}
with open("skills/mail-assistant/accounts/my-outlook.json", "w") as f:
    json.dump(account, f, indent=2)
```

**3. Outlook — 启动浏览器授权**
```python
import subprocess, sys
subprocess.run([sys.executable, "skills/mail-assistant/scripts/oauth_web.py", "my-outlook"])
# 脚本会自动打开浏览器，用户登录后自动接收回调
```

**4. 163 / QQ 邮箱 — 创建配置**
```python
account = {
    "id": "my-163",  # 或 my-qq
    "type": "163",  # 或 qq
    "user": "user@163.com",
    "smtp": {"host": "smtp.163.com", "port": 465, "auth": "授权码"},
    "imap": {"host": "imap.163.com", "port": 993, "auth": "授权码"},
}
with open("skills/mail-assistant/accounts/my-163.json", "w") as f:
    json.dump(account, f, indent=2)
```

**5. 测试连接**
```python
# Outlook
subprocess.run([sys.executable, "skills/mail-assistant/scripts/outlook_api.py", "my-outlook", "list-inbox", "--limit", "1"], timeout=30)

# 163/QQ
subprocess.run([sys.executable, "skills/mail-assistant/scripts/email_client.py", "my-163", "list-inbox", "--limit", "1"], timeout=30)
```

**6. 设置定时同步**
```python
subprocess.run([sys.executable, "skills/mail-assistant/scripts/sync_all.py"])
```

也可以使用 setup_wizard.py 交互式配置：
```bash
python3 skills/mail-assistant/scripts/setup_wizard.py
```

---

## 🔑 添加邮箱账户（Agent 引导模式）

以下配置流程由 Agent 自动执行。参看上方「配置流程」节中的 Python 代码段。

### Outlook / Microsoft 365

用户只需说 "添加 Outlook 邮箱"，Agent 即可自动：
1. 创建 `accounts/my-outlook.json` 配置文件（内置 Azure 应用注册）
2. 通过 `subprocess.run` 调用 `scripts/oauth_web.py` 启动浏览器授权
3. 用户登录 Microsoft 账户并授权
4. 完成配置

### 163 邮箱

用户提供邮箱地址和授权码，Agent 自动：
1. 创建 `accounts/my-163.json` 配置文件
2. 通过 `email_client.py` 验证连接
3. 确认配置成功

### QQ 邮箱

用户提供邮箱地址和授权码，Agent 自动：
1. 创建 `accounts/my-qq.json` 配置文件
2. 通过 `email_client.py` 验证连接
3. 确认配置成功

---

## 🚀 核心功能

| 功能 | 说明 |
|------|------|
| 📬 收件箱查看 | 列出邮件、预览详情、查看附件 |
| ✉️ 发送邮件 | 支持附件、CC、BCC，AI 辅助撰写 |
| 🔍 搜索筛选 | 按发件人/关键词/时间搜索 |
| 📑 标记已读/未读 | 管理邮件状态 |
| 🤖 自动回复 | 按域名/关键词设置自动回复规则 |
| ⏰ 定时同步 | 每小时自动同步（OpenClaw cron） |
| 🔄 手动同步 | `python3 scripts/sync_all.py` |

### 自然语言交互示例

| 你说 | 我做什么 |
|------|---------|
| "帮我查一下今天 Outlook 的邮件" | 读取 Outlook 收件箱，筛选今天的邮件 |
| "给 xx@qq.com 发一封请假邮件" | 撰写邮件 → 你确认 → 发送 |
| "总结最近 3 封重要邮件" | 提取最近邮件，用 LLM 总结 |
| "设置对老板的邮件自动回复" | 创建自动回复规则 |
| "帮我把这封邮件标记为已读" | 调用 API 标记已读 |

---

## 💻 编程式调用指南（供 Agent / 开发者使用）

本 Skill 的 Python 脚本既可作为 CLI 运行，也可作为 Python 模块导入。

**建议使用 import 方式调用**，令牌过期会自动刷新。

### Outlook / M365

```python
import sys
sys.path.insert(0, "skills/mail-assistant/scripts")

from outlook_api import list_inbox, read_mail, mark_read, mark_unread, search

# 列出最近 5 封未读邮件
list_inbox("my-outlook", limit=5, unread_only=True)

# 搜索邮件
search("my-outlook", "发票", limit=10)

# 读取单封邮件
read_mail("my-outlook", "<message-id>")

# 标记已读/未读
mark_read("my-outlook", "<message-id>")
mark_unread("my-outlook", "<message-id>")
```

所有函数打印 JSON 到 stdout。如需在 Python 中捕获返回值，使用 CLI 方式：

```python
import subprocess, json
result = subprocess.run(
    [sys.executable, "skills/mail-assistant/scripts/outlook_api.py",
     "my-outlook", "list-inbox", "--limit", "5"],
    capture_output=True, text=True, timeout=30
)
emails = json.loads(result.stdout)
```

### 163 / QQ 邮箱

```python
from email_client import list_inbox, read_mail, mark_read

list_inbox("my-qq", limit=5, unread_only=True)
read_mail("my-163", "<uid>")
```

### 自动回复规则

```python
import subprocess, json

# 列出规则
result = subprocess.run([sys.executable, "skills/mail-assistant/scripts/auto_reply.py", "list"],
    capture_output=True, text=True, timeout=10)
rules = json.loads(result.stdout)
```

### 手动同步

```python
import subprocess
subprocess.run([sys.executable, "skills/mail-assistant/scripts/sync_all.py"])
```

## 🔧 脚本参考

| 脚本 | 用途 |
|------|------|
| `scripts/setup_wizard.py` | 交互式配置向导（推荐） |
| `scripts/oauth_web.py` | Outlook 浏览器授权（PKCE + 本地服务器） |
| `scripts/oauth_manager.py` | OAuth2 令牌管理（auth/refresh/revoke） |
| `scripts/outlook_api.py` | Microsoft Graph API 调用 |
| `scripts/email_client.py` | SMTP/IMAP 发送（163/QQ） |
| `scripts/auto_reply.py` | 自动回复规则管理 |
| `scripts/sync_all.py` | 同步所有邮箱 + 触发自动回复 |
| `scripts/email_utils.py` | 工具函数（格式化、状态管理） |

---

## 🔐 安全与隐私

- OAuth2 令牌本地存储，不离开本机
- 邮件正文不写入长期存储（MEMORY.md）
- 随时可通过 `scripts/oauth_manager.py revoke <id>` 撤销授权
- QQ/163 使用**授权码**而非密码

---

## 📚 参考文档

- `references/microsoft_graph.md` — Microsoft Graph API 详细文档
- `references/email_protocols.md` — SMTP/IMAP 配置参考
- `references/auto_reply_rules.md` — 自动回复规则格式