IronClaw 谷歌文档校验指南：使用 verify_document 对 Google Docs 做文本与表格断言

• 人工智能
• AI 应用
• 交互助手
• AI Agent

导读

本文聚焦 IronClaw 的google-docs扩展中面向模型暴露的只读校验能力verify_document：它把"文档内容是否符合预期"从一次脆弱的手工读取，变成一次带结构化断言的验证，是 IronClaw 语义化文档工作流（inspect_document→apply_text_edits/create_table_with_data→verify_document）闭环中最后也是最重要的一环。读完本文，你将掌握该能力的调用约定、输入输出契约、底层实现原理，以及如何在 Agent 场景中用它做安全的变更后回归验证。

一、verify_document 是什么

verify_document是 IronClawgoogle-docs扩展提供的 15 个工具之一，能力 ID 为google-docs.verify_document。它的职责在官方能力说明中写得很直白：

Verify required text fragments and exact row-major table contents against the current Google Docs provider state.

即：以当前 Google Docs 服务端状态为准，校验文档是否包含指定的文本片段，以及指定表格的单元格内容是否与期望的行主序（row-major）数据完全一致。

它的几个关键特性，决定了它在 IronClaw 工具矩阵中的独特定位：

• 纯只读：整个操作只发起GET读取，从不向文档写入任何内容（其effects声明为["network", "use_secret"]，不含external_write，见 manifest.toml）。
• 失败不报错：当文档与预期不符时，它不会以工具调用失败（Failure）收场，而是返回verified: false，并在checks数组中逐条给出每个期望项（expectation）的通过/失败明细，方便模型精确诊断到底哪一项没满足。
• 结构化比对：文本采用"包含式片段匹配"（substring），表格采用"按文档顺序逐格精确匹配"，二者均可独立或组合使用。

在 IronClaw 官方推荐的工作流里，verify_document与inspect_document、apply_text_edits、create_table_with_data一起构成 3～4 次模型可见调用的"语义化编辑闭环"，替代了过去需要多次探测文档索引的低级操作（参见 google-docs 包 README）。

二、能力提示（prompt）逐句解读

关联文档全文如下：

Verify required text fragments and exact row-major table contents against the current Google Docs provider state.

This operation never mutates the document. A mismatch returnsverified: falsewith per-expectation checks instead of failing the tool call.

Each table expectation may set a zero-basedtable_index; when omitted, expectations target tables sequentially in their listed order.

The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.

逐句拆解，它就是模型调用该工具时的行为准则：

1. "Verify required text fragments and exact row-major table contents against the current Google Docs provider state"—— 校验对象是"服务端当前状态"（provider state），而非任何本地缓存或上次读取的快照；每次调用都会重新读取文档。
2. "This operation never mutates the document"—— 该操作零副作用。在需要"变更后确认"或"防御性复核"的场景下，模型可以放心反复调用，不会引入额外写入。
3. "A mismatch returnsverified: falsewith per-expectation checks instead of failing the tool call"—— 这是它区别于普通错误处理的关键：不一致是业务结果而不是工具故障，因此以结构化结果返回，模型可以据此决定是继续编辑还是终止。
4. "Each table expectation may set a zero-basedtable_index; when omitted, expectations target tables sequentially in their listed order"—— 表格定位规则：expected_tables数组里的每个期望项都可以显式指定一个从 0 开始的table_index；不指定时，第 N 个期望项默认指向文档中的第 N 张表。这也是源码中expectation.table_index.unwrap_or(index)的语义来源。
5. "The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field"—— 调用方协议：工具的选择与分发由宿主（host）根据能力 ID 完成，模型只需按输入 schema 提供参数，绝不能自行添加action字段。这一点在源码层有强约束：WASM 客端的params_with_action会直接拒绝任何携带action键的请求（返回invalid_parameters，见 lib.rs 及同名单元测试）。

三、输入参数契约

verify_document的输入 schema 定义在 verify_document.input.v1.json，核心要点如下：

其中expected_tables的每一项（TableExpectation）结构为：

• table_index（integer，可选，0～1000）：零基的表格位置；省略时默认取该项在expected_tables数组中的下标。
• table_data（string[][]，必填）：行主序的期望单元格文本。外层数组每项是一行，内层数组每项是一个单元格；整体约束为 1～100 行、每行 1～20 列、单元格内容不超过 10000 字节。

另有两条顶层约束值得注意：

• expected_text与expected_tables通过anyOf实现至少提供其一（也可同时提供），完全空白的请求会被 schema 拒绝。
• additionalProperties: false：不允许传入 schema 之外的任何字段，包括action——与提示文档最后一句的告诫互为印证。

这些限制在 Rust 侧同样有运行时防线：verify_parsed_document会校验"文本期望上限 100 条、表格期望上限 20 条、片段 1～10000 字节"，越界一律返回invalid_parameters（见 api.rs）。

调用示例

{ "document_id": "1AbC...xyz", "expected_text": ["user-owned agents", "IronClaw"], "expected_tables": [ { "table_index": 0, "table_data": [ ["Owner", "Scope"], ["Ada", "user-owned agents"] ] } ] }

以上请求的含义是：文档中必须同时出现 "user-owned agents" 与 "IronClaw" 两段文本，且文档中第一张表格的内容必须与给定的 2×2 行主序数据逐格一致。

四、返回结构：verified + checks

verify_document的返回类型VerifyDocumentResult（定义见 types.rs）包含四个字段：

典型的两类检查项描述格式为：

• 文本：document contains text "xxx"
• 表格：table 0 matches expected data

一个失败场景的返回示例（来自 e2e 测试契约）：

{ "document_id": "", "revision_id": "", "verified": false, "checks": [ { "expectation": "document contains text \"missing\"", "passed": false } ] }

这条输出正是 provider_operation_google_docs_cases.py 中google_docs_verify_document_empty用例的精确断言：即便文档为空、期望落空，工具依然以成功响应返回结构化失败明细，而不是抛出工具级错误。

五、底层实现：读取、比对与边界

5.1 从"读取"到"校验"的完整链路

入口在 api.rs 的verify_document：

1. fetch_document(document_id)以GET https://docs.googleapis.com/v1/documents/{id}?includeTabsContent=true拉取服务端最新状态，并对多 Tab 文档做normalize_first_tab归一化——即把第一个 Tab 的body、namedRanges提升到文档顶层，保证语义操作始终作用于首个 Tab（见 api.rs）。
2. document_text递归遍历正文结构元素（段落 textRun、表格单元格、目录 tableOfContents），拼接出纯文本全文（extract_text_from_elements）。
3. 对每条expected_text做子串包含判断（text.contains(fragment)）。
4. 对每个表格期望，先取零基表格序号（省略时取数组下标），再执行逐格精确比对，生成检查项。
5. 汇总checks，全部通过则verified = true。

5.2 表格匹配的精确语义

表格比对函数table_element_matches（见 api.rs）的规则非常严格：

• 表格的行数必须与期望一致；
• 每行的列数必须与期望一致；
• 每个单元格的文本在去除末尾换行符（trim_end_matches('\n')）后与期望字符串完全相等。

这意味着table_data必须是与文档中表格完全对齐的"行主序精确快照"，顺序、行列数、单元格内容任何一项不一致都会导致该检查项passed: false。文档中表格的选取方式是"按正文 content 数组中table元素的出现顺序编号"，与table_index一一对应（table_matches先过滤出所有 table 元素再按下标取值，见 api.rs）。

5.3 只读与安全的三个保证

• 零写入：verify_document不会构造任何batchUpdate请求，仅走只读 GET 路径；其凭据注入使用的也是documents.readonly只读 scope（见 manifest.toml），与写入类工具使用的documentsscope 区分开来。
• 修订号旁证：返回的revision_id来自读取响应，可用于下一步写入时附加writeControl.requiredRevisionId做乐观并发控制（batch_update_body的实现见 api.rs），从而把"校验通过"转化为"基于该校验时刻的写入"。
• 错误边界清晰：请求本身的参数问题（如空期望、超限）会以invalid_parameters的 Input 类失败返回；而"内容不匹配"则永远走成功路径返回verified: false。两类结果语义分明，模型无需猜测。

5.4 测试印证

仓库中有多层测试证据支撑该能力的行为契约：

• WASM 客端单元测试verification_reports_each_failed_expectation_without_erroring：验证"文本通过、表格未匹配"时返回verified: false且checks长度为 2、逐项 passed 正确（见 api.rs）。
• verification_can_target_a_later_table_without_padding_expectations：验证只给一条table_index: Some(1)的期望即可直接校验文档中的第二张表，无需为第一张表填充占位期望（见 api.rs）。
• e2e 契约用例google_docs_verify_document与google_docs_verify_document_empty（见 provider_operation_google_docs_cases.py）：分别覆盖"期望文本命中"与"文档为空、期望落空"两条路径的精确输出。
• schema 一致性测试semantic_input_schemas_bound_document_ids：断言包括verify_document在内的语义类输入 schema 中document_id.maxLength == 256（见 api.rs）。

六、在 Agent 工作流中的典型用法

verify_document在 IronClaw 中承担"最后一道确认"的角色，推荐把它编排在语义化编辑工作流的收尾：

1. google-docs.inspect_document：读取段落与表格的结构化索引，确定编辑锚点。
2. google-docs.apply_text_edits/google-docs.create_table_with_data：做一次原子化的文本替换或整表写入（后者自带写入后回读校验）。
3. google-docs.verify_document：以服务端最新状态为准，对"关键文本必须存在"和"关键表格内容精确一致"做一次独立的回归断言。

这样一轮典型的文档任务只需 3～4 次模型可见的能力调用（见 google-docs 包 README），索引发现、批量单元格写入、并发校验、服务端回读都由扩展内部完成。

实践建议：

• 把校验项写成业务断言，例如"合同必须包含甲方条款"、"预算表第一张表必须与提交的数据一致"，而不是泛泛地"读一遍文档看看"；
• 充分利用逐项checks诊断：verified: false后先定位passed: false的期望项，再决定是补编辑还是结束任务；
• 校验纯只读，可在循环编辑过程中多次调用，无需担心副作用；
• 携带revision_id进入下一步写入，用writeControl.requiredRevisionId防止并发编辑导致的状态漂移。

七、边界与限制

• 表格是精确匹配而非模糊匹配：单元格文本需在去除末尾换行后与期望完全相等，任何多余空格、大小写差异都会导致失败。
• 作用于第一个 Tab：多 Tab 文档的语义读取会被归一化到第一个 Tab，verify_document的文本与表格断言均针对该 Tab 展开。
• 期望规模有上限：文本期望最多 100 条、表格期望最多 20 条、单表最多 100 行 × 20 列，超出即参数错误。
• 校验点即服务端真实状态：该校验不依赖任何本地缓存或前序读取结果，适合作为与提供商状态对齐的权威断言。

延伸阅读

• google-docs 包 README：扩展全貌与"语义化优先"的设计取舍
• verify_document 输入 schema：完整 JSON Schema 契约
• WASM 客端实现 lib.rs：能力分发与 action 参数约束
• API 实现 api.rs：读取、比对、修订号与错误映射的完整实现
• 类型定义 types.rs：VerifyDocumentResult、TableExpectation、VerificationCheck等结构定义
• e2e 契约用例：google_docs_verify_document*系列端到端断言
• Google 扩展文档：google-docs能力族的整体介绍

• 人工智能
• AI 应用
• 交互助手
• AI Agent