用途
gws-people 是 Google Workspace CLI（gws）中面向 Google People API（v1）的命令行技能，用于管理联系人和个人资料。它把 People API 的资源与方法映射为命令行调用，命令形式为：
gws people <resource> <method> [flags]
前置条件
使用前需阅读 ../gws-shared/SKILL.md，了解认证方式、全局标志和安全规则。如果该文件缺失，可运行 gws generate-skills 生成。
主要能力（API 资源与方法）
contactGroups（联系人分组）
- batchGet：通过指定一组联系人分组资源名称，获取已认证用户拥有的联系人分组列表。
- create：创建属于已认证用户的新联系人分组。分组名称在用户的分组中必须唯一，重名会返回 HTTP 409 错误。同一用户的变更请求应顺序发送，以避免延迟增加和失败。
- delete：通过指定联系人分组资源名称，删除已认证用户拥有的现有联系人分组。同一用户的变更请求应顺序发送。
- get：通过指定联系人分组资源名称，获取已认证用户拥有的特定联系人分组。
- list：列出已认证用户拥有的所有联系人分组，但不填充分组中的成员。
- update：更新已认证用户拥有的现有联系人分组名称。名称必须唯一，重名返回 HTTP 409 错误。同一用户的变更请求应顺序发送。
- members：对 members 资源的操作。
otherContacts（其他联系人）
- copyOtherContactToMyContactsGroup：将“其他联系人”复制为用户“myContacts”分组中的新联系人。同一用户的变更请求应顺序发送。
- list：列出所有“其他联系人”，即不在任何联系人分组中的联系人。“其他联系人”通常是由交互自动创建的联系人。同步令牌在完整同步后 7 天过期；使用过期同步令牌的请求会返回带有 google.rpc.ErrorInfo、原因为 EXPIRED_SYNC_TOKEN 的错误，此时客户端应不带 sync_token 发起完整同步请求。
- search：在已认证用户的其他联系人中返回匹配搜索查询的联系人列表。查询匹配来自 OTHER_CONTACT 来源的联系人 names、emailAddresses 和 phoneNumbers 字段。重要：搜索前客户端应发送一个空查询的预热请求以更新缓存。参见 https://developers.google.com/people/v1/other-contacts#search_the_users_other_contacts
people（人员）
- batchCreateContacts：批量创建新联系人并返回新联系人的 PersonResponses。同一用户的变更请求应顺序发送。
- batchUpdateContacts：批量更新联系人并返回资源名称到更新后联系人 PersonResponses 的映射。同一用户的变更请求应顺序发送。
- createContact：创建新联系人并返回该联系人的 person 资源。如果对联系人来源中为单例的字段（biographies、birthdays、genders、names）指定了多个字段，请求会返回 400 错误。同一用户的变更请求应顺序发送。
- deleteContactPhoto：删除联系人的照片。同一用户的变更请求应顺序执行，以避免锁争用。
- get：通过指定资源名称提供某个人的信息。使用 people/me 表示已认证用户。如果未指定 personFields，请求返回 400 错误。
- getBatchGet：通过指定一组请求的资源名称，提供一组特定人员的信息。使用 people/me 表示已认证用户。如果未指定 personFields，请求返回 400 错误。
- listDirectoryPeople：提供已认证用户域目录中的域个人资料和域联系人列表。当指定 sync_token 时，自上次同步以来删除的资源会以 PersonMetadata.deleted 设为 true 的 person 返回。当指定 page_token 或 sync_token 时，所有其他请求参数必须与首次调用一致。同步请求的写入可能有几分钟的传播延迟。增量同步不适用于写后读场景。
- searchContacts：在已认证用户的分组联系人中返回匹配搜索查询的联系人列表。查询匹配来自 CONTACT 来源的联系人 names、nickNames、emailAddresses、phoneNumbers 和 organizations 字段。重要：搜索前客户端应发送一个空查询的预热请求以更新缓存。参见 https://developers.google.com/people/v1/contacts#search_the_users_contacts
- searchDirectoryPeople：在已认证用户的域目录中返回匹配搜索查询的域个人资料和域联系人列表。
- updateContact：更新现有联系人的人员数据。任何非联系人数据不会被修改；要更新的人员中的任何非联系人数据将被忽略。update_mask 中指定的所有字段都会被替换。如果要更新的联系人未指定 person.metadata.sources 或没有联系人来源，服务器返回 400 错误。
- updateContactPhoto：更新联系人的照片。同一用户的变更请求应顺序发送。
- connections：对 connections 资源的操作。
使用方式
在调用任何 API 方法前，先检查它：
浏览资源和方法
gws people --help
查看方法的必需参数、类型和默认值
gws schema people.<resource>.<method>
使用 gws schema 的输出构建 --params 和 --json 标志。
适用场景
适用于需要通过命令行批量或自动化管理 Google 联系人、联系人分组、其他联系人以及域目录人员的场景，例如批量创建/更新联系人、搜索联系人、同步目录人员、管理联系人照片等。
限制
- 同一用户的变更（Mutate）请求应顺序发送，以避免延迟增加和失败；删除联系人照片时顺序执行以避免锁争用。
- 联系人分组名称在用户的分组中必须唯一，重名返回 HTTP 409 错误。
- 创建联系人时，对单例字段（biographies、birthdays、genders、names）指定多个字段会返回 400 错误。
- get 与 getBatchGet 未指定 personFields 时返回 400 错误。
- updateContact 未指定 person.metadata.sources 或没有联系人来源时返回 400 错误。
- otherContacts 的同步令牌在完整同步后 7 天过期，过期后需不带 sync_token 发起完整同步。
- listDirectoryPeople 的同步请求写入可能有几分钟传播延迟，增量同步不适用于写后读场景。
- 搜索联系人或其他联系人前需发送空查询的预热请求以更新缓存。
- 认证、全局标志和安全规则依赖 ../gws-shared/SKILL.md，缺失时需运行 gws generate-skills 生成。