企业官网建设流程全解析

gog people 使用指南：在终端与 Agent 中安全调用 Google People API

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

本指南围绕 gogcli（gog）的people命令族展开，讲解如何在终端、脚本与 AI Agent 场景下，通过 Google People API 完成"查看我的资料、按 ID 获取用户档案、搜索 Workspace 通讯录、读取用户关系、导出无损 JSON"等操作。读完本文，你将掌握gog people五个子命令的完整用法、核心 flag 的作用与默认值，以及--readonly、--json --wrap-untrusted、--no-input等跨命令安全规则如何在 People 场景落地。

定位：gog people是什么

gog（项目名为 gogcli，描述为 "Google Workspace in your terminal."）把 Google Workspace 常用操作封装为可脚本化、可被 LLM/Agent 稳定消费的 CLI。gog people是其中的一个人物/通讯录命令组，对应 Google People API，覆盖以下操作：

从源码看，命令组定义在 internal/cmd/people.go：PeopleCmd挂载了me、get（别名info,show）、search（别名find,query）、relations、raw五个子命令，全部是只读操作，本身不产生任何写入副作用。get与raw都建立在 People API 的people.get之上，区别在于get返回整理后的简短字段，raw返回完整的原始 Person 资源。

快速开始：安全启动三段式

技能文档（.agents/skills/gog-people/SKILL.md）给出了一组"Safe start"命令，建议任何 Agent 或脚本在正式操作前先跑一遍，确认认证、schema 与只读能力都就绪：

gog auth list --check --json --no-input gog schema people --json gog --readonly --account user@example.com people me --json

这三条命令各自解决一个问题：

1. gog auth list --check --json --no-input：以非交互方式检查本地已认证账号及其 OAuth 服务范围，输出 JSON。--no-input保证在自动化环境中失败时不挂起等待输入。
2. gog schema people --json：输出people命令族的机器可读契约（子命令、flag、退出码、安全状态），让 Agent 在调用前就能拿到准确语法，而不是靠猜。
3. gog --readonly --account user@example.com people me --json：以只读模式显式指定账号查询当前用户资料，是最小的端到端连通性验证。

技能文档同时给出了四条黄金纪律：

• 始终用--account显式选择账号，避免误用默认账号；
• 读取 Google 内容给 Agent 解析时，用--json --wrap-untrusted（对外部不可信内容加包裹标记）；
• 任务不允许改动 Google 数据时，务必加--readonly；
• 自动化环境用--no-input，写操作前先--dry-run预演；
• 任何写/删操作前，先确认准确的账号、对象与变更内容。

关于这些共享规则（认证、输出、安全、实盘写入规范）的完整说明，详见同仓库的 .agents/skills/gog/SKILL.md（gog-people技能明确要求先读它）。

五个子命令实战详解

people me：查看当前账号资料

最常用的命令，等价于 People API 的people.get访问people/me：

gog people me gog --readonly --account user@example.com people me --json

不带--json时，输出为 TSV 风格三行（存在才输出）：

name 张三 email user@example.com photo https://lh3.googleusercontent.com/...

从 internal/cmd/people.go 的实现看，它请求的 personFields 掩码是names,emailAddresses,photos，即只取姓名、邮箱、头像三项。重要的容错设计：当 People API 返回 403 且 reason 为accessNotConfigured（或错误文本包含 "People API has not been used"）时，命令不会直接失败，而是回退到fetchPeopleMeProfileFromToken（people.go）：从本地 OAuth 令牌存储中读取 refresh token，通过IdentityForRefreshToken换取身份信息，至少给出 email。也就是说，即使 People API 尚未在 GCP 项目里启用，people me --json也能返回基于 token 的身份摘要，而不是干巴巴报错。

提示：若看到 "people API is not enabled" 类错误，需要在 Google Cloud Console 的 API 库中启用 People API。源码中把该链接写死在 people_helpers.go：https://console.cloud.google.com/apis/library/people.googleapis.com，报错信息会自动带上这个 URL。

people get：按 ID 获取用户档案

gog people get <userId> gog people get info <userId> # 别名 info gog people show <userId> # 别名 show

<userId>支持三种写法（由 people_helpers.go 的normalizePeopleResource归一化处理）：

• me→ 自动补全为people/me；
• people/12345678901234567890→ 原样使用（People API 的资源名格式）；
• 其它任意字符串 → 自动加上people/前缀，例如alice会被当成people/alice解析。

所以gog people get user@example.com这类按邮箱裸串查询的写法，会尝试构造people/user@example.com资源名——如果失败，请改用raw命令（见下节，它内置了邮箱→资源名的解析流程），或直接使用形如people/开头的标准资源名。需要查看完整 flag 列表可执行gog people get --help，或直接阅读生成的命令文档 docs/commands/gog-people-get.md。

people raw：无损原始 JSON，供脚本与 LLM 消费

raw是 People 命令族中"信息量最大"的一个，直接转发 People API 的people.get响应，不做字段裁剪：

gog people raw <userId> --json gog people raw <userId> --json --pretty --person-fields names,emailAddresses,photos gog people raw user@example.com --json

关键参数：

默认掩码定义在 people_raw.go，覆盖了常见字段全集：

names,emailAddresses,phoneNumbers,organizations,urls,addresses,biographies, birthdays,photos,metadata,relations,userDefined,memberships,events,imClients, interests,locales,nicknames,occupations,skills

按邮箱解析资源名：当<userId>包含@且不是people/前缀时，raw会走一段"邮箱查找"逻辑（people_raw.go）：分页遍历当前账号的 Connections（people/me的联系人，每页 1000 条），用names,emailAddresses,metadata掩码匹配邮箱。三种结果：

• 恰好匹配 1 个联系人 → 用该联系人的people/...资源名继续People.Get；
• 匹配 0 个 → 报错contact not found for email "..."；
• 匹配多个 → 报错提示使用明确的people/...资源名（避免歧义）。

这种"邮箱进、无损 JSON 出"的能力，特别适合 Agent 在只知道对方邮箱时，一次性拿到完整联系人画像。另外，raw的内部实现runPeopleRaw也被contacts raw命令复用（见 people_raw.go），所以 People 与 Contacts 两个命令组共享同一套底层逻辑。

people search：搜索 Workspace 通讯录

gog people search 'alice' gog people search find 'alice' # 别名 find gog people search query 'alice' # 别名 query gog --readonly --account user@example.com people search 'alice' --max 20 --json

分页与结果控制参数（详见 docs/commands/gog-people-search.md）：

--fail-empty让"搜索无结果"变成可检测的退出码而不是静默空输出，这是把搜索接入自动化流水线时的关键设计。

people relations：获取用户关系

gog people relations # 当前账号自己的关系 gog people relations <userId> gog people relations <userId> --type manager # 按关系类型过滤

<userId>可省略，省略时作用于当前账号。--type用于过滤关系类型（如manager、assistant、spouse等 People API 支持的关系类型值），flag 细节见 docs/commands/gog-people-relations.md。该命令适合快速回答"这个人的上级/助理是谁"这类组织关系问题。

跨命令的通用输出与安全 flag

gog people的所有子命令都继承全局根 flag（完整清单见 docs/commands/gog-people.md）。面向 Agent/自动化，下面几组最值得关注：

组合示例（严格只读 + 精确到人，适合 Agent 默认执行）：

gog --readonly --enable-commands people.me,people.get --account user@example.com \ people get people/12345678901234567890 --json --wrap-untrusted

注意：--readonly会同时影响 OAuth 授权（auth add在只读模式下只申请只读 scope），因此需要写入能力时再移除它，并且只在你被明确要求的那一次操作上移除。

与其它命令族的协作与边界

People 命令是只读的，天然适合放进"先查后做"的自动化流水线。典型组合：

# 步骤 1：确认自己身份 gog --readonly --account user@example.com people me --json --results-only # 步骤 2：在通讯录中定位同事 gog --readonly --account user@example.com people search 'zhang' --max 5 --json --wrap-untrusted # 步骤 3：用拿到的资源名取完整画像 gog --readonly --account user@example.com people raw people/12345678901234567890 --json --pretty

边界说明：

• people读取的是"人物档案 + Workspace 通讯录"；若你主要面向个人联系人簿操作，仓库还提供contacts命令组（contacts list、contacts search等），二者在raw底层共享runPeopleRaw实现（people_raw.go），可互为备用入口；
• people命令组没有写操作，不要期望用它增删改联系人；涉及联系人写操作时，请在动手前确认对应命令存在且--dry-run可用；
• 组织架构批量查询（如管理员视角的成员枚举）通常走admin命令组，而不是people搜索。

为 Agent 环境做准备

如果你在 headless/服务化环境运行 Agent：

• 用--no-input让认证/钥匙串失败时立刻暴露问题，而不是挂死等待；
• 文件钥匙串场景下，GOG_KEYRING_BACKEND=file、GOG_KEYRING_PASSWORD、HOME必须出现在真正启动gog的进程环境里（不能只存在于登录 shell）；
• 共享 Agent 环境优先使用烘焙好的只读/agent-safe 二进制，方案见 docs/safety-profiles.md 与仓库根目录 safety-profiles/ 下的agent-safe.yaml、readonly.yaml；
• 正式调用前不要猜语法：gog people <command> --help看 flag，gog schema people <command> --json拿机器可读契约。技能文档（.agents/skills/gog-people/SKILL.md）本身也是为 Agent 生成的技能卡（由 scripts/gen-agent-skills.mjs 生成，请勿手改），其中../gog/SKILL.md的共享规则对应仓库内的 .agents/skills/gog/SKILL.md。

实现原理速览（源码级）

把本文涉及的实现串起来，可以看到清晰的分层：

1. 命令注册层：internal/cmd/people.go 用 kong 定义PeopleCmd及五个子命令，并声明别名（get→info,show、search→find,query）。
2. 服务获取层：peopleContactsService(ctx, account)负责按账号解析出 People API client；requireAccount(flags)强制显式选账号。
3. 资源名归一化：internal/cmd/people_helpers.go 的normalizePeopleResource把me、裸字符串统一转为people/...资源名。
4. 错误包装：internal/cmd/people_helpers.go 的wrapPeopleAPIError把accessNotConfigured翻译成带启用链接的可读错误。
5. 原始响应：internal/cmd/people_raw.go 的runPeopleRaw实现邮箱→资源名解析、默认字段掩码、People.Get调用与 JSON 写出，同时被contacts raw复用。
6. 容错回退：internal/cmd/people.go 的fetchPeopleMeProfileFromToken在 People API 未启用时，用 refresh token 换取身份兜底，保证me至少能返回 email。

相关测试位于 internal/cmd/people_raw_test.go 与 internal/cmd/people_testutil_test.go，可作为理解各命令行为的补充样例。更多命令总览见 docs/commands/README.md，Agent 技能汇总见 docs/agent-skills.md。

小结

gog people用五个只读子命令覆盖了 Google People API 的主要查询场景：me自查、get精确取档、raw无损导出（支持邮箱解析资源名）、relations查关系、search搜通讯录。配合--readonly、--json --wrap-untrusted、--no-input与--enable-commands这套跨命令安全组合，它既能作为交互式终端工具，也能稳定嵌入 Agent 与 CI 流水线。记住两条原则即可：先schema/--help拿准确语法，再--dry-run/--readonly兜底执行。

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli