首页
/ AutoGPT 平台 Google Docs Blocks 使用指南:用 LLM 与工作流自动创建、编辑与分享 Google 文档

AutoGPT 平台 Google Docs Blocks 使用指南:用 LLM 与工作流自动创建、编辑与分享 Google 文档

2026-09-06 19:26:50作者:仰钰奇

AutoGPT 平台(autogpt_platform)在 Blocks 体系中内置了一整套面向 Google Docs 的文档操作节点,覆盖创建、读取、定位、插入、删除、格式化、导出与分享等 19 个能力。本篇以 Google Docs 集成文档 为骨架,结合其在 docs.py 中的真实实现展开,帮助你理解每个块的输入输出契约、底层 API 调用与索引规则,并学会用这些块把"LLM 生成的 Markdown 自动排版成 Google 文档"这一场景真正跑起来。

适用前提:Google OAuth 集成与块注册机制

在动手编排工作流之前,先了解这套块的使能条件。所有 Google Docs 块都定义在 docs.py 中,统一挂在 BlockCategory.DATA 数据分类下,并且共享一个总开关:

GOOGLE_DOCS_DISABLED = not GOOGLE_OAUTH_IS_CONFIGURED

GOOGLE_OAUTH_IS_CONFIGURED_auth.py 计算,仅当后端配置里同时存在 secrets.google_client_idsecrets.google_client_secret(见 settings.pySecrets 模型)时才为真。也就是说:只要平台没配好 Google OAuth Client,全部 19 个文档块都会被标记为 disabled,不会出现在可用的块列表里。Google 作为 Provider 的元数据注册(OAuth2 认证类型)在 _config.py 中声明,每个块运行前由块框架注入 GoogleCredentials(类型即 OAuth2Credentials)。

运行时,块的 run() 内部通过 _build_docs_service_build_drive_service 基于注入的凭据构造 Google Docs v1 / Drive v3 服务对象,再调用官方 API。因此在编辑器里为每个块单独配置一次 Google 账号授权即可,无需任何 API Key。

平台级 OAuth 集成与授权流程可进一步参考 docs/platform/integrating/oauth-guide.mddocs/platform/contributing/oauth-integration-flow.md

文档选型:GoogleDriveFile 输入与"绝不硬编码 file ID"约定

除 Create 之外,其余所有块都有一个 document 输入。文档明确提醒:不要input_default 中硬编码 file ID(包括从用户在聊天里粘贴的 Drive URL 中解析出来的 ID),运行时应该由 AgentGoogleDriveFileInputBlock 配合匹配的 allowed_views 喂入文档。

其底层原因见 _drive.py

  • GoogleDriveFileL44-L61)带有一个隐藏字段 _credentials_id:当块 A 输出一个文件时,它同时把"该文件对应的授权凭据 ID"带到块 B,从而实现凭据在块链上自动传递
  • GoogleDriveFileFieldL64-L166)会生成一个 google-drive-picker 格式的输入框,前端据此渲染"认证 + 文件选择"二合一控件,并把 auto_credentials 配置(provider=google、type=oauth2、scope、kwarg 名)注入 schema。只有经过这个 Picker 选中的文件才会携带 _credentials_id,手填的字符串 ID 无法通过认证,这正是文档反复强调不要硬编码的根本原因。

所有接收文档的块都配置了 allowed_views=["DOCUMENTS"](仅显示 Google Docs 文档),并把 scope 默认为 https://www.googleapis.com/auth/drive.file。注意,_drive.py 中的 AgentGoogleDriveFileInputBlock(位于 blocks/io.py)正是文档提到的、供前端"人工选择文档"的那一类块。

输出统一约定:凡是接收/输出 document 的块,其输出的 document 都经由 _make_document_output 标准化为 mimeType="application/vnd.google-apps.document" 的 GoogleDriveFile,url 形如 https://docs.google.com/document/d/{document_id}/edit,并保留原 _credentials_id——所以任意文档块的 document 输出都可以直接连到下一个文档块的 document 输入,实现链式操作

索引模型:基于位置的精确编辑基础

格式化、删除、定点插入等操作依赖 Google Docs 的"content index"(字符索引)概念,理解这一点是正确使用后文多个块的前提:

  • 索引从 1 开始,位置 0 是保留给 section break(分节符)的,因此 Delete / Format / Replace Range 等块的 start_index 均声明了 ge=1(源码约束,见 docs.py 等处);
  • 插入类块的 index 语义按块区分Insert Plain TextInsert Markdown Atindex 默认 1(文档开头),而 Insert Page BreakInsert Tableindex 默认 0(文档末尾,运行时由 _get_document_end_index 动态解析为真实末尾索引,实现上取正文最后一个元素的 endIndex - 1);
  • 获取精确索引位置的标准姿势是先跑 Get Structure 块(见下文),再拿着返回的 start_index/end_index 去执行删除、替换或格式化;
  • Delete / Format / Replace Range 类块在源码中均校验 start_index < end_index,否则直接产出 error 输出。

Markdown 家族:让 LLM 输出直接变成排版好的 Google 文档

这一组共 5 个块是整套 Google Docs 集成中最贴合 AutoGPT"AI 生成内容"定位的能力。它们在底层复用同一套机制:导入 gravitas_md2gdocs 库的 to_requests(markdown, start_index=...),把 Markdown 一次性翻译成 Google Docs batchUpdate 的请求序列。从源码类注释可以确认其支持的 Markdown 语法覆盖:标题 H1–H6、加粗/斜体/删除线、行内代码与代码块、链接、有序/无序列表、引用块

Google Docs Append Markdown

作用:把带完整格式的 Markdown 追加到文档末尾,专为 LLM/AI 输出设计。实现对应 docs.py:先解析文档末尾索引,若 add_newline=True 且文档非空(end_index > 1)则先插入一个换行,再调用 to_requests 把转换结果一次 batchUpdate 提交。

输入:

输入 说明 类型 必填
document 选择要追加的 Google Doc;运行时由 AgentGoogleDriveFileInputBlock(allowed_views 匹配)喂入,禁止在 input_default 硬编码 file ID Document
markdown 要追加的 Markdown 内容 str
add_newline 在追加内容前插入换行(源码默认 True bool

输出:

输出 说明 类型
result 追加操作结果(源码含 successrequests_count Dict[str, Any]
document 供链式操作使用的文档对象 GoogleDriveFile
error 失败时的错误消息 str

典型用法:AI 报告生成(把 LLM 的分析/摘要排版后追加到既有报告)、内容聚合(多来源内容持续累加进一份滚动文档)、会议纪要(AI 转写排版后的纪要写入共享团队文档)。

Google Docs Insert Markdown At

作用:在指定索引位置插入排版后的 Markdown。与 Append 的区别只在于位置:index=1 即文档开头,其他正数索引可把内容"嵌"进正文任意段落之间。源码逻辑非常薄——直接 to_requests(markdown, start_index=index) 后提交(L2151-L2260)。

输入:

输入 说明 类型 必填
document 选择要插入的 Google Doc(同样禁止硬编码 ID) Document
markdown 要插入的 Markdown 内容 str
index 插入位置(1 = 文档开头,源码默认 1 int

输出:result(含 successrequests_count)、documenterror

典型用法:内容插入(把 AI 生成的章节插入模板指定位置)、文档装配(在标记位置逐个拼装格式化内容块)、动态报告(数据驱动内容写入报告模板特定小节)。

Google Docs Replace All With Markdown

作用:清空整篇文档并用格式化 Markdown 重建内容,适合"完全用 AI 输出重新生成文档"的场景。源码实现(L2029-L2148)分两步:若 _get_document_end_index 大于 1,先 deleteContentRange 删除 [1, doc_end) 全部正文,再 to_requests(markdown, start_index=1) 从头写入。

输入:

输入 说明 类型 必填
document 选择要替换内容的 Google Doc Document
markdown 用于重建文档的 Markdown 内容 str

输出:resultsuccessrequests_count)、documenterror

典型用法:文档再生成(用新 AI 输出整体替换旧内容)、内容刷新(周期性文档在不重建文件的前提下更新正文)、模板重置(清空并重填模板供新一轮使用)。

Google Docs Replace Content With Markdown

作用:查找指定文本(如占位符 token)并将其替换为排版后的 Markdown,是"模板 + LLM"工作流的王牌节点。实现(L2407-L2613)比普通替换复杂:先用 _find_text_positions 递归扫描正文段落与表格单元格内的 textRun,用真实的文档 startIndex/endIndex(而非纯文本偏移)定位所有出现位置;随后逆序处理每个位置,把"删除该区间 + 插入转换后的 Markdown 请求"合并到同一次 batchUpdate,可将 API 调用次数减半。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
find_text 要查找并替换的文本(如 {{PLACEHOLDER}} 或任意文本) str
markdown 替换查找文本的 Markdown 内容 str
match_case 查找时是否区分大小写(源码默认 False bool

输出:result(含 replacements_maderequests_count,无匹配时 replacements_made=0)、documenterror

典型用法:智能模板(把 {{SECTION}} 占位符替换为 AI 生成的排版内容)、动态章节(按上下文用格式化内容填充文档段落)、增强版邮件合并(带格式的内容替换,而非纯文本)。

Google Docs Replace Range With Markdown

作用:按起止索引删除旧区间并用 Markdown 替换,实现"只动指定区段、其余保留"。源码(L2263-L2404)先 deleteContentRange 删除 [start_index, end_index),再在同一 start_indexto_requests 写入新内容。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
markdown 替换进区间的新 Markdown str
start_index 被替换区间起点(必须 >= 1) int
end_index 被替换区间终点 int

输出:result(含 requests_countcharacters_deleted)、documenterror

典型用法:章节更新(替换指定章节但保留其余内容)、定点再生成(对文档特定片段用新 AI 输出重写)、增量更新(周期性报告的识别区段局部刷新)。

纯文本家族:不带格式的原样写入

与 Markdown 块相对,纯文本块不做任何格式解释,文本"给什么写什么",适合日志、原始数据或格式交给后续步骤处理的场景。

Google Docs Append Plain Text

作用:把无格式文本追加到文档末尾。实现(L391-L498)逻辑为:解析文档 end index → 按 add_newline 决定是否加换行前缀 → insertText。返回的 resultcharacters_added

输入:

输入 说明 类型 必填
document 选择要追加的 Google Doc Document
text 要追加的纯文本(无格式处理) str
add_newline 在追加文本前插入换行(源码默认 True bool

输出:resultsuccesscharacters_added)、documenterror

典型用法:活动日志(向文档型日志追加带时间戳条目)、数据采集(先落原始数据/转写文本、稍后再排版)、速记(不在意格式地快速记笔记)。

Google Docs Insert Plain Text

作用:在指定索引位置插入无格式文本。与 Insert Markdown At 对称,实现(L501-L604)直接 insertText,源码里对 index 做了 max(1, index) 下限保护。文本原样写入,不会破坏周边已有格式。

输入:

输入 说明 类型 必填
document 选择要插入的 Google Doc Document
text 要插入的纯文本(无格式处理) str
index 插入位置(1 = 文档开头,源码默认 1 int

输出:resultsuccesscharacters_inserted)、documenterror

典型用法:数据插入(向指定位置写原始数据值)、模板变量填充(在模板标记位写变量值)、顺序内容追加(在滚动文档的指定位置持续追加)。

Google Docs Find Replace Plain Text

作用:全文档查找并替换纯文本,替换内容不带新格式、保留周边格式,大小写匹配可配置。实现(L607-L730)使用 Docs API 的 replaceAllText,并通过响应里的 replies[0].replaceAllText.occurrencesChanged 统计替换次数。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
find_text 要查找的纯文本 str
replace_text 替换用的纯文本(不应用格式) str
match_case 查找时是否区分大小写(源码默认 False bool

输出:result(含 replacements_made)、documenterror

典型用法:模板填充(把 {{NAME}} 这类 token 替换成真实值)、批量更新(跨多文档统一替换公司名/日期等)、纠错(批量修正常见拼写或过时术语)。

创建、读取与分析类块

Google Docs Create

作用:在用户的 Google Drive 中新建一篇 Google Doc,可携带初始正文。实现(L267-L388)与其它块不同:它自身声明了 credentials 输入(scope drive.file),创建流程是先调 Drive files().create(mimeType 为 application/vnd.google-apps.document),若有 initial_content 再在 index 1 处 insertText 写入。注意这是唯一一个同时需要 Drive 与 Docs 两个 service 的块。

输入:

输入 说明 类型 必填
title 新文档标题 str
initial_content 可选的初始文本内容(源码默认空串) str

输出:

输出 说明 类型
document 创建出的文档对象(携带 _credentials_id,可直接用于后续块) GoogleDriveFile
document_id 创建出的文档 ID str
document_url 打开文档的 URL str
error 创建失败时的错误消息 str

典型用法:报告模板(每个报告周期按标准化标题新建文档)、动态文档生成(为客户/项目批量生成个性化文档)、工作流自动化(作为 onboarding / 项目启动流程的一环自动建文档)。

Google Docs Read

作用:抽取文档纯文本内容与标题,不含格式。实现(L177-L264)通过 _extract_text_from_content 递归遍历段落 textRun 与表格单元格拼出全部文本。

输入:

输入 说明 类型 必填
document 选择要读取的 Google Doc Document

输出:

输出 说明 类型
text 文档的纯文本内容 str
title 文档标题 str
document 供链式操作使用的文档对象 GoogleDriveFile
error 读取失败时的错误消息 str

典型用法:内容抽取(取文档文本供处理、分析或喂给 LLM 做摘要)、搜索与索引(抽取全文建立全文检索索引)、内容迁移(读取后转换/迁移到其它系统)。

Google Docs Get Metadata

作用:返回文档的元信息:标题、唯一 ID、当前 revision ID 与访问 URL。实现(L733-L828)读取 documents().get 响应中的 titlerevisionId

输入:

输入 说明 类型 必填
document 选择要查询的 Google Doc Document

输出:

输出 说明 类型
title 文档标题 str
document_id 文档 ID str
revision_id 当前修订版本 ID str
document_url 打开文档的 URL str
document 供链式操作使用的文档对象 GoogleDriveFile
error 失败时的错误消息 str

典型用法:文档盘点(批量收集元数据用于跟踪/编目)、版本监控(通过 revision ID 侦测文档是否被改动)、链接生成(提取文档 URL 用于邮件等渠道分发)。

Google Docs Get Structure

作用:分析文档结构并返回带索引的内容段,是 Format / Delete / Replace Range 等精确编辑动作的"探路器"。实现(L2616-L2896)对正文每个元素:普通段输出 type=paragraph;标题段通过 namedStyleTypeHEADING_1~HEADING_6)映射出 type=heading + level;表格输出 type=table(含行列数);还会识别目录(table_of_contents)。flat 模式(detailed=False)得到扁平段列表;detailed 模式额外输出每段的 paragraphStyle 与表格逐 cell 的层级结构。

输入:

输入 说明 类型 必填
document 选择要分析的 Google Doc Document
detailed 返回完整层级结构而非扁平段列表(源码默认 False bool

输出:

输出 说明 类型
segments 扁平的内容段列表(detailed=False 时),每段含 type/text/start_index/end_index List[Dict[str, Any]]
structure 完整的层级文档结构(detailed=True 时,根为 {"body": [...]} Dict[str, Any]
document 供链式操作使用的文档对象 GoogleDriveFile
error 失败时的错误消息 str

典型用法:位置发现(Insert/Delete 前确认正确索引)、文档分析(理解结构以便抽取或操作)、导航辅助(把章节映射成可定点操作的范围)。

编辑与排版类块

Google Docs Delete Content

作用:按起止索引删除一段内容。实现(L1220-L1329)调用 deleteContentRange,删除后后续内容自动前移补齐。建议先用 Get Structure 拿到正确位置。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
start_index 待删除内容起点(必须 >= 1,索引 0 是分节符) int
end_index 待删除内容终点 int

输出:resultsuccesscharacters_deleted)、documenterror

典型用法:内容清理(移除过时章节或模板占位文本)、结构重组(重组工作流中删整段)、修订管理(定稿前删除草稿内容)。

Google Docs Format Text

作用:对指定索引区间应用加粗、斜体、下划线、字号与文字颜色。实现(L1449-L1636)组出 updateTextStyle 请求并显式声明要更新的字段列表。颜色输入用 hex 字符串,经 _parse_hex_color_to_rgb_floats 解析为归一化 RGB 浮点(支持 #RGB/#RRGGBB 简写,非法颜色会被忽略并返回 warning,不阻断其余格式生效)。所有格式选项可在一次请求里同时应用。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
start_index 待格式化文本起点(必须 >= 1) int
end_index 待格式化文本终点 int
bold 加粗(默认 False bool
italic 斜体(默认 False bool
underline 下划线(默认 False bool
font_size 字号(磅值,0 = 不变) int
foreground_color 文字颜色 hex,如 #FF0000 为红色 str

输出:resultsuccess,非法颜色时附 warning)、documenterror

典型用法:重点高亮(对关键结论/待办用加粗或颜色强调)、条件格式化(如逾期项标红的流程化判断)、统一排版(按品牌规范为生成内容套样式)。

Google Docs Insert Page Break

作用:在指定索引处插入分页符,强制后续内容另起一页。实现(L1121-L1217):index=0 时先解析到文档末尾再插 insertPageBreak

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
index 插入分页符的位置(0 = 文档末尾,源码默认 0 int

输出:resultdocumenterror

典型用法:报告排版(各大节之间加分页)、打印准备(控制 PDF 导出前的页面布局)、文档结构(按章节/章分隔以便阅读)。

Google Docs Insert Table

作用:在指定位置插入表格;可只给行列数建空表,也可提供二维数组内容直接建带数据的表,单元格内容可选以 Markdown 排版。实现(L831-L1118)是 docs.py 里最复杂的:先 insertTable,再抓取文档定位新表、递归提取每个 cell 的 startIndex,按索引降序回填(保证先写后面的 cell 不影响前面的索引);Markdown 模式下逐 cell 调用 to_requests(因请求相互依赖),纯文本模式下则把插入合并成一次批量调用。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
rows 行数(提供 content 时忽略,源码默认 3 int
columns 列数(提供 content 时忽略,源码默认 3 int
content 可选的二维单元格内容,如 [['Header1','Header2'],['Row1Col1','Row1Col2']];提供后行列由它推导 List[List[str]]
index 插入表格的位置(0 = 文档末尾,源码默认 0 int
format_as_markdown 是否将单元格内容按 Markdown 排版(标题/加粗/链接等,默认 False bool

输出:resultsuccessrowscolumnscells_populatedcells_found)、documenterror

典型用法:数据呈现(把 API/数据库结构化数据落成表格)、报告表格(加指标/对比/状态的汇总表)、模板表格(先建表结构再填充动态内容)。

导出与分享类块

Google Docs Export

作用:把 Google Doc 导出为 PDF、Word、文本等多种格式。实现(L1332-L1446)走 Drive files().export文本类格式(text/plaintext/html)返回 UTF-8 解码字符串,二进制格式返回 base64 编码字符串。格式取值由源码 ExportFormat 枚举固化:

输入 说明 类型 必填
document 选择要导出的 Google Doc Document
format application/pdf(默认)/ application/vnd.openxmlformats-officedocument.wordprocessingml.document(DOCX)/ application/vnd.oasis.opendocument.text(ODT)/ text/plain / text/html / application/epub+zip / application/rtf 枚举

输出:

输出 说明 类型
content 导出内容(二进制格式为 base64 编码) str
mime_type 导出内容的 MIME 类型 str
document 供链式操作使用的文档对象 GoogleDriveFile
error 导出失败时的错误消息 str

典型用法:报告分发(终稿导出 PDF 供邮件发送或归档)、跨平台分享(导出 Word 给非 Google Docs 用户)、备份(周期性导出 PDF 离线存档)。

Google Docs Share

作用:通过邮箱把文档分享给特定用户。实现(L1639-L1774):填了 email 就创建 type=user 的权限并可选 sendNotificationEmail + emailMessage;邮箱留空则创建 type=anyone 的"有链接者可访问"权限,仅生成可分享链接。

输入:

输入 说明 类型 必填
document 选择要分享的 Google Doc Document
email 分享对象的邮箱;留空表示链接分享 str
role 权限角色:reader(默认)| writer | commenter 枚举
send_notification 是否向对方发送通知邮件(源码默认 True bool
message 通知邮件附带的可选消息 str

输出:

输出 说明 类型
result 分享操作结果 Dict[str, Any]
share_link 文档链接 str
document 供链式操作使用的文档对象 GoogleDriveFile
error 分享失败时的错误消息 str

典型用法:自动化协作(生成文档后自动分享给干系人)、流程通知(审批流程中分享文档并通知收件人)、客户交付(含通知消息地把成品交付给客户)。

Google Docs Set Public Access

作用:切换文档的"公开/私有"状态。实现(L1777-L1890):公开时创建 type=anyone 权限并在链接后附加 ?usp=sharing;转私有则列出权限并删除所有 type=anyone 项。

输入:

输入 说明 类型 必填
document 选择要处理的 Google Doc Document
public True 公开 / False 私有(源码默认 True bool
role 公开访问角色:reader(默认)| commenter 枚举

输出:

输出 说明 类型
result 操作结果(含 is_public Dict[str, Any]
share_link 文档链接 str
document 供链式操作使用的文档对象 GoogleDriveFile
error 失败时的错误消息 str

典型用法:公开发布(定稿后开放给所有人)、访问开关(随工作流阶段自动切换文档可见性)、链接分发(生成无需逐个授权的分享链接)。

实操串联:一条"AI 生成 → 排版 → 分发"的完整链路

把上述块串起来即可构造典型的 AutoGPT 自动化场景(所有节点的关键结构均有前述源码与测试用例佐证,例如 Create 的 mock 输出形态可见于 docs.py,Append Markdown 的批量请求形态见 L1937-L1966):

  1. 准备模板文档:先用 Google Docs Create(或直接手动在 Drive 建文档)产出承载文档,输出 document(含 document_iddocument_url);
  2. 人工授权与选档:把 document 接入 AgentGoogleDriveFileInputBlockblocks/io.py)完成账号授权,注意保持 allowed_views 一致;开发中切勿把聊天里解析出的 Drive URL ID 塞进 input_default
  3. 探测结构Google Docs Get Structure 读取章节索引,为定点写入做准备;
  4. 内容注入(任选)
    • 整篇替换用 Replace All With Markdown
    • 占位符填充用 Replace Content With Markdown(配 {{SECTION}} token);
    • 精确区段刷新用 Replace Range With Markdown / Delete Content / Insert Markdown At
    • 持续累加用 Append Markdown,纯日志数据用 Append Plain Text
    • 结构化数据用 Insert Tableformat_as_markdown 打开可得到带加粗表头的表格);
  5. 排版微调Format Text 对关键结论加粗、着色;Insert Page Break 控制分页;
  6. 存档与分发Export 导出 PDF/DOCX 交付,ShareSet Public Access 把成品分享给团队成员或公开。

由于每个文档块都返回可链式的 document(携带 _credentials_id),从第 2 步之后的任何环节都不需要重复授权,链路可以完整串通。

边界与注意要点

  • 启用条件:未配置 google_client_id/google_client_secret 时全部文档块为 disabled(见 _auth.py)。
  • 凭据作用域:多数文档块默认申请 drive.file scope;Create 块显式声明 scope。平台层对凭据进行 scope 校验,块只能使用已授权且含所需 scope 的凭据。
  • 索引合法性:删除/格式化/替换区间的 start_index 必须 >= 1 且小于 end_index,否则块直接输出 error;插入型块的 index=0 语义(表与分页符)与 index=1(文本/Markdown)切勿混用。
  • 导出内容形态:文本格式为明文字符串,其余格式为 base64,下游接 HTTP/文件块时要按 MIME 区分解码。
  • 大量内容写入:Markdown 转换与表格填充会把多次 API 操作合并进单次 batchUpdate(尤其 Find-Replace-Markdown 的"先删后插"合并与表格按索引降序回填),既保证索引正确也降低调用量。

进一步了解整套集成清单,可浏览 Google 集成目录(覆盖 docs/calendar/gmail/sheets 等),块级自动化与平台使用可参考 AutoGPT 平台文档集成总览

登录后查看全文
热门项目推荐
相关项目推荐