gogcli 中 gog chat spaces 命令详解Google Chat 空间Spaces的列出、查找与创建【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文以docs/commands/gog-chat-spaces.md官方命令参考为主体完整讲解gog chat spaces命令组及其list、find、create三个子命令的用法、参数、输出格式与退出码并结合 internal/cmd/chat_spaces.go 等源码实现说明分页、匹配与成员归一化等关键机制读完即可在脚本中可靠地管理 Google Chat 空间。命令定位与适用前提gog chat spaces是 gogcliGoogle Workspace 终端客户端中管理 Google Chat 空间的命令组官方参考页为 docs/commands/gog-chat-spaces.md该页面由gog schema --json生成可通过make docs-commands重新生成。其命令树如下gog chat ├── dm 直接消息DM ├── messages 消息 ├── spaces 空间本文主题 │ ├── list 列出空间 │ ├── find 按显示名查找 │ └── create 创建空间 └── threads 会话线程这一结构可以直接在源码 internal/cmd/chat.go 中得到印证ChatCmd下挂载spaces、messages、threads、dm四个子命令组而 internal/cmd/chat_spaces.go 中的ChatSpacesCmd结构体通过 kong 标签声明了三个子命令及其别名子命令别名说明listls列出空间findsearch、query按显示名查找空间createadd、new创建空间适用前提Workspace 限制Chat API 仅对 Google Workspace 账号开放。internal/cmd/chat_helpers.go 中的requireWorkspaceAccount会对消费级账号直接报错func requireWorkspaceAccount(account string) error { if isConsumerAccount(account) { return usage(chat requires a Google Workspace account (non-gmail.com)) } return nil }即使用个人 gmail.com 账号运行gog chat spaces ...会被拒绝。使用前需要已通过gog auth add完成对应 Workspace 账号的 OAuth 授权多账号场景下用全局参数-a/--account别名--acct支持邮箱、别名或auto指定目标账号。gog chat spaces list列出空间用法gog chat spaces list (ls) [flags]命令级参数定义于 internal/cmd/chat_spaces.goFlag别名类型/默认说明--max--limitint64默认100每页最大结果数必须大于 0否则报max must be 0--page--cursorstring上一页返回的分页令牌--all--all-pages、--allpagesbool自动抓取所有分页--fail-empty--non-empty、--require-resultsbool无结果时以退出码 3 退出分页机制list底层调用 Chat API 的Spaces.List源码中通过闭包fetch(pageToken)发起请求并用loadPagedItems(c.Page, c.All, fetch)统一处理单页或全量抓取见 internal/cmd/chat_spaces.go。当结果仍存在下一页而用户未加--all时终端会打印类似--all/--all-pages的翻页提示printNextPageHintWithAll。输出格式文本模式默认表格列由 internal/cmd/chat_presentation.go 的chatSpaceColumns()固定为三列RESOURCEspaces/...资源名、NAME显示名、TYPE空间类型。JSON 模式-j/--json/--machine输出结构为{ spaces: [ { resource: spaces/AbCd..., name: Engineering, type: SPACE, uri: https://chat.google.com/..., threading: THREADING_DISABLED } ], nextPageToken: ... }对应源码 internal/cmd/chat_spaces.goJSON 项比文本表格多出urispaceUri与threadingthreading state两个字段适合脚本直接消费。空结果处理无结果时文本模式打印No spaces若指定--fail-empty则返回退出码 3failEmptyExit便于 CI/脚本判断“空间不存在”。示例# 默认列前 100 个空间 gog chat spaces list # 限制每页 50 条并用上一页令牌翻页 gog chat spaces list --max 50 --page 上次输出的nextPageToken # 抓取全部分页并输出 JSON gog chat spaces list --all -j # 无结果时以退出码 3 失败适合脚本断言 gog chat spaces list --fail-emptygog chat spaces find按显示名查找用法gog chat spaces find (search,query) displayName [flags]displayName为必填位置参数空值会报required: displayName。命令级参数internal/cmd/chat_spaces.goFlag类型/默认说明--max/--limitint64默认100每页最大结果数--exactbool要求对 displayName 做精确忽略大小写匹配而非子串匹配匹配语义默认是“子串包含 忽略大小写”加--exact后转为“完全相等 忽略大小写”。实现见 internal/cmd/chat_spaces.gofunc chatSpaceDisplayNameMatches(displayName, query string, exact bool) bool { if exact { return strings.EqualFold(displayName, query) } return strings.Contains(strings.ToLower(displayName), strings.ToLower(query)) }注意实现细节find并非服务端搜索而是逐页拉取全部空间后在本地过滤——源码中collectAllPages(, fetch)会遍历所有分页见 internal/cmd/chat_spaces.go因此空间数量很大时耗时与请求量会随之增长。JSON 模式输出为{spaces: [{resource, name, type, uri}]}无匹配时文本模式打印No results且正常退出退出码 0无--fail-empty语义。示例# 子串匹配默认 gog chat spaces find Engineering # 精确匹配显示名忽略大小写 gog chat spaces find Engineering --exact -jgog chat spaces create创建空间用法gog chat spaces create (add,new) displayName [flags]Flag说明displayName必填位置参数空间显示名自动去除首尾空白--member空间成员邮箱或users/...资源名可重复传多次也支持逗号分隔一次传多个成员归一化规则创建流程先经newChatSpaceCreatePlan构造请求计划internal/cmd/chat_space_create_plan.go所有--member值先经parseCommaArgs按逗号拆分并去空白internal/cmd/chat_helpers.go所以--member acorp.com,bcorp.com与--member acorp.com --member bcorp.com等价以users/开头的值视为 Chat 用户资源名其中的 id 不允许再含/或空白等非法字符否则报invalid --member其余值按纯邮箱校验validatePlainEmail通过后自动补全为users/email每个成员生成一条MembershipMember.Type固定为HUMAN请求体为SetUpSpaceRequestSpace.SpaceType固定为SPACE最终经svc.Spaces.Setup(...).Do()提交internal/cmd/chat_spaces.go。Dry-run 支持create支持全局-n/--dry-run别名--dryrun、--noop、--preview。源码在真正调用 API 前执行dryRunExit(ctx, flags, chat.spaces.create, plan.dryRunPayload())其载荷包含三个字段internal/cmd/chat_space_create_plan.go{ display_name: Engineering, members: [acorp.com, users/bcorp.com], member_users: [users/acorp.com, users/bcorp.com] }其中member_users是归一化后的资源名可用于校验成员解析是否符合预期而不实际创建空间。输出JSON 模式{space: Space 对象}即 API 返回的完整 Space 资源文本模式输出resourcespaces/...与name显示名两行键值对供cut/awk解析。创建结果的 resourcespaces/id是后续所有消息类命令的关键入参internal/cmd/chat_helpers.go 的normalizeSpace接受完整资源名或裸 ID 并统一补成spaces/id形式可直接用于gog chat messages send、gog chat threads list等下游命令参见 docs/commands/gog-chat-messages.md、docs/commands/gog-chat-threads.md。示例# 创建并加入成员 gog chat spaces create Release-42 --member acorp.com --member bcorp.com # 逗号分隔写法等价 gog chat spaces create Release-42 --member acorp.com,bcorp.com -j # 先演练打印将执行的动作含归一化后的 member_users不真正创建 gog chat spaces create Release-42 --member acorp.com -n # 提取新空间资源名供后续命令使用 gog chat spaces create Release-42 -p | awk -F\t $1resource{print $2}验证覆盖上述行为均有测试保障internal/cmd/chat_space_create_plan_test.go 覆盖了成员逗号拆分、users/前缀归一化、显示名空白裁剪、缺少 displayName 与非法成员的报错以及无成员时Memberships为 nil 的分支。通用全局参数spaces 命令组继承gog chat spaces命令组继承 gogcli 的根级参数完整列表见 docs/commands/gog-chat-spaces.md。与日常使用最相关的摘录Flag类型默认说明-j/--json/--machineboolfalse向 stdout 输出 JSON最适合脚本-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 文本无颜色--select/--pick/--projectstringJSON 模式下选取逗号分隔字段尽力而为支持点路径--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等外层字段-n/--dry-run/--noop/--previewbool不产生变更打印将执行的动作后成功退出-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--no-input/--non-interactivebool从不交互提示直接失败适合 CI--readonlyboolfalse运行时拦截一切变更类 API 请求-a/--account/--acctstring指定账号邮箱、别名或auto--clientstring选择 OAuth 客户端凭据 token 桶--access-tokenstring直接使用给定 access token绕过本地 refresh token约 1 小时过期--quota-projectstring计费项目X-Goog-User-Project--access-token或 ADC 场景下部分 API 必需--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME--enable-commands/--enable-commands-exactstring按点路径白名单限制 CLI 可用命令--disable-commandsstring按点路径黑名单禁用命令--wrap-untrustedboolfalseJSON/raw 输出时将抓取到的文本字段包裹为外部不可信内容标记-v/--verbosebool开启详细日志--colorstringauto着色输出auto|always|never其中--readonly对list/find天然安全但对create会在运行时拦截写请求是自动化环境下防止误创建空间的直接手段Agent 化使用可参考 safety-profiles/agent-safe.yaml 等内置安全配置。源码级实现要点小结命令结构ChatSpacesCmdinternal/cmd/chat_spaces.go是纯声明式结构体每个子命令的Run方法负责参数校验 → 账号解析requireAccountrequireWorkspaceAccount→ 获取chatService→ 调 API → 按outfmt.IsJSON(ctx)分支输出符合仓库统一的命令实现模式。计划/演练模式create将“解析与请求构造”抽离为chatSpaceCreatePlaninternal/cmd/chat_space_create_plan.go使 dry-run 可以在不触碰网络的情况下输出可审计的载荷这也是仓库中 mutation 类命令的通用做法。输出约定文本表格统一经outfmt.WriteTable渲染列定义集中在 internal/cmd/chat_presentation.go对显示名等字段做了制表符/换行清洗sanitizeTab、sanitizeChatText保证 TSV 输出-p不会因内容破坏列对齐。空值防护compactChatRows会过滤切片中的 nil 元素internal/cmd/chat_presentation.go避免 API 返回异常条目时 panic。典型工作流创建空间并发消息脚本化# 1. 演练确认后创建空间拿到 resource SPACE$(gog chat spaces create Ops-Alerts --member oncallcorp.com -j \ | sed -n s/.*space:{[^}]*name:spaces\/[^]*.*//p) # 示例按 JSON 提取 name 字段 # 2. 验证空间已存在按显示名精确查找 gog chat spaces find Ops-Alerts --exact -j # 3. 无结果断言CI 中确认尚未创建 gog chat spaces list --all -j --select resource | grep -q Ops-Alerts更稳健的做法是解析create -j的space.name字段JSON 结构见上文后直接传给消息命令避免再次查找。参考命令参考页docs/commands/gog-chat-spaces.md、gog-chat-spaces-list.md、gog-chat-spaces-find.md、gog-chat-spaces-create.md、gog-chat.md命令索引docs/commands/README.md核心实现internal/cmd/chat_spaces.go、internal/cmd/chat_space_create_plan.go、internal/cmd/chat_helpers.go、internal/cmd/chat_presentation.go、internal/cmd/chat.go测试internal/cmd/chat_space_create_plan_test.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考