企业官网建设流程全解析

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

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）根据**能力 ID（capability id）**自动选择分发，对应关系定义在 crates/extensions/packages/google-docs/wasm-src/src/lib.rs 中：

"google-docs.inspect_document" => Ok("inspect_document"),

调用时只需要提交输入 schema 中声明的参数，不要自行附加action字段——宿主会根据能力 ID 注入 action（params_with_action会拒绝调用方传入的action字段并返回invalid_parameters错误）。

二、输入参数：仅一个必填字段

inspect_document的输入 schema 定义在 crates/extensions/packages/google-docs/schemas/google-docs/inspect_document.input.v1.json，参数极其精简：

一个合法的请求体示例：

{"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 的InspectDocumentResult：

pub struct InspectDocumentResult { pub document_id: String, pub title: String, pub revision_id: String, pub body_length: i64, pub elements: Vec<DocumentElement>, // 按文档顺序排列的结构元素 }

其中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: Vec<Vec<TableCell>>——即按行、按列组织的二维单元格数组。每个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}?includeTabsContent=true拉取完整文档并结构化解析，代价远低于"建草稿 + 反复探测"的试探式流程。

五、语义编辑工作流中的定位：inspect → edit → verify

inspect_document是 IronClaw 推荐的四步语义化文档工作流的第一步（见 README.md）：

1. inspect_document：一次调用获取带索引的结构视图，用于规划；
2. apply_text_edits/create_table_with_data：基于文本锚点或表格数据执行受校验的批量修改；
3. verify_document：从 provider 读回状态，逐条核验文本与表格是否符合预期。

这套组合把典型的文档操作压缩到 3～4 次模型可见的能力调用，索引发现、批量单元格写入、并发检查、provider 读回全部由扩展内部完成。

其中apply_text_edits与inspect_document的配合尤为紧密：apply_text_edits的build_anchored_edit_requests会先在本地文本上校验锚点唯一性（默认replace_all=false时锚点必须唯一），再生成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使用includeTabsContent=true拉取文档，并通过normalize_first_tab将第一个 tab的 body 与 namedRanges 归一化到顶层字段，语义读取（含 inspect）默认作用于第一个 tab；apply_text_edits生成请求时还会附加tabsCriteria.tabIds限定到被检查的 tab（对应测试 anchored_edits_are_scoped_to_the_inspected_tab）。

七、源码级解析：一次调用内部发生了什么

inspect_document的完整链路（api.rs）：

1. fetch_document向https://docs.googleapis.com/v1/documents/{document_id}?includeTabsContent=true发起GET；
2. normalize_first_tab归一化多 tab 文档，使语义读取稳定作用于首个 tab；
3. parse_structural_elements遍历body.content：
   • 命中paragraph元素 → 提取startIndex/endIndex、拼接 text、读取namedStyleType，产出Paragraph；
   • 命中table元素 → 遍历tableRows→tableCells→ 每个单元格递归提取文本与索引，产出Table；
   • 其余元素类型（如tableOfContents）不进入结构化结果；
4. 汇总为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_1"，elements[1].kind == "table"且rows[0][1].text == "Ada\n"——证明段落样式、表格行列与单元格文本均被无损保留。

八、错误处理与权限前提

• 凭证：该工具运行在 WASM 沙箱中，由宿主注入带 documents 作用域的 Google product-auth 凭证，WASM 侧永远接触不到真实 OAuth token；HTTP 访问范围限定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，即可在 3～4 次调用内完成"检查 → 编辑 → 校验"的完整闭环，而无需创建草稿文档或低效地反复探测索引。相关源码、schema 与测试位于 crates/extensions/packages/google-docs 包内，可供进一步深入研读。

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