gogcligog chat命令组实战指南Google Chat 的终端操作与 Agent 集成参考【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇指南以 gogcli 的gog chat命令族为主体系统讲解 Google Chat 在命令行中的完整操作面Space 管理、消息收发与检索、表情回应、线程Thread与 DM 直聊。读完后你可以直接复制命令在脚本、CI 或 Agent 工作流中驱动 Google Chat并理解各命令背后的源码实现与安全性开关dry-run、readonly、命令白名单。本文内容基于仓库生成的命令参考 docs/commands/gog-chat.md 及其全部子命令页面结合 internal/cmd 下的实际实现代码撰写。命令族总览与目录结构gog chat是 gogcli 中专用于 Google Chat API 的顶层命令组其用法形如gog chat command [flags]从 docs/commands/gog-chat.md 定义的命令树看整个命令族分为四条主线gog chat ├── dm # Direct messages直聊/单聊 │ ├── dm send # 向某个邮箱地址发送直聊消息 │ └── dm space # 查找或创建与对方的 DM Space ├── messages # Chat messages消息操作 │ ├── list # 列出 Space 中的消息含线程过滤、未读过滤 │ ├── react # 给消息添加 emoji 回应 │ ├── reactions # 回应管理create / delete / list │ ├── search # 跨 Chat 全局搜索消息 │ └── send # 发送消息支持附件与线程回复 ├── spaces # Chat spacesSpace 管理 │ ├── create # 创建 Space │ ├── find # 按显示名称查找 Space │ └── list # 列出 Space └── threads # Chat threads线程 └── list # 列出 Space 中的线程注意 gogcli 的命令风格许多叶子命令带有同义动词别名括号中即别名例如gog chat messages send (create,post) space、gog chat messages list (ls) space、gog chat spaces list (ls)、gog chat messages search (find,query) query、gog chat dm space (find,setup) email。这让命令既兼容 REST 语义create/post又兼容 shell 习惯ls/find。全局 Flags认证、输出与安全控制gog chat及其所有子命令共享一套完整的全局 flag继承自 docs/commands/gog-chat.md 的 Flags 表。理解这组 flag 是安全地把 chat 命令接入自动化流水线的前提Flag类型默认值说明--access-tokenstring直接使用给定的 access token绕过本地存储的 refresh tokentoken 约 1 小时后过期-a/--account/--acctstring指定账号邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth client 名称选择对应的已存凭据 token bucket--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向 stdout 输出 JSON最适合脚本处理--no-input/--non-interactive/--noninteractivebool永不提示直接失败适合 CI 场景-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 文本无颜色--quota-projectstring用于 API 计费计量的 Google Cloud 项目以X-Goog-User-Project发送部分 API 在使用--access-token或 ADC 时必填--readonlyboolfalse运行时阻断一切写操作请求auth add时也只申请只读 OAuth scope--results-onlyboolJSON 模式下仅输出主结果丢弃 nextPageToken 等包装字段--select/--pick/--projectstringJSON 模式下按逗号分隔的字段选择尽力而为支持点路径。更推荐多数命令使用--fields-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/raw 输出中把取回的外部文本字段包裹在“外部不可信内容”标记内其中三个组合对 Agent 场景尤为关键--dry-run任何写操作发消息、建 Space、贴回应都可以先预览命令会打印意图动作后以成功状态码退出是“先验证再执行”的标准手段--readonly在运行时层面直接阻断变更类 API 请求配合--enable-commands前缀白名单例如只允许chat.messages.list,chat.spaces.list可以给 Agent 一份“只读 限定范围”的 CLI--no-input保证非交互环境下任何需要提示的步骤都会失败而不是挂起适合 CI 与定时任务。--wrap-untrusted则专门服务于 LLM 消费场景当 chat 消息文本本身可能包含指令性内容prompt injection时该开关把外部文本明确标记为不可信内容降低模型误将其当作指令执行的风险。Space 管理list / find / createSpace 是 Google Chat 中消息与线程的容器几乎所有消息类命令的第一个位置参数都是 Space 名称形如spaces/...。列出 Spacegog chat spaces list (ls) [flags]该命令的专属 flag引自 docs/commands/gog-chat-spaces-list.mdFlag类型默认值说明--all/--all-pages/--allpagesbool抓取全部分页--fail-empty/--non-empty/--require-resultsbool无结果时以退出码 3 退出--max/--limitint64100最大结果数--page/--cursorstring分页 token典型用法-p -j --all gog chat spaces list拿到全部 Space 的 JSON/TSV 列表--fail-empty的退出码 3 约定适合在脚本中判断“空间不存在”。按显示名查找与创建gog chat spaces find display_name按显示名称查找 Space是“用人类可读名称定位 Space ID”的入口后续把spaces/...ID 传给消息命令gog chat spaces create创建新 Space。配合-ndry-run可先预览创建参数。Space 定位的推荐链路spaces find或spaces list -p拿到spaces/ID → 传给messages list/messages send。消息操作send / list / search / react发送消息支持附件与线程回复gog chat messages send (create,post) space [flags]专属 flag引自 docs/commands/gog-chat-messages-send.mdFlag类型说明--textstring消息文本未提供--attach时必填--attach[]string附件文件路径例如图片可重复传入多个--threadstring回复到指定线程spaces/.../threads/...三个要点纯附件消息合法--text在提供了--attach时不再是必填可以只发一张图片线程回复--thread接收线程全名spaces/space/threads/thread用于在既有线程内继续对话而不是新开线程可预览加上-n后不真正发送仅打印将要发送的内容方便在 Agent 工作流里做“生成 → 预览 → 用户确认 → 发送”的闭环。列出消息gog chat messages list (ls) space [flags]专属 flag引自 docs/commands/gog-chat-messages-list.mdFlag类型默认值说明--all/--all-pages/--allpagesbool抓取全部分页--fail-empty/--non-empty/--require-resultsbool无结果时以退出码 3 退出--max/--limitint6450最大结果数--orderstring排序方式例如createTime desc--page/--cursorstring分页 token--threadstring按线程过滤spaces/.../threads/...--unreadbool仅返回最后阅读时间之后的消息其中--unread是“终端收件箱”场景的核心轮询一次gog chat messages list space --unread -j就能拿到自上次阅读以来的增量消息--thread则把输出收窄到某条讨论线。全局搜索gog chat messages search (find,query) query ... [flags]search是跨全部 Chat 的检索命令专属 flag引自 docs/commands/gog-chat-messages-search.mdFlag类型默认值说明--all/--all-pages/--allpagesbool抓取全部分页--fail-empty/--non-empty/--require-resultsbool无结果时以退出码 3 退出--markupstring格式化文本语法chat或markdown--max/--limitint6425每页最大结果数--orderstring排序create_time desc或relevance descDeveloper Preview--page/--cursorstring分页 token--viewstringbasic结果视图basic或fullquery ...表示查询词可以是多个位置参数。两个实用细节--view full返回完整消息体含格式化文本--markup chat与--markup markdown决定返回的文本是 Chat 原生格式还是 Markdown--order relevance desc目前标注为 Developer Preview 能力使用时应以当前 API 支持为准。仓库还保留了针对 chat 搜索的 live 测试脚本如 scripts/live_chat_search_test.go可用于了解该命令在真实 API 下的验证方式。emoji 回应react 与 reactions 管理# 给消息贴一个 emoji快捷方式 gog chat messages react message emoji [flags] # 回应资源的完整管理 gog chat messages reactions (reaction) command ├── reactions create # 添加 emoji 回应 ├── reactions delete # 删除回应 └── reactions list # 列出消息上的回应react的专属 flag引自 docs/commands/gog-chat-messages-react.md只有一个值得注意的--spacestring当message只是裸 ID 时必填用于补全消息所在的 Space。位置参数message既可以是完整资源名spaces/.../messages/...也可以是裸消息 ID --space。reactions子树则对应 Chat API 中 reaction 的增删查适合需要“列出某人贴了哪些回应”“批量清理回应”的自动化场景。DM 直聊dm space 与 dm sendDMDirect Message是与单个用户的双向直聊无需先知道 Space ID用对方邮箱地址即可。定位或建立 DM Spacegog chat dm space (find,setup) email该命令的语义是“查找或创建”如果与email的 DM Space 已存在则返回它否则创建。这是自动化脚本里最常用的一步——它把“人和邮箱地址”映射成后续dm send所需的spaces/...资源名参见 docs/commands/gog-chat-dm-space.md。发送直聊消息gog chat dm send (create,post) email [flags]专属 flag引自 docs/commands/gog-chat-dm-send.mdFlag类型说明--textstring消息文本必填--threadstring回复到线程spaces/.../threads/...一条典型的“确保通道存在 发送”组合# 1. 找到/建立与对方邮箱的 DM Space拿到 spaces/... 名称 gog chat dm space teammateexample.com -p # 2. 发送文本-y 跳过确认先加 -n 预览 gog chat dm send teammateexample.com --text 部署已完成请验证 -ydm send同样支持--thread在既有 DM 线程中续写与全局--dry-run、-j、-p等 flag 的组合规则一致。线程threads listgog chat threads list space [flags]专属 flag引自 docs/commands/gog-chat-threads-list.md与消息列表高度一致--all、--fail-empty、--max默认50、--page等。线程是 Space 内的讨论线threads list输出的spaces/.../threads/...正是messages list --thread与messages send --thread接受的过滤/回复目标三者构成“列线程 → 按线程读消息 → 在线程中回复”的闭环。源码结构与实现位置从源码结构看chat 命令族集中在 internal/cmd 包下按功能拆分为五个文件与文档命令树一一对应internal/cmd/chat_spaces.go — Space 的 list/find/createinternal/cmd/chat_messages.go — 消息 send/list/search/reactinternal/cmd/chat_reactions.go — reactions 的 create/delete/listinternal/cmd/chat_threads.go — 线程列表internal/cmd/chat_dm.go — DM space 与 DM send。命令的 flag 定义、别名ls、find、create/post等与 Kong 解析配置均在上述文件中声明页面中“Generated fromgog schema --json”的提示说明这些命令参考页由 schema 导出工具自动生成仓库提供make docs-commands目标因此文档与代码在 flag 层面保持一致。此外仓库还包含 chat 相关的 live 测试脚本 scripts/live-chat-test.sh 与 scripts/live_chat_search_test.go可作为命令真实行为验证的参考。脚本化与 Agent 集成的推荐姿势基于上述命令与 flag 的组合几类高频用法# 只读巡检列出某 Space 最近 20 条消息TSV便于 diff gog chat messages list spaces/xxx --max 20 --order createTime desc -p # 增量轮询只拿未读消息JSON 供后续处理 gog chat messages list spaces/xxx --unread -j --results-only # 搜索 无结果显式失败退出码 3用于 CI 断言 gog chat messages search 发布 事故 --view full --fail-empty -j # Agent 受限运行只读 命令白名单 不可信内容包裹 gog chat messages search 关键词 -j \ --readonly --enable-commands chat.messages,chat.spaces,chat.threads \ --wrap-untrusted --no-input # 发送前预览 gog chat dm send teammateexample.com --text ... -n安全要点回顾--readonly保证零副作用--enable-commands/--disable-commands收窄命令面--no-input防挂起--wrap-untrusted隔离外部文本-n提供发送前预览。这套组合使gog chat既能作为人类日常终端工具也能作为 LLM Agent 在受控权限下操作 Google Chat 的执行层。相关文档命令参考总索引docs/commands/README.md父命令docs/commands/gog.md各子命令参考页gog-chat-dm.md、gog-chat-messages.md、gog-chat-spaces.md、gog-chat-threads.md安全配置主题docs/safety-profiles.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考