用途
Google Contacts 用于搜索、查看、创建、更新和删除用户的 Google 通讯录联系人。所有操作都通过 hatch_gws_cli people <resource> <method> 执行，资源与方法作为两个独立单词，参数放在 --params JSON 对象中；创建和编辑时另用 --json 传入请求体。
主要能力
- 查找联系人：按姓名或邮箱搜索，或浏览整个通讯录，或获取某个人的完整详情。
- 添加联系人：至少提供姓名即可，用户提供邮箱和电话时一并加入。
- 编辑联系人：更新指定字段，需带上要保留的字段以免丢失。
- 删除联系人：按 resourceName 删除。
使用方式
连接
联系人功能需要一次性连接后命令才会返回数据。运行 hatch_gws_cli people status。若未连接，将返回的 connect_url 以 Connect Google Contacts 形式发出，等待用户点击。不要自行编造 URL、引导用户去设置或索要凭据。
断开连接运行 hatch_gws_cli people disconnect，并将其 disconnect_url 以 Disconnect Google Contacts 形式发出。
若命令报告认证失败或未连接，重新运行 status 并按其返回的链接操作。若 status 不可用，说明此设备上 Google Contacts 不可用并停止。认证流程仅通过 status 和 disconnect 进行，不要手写凭据文件或使用原始 gws auth。
常见流程
查找联系人：
- 按姓名或邮箱查找：
people people searchContacts --params '{"query":"alice","readMask":"names,emailAddresses,phoneNumbers","pageSize":10}' - 浏览整个通讯录：
people people connections list --params '{"resourceName":"people/me","personFields":"names,emailAddresses,phoneNumbers","pageSize":50}' - 获取某人完整详情（需已有 resourceName）：
people people get --params '{"resourceName":"people/<id>","personFields":"names,emailAddresses,phoneNumbers"}'
添加联系人：
people people createContact --json '{"names":[{"givenName":"Alice","familyName":"Smith"}],"emailAddresses":[{"value":"alice@example.com"}],"phoneNumbers":[{"value":"+15551234567"}]}'
编辑联系人：
people people updateContact --params '{"resourceName":"people/<id>","updatePersonFields":"emailAddresses"}' --json '{"etag":"<etag>","emailAddresses":[<the full list with your change>]}'
删除联系人：
people people deleteContact --params '{"resourceName":"people/<id>"}'
查看某命令的旗标可运行 hatch_gws_cli people <resource> <method> --help；查看某方法的 --params/--json 结构可运行 hatch_gws_cli schema people.people.searchContacts（以此类推）。
规则
- 联系人的 id 是不透明的 resourceName，形如 people/c1234567890，people/me 表示已连接账户本身。读取必须指明所需字段：搜索用 readMask，get/connections list 用 personFields 掩码（均为逗号分隔列表，如 names,emailAddresses,phoneNumbers）。切勿编造 resourceName，应把读取返回的值直接用于编辑或删除。
- 创建、编辑和删除联系人可在用户请求清晰明确时直接进行，无需额外确认。编辑或删除前须先解析出确切的人。
- 编辑或删除前先读取：通过搜索或浏览解析出该人，使用读取返回的确切 resourceName（和 etag），绝不对未找到的联系人执行操作。编辑时须包含要保留的字段，以免更新时丢失。
- 仅用平实语言与用户交流。命令及其 JSON 输出仅供内部使用，不要出现在回复中——不出现命令或旗标（hatch_gws_cli、--params）、不出现状态词（not_connected、unavailable）、不出现 resourceName、不出现 API 字段（etag、分页令牌）或原始 JSON。联系人自身的姓名、邮箱和电话是用户所需内容，应保留在回复中。
- 绝不打印令牌、密钥或凭据材料。若出现在工具输出中，应予以遮蔽。
- 当 Google 提供来源更新时间时，读取结果会附加 contact_source_updated_at，包含 UTC 和用户本地两种形式。生日仍为日历日期。
适用场景
适用于需要查询、整理或维护 Google 通讯录联系人的日常任务，例如查找某人的联系方式、新增联系人、修改邮箱或电话、删除不再需要的联系人。
限制
联系人分组与标签、"其他联系人"（从邮件自动保存的地址，而非完整联系人）以及目录或域内人员在此并非一等流程。若任务涉及这些，可用 hatch_gws_cli schema people.<resource>.<method> 查看其结构并在变更前确认，但没有预置且经过测试的配方。