gmail-label

Gmail 自动标签

目标

获取收件箱邮件，通过并行子 Agent 将其分类为 Action Required / Waiting On / Reference，然后通过 Gmail API 批量应用标签。

脚本

• ./scripts/gmail_label_fetch.py - 将邮件摘要作为紧凑的 JSON 获取
• ./scripts/gmail_label_split.py - 将邮件拆分为 N 个区块，以便并行分类
• ./scripts/gmail_label_merge.py - 将已分类的区块合并为单个 labels.json
• ./scripts/gmail_label_apply.py - 批量应用邮件分类标签

子 Agent

• email-classifier — 定义于 .claude/agents/email-classifier.md
• 模型：Sonnet 4.5（快速且经济高效的分类）
• 每个子 Agent 读取一个区块，并写入一个分类结果文件

流程（并行 — 默认）

步骤 1：获取邮件

python3 .claude/skills/gmail-label/scripts/gmail_label_fetch.py \
  --account ACCOUNT --query "in:inbox" --limit 100 --output .tmp/emails.json

步骤 2：拆分为区块

python3 .claude/skills/gmail-label/scripts/gmail_label_split.py \
  --input .tmp/emails.json --chunks 10 --output-dir .tmp/chunks

步骤 3：并行分类（启动 10 个子 Agent）

在后台启动 10 个 email-classifier 子 Agent，每个负责一个区块。每个子 Agent：

• 读取 .tmp/chunks/chunk_N.json
• 对每封邮件进行分类
• 写入 .tmp/chunks/classified_N.json

使用 run_in_background: true 和 model: "sonnet" 的 Task 工具。一次性在同一条消息中启动全部 10 个，以实现真正的并行：

For each chunk 0-9, spawn a Task with:
  subagent_type: "email-classifier"
  model: "sonnet"
  run_in_background: true
  prompt: "Read /absolute/path/.tmp/chunks/chunk_N.json, classify each email, write results to /absolute/path/.tmp/chunks/classified_N.json"

重要：不要使用 TaskOutput 读取子 Agent 的结果。 子 Agent 会将结果写入文件 — 主 Agent 无需查看分类数据。读取 TaskOutput 会占满上下文窗口，并在批次较大（500 封以上邮件）时导致“提示词过长”错误。

请改为轮询文件是否存在：

# Wait until all classified files exist (timeout after 120s)
for i in $(seq 0 9); do
  while [ ! -f ".tmp/chunks/classified_$i.json" ]; do sleep 2; done
done

然后直接继续步骤 4（合并）。

步骤 4：合并分类结果

python3 .claude/skills/gmail-label/scripts/gmail_label_merge.py \
  --input-dir .tmp/chunks --output .tmp/labels.json

步骤 5：应用标签

python3 .claude/skills/gmail-label/scripts/gmail_label_apply.py \
  --account ACCOUNT --input .tmp/labels.json

分类指南

Action Required：

• 需要核实的安全警报
• 即将到期且有截止日期的信用卡／域名续订
• 提出问题的 Slack @提及
• 需要问候的新团队成员（Slack 加入通知）
• 需要回复的客户邮件
• 商家信息更新（Google Business Profile、Bing Places）
• Stripe 需要采取操作的通知

Waiting On：

• 等待回复的外发销售邮件
• 等待解决的支持工单
• 已发送、等待回复的提案

Reference：

• 营销简报（DigitalMarketer 等）
• 慈善／非营利组织简报（RAPS 等）
• Google Business Profile 绩效报告
• 促销优惠（Blinkist、销售等）
• 平台更新通知（Google Play、Apify 等）
• 确认码（已使用）
• 房地产简报（Westbank 等）
• 游戏账号邮件（Riot Games 等）
• 资讯类安全警报（已开启 2FA 等）
• 健康提示
• 法律／政策更新通知

账号注册表

账号存储在工作区根目录的 gmail_accounts.json 中。每个账号需要：

• email - Gmail 地址
• token_file - OAuth 令牌路径

添加新账号

python3 .claude/skills/gmail-inbox/scripts/gmail_multi_auth.py --account ACCOUNT_NAME --email EMAIL

性能

• 串行流程：100 封邮件约需 36 秒（获取 1 秒 + 分类 34 秒 + 应用 1 秒）
• 并行流程：100 封邮件约需 30 秒（分类 19 秒 + 合并不到 1 秒 + 应用约 10 秒）
• 分类是瓶颈；10 个并行子 Agent 可将耗时从 34 秒缩短至 19 秒（提速约 1.8 倍）
• Agent 启动开销（约 4 秒的错峰启动）限制了理论收益
• 应用步骤的耗时可能因 Gmail API 限流而有所不同

---

架构

输入

名称	类型	必填	描述
account	string	是	注册表中的 Gmail 账号名称
query	string	否	Gmail 搜索查询（默认：'in:inbox'）
limit	integer	否	要分类的邮件数量上限（默认：100）
chunks	integer	否	并行分类区块数（默认：10）

输出

名称	类型	描述
labels_applied	object	各类别的数量：Action Required、Waiting On、Reference

凭据

名称	来源
credentials.json	文件
token_*.json	文件（自动生成）

可组合使用

与此工具适合串联使用的技能：gmail-inbox

费用

用于分类的 Claude Sonnet API