核心用法
gws-people 是 Google Workspace CLI 工具集中专用于 People API 的技能模块，封装了联系人全生命周期管理能力。采用 gws people <resource> <method> [flags] 的命令结构，支持三大资源域：
- contactGroups：联系人分组 CRUD 操作，含成员管理子资源
- people：核心联系人操作，包括单条/批量创建更新、照片管理、目录搜索
- otherContacts："其他联系人"管理（自动生成的交互记录联系人）
关键特性包括：批量操作（batchCreateContacts、batchUpdateContacts）、增量同步机制（sync_token 支持 7 天有效期）、企业目录集成（listDirectoryPeople、searchDirectoryPeople），以及预热缓存机制（搜索前需发送空查询 warmup 请求）。
显著优点
1. Google 生态深度集成：原生对接 Gmail、Google Contacts、Workspace Directory，数据一致性有保障
2. 批量效率优化：显式支持批量创建/更新，减少 API 调用次数
3. 企业级目录支持：可访问域内用户档案，适合组织通讯录自动化
4. Schema 自省能力：通过 gws schema 动态获取参数类型与默认值，降低学习成本
潜在局限
- 并发限制：文档多次强调 "Mutate requests... should be sent sequentially"，同一用户的写操作必须串行，高并发场景需自行队列化
- 同步延迟：目录写入后 "propagation delay of several minutes"，不适用于实时读场景
- 字段约束严格：单例字段（如 biographies、birthdays）多值提交直接 400 错误
- Token 过期：sync_token 7 天失效，需降级为全量同步
适合人群
- 需要自动化维护 Google Contacts 的 Workspace 管理员
- 构建 CRM-Contacts 同步管道的开发者
- 需要批量导入/迁移联系人的企业 IT 团队
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据覆盖 | `update_mask` 未谨慎指定时，未包含字段会被清空而非保留 |
| 重复创建 | 分组名称唯一性校验在服务端，本地需预处理去重 |
| 隐私合规 | 企业目录搜索可能暴露内部组织架构，需遵循 GDPR/企业数据政策 |
| 锁竞争 | 并发照片更新可能触发 "lock contention"，导致操作失败 |