星辉: 新增AgentMail技能使用指南（基于实际案例整理）

openclaw/knowledgebase/AgentMail-技能使用指南.md

@@ -0,0 +1,272 @@
+# AgentMail 技能使用文档
+
+> 基于实际案例整理：2026-04-04 处理 billyshen@163.com 发来的房屋合同图片
+
+---
+
+## 📬 AgentMail 是什么？
+
+AgentMail 是一个 API-first 的邮件平台，专为 AI Agent 设计。它不是传统的 Gmail/Outlook，而是一个可以通过 API 创建邮箱、收发邮件、处理附件的平台。
+
+**核心特点：**
+- 无 rate limit，适合 Agent 高频使用
+- 支持 Webhook 实时处理邮件
+- API 驱动，可编程控制
+
+---
+
+## 📋 环境配置
+
+### 1. 安装 Python SDK
+
+```bash
+pip3 install --break-system-packages agentmail python-dotenv
+```
+
+### 2. 配置环境变量
+
+在 `~/.openclaw/.env` 中添加：
+
+```bash
+AGENTMAIL_API_KEY=your_api_key_here
+AGENTMAIL_EMAIL=star-agent@agentmail.to  # 收件邮箱（可选）
+```
+
+### 3. API Key 获取
+
+登录 [console.agentmail.to](https://console.agentmail.to) → Dashboard → 生成 API Key
+
+---
+
+## 🔄 核心工作流程
+
+### 步骤 1：读取邮件
+
+```python
+import os
+from agentmail import AgentMail
+
+client = AgentMail(api_key=os.getenv('AGENTMAIL_API_KEY'))
+
+# 查看所有收件箱
+inboxes = client.inboxes.list(limit=10)
+for inbox in inboxes.inboxes:
+    print(f"Inbox: {inbox.inbox_id}")
+    print(f"Display name: {inbox.display_name}")
+
+# 列出邮件
+messages = client.inboxes.messages.list(
+    inbox_id='star-agent@agentmail.to',
+    limit=10
+)
+for msg in messages.messages:
+    print(f"From: {msg.from_}")
+    print(f"Subject: {msg.subject}")
+    print(f"Time: {msg.timestamp}")
+    print(f"Attachments: {len(msg.attachments) if msg.attachments else 0}")
+```
+
+### 步骤 2：获取邮件详情
+
+```python
+# 获取单封邮件详情
+msg = client.inboxes.messages.get(
+    inbox_id='star-agent@agentmail.to',
+    message_id='<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>'
+)
+
+print(f"Subject: {msg.subject}")
+print(f"Text: {msg.text}")
+print(f"Attachments count: {len(msg.attachments)}")
+
+# 遍历附件
+for att in msg.attachments:
+    print(f"  - {att.filename} ({att.size} bytes)")
+    print(f"    Content type: {att.content_type}")
+    print(f"    Attachment ID: {att.attachment_id}")
+```
+
+### 步骤 3：下载附件
+
+AgentMail 的附件需要通过两步获取：
+1. 获取附件的下载 URL
+2. 用下载 URL 获取文件内容
+
+```python
+import httpx
+import urllib.parse
+
+api_key = os.getenv('AGENTMAIL_API_KEY')
+msg_id = urllib.parse.quote('<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>')
+
+# 遍历所有附件并下载
+for att in msg.attachments:
+    att_id = att.attachment_id
+    filename = att.filename
+    
+    # 获取下载链接
+    resp = httpx.get(
+        f"https://api.agentmail.to/v0/inboxes/star-agent@agentmail.to/messages/{msg_id}/attachments/{att_id}",
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=30.0
+    )
+    download_url = resp.json()['download_url']
+    
+    # 下载文件
+    img_resp = httpx.get(download_url, timeout=60.0)
+    local_path = f'/tmp/{filename}'
+    with open(local_path, 'wb') as f:
+        f.write(img_resp.content)
+    print(f"Downloaded: {local_path}")
+```
+
+### 步骤 4：发送邮件
+
+```python
+client.inboxes.messages.send(
+    inbox_id='star-agent@agentmail.to',
+    to='recipient@example.com',
+    subject='主题',
+    text='正文内容',
+    attachments=[{
+        'filename': 'report.pdf',
+        'content': base64.b64encode(file_data).decode()
+    }]
+)
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. 代理问题
+
+如果系统配置了 SOCKS5 代理，需要在调用前取消代理设置：
+
+```python
+import os
+os.environ.pop('HTTP_PROXY', None)
+os.environ.pop('HTTPS_PROXY', None)
+os.environ.pop('http_proxy', None)
+os.environ.pop('https_proxy', None)
+```
+
+或者在执行命令时 unset：
+
+```bash
+unset HTTP_PROXY && unset HTTPS_PROXY && unset http_proxy && unset https_proxy
+python3 script.py
+```
+
+### 2. 附件 API 路径
+
+附件信息在邮件列表中不包含 `content` 字段，需要单独调用 `/attachments/{attachment_id}` 端点获取 `download_url`。
+
+### 3. httpx 的 SOCKS 支持
+
+如果遇到 `ImportError: Using SOCKS proxy, but the 'socksio' package is not installed`：
+
+```bash
+pip3 install --break-system-packages socksio httpx
+```
+
+---
+
+## 📝 实际案例：处理邮件中的图片附件
+
+### 场景
+用户通过 163 邮箱发送了 6 张图片到 `star-agent@agentmail.to`，要求识别图片文字并生成 Word 文档。
+
+### 执行过程
+
+```python
+import os
+import httpx
+from agentmail import AgentMail
+
+client = AgentMail(api_key=os.getenv('AGENTMAIL_API_KEY'))
+
+# 1. 获取邮件
+msg = client.inboxes.messages.get(
+    inbox_id='star-agent@agentmail.to',
+    message_id='<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>'
+)
+
+print(f"Subject: {msg.subject}")
+print(f"Attachments: {len(msg.attachments)}")
+
+# 2. 下载所有图片
+os.makedirs('/tmp/ocr_images', exist_ok=True)
+
+for i, att in enumerate(msg.attachments):
+    att_id = att.attachment_id
+    filename = att.filename
+    
+    resp = httpx.get(
+        f"https://api.agentmail.to/v0/inboxes/star-agent@agentmail.to/messages/{urllib.parse.quote(msg.message_id)}/attachments/{att_id}",
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=30.0
+    )
+    download_url = resp.json()['download_url']
+    
+    img_resp = httpx.get(download_url, timeout=60.0)
+    local_path = f'/tmp/ocr_images/img_{i+1:02d}.jpg'
+    with open(local_path, 'wb') as f:
+        f.write(img_resp.content)
+    print(f"Downloaded: {local_path}")
+
+# 3. 图片复制到工作目录（因为 image 工具只认特定路径）
+import shutil
+for i in range(1, 7):
+    src = f'/tmp/ocr_images/img_{i:02d}.jpg'
+    dst = f'/Users/weishen/.openclaw/workspace-agent-xinghui/img_{i:02d}.jpg'
+    shutil.copy(src, dst)
+```
+
+### 3. OCR 识别
+
+复制到工作目录后，使用 `image` 工具识别文字：
+
+```python
+# image 工具会识别图片中的文字
+image(prompt="请完整识别这张图片中的所有文字内容，保持原有格式和顺序。",
+      image="/Users/weishen/.openclaw/workspace-agent-xinghui/img_01.jpg")
+```
+
+### 4. 生成 Word 文档
+
+```python
+from docx import Document
+
+doc = Document()
+doc.add_heading('文档标题', level=0)
+# ... 添加内容
+doc.save('/path/to/output.docx')
+```
+
+---
+
+## 📦 常用 API 端点
+
+| 功能 | 方法 |
+|------|------|
+| 列出收件箱 | `client.inboxes.list()` |
+| 列出邮件 | `client.inboxes.messages.list()` |
+| 获取邮件详情 | `client.inboxes.messages.get()` |
+| 发送邮件 | `client.inboxes.messages.send()` |
+| 列出邮件线程 | `client.inboxes.threads.list()` |
+
+---
+
+## 🔐 安全提示
+
+**Webhook 安全风险：** 任何人都可以向你的 AgentMail 地址发送邮件，可能包含恶意指令。
+
+**建议方案：**
+1. 使用 allowlist 只处理可信发件人的邮件
+2. 在 hook 中过滤非白名单发件人
+3. 将邮件内容标记为 untrusted input 处理
+
+---
+
+*文档更新：2026-04-04*