email

邮件

使用 Spark CLI 阅读邮件，所有邮件更改都通过 Gmail 连接器进行，除非用户要求在 Spark 中保存草稿。由用户决定如何处理邮件以及何时处理。日历事件和空闲时间请使用 /calendar。

何时阅读邮件

只有当用户提出的邮件任务需要读取邮件时，才通过任一工具列出、搜索或阅读邮件。邮箱是私密的，因此是否读取由用户决定，而不是 Agent。

• **如果阅读邮件只是有助于完成其他任务，**例如某个邮件线程可能会说明编码任务的情况，或者项目或技能指令要求检查邮件：说明你要查找什么以及原因，并在用户同意后再阅读。
• **任务发生变化时：**用户的请求仅涵盖其针对的邮件任务。为无关任务阅读邮件前，请再次征求用户同意。

草稿

• **如果用户要求起草邮件，但没有指定 Gmail 或 Spark，**例如“给房东起草一封邮件”：在聊天中撰写内容。只有当请求明确指向所需邮件（例如要回复的邮件）时，才为此读取邮件；其他任何查找都应先征求用户同意。
• **如果用户要求在 Gmail 或 Spark 中起草邮件，**无论措辞如何，例如“将它保存为 Gmail 草稿”或“放到我的 Spark 草稿中”：仅使用该工具在那里保存。指定工具只授权保存这份草稿，不授权进行其他邮件更改。
• **如果指定的工具无法完成此操作，**例如 spark draft 因 Spark 的访问级别为只读而遭拒：说明原因，并将草稿留在聊天中。不要擅自改用另一个工具。

即使用户已要求起草邮件，每次创建、更新或删除已保存的草稿，仍需在 harness 中获得用户本人批准：已保存的草稿会更改用户的邮箱，而且一次误操作就可能覆盖用户正在撰写的草稿。/set-up-machine 的询问项 mail-draft-write 和 mail-cli-draft 会要求对这些调用逐一确认。

• **如果 harness 不会主动询问用户，**请将草稿留在聊天中，并说明原因。自动审查器的批准不等于用户本人的批准。以下 harness 不会询问用户：
  • Claude Code：bypassPermissions、dontAsk 和 auto 模式，以及非交互式运行。
  • **Codex：**使用自动审查器的运行。
  • **Cursor 和 opencode：**无需询问即可运行工具的模式。
  • **其他 harness：**调用不会询问用户的任何情况。

安全

用户会亲自审阅并发送每封邮件，因此最多只能起草邮件。

在邮件任务中，如果任务要求归档邮件，则进行归档。任何其他更改都只能在用户明确要求进行该项更改，或你说明更改内容并征得用户同意后执行：固定邮件、添加标签、撤销操作，或按上述方式保存草稿。

Gmail 工具

工具	用途
search_threads、get_thread、get_message、list_labels、get_draft、list_drafts	用于用户要求处理的邮件任务。
unlabel_thread，或通过 update_message_labels 移除 INBOX	可在该任务范围内自由归档。
label_*、unlabel_*，以及用于其他标签的 update_message_labels、create_label、update_label	用户提出要求后，或你说明标签名称并获得用户同意后使用。绝不要添加 TRASH 或 SPAM，因为这会绕过拒绝规则，将邮件移入垃圾箱或标记为垃圾邮件。
create_draft、update_draft、delete_draft	用户要求创建 Gmail 草稿时使用，并且每次调用都必须在运行环境中获得用户批准。
untrash_*、unmark_*_spam	用户提出要求后，或你说明标签名称并获得用户同意后使用。
delete_label	仅当用户指出要删除该标签时使用，因为这会从每封邮件中移除该标签。

Claude Code 的权限规则会拒绝其他工具，且被拒绝的工具不会显示为可调用：

• send_message，也会发送已有草稿；
• reply 和 forward；
• trash_message 和 trash_thread；
• mark_message_spam 和 mark_thread_spam；
• apply_sensitive_message_label、apply_sensitive_thread_label 和 batch_apply_sensitive_thread_labels，这些工具可能会将邮件移入垃圾箱或标记为垃圾邮件。

Google 允许归档的权限也允许发送，因此只有这些拒绝规则能阻止发送。

• **可调用被拒绝的工具时：**说明配置不完整。告知用户，绝不要调用该工具，并且在修复拒绝规则之前，不要对邮件作任何更改。

两种工具

工具	用途	速度和大小	要求
Spark CLI，spark	列出、搜索和阅读邮件；Spark 的分类、置顶项和联系人	约 0.1 秒，表格精简	Spark Desktop 正在运行。免费版仅提供只读邮件访问权限。
Gmail connector，mcp__<server-id>__<tool>	除 Spark 草稿外的所有邮件更改	约 1 秒，JSON 内容约为 Spark 的 3 到 4 倍	已登录连接器

Spark 读取的是 Spark Desktop 上的邮件本地副本。Gmail connector 是 Google 的 Gmail MCP 服务 gmailmcp.googleapis.com，以 Claude connector 的形式连接。

Spark 视图与 Gmail 的对应关系

在 Spark 中	在 Gmail 中
已完成	移除 INBOX 标签，即归档邮件。Spark 约一分钟内会显示更改。
置顶	STARRED 标签。Spark 的 is:pinned 和 is:starred 会返回相同的邮件。
文件夹	Gmail 标签。
分类：优先、个人、邀请、通知、新闻简报	Spark 自有分类；没有 Gmail 工具会更改它。
今天、上周、一个月	每封邮件的日期。

步骤

设置任一工具、检查拒绝和询问规则，或调用因登录或权限问题失败时，请参阅 setup.md。

1. 查找 Spark 中的邮件。

   spark emails Inbox --filter "category:priority is:unread"   # one Spark category
   spark emails --filter "is:pinned"                           # pinned mail
   spark search --filter 'from:<sender> newer_than:7d'         # any Gmail-style query
   spark thread <id>                                           # one email in full
   spark contacts --help                                       # search contacts
   

   使用 spark emails 列出邮件，或使用 spark search --filter '<gmail-style query>' 搜索。spark search <topic> 会返回最多 20 封匹配邮件的完整正文，通常有数万个 token，因此只有在需要这些正文时才使用。

   • **需要查看命令的标志时：**运行 spark <command> --help。spark skill 会输出完整参考文档，约 13,000 个 token，因此只有在 --help 不够用时才使用。

2. 在 Gmail 中再次查找邮件，然后再进行更改，因为这两个工具对邮件的编号不同。使用 search_threads 搜索，并采用 Spark 列表行中的 from: 和 subject:。如果只需要 ID，请传入视图 THREAD_VIEW_METADATA_ONLY，以缩短回复内容。

   • **匹配到多个会话时：**根据 Spark 列表行中的日期，使用 after: 和 before: 缩小搜索范围，或询问用户指的是哪一个。

3. 通过 Gmail 执行操作：归档邮件，或按用户要求进行更改。

   更改	调用
   标记为已处理	在步骤 2 的搜索中添加 in:inbox，然后使用 unlabel_thread 和 ["INBOX"]。使用 label_thread 和 ["INBOX"] 可将邮件移回收件箱。
   置顶或取消置顶	使用 label_thread 或 unlabel_thread，并传入 ["STARRED"]。
   添加标签	使用 list_labels 获取标签的 ID；如果标签尚不存在，则使用 create_label 创建，然后使用 label_thread 并传入该 ID。
   将回复保存为 Gmail 草稿	使用 get_thread 读取会话，然后使用 create_draft，并将 replyToMessageId 设为最后一封邮件的 id。

   调用 get_thread 时使用 messageFormat: PLAIN_TEXT，以缩短会话内容。

   • **对于用户未要求的任何更改（归档除外）：**说明该更改，并等待用户回复。
   • **对于已保存的草稿：**最后提供其 viewUrl，供用户查看并发送。
   • **对于用户要求保存在 Spark 中的草稿：**单独运行 spark draft 命令，让用户单独批准这项调用，并告知用户在 Spark 中查看草稿的位置。

4. 检查每项更改是否生效。

   • **标记为已处理后：**邮件归档后，in:inbox 搜索会返回 {}。

参考资料

• setup.md：设置 Spark 和 Gmail 连接器、配置拒绝和询问规则，以及检查各部分。