人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文聚焦 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一起构成 34 次模型可见调用的语义化编辑闭环替代了过去需要多次探测文档索引的低级操作参见 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.逐句拆解它就是模型调用该工具时的行为准则Verify required text fragments and exact row-major table contents against the current Google Docs provider state—— 校验对象是服务端当前状态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—— 表格定位规则expected_tables数组里的每个期望项都可以显式指定一个从 0 开始的table_index不指定时第 N 个期望项默认指向文档中的第 N 张表。这也是源码中expectation.table_index.unwrap_or(index)的语义来源。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核心要点如下参数类型必填约束说明document_idstring是1256 字符文档 ID与 Google Drive 文件 ID 相同expected_textstring[]二选一1100 项每项 110000 字节文档必须全部包含的文本片段expected_tablesobject[]二选一120 项需按文档顺序精确匹配的表格期望其中expected_tables的每一项TableExpectation结构为table_indexinteger可选01000零基的表格位置省略时默认取该项在expected_tables数组中的下标。table_datastring[][]必填行主序的期望单元格文本。外层数组每项是一行内层数组每项是一个单元格整体约束为 1100 行、每行 120 列、单元格内容不超过 10000 字节。另有两条顶层约束值得注意expected_text与expected_tables通过anyOf实现至少提供其一也可同时提供完全空白的请求会被 schema 拒绝。additionalProperties: false不允许传入 schema 之外的任何字段包括action——与提示文档最后一句的告诫互为印证。这些限制在 Rust 侧同样有运行时防线verify_parsed_document会校验文本期望上限 100 条、表格期望上限 20 条、片段 110000 字节越界一律返回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 checksverify_document的返回类型VerifyDocumentResult定义见 types.rs包含四个字段字段类型说明document_idstring实际读取到的文档 IDrevision_idstring校验时刻的文档修订 ID可用于与后续写入的writeControl.requiredRevisionId配合做并发保护verifiedboolean全部检查项通过为true任一失败为falsechecksarray逐期望项的检查明细每项含expectation人类可读的期望描述与passed是否通过典型的两类检查项描述格式为文本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_documentfetch_document(document_id)以GET https://docs.googleapis.com/v1/documents/{id}?includeTabsContenttrue拉取服务端最新状态并对多 Tab 文档做normalize_first_tab归一化——即把第一个 Tab 的body、namedRanges提升到文档顶层保证语义操作始终作用于首个 Tab见 api.rs。document_text递归遍历正文结构元素段落 textRun、表格单元格、目录 tableOfContents拼接出纯文本全文extract_text_from_elements。对每条expected_text做子串包含判断text.contains(fragment)。对每个表格期望先取零基表格序号省略时取数组下标再执行逐格精确比对生成检查项。汇总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 中承担最后一道确认的角色推荐把它编排在语义化编辑工作流的收尾google-docs.inspect_document读取段落与表格的结构化索引确定编辑锚点。google-docs.apply_text_edits/google-docs.create_table_with_data做一次原子化的文本替换或整表写入后者自带写入后回读校验。google-docs.verify_document以服务端最新状态为准对关键文本必须存在和关键表格内容精确一致做一次独立的回归断言。这样一轮典型的文档任务只需 34 次模型可见的能力调用见 google-docs 包 README索引发现、批量单元格写入、并发校验、服务端回读都由扩展内部完成。实践建议把校验项写成业务断言例如合同必须包含甲方条款、预算表第一张表必须与提交的数据一致而不是泛泛地读一遍文档看看充分利用逐项checks诊断verified: false后先定位passed: false的期望项再决定是补编辑还是结束任务校验纯只读可在循环编辑过程中多次调用无需担心副作用携带revision_id进入下一步写入用writeControl.requiredRevisionId防止并发编辑导致的状态漂移。七、边界与限制表格是精确匹配而非模糊匹配单元格文本需在去除末尾换行后与期望完全相等任何多余空格、大小写差异都会导致失败。作用于第一个 Tab多 Tab 文档的语义读取会被归一化到第一个 Tabverify_document的文本与表格断言均针对该 Tab 展开。期望规模有上限文本期望最多 100 条、表格期望最多 20 条、单表最多 100 行 × 20 列超出即参数错误。校验点即服务端真实状态该校验不依赖任何本地缓存或前序读取结果适合作为与提供商状态对齐的权威断言。延伸阅读google-docs 包 README扩展全貌与语义化优先的设计取舍verify_document 输入 schema完整 JSON Schema 契约WASM 客端实现 lib.rs能力分发与 action 参数约束API 实现 api.rs读取、比对、修订号与错误映射的完整实现类型定义 types.rsVerifyDocumentResult、TableExpectation、VerificationCheck等结构定义e2e 契约用例google_docs_verify_document*系列端到端断言Google 扩展文档google-docs能力族的整体介绍赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Docs 扩展深度指南让 Agent 创建、编辑并校验 Google 文档IronClaw Google Docs 扩展深度指南让 Agent 创建、编辑并校验 Google 文档 IronClaw 的 Google Docs 扩展人工智能AI 应用交互助手AI AgentIronClaw 谷歌表格扩展 add_sheet 工具从 Capability 提示文档到 Sheets API 的完整调用链IronClaw 谷歌表格扩展 add_sheet 工具从 Capability 提示文档到 Sheets API 的完整调用链 导读 本文以 IronCla人工智能AI 应用交互助手AI Agentgogcli 谷歌文档原生表格行删除指南gog docs table-row delete 命令详解与底层实现gogcli 谷歌文档原生表格行删除指南 gog docs table row delete 命令详解与底层实现 导读 gog docs table row创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考