gogcli 实战:`gog gmail drafts get` 命令详解——读取 Gmail 草稿详情与附件下载
gogcli 实战:gog gmail drafts get 命令详解——读取 Gmail 草稿详情与附件下载
gog gmail drafts get 是 gogcli(Google Workspace in your terminal)中用于获取单封 Gmail 草稿完整详情的子命令,它以 draftId 为入参,一次 API 调用即可取回草稿的收件人、主题、正文、附件清单,并支持将附件批量下载到本地目录。本文以官方命令文档为骨架,结合仓库源码(internal/cmd/gmail_drafts.go)与测试用例,完整讲解该命令的用法、全部标志参数、文本/JSON 两种输出格式、附件下载机制及其安全约束,帮助你将其无缝接入日常邮件工作流与自动化脚本。
命令定位与使用场景
gog gmail drafts get 属于 gog gmail drafts 子命令族。整个草稿命令族定义在 internal/cmd/gmail_drafts.go 的 GmailDraftsCmd 结构中,除 get 之外还包括:
list(别名ls)— 列出草稿delete(别名rm/del/remove)— 永久删除草稿send(别名post)— 发送草稿create(别名add/new)— 新建草稿update(别名edit/set)— 更新草稿reply/reply-all/forward(别名fwd)— 保存回复/转发草稿
get 命令在结构体中定义为:
Get GmailDraftsGetCmd `cmd:"" name:"get" aliases:"info,show" help:"Get draft details"`
可见它同时注册了 info、show 两个别名(见 internal/cmd/gmail_drafts.go#L21),与 gmail 的别名 mail/email、drafts 的别名 draft 组合后,等效写法非常灵活。
典型使用场景包括:在发送草稿前核对收件人与附件、把草稿正文导出到本地、批量备份草稿附件、或作为脚本管线中"先读草稿、再决定是否发送"的前置步骤。
基本用法与别名体系
官方用法定义为:
gog gmail (mail,email) drafts (draft) get (info,show) <draftId> [flags]
其中括号内的词都是可互换的别名,因此以下写法完全等价:
gog gmail drafts get d1
gog email draft info d1
gog gmail drafts show d1
gog mail drafts get d1
<draftId> 是唯一的位置参数(必填)。从源码看,命令启动时会对该参数做空值校验(strings.TrimSpace 后为空即报 usage("empty draftId"),见 internal/cmd/gmail_drafts.go#L112-L115),因此前后带空格的 ID 会被自动清理,但空字符串会直接报错退出。
草稿 ID 可通过 gog gmail drafts list 获取,也可从 Gmail 网页端的草稿 URL 中提取。
命令专属标志
get 子命令只有两个专属标志(定义于 internal/cmd/gmail_drafts.go#L104-L108):
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--download |
bool |
false | 下载草稿附件 |
--use-indexed-attachment-ids |
bool |
false | 全程使用 0 起始的索引作为附件 ID(输出、下载参数与保存文件名一致) |
--download 的底层行为:开启后,命令会先通过 commandLayout 计算配置目录,并把附件保存到 <config>/gmail-attachments 目录下——该目录路径由 internal/config/layout_paths.go#L62-L64 的 GmailAttachmentsDir() 确定,即配置根目录下的固定子目录。随后命令才会调用 Gmail API 拉取草稿详情,再对草稿载荷中的附件逐个执行下载。
--use-indexed-attachment-ids 的底层行为:Gmail API 返回的附件 ID 是一串很长的 base64url 字符串。开启此标志后,所有输出(文本与 JSON)、下载文件命名都以 0 起始的序号(0、1、2...)代替长 ID;在 JSON 模式下,命令还会额外输出一个 attachments 字段,用索引映射每个附件,并从原始草稿转储中剥离冗长的原始附件 ID(见 internal/cmd/gmail_drafts.go#L163-L168)。该标志同时支持环境变量 GOG_GMAIL_USE_INDEXED_ATTACHMENT_IDS 注入。
空草稿与无附件边界
源码对两种边界情况做了专门处理:
- 若返回的草稿
Message为空(空草稿),文本模式打印Empty draft并正常退出,JSON 模式则原样输出{"draft": draft}; - 若草稿没有 messageId 或没有附件,即使带了
--download,attachDir也会被重置为空,不会执行任何下载(见 internal/cmd/gmail_drafts.go#L138-L150)。
全局标志(适用于所有 gogcli 命令)
get 命令继承 gogcli 全部全局标志,完整清单如下:
| Flag | 类型 | 默认值 | Help |
|---|---|---|---|
--access-token |
string |
直接使用提供的访问令牌(绕过已存储的 refresh token;令牌约 1 小时过期) | |
-a--account--acct |
string |
账户邮箱、别名或 auto(用于 Google API 命令认证) |
|
--client |
string |
OAuth 客户端名(选择已存凭据 + token 桶) | |
--color |
string |
auto | 颜色输出:auto|always|never |
--disable-commands |
string |
逗号分隔的禁用命令列表;支持点路径 | |
-n--dry-run--dryrun--noop--preview |
bool |
不执行变更;打印预期动作并以成功退出 | |
--enable-commands |
string |
逗号分隔的启用命令前缀列表;支持点路径(限制 CLI) | |
--enable-commands-exact |
string |
逗号分隔的精确启用命令列表;支持点路径,且父命令不会启用子命令 | |
-y--force--assume-yes--yes |
bool |
跳过破坏性命令的确认提示 | |
--gmail-no-send |
bool |
false | 阻止 Gmail 发送操作(Agent 安全用) |
-h--help |
kong.helpFlag |
显示上下文相关的帮助 | |
--home |
string |
覆盖 gogcli 的 config/data/state/cache 根目录(等价于 GOG_HOME) | |
-j--json--machine |
bool |
false | 向 stdout 输出 JSON(最适合脚本) |
--no-input--non-interactive--noninteractive |
bool |
从不提示;直接失败(适合 CI) | |
-p--plain--tsv |
bool |
false | 输出稳定的、可解析的文本到 stdout(TSV;无颜色) |
--quota-project |
string |
用于结算 API 用量的 Google Cloud 项目(作为 X-Goog-User-Project 发送;部分 API 在 --access-token 或 ADC 下要求此参数) |
|
--readonly |
bool |
false | 在运行时阻止变更型 API 请求;auth add 也仅请求只读 OAuth 范围 |
--results-only |
bool |
JSON 模式下只输出主结果(丢弃 envelope 字段如 nextPageToken) | |
--select--pick--project |
string |
JSON 模式下选择逗号分隔的字段(尽力而为;支持点路径) | |
-v--verbose |
bool |
启用详细日志 | |
--version |
kong.VersionFlag |
打印版本并退出 | |
--wrap-untrusted |
bool |
false | JSON/raw 输出时,将获取的外部文本字段包裹在 untrusted-content 标记中 |
与认证相关的要点:命令通过 requireGmailService 获取已认证的 Gmail 服务(见 internal/cmd/gmail_drafts.go#L129-L131),默认走已存储的 OAuth 凭据;若想临时切换身份,可用 --access-token 直传令牌,或 --account 指定账户邮箱/别名,或 --client 切换 OAuth 客户端凭据桶。
与安全相关的要点:--gmail-no-send 从全局层面阻断发送类操作;--readonly 在运行时拦截变更型请求——drafts get 本身是只读操作,因此与 --readonly 天然兼容,可放心叠加使用,适合在只读 Agent 环境或 CI 中安全地读取草稿。
文本输出格式
不带 --json/--plain 时,get 使用人类可读的文本输出。结合源码 internal/cmd/gmail_drafts.go#L172-L200,输出结构如下:
Draft-ID: d1
Message-ID: m1
To: a@example.com
Cc: b@example.com
Bcc: c@example.com
Subject: 项目周报草稿
(此处为草稿正文最佳文本,来自 gmailcontent.BestBodyText 的纯文本提取)
Attachments:
attachment file.txt 10 B text/plain att1
各字段说明:
Draft-ID/Message-ID:草稿 ID 与底层消息 ID(草稿本质是带DRAFT标签的 message);To/Cc/Bcc/Subject:通过headerValue从 MIME 载荷的 headers 中提取(internal/cmd/gmail_thread_search_helpers.go#L96);- 正文:由
gmailcontent.BestBodyText从 MIME 多部分结构中选出最合适的纯文本; Attachments:区块:每行格式为attachment\t<文件名>\t<大小>\t<MIME类型>\t<引用>,其中"引用"默认是 Gmail 的 attachmentId,开启--use-indexed-attachment-ids后变为 0 起始的数字索引。
该输出结构由测试用例 TestGmailDraftsGetCmd_Text 逐一断言(internal/cmd/gmail_drafts_cmd_test.go#L141-L192),包括对 attachment file.txt 10 B text/plain att1 行格式的精确校验,可放心依赖。
下载时的文本输出
带上 --download 后,输出末尾会追加每条附件的保存结果:
Saved: /home/user/.config/gogcli/gmail-attachments/file.txt
Cached: /home/user/.config/gogcli/gmail-attachments/file.txt
Saved 表示本次新下载,Cached 表示该文件已存在于目标目录(幂等重跑时出现),见 internal/cmd/gmail_drafts.go#L188-L200。
JSON 输出格式(脚本友好)
使用 -j/--json/--machine 后,输出为结构化 JSON。基础形态为:
{
"draft": {
"id": "d1",
"message": {
"id": "m1",
"threadId": "t1",
"payload": { "mimeType": "multipart/mixed", "headers": [], "parts": [] }
}
}
}
即 draft 字段内直接透传 Gmail API 的完整 Draft 对象。组合标志时字段会相应扩展:
- 加
--download:新增downloaded数组,每项含messageId、attachmentId(或索引)、filename、path、cached等下载结果字段(见 internal/cmd/gmail_drafts.go#L151-L162); - 加
--use-indexed-attachment-ids:新增attachments索引映射数组,同时原始draft.message.payload中被剥离长附件 ID(见 internal/cmd/gmail_drafts.go#L163-L168); - 加
--results-only:只输出主结果对象,去掉nextPageToken等 envelope 字段; - 加
--select:按逗号分隔的点路径字段做尽力而为的投影。
这类组合在测试 internal/cmd/execute_gmail_more_commands_test.go#L172 中也有覆盖:gmail drafts get d1 --json --download 会同时携带 JSON 与下载两个行为。
附件下载机制与 dry-run 安全保证
--download 的核心链路为:解析草稿载荷中的附件(collectAttachments,见 internal/cmd/gmail_attachments.go#L200)→ 对每个带 attachmentId 的部分调用 Gmail users.messages.attachments.get 拉取字节 → 写入 <config>/gmail-attachments。
值得注意的是,下载动作也纳入 dry-run 保护。在 internal/cmd/gmail_drafts.go#L117-L127,命令在真正发起 API 请求前会先执行 attachmentDownloadDryRun,其操作路径为 gmail.drafts.get.download。
对应的测试 internal/cmd/gmail_attachment_dryrun_test.go#L17-L80 验证了关键行为:当同时传入 --dry-run、--readonly、--gmail-no-send 等安全标志时,dry-run 阶段不会打开密钥环、不会创建 Gmail 客户端、不会写入任何文件——它只解析并打印预期的下载动作(包括目标目录:草稿下载默认落到配置目录的 gmail-attachments 子目录,见同文件 L57-L59 的测试断言),然后以成功状态退出。这使得 drafts get --download --dry-run 成为一种安全的"预览将下载哪些附件到何处"的方式,非常适合在 CI 或 Agent 环境中先行验证。
相关命令与延伸阅读
- 父命令:gog gmail drafts — 全部草稿操作入口
- 兄弟命令:gog gmail drafts list(获取 draftId)、gog gmail drafts create、gog gmail drafts update、gog gmail drafts send、gog gmail drafts delete
- 命令索引:Command index
- 源码实现:internal/cmd/gmail_drafts.go(
GmailDraftsGetCmd定义于 L104-L203) - 测试用例:internal/cmd/gmail_drafts_cmd_test.go(
TestGmailDraftsGetCmd_Text)、internal/cmd/gmail_attachment_dryrun_test.go - 附件处理工具:internal/cmd/gmail_attachments.go
- 附件目录约定:internal/config/layout_paths.go
提示:本文所引用的命令文档均由
gog schema --json自动生成,如需查阅最新标志清单,可运行gog gmail drafts get --help,或按仓库内文档头部注释执行make docs-commands重新生成。