IronClaw 的 Google Docs 结构化检查：用 `inspect_document` 精准规划索引化编辑

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载inspect_document是 IronClaw 扩展体系中 Google Docs 集成的语义化只读操作它把一份文档以带文档索引document indexes的段落与表格形式结构化返回供模型在规划索引化编辑indexed edits或处理表格前准确掌握文档结构。读完本文你将掌握该操作的能力边界、输入参数、返回结构、与get_document的取舍以及它在inspect → edit → verify语义工作流中的源码级实现原理。一、inspect_document是什么为“规划编辑”而生的结构化读取在 IronClaw 的 Google Docs 扩展中inspect_document的核心定位是Inspect a Google Docs document as structured paragraphs and tables, including indexes and cell contents.即将文档按“段落 表格”的结构返回并携带每个结构元素的起止索引和表格单元格内容。它面向的是“接下来要按索引做精确编辑”的场景——模型先通过一次调用获得完整的结构化视图据此计算插入、删除、格式化操作所需的具体索引而无需手工猜测索引、也无需创建临时草稿文档去试探do not create scratch documents to infer indexes。该操作由宿主host根据**能力 IDcapability id**自动选择分发对应关系定义在 crates/extensions/packages/google-docs/wasm-src/src/lib.rs 中google-docs.inspect_document Ok(inspect_document),调用时只需要提交输入 schema 中声明的参数不要自行附加action字段——宿主会根据能力 ID 注入 actionparams_with_action会拒绝调用方传入的action字段并返回invalid_parameters错误。二、输入参数仅一个必填字段inspect_document的输入 schema 定义在 crates/extensions/packages/google-docs/schemas/google-docs/inspect_document.input.v1.json参数极其精简字段类型必填约束说明document_idstring是1 ≤ 长度 ≤ 256文档 ID与 Google Drive 文件 ID 相同一个合法的请求体示例{document_id: 1ABCxyz...}该 schema 是语义化操作统一约束的一部分源码中的测试 semantic_input_schemas_bound_document_ids 会逐一校验inspect_document、apply_text_edits、create_table_with_data、verify_document四个语义操作的document_id.maxLength均为 256防止 schema 与 serde 契约漂移。document_id的获取方式与 Drive 文件一致——按 crates/extensions/packages/google-docs/README.md 与 lib.rs 的说明文档 ID 即 Google Drive 文件 ID可借助 google-drive 扩展的list_files查找已有文档。三、返回结构段落、表格、索引与单元格内容inspect_document的执行路径为InspectDocument { document_id }→api::inspect_document→parse_inspection见 api.rs返回结构定义在 types.rs 的InspectDocumentResultpub struct InspectDocumentResult { pub document_id: String, pub title: String, pub revision_id: String, pub body_length: i64, pub elements: VecDocumentElement, // 按文档顺序排列的结构元素 }其中elements的每个元素是一个带kind标签的枚举#[serde(tag kind, rename_all snake_case)] pub enum DocumentElement { Paragraph(ParagraphElement), Table(TableElement), }Paragraph段落ParagraphElement携带start_index、end_index均为 0 基字符偏移、完整text以及可选的named_style如HEADING_1、NORMAL_TEXT、TITLE、SUBTITLE等来自 Docs API 的paragraphStyle.namedStyleType。有了named_style模型无需再逐个字符探测就能识别标题层级这对大纲类编辑至关重要。Table表格TableElement携带表格自身的start_index/end_index以及rows: VecVecTableCell——即按行、按列组织的二维单元格数组。每个TableCell同样带start_index、end_index和text保证模型知道每个单元格在整个文档中的精确字符区间。body_length取自文档 body 最后一个结构元素的endIndex。此外parse_inspection返回的revision_id取自文档读取时的revisionId这也是后续语义编辑见下节进行并发校验的锚点。四、与get_document的分工何时该用哪一个同包的get_document提示词见 get_document.md返回的是元数据标题、revision、body 长度和命名范围named ranges——它不返回段落和表格。两份提示词共同划定了清晰的分工只需要文档元数据、修订号或命名范围 →get_document需要文档结构、段落/表格索引、单元格内容以规划索引化编辑 →inspect_document同时inspect_document的提示词明确要求一次调用返回 provider 结构不要创建草稿文档去推断索引。这是因为该操作内部通过一次GET {document_id}?includeTabsContenttrue拉取完整文档并结构化解析代价远低于建草稿 反复探测的试探式流程。五、语义编辑工作流中的定位inspect → edit → verifyinspect_document是 IronClaw 推荐的四步语义化文档工作流的第一步见 README.mdinspect_document一次调用获取带索引的结构视图用于规划apply_text_edits/create_table_with_data基于文本锚点或表格数据执行受校验的批量修改verify_document从 provider 读回状态逐条核验文本与表格是否符合预期。这套组合把典型的文档操作压缩到 34 次模型可见的能力调用索引发现、批量单元格写入、并发检查、provider 读回全部由扩展内部完成。其中apply_text_edits与inspect_document的配合尤为紧密apply_text_edits的build_anchored_edit_requests会先在本地文本上校验锚点唯一性默认replace_allfalse时锚点必须唯一再生成replaceAllText请求并通过writeControl.requiredRevisionId绑定 inspect 到的修订号防止并发漂移——这正是先用 inspect_document 看清结构、再安全编辑的底层保障。六、索引语义与使用注意事项索引规则遵循 Docs API 的 0 基字符偏移约定以下要点来自 lib.rs 的官方 Tips索引是 0 基字符偏移空文档 body 从索引 0 处的换行符开始因此在索引 1 处插入即可在文档开头追加文本-1表示追加到文档末尾insert_text中index -1走endOfSegmentLocation分支多次编辑时按索引从大到小处理避免索引漂移表格填充正是这样实现的——build_table_population_requests把插入点按索引降序排序后逐条insertText其余低阶操作insert_text、delete_content、format_text、format_paragraph、insert_table、create_list、batch_update等仍作为兼容层与逃生舱保留。另外值得注意fetch_document使用includeTabsContenttrue拉取文档并通过normalize_first_tab将第一个 tab的 body 与 namedRanges 归一化到顶层字段语义读取含 inspect默认作用于第一个 tabapply_text_edits生成请求时还会附加tabsCriteria.tabIds限定到被检查的 tab对应测试 anchored_edits_are_scoped_to_the_inspected_tab。七、源码级解析一次调用内部发生了什么inspect_document的完整链路api.rsfetch_document向https://docs.googleapis.com/v1/documents/{document_id}?includeTabsContenttrue发起GETnormalize_first_tab归一化多 tab 文档使语义读取稳定作用于首个 tabparse_structural_elements遍历body.content命中paragraph元素 → 提取startIndex/endIndex、拼接 text、读取namedStyleType产出Paragraph命中table元素 → 遍历tableRows→tableCells→ 每个单元格递归提取文本与索引产出Table其余元素类型如tableOfContents不进入结构化结果汇总为InspectDocumentResult含document_id、title、revision_id、body_length、elements。上述解析逻辑由单元测试 parse_document_preserves_paragraph_and_table_structure 覆盖验证一份包含HEADING_1段落和两格表格的模拟文档经parse_inspection后elements[0].kind paragraph且named_style HEADING_1elements[1].kind table且rows[0][1].text Ada\n——证明段落样式、表格行列与单元格文本均被无损保留。八、错误处理与权限前提凭证该工具运行在 WASM 沙箱中由宿主注入带 documents 作用域的 Google product-auth 凭证WASM 侧永远接触不到真实 OAuth tokenHTTP 访问范围限定docs.googleapis.com/v1/documents*。401映射为AuthRequired错误码google_api_error_status_401其他非 2xx映射为Client错误码api_status_{status}如api_status_429表示限流消息经bounded_message截断至 512 字符参数校验document_id缺失或超长由 schema 直接拦截调用方携带action字段会得到invalid_parameters。总结inspect_document是 IronClaw Google Docs 扩展中结构化、索引化、一次到位的读取操作它用一次能力调用返回带 0 基字符索引的段落与表格视图让模型在真正动手编辑前就能精确掌握文档结构与索引位置。配合apply_text_edits、create_table_with_data与verify_document即可在 34 次调用内完成检查 → 编辑 → 校验的完整闭环而无需创建草稿文档或低效地反复探测索引。相关源码、schema 与测试位于 crates/extensions/packages/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 Google Docs 扩展 apply_text_edits 实战文本锚定替换的原子化编辑与回读验证IronClaw Google Docs 扩展 apply_text_edits 实战文本锚定替换的原子化编辑与回读验证 本文聚焦 IronClaw 开源仓库人工智能AI 应用交互助手AI AgentIronClaw Google Docs 扩展 replace_text 文本查找替换操作详解IronClaw Google Docs 扩展 replace_text 文本查找替换操作详解 在 IronClaw 的 Google Docs 扩展 goo人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考