用途
该技能用于通过 Gmail v1 REST API 驱动 Gmail，覆盖读取、搜索、分类、打标签、归档和发送邮件、会话、标签与附件。适用于用户提到 Gmail 或需要操作其邮箱的场景。
认证与作用域
用户 OAuth bearer 令牌存放于 $GOOGLE_GMAIL_TOKEN，每次调用都需以 Authorization: Bearer $GOOGLE_GMAIL_TOKEN 携带。令牌至少包含 gmail.readonly 以及身份作用域（openid email profile）；若用户在安装时选择写入权限，还会包含 gmail.modify（打标签/归档/移入回收站）和/或 gmail.send（撰写与发送）。技能要求始终按最小作用域假设，直到写入确实失败再处理，不要从此处向 Google 请求新作用域。
主要能力
- 验证认证：始终先运行 users/me/profile，确认连接并识别所操作的 Gmail 账号。
- 列出最近未读收件箱、按 Gmail 查询语法搜索、按标签过滤。
- 读取单封邮件正文（纯文本与 HTML）、读取整个会话。
- 列出系统与用户自定义标签。
- 下载附件。
- 分页遍历结果。
- 写入操作：标记已读/未读、加星、归档、应用自定义标签、创建新标签、将邮件或会话移入回收站（可用 /untrash 恢复，不使用 messages.delete）。
- 发送新邮件、在会话内回复、保存草稿。
使用方式
通过 curl + jq 调用 Gmail REST API。Gmail API 返回标准 JSON，失败时返回 {"error": {"code": 401|403|..., "message": "..."}}，需原样展示该错误。401 表示令牌过期（需重新安装）；403 insufficientPermissions 表示用户未授予本次调用所需的写入作用域，需说明缺少哪个作用域并建议重新安装连接器并勾选对应写入选项。
在任何破坏性写入（移入回收站、发送邮件）前，向用户展示确切目标或草稿并请求确认；不要在未明确许可的情况下批量操作大量邮件。
邮箱负载可能很大，先取元数据，仅在用户确实需要某封邮件正文时使用 format=full。messages.list 仅返回 {id, threadId}，需再对每封邮件调用 messages.get 获取头部或正文。
可选使用 Google Workspace CLI（gws）发送邮件。gws 是 Google 官方 CLI（非官方支持，由 googleworkspace 组织社区维护），从 Google Discovery Document 动态构建命令面，API 错误时以非零状态退出，并提供手工编写的辅助命令（前缀 +）处理消息编码样板。安装：npm install -g @googleworkspace/cli 或 brew install googleworkspace-cli，预编译二进制见 https://github.com/googleworkspace/cli/releases。认证：gws 从 GOOGLE_WORKSPACE_CLI_TOKEN 环境变量读取 OAuth bearer 令牌，需在每个调用 gws 的 shell 块顶部执行 export GOOGLE_WORKSPACE_CLI_TOKEN="$GOOGLE_GMAIL_TOKEN"。可用 gws gmail users getProfile --params '{"userId":"me"}' 确认当前账号。发送/回复/转发使用 +send / +reply / +reply-all / +forward 辅助命令，它们自动处理 threadId、In-Reply-To、References 等。读取、搜索、标签、附件等操作 gws 与 curl 等价，curl 配方通常更短。
适用场景
- 收件箱分类与清理：列出未读、按查询搜索、打标签、归档。
- 邮件检索与阅读：按发件人、主题、标签、时间等条件搜索并读取正文或整个会话。
- 附件处理：定位并下载附件。
- 邮件撰写与回复：发送新邮件、在会话内回复、保存草稿。
限制
- 写入操作需要 gmail.modify 或 gmail.send 作用域，若仅授予 gmail.readonly 会返回 403 insufficientPermissions。
- 不使用 messages.delete（永久删除且需要更高作用域）。
- 401 表示令牌过期或撤销，需重新连接 Gmail 连接器。
- 403 userRateLimitExceeded / 429 表示配额或限流，需退避约 5 秒后重试一次。
- 404 notFound 表示消息、会话或附件 ID 错误，需核对 ID。
- 发送邮件时，Gmail 要求消息为 base64url 编码的 RFC 2822 字符串；非 ASCII 主题需使用 MIME encoded-word。
- 回复时若不在请求体中传入 threadId，即使 In-Reply-To 头正确，Gmail 也会开启新会话。
- 具体收费、价格、平台支持等信息暂未提供。