核心用法
google-contacts 是一个基于 Maton API 网关的文档型技能，为用户提供完整的 Google People API 接入方案。用户需先在 maton.ai 注册获取 MATON_API_KEY，通过 https://ctrl.maton.ai 完成 Google OAuth 授权建立连接，随后即可调用 RESTful API 执行联系人全生命周期管理：包括列表查询、单条/批量增删改、分组管理以及智能搜索。API 路径完全兼容 Google People API 原生接口，Maton 网关自动注入 OAuth Token，大幅降低集成门槛。
显著优点
托管式 OAuth 体验：无需自行处理复杂的 Google OAuth 2.0 流程，Maton 提供可视化连接管理界面，支持多账号切换与连接状态监控。完整功能覆盖：不仅支持基础 CRUD，还涵盖批量操作（batchCreate/batchDelete）、联系人群组管理、Other Contacts 迁移等高级特性。企业级可靠性：支持 etag 乐观锁并发控制、分页同步令牌（syncToken）、字段级掩码（readMask/updatePersonFields）等 Google API 最佳实践。多语言示例：提供 Python、JavaScript、Bash 等即插即用的代码模板，5 分钟完成接入。
潜在缺点与局限性
外部依赖锁定：核心功能完全依赖 Maton 网关服务（gateway.maton.ai），若服务不可用则技能失效，存在单点故障风险。网络延迟问题：所有请求需经 Maton 中转，相比直连 Google API 增加约 50-100ms 延迟，批量操作时累积明显。功能边界限制：作为代理网关，Google API 的新特性可能存在支持滞后；部分高级功能如照片上传、关系网络分析未在文档中体现。数据隐私顾虑：联系人数据流经第三方 Maton 服务器，对高敏感场景需评估合规风险。
适合的目标群体
快速原型开发者：需要在短时间内集成 Google 通讯录的 MVP 项目团队。无 OAuth 经验的工程师：希望跳过繁琐的 Google Cloud Console 配置和令牌刷新逻辑。多账号管理场景：需要同时操作多个 Google 账号联系人的企业自动化工具。低代码/自动化平台：作为后端 API 供 n8n、Make 等工具调用，构建客户数据同步工作流。
使用风险
密钥泄露风险：MATON_API_KEY 作为唯一凭证，若硬编码或日志泄露将导致账号被滥用，建议配合密钥管理服务。速率限制：Google People API 默认配额 90 请求/用户/秒，Maton 网关可能叠加额外限制，大规模同步需实现指数退避重试。OAuth 令牌过期：长期运行的自动化任务需监控连接状态，通过 ctrl.maton.ai 及时刷新或重建连接。数据一致性：并发修改同一联系人时依赖 etag 机制，客户端需正确处理 409 冲突响应。