IronClaw 扩展实战：深入解析 google-docs `insert_text` 文本插入能力的参数契约与实现原理

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

本文以 IronClaw 开源仓库中 google-docs 扩展包的insert_text能力为核心，讲解该能力如何通过「提示文档 + JSON Schema 输入契约」驱动模型调用 Google Docs API 完成文本插入。读者将掌握insert_text的完整参数语义（含index与segment_id的边界行为）、能力注册与凭据注入机制、WASM 端底层实现原理，以及正确的调用方式与常见错误处理。

一、能力定位：insert_text在 google-docs 扩展中的角色

IronClaw 的 google-docs 扩展（包目录）是一个data-only 扩展包：不包含独立 crate，可移植的工具半部分以 WASM guest 形式交付，产物固化在wasm/google_docs_tool.wasm，guest 源码位于 wasm-src。该包以扩展 IDgoogle-docs注册，共暴露 15 个工具能力，由 manifest.toml 统一声明。

insert_text是其中最基本的低层文本写入能力，其工具 ID 为google-docs.insert_text。在 manifest 中它被声明为：

• effects = ["network", "use_secret", "external_write"]：会发起网络请求、使用密钥（OAuth 凭据）并产生外部写入；
• default_permission = "ask"：默认情况下需要用户确认；
• visibility = "model"：该能力仅向模型可见；
• 凭据由 host 注入：以Authorization: Bearer <token>请求头形式附加到docs.googleapis.com，携带https://www.googleapis.com/auth/documents写权限 scope（见 manifest.toml）。

值得注意的是，google-docs 包同时提供inspect_document、apply_text_edits、create_table_with_data、verify_document等语义化高层能力。包 README（README.md）建议日常文档编辑优先使用语义能力，而insert_text这类基于索引的低层操作则保留为兼容与兜底手段，用于不支持语义流程的边界场景。

二、调用契约：按 Schema 传参，绝不携带action字段

insert_text的提示文档（即本主题关联文档 insert_text.md）全文只有两条核心约定：

1. 功能：在文档的某个位置插入文本（Insert text at a document position）；
2. 调用方式：宿主（host）根据能力 ID（capability id）选择本操作，模型只能提供输入 Schema 描述的参数，不得包含action字段。

第二条约定的背后是 IronClaw 扩展调用模型的设计：一个 WASM 工具对应多个能力（capability），宿主通过ToolContext.capability_id告诉 guest 本次要执行哪个操作，guest 再把 capability id 映射为内部 action。以google-docs.insert_text为例，映射发生在 lib.rs 的action_from_context中：

match context.capability_id.as_str() { "google-docs.insert_text" => Ok("insert_text"), ... }

随后params_with_action（lib.rs）会把 action 名称注入到请求参数里——如果调用方擅自传入action字段，guest 会直接返回invalid_parameters错误，并有专门的单元测试params_with_action_rejects_caller_supplied_action加以锁定（见 lib.rs）。这正是「不要包含 action 字段」这一约定的源码级保障：action 由宿主依据能力 ID 决定，模型只需关注业务参数。

三、输入 Schema 全解：四个参数与默认值语义

insert_text的输入契约由 JSON Schema 文件 insert_text.input.v1.json 定义，其required数组仅要求document_id与text，其余两个参数可选：

{ "type": "object", "required": ["document_id", "text"], "properties": { "document_id": { "type": "string", "description": "The document ID." }, "text": { "type": "string", "description": "Text to insert." }, "index": { "type": "integer", "description": "Character index. Defaults to -1 to append." }, "segment_id": { "type": "string", "description": "Segment ID. Defaults to body." } }, "additionalProperties": false }

对照 WASM 侧的类型定义 types.rs，四个参数语义如下：

注意 Schema 中的additionalProperties: false：调用方传入任何未声明字段都会被拒。index与segment_id的默认值在 Rust 侧由#[serde(default = "default_insert_index")]（index默认-1）与#[serde(default)]（segment_id默认空串）落实。

四、源码级实现：insert_text如何翻译为 Docs API 请求

核心实现在 api.rs 的pub fn insert_text函数中。它根据index取值分三种分支构造insertText请求：

1. index == -1（追加模式）：构造endOfSegmentLocation定位器——若segment_id非空则附带segmentId，表示「插入到该段（默认正文）的末尾」：

serde_json::json!({ "insertText": { "text": text, "endOfSegmentLocation": loc, } })

2. index < 0且不等于-1（非法）：直接返回ErrorKind::Input、错误码invalid_index，提示「仅接受 -1（追加）或非负索引」。对应单元测试insert_text_rejects_negative_indexes_other_than_append（api.rs）。

3. index >= 0（定点插入）：构造location定位器（同样按需附带segmentId），在指定 0-based 字符索引处插入：

serde_json::json!({ "insertText": { "text": text, "location": { "index": index, "segmentId": ... }, } })

无论哪种分支，最终都通过batch_update_raw以POST {document_id}:batchUpdate发送到https://docs.googleapis.com/v1/documents（API 基址常量见 api.rs），并解析响应返回UpdateResult：

pub struct UpdateResult { pub document_id: String, pub revision_id: String, }

返回体包含文档 ID 与更新后的revision_id——后者可继续作为后续apply_text_edits/create_table_with_data等操作的requiredRevisionId写控制依据，用于并发冲突检测。

关于索引的实践要点（来自 guest 文档注释，lib.rs）

• 索引是0-based 字符偏移；
• 空文档正文起始处有一个位于 index 0 的换行符，因此要在文档开头前置文本，应插入到 index 1；
• 使用-1即可追加到文档末尾，无需关心当前长度；
• 一次执行多处编辑时，建议从最高索引向最低索引处理，避免索引随插入而漂移错位。

五、安全与错误模型：凭据隔离与稳定错误码

insert_text的 API 调用全部经由 host 的 HTTP 能力完成（host::http_request），WASM guest永远接触不到真实的 OAuth token——凭据注入、限流由宿主统一处理（见 api.rs 的模块注释）。这保证了扩展的「最小权限」原则：即使 guest 被攻破，也无法窃取凭据。

错误处理上，guest 返回带稳定错误码的GuestFailure：

• 参数非法（如非法index、调用方携带action）→ErrorKind::Input；
• Google API 返回 401 →ErrorKind::AuthRequired，错误码google_api_error_status_401（对应 api.rs）；
• 其余非 2xx 状态码 →ErrorKind::Client，错误码api_status_<code>（如api_status_429表示限流）；
• 网络被拒/传输失败 → 按HttpErrorKind映射为NetworkDenied/OperationFailed等（见transport_failure，api.rs）。

同时，guest 侧的 free-text 错误消息会被裁剪到 512 字符以内（bounded_message），避免超长字符串进入宿主日志链路。

六、一次完整调用示例

综合以上契约，一次在文档开头插入标题的合法调用参数如下（模型只需给出业务参数，action由宿主依据google-docs.insert_text能力 ID 注入）：

{ "document_id": "abc123", "text": "Hello World\n", "index": 1 }

追加到文档末尾则可省略index（默认-1）：

{ "document_id": "abc123", "text": "Appended line\n" }

若要向页眉/页脚等非正文分段插入，则补充segment_id：

{ "document_id": "abc123", "text": "Confidential", "index": 0, "segment_id": "kix.header-id" }

执行成功后返回：

{ "document_id": "abc123", "revision_id": "<最新修订ID>" }

七、验证与质量保障

google-docs 包的 manifest 投影由cargo test -p ironclaw_extension_registry校验，WASM 产物新鲜度由python3 scripts/ci/check-wasm-artifact-freshness.py检查（见 README.md）。针对insert_text的参数合法性，WASM 源码内置了insert_text_rejects_negative_indexes_other_than_append单元测试（api.rs），确保「仅 -1 或非负索引」的契约不会被未来改动破坏。读者可沿 wasm-src 与 schemas/google-docs 两个目录继续深入，对照 Schema 与实现理解其余 14 个能力的同类约定。

小结

insert_text虽是一个低层能力，却完整体现了 IronClaw 扩展体系的核心设计：能力 ID 驱动的操作选择、Schema 驱动的参数契约、宿主统一注入凭据的零信任边界、以及带稳定错误码的失败模型。理解它的参数语义（index的-1追加约定、segment_id的分段定位）与实现路径，是掌握整个 google-docs 包乃至编写自定义 WASM 扩展的基础。

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