google-contacts

Google Contacts

适用于 Agent 调用的 Google Contacts 工具，封装了 Google People API。创建、读取、更新和删除联系人的联系人信息；按姓名、电子邮件或电话号码搜索联系人；设置或移除联系人照片；创建和管理联系人群组（标签）及其成员；并浏览自动保存的“其他联系人”页面。所有工具都使用单个 OAuth 连接；可用功能取决于已授予的作用域。

独立的非官方 Google Contacts 连接器。与 Google Contacts 无关联，也未获其认可或赞助。“Google Contacts”是其所有者的商标，此处仅用于标识此连接器所适配的服务。

适用场景

• 保存、查找、更新或删除某人的 Google Contacts 联系人（“把 Jane 添加到我的联系人”“Bob 的电子邮件是什么”“移除此联系人”）。
• 将联系人整理到群组/标签中，并添加或移除成员。
• 设置或移除联系人的照片。
• 查找用户曾有过互动（例如发过电子邮件）但从未明确保存的人——即“其他联系人”页面——并将其添加为已保存联系人。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先运行 npx skills add zapier/connectors --skill google-contacts 安装（或使用你所用运行环境自己的技能安装机制），然后继续操作。安装技能会复制这些文件，而非依赖项。在运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。如果要在自己的项目中将已发布的包作为依赖项导入？该 npm install 已会解析所有内容——请参阅 references/use-as-sdk.md。

想查看实际的仓库源码——浏览 references/、运行此连接器的测试或修改代码？请参阅 README.md，了解如何克隆指定范围的仓库。

此连接器运行于 Node.js 22.18+。选择与你的运行方式匹配的参考文档，并在进行任何其他操作之前先加载：

你拥有……	加载
支持 MCP 的客户端——工具可能已加载（例如 mcp__google-contacts__<tool>），也可以自行注册本地服务（或指导用户完成注册）	references/use-as-mcp.md
终端 / 子进程访问权限（可以运行 node）	references/use-as-cli.md
仅有自己的代码，并将此包作为依赖项导入	references/use-as-sdk.md
无工具访问权限、无终端、无法导入此包——你要编写自己的代码，直接调用 Google Contacts API（例如在代码执行沙箱中）	references/use-as-recipe.md

脚本

所有脚本均使用单个 google-contacts 连接。

脚本	脚本名称	连接	描述
scripts/createContact.ts	createContact	google-contacts	根据结构化的姓名、电子邮件、电话、地址和组织字段创建联系人。
scripts/getContact.ts	getContact	google-contacts	按资源名称检索单个联系人，并获取完整的字段详情。
scripts/updateContact.ts	updateContact	google-contacts	更新联系人；发送的每个数组都会替换整个字段，未提供的字段保持不变。
scripts/deleteContact.ts	deleteContact	google-contacts	从账号中删除联系人。
scripts/listContacts.ts	listContacts	google-contacts	分页列出账号中的联系人——主要的 resourceName 解析器。
scripts/searchContacts.ts	searchContacts	google-contacts	按姓名、昵称、电子邮件、电话或组织搜索联系人（前缀匹配）。
scripts/updateContactPhoto.ts	updateContactPhoto	google-contacts	根据 Base64 编码的图片设置或替换联系人的照片。
scripts/deleteContactPhoto.ts	deleteContactPhoto	google-contacts	移除联系人的照片，恢复为默认头像。
scripts/listContactGroups.ts	listContactGroups	google-contacts	列出联系人群组（标签），包括用户群组和系统群组——contactGroupResourceName 解析器。
scripts/getContactGroup.ts	getContactGroup	google-contacts	获取单个联系人群组，可选择同时获取其成员的联系人资源名称。
scripts/createContactGroup.ts	createContactGroup	google-contacts	创建新的用户联系人群组（标签）。
scripts/updateContactGroup.ts	updateContactGroup	google-contacts	重命名用户联系人群组（系统群组无法重命名）。
scripts/deleteContactGroup.ts	deleteContactGroup	google-contacts	删除用户联系人群组（标签），可选择同时删除其成员联系人。
scripts/modifyContactGroupMembers.ts	modifyContactGroupMembers	google-contacts	在群组中添加和／或移除联系人，不影响其他群组成员关系。
scripts/listOtherContacts.ts	listOtherContacts	google-contacts	列出自动保存的“其他联系人”（互动过但从未保存的人）。
scripts/searchOtherContacts.ts	searchOtherContacts	google-contacts	按姓名、电子邮件或电话搜索“其他联系人”（前缀匹配）。
scripts/copyOtherContact.ts	copyOtherContact	google-contacts	将“其他联系人”转为已保存联系人，并返回可编辑的联系人。

消歧与拒绝

• 先确定名称，再执行操作。 对以姓名识别的联系人调用 updateContact / deleteContact / modifyContactGroupMembers 之前，先调用 searchContacts（或 listContacts），并统计姓名完全匹配且不区分大小写的结果。只有一个匹配项 → 对其执行操作；不要过度追问。两个或更多匹配项且无法区分 → 停止，列出带有区分字段（邮箱或电话）的候选项，并询问用户要选哪一个，绝不要默默挑选。通过 listContactGroups 处理群组时也适用相同规则。
• 编辑列表字段会替换整个列表。 updateContact 会整体替换你发送的每个数组（例如 emailAddresses）。要在不丢弃其他值的情况下_添加_一个值，先调用 getContact，再追加，然后发送完整数组。对于群组成员关系，优先使用 modifyContactGroupMembers（按元素操作），而不是 updateContact。
• 超出支持范围——拒绝，不要替代处理。 此连接器不支持批量创建、更新或删除联系人、查询 Google Workspace 目录，也不支持联系人合并或去重。如果用户提出其中任何一项，说明不支持并停止——不要调用其他工具并声称已完成。
• 不支持批量操作——绝不要通过循环来伪装。 没有批处理端点。如果用户要求一次性更改、添加或删除许多或所有联系人的某个字段（例如“将所有人的公司都设为 Acme”），请拒绝并说明不支持——不要对多个联系人循环调用 updateContact / deleteContact / modifyContactGroupMembers 来模拟批量操作。对单个、明确指定的联系人执行操作没有问题；但不要对整个通讯录批量操作。

身份验证

每种形态都会将身份验证信息作为一个连接选择器传入，而不是密钥——格式为 [<resolver>:]<value> 字符串。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请查看此连接器自己的解析器，不要想当然。<resolver>: 前缀是可选的；不带前缀的值会交给第一个能识别它的解析器——符合 UUID 格式的不带前缀值始终会被 zapier: 识别。每个脚本都会声明所需的连接及其接受的解析器。传入连接的确切语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考文档。

想先检查已配置的内容？不要通过转储环境变量值来检查——env 或 env | grep <name> 会连同名称一起打印值，如果其中设置了有效凭据，就会将其泄露到记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式——并按照参考文档自身的流程获取连接；不要直接向用户索要连接 ID 或令牌，仿佛用户早已记住它们：

	加载
直接传入凭据	references/use-without-zapier.md
通过 Zapier 连接转发凭据	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 封套：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何查看脚本确切的形状，请参阅上文加载的参考文档）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剥离：它们是脚本从 API 返回、但 outputSchema 未声明的字段。如果需要这些字段，请重新运行并跳过输出验证。
  • { skipped: true } — 已绕过验证；data 是未经检查的原始脚本输出。

读取被剥离的字段／skipOutputDataValidation。 要获取未经验证的原始结果，请选择跳过输出验证（确切语法因形状而异；请参阅上文加载的参考文档）。

精简结果／filterOutputData。 要将大型结果缩减为所需字段，请传入一个 jq 表达式，对 data 进行后处理（确切语法同样因形状而异）。jq 仅针对 data 运行，而非 { data, meta } 封套，因此表达式应以 data 为根（运行脚本的 --help，或形状对应的命令，以查看其输出架构）。转换后的值会替换 data，meta 保持不变，且结果不会根据输出架构重新验证。

参考文档

在相关领域工作前，先加载匹配的参考文件：

参考文档	涵盖内容	何时加载
references/google-contacts-api-gotchas.md	错误代码、更新替换语义、etag 并发控制、搜索前缀匹配与预热、写入传播延迟、资源名称格式、联系人组类型、成员资格限制、其他联系人字段限制以及分页。	调用任何工具前。