人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文以 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.wasmguest 源码位于 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等语义化高层能力。包 READMEREADME.md建议日常文档编辑优先使用语义能力而insert_text这类基于索引的低层操作则保留为兼容与兜底手段用于不支持语义流程的边界场景。二、调用契约按 Schema 传参绝不携带action字段insert_text的提示文档即本主题关联文档 insert_text.md全文只有两条核心约定功能在文档的某个位置插入文本Insert text at a document position调用方式宿主host根据能力 IDcapability 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_actionlib.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四个参数语义如下参数类型必填默认值语义document_idstring是—目标文档 ID与 Google Drive 文件 ID 相同textstring是—要插入的文本内容indexinteger否-1追加插入位置0-based 字符索引-1表示追加到段尾segment_idstring否空字符串正文 body目标分段 ID空表示文档正文注意 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请求index -1追加模式构造endOfSegmentLocation定位器——若segment_id非空则附带segmentId表示「插入到该段默认正文的末尾」serde_json::json!({ insertText: { text: text, endOfSegmentLocation: loc, } })index 0且不等于-1非法直接返回ErrorKind::Input、错误码invalid_index提示「仅接受 -1追加或非负索引」。对应单元测试insert_text_rejects_negative_indexes_other_than_appendapi.rs。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/documentsAPI 基址常量见 api.rs并解析响应返回UpdateResultpub 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_requestWASM guest永远接触不到真实的 OAuth token——凭据注入、限流由宿主统一处理见 api.rs 的模块注释。这保证了扩展的「最小权限」原则即使 guest 被攻破也无法窃取凭据。错误处理上guest 返回带稳定错误码的GuestFailure参数非法如非法index、调用方携带action→ErrorKind::InputGoogle API 返回 401 →ErrorKind::AuthRequired错误码google_api_error_status_401对应 api.rs其余非 2xx 状态码 →ErrorKind::Client错误码api_status_code如api_status_429表示限流网络被拒/传输失败 → 按HttpErrorKind映射为NetworkDenied/OperationFailed等见transport_failureapi.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【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI AgentIronClaw 扩展开发指南深入理解 github.list_issue_comments 工具的参数契约、URL 解析与认证机制IronClaw 扩展开发指南深入理解 github.list_issue_comments 工具的参数契约、URL 解析与认证机制 github.list_人工智能AI 应用交互助手AI AgentIronClaw 扩展开发指南google-calendar.list_calendars 日历发现能力的原理与实战IronClaw 扩展开发指南 google calendar.list_calendars 日历发现能力的原理与实战 本文围绕 IronClaw 开源仓库中人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考