email-whiz

Email Whiz

通过 MCP 管理 Gmail 收件箱。优先并行处理，针对大型收件箱优化。

---

规范术语

术语	定义
5-bucket	DO / DELEGATE / DEFER / REFERENCE / NOISE —— 五个分类桶（历史上称为“4D+N”）
inbox zero	收件箱中只剩下今天需要处理的事项
fast-lane	仅依据发件人和主题进行分类，不读取邮件内容
security gate	归档前扫描 NOISE 中的主题关键词（捕获双重验证、密码重置邮件）
session cache	Phase 0 结果的本地缓存（TTL 为 1 小时），位于 `~/.{gemini
tier	收件箱大小类别：Small（<50）/ Medium（50-500）/ Large（500-5k）/ Massive（5k+）
quick	跳过 Phase 0 的轻量模式修饰前缀
combo	串联两个共享已发现状态的模式：<mode> + <mode>
mega-wave	将 10-15 次独立工具调用打包在一起的单条消息
baseline	滚动 30 天的收件箱数量平均值；破产触发条件相对于此值计算
auto-rule	根据行为模式分析创建的 Gmail 过滤器
VIP	会收到持续回复和高优先级处理的发件人
engagement	对某发件人的回复率：已发送回复数 / 已收到邮件数
confidence	HIGH >80% / MEDIUM 50-80% / LOW <50% —— 决定自动规则的操作
memory	存储在 `~/.{gemini
correction	用户不同意自动分类时提供的纠正，并作为记忆覆盖项保存
staleness	记忆条目超过阈值未确认或使用（VIP：90 天，覆盖项：60 天）

---

分派

$ARGUMENTS	操作
triage	使用 fast-lane + 5-bucket 对收件箱分类，按类别批量处理
inbox-zero	每日/每周例行处理、进度跟踪、基线破产检测
filters	基于模式检测提供过滤器建议，并进行置信度评分
auto-rules	行为分析 → 根据模板自动创建 Gmail 过滤器
analytics	邮件量趋势、回复时间、发件人频率、时间模式
newsletters	订阅审查 + 退订计划
labels	分类体系分析、合并/重命名/删除建议
search <goal>	自然语言 → Gmail 搜索查询
senders	识别 VIP + 噪声邮件
digest	最近重要邮件摘要
cleanup	归档候选邮件、重复项检测、批量归档
audit	收件箱完整健康报告，包含评分和行动计划
quick search 或 quick digest	跳过 Phase 0，直接运行模式。只有 search 和 digest 兼容 quick
<mode> + <mode>	串联模式，共享已发现的状态（triage + filters）
(empty)	自动扫描：运行 Phase 0 + 账户分析，并提供按优先级排序的行动计划

分类门控： 如果 $ARGUMENTS 可能匹配多种模式，请先询问用户想要哪一种，再继续。

---

混合模式协议

读取操作 — 立即执行： gmail_search_emails、gmail_read_email、gmail_list_email_labels、gmail_list_filters、gmail_get_filter

写入操作 — 执行前确认： 单项：gmail_modify_email、gmail_delete_email、gmail_create_label 批量：gmail_batch_modify_emails、gmail_batch_delete_emails 标签：gmail_update_label、gmail_delete_label、gmail_get_or_create_label 过滤器：gmail_create_filter、gmail_create_filter_from_template、gmail_delete_filter

除非用户明确提出要求，否则禁止删除邮件。 切勿主动调用 gmail_delete_email 或 gmail_batch_delete_emails。始终改用归档。只有用户直接说“删除”时才使用删除工具——即便如此，也要先使用破坏性操作警告模板（输入“DELETE”确认）。

确认格式： 参见 templates.md。写入操作前，始终说明范围、数量和可逆性。

---

并行化规则

1. 相互独立的工具调用放在同一条消息中。 将相互独立的调用分成多轮执行属于错误。
2. Phase 0 与模式的首批查询合并——可以合并时，绝不要分两轮顺序执行。
3. 针对不相交 ID 集合的批量操作：并行执行。 NOISE + REFERENCE + DEFER = 1 条消息，3 次调用。
4. 分析/审计：大规模并发——在 1 条消息中执行 10-15 条搜索查询。
5. gmail_read_email：每条消息批量读取 5-8 封（完整邮件内容较长）。
6. 过滤器创建：冲突检查通过后并行执行。
7. 组合模式边界：顺序执行（存在数据依赖）。但模式 2 跳过 Phase 0。
8. 每条消息最多 15-20 次调用。 超出此范围时，单个 429 会影响整个调用组。
9. **遇到 429 时：**保留已完成的结果，改为顺序执行，每次间隔 2 秒。60 秒内出现 3 次 429 → 暂停 60 秒。

详情：efficiency-guide.md § 并行调用映射。

---

Phase -1：加载记忆（quick 前缀时跳过）

探索前加载用户的长期记忆。每个会话执行一次。

!uv run python scripts/memory.py load --mode <current_mode>

与 Phase 0 缓存检查在同一条消息中合并（两者都是本地文件读取，不会调用 API）：

!uv run python scripts/memory.py load --mode triage
!uv run python scripts/inbox_snapshot.py cache load

如果存在记忆，则将其整合到会话中：

• VIP 发件人 → 快速归类为 DO（第 1 轮）
• 噪声发件人 → 快速归类为 NOISE（第 1 轮）
• 更正 → 最高优先级：覆盖任何冲突的快速规则
• 分流覆盖规则 → 在通用决策树前应用
• 过滤器历史记录 → 跳过此前被拒绝的过滤器建议
• 标签偏好 → 创建标签时采用首选命名
• 收件箱模式 → 调整分析/审计中的预期

如果存在记忆，则每个会话运行一次 !uv run python scripts/memory.py prune。仅当清理条目数 > 0 时报告。

---

Phase 0：发现（quick 前缀时跳过）

前置条件： 除 quick 模式外，先运行 Phase -1（加载记忆）。

0a：会话缓存检查

!uv run python scripts/inbox_snapshot.py cache load 如果缓存有效（不到 1 小时）→ 使用缓存的标签、过滤器和层级。跳转到相应模式。

0b：并行发现 + 模式融合（缓存未命中）

在同一条消息中发出 Phase 0 调用以及模式的首批查询：

核心发现（始终执行）：

1. gmail_list_email_labels → 标签名称/ID 映射 + INBOX 的 messagesTotal/messagesUnread
2. gmail_list_filters → 现有过滤器条件
3. gmail_search_emails → "in:inbox is:unread"（maxResults: 10）→ 取样

模式专属的附加查询（同一条消息）：

• 分流：+ gmail_search_emails "is:unread"（maxResults: 每层级）
• Inbox Zero：+ "is:unread newer_than:1d" + "label:_deferred"
• 分析：+ 4 次每周邮件量查询（大规模并发）
• 审计：+ 新闻简报数量 + 已发送邮件数量 + 逾期数量（大规模并发）
• 清理：+ 4 次过期检测查询

0c：层级评估

使用 INBOX 标签的 messagesTotal（不要使用 resultSizeEstimate——它不可靠）。

收件箱大小	层级	maxResults	策略
<50	小型	50	全部处理
50-500	中型	100	抽查近期邮件和未读邮件
500-5000	大型	200	优先处理重要邮件，按日期范围拆分
5000+	超大型	200	按日期范围并行查询，基线破产级

为什么 maxResults 为 100-200： MCP 服务采用 N+1 获取模式（每个结果都会触发一次单独的 API 调用）。maxResults=500 ≈ 501 次 API 调用 ≈ 2505 个配额单位。200 ≈ 1005 个配额单位。

超大型层级： 按日期范围拆分（每段 30 天），并行发出所有分段查询。始终在常规扫描的同时查询 is:important is:unread。MCP 服务不支持 pageToken——按日期范围拆分是唯一的分页方式。

0d：写入会话缓存

!uv run python scripts/inbox_snapshot.py cache save --labels '...' --filters '...' --inbox-count N --unread-count M --tier TIER 任何写入操作后（创建过滤器/标签、批量修改）都要使缓存失效。

始终使用发现的标签名称——绝不要创建与现有分类体系冲突的名称。

---

自动扫描（空参数调用）

不带参数调用时，执行智能账户扫描，而不是显示菜单。

步骤 1：超级波次发现（1 条消息）

将阶段 0 的核心发现与 6 个分析查询合并到一条消息中（约 10 次调用）：

• 阶段 0 核心：gmail_list_email_labels + gmail_list_filters + gmail_search_emails "in:inbox is:unread"（maxResults：10）
• 收件箱触达范围：gmail_search_emails "in:inbox has:nouserlabels newer_than:7d"（maxResults：10）
• 新闻邮件：gmail_search_emails "in:inbox (list:* OR subject:newsletter)"（maxResults：50）
• 过期的延后邮件：gmail_search_emails "label:_deferred older_than:7d"（maxResults：10）
• 积压邮件：gmail_search_emails "in:inbox is:unread older_than:7d"（maxResults：10）
• 清理候选邮件：gmail_search_emails "in:inbox (subject:receipt OR subject:confirmation) older_than:30d"（maxResults：10）
• !uv run python scripts/inbox_snapshot.py trend --days 7
• !uv run python scripts/inbox_snapshot.py baseline --days 30

步骤 2：分析与评分

根据结果计算：层级（依据 INBOX 的 messagesTotal）、破产级别（与基线比较）、分流需求（未读积压）、过滤器机会（噪声发件人群组）、新闻邮件负担、清理潜力、延后邮件堆积情况。

步骤 3：呈现行动计划

使用自动扫描报告模板（templates.md § 自动扫描报告）。提供 3-5 条按优先级排序的建议，并估算影响。每条建议对应一种模式。

提供以下选项：回复编号、模式名称、all（按顺序串联排名前 3 的建议，并共享阶段 0 状态）或 menu（显示完整模式列表）。

---

编排模式

此技能在 context: fork 中运行。内部应用以下模式：

拆解门槛（每种模式执行前）

1. 列出该模式所需的所有工具调用
2. 分类：独立（不同查询）或依赖（需要先前结果）
3. 将所有独立调用打包到尽可能少的消息中
4. 绝不要按顺序执行独立调用

各模式的波次模式

模式	波次 1	波次 2	波次 3	总计
自动扫描	阶段 0 + 6 项分析（约 10 次）	评分（0 次工具调用）	—	约 10 次
分流	阶段 0 + 快速通道（约 5 次）	3 次 batch_modify	5-8 次 read_email	约 16 次
分析	阶段 0 + 超级波次（约 15 次）	按实体分批（约 12 次）	—	约 27 次
审计	阶段 0 + 超级波次（约 14 次）	按实体分批（约 20 次）	—	约 34 次
清理	阶段 0 + 4 个过期查询（约 7 次）	batch_modify（约 3 次）	—	约 10 次
过滤器	阶段 0 + 发件人/主题（约 6 次）	create_filter（约 5 次）	—	约 11 次
收件箱归零	阶段 0 + 未读/延后邮件（约 5 次）	批量操作（约 3 次）	—	约 8 次
组合	阶段 0 + 模式 1	模式 1 操作	刷新 + 模式 2	不定

---

模式：分流

三轮分类。详情：triage-framework.md § 快速通道、efficiency-guide.md。

第 1 轮：快速通道（不读取邮件正文）

仅根据搜索结果中的发件人 + 主题 + 摘要进行分类：

• 记忆中的更正 → 覆盖任何冲突规则（最高优先级）
• 记忆中的 VIP 发件人 → 处理（置信度来自记忆）
• 记忆中的噪声发件人 → 噪声（置信度来自记忆）
• noreply@*、notifications@*、calendar-notification@* → 噪声
• 已知 VIP 发件人（来自会话缓存）→ 处理
• 主题为 [FYI]/[INFO]/新闻简报/收据/确认 → 参考
• 主题为 [ACTION]/[URGENT]/截止日期 → 处理
• 未匹配 → 未决定

第 1.5 轮：安全检查（归档噪声前必须执行）

扫描所有噪声邮件的主题/摘要，查找安全关键词：password reset、verify your、sign-in、unusual activity、2FA、account locked、verification code、one-time password、security alert、new device、suspicious login、recovery phone、two-step verification、confirm your identity、new sign-in method。匹配到任何关键词 → 从噪声中移出，转入审核。此外：任何 noreply@ 邮件，只要 newer_than:7d → 转入审核（登录通知不会过期；验证码会过期，但仍应显示）。

第 2 轮：批量操作（全部放在一条消息中）

前置条件： 如果尚未在第 0 阶段解析 _reference 和 _deferred，则调用 gmail_get_or_create_label。

同时发起 3 次 gmail_batch_modify_emails 调用（ID 集合互不重叠，可并行安全执行）：

• 噪声 ID → 移除 INBOX
• 参考 ID → 添加 _reference，移除 INBOX
• 延后处理 ID → 添加 _deferred，移除 INBOX

第 3 轮：检查邮件正文（仅处理未决定和审核邮件）

每条消息批量调用 5-8 次 gmail_read_email。应用完整的 5 类分类。按与第 2 轮相同的并行模式批量处理结果。使用快速通道分类摘要进行报告（显示自动分类占比）。将反复出现的噪声发件人模式列为筛选条件候选项。

---

模式：收件箱清零

结构化习惯系统。详情：inbox-zero-system.md。

每日（5 分钟）： 在 1 条消息中合并第 0 阶段 + is:unread newer_than:1d + label:_deferred。快速分类（5 类）。批量归档噪声和参考邮件。报告：收件箱数量（处理前 → 处理后）。更新进度文件。

每周（15 分钟）： 在 1 条消息中发起 3 个查询：延后邮件检查 + 筛选效果 + 新闻简报检查。清理、重新延后或归档。更新 weekly_reviews。

积压检测： 相对于 30 天基线（而非绝对值）。黄色：高于基线 20-50%。橙色：高于基线 50-100%（积极分类 + 创建筛选条件）。红色：高于基线 >100%（执行完整的积压处理流程）。加速触发条件：连续 2 周以上，每周环比增长 >20%。新用户默认基线为 500，直到积累 7 个以上快照后建立基线。恢复流程请参阅 inbox-zero-system.md。

---

模式：筛选条件

基于模式检测的筛选条件建议。详情：filter-patterns.md。

在 1 条消息中发起发件人聚类、主题模式分析和 gmail_list_filters。为候选项评分：高（数量 ≥20，互动率 <5%）→ 提议创建。中（≥10，<15%）→ 提出建议。低 → 仅展示。创建前检查冲突。获批后：在 1 条消息中发起多个 gmail_create_filter 调用。超大规模：将 90 天拆分为 3 个 30 天片段，并行查询。

---

模式：自动规则

深入分析行为 → 自动创建筛选条件。详情：filter-patterns.md § 自动规则检测。

在 1 条消息中发起发件人分析、主题挖掘和筛选条件获取。超大规模：将 90 天拆分为 3 个 30 天日期范围片段，并行发起全部查询。按置信度评分。提供自动规则报告。高：经确认后调用 gmail_create_filter_from_template。中：逐项审核。创建时：在 1 条消息中创建多个筛选条件。2 周后安排学习循环。

---

模式：分析

通过 mega-wave 分析电子邮件通信指标。详情：analytics-guide.md。

在 1 条消息中发出所有查询：每周 4 次的邮件量 + 已发送数量 + 收件箱触达率 + 回复率 + 逾期邮件 + 发件人频率 + 标签分布（约 12 次调用，减少约 65% 的消息）。判断邮件量趋势（增长／稳定／下降）。计算收件箱触达率（良好：<30%）。按邮件量列出排名前 20 的发件人，并提供互动矩阵。呈现完整的分析报告。

---

模式：新闻简报

审查订阅。在 1 条消息中发出 list:* + subject:newsletter。估算每项订阅的发送频率和阅读率。分类为：取消订阅／保留／过滤。显示取消订阅链接。获得批准后：创建过滤器或提供取消订阅 URL。详情：workflows.md § 取消订阅策略。

---

模式：标签

分析标签体系。gmail_list_email_labels 会返回每个标签的 messagesTotal／messagesUnread。要按最近 30 天的活动分类，请分批发出每批 10–15 个搜索查询，每个标签各一个。查找：重复／同义标签、过时标签（90 天以上无邮件）、需要建立层级结构的扁平结构。建议：合并／重命名／删除／重组。合并时：使用 gmail_batch_modify_emails 迁移邮件，然后使用 gmail_delete_label。详情：workflows.md § 标签层级结构。

---

模式：搜索

兼容快速模式（无需第 0 阶段）。将自然语言转换为 Gmail 搜索查询。解析意图（谁／什么／何时／状态），映射到运算符，添加排除条件，展示查询、说明和预期匹配结果。提供执行查询的选项。详情：filter-patterns.md § Gmail 搜索运算符。

---

模式：发件人

识别 VIP 和噪声发件人。在 1 条消息中发出示例搜索和每位发件人的回复率查询（如果排名靠前的发件人超过 12 位，则将回复率查询拆分为 2 条消息，以不超过调用上限）。VIP：回复率 >50% 或经常加星标。噪声：邮件量 >10，互动率为 0%。呈现发件人报告。获得批准后：创建 VIP 过滤器（标记为重要）或噪声过滤器。详情：triage-framework.md § 发件人快捷操作、workflows.md § VIP 管理。

---

模式：摘要

兼容快速模式（无需第 0 阶段）。搜索 is:important newer_than:3d（或 is:starred OR is:unread is:important）。提取每封邮件的发件人、主题和一行摘要。分类为：需回复／供参考／待读。呈现摘要报告。提供选项："open N" | "archive fyi"。详情：templates.md § 摘要。

---

模式：清理

归档候选邮件。在 1 条消息中发出全部 4 个过时邮件检测查询：收据／确认邮件 older_than:30d + 旧新闻简报 older_than:30d + 已过期的延后处理邮件 older_than:14d + 已读完且无标签的邮件 older_than:60d。并行调用 gmail_batch_modify_emails，批量归档所有结果。仅归档，绝不删除。详情：workflows.md § 批量操作。

---

模式：审计

通过 mega-wave 全面检查收件箱健康状况。在 1 条消息中发出 11 个基础查询（每个标签和每个发件人的查询作为第二波执行）：收件箱邮件数、未读比例、过滤器数量、收件箱触达率、回复率、逾期邮件、新闻简报邮件量、延后处理邮件堆积、已发送邮件量、标签健康状况、发件人前 20 名（减少约 70% 的消息）。根据收件箱触达率、过滤器覆盖率和标签健康状况评分，范围为 0–100。找出 3 个最容易快速见效的改进点。生成行动计划。详情：analytics-guide.md、templates.md § 完整审计。

---

范围边界

适用于： Gmail 分拣、收件箱清零、过滤器、自动规则、分析、新闻简报、标签、搜索、发件人、摘要、清理、审计。 不适用于： 日历、Google Drive、非 Gmail 服务、实时监控、CRM。

---

参考文件索引

文件	内容	加载时机
references/efficiency-guide.md	缓存、并行调用、层级、MCP 约束、快速通道、分页	所有模式
references/triage-framework.md	5 类决策树、快速通道规则、安全检查、批量处理	triage、inbox-zero
references/filter-patterns.md	Gmail 运算符、过滤器模板、自动规则算法、学习循环	filters、auto-rules、search
references/workflows.md	破产处理、VIP、批量操作、标签层级、取消订阅、组合模式	cleanup、labels、senders、newsletters
references/templates.md	所有确认、报告和执行结果模板	每种模式
references/inbox-zero-system.md	每日/每周例行工作、进度架构、基线破产处理	inbox-zero
references/analytics-guide.md	邮件量、响应时间、发件人频率、时间分析方法	analytics、audit
references/tool-reference.md	全部 18 个 Gmail MCP 工具签名、参数、MCP 约束	选择工具时

脚本：

脚本	用途	运行时机
scripts/inbox_snapshot.py save --inbox-count N	保存收件箱数量快照	每次 inbox-zero 检查后
scripts/inbox_snapshot.py trend --days 7	计算收件箱趋势	analytics 模式期间
scripts/inbox_snapshot.py baseline --days 30	计算用于破产处理的滚动基线	inbox-zero 期间
scripts/inbox_snapshot.py cache load	加载会话缓存（TTL 为 1h）	Phase 0 step 0a
scripts/inbox_snapshot.py cache save --labels --filters --inbox-count --unread-count --tier	写入会话缓存	Phase 0 step 0d
scripts/inbox_snapshot.py cache clear	使会话缓存失效	写入操作后
scripts/memory.py load --mode MODE	加载按模式筛选的用户记忆	Phase -1
scripts/memory.py save-sender	保存 VIP 或噪声发件人	triage/senders 后
scripts/memory.py save-correction	记录用户的分类覆盖	用户更正时
scripts/memory.py prune	移除过期的记忆条目	每个会话一次
scripts/memory.py stats	记忆摘要计数	诊断

---

关键规则

1. 在任何工作流开始前运行 Phase 0 发现流程——绝不假设标签／筛选器状态（quick 模式除外）
2. 确认所有写入操作——调用前展示范围、数量和可逆性
3. 批量处理相似操作——适用 gmail_batch_modify_emails 时，绝不循环调用 gmail_modify_email
4. 保留现有分类体系——可以提出改进建议，但绝不擅自重命名
5. 创建筛选器前检查冲突——先调用 gmail_list_filters
6. 为所有筛选器／规则建议提供置信度评分
7. 为每项批量操作提供回滚指导
8. 妥善处理 MCP 故障——参见 efficiency-guide.md § 错误恢复
9. 显示退订链接——让清理新闻邮件的操作切实可行
10. 优先处理快速见效的事项——所有报告都先列出影响大、耗时少的事项
11. 每次例行处理后更新收件箱归零进度
12. 除非用户明确要求删除邮件，否则绝不删除。所有模式下默认归档。用户确实要求删除时，在调用 gmail_delete_email 或 gmail_batch_delete_emails 前，使用破坏性操作警告模板（确认词为 “DELETE”）
13. 在同一条消息中发起所有相互独立的工具调用——将独立调用按顺序逐个执行属于错误
14. 在读取内容前使用快速通道分类——仅凭发件人和主题即可完成 60% 以上的分类
15. 归档 NOISE 前，始终运行安全检查——扫描主题中是否包含 2FA／密码／安全相关关键词
16. 在 Phase 0 前检查会话缓存。任何写入操作后使缓存失效（gmail_create_label、gmail_get_or_create_label、gmail_create_filter、gmail_create_filter_from_template、gmail_batch_modify_emails、gmail_batch_delete_emails）。
17. maxResults 设为 100-200（而非 500）——MCP 的 N+1 模式意味着 500 条结果约等于 501 次 API 调用
18. 破产触发条件以 30 天基线为准，而非绝对阈值
19. 在 Phase 0 前加载用户记忆（Phase -1）。在交付主要输出后再保存记忆——绝不能因写入记忆而阻碍模式的核心工作流

---

记忆保存触发条件

在自然的决策节点保存记忆。绝不要为保存记忆而拖慢模式——始终在交付模式的主要输出后再保存。

触发条件	命令
分类：用户覆盖快速通道分类	memory.py save-correction --mode triage --what "..." --correction "..." --pattern "..." --action BUCKET
分类：NOISE 批量归档成功	memory.py save-sender --email X --type noise --reason "..." --source triage（在 1 条消息中批量保存多个）
发件人：识别出 VIP（回复率 >50%）	memory.py save-sender --email X --type vip --name "..." --reason "..." --source senders
筛选器：成功创建筛选器	memory.py save-filter --filter-id ID --description "..." --effectiveness high
筛选器：用户拒绝某项建议	memory.py save-filter --filter-id rejected --description "..." --effectiveness failed
标签：用户说明命名偏好	memory.py save-labels --convention "..." --structure "..."
分析：已计算邮件量模式	memory.py save-patterns --daily-volume N --busy '[...]'
任意模式：用户纠正某项分类	memory.py save-correction ...

当某个模式产生多条记忆时，在同一条消息中批量发起多个保存调用（例如，分类识别出 5 个噪声发件人）