google-docs

Google Docs

用于通过 Google Docs API v1（https://docs.googleapis.com/v1/）处理文档内容，以及通过 Google Drive API v3（https://www.googleapis.com/drive/v3/）执行 Docs API 不支持的查找、导出、复制模板和文件夹操作。共 22 个工具：创建文档（空白文档、根据文本/Markdown 创建，或使用模板创建）、读取文档的结构化内容和标签页、将文档导出为文本/Markdown、按名称查找文档，以及编辑内容——追加/插入/查找并替换/删除文本、定位文本位置、设置字符和段落格式、创建项目符号列表/编号列表、插入和编辑表格、创建页眉/页脚/脚注、插入和替换内嵌图片，以及设置页面/边距/背景样式。

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

适用场景

• Agent 需要创建文档——创建空白文档、根据初始文本或 Markdown 创建文档，或填充 {{placeholder}} 模板，还可选择指定 Drive 文件夹。
• Agent 需要读取文档——读取其结构化内容和编辑索引（getDocument）、获取清理后的文本/Markdown（exportDocument），或按名称查找文档（findDocuments）并定位文本（findText）。
• Agent 需要编辑文本——追加文本、在指定位置插入文本、查找并替换，或删除一段内容。
• Agent 需要设置格式或重新排版——设置字符格式；创建项目符号列表或编号列表（createList）；设置段落样式——标题、对齐方式、行距、缩进（formatParagraph）；插入/替换内嵌图片；或设置页面大小/边距/背景。
• Agent 需要调整文档结构——插入表格并填充单元格（insertTable）、添加/删除表格行或列（modifyTable）、创建页眉或页脚并设置其文本（createHeader / createFooter），并将返回的 segmentId 传给 formatText 来设置其格式；或添加脚注（createFootnote），并通过将返回的 segmentId 作为目标传给 insertText 来填写脚注正文。

设置

这是一个 agentskills.io 技能。

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

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

此连接器需要 Node.js 22.18+。选择与你的运行方式相符的参考文档，并在进行任何操作前先阅读：

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

脚本

所有脚本都使用唯一的 google-docs 连接（一份 OAuth 凭据即可授权访问 Docs 和 Drive 主机）。

脚本	脚本名称	连接	描述
scripts/createDocument.ts	createDocument	google-docs	创建新文档，可选择添加初始文本/Markdown 并将文档放入文件夹。
scripts/createDocumentFromTemplate.ts	createDocumentFromTemplate	google-docs	复制模板文档并填入其中的 {{placeholder}} 标记。
scripts/getDocument.ts	getDocument	google-docs	读取文档的结构化内容、标签页和编辑索引。
scripts/exportDocument.ts	exportDocument	google-docs	将文档导出为纯文本或 Markdown。
scripts/findDocuments.ts	findDocuments	google-docs	按名称和/或文件夹查找 Google Docs 文档。
scripts/appendText.ts	appendText	google-docs	在文档末尾追加文本（可选 Markdown）。
scripts/insertText.ts	insertText	google-docs	在特定索引处插入文本。
scripts/replaceAllText.ts	replaceAllText	google-docs	查找并替换字符串的所有匹配项。
scripts/findText.ts	findText	google-docs	查找短语的匹配项并返回其索引范围。
scripts/deleteContentRange.ts	deleteContentRange	google-docs	删除索引范围内的内容。
scripts/formatText.ts	formatText	google-docs	对索引范围应用字符格式。
scripts/formatParagraph.ts	formatParagraph	google-docs	为范围设置段落样式（标题、对齐方式、间距、缩进）。
scripts/createList.ts	createList	google-docs	将范围设为项目符号列表或编号列表，或在两者之间转换。
scripts/removeListFormatting.ts	removeListFormatting	google-docs	移除范围内的项目符号/编号，保留文本。
scripts/insertImage.ts	insertImage	google-docs	从公开 URL 插入内嵌图片。
scripts/replaceImage.ts	replaceImage	google-docs	替换现有的内嵌图片。
scripts/updateDocumentStyle.ts	updateDocumentStyle	google-docs	设置页面大小、页边距或背景颜色。
scripts/insertTable.ts	insertTable	google-docs	插入 rows×columns 表格，可选择预填单元格内容。
scripts/modifyTable.ts	modifyTable	google-docs	在参考单元格处添加或删除表格行或列。
scripts/createHeader.ts	createHeader	google-docs	创建带有文本的默认页眉；返回用于通过 formatText 设置样式的 segmentId。
scripts/createFooter.ts	createFooter	google-docs	创建带有文本的默认页脚；返回用于通过 formatText 设置样式的 segmentId。
scripts/createFootnote.ts	createFootnote	google-docs	插入脚注引用；返回用于 insertText 的 segmentId。

消歧与拒绝

写入前先消歧。 在编辑通过名称使用 findDocuments 查找的文档前，统计大小写不敏感的精确标题匹配项：

• 恰好一个匹配项 — 对其执行操作。不要过度追问；只有一个明确匹配项时，直接使用它。
• 两个或更多匹配项并列 — 停止操作。列出并列候选项及一个用于区分的字段（modifiedTime 或 url），询问用户指的是哪一个。不要随意选择，也不要全部编辑。

这同样适用于索引位置：getDocument / findText 返回的索引在任何编辑后都会失效。再次进行基于索引的调用前，请重新读取，而不要在编辑后重复使用位置。

不支持的操作——说明不支持并停止；不要使用其他工具伪装完成。 此目录有意不支持以下操作：

• 上传二进制文件并转换为 Doc，或往返转换粘贴的 HTML。 二进制文件上传请使用 Drive 连接器；请在此处直接编写内容。
• 管理评论或接受／拒绝建议。 getDocument 可以通过 suggestionsViewMode 读取建议的编辑内容，但没有用于写入评论或建议的工具。
• 将 PDF、DOCX 或 HTML 导出为内联内容。 exportDocument 仅返回纯文本或 Markdown；PDF、DOCX 和 HTML 需要使用 Drive 下载链接（Drive 仅提供打包为压缩 Web Page 的 HTML，不提供内联 text/html）。

如果用户要求执行上述任一操作，请告知用户不支持并停止——不要尝试使用无关工具来近似完成。

身份验证

每种调用形式都将身份验证信息作为一个连接选择器传递，而不是密钥——格式为 [<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-docs-api-gotchas.md	UTF-16 索引、索引 0 处的分节符、编辑后的过时索引、无法删除的末尾换行符、includeTabsContent、按标签页定位的默认行为、由 Drive 支持的查找/导出/文件夹放置、图像获取与大小限制，以及 PT/RGB 单位。	在进行任何基于索引的编辑（插入/格式设置/删除）、查找并替换、插入图像、导出文档或放置到文件夹之前。
references/google-docs-batchupdate.md	降序规则、预置表格的两阶段填充、通过前导制表符实现列表嵌套、第二种段落索引空间（空页眉/页脚的结束索引为 1 → 创建时的文本）、删除最后一行会删除表格，以及受支持的 Markdown 子集。	在编写结构内容前加载——列表（createList/removeListFormatting）、表格（insertTable/modifyTable）、页眉/页脚/脚注（createHeader/createFooter/createFootnote），或使用 markdown: true 写入路径时。