核心用法
gws people 是基于 Google People API v1 的命令行工具，面向开发者与系统管理员提供通讯录管理能力。支持三大资源维度：
- contactGroups：联系人分组的 CRUD 操作，需保证组名唯一性
- otherContacts：管理自动生成的"其他联系人"，支持复制到主通讯录
- people：核心联系人操作，涵盖单条/批量创建、更新、删除、照片管理，以及企业目录（directory）搜索
所有变更操作（mutate）需串行执行，同一用户的并发请求会导致延迟增加或失败。搜索功能需先发送空查询预热缓存。
显著优点
1. 批处理能力：batchCreateContacts/batchUpdateContacts 大幅提升批量导入效率
2. 企业场景覆盖：listDirectoryPeople/searchDirectoryPeople 支持 Google Workspace 域内联系人同步
3. 字段级掩码：通过 personFields 和 update_mask 精确控制读写范围，减少 API 配额消耗
4. 同步令牌机制：支持增量同步（sync_token），适合构建本地缓存与定期同步任务
潜在缺点与局限性
- 并发限制：强制串行执行 mutate 操作，高并发场景需客户端自行实现队列
- 同步令牌过期：otherContacts 的 sync_token 7 天过期，需降级为全量同步
- 字段限制：单例字段（biographies/birthdays/genders/names）在 create 时仅限单值，违反则 400 错误
- 无内置 OAuth 流程：依赖外部
gws认证体系，需预先完成授权配置
适合人群
- 需要自动化通讯录管理的 DevOps/SRE 工程师
- 构建 CRM 数据同步管道的后端开发者
- Google Workspace 管理员进行域内联系人治理
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据误删 | delete/update 操作不可逆，建议先 list/get 确认 |
| 配额耗尽 | people 接口读写配额较严格，批量操作需控制速率 |
| 隐私合规 | 处理企业目录数据时需符合 GDPR/本地数据保护法规 |
| 令牌失效 | 依赖外部 refresh token，需监控认证状态 |
> 版本：v0.22.3 | 依赖：gws CLI 工具链