尧图网站建设 
gog people 使用指南在终端与 Agent 中安全调用 Google People API【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南围绕 gogcligog的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覆盖以下操作命令用途get按 ID 获取用户档案me显示当前账号自己的资料people/meraw以 JSON 输出 People API 原始响应People.Get无损适合脚本与 LLM 消费relations获取用户关系search搜索 Workspace 通讯录从源码看命令组定义在 internal/cmd/people.goPeopleCmd挂载了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 userexample.com people me --json这三条命令各自解决一个问题gog auth list --check --json --no-input以非交互方式检查本地已认证账号及其 OAuth 服务范围输出 JSON。--no-input保证在自动化环境中失败时不挂起等待输入。gog schema people --json输出people命令族的机器可读契约子命令、flag、退出码、安全状态让 Agent 在调用前就能拿到准确语法而不是靠猜。gog --readonly --account userexample.com people me --json以只读模式显式指定账号查询当前用户资料是最小的端到端连通性验证。技能文档同时给出了四条黄金纪律始终用--account显式选择账号避免误用默认账号读取 Google 内容给 Agent 解析时用--json --wrap-untrusted对外部不可信内容加包裹标记任务不允许改动 Google 数据时务必加--readonly自动化环境用--no-input写操作前先--dry-run预演任何写/删操作前先确认准确的账号、对象与变更内容。关于这些共享规则认证、输出、安全、实盘写入规范的完整说明详见同仓库的 .agents/skills/gog/SKILL.mdgog-people技能明确要求先读它。五个子命令实战详解people me查看当前账号资料最常用的命令等价于 People API 的people.get访问people/megog people me gog --readonly --account userexample.com people me --json不带--json时输出为 TSV 风格三行存在才输出name 张三 email userexample.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时命令不会直接失败而是回退到fetchPeopleMeProfileFromTokenpeople.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.gohttps://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 # 别名 showuserId支持三种写法由 people_helpers.go 的normalizePeopleResource归一化处理me→ 自动补全为people/mepeople/12345678901234567890→ 原样使用People API 的资源名格式其它任意字符串 → 自动加上people/前缀例如alice会被当成people/alice解析。所以gog people get userexample.com这类按邮箱裸串查询的写法会尝试构造people/userexample.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 userexample.com --json关键参数参数默认说明userId—Person 资源名people/...或邮箱--person-fields宽泛默认掩码People API 的 personFields 掩码传更窄的列表可缩小输出--pretty关闭紧凑单行美化打印 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分页遍历当前账号的 Connectionspeople/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 userexample.com people search alice --max 20 --json分页与结果控制参数详见 docs/commands/gog-people-search.md参数默认说明--max/--limit50最大结果数--page/--cursor—分页游标--all/--all-pages关闭拉取全部分页--fail-empty/--non-empty/--require-results关闭无结果时以退出码 3 结束便于脚本判断--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。该命令适合快速回答这个人的上级/助理是谁这类组织关系问题。跨命令的通用输出与安全 flaggog people的所有子命令都继承全局根 flag完整清单见 docs/commands/gog-people.md。面向 Agent/自动化下面几组最值得关注场景推荐组合作用机器可读输出--json别名-j/--machinestdout 只输出 JSON人类提示走 stderr解析 Google 内容--json --wrap-untrusted给取自 Google 的文本字段加不可信内容包裹标记防止内容被当成指令字段裁剪--select/--pick/--projectJSON 模式下按点路径选择字段尽力而为去掉信封字段--results-only只保留主结果丢掉nextPageToken等信封字段只读约束--readonly运行时拦截所有变更型 API 请求自动化安全--no-input永不提示失败立即报错适合 CI命令白名单--enable-commands/--disable-commands逗号分隔、支持点路径限制可用命令文本输出-p/--plain/--tsv稳定可解析的 TSV 输出无颜色组合示例严格只读 精确到人适合 Agent 默认执行gog --readonly --enable-commands people.me,people.get --account userexample.com \ people get people/12345678901234567890 --json --wrap-untrusted注意--readonly会同时影响 OAuth 授权auth add在只读模式下只申请只读 scope因此需要写入能力时再移除它并且只在你被明确要求的那一次操作上移除。与其它命令族的协作与边界People 命令是只读的天然适合放进先查后做的自动化流水线。典型组合# 步骤 1确认自己身份 gog --readonly --account userexample.com people me --json --results-only # 步骤 2在通讯录中定位同事 gog --readonly --account userexample.com people search zhang --max 5 --json --wrap-untrusted # 步骤 3用拿到的资源名取完整画像 gog --readonly --account userexample.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_BACKENDfile、GOG_KEYRING_PASSWORD、HOME必须出现在真正启动gog的进程环境里不能只存在于登录 shell共享 Agent 环境优先使用烘焙好的只读/agent-safe 二进制方案见 docs/safety-profiles.md 与仓库根目录 safety-profiles/ 下的agent-safe.yaml、readonly.yaml正式调用前不要猜语法gog people command --help看 flaggog schema people command --json拿机器可读契约。技能文档.agents/skills/gog-people/SKILL.md本身也是为 Agent 生成的技能卡由 scripts/gen-agent-skills.mjs 生成请勿手改其中../gog/SKILL.md的共享规则对应仓库内的 .agents/skills/gog/SKILL.md。实现原理速览源码级把本文涉及的实现串起来可以看到清晰的分层命令注册层internal/cmd/people.go 用 kong 定义PeopleCmd及五个子命令并声明别名get→info,show、search→find,query。服务获取层peopleContactsService(ctx, account)负责按账号解析出 People API clientrequireAccount(flags)强制显式选账号。资源名归一化internal/cmd/people_helpers.go 的normalizePeopleResource把me、裸字符串统一转为people/...资源名。错误包装internal/cmd/people_helpers.go 的wrapPeopleAPIError把accessNotConfigured翻译成带启用链接的可读错误。原始响应internal/cmd/people_raw.go 的runPeopleRaw实现邮箱→资源名解析、默认字段掩码、People.Get调用与 JSON 写出同时被contacts raw复用。容错回退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.mdAgent 技能汇总见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gog people 使用指南：在终端与 Agent 中安全调用 Google People API
gog people 使用指南在终端与 Agent 中安全调用 Google People API【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南围绕 gogcligog的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覆盖以下操作命令用途get按 ID 获取用户档案me显示当前账号自己的资料people/meraw以 JSON 输出 People API 原始响应People.Get无损适合脚本与 LLM 消费relations获取用户关系search搜索 Workspace 通讯录从源码看命令组定义在 internal/cmd/people.goPeopleCmd挂载了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 userexample.com people me --json这三条命令各自解决一个问题gog auth list --check --json --no-input以非交互方式检查本地已认证账号及其 OAuth 服务范围输出 JSON。--no-input保证在自动化环境中失败时不挂起等待输入。gog schema people --json输出people命令族的机器可读契约子命令、flag、退出码、安全状态让 Agent 在调用前就能拿到准确语法而不是靠猜。gog --readonly --account userexample.com people me --json以只读模式显式指定账号查询当前用户资料是最小的端到端连通性验证。技能文档同时给出了四条黄金纪律始终用--account显式选择账号避免误用默认账号读取 Google 内容给 Agent 解析时用--json --wrap-untrusted对外部不可信内容加包裹标记任务不允许改动 Google 数据时务必加--readonly自动化环境用--no-input写操作前先--dry-run预演任何写/删操作前先确认准确的账号、对象与变更内容。关于这些共享规则认证、输出、安全、实盘写入规范的完整说明详见同仓库的 .agents/skills/gog/SKILL.mdgog-people技能明确要求先读它。五个子命令实战详解people me查看当前账号资料最常用的命令等价于 People API 的people.get访问people/megog people me gog --readonly --account userexample.com people me --json不带--json时输出为 TSV 风格三行存在才输出name 张三 email userexample.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时命令不会直接失败而是回退到fetchPeopleMeProfileFromTokenpeople.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.gohttps://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 # 别名 showuserId支持三种写法由 people_helpers.go 的normalizePeopleResource归一化处理me→ 自动补全为people/mepeople/12345678901234567890→ 原样使用People API 的资源名格式其它任意字符串 → 自动加上people/前缀例如alice会被当成people/alice解析。所以gog people get userexample.com这类按邮箱裸串查询的写法会尝试构造people/userexample.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 userexample.com --json关键参数参数默认说明userId—Person 资源名people/...或邮箱--person-fields宽泛默认掩码People API 的 personFields 掩码传更窄的列表可缩小输出--pretty关闭紧凑单行美化打印 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分页遍历当前账号的 Connectionspeople/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 userexample.com people search alice --max 20 --json分页与结果控制参数详见 docs/commands/gog-people-search.md参数默认说明--max/--limit50最大结果数--page/--cursor—分页游标--all/--all-pages关闭拉取全部分页--fail-empty/--non-empty/--require-results关闭无结果时以退出码 3 结束便于脚本判断--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。该命令适合快速回答这个人的上级/助理是谁这类组织关系问题。跨命令的通用输出与安全 flaggog people的所有子命令都继承全局根 flag完整清单见 docs/commands/gog-people.md。面向 Agent/自动化下面几组最值得关注场景推荐组合作用机器可读输出--json别名-j/--machinestdout 只输出 JSON人类提示走 stderr解析 Google 内容--json --wrap-untrusted给取自 Google 的文本字段加不可信内容包裹标记防止内容被当成指令字段裁剪--select/--pick/--projectJSON 模式下按点路径选择字段尽力而为去掉信封字段--results-only只保留主结果丢掉nextPageToken等信封字段只读约束--readonly运行时拦截所有变更型 API 请求自动化安全--no-input永不提示失败立即报错适合 CI命令白名单--enable-commands/--disable-commands逗号分隔、支持点路径限制可用命令文本输出-p/--plain/--tsv稳定可解析的 TSV 输出无颜色组合示例严格只读 精确到人适合 Agent 默认执行gog --readonly --enable-commands people.me,people.get --account userexample.com \ people get people/12345678901234567890 --json --wrap-untrusted注意--readonly会同时影响 OAuth 授权auth add在只读模式下只申请只读 scope因此需要写入能力时再移除它并且只在你被明确要求的那一次操作上移除。与其它命令族的协作与边界People 命令是只读的天然适合放进先查后做的自动化流水线。典型组合# 步骤 1确认自己身份 gog --readonly --account userexample.com people me --json --results-only # 步骤 2在通讯录中定位同事 gog --readonly --account userexample.com people search zhang --max 5 --json --wrap-untrusted # 步骤 3用拿到的资源名取完整画像 gog --readonly --account userexample.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_BACKENDfile、GOG_KEYRING_PASSWORD、HOME必须出现在真正启动gog的进程环境里不能只存在于登录 shell共享 Agent 环境优先使用烘焙好的只读/agent-safe 二进制方案见 docs/safety-profiles.md 与仓库根目录 safety-profiles/ 下的agent-safe.yaml、readonly.yaml正式调用前不要猜语法gog people command --help看 flaggog schema people command --json拿机器可读契约。技能文档.agents/skills/gog-people/SKILL.md本身也是为 Agent 生成的技能卡由 scripts/gen-agent-skills.mjs 生成请勿手改其中../gog/SKILL.md的共享规则对应仓库内的 .agents/skills/gog/SKILL.md。实现原理速览源码级把本文涉及的实现串起来可以看到清晰的分层命令注册层internal/cmd/people.go 用 kong 定义PeopleCmd及五个子命令并声明别名get→info,show、search→find,query。服务获取层peopleContactsService(ctx, account)负责按账号解析出 People API clientrequireAccount(flags)强制显式选账号。资源名归一化internal/cmd/people_helpers.go 的normalizePeopleResource把me、裸字符串统一转为people/...资源名。错误包装internal/cmd/people_helpers.go 的wrapPeopleAPIError把accessNotConfigured翻译成带启用链接的可读错误。原始响应internal/cmd/people_raw.go 的runPeopleRaw实现邮箱→资源名解析、默认字段掩码、People.Get调用与 JSON 写出同时被contacts raw复用。容错回退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.mdAgent 技能汇总见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考