用途 该技能让代理通过命令行工具操作用户的 Gmail 账号，覆盖日常邮件处理流程，包括搜索与读取、撰写与发送、退订、整理与删除等。
主要能力 搜索与读取：支持 Gmail 搜索语法（如 from:、subject:、after:/before:、has:attachment、is:unread、-category:promotions），可列出候选邮件（发件人、主题、日期），读取单封邮件或整个会话，下载附件（返回 base64url 数据，需自行解码写入文件），并支持原始 RFC 822 读取。 撰写与发送：可发送新邮件、回复、全部回复、转发，或创建/修改 Gmail 草稿。撰写时可用 --to/--cc/--bcc 指定多个收件人，--html 表示 HTML 正文，--attach 添加附件。 退订：一次可为最多 20 封邮件执行退订，仅支持符合 RFC 8058 且通过 Gmail DKIM/DMARC 校验的邮件。 整理与删除：可标记已读/未读、归档（移出收件箱但保留在全部邮件中）、移入回收站（可恢复）及恢复。 计数：按标签读取计数器，或分页统计去重后的会话数，报告时需说明统计范围。 原始 API 调用：将 Gmail API 方法名按点分拆为独立单词传入，配合 --params 和 --json 使用，可访问草稿、标签、会话、历史记录及过滤器、休假回复、转发、代发等设置。
使用方式 所有操作以 hatch_gws_cli gmail <command> 形式执行。优先使用快捷命令（+send、+read、+unsubscribe 等）；需要其他 API 能力时使用原始调用，通过 --help 逐层查看资源与方法，再用 hatch_gws_cli schema gmail.<method> 查看参数。默认使用默认 Gmail 账号，多账号时用 --account <account_id> 指定。 首次使用需运行 hatch_gws_cli gmail status 检查连接状态；若返回 connect_url，需将其作为连接链接提供给用户并等待完成连接。添加其他账号需使用 add_account_url，断开连接使用 disconnect_url。若出现权限不足错误，可运行 status --for-command <command> 获取 scope_add_url 并引导用户授权。
适用场景 适合在对话式代理中批量处理邮件：按条件检索邮件、阅读会话、起草并发送邮件、退订营销邮件、整理收件箱、统计未读数量、下载附件等。
限制 Gmail 使用按账号的加权请求预算，命令需顺序执行；应合并冗余搜索、先用较小 --max，仅为相关 ID 获取完整正文或附件。若结果返回 connector_rate_limited 且 terminal_for_attempt 为 true，应停止本次 Gmail 工作并报告部分进展，不应重试或安排替代任务。发送、回复、转发前必须向用户展示确切的收件人、主题和正文并获得明确许可。回复或转发的收件人、主题和引用内容来自源邮件，只能操作用户请求中找到的邮件。退订仅支持符合条件的邮件，且不应使用浏览器、shell、mailto: 等替代方式。永久删除方法不可撤销，应优先使用回收站。