在 IronClaw 中向 Google Slides 形状插入文本：google-slides 扩展 insert_text 能力深度解析

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文以 IronClaw 仓库中 google-slides 扩展的能力提示文档 insert_text.md 为核心结合其输入 Schema、WASM 实现与 Manifest 配置完整讲解如何在 Agent 会话中安全、正确地调用google-slides.insert_text工具向幻灯片形状插入文本。读完本文你将掌握该能力提示词的契约语义、四个输入参数的取值规则、从参数到 Google Slides APIbatchUpdate请求的底层调用链以及权限、凭据与错误处理机制可直接在 IronClaw 的扩展生态中落地演示文稿自动填充类实战方案。一、能力定位一份最小提示词背后的工具契约关联文档全文仅三句话却是理解整个 google-slides 扩展运行模型的关键Insert text into a shape.The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.这三句话定义了该工具的提示词契约prompt contract对应三个硬性规则能力由宿主按 capability id 选择模型不需要也不允许自行声明我要执行哪个操作。宿主在调用时把 invocation context 注入 WASM 工具工具从 context 中读取capability_id如google-slides.insert_text并映射为内部动作名。见 lib.rs 中的action_from_context14 个 capability id 与动作名一一对应未知 id 返回unsupported_google_slides_capability的 Input 错误。只提供输入 Schema 描述的参数模型输出参数时工具侧会对参数做serde_json反序列化任何未知字段或类型不匹配都会触发invalid_parameters的 Input 类失败。禁止携带 action 字段这是最容易踩的坑。params_with_actionlib.rs会在参数中检测action键——如果模型自己塞了action字段工具会直接返回invalid_parameters错误并拒绝执行。动作名只能由宿主从 capability id 推导并注入这与 types.rs 中#[serde(tag action, rename_all snake_case)]的反序列化约定配合防止模型越权选择能力。这种提示词只描述意图、不承载分发逻辑的设计正是 IronClaw 扩展体系统一模型的一部分manifest 编译为解析后的记录宿主负责能力选择与参数校验工具保持无状态、无感知。二、输入 Schema 全参数解读insert_text工具的输入参数定义在 insert_text.input.v1.json采用 JSON Schema draft-07参数类型必填说明presentation_idstring是演示文稿 ID与 Google Drive 文件 ID 相同object_idstring是目标形状/文本框的对象 IDtextstring是要插入的文本内容insertion_indexinteger否字符索引0 基默认0即插入到形状文本开头值得注意的细节required数组严格限定presentation_id、object_id、text三个字段缺一不可insertion_index是唯一可选参数缺省为 0——因此向文本框末尾追加内容时需要先通过get_presentation读取当前文本长度再计算索引或用batch_update组合请求additionalProperties: false意味着 Schema 之外的任何参数都会在宿主校验或工具反序列化阶段被拒绝保证提示词只描述 Schema 参数的约束是强约束而非建议。对应地WASM 侧的类型定义在 types.rs 的InsertText变体中presentation_id、object_id、text为必填Stringinsertion_index使用#[serde(default)]默认为0。Schema 与 serde 契约通过schemars::JsonSchema派生保持一致见schema()方法防止广告 Schema 与解析代码漂移。三、WASM 实现从参数到 Google Slides API 请求工具本体是编译为 WASM 的 guest源码位于 api.rs。insert_text的实现非常直观api.rspub fn insert_text( presentation_id: str, object_id: str, text: str, insertion_index: i64, ) - ResultUpdateResult, GuestFailure { let request serde_json::json!({ insertText: { objectId: object_id, text: text, insertionIndex: insertion_index, } }); let parsed batch_update_raw(presentation_id, vec![request])?; Ok(UpdateResult { presentation_id: parsed[presentationId].as_str().unwrap_or().to_string(), created_object_id: None, }) }底层调用链可以拆解为四步构造请求体insert_text将三个参数包装为 Google Slides API 的insertText请求对象。注意这里复用的是batchUpdate接口——它把insertText包在requests数组中batch_update_rawapi.rsPOST 到https://slides.googleapis.com/v1/presentations/{presentation_id}:batchUpdate。宿主 HTTP 能力代理WASM 工具并不直接持有 OAuth 令牌而是调用宿主注入的host::http_request。凭证注入、限流全部由宿主完成工具永远看不到真实令牌源码注释明确说明这一点api.rs。这正是 IronClaw 隐私优先架构在扩展层的体现。响应处理batch_update_raw将响应 JSON 反序列化insert_text从中提取presentationId返回UpdateResult。由于 insertText 不创建新对象created_object_id恒为None。URL 编码presentation_id经过url_encodeapi.rs后拼入路径避免特殊字符破坏 URL 结构。四、Manifest 中的权限与凭据配置工具能安全地写入外部系统靠的是 manifest.toml 中的声明式配置insert_text 工具段[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-slides.insert_text description Insert text into a shape. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-slides/insert_text.input.v1.json prompt_doc_ref prompts/google-slides/insert_text.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/presentations] audience { scheme https, host slides.googleapis.com } injection { type header, name authorization, prefix Bearer }四个关键配置项的语义origin_gate_matrixinsert_text属于写操作在loop_run来源下默认gated_unless_granted未获授权时需门禁审批在product和automation来源下直接forbidden。这与get_presentation/get_thumbnail等只读工具仅声明network、use_secret效果形成对比写操作的暴露面被严格收窄。effects声明network发起网络请求、use_secret使用凭据、external_write对外部系统产生写入是宿主进行效果审计与策略判定的依据。default_permission ask首次调用需用户/审批者确认结合门禁矩阵构成双层防护。credentials声明凭据句柄google_runtime_token、vendorgoogle、OAuth scopehttps://www.googleapis.com/auth/presentations并以Authorization: Bearer token头注入到slides.googleapis.com。注意写操作用的是非只读 scope而get_presentation/get_thumbnail用的是presentations.readonly——最小权限原则在工具级粒度上生效。OAuth 流程本身也由 manifest 的[auth.google]段声明PKCE S256、offline access、keepalive_idle_seconds 604800的刷新保活模型与工具都不接触令牌生命周期。五、完整实战流程从创建演示文稿到插入文本官方源码在 lib.rs 给出了推荐的组合路径To add text to a slide: first create_shape (TEXT_BOX), then insert_text into the returned object_id.标准流程为五步create_presentation创建空白演示文稿取得presentation_idcreate_slide添加幻灯片layout缺省为BLANKcreate_shape在幻灯片上创建文本框shape_type缺省为TEXT_BOX从返回值取得object_idinsert_text向该文本框写入文本insertion_index缺省 0即从开头插入可选format_text设置加粗、字号、字体、颜色等样式。对应的一组实际可用的调用参数示例对应 lib.rs 中的文档示例{presentation_id: abc123, title: Q1 Report} {presentation_id: abc123, layout: TITLE_AND_BODY} {presentation_id: abc123, slide_object_id: slide1, shape_type: TEXT_BOX, x: 50, y: 50, width: 300, height: 40} {presentation_id: abc123, object_id: shape1, text: Hello World} {presentation_id: abc123, object_id: shape1, bold: true, font_size: 24}需要注意的坐标系约定位置与尺寸使用**点points**为单位1 英寸 72 点标准幻灯片为 720×405 点10×5.625 英寸WASM 侧在create_shape时会把点换算为 EMU1 点 12700 EMU见 api.rs 的pt_to_emu。演示文稿 ID 与 Google Drive 文件 ID 相同可以用 google-drive 扩展的list_files按名称检索已有演示文稿。六、错误处理与可观测性insert_text的错误处理沿用了整个扩展统一的GuestFailure模型api.rs401 未授权映射为ErrorKind::AuthRequired错误码固定为google_api_error_status_401——这是可恢复错误宿主收到后会触发令牌刷新或重新认证流程2xx 之外的其它状态如 429 限流、4xx/5xx映射为ErrorKind::Client错误码为api_status_{status}消息体包含状态码与响应原文网络层失败由transport_failure按HttpErrorKind映射为对应的AuthRequired/Input/OutputTooLarge/Executor/NetworkDenied/Client/OperationFailedJSON 反序列化失败serialization_failure归为ErrorKind::Executor的serialization_failed。上述分类均有单元测试背书例如 api.rs 测试模块 验证了 401 → AuthRequired、非 401 → Client 的映射。此外工具在每次 API 调用前通过host::log(LogLevel::Debug, ...)记录方法与 URLapi.rs便于链路追踪所有错误消息经bounded_message截断到 512 字符api.rs防止无限长消息外泄。七、延伸同一扩展中的文本编辑工具族insert_text并非孤立存在google-slides 扩展共提供 14 个工具见 README.md与文本操作直接相关的还有delete_text按FIXED_RANGE或FROM_START_INDEX范围删除形状内文本replace_all_text跨整个演示文稿查找替换返回occurrences_changed计数format_text设置加粗/斜体/下划线/字号/字体/前景色颜色为#RRGGBB十六进制内部解析为 RGB 浮点batch_update一次性原子执行多条原始 Slides API 请求复杂多步编辑的终极兜底。这些工具共享同一套提示词契约host selects this operation from the capability id; do not include an action field、同一份 OAuth 凭据体系google_runtime_tokenpresentationsscope和同一套错误映射。模板化工作流如先建含占位符文本的形状再用replace_all_text或replace_shapes_with_image批量替换正是这套工具族的设计意图见 lib.rs。八、验证与质量保障该扩展包是纯数据包data-only无独立 crate工具以 WASM guest 形式交付。其质量保障来自两条链路manifest 投影测试cargo test -p ironclaw_extension_registry验证 manifest 能被正确解析投影README 中明确列出WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py将提交的wasm/google_slides_tool.wasm与wasm-src/源码树摘要绑定修改 guest 源码而不重建产物会导致 CI 失败——这保证了文档与实现、产物与源码的一致性。此外google-slides 与 gmail、google-docs 等共享vendor.google凭据组OAuth client id/secret 由部署方通过 manifest.toml 的[admin_configuration]配置扩展的家族模型与包目录规则可进一步参考 crates/extensions/AGENTS.md。结语insert_text提示词虽短却是 IronClaw 扩展架构的一个缩影宿主按 capability id 分发能力、Schema 约束参数、WASM guest 无凭据直连、manifest 声明权限与效果。掌握提示词 Schema Manifest 实现四层契约你就能在 IronClaw 中安全地构建从创建演示文稿到批量填充文本的完整自动化能力。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Slides 扩展深度解析delete_text 工具从形状中删除文本的实现与实战IronClaw Google Slides 扩展深度解析delete_text 工具从形状中删除文本的实现与实战 在 IronClaw 的 Google S人工智能AI 应用交互助手AI Agentgogcli gog slides insert-text 实战指南向 Google Slides 形状与表格单元格插入文本gogcli gog slides insert text 实战指南向 Google Slides 形状与表格单元格插入文本 本文以 gogcli 项目GoIronClaw Google Slides 扩展用 replace_shapes_with_image 将占位形状批量替换为图片IronClaw Google Slides 扩展用 replace_shapes_with_image 将占位形状批量替换为图片 在 IronClaw 的人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考