人工智能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閉環(huán)中最后也是最重要的一環(huán)。讀完本文你將掌握該能力的調用約定、輸入輸出契約、底層實現(xiàn)原理以及如何在 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 服務端狀態(tài)為準校驗文檔是否包含指定的文本片段以及指定表格的單元格內容是否與期望的行主序row-major數(shù)據(jù)完全一致。它的幾個關鍵特性決定了它在 IronClaw 工具矩陣中的獨特定位純只讀整個操作只發(fā)起GET讀取從不向文檔寫入任何內容其effects聲明為[network, use_secret]不含external_write見 manifest.toml。失敗不報錯當文檔與預期不符時它不會以工具調用失敗Failure收場而是返回verified: false并在checks數(shù)組中逐條給出每個期望項expectation的通過/失敗明細方便模型精確診斷到底哪一項沒滿足。結構化比對文本采用包含式片段匹配substring表格采用按文檔順序逐格精確匹配二者均可獨立或組合使用。在 IronClaw 官方推薦的工作流里verify_document與inspect_document、apply_text_edits、create_table_with_data一起構成 34 次模型可見調用的語義化編輯閉環(huán)替代了過去需要多次探測文檔索引的低級操作參見 google-docs 包 README。二、能力提示prompt逐句解讀關聯(lián)文檔全文如下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—— 校驗對象是服務端當前狀態(tài)provider state而非任何本地緩存或上次讀取的快照每次調用都會重新讀取文檔。This operation never mutates the document—— 該操作零副作用。在需要變更后確認或防御性復核的場景下模型可以放心反復調用不會引入額外寫入。A mismatch returnsverified: falsewith per-expectation checks instead of failing the tool call—— 這是它區(qū)別于普通錯誤處理的關鍵不一致是業(yè)務結果而不是工具故障因此以結構化結果返回模型可以據(jù)此決定是繼續(xù)編輯還是終止。Each table expectation may set a zero-basedtable_index; when omitted, expectations target tables sequentially in their listed order—— 表格定位規(guī)則expected_tables數(shù)組里的每個期望項都可以顯式指定一個從 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—— 調用方協(xié)議工具的選擇與分發(fā)由宿主host根據(jù)能力 ID 完成模型只需按輸入 schema 提供參數(shù)絕不能自行添加action字段。這一點在源碼層有強約束WASM 客端的params_with_action會直接拒絕任何攜帶action鍵的請求返回invalid_parameters見 lib.rs 及同名單元測試。三、輸入參數(shù)契約verify_document的輸入 schema 定義在 verify_document.input.v1.json核心要點如下參數(shù)類型必填約束說明document_idstring是1256 字符文檔 ID與 Google Drive 文件 ID 相同expected_textstring[]二選一1100 項每項 110000 字節(jié)文檔必須全部包含的文本片段expected_tablesobject[]二選一120 項需按文檔順序精確匹配的表格期望其中expected_tables的每一項TableExpectation結構為table_indexinteger可選01000零基的表格位置省略時默認取該項在expected_tables數(shù)組中的下標。table_datastring[][]必填行主序的期望單元格文本。外層數(shù)組每項是一行內層數(shù)組每項是一個單元格整體約束為 1100 行、每行 120 列、單元格內容不超過 10000 字節(jié)。另有兩條頂層約束值得注意expected_text與expected_tables通過anyOf實現(xiàn)至少提供其一也可同時提供完全空白的請求會被 schema 拒絕。additionalProperties: false不允許傳入 schema 之外的任何字段包括action——與提示文檔最后一句的告誡互為印證。這些限制在 Rust 側同樣有運行時防線verify_parsed_document會校驗文本期望上限 100 條、表格期望上限 20 條、片段 110000 字節(jié)越界一律返回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] ] } ] }以上請求的含義是文檔中必須同時出現(xiàn) user-owned agents 與 IronClaw 兩段文本且文檔中第一張表格的內容必須與給定的 2×2 行主序數(shù)據(jù)逐格一致。四、返回結構verified checksverify_document的返回類型VerifyDocumentResult定義見 types.rs包含四個字段字段類型說明document_idstring實際讀取到的文檔 IDrevision_idstring校驗時刻的文檔修訂 ID可用于與后續(xù)寫入的writeControl.requiredRevisionId配合做并發(fā)保護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用例的精確斷言即便文檔為空、期望落空工具依然以成功響應返回結構化失敗明細而不是拋出工具級錯誤。五、底層實現(xiàn)讀取、比對與邊界5.1 從讀取到校驗的完整鏈路入口在 api.rs 的verify_documentfetch_document(document_id)以GET https://docs.googleapis.com/v1/documents/{id}?includeTabsContenttrue拉取服務端最新狀態(tài)并對多 Tab 文檔做normalize_first_tab歸一化——即把第一個 Tab 的body、namedRanges提升到文檔頂層保證語義操作始終作用于首個 Tab見 api.rs。document_text遞歸遍歷正文結構元素段落 textRun、表格單元格、目錄 tableOfContents拼接出純文本全文extract_text_from_elements。對每條expected_text做子串包含判斷text.contains(fragment)。對每個表格期望先取零基表格序號省略時取數(shù)組下標再執(zhí)行逐格精確比對生成檢查項。匯總checks全部通過則verified true。5.2 表格匹配的精確語義表格比對函數(shù)table_element_matches見 api.rs的規(guī)則非常嚴格表格的行數(shù)必須與期望一致每行的列數(shù)必須與期望一致每個單元格的文本在去除末尾換行符trim_end_matches(\n)后與期望字符串完全相等。這意味著table_data必須是與文檔中表格完全對齊的行主序精確快照順序、行列數(shù)、單元格內容任何一項不一致都會導致該檢查項passed: false。文檔中表格的選取方式是按正文 content 數(shù)組中table元素的出現(xiàn)順序編號與table_index一一對應table_matches先過濾出所有 table 元素再按下標取值見 api.rs。5.3 只讀與安全的三個保證零寫入verify_document不會構造任何batchUpdate請求僅走只讀 GET 路徑其憑據(jù)注入使用的也是documents.readonly只讀 scope見 manifest.toml與寫入類工具使用的documentsscope 區(qū)分開來。修訂號旁證返回的revision_id來自讀取響應可用于下一步寫入時附加writeControl.requiredRevisionId做樂觀并發(fā)控制batch_update_body的實現(xiàn)見 api.rs從而把校驗通過轉化為基于該校驗時刻的寫入。錯誤邊界清晰請求本身的參數(shù)問題如空期望、超限會以invalid_parameters的 Input 類失敗返回而內容不匹配則永遠走成功路徑返回verified: false。兩類結果語義分明模型無需猜測。5.4 測試印證倉庫中有多層測試證據(jù)支撐該能力的行為契約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以服務端最新狀態(tài)為準對關鍵文本必須存在和關鍵表格內容精確一致做一次獨立的回歸斷言。這樣一輪典型的文檔任務只需 34 次模型可見的能力調用見 google-docs 包 README索引發(fā)現(xiàn)、批量單元格寫入、并發(fā)校驗、服務端回讀都由擴展內部完成。實踐建議把校驗項寫成業(yè)務斷言例如合同必須包含甲方條款、預算表第一張表必須與提交的數(shù)據(jù)一致而不是泛泛地讀一遍文檔看看充分利用逐項checks診斷verified: false后先定位passed: false的期望項再決定是補編輯還是結束任務校驗純只讀可在循環(huán)編輯過程中多次調用無需擔心副作用攜帶revision_id進入下一步寫入用writeControl.requiredRevisionId防止并發(fā)編輯導致的狀態(tài)漂移。七、邊界與限制表格是精確匹配而非模糊匹配單元格文本需在去除末尾換行后與期望完全相等任何多余空格、大小寫差異都會導致失敗。作用于第一個 Tab多 Tab 文檔的語義讀取會被歸一化到第一個 Tabverify_document的文本與表格斷言均針對該 Tab 展開。期望規(guī)模有上限文本期望最多 100 條、表格期望最多 20 條、單表最多 100 行 × 20 列超出即參數(shù)錯誤。校驗點即服務端真實狀態(tài)該校驗不依賴任何本地緩存或前序讀取結果適合作為與提供商狀態(tài)對齊的權威斷言。延伸閱讀google-docs 包 README擴展全貌與語義化優(yōu)先的設計取舍verify_document 輸入 schema完整 JSON Schema 契約WASM 客端實現(xiàn) lib.rs能力分發(fā)與 action 參數(shù)約束API 實現(xiàn) api.rs讀取、比對、修訂號與錯誤映射的完整實現(xiàn)類型定義 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 創(chuàng)建、編輯并校驗 Google 文檔IronClaw Google Docs 擴展深度指南讓 Agent 創(chuàng)建、編輯并校驗 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 命令詳解與底層實現(xiàn)gogcli 谷歌文檔原生表格行刪除指南 gog docs table row delete 命令詳解與底層實現(xiàn) 導讀 gog docs table row創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考