gmail

Gmail

使用 Gmail 管理、搜索和整理邮件。

安装

依赖项：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

验证设置

安装后，验证技能是否已正确配置：

$SKILL_DIR/scripts/gmail.py check

此命令会检查：

• Python 依赖项（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 身份验证配置
• 与 Gmail API 的连接

如果有任何缺失，检查命令会提供设置说明。

身份验证

Gmail 使用 OAuth 2.0 进行身份验证。完整设置说明请参阅：

1. GCP 项目设置指南 - 创建项目并启用 Gmail API
2. Google OAuth 设置指南 - 配置凭据

快速开始

1. 创建 ~/.config/agent-skills/google.yaml：

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. 运行 $SKILL_DIR/scripts/gmail.py check 以触发 OAuth 流程并验证设置。

遇到权限范围或身份验证错误时，请参阅 OAuth 故障排除指南。

命令

各命令的读写分类请参阅 permissions.md。

check

验证配置和连接。

$SKILL_DIR/scripts/gmail.py check

此命令会验证：

• 是否已安装 Python 依赖项
• 是否已配置身份验证
• 是否可以连接到 Gmail API
• 显示你的电子邮件地址和邮箱统计信息

auth setup

为自定义 OAuth 流程保存 OAuth 2.0 客户端凭据。

$SKILL_DIR/scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

凭据会保存到 ~/.config/agent-skills/gmail.yaml。

auth reset

清除已保存的 OAuth 令牌。下一个需要身份验证的命令会自动触发重新身份验证。

$SKILL_DIR/scripts/gmail.py auth reset

遇到权限范围或身份验证错误时使用此命令。

auth status

显示当前 OAuth 令牌信息，不会发起 API 调用。

$SKILL_DIR/scripts/gmail.py auth status

显示内容：是否已保存令牌、已授予的权限范围、刷新令牌是否存在、令牌过期时间以及客户端 ID。

messages list

列出符合查询条件的邮件。

# List recent messages
$SKILL_DIR/scripts/gmail.py messages list

# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected]" --max-results 20

参数：

• --query：Gmail 搜索查询（可选）
• --max-results：最大结果数（默认值：10）

搜索查询示例：

完整的 Gmail 搜索语法请参阅 gmail-queries.md。

常用查询：

• is:unread - 未读邮件
• from:[email protected] - 来自发件人的邮件
• subject:meeting - 主题包含关键词的邮件
• has:attachment - 包含附件的邮件
• after:2024/01/01 - 指定日期之后的邮件
• label:important - 带有标签的邮件

messages get

按 ID 获取邮件。

# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal

参数：

• message_id：邮件 ID（必填）
• --format：邮件格式（full、minimal、raw、metadata），默认值：full

messages mark-read

移除 UNREAD 标签，将一封或多封邮件标记为已读。

# Mark a single message
$SKILL_DIR/scripts/gmail.py messages mark-read MESSAGE_ID

# Mark multiple messages
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 MSG2 MSG3

# Mark all unread messages from a sender
$SKILL_DIR/scripts/gmail.py messages mark-read --query "is:unread from:[email protected]"

# Combine IDs and query
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 --query "is:unread label:updates"

参数：

• message_ids：一个或多个邮件 ID（使用 --query 时可选）
• --query：用于查找要标记为已读邮件的 Gmail 搜索查询
• --max-results：从 --query 的结果中标记的邮件数上限（默认值：100）

threads get

获取完整的对话串，并按时间顺序显示其中的所有邮件。对于来自 Google Groups 的邮件，还会提供可分享的永久链接，使用 d/msgid URL 格式。

# Get full thread
$SKILL_DIR/scripts/gmail.py threads get THREAD_ID

参数：

• thread_id：对话串 ID（必填）

send

发送电子邮件。

# Send simple email
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Hello" \
  --body "This is the message body"

# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc [email protected] \
  --bcc [email protected]

# Send from a markdown file with frontmatter
$SKILL_DIR/scripts/gmail.py send --from-file update.md

# Send from file with CLI overrides
$SKILL_DIR/scripts/gmail.py send --from-file update.md --to [email protected]

# Reply to a message in-thread
$SKILL_DIR/scripts/gmail.py send --reply-to MESSAGE_ID --body "Thanks, got it."

参数：

• --to：收件人电子邮件地址（除非使用 --from-file 或 --reply-to，否则必填）
• --subject：电子邮件主题（除非使用 --from-file 或 --reply-to，否则必填）
• --body：电子邮件正文文本（除非使用 --from-file，否则必填）
• --from-file：包含 YAML frontmatter 的 Markdown 文件（格式见下文）
• --cc：抄送收件人（逗号分隔）
• --bcc：密送收件人（逗号分隔）
• --reply-to：要回复的邮件 ID（在同一邮件线程中发送，并自动填入收件人和主题）

CLI 标志会覆盖 frontmatter 中的值。使用 --from-file 时，Markdown 正文会转换为 HTML，并以 multipart/alternative 格式发送（HTML + 纯文本 备用版本）。

Markdown 文件格式：

---
to: [email protected]
cc: [email protected]
bcc: [email protected]
subject: Weekly Update
---

# Status Update

Here's what happened this week:

- **Feature A** shipped to production
- Fixed the [login bug](https://jira.example.com/DEMO-123)

| Task | Status |
|------|--------|
| Deploy | Done |

drafts list

列出草稿邮件。

# List drafts
$SKILL_DIR/scripts/gmail.py drafts list

# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20

参数：

• --max-results：结果数量上限（默认值：10）

drafts create

创建草稿邮件。

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Draft Subject" \
  --body "This is a draft message"

# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc [email protected]

# Create a reply draft in-thread
$SKILL_DIR/scripts/gmail.py drafts create --reply-to MESSAGE_ID --body "I'll look into this."

# Create draft from a markdown file
$SKILL_DIR/scripts/gmail.py drafts create --from-file update.md

参数：

• --to：收件人电子邮件地址（除非使用 --from-file，否则必填）
• --subject：电子邮件主题（除非使用 --from-file，否则必填）
• --body：电子邮件正文文本（除非使用 --from-file，否则必填）
• --from-file：包含 YAML frontmatter 的 Markdown 文件（格式与 send 相同）
• --cc：抄送收件人（逗号分隔）
• --bcc：密送收件人（逗号分隔）

drafts send

发送草稿邮件。

# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

参数：

• draft_id：要发送的草稿 ID（必填）

labels list

列出所有 Gmail 标签。

# List labels
$SKILL_DIR/scripts/gmail.py labels list

labels create

创建新标签。

# Create label
$SKILL_DIR/scripts/gmail.py labels create "Project X"

参数：

• name：标签名称（必填）

示例

验证设置

$SKILL_DIR/scripts/gmail.py check

查找未读邮件

$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

搜索来自某位发件人的邮件

$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected]" --max-results 5

快速发送电子邮件

$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Quick Question" \
  --body "Do you have time for a meeting tomorrow?"

创建并发送草稿

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Weekly Update" \
  --body "Here's this week's update..."

# List drafts to get the ID
$SKILL_DIR/scripts/gmail.py drafts list

# Send the draft
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

使用标签整理

# Create a label
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"

# List all labels
$SKILL_DIR/scripts/gmail.py labels list

高级搜索

# Find emails with attachments from last week
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"

# Find important emails from specific sender
$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected] is:important"

# Find emails in a conversation
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"

Gmail 搜索查询语法

常用搜索运算符：

运算符	说明	示例
from:	发件人电子邮件地址	from:[email protected]
to:	收件人电子邮件地址	to:[email protected]
subject:	主题包含	subject:meeting
label:	有此标签	label:important
has:attachment	有附件	has:attachment
is:unread	未读邮件	is:unread
is:starred	已加星标的邮件	is:starred
after:	此日期之后	after:2024/01/01
before:	此日期之前	before:2024/12/31
newer_than:	在此时间段内较新	newer_than:7d
older_than:	在此时间段内较旧	older_than:30d

运算符之间用空格组合（隐式 AND），也可使用 OR：

# AND (implicit)
from:[email protected] subject:meeting

# OR
from:[email protected] OR from:[email protected]

# Grouping with parentheses
(from:[email protected] OR from:[email protected]) subject:meeting

完整参考请参阅 gmail-queries.md。

错误处理

身份验证错误和范围错误不可重试。 如果命令因身份验证错误、权限范围不足错误或权限被拒绝错误（退出代码 1）而失败，请停止并告知用户。不要重试或尝试自主修复问题——这些错误需要用户交互（基于浏览器的 OAuth 授权）。请引导用户查看 OAuth 故障排除指南。

可重试错误：速率限制（HTTP 429）和临时服务器错误（HTTP 5xx）在短暂等待后重试可能会成功。其他所有错误都应报告给用户。

模型建议

此技能会进行需要结构化输入/输出的 API 调用。建议使用具备标准能力的模型。