Gmail 标签整理是做什么的？

将大量 Gmail 历史邮件整理至邮箱主人自己的标签，并让未来的邮件自动归类。

大多数助手中内置的 Gmail 连接器每次调用只能标记一个线程，且没有过滤器 API。这对于处理数千封邮件来说太慢，也无法阻止邮件再次堆积。本技能改用完整的 Gmail MCP 服务器，它提供真正的服务器端过滤器和 50 封邮件的批量处理能力。

首次运行前

安装 MCP 服务器。 参见 install/INSTALL.md。它需要一个 Google Cloud OAuth 桌面客户端和一次浏览器登录。大约需要十分钟，一次即可。
创建规则文件。 将 references/rules-TEMPLATE.md 复制到一个私人文件（模板建议使用 my-rules.md，该文件已包含在 .gitignore 中）并根据账户自身历史填写。切勿凭空发明规则。 参见“学习规则”部分。

该技能奏效的唯一规则

规则是从邮箱主人自己的历史标记中学来的，绝不是发明的。

对于每个发件人或主题，查看该人自己已将该发件人归类到哪个标签，并复制该操作。仅当一个发件人从未出现在其历史中时，才允许进行判断性决定，并将该决定记录在“猜测”部分以便更正。错误的标签修复成本很低；但对 300 封邮件静默应用错误的标签则代价高昂。

第二条规则，是从实践中得出的：内容同样重要，而不仅仅是发件人。 发件人只是一个维度。来自一家健康出版公司的关于金钱的新闻通讯应该同时获得“金钱”标签。一个线程可以带多个标签。

学习规则

询问账户，而不是用户。对于每个标签，查看该标签中已有的内容：

search_emails: label:"<标签名称>"

读取 30 到 50 个结果并记下发件人。该列表即为规则。对每个标签重复此操作。然后使用 list_email_labels 获取标签 ID，这正是 batch_modify_emails 实际需要的参数。

只需执行一次，将其写入规则文件，并在每次运行中持续追加。每次运行都会发现上次未见过的新发件人。

执行一次运行

一次运行是一个有边界、有记录、可逆的工作块。目标为 200 到 300 封邮件。不要试图一次性完成所有工作。

1. 确认过滤器存在。

list_filters

如果规则文件中的过滤器缺失，首先使用 create_filter 逐个标签组创建它们，使用 from: 条件。过滤器是防止问题复发的关键部分。

2. 查找未标记的邮件。

先收件箱：

search_emails: has:nouserlabels in:inbox

待收件箱仅剩刻意保留无标签的邮件后，其余工作移至存档。按日期分页处理，每次移动最早的边界：

search_emails: has:nouserlabels -in:inbox -in:sent -in:draft -in:trash -in:spam -in:chats before:YYYY/MM/DD

每次取 50 到 60 封。将 before: 设置为你刚刚处理的最新结果中最早邮件的日期，下一次调用将从你停止的地方继续。这种方法比分页令牌更可靠，且能抵御中断。

3. 按标签分组，然后批量处理。

将页面中的邮件按标签分组，每组一个邮件 ID 列表，然后为每个标签调用一次 batch_modify_emails，使用 addLabelIds。切勿对每条消息单独调用。

如果某个批次返回 Too many concurrent requests for user，仅对失败的 ID 进行重试。该调用会准确报告哪些 ID 失败。

4. 记录日志。 向撤销日志追加一条带日期的条目。参见“撤销日志”部分。

切勿触碰

一次性登录代码、魔法链接、密码重置和安全警报。 这些保持无标签，且绝不被移至垃圾箱。如果用户需要快速找到一个登录验证码，标签帮不上忙，而垃圾箱规则反而有害。
邮箱主人自己“绝不标记”列表上的任何内容。 用户有一些他们希望保持无标签的出版物和发件人，他们会告诉你。一旦他们提到，立即将其写入规则文件，使用他们自己的措辞。
家人和私人邮件，除非邮箱主人自己已经标记了该发件人。

处理垃圾邮件

仅在邮箱主人明确授权的范围内，且仅根据主题匹配进行垃圾箱处理。安全的默认集合是服务条款和隐私政策更新通知：

subject:("terms of service" OR "terms and conditions" OR "terms of use"
         OR "privacy policy" OR "user agreement")
negatedQuery: subject:(code OR verification OR verify OR "security alert" OR password)

否定查询不可省略。没有它，“验证您的账户 - 已更新条款”这样的邮件会被移至垃圾箱。

Gmail 的垃圾箱可在 30 天内恢复。本技能不会执行任何删除操作。

撤销日志

每次运行追加一条带日期的条目。它是使工作可撤销和可审查的记录：

日期和运行编号。
过滤器是否存在，以及创建了哪些。
标记的邮件数量，以及每个标签的计数。
判断性决定，注明名称。哪些发件人没有先例，做出了什么决定，以及原因。这是稍后需要更正的部分。
确认保持无标签且未触碰的内容。

参见 examples/undo-log-EXAMPLE.md。即使运行过程很平淡也要编写日志。特别是平淡的时候。

过滤器不处理旧邮件

这总是会让人困惑，所以要向用户明确说明：

Gmail 过滤器只对创建后到达的邮件生效。 它永远不会回溯处理历史邮件。因此，工作的两个部分是真正独立的：过滤器自动处理未来，而存档积压必须按上面描述的方式，逐次手动处理。

这意味着：经过几次运行发现真正的高量发件人后，回去为它们也添加过滤器。否则这些发件人继续发送无标签邮件，积压会在你身后重新形成。

撤销一次运行

读取该运行的撤销日志条目，然后使用 batch_modify_emails 并带上 removeLabelIds，应用相同的邮件 ID。对于已被移至垃圾箱的邮件，untrash 可在 30 天内使用。这就是为什么日志记录计数和原因，而不是仅仅记录“已完成”。

Gmail 标签整理