核心用法
gws-people 是 Google People API 的 CLI 封装工具，提供完整的联系人生命周期管理能力。采用 gws people <resource> <method> 的命令结构，支持三大资源维度：
contactGroups — 联系人分组管理，涵盖创建、更新、删除、批量获取及成员操作。需注意组名唯一性约束，重复名将返回 HTTP 409 错误。
otherContacts — 处理自动生成的"其他联系人"（通常来自邮件往来），支持复制到主联系人、列表查询及搜索。搜索前需发送空查询预热请求以更新缓存。
people — 核心联系人操作，包括单条/批量创建更新、照片增删、企业目录检索等。searchContacts 和 searchDirectoryPeople 分别针对个人通讯录和 Workspace 域目录，支持多字段模糊匹配。
关键约束：同一用户的变更请求必须串行执行，避免延迟增加和失败；同步令牌 7 天过期，需全量重同步。
显著优点
- 企业级覆盖：完整对接 People API v1，支持个人 + 域目录双场景
- 批量效率：
batchCreateContacts/batchUpdateContacts支持批量操作，适合数据迁移 - Schema 驱动：
gws schema命令自动生成参数模板，降低 API 学习成本 - 权限粒度细：依托 Google OAuth，可精确控制通讯录读写范围
潜在局限
- 串行瓶颈：强制顺序执行 mutate 操作，高并发场景受限
- 缓存预热：搜索功能需前置空查询，增加交互复杂度
- 同步延迟：域目录写入后需数分钟传播，不适用于实时读写
- 单例字段限制：biographies、birthdays 等字段仅允许单值，多值提交触发 400 错误
适合人群
- Workspace 管理员批量维护企业通讯录
- 开发者构建联系人同步/备份自动化流水线
- 需要将"其他联系人"整理进标准分组的效率用户
常规风险
- 数据覆盖：
update_mask未谨慎配置可能导致非预期字段替换 - 409 冲突：并发创建同名分组触发冲突，需客户端实现重试/命名空间隔离
- 照片操作竞态：
deleteContactPhoto/updateContactPhoto明确警告锁竞争风险 - OAuth 令牌泄露：CLI 工具通常存储令牌于本地，共享环境需配置隔离