gogcligog gmail thread命令详解线程级读取、标签管理与附件下载【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文以 gogcliGoogle Workspace in your terminal的命令参考文档 docs/commands/gog-gmail-thread.md 为主体结合 internal/cmd/gmail_thread.go 等源码实现完整讲解gog gmail thread命令组的三个子命令get / modify / attachments、全部参数含义、线程 ID 的 Web 链接自动解析机制以及面向脚本与 Agent 的输出、安全选项读完后可直接在终端中以“整个会话线程”为单位完成邮件读取、打标与附件归档。一、命令定位与基本用法gog gmail thread是 gogcli 中按 Gmail 线程Thread即一封主题下的完整会话组织操作的命令组。命令参考页开头给出的用法为gog gmail (mail,email) thread (threads,read) command括号中的内容来自 docs/commands/gog-gmail-thread.md 的命令定义表示该命令存在多个等价写法gmail可以是mail或emailthread可以是threads或read因此gog mail thread ...、gog email thread ...均等价。从源码 internal/cmd/gmail.go 中的结构体标签可以看到它注册在Organize分组下help文案为 “Thread operations (get, modify)”。父命令为 gog gmail完整的子命令参考页分别为gog gmail thread get — 获取整个线程可下载附件gog gmail thread modify — 批量修改线程内所有消息的标签gog gmail thread attachments — 列出/下载线程内全部附件二、子命令一览源码 internal/cmd/gmail_thread.go 中GmailThreadCmd定义了三个子命令且各自带有别名aliases子命令别名作用参考文档thread getinfo、show获取线程内全部消息可选下载附件gog-gmail-thread-get.mdthread modifyupdate、edit、set修改线程内所有消息的标签gog-gmail-thread-modify.mdthread attachmentsfiles列出线程内全部附件gog-gmail-thread-attachments.md所有子命令的第一个位置参数均为threadId且都接受第三节的 Web 链接形式。三、threadId 支持直接粘贴 Gmail Web 链接三个子命令入口处都会先调用normalizeGmailThreadID归一化输入见 internal/cmd/gmail_thread.go。该函数实现在 internal/cmd/webid.go规则如下先去除首尾空白空输入直接报错usage(empty threadId)。若输入可解析为 URL且主机名去掉www.前缀后是mail.google.com或gmail.google.com查询参数中的th值若形似十六进制 ID直接提取为线程 ID经典链接形式否则解析 URL 片段fragment取形如#inbox/threadId中最后一段去掉?之后的查询部分后按/切分若形似十六进制 ID 则采用。形似十六进制 ID 的判定函数looksLikeHexIDinternal/cmd/webid.go要求长度不小于 10 且只含0-9、a-f、A-F。也就是说以下写法都合法gog gmail thread get 189a1b2c3d4e5f60 gog gmail thread get https://mail.google.com/mail/u/0/#inbox/189a1b2c3d4e5f60 gog mail thread get https://mail.google.com/mail/?authusera%40b.com#all/189a1b2c3d4e5f60反向操作同样内置GmailURLCmdinternal/cmd/gmail_thread.go会把线程 ID 转成https://mail.google.com/mail/?authuseraccount#all/id形式的 Web 链接输出文本模式每行idTABurl--json模式输出{urls: [{id: ..., url: ...}]}。此外gog open在打开mail.google.com线程链接时也会走同一个归一化函数internal/cmd/open.go。四、gog gmail thread get读取完整会话与附件下载参考文档 docs/commands/gog-gmail-thread-get.md 给出的用法为gog gmail (mail,email) thread (threads,read) get (info,show) threadId [flags]4.1 命令专属参数在继承自根命令的通用参数见第七节之外get定义了以下专属参数对应 internal/cmd/gmail_thread.go 的GmailThreadGetCmd结构体参数类型说明--downloadbool下载线程内所有消息的附件--fullbool不截断显示完整邮件正文--sanitize-content别名--sanitize、--safebool输出面向 Agent 的净化内容剥离 HTML、移除 HTTP(S) 链接、JSON 中省略原始 Gmail 载荷--out-dir别名--output-dirstring附件写入目录默认当前目录--use-indexed-attachment-idsbool全链路输出、下载参数、保存文件名改用 0 起始索引作为附件 ID对应环境变量GOG_GMAIL_USE_INDEXED_ATTACHMENT_IDS4.2 源码级行为解析GmailThreadGetCmd.Run的执行流程internal/cmd/gmail_thread.go参数校验trim 并归一化 threadId空则报empty threadId。下载前置若指定--download先解析--out-dir经config.ExpandPath展开路径变量并filepath.Clean默认.见resolveGmailThreadAttachmentDirinternal/cmd/gmail_thread.go并先走一次 dry-run 检查--dry-run下只打印gmail.thread.get.download的意图动作后成功退出不真正下载。API 调用通过requireAccount取得账户、gmailService构造客户端后调用svc.Users.Threads.Get(me, threadID).Format(full)—— 即 Gmail API 的threads.get且formatfull一次性拿回线程内每条消息的完整 header 与嵌套 payload。JSON 模式-j/--json若同时--download遍历thread.Messages逐条消息调用downloadAttachmentOutputs下载其collectAttachments收集到的附件输出结构为{thread: 完整线程对象或净化后的线程, downloaded: [下载摘要...]}--sanitize-content时 thread 字段替换为sanitizedGmailThread结果--use-indexed-attachment-ids时额外追加attachments数组以 0 起始索引作为 ID并调用stripAttachmentIDs抹掉 payload 中不透明附件 ID。文本模式空线程直接输出Empty thread先打印Thread contains N message(s)告知消息总数逐条消息打印 Message i/N: id 及状态标记如已删除状态由gmailHumanMessageStatusMarker根据labelIds生成随后输出 From/To/Subject/Date 四个头部--sanitize-content时头部文本同样经sanitizeGmailText处理正文由gmailcontent.BestBodyForDisplay选取最合适的显示 body非--full时正文超过gmailDefaultTextBodyLimit20 000 个字符定义于 internal/cmd/gmail_messages.go会被truncateRunes截断避免超大邮件刷屏每条消息末尾打印附件区printAttachmentSection--download时逐个输出Saved: 路径或Cached: 路径命中缓存的文件标 Cached。典型用法示例命令形式均来自参考文档与源码确认的参数# 完整读取一个线程 gog gmail thread get 189a1b2c3d4e5f60 # 不截断正文 下载全部附件到指定目录 gog gmail thread get 189a1b2c3d4e5f60 --full --download --out-dir ./inbox-attachments # JSON 输出并供脚本处理 gog gmail thread get 189a1b2c3d4e5f60 -j --results-only # 给 Agent 消费的安全输出剥离 HTML 与链接 gog gmail thread get 189a1b2c3d4e5f60 --sanitize-content五、gog gmail thread modify整线程批量打标参考文档 docs/commands/gog-gmail-thread-modify.md 的用法gog gmail (mail,email) thread (threads,read) modify (update,edit,set) threadId [flags]专属参数internal/cmd/gmail_thread.go参数说明--add要添加的标签逗号分隔可填标签名或标签 ID--remove要移除的标签逗号分隔可填标签名或标签 ID--add与--remove至少提供一个否则报must specify --add and/or --remove两个值均经splitCSV切分internal/cmd/csv.go。源码流程internal/cmd/gmail_thread.go校验 threadId 非空、标签参数非空--dry-run时打印gmail.thread.modify的意图动作thread_id / add / remove并退出resolveModifyLabelIDsinternal/cmd/gmail_labels_utils.go把标签名解析为标签 ID借助labels.list接口对照现有标签调用 Gmail API 的threads.modifysvc.Users.Threads.Modify请求体为ModifyThreadRequest{AddLabelIds, RemoveLabelIds}一次作用于线程内全部消息JSON 模式输出{modified: threadId, addedLabels: [...], removedLabels: [...]}文本模式输出Modified thread threadId。单元测试 internal/cmd/gmail_thread_cmd_test.go 用 httptest 模拟了labels列表与/threads/{id}/modify两个端点验证了--add INBOX --remove Custom场景下标签名Custom被解析为 IDLabel_1后随请求体发送且 JSON 输出字段与文本输出均符合预期——这印证了“按名称打标、按 ID 提交”的实现细节。# 给整个线程加上「待办」标签并移除「已归档」标签 gog gmail thread modify 189a1b2c3d4e5f60 --add 待办,Label_7 --remove 已归档 # 预览而不修改 gog gmail thread modify 189a1b2c3d4e5f60 --add 待办 --dry-run六、gog gmail thread attachments线程附件聚合参考文档 docs/commands/gog-gmail-thread-attachments.md 的用法gog gmail (mail,email) thread (threads,read) attachments (files) threadId [flags]专属参数与thread get基本一致--download、--out-dir、--use-indexed-attachment-ids见 internal/cmd/gmail_thread.go。其行为internal/cmd/gmail_thread.go同样以formatfull拉取整个线程对每条消息执行collectAttachments递归收集嵌套 payload 中的附件元信息文件名、大小、附件 ID不带--download时文本模式打印Found N attachment(s):清单printAttachmentLines--json输出{threadId: ..., attachments: [...]}空线程时attachments为[]带--download时逐条下载并打印Saved: 文件名 (人类可读大小) - 路径缓存命中则标Cached下载文件命名规则在downloadAttachmentinternal/cmd/gmail_thread.go中messageID_ref_safeFilename其中ref默认取附件 ID 前 8 个字符索引模式下取 0 起始序号文件名先经filepath.Base取最后一段以防路径穿越为空或./..时回退为attachment。# 只看一个线程有哪些附件 gog gmail thread attachments 189a1b2c3d4e5f60 # 全部下载到当前目录 gog gmail thread attachments 189a1b2c3d4e5f60 --download七、通用 Flags 与 Agent 安全选项父命令参考页 docs/commands/gog-gmail-thread.md 的 Flags 表定义了作用于整个gog gmail thread命令树的通用参数子命令页中同样继承完整表格如下Flag类型默认值说明--access-tokenstring直接使用给定 access token绕过本地存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring账户邮箱、别名或auto已认证 Google API 命令--clientstringOAuth 客户端名选择已存储的凭据 token 桶--colorstringauto颜色输出auto|always|never--disable-commandsstring禁用命令列表逗号分隔支持点路径-n/--dry-run/--dryrun/--noop/--previewbool不做修改打印意图动作后成功退出--enable-commandsstring启用命令前缀列表逗号分隔支持点路径用于收窄 CLI--enable-commands-exactstring精确启用命令列表父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--gmail-no-sendboolfalse阻止 Gmail 发送类操作Agent 安全-h/--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本--no-input/--non-interactive/--noninteractivebool绝不交互提问失败即退出适合 CI-p/--plain/--tsvboolfalse输出稳定可解析文本TSV、无颜色--quota-projectstring计费的 Google Cloud 项目发送为 X-Goog-User-Project部分 API 在--access-token或 ADC 下需要--readonlyboolfalse运行时阻止修改类 API 请求auth add也会仅申请只读 OAuth scope--results-onlyboolJSON 模式下仅输出主结果丢弃 nextPageToken 等信封字段--select/--pick/--projectstringJSON 模式下选择字段逗号分隔支持点路径尽力而为多数命令推荐用--fields-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出时用“外部不可信内容”标记包裹抓取到的文本字段与线程命令配合时值得注意的几个点只读防护--readonly会在运行时拦截修改类 API 请求配合thread get/thread attachments这类纯读取命令可在脚本里确保“绝不改动邮箱”而thread modify这类写操作在--readonly下会被阻止。dry-runthread modify与带--download的thread get/thread attachments都会先经过dryRunExit/attachmentDownloadDryRun-n时只打印意图动作含 thread_id、add/remove 列表或 out_dir并成功退出便于在 CI 中验证参数。CI 友好--no-input保证任何需要交互的地方直接失败而不是挂起等待--json--results-only可以最小化输出方便jq消费。多账户-a 邮箱或别名指定操作账户--home可把整个状态根目录指向隔离目录便于并行会话。安全输出--sanitize-contentthread get专属与--wrap-untrusted全局分别对应“清洗正文”和“标记不可信内容”两种 Agent 消费策略--gmail-no-send则全局封禁发送类操作属于文档标注的 agent safety 开关。八、继续深入命令参考自动生成于gog schema --json修改请运行make docs-commands勿手工编辑gog-gmail-thread.md、gog-gmail-thread-get.md、gog-gmail-thread-modify.md、gog-gmail-thread-attachments.md核心实现internal/cmd/gmail_thread.go三个子命令与GmailURLCmd、internal/cmd/webid.go线程/消息 ID 的链接解析标签解析internal/cmd/gmail_labels_utils.go测试internal/cmd/gmail_thread_cmd_test.gomodify 的 JSON/文本双模式端到端验证、internal/cmd/gmail_thread_run_test.go父命令参考gog-gmail.md全部命令索引见 docs/commands/README.md适用前提命令行为以当前仓库源码为准需先通过gog auth完成相应账户的 Gmail 授权threads.get依赖 Gmail API 的读取 scopethreads.modify依赖修改类 scope--readonly模式下写操作不可用。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考