IronClaw Google Docs 扩展深度指南让 Agent 创建、编辑并校验 Google 文档【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclawIronClaw 的 Google Docs 扩展google-docs允许 Agent 直接操作 Google Docs——创建文档、检查段落与表格、执行锚点编辑、批量填充表格并回读校验结果。本文以官方文档 docs/extensions/google/docs.md 为主线结合仓库中扩展包的 manifest、WASM 实现与测试用例完整讲解安装授权、15 个可用动作、文档 ID 使用技巧以及语义化操作背后的索引发现与并发校验原理帮助你让 Agent 可靠地完成日常文档工作。安装与授权在使用任何 Google Docs 能力之前需要先完成 Google OAuth 配置可参考 Google OAuth 配置指南。1. 启用 Google Docs API在 Google Cloud 控制台中进入APIs Services → Library搜索Google Docs API并点击Enable。2. 安装扩展ironclaw extension install google-docs3. 授权访问ironclaw extension activate google-docs激活需要凭证的扩展会启动其设置流程。你可以在 Web 界面见 docs/using/webui.mdx的Extensions页面完成该流程——对 Google 服务而言即 OAuth 同意屏幕。建议先完成 认证设置以便 Agent 捕获回调。令牌会加密存储并自动刷新。提示即使你已认证过某个 Google 服务每个额外的 Google 扩展仍需单独认证一次。扩展清单与 OAuth 细节从仓库中的 manifest.toml 可以看到该扩展的完整配置扩展 IDgoogle-docs版本0.2.0信任级别first_party_requested运行时wasm模块为wasm/google_docs_tool.wasm编译产物提交在wasm/目录WASM 源码在wasm-src/管理员配置部署级 OAuth 客户端凭证google_oauth_client_id非机密与google_oauth_client_secret机密由所有 Google 系列扩展共享OAuth 方式oauth2_code授权码流程授权端点https://accounts.google.com/o/oauth2/v2/auth令牌端点https://oauth2.googleapis.com/token使用 PKCEs256权限范围Scopeshttps://www.googleapis.com/auth/documents读写与https://www.googleapis.com/auth/documents.readonly只读manifest 中还有两个值得注意的运维细节extra_authorize_params包含access_type offline、include_granted_scopes true、prompt consent确保获得可用于自动刷新的刷新令牌。[auth.google.refresh]中的keepalive_idle_seconds 6048007 天——Google 对处于 testing 发布状态的应用其刷新令牌在闲置 7 天后失效宿主认证引擎的 keepalive 清理任务会在供应商生命周期到期前主动刷新空闲账户避免令牌过期。每个工具在 manifest 中还声明了自己的凭证注入方式写入型工具使用documents读写 scope只读型工具使用documents.readonly凭证以authorization: Bearer token请求头形式注入audience 为https://docs.googleapis.com。可用动作总览该扩展共提供15 个工具分为两类底层操作兼容与兜底动作功能create_document创建新文档可指定标题get_document获取文档元数据标题、修订号、命名区域read_content提取文档纯文本或结构化内容insert_text在正文指定索引处插入文本delete_content按起止索引删除内容区间replace_text全文档查找并替换文本format_text对文本区间应用字符格式粗体、斜体、字号、颜色format_paragraph对区间应用段落样式标题级别、对齐、间距、缩进insert_table插入指定行列数的表格create_list将段落区间转换为项目符号或编号列表batch_update单次 API 调用发送多个文档更新请求语义化操作首选具备校验与回读动作功能inspect_document以稳定文档索引检查段落与表格apply_text_edits应用经过校验、限定 Tab 的文本替换并验证结果create_table_with_data一次完成表格插入、填充、样式化与验证verify_document依据 Provider 状态核对预期文本与指定表格内容官方推荐的工作流是inspect_document→ 若干次apply_text_edits/create_table_with_data→verify_document。这样一个典型文档任务只需 34 次模型可见的能力调用扩展内部自行完成索引发现、批量单元格写入、并发检查和 Provider 回读原有的 11 个底层操作仍保留用于兼容与边缘场景。这一设计在包内 README.md 中有明确说明。WASM 分发机制该扩展是data-only 包没有 Rust crate可移植工具半区以 WASM guest 形式分发。入口在 lib.rs实现sandboxed-toolworld通过execute接收请求参数与调用上下文先由action_from_context根据capability_id如google-docs.apply_text_edits映射到具体动作再反序列化参数并分发给 api.rs 中的实现。两个安全细节值得一提调用方若在参数中自行携带action字段会被直接拒绝invalid_parameters动作名只能来自宿主注入的上下文防止越权调用schema()通过schemars::schema_for!从GoogleDocsAction类型自动推导 JSON Schema保证对外广告的 schema 与 serde 契约永不失步。使用示例配置完成后你可以直接向 Agent 提出如下请求Create a new document titled Q2 Marketing PlanRead the content of document ID 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upmsInsert a summary paragraph at the top of my reportReplace all occurrences of TBD with Pending Review in this docFormat the title as Heading 1 and make it boldAdd a 3-column table for the budget breakdownAgent 会将这些自然语言指令映射到上述工具调用。从 lib.rs 的文档示例可以看到底层请求的 JSON 形态{action: create_document, title: Meeting Notes} {action: read_content, document_id: abc123} {action: insert_text, document_id: abc123, text: Hello World\n, index: 1} {action: replace_text, document_id: abc123, find: Hello, replace: Hi} {action: format_text, document_id: abc123, start_index: 1, end_index: 12, bold: true, font_size: 18} {action: format_paragraph, document_id: abc123, start_index: 1, end_index: 12, named_style: HEADING_1}关键使用提示来自 WASM 实现文档 ID 即 Google Drive 文件 ID可用 google-drive 扩展的list_files按名称搜索已有文档索引为 0 基字符偏移空文档正文从索引 0 处的一个换行符开始因此要在文首插入文本请用索引1index -1表示追加到文末见 api.rs 中insert_text的实现-1 会映射为endOfSegmentLocation其他负数索引则直接报invalid_index多次编辑时从高索引向低索引处理避免索引位移问题——这一点在create_table_with_data中体现为按索引降序批量生成单元格写入请求见下文。深入语义化操作源码级原理inspect_document稳定的结构索引inspect_document通过GET /v1/documents/{id}?includeTabsContenttrue拉取文档api.rs将正文扁平化为带start_index/end_index的段落含named_style与表格含逐单元格文本结构。对多 Tab 文档实现会把第一个 Tab 的body与namedRanges归一化到顶层保证语义读取聚焦于首 Tab有对应单测tabbed_documents_are_normalized_to_the_first_tab_for_semantic_reads佐证。返回的稳定索引正是后续apply_text_edits与create_table_with_data定位的基准。apply_text_edits校验先行、原子替换、结果回读该动作的输入 schema 见 apply_text_edits.input.v1.jsondocument_id必填1256 字符edits为 1100 个{find, replace, replace_all, match_case}条目。执行流程api.rs分四步本地校验空find、超过 10000 字节的文本、非 ASCII 且不区分大小写的匹配都会被拒绝replace_allfalse时锚点文本必须唯一匹配一次否则报错提示改为replace_alltrue或换用唯一锚点单测anchored_edit_rejects_ambiguous_text_unless_replace_all_is_explicit验证修订锁读取文档当前revisionId通过writeControl.requiredRevisionId将替换请求绑定到该修订防止并发修改造成覆盖单测semantic_batch_updates_require_the_revision_that_was_inspected验证Tab 限定replaceAllText请求携带tabsCriteria.tabIds仅作用于被检查的 Tab单测anchored_edits_are_scoped_to_the_inspected_tab验证回读验证批量更新后重新拉取文档统计occurrences_changed并将实际全文与本地推演的期望文本比对输出verified布尔值。create_table_with_data一次调用完成建表四阶段输入 schema 见 create_table_with_data.input.v1.jsonindex至少为 1table_data为矩形行主序数据最多 100 行 × 20 列每单元格最多 10000 字节bold_header可选控制表头加粗。实现api.rs按阶段推进并在每个阶段通过 revision 校验检测并发漂移TableInserted携带前置修订插入表格插入位置取index 1跳过表格前的换行符见preferred_inserted_table_indexTablePopulated读取插入后的真实索引从最后一个单元格到第一个按降序生成insertText请求批量写入单测table_population_requests_are_emitted_from_last_cell_to_first验证顺序避免索引位移HeaderStyled可选对首行单元格应用bold文本样式Verified再次读取并比对表格内容输出rows、columns、populated_cells、stage、verified与可选的failure字段。任何阶段失败都会返回partial_table_result明确报告已完成到哪个阶段及失败原因而不是让 Agent 盲目重试。verify_document不改动 Provider 状态的只读校验verify_document纯读取校验支持最多 100 条文本片段期望与 20 条表格期望每条可通过table_index指向任意第 N 张表单测verification_can_target_a_later_table_without_padding_expectations验证。返回逐条VerificationCheck期望描述 通过与否与总verified布尔值即使某项不通过也不会报错中断方便 Agent 精准定位哪一项不符。使用文档 IDGoogle 文档 ID 出现在文档 URL 中https://docs.google.com/document/d/DOCUMENT_ID/edit提示你可以直接告诉 Agent use the document at this URL 并粘贴完整 URLAgent 会自动提取其中的文档 ID。错误与鉴权行为WASM 实现的错误映射api.rs值得了解任何 Google API 返回401都会映射为AuthRequired类型错误稳定错误码google_api_error_status_401宿主可据此触发重新认证/刷新流程单测api_status_error_401_maps_to_auth_required验证其他非 2xx 状态如 429 限流映射为Client错误错误码形如api_status_429并附带有界长度的响应体信息所有请求均通过宿主的 HTTP 能力发出由宿主负责凭证注入与限流WASM 工具本身永远接触不到真实 OAuth 令牌——这是 IronClaw 安全模型的关键一环。验证与测试该扩展通过两层机制保障质量manifest 投影测试cargo test -p ironclaw_extension_registry校验扩展清单的合法性与投影一致性WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/google_docs_tool.wasm与wasm-src/源码同步防止提交过期的二进制产物。此外api.rs 内置了十余个单元测试覆盖索引校验、颜色解析、多 Tab 归一化、修订漂移检测、表格阶段往返序列化等关键路径first_party_manifest_v3_parity.rs 等集成测试则验证了该 first-party 扩展在组合层与 WebUI 中的一致性。小结Google Docs 扩展把创建—检查—编辑—校验的完整闭环封装进 15 个模型可见的工具中。日常文档工作应优先使用inspect_document、apply_text_edits、create_table_with_data与verify_document这四个语义化动作它们内部处理索引发现、批量请求、修订并发控制与 Provider 回读把原本需要多轮索引探测的流程压缩到 34 次调用同时保留底层动作作为兼容与兜底手段。配合加密存储、自动刷新且永不出 guest 的 OAuth 令牌这套方案在易用性与安全性之间取得了良好平衡。若需按名称搜索文档可组合使用 google-drive 扩展Google 系列扩展的 manifest 均位于 crates/extensions/packages 目录下。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw Google Docs 扩展深度指南：让 Agent 创建、编辑并校验 Google 文档
IronClaw Google Docs 扩展深度指南让 Agent 创建、编辑并校验 Google 文档【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclawIronClaw 的 Google Docs 扩展google-docs允许 Agent 直接操作 Google Docs——创建文档、检查段落与表格、执行锚点编辑、批量填充表格并回读校验结果。本文以官方文档 docs/extensions/google/docs.md 为主线结合仓库中扩展包的 manifest、WASM 实现与测试用例完整讲解安装授权、15 个可用动作、文档 ID 使用技巧以及语义化操作背后的索引发现与并发校验原理帮助你让 Agent 可靠地完成日常文档工作。安装与授权在使用任何 Google Docs 能力之前需要先完成 Google OAuth 配置可参考 Google OAuth 配置指南。1. 启用 Google Docs API在 Google Cloud 控制台中进入APIs Services → Library搜索Google Docs API并点击Enable。2. 安装扩展ironclaw extension install google-docs3. 授权访问ironclaw extension activate google-docs激活需要凭证的扩展会启动其设置流程。你可以在 Web 界面见 docs/using/webui.mdx的Extensions页面完成该流程——对 Google 服务而言即 OAuth 同意屏幕。建议先完成 认证设置以便 Agent 捕获回调。令牌会加密存储并自动刷新。提示即使你已认证过某个 Google 服务每个额外的 Google 扩展仍需单独认证一次。扩展清单与 OAuth 细节从仓库中的 manifest.toml 可以看到该扩展的完整配置扩展 IDgoogle-docs版本0.2.0信任级别first_party_requested运行时wasm模块为wasm/google_docs_tool.wasm编译产物提交在wasm/目录WASM 源码在wasm-src/管理员配置部署级 OAuth 客户端凭证google_oauth_client_id非机密与google_oauth_client_secret机密由所有 Google 系列扩展共享OAuth 方式oauth2_code授权码流程授权端点https://accounts.google.com/o/oauth2/v2/auth令牌端点https://oauth2.googleapis.com/token使用 PKCEs256权限范围Scopeshttps://www.googleapis.com/auth/documents读写与https://www.googleapis.com/auth/documents.readonly只读manifest 中还有两个值得注意的运维细节extra_authorize_params包含access_type offline、include_granted_scopes true、prompt consent确保获得可用于自动刷新的刷新令牌。[auth.google.refresh]中的keepalive_idle_seconds 6048007 天——Google 对处于 testing 发布状态的应用其刷新令牌在闲置 7 天后失效宿主认证引擎的 keepalive 清理任务会在供应商生命周期到期前主动刷新空闲账户避免令牌过期。每个工具在 manifest 中还声明了自己的凭证注入方式写入型工具使用documents读写 scope只读型工具使用documents.readonly凭证以authorization: Bearer token请求头形式注入audience 为https://docs.googleapis.com。可用动作总览该扩展共提供15 个工具分为两类底层操作兼容与兜底动作功能create_document创建新文档可指定标题get_document获取文档元数据标题、修订号、命名区域read_content提取文档纯文本或结构化内容insert_text在正文指定索引处插入文本delete_content按起止索引删除内容区间replace_text全文档查找并替换文本format_text对文本区间应用字符格式粗体、斜体、字号、颜色format_paragraph对区间应用段落样式标题级别、对齐、间距、缩进insert_table插入指定行列数的表格create_list将段落区间转换为项目符号或编号列表batch_update单次 API 调用发送多个文档更新请求语义化操作首选具备校验与回读动作功能inspect_document以稳定文档索引检查段落与表格apply_text_edits应用经过校验、限定 Tab 的文本替换并验证结果create_table_with_data一次完成表格插入、填充、样式化与验证verify_document依据 Provider 状态核对预期文本与指定表格内容官方推荐的工作流是inspect_document→ 若干次apply_text_edits/create_table_with_data→verify_document。这样一个典型文档任务只需 34 次模型可见的能力调用扩展内部自行完成索引发现、批量单元格写入、并发检查和 Provider 回读原有的 11 个底层操作仍保留用于兼容与边缘场景。这一设计在包内 README.md 中有明确说明。WASM 分发机制该扩展是data-only 包没有 Rust crate可移植工具半区以 WASM guest 形式分发。入口在 lib.rs实现sandboxed-toolworld通过execute接收请求参数与调用上下文先由action_from_context根据capability_id如google-docs.apply_text_edits映射到具体动作再反序列化参数并分发给 api.rs 中的实现。两个安全细节值得一提调用方若在参数中自行携带action字段会被直接拒绝invalid_parameters动作名只能来自宿主注入的上下文防止越权调用schema()通过schemars::schema_for!从GoogleDocsAction类型自动推导 JSON Schema保证对外广告的 schema 与 serde 契约永不失步。使用示例配置完成后你可以直接向 Agent 提出如下请求Create a new document titled Q2 Marketing PlanRead the content of document ID 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upmsInsert a summary paragraph at the top of my reportReplace all occurrences of TBD with Pending Review in this docFormat the title as Heading 1 and make it boldAdd a 3-column table for the budget breakdownAgent 会将这些自然语言指令映射到上述工具调用。从 lib.rs 的文档示例可以看到底层请求的 JSON 形态{action: create_document, title: Meeting Notes} {action: read_content, document_id: abc123} {action: insert_text, document_id: abc123, text: Hello World\n, index: 1} {action: replace_text, document_id: abc123, find: Hello, replace: Hi} {action: format_text, document_id: abc123, start_index: 1, end_index: 12, bold: true, font_size: 18} {action: format_paragraph, document_id: abc123, start_index: 1, end_index: 12, named_style: HEADING_1}关键使用提示来自 WASM 实现文档 ID 即 Google Drive 文件 ID可用 google-drive 扩展的list_files按名称搜索已有文档索引为 0 基字符偏移空文档正文从索引 0 处的一个换行符开始因此要在文首插入文本请用索引1index -1表示追加到文末见 api.rs 中insert_text的实现-1 会映射为endOfSegmentLocation其他负数索引则直接报invalid_index多次编辑时从高索引向低索引处理避免索引位移问题——这一点在create_table_with_data中体现为按索引降序批量生成单元格写入请求见下文。深入语义化操作源码级原理inspect_document稳定的结构索引inspect_document通过GET /v1/documents/{id}?includeTabsContenttrue拉取文档api.rs将正文扁平化为带start_index/end_index的段落含named_style与表格含逐单元格文本结构。对多 Tab 文档实现会把第一个 Tab 的body与namedRanges归一化到顶层保证语义读取聚焦于首 Tab有对应单测tabbed_documents_are_normalized_to_the_first_tab_for_semantic_reads佐证。返回的稳定索引正是后续apply_text_edits与create_table_with_data定位的基准。apply_text_edits校验先行、原子替换、结果回读该动作的输入 schema 见 apply_text_edits.input.v1.jsondocument_id必填1256 字符edits为 1100 个{find, replace, replace_all, match_case}条目。执行流程api.rs分四步本地校验空find、超过 10000 字节的文本、非 ASCII 且不区分大小写的匹配都会被拒绝replace_allfalse时锚点文本必须唯一匹配一次否则报错提示改为replace_alltrue或换用唯一锚点单测anchored_edit_rejects_ambiguous_text_unless_replace_all_is_explicit验证修订锁读取文档当前revisionId通过writeControl.requiredRevisionId将替换请求绑定到该修订防止并发修改造成覆盖单测semantic_batch_updates_require_the_revision_that_was_inspected验证Tab 限定replaceAllText请求携带tabsCriteria.tabIds仅作用于被检查的 Tab单测anchored_edits_are_scoped_to_the_inspected_tab验证回读验证批量更新后重新拉取文档统计occurrences_changed并将实际全文与本地推演的期望文本比对输出verified布尔值。create_table_with_data一次调用完成建表四阶段输入 schema 见 create_table_with_data.input.v1.jsonindex至少为 1table_data为矩形行主序数据最多 100 行 × 20 列每单元格最多 10000 字节bold_header可选控制表头加粗。实现api.rs按阶段推进并在每个阶段通过 revision 校验检测并发漂移TableInserted携带前置修订插入表格插入位置取index 1跳过表格前的换行符见preferred_inserted_table_indexTablePopulated读取插入后的真实索引从最后一个单元格到第一个按降序生成insertText请求批量写入单测table_population_requests_are_emitted_from_last_cell_to_first验证顺序避免索引位移HeaderStyled可选对首行单元格应用bold文本样式Verified再次读取并比对表格内容输出rows、columns、populated_cells、stage、verified与可选的failure字段。任何阶段失败都会返回partial_table_result明确报告已完成到哪个阶段及失败原因而不是让 Agent 盲目重试。verify_document不改动 Provider 状态的只读校验verify_document纯读取校验支持最多 100 条文本片段期望与 20 条表格期望每条可通过table_index指向任意第 N 张表单测verification_can_target_a_later_table_without_padding_expectations验证。返回逐条VerificationCheck期望描述 通过与否与总verified布尔值即使某项不通过也不会报错中断方便 Agent 精准定位哪一项不符。使用文档 IDGoogle 文档 ID 出现在文档 URL 中https://docs.google.com/document/d/DOCUMENT_ID/edit提示你可以直接告诉 Agent use the document at this URL 并粘贴完整 URLAgent 会自动提取其中的文档 ID。错误与鉴权行为WASM 实现的错误映射api.rs值得了解任何 Google API 返回401都会映射为AuthRequired类型错误稳定错误码google_api_error_status_401宿主可据此触发重新认证/刷新流程单测api_status_error_401_maps_to_auth_required验证其他非 2xx 状态如 429 限流映射为Client错误错误码形如api_status_429并附带有界长度的响应体信息所有请求均通过宿主的 HTTP 能力发出由宿主负责凭证注入与限流WASM 工具本身永远接触不到真实 OAuth 令牌——这是 IronClaw 安全模型的关键一环。验证与测试该扩展通过两层机制保障质量manifest 投影测试cargo test -p ironclaw_extension_registry校验扩展清单的合法性与投影一致性WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/google_docs_tool.wasm与wasm-src/源码同步防止提交过期的二进制产物。此外api.rs 内置了十余个单元测试覆盖索引校验、颜色解析、多 Tab 归一化、修订漂移检测、表格阶段往返序列化等关键路径first_party_manifest_v3_parity.rs 等集成测试则验证了该 first-party 扩展在组合层与 WebUI 中的一致性。小结Google Docs 扩展把创建—检查—编辑—校验的完整闭环封装进 15 个模型可见的工具中。日常文档工作应优先使用inspect_document、apply_text_edits、create_table_with_data与verify_document这四个语义化动作它们内部处理索引发现、批量请求、修订并发控制与 Provider 回读把原本需要多轮索引探测的流程压缩到 34 次调用同时保留底层动作作为兼容与兜底手段。配合加密存储、自动刷新且永不出 guest 的 OAuth 令牌这套方案在易用性与安全性之间取得了良好平衡。若需按名称搜索文档可组合使用 google-drive 扩展Google 系列扩展的 manifest 均位于 crates/extensions/packages 目录下。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考