google-sheets

Google Sheets

用于通过 Google Sheets API v4（https://sheets.googleapis.com/v4/）处理 Google Sheets，并通过 Google Drive API 查找电子表格。共提供 26 个工具，分为两种互补的操作方式：记录操作——将行作为以列标题为键的对象（适用于“记录这笔支出”“将状态更新为 Done”“查询上季度总额”等任务）；以及单元格操作——使用原始 A1 地址值处理公式、精确控制数字和文本，以及任意范围。此外，还支持电子表格和工作表的结构与呈现设置（格式、排序、验证）。

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

适用场景

• 读取或查找电子表格中的数据 — 按列值查找一行（lookupRow）、查找所有匹配行（findRows）、列出一段行（listRows），或读取原始范围（getValues）。
• 写入数据 — 追加一行或多行（createRow / createRows）、更新某行的特定列而不影响其他列（updateRow / updateRows），或写入原始范围 / 公式（updateValues）。
• 清除或删除 — 清除行内容但保留该行（clearRows / clearValues），或彻底删除行（deleteRows）。
• 管理结构 — 创建电子表格（createSpreadsheet），添加 / 列出 / 复制 / 重命名 / 隐藏 / 删除工作表，添加列。
• 设置格式与验证 — 数字 / 日期 / 货币格式、文本样式、对范围排序、复制范围、下拉列表以及数字 / 日期验证、条件格式。

设置

这是一个 agentskills.io 技能。

如果尚未将此连接器安装为技能，请先运行 npx skills add zapier/connectors --skill google-sheets 安装（或使用你的运行环境自身的技能安装机制），然后继续。安装技能会复制这些文件，而不是依赖项。运行 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-sheets__<tool>），或者你可以自行注册本地服务（或指导用户注册）	references/use-as-mcp.md
终端／子进程访问权限（可以运行 node）	references/use-as-cli.md
只有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法访问工具、终端，也无法导入此软件包——你需要编写自己的代码，直接调用 Google Sheets API（例如在代码执行沙盒中）	references/use-as-recipe.md

脚本

所有脚本都使用唯一的 google-sheets 连接。

脚本	脚本名称	连接	描述
scripts/createSpreadsheet.ts	createSpreadsheet	google-sheets	创建新的电子表格，可选择添加工作表和标题行。
scripts/getSpreadsheet.ts	getSpreadsheet	google-sheets	获取电子表格的元数据及其工作表列表。
scripts/listSpreadsheets.ts	listSpreadsheets	google-sheets	按名称在 Drive 中查找电子表格（需要 Drive 访问权限；否则请传入 URL/ID）。
scripts/addWorksheet.ts	addWorksheet	google-sheets	添加工作表（标签页），可选择添加标题行。
scripts/listWorksheets.ts	listWorksheets	google-sheets	列出电子表格中的工作表（标签页）。
scripts/copyWorksheet.ts	copyWorksheet	google-sheets	将工作表复制到另一个电子表格（或同一个电子表格）中。
scripts/updateWorksheetProperties.ts	updateWorksheetProperties	google-sheets	重命名、移动、冻结行/列、隐藏工作表或更改其颜色。
scripts/deleteWorksheet.ts	deleteWorksheet	google-sheets	永久删除工作表及其数据。
scripts/addColumn.ts	addColumn	google-sheets	插入列，可选择设置标题标签。
scripts/createRow.ts	createRow	google-sheets	根据列标题对应的值追加单行。
scripts/createRows.ts	createRows	google-sheets	通过一次批量调用追加多行。
scripts/updateRow.ts	updateRow	google-sheets	按行号更新某一行中的指定列（其他列保持不变）。
scripts/updateRows.ts	updateRows	google-sheets	通过一次批量调用更新多行（每行按行号指定）。
scripts/lookupRow.ts	lookupRow	google-sheets	查找第一个列值与指定值匹配的行。
scripts/findRows.ts	findRows	google-sheets	按列/值筛选条件查找所有匹配的行（有范围限制）。
scripts/listRows.ts	listRows	google-sheets	将一段行范围读取为记录。
scripts/clearRows.ts	clearRows	google-sheets	清除指定行的内容（保留行；其他内容不会移动）。
scripts/deleteRows.ts	deleteRows	google-sheets	删除指定行；其下方的所有内容都会上移。
scripts/getValues.ts	getValues	google-sheets	以 A1 表示法读取原始单元格范围。
scripts/updateValues.ts	updateValues	google-sheets	向原始单元格范围写入值（RAW 或 USER_ENTERED）。
scripts/clearValues.ts	clearValues	google-sheets	清除原始单元格范围中的值（保留格式）。
scripts/formatCells.ts	formatCells	google-sheets	对范围应用数字/日期/货币格式或文本样式。
scripts/sortRange.ts	sortRange	google-sheets	按一列或多列对范围排序。
scripts/copyRange.ts	copyRange	google-sheets	将范围（值 + 格式）复制到其他位置。
scripts/setDataValidation.ts	setDataValidation	google-sheets	为范围设置下拉列表/数字/日期验证规则。
scripts/addConditionalFormatRule.ts	addConditionalFormatRule	google-sheets	为范围添加条件格式规则。

消歧与拒绝

写入前先消歧。 在通过列值找到某行后写入（例如，更新通过 lookupRow 找到的行，或操作通过 listSpreadsheets 找到的电子表格）之前，请统计大小写不敏感的精确匹配项：

• 恰好匹配一项 — 对其执行操作。不要过度追问；只有一个明确匹配项时，答案就是它。
• 有两项或更多并列匹配 — 停止操作。列出并列的行（或电子表格），并附上可用于区分的字段（另一列的值、电子表格的修改时间 / URL），然后询问用户要选哪一项。不要擅自选择，也不要对所有匹配项写入。

行号并不稳定 — 插入 / 删除 / 排序时，行号会变化。若要在多次运行中定位同一条逻辑记录，请使用 lookupRow 按唯一键列匹配，而不要依赖记住的行号。

执行破坏性操作或批量覆盖操作前先确认。 deleteWorksheet、deleteRows、clearRows 和 clearValues 会删除数据；updateValues 可能会覆盖数据。先与用户确认确切目标，且删除 / 清除 / 覆盖的范围绝不能超过用户的要求。

不支持的操作 — 明确告知并停止；不要假装用其他工具实现。 此目录有意不支持：

• 创建或管理图表、数据透视表、命名范围、受保护范围或筛选器。 没有相应工具；不要尝试用格式设置来替代。
• 一步完成查找或创建。 组合操作：lookupRow → 如果未找到，则执行 createRow。
• 永久删除整个电子表格。 删除工作表（deleteWorksheet）是唯一支持的结构性删除操作。

如果用户要求执行上述任何操作，请告知用户不支持，并停止。

身份验证

每种形态都会将一个连接选择器（而非密钥）传递给身份验证：[<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。 如需将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（具体语法同样因形状而异）。jq 只针对 data 运行，不针对 { data, meta } 信封，因此表达式应以 data 为根（运行脚本的 --help——或形状的等效命令——即可查看输出架构）。转换后的值会替换 data，meta 保持不变，结果不会再次根据输出架构进行验证。

参考资料

在对应领域开展工作前，请加载匹配的参考文件：

参考资料	涵盖内容	加载时机
references/google-sheets-api-gotchas.md	错误恢复、速率限制重试、batchUpdate 原子性、行删除和追加逻辑、400/403/404/429 错误	进行任何可能失败的调用之前——包括错误恢复、速率限制重试、batchUpdate 原子性、行删除或追加逻辑，或遇到 400/403/404/429 错误时
references/google-sheets-a1-and-values.md	RAW 与 USER_ENTERED、序列号日期、不规则行、带工作表名称引号的 A1 范围	读取或写入单元格值之前——尤其是在选择 RAW 或 USER_ENTERED、解读序列号日期、处理不规则行，或构造带工作表名称引号的 A1 范围时