IronClaw Google Slides 扩展：用 replace_shapes_with_image 将占位形状批量替换为图片

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载在 IronClaw 的 Google Slides 扩展extension idgoogle-slides中replace_shapes_with_image是一个面向模板驱动批量出片场景的原子操作它按文本内容匹配演示文稿中的形状并将所有命中形状替换为指定图片。本文以该操作的 prompt 文档replace_shapes_with_image.md为核心结合其输入 Schema、WASM 实现与清单声明讲清它的能力语义、参数契约、调用约束与底层实现帮助你在自动化幻灯片生成、模板填充类 Agent 工作流中正确使用它。操作定位模板化替换而非精确对象编辑在 Google Slides 扩展的 14 个工具中replace_shapes_with_image属于按内容寻址的一类操作——它不要求你预先知道某个形状的objectId而是通过文本内容find在整个演示文稿范围内定位形状。这与insert_image需要指定slide_object_id和坐标尺寸在 api.rs 中通过createImage请求实现形成互补insert_image精确插入一张新图片需要指定目标幻灯片与位置尺寸replace_shapes_with_image把已有的、带特定文本的形状整体替换为图片适合占位图 → 真实图的批处理。从 manifest.toml 的声明看它的能力描述为 Replace matching shapes with an image.visibility model对模型可见、default_permission ask默认需用户授权确认并声明了network、use_secret、external_write三类效果即会发起外部网络请求、使用 Google 凭据、并对外部资源产生写操作。输入契约四个参数与默认值该操作的输入参数由独立的 JSON Schema 文件定义replace_shapes_with_image.input.v1.json。以下是完整参数表参数类型是否必填说明presentation_idstring✅ 必填演示文稿 ID与 Google Drive 文件 ID 相同findstring✅ 必填用于匹配形状的文本内容image_urlstring✅ 必填替换图片的 URL需可公开访问match_caseboolean可选是否区分大小写匹配默认trueSchema 同时设置additionalProperties: false意味着传入任何未声明的字段都会被拒绝这是工具参数校验的硬边界。关键默认值在 types.rs 的 Rust 枚举定义中再次确认match_case通过#[serde(default default_true)]实现即模型不传时按区分大小写处理。需要忽略大小写匹配时应显式传入match_case: false。调用规则由 capability id 驱动禁止携带 action 字段prompt 文档明确了两条调用规则二者在源码中均有对应的强制校验操作由 host 从 capability id 选择。WASM 入口在 lib.rs 的action_from_context中将调用上下文里的capability_id如google-slides.replace_shapes_with_image映射为内部 action 名replace_shapes_with_image未知的 capability id 会返回unsupported_google_slides_capability错误。只提供 input schema 描述的参数不要包含action字段。在params_with_action中如果调用方参数里显式携带action字段会直接返回invalid_parameters错误该行为有专门单测覆盖见 lib.rs 中的params_with_action_rejects_caller_supplied_action。action由 host 依据 capability id 注入调用方自行指定会导致歧义甚至越权操作因此被严格禁止。一个符合契约的调用参数示例由模型侧生成host 会自动注入 action{ presentation_id: 1AbC...def, find: [LOGO], image_url: https://example.com/logo.png, match_case: true }底层实现一次 batchUpdate 完成全量替换replace_shapes_with_image的实现位于 api.rs 的replace_shapes_with_image函数中。它不逐个遍历元素而是构造一个replaceAllShapesWithImage请求通过batchUpdate端点一次性提交{ replaceAllShapesWithImage: { containsText: { text: find, matchCase: match_case }, imageUrl: image_url, imageReplaceMethod: CENTER_INSIDE } }值得注意的实现细节匹配语义containsText意味着只要形状文本包含find内容即命中非全等匹配这与占位符场景高度契合——例如形状文本为[COMPANY]用find: [COMPANY]即可命中图片填充方式imageReplaceMethod固定为CENTER_INSIDE即图片在保持纵横比的前提下居中放入形状区域既不会裁切也不会变形拉伸返回值函数从 API 响应中提取replies[0].replaceAllShapesWithImage.occurrencesChanged返回ReplaceResult含presentation_id与occurrences_changed。occurrences_changed可用于验证替换是否真正生效——若为 0说明没有形状命中find文本。所有网络请求都经 host 的 HTTP capability 发出基地址https://slides.googleapis.com/v1/presentationsWASM 侧永远看不到 OAuth 令牌本体凭据由 host 按 manifest 中声明的google_runtime_token注入authorization请求头。权限、凭据与失败语义在 manifest.toml 中本工具对应的凭据声明要求scopes [https://www.googleapis.com/auth/presentations]读写级audience指向slides.googleapis.com。由于default_permission ask每次执行都会触发用户授权确认loop_run场景为gated_unless_grantedproduct与automation场景直接forbidden即仅限 Agent 循环内使用。失败处理遵循统一的 api.rs 错误映射HTTP 401 →AuthRequired错误码google_api_error_status_401凭据失效或 scope 不足触发重新授权流程其他非 2xx 状态码 →Client类错误错误码形如api_status_429限流、api_status_404演示文稿不存在或图片 URL 无法访问等本地参数非法 →Input类错误错误码invalid_parameters。典型工作流占位形状 → 真实图片该操作最典型的应用是模板填充工作流IronClaw 的 lib.rs 文档注释给出了完整思路用create_shape在模板上创建带占位文本的形状如TEXT_BOX中输入[LOGO]用get_presentation确认演示文稿与元素状态准备真实图片的公开 URL调用replace_shapes_with_image一次性替换所有命中的占位形状通过返回的occurrences_changed校验替换数量是否符合预期。与配套的replace_all_text文本级查找替换、batch_update多操作原子提交组合即可搭建模板 → 填文本 → 换图片的完整自动出片管线。扩展的整体安装与授权流程可参考 docs/extensions/google/slides.md先完成 Google OAuth 设置然后执行ironclaw extension install google-slides与ironclaw extension activate google-slides完成授权。注意即使已经授权过其他 Google 扩展仍需对 Slides 扩展单独完成一次授权。小结replace_shapes_with_image是一个把按文本匹配形状 整页替换为图片封装为单个能力点的工具参数契约精简3 个必填 1 个可选、调用规则明确capability id 驱动、禁止自带action字段、底层以单次replaceAllShapesWithImagebatchUpdate 原子完成全量替换并回报替换计数。在 IronClaw 的 Google Slides 扩展中它是模板化演示文稿自动化最直接的一环可与create_shape、replace_all_text、batch_update组合成完整的占位填充工作流。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐Google Slides 模板占位符自动替换gogcli slides create-from-template 实战指南Google Slides 模板占位符自动替换gogcli slides create from template 实战指南 gog slides creatIronClaw Google Calendar 扩展指南使用 google-calendar.add_attendees 为日历事件批量添加与会者IronClaw Google Calendar 扩展指南使用 google calendar.add_attendees 为日历事件批量添加与会者 导读 g人工智能AI 应用交互助手AI AgentIronClaw Google Docs 扩展 replace_text 文本查找替换操作详解IronClaw Google Docs 扩展 replace_text 文本查找替换操作详解 在 IronClaw 的 Google Docs 扩展 goo人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考