核心用法
本技能是 Google People API 的代理封装，通过 Maton 平台提供托管 OAuth 认证，让用户无需处理复杂的 Google OAuth 流程即可操作 Google 通讯录。核心能力覆盖三大场景：
1. 联系人全生命周期管理
- 支持单条/批量查询、创建、更新、删除联系人
- 提供
personFields精细字段控制（姓名、邮箱、电话、地址、公司、生日、备注等） - 支持 etag 乐观锁并发控制，防止数据覆盖
2. 联系人群组管理
- 系统内置群组（星标、家人、同事、好友等）与用户自定义群组
- 群组成员批量增删，支持连带删除选项
3. 智能搜索与其他联系人
- 全文搜索联系人姓名、邮箱等信息
- 管理"其他联系人"（邮件往来但未正式添加的联系人），可一键转正
使用时需设置 MATON_API_KEY 环境变量，所有请求通过 https://api.maton.ai/google-contacts/{path} 代理转发，Maton 自动注入 OAuth Token。多账号场景下可通过 Maton-Connection 头部指定具体连接。
显著优点
- 零 OAuth 配置成本：托管认证省去客户端 ID/Secret 管理、Token 刷新、权限范围配置等繁琐步骤
- 完整 API 覆盖：完整映射 Google People API，包括批量操作、分页、搜索等高级功能
- 多语言友好：提供 Python、JavaScript、Bash/curl 等多种代码示例，降低接入门槛
- 多账号支持：同一 Maton 密钥可管理多个 Google 账号的通讯录连接
潜在缺点与局限性
- 供应商锁定：完全依赖 Maton 代理服务，若服务中断或定价调整将直接影响使用
- 网络依赖：所有请求必须经过 Maton 服务器中转，无法离线或直连 Google API
- 搜索延迟：新建联系人存在索引延迟，搜索结果可能不包含最新数据
- 写入需确认：技能文档明确要求写操作前需用户确认，自动化场景下可能增加交互复杂度
- 并发限制：同一用户的变更请求建议串行发送，高并发写入可能触发限流或失败
适合人群
- 需要快速集成 Google 通讯录功能的开发者与自动化工程师
- 无 OAuth 开发经验但希望使用 Google People API 的个人用户
- 管理多个 Google 账号通讯录的运维人员
- 构建 CRM 同步、客户管理、通讯录备份等场景的工具开发者
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据隐私 | 联系人数据流经 Maton 代理服务器，需信任第三方数据处理能力 |
| Token 安全 | MATON_API_KEY 泄露将导致对应 Google 账号的通讯录被完全控制 |
| 误操作风险 | 批量删除、群组连带删除等操作不可逆，需谨慎确认 |
| 服务可用性 | 依赖 Maton 服务稳定性，建议实现本地缓存与降级方案 |
| 合规风险 | 处理欧盟 GDPR、中国个人信息保护法等场景需额外评估 |
建议生产环境启用连接审计日志，定期轮换 API Key，并为敏感操作设置二次确认机制。