用途：把 Gmail 账号连接到本机，并在 Gmail 调用开始失败时诊断问题。访问方式是针对用户自己的 Google Cloud 项目做 OAuth，项目不存在或未授权前无法使用。
主要能力：gmail doctor 检查整条链路（运行时、OAuth 客户端、令牌、scope、出网、两次实时 API 调用），失败项会给出修复命令或控制台页面；gmail doctor --quick 只查本地文件不联网；gmail doctor --json 输出便于程序化检查的 Envelope。gmail whoami 显示当前账号或“not logged in”。
使用方式：首次设置中 Google Cloud 部分需用户自己在浏览器完成，约十分钟，产出一个文件。OAuth 客户端类型必须是 Desktop app，Web 客户端没有 loopback 重定向，无法完成授权。Cloud 项目需保持 Testing 并把用户加为测试用户，因为 gmail.modify 属受限 scope，已发布项目会被硬性拦截；代价是刷新令牌 7 天后过期，需约每周执行 gmail login --force。credentials.json 就绪后运行 gmail login 打开浏览器并写入令牌，再用 gmail doctor 确认。
登录相关：gmail login 在已有可用令牌时不操作；--force 重新授权（7 天后或 scope 变更后）；--read-only 仅 gmail.readonly，该账号不能发送；--profile 指定第二账号；gmail logout --profile 本地遗忘，--revoke 同时在 Google 撤销授权。--force 可解决多数认证失败。
无浏览器或 SSH 环境：gmail login 会启动 loopback 监听并打开浏览器，无浏览器时固定端口并转发，例如在笔记本上 ssh -L 8765:localhost:8765 user@host，在主机上 gmail login --port 8765 --no-browser，再打开打印的 URL。Google 设备码流程不接受 Gmail scope，不可用。
多账号：一个 OAuth 客户端，每个 profile 一个令牌文件，所有命令支持 --profile，$GMAIL_SKILL_PROFILE 设默认值。
失败对照：auth_required 无令牌，执行 gmail login；auth_expired 刷新令牌失效（7 天 Testing 过期、改密码或撤销），执行 gmail login --force；scope_insufficient 令牌早于所需 scope，执行 gmail login --force；client_invalid 无客户端 JSON 或为 Web 客户端，按 README 设置且类型须为 Desktop app；api_not_enabled 需在控制台启用 Gmail API；rate_limited 为每分钟配额，可重试并减少批量；quota_exceeded 为每日预算或账号发送上限，当天不可重试。
文件位置：~/.config/gmail-skill/（或 $GMAIL_SKILL_HOME），目录权限 0700；credentials.json 是 OAuth 客户端，<profile>.token.json 是活动会话，权限 0600。两者都不要复制进仓库、聊天或缺陷报告；gmail doctor --json 已脱敏，不含令牌与客户端密钥。