使用 gws CLI 管理 Google People…

在已安装并认证 gws CLI 后，通过 Google People API 操作联系人组、其他联系人、联系人及域目录资料。

适用场景

解决思路

1. 先阅读 ../gws-shared/SKILL.md，获取认证、全局标志和安全规则；如果该文件缺失，运行 gws generate-skills 生成。
2. 使用命令格式：gws people <resource> <method> [flags]。
3. 调用任何 API 方法前先检查：运行 gws people --help 浏览资源和对应方法。
4. 运行 gws schema people.<resource>.<method> 查看方法的必需参数、类型和默认值。
5. 根据 gws schema 输出构建 --params 和 --json 标志。
6. contactGroups.batchGet：按一组 contact group resource name 获取已认证用户拥有的联系人组列表。
7. contactGroups.create：创建已认证用户拥有的新联系人组；联系人组名称必须在用户联系人组中唯一，尝试创建重复名称会返回 HTTP 409；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
8. contactGroups.delete：按 contact group resource name 删除已认证用户拥有的现有联系人组；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
9. contactGroups.get：按 contact group resource name 获取已认证用户拥有的指定联系人组。
10. contactGroups.list：列出已认证用户拥有的所有联系人组；不会填充联系人组成员。
11. contactGroups.update：更新已认证用户拥有的现有联系人组名称；更新后的联系人组名称必须唯一，尝试创建重复名称会返回 HTTP 409；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
12. contactGroups.members：操作 members 资源。
13. otherContacts.copyOtherContactToMyContactsGroup：将“Other contact”复制为用户“myContacts”组中的新联系人；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
14. otherContacts.list：列出所有“Other contacts”，即不在联系人组中的联系人，通常是来自交互的自动创建联系人；完整同步后 sync token 7 天过期；使用过期 sync token 的请求会返回带 google.rpc.ErrorInfo 且 reason 为 EXPIRED_SYNC_TOKEN 的错误；遇到此错误时应移除 sync_token 并进行完整同步。
15. otherContacts.search：在已认证用户的 other contacts 中搜索匹配 query 的联系人；query 匹配 OTHER_CONTACT 来源的 names、emailAddresses 和 phoneNumbers 字段；重要：搜索前应先用空 query 发送 warmup request 更新缓存；参考 https://developers.google.com/people/v1/other-contacts#search_the_users_other_contacts。
16. people.batchCreateContacts：批量创建新联系人并返回新联系人的 PersonResponses；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
17. people.batchUpdateContacts：批量更新联系人并返回 resource name 到更新后联系人 PersonResponses 的映射；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
18. people.createContact：创建新联系人并返回该联系人的 person resource；如果在联系人来源的单例字段（biographies、birthdays、genders、names）上指定多个字段，请求返回 400；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
19. people.deleteContactPhoto：删除联系人照片；对同一用户的 mutate 请求应顺序执行，以避免锁争用。
20. people.get：通过 resource name 获取指定 person 信息；使用 people/me 表示已认证用户；如果未指定 personFields，请求返回 400。
21. people.getBatchGet：通过指定一组 resource name 获取多个指定 people 的信息；使用 people/me 表示已认证用户；如果未指定 personFields，请求返回 400。
22. people.listDirectoryPeople：列出已认证用户域目录中的域资料和域联系人；指定 sync_token 时，自上次同步以来删除的资源会作为 PersonMetadata.deleted 为 true 的 person 返回；指定 page_token 或 sync_token 时，所有其他请求参数必须与第一次调用匹配；同步请求的写入可能有几分钟传播延迟；增量同步不适用于 read-after-write 场景。
23. people.searchContacts：在已认证用户的分组联系人中搜索匹配 query 的联系人；query 匹配 CONTACT 来源的 names、nickNames、emailAddresses、phoneNumbers 和 organizations 字段；重要：搜索前应先用空 query 发送 warmup request 更新缓存；参考 https://developers.google.com/people/v1/contacts#search_the_users_contacts。
24. people.searchDirectoryPeople：在已认证用户的域目录中搜索匹配 query 的域资料和域联系人。
25. people.updateContact：更新现有联系人 person 的联系人数据；任何非联系人数据不会被修改；要更新 person 中的非联系人数据会被忽略；update_mask 中指定的所有字段都会被替换；如果未为要更新的联系人指定 person.metadata.sources 或联系人没有 contact source，服务器返回 400。
26. people.updateContactPhoto：更新联系人照片；对同一用户的 mutate 请求应顺序发送，避免增加延迟和失败。
27. people.connections：操作 connections 资源。

适用边界 · 注意事项

• 未安装 gws CLI 或未按 gws-shared/SKILL.md 完成认证、全局标志和安全规则配置时，不要使用。
• 需要管理的不是 Google People（如本地通讯录、微信/钉钉/企业微信联系人、非 Google 域目录）时，不适用。
• 需要 read-after-write 一致性的增量同步时，不要依赖 people.listDirectoryPeople 的增量同步。