ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

IronClaw Google Slides 扩展指南:create_shape 能力契约、输入参数与 WASM 实现解析

IronClaw Google Slides 扩展指南:create_shape 能力契约、输入参数与 WASM 实现解析 人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载在 IronClaw 的扩展体系中google-slides是一个以数据包data-only package形式交付的 Google Slides 扩展通过 WASM 访客guest在宿主沙箱内调用 Google Slides API。create_shape.md 正是该能力capability面向宿主与 LLM 的操作契约文档它声明了「在幻灯片上创建形状或文本框」这一原子操作并规定了调用的关键纪律——宿主根据 capability id 选择操作调用方只提供输入 schema 描述的参数不得携带 action 字段。读完本文你将掌握google-slides.create_shape的完整参数契约、坐标与尺寸换算规则、底层 batchUpdate 请求构造以及它在 IronClaw 扩展宿主中的分发与鉴权流程可直接用于为 Agent 编排「建页 → 建形状 → 写文本 → 排版」的演示文稿自动化流水线。一、prompt 文档定位capability 契约而非自由文本提示词create_shape.md全文虽短却精确界定了它在扩展体系中的角色Create a shape or text box.The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.这句话包含三层契约语义操作由宿主按 capability id 分发LLM 或调用方不会在参数里声明我要执行 create_shape而是由宿主根据已授权的能力标识capability idgoogle-slides.create_shape把请求路由到对应实现参数以输入 schema 为准所有可传字段、必填项、类型与取值范围都定义在 create_shape.input.v1.jsonprompt 文档本身不重复罗列禁止携带 action 字段这是防注入的关键约束——操作名由宿主注入调用方伪造 action 会被直接拒绝详见下文源码佐证。在 IronClaw 中每个工具tool都同时拥有prompt_doc_ref面向模型的能力说明与input_schema_ref面向参数校验的 JSON Schema二者通过 manifest.toml 关联。这种「prompt 与 schema 分离」的设计让模型理解与机器校验各司其职也正是 create_shape 这种简短 prompt 能支撑完整能力的根本原因。二、create_shape 输入参数契约字段、必填项与默认值create_shape.input.v1.json 是create_shape参数的权威定义采用 JSON Schema draft-07。核心约束如下参数类型必填说明presentation_idstring是演示文稿 ID与 Google Drive 文件 ID 相同slide_object_idstring是目标幻灯片页面的 object IDxnumber是形状左上角 X 坐标单位点ptynumber是形状左上角 Y 坐标单位点ptwidthnumber是形状宽度单位点ptheightnumber是形状高度单位点ptshape_typestring否形状类型默认TEXT_BOX两个容易被忽略的细节additionalProperties: falseschema 明确禁止未声明的额外字段。调用方传入 schema 之外的键例如手滑写入color、rotation会在参数校验阶段被拒绝而不是被静默忽略。shape_type的取值空间schema 只给出默认值TEXT_BOX而完整允许值由 types.rs 中的 Rust 契约注释给出包括TEXT_BOX、RECTANGLE、ROUND_RECTANGLE、ELLIPSE默认函数default_shape_type()返回TEXT_BOX。也就是说不传shape_type时创建的是一个可直接承载文本的文本框传矩形/椭圆等几何形状时同样可以随后插入文本。一个最小可用的调用参数示例{ presentation_id: 1AbC...DriveFileId, slide_object_id: p1, shape_type: TEXT_BOX, x: 50, y: 50, width: 300, height: 40 }三、坐标与尺寸为什么用「点」以及如何换算create_shape的四个几何参数全部以**点points, pt**为单位。这是 Google Slides API 的页面级单位约定IronClaw 的 WASM 实现 api.rs 在构造请求时通过pt_to_emu将其换算为 Slides API 内部使用的 EMUEnglish Metric Units/// Points to EMU (English Metric Units). 1 point 12700 EMU. fn pt_to_emu(pt: f64) - f64 { pt * 12700.0 }换算关系与实用基准1 点 12700 EMU1 英寸 72 点标准幻灯片尺寸为 720 × 405 点即 10 × 5.625 英寸这是 IronClaw 在 lib.rs 的 Tips 中明确给出的设计基准用于估算形状的合理摆位换算后的size与transform均以EMU为单位提交且transform固定为scaleX/scaleY 1.0、shearX/shearY 0.0、仅平移translateX/translateY的纯平移矩阵。也就是说调用方始终以「点」这一对人类和模型都友好的单位工作底层换算完全由工具完成无需关心 EMU。四、底层实现一次 createShape batchUpdate 请求的完整构造create_shape不是独立的 REST 端点而是通过 Google Slides API 的presentations/{id}:batchUpdate批量更新端点执行。核心实现在 api.rspub fn create_shape( presentation_id: str, slide_object_id: str, shape_type: str, x: f64, y: f64, width: f64, height: f64, ) - ResultUpdateResult, GuestFailure { let request serde_json::json!({ createShape: { shapeType: shape_type, elementProperties: { pageObjectId: slide_object_id, size: { width: { magnitude: pt_to_emu(width), unit: EMU }, height: { magnitude: pt_to_emu(height), unit: EMU }, }, transform: { scaleX: 1.0, scaleY: 1.0, shearX: 0.0, shearY: 0.0, translateX: pt_to_emu(x), translateY: pt_to_emu(y), unit: EMU, }, }, } }); let parsed batch_update_raw(presentation_id, vec![request])?; // replies[0].createShape.objectId 即新形状的 object ID ... }请求结构的要点elementProperties.pageObjectId即参数中的slide_object_id把形状锚定到目标幻灯片size由width/height换算而来transform由x/y换算而来二者共同决定形状的位置与大小响应通过replies[0][createShape][objectId]取出新创建形状的 object ID封装进UpdateResult含presentation_id与可选的created_object_id返回给调用方——这个 object ID 是后续insert_text、format_text、format_paragraph等操作定位该元素的钥匙。对应的类型契约定义在 types.rs 的CreateShape变体其中x/y/width/height为f64shape_type通过#[serde(default default_shape_type)]缺省为TEXT_BOX。五、为什么「不要带 action 字段」宿主分发与参数注入的源码佐证prompt 文档中「do not include an action field」的要求在 lib.rs 中有两处直接实现capability id → action 的映射action_from_context宿主把调用上下文含capability_id注入给 WASM 访客访客据此将google-slides.create_shape映射为create_shape动作名action 由宿主注入、调用方禁止携带params_with_action访客解析参数后如果发现其中已含action键直接返回invalid_parameters错误随后把宿主决定好的 action 名插入参数对象再交给 serde 反序列化为GoogleSlidesAction枚举。配套单元测试params_with_action_rejects_caller_supplied_actionlib.rs专门验证了这一防注入行为。这解释了为什么 prompt 文档要反复强调「Provide only the parameters described by the input schema」操作路由权在宿主调用方越权指定 action 会被视为非法参数。这也是 IronClaw 扩展能力面收窄capability-scoped设计的一部分——每个工具只能通过清单中声明的能力 id 被触发。六、权限与执行环境manifest 中的工具声明manifest.toml 中google-slides.create_shape的完整工具声明定义了它的运行时行为effects[network, use_secret, external_write]—— 该操作会产生外部写副作用需要网络与凭据default_permissionask—— 默认需要用户/宿主授权后才执行visibilitymodel—— 该工具对模型可见origin_gate_matrixloop_run gated_unless_grantedproduct/automation为forbidden—— 在 Agent 循环中默认受门控未授予前不可执行credentialsgoogle_runtime_tokenvendor 为googlescope 为https://www.googleapis.com/auth/presentationsaudience 为https://slides.googleapis.com以Authorization: Bearer token请求头注入input_schema_ref / prompt_doc_ref分别指向 create_shape.input.v1.json 与 create_shape.md。OAuth 流程由包级[auth.google]声明authorization code PKCE s256scope 覆盖presentations与presentations.readonlyclient_id/client_secret 来自管理员配置的google_oauth_client_id/google_oauth_client_secret。值得一提的是WASM 访客本身永远接触不到 OAuth 令牌——所有 API 调用都经由宿主的 HTTP capability 完成凭据注入与限流api.rs 头部注释明确说明这一点。七、打包与嵌入数据包如何进入 IronClawgoogle-slides是一个纯数据包data-only package它没有独立的 crate工具实现以 WASM 二进制形式交付。这一点在 README.md 中有明确说明其目录结构为manifest.tomlprompts/schemas/wasm/已编译产物google_slides_tool.wasmwasm-src/访客源码。在宿主侧该包由 gsuite.rs 的google_slides_bundle()通过include_str!/include_bytes!静态嵌入并在资产清单中登记全部 14 个工具create_presentation…batch_update其中包含create_shape。仓库内有两类校验保证交付一致性manifest 投影测试cargo test -p ironclaw_extension_registryWASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/下的二进制与wasm-src/源码同步。八、实战组合用 create_shape 编排一页演示文稿结合 lib.rs 文档注释中的 Tipscreate_shape在真实工作流中通常是「建形状 → 填文本 → 排版」链条的第一环// 1. 建演示文稿create_presentation {action: create_presentation, title: Q1 Report} // 2. 建幻灯片create_slide返回新幻灯片 object ID {action: create_slide, presentation_id: abc123, layout: TITLE_AND_BODY} // 3. 建文本框create_shape——宿主按 capability id 分发调用方不传 action {presentation_id: abc123, slide_object_id: slide1, shape_type: TEXT_BOX, x: 50, y: 50, width: 300, height: 40} // 4. 写入文本insert_textobject_id 使用第 3 步返回的 created_object_id {action: insert_text, presentation_id: abc123, object_id: shape1, text: Hello World} // 5. 排版format_text / format_paragraph {action: format_text, presentation_id: abc123, object_id: shape1, bold: true, font_size: 24}补充两个实操提示查找目标presentation_id即 Google Drive 文件 ID可用google-drive工具的list_files查找既有演示文稿slide_object_id可通过get_presentation返回的 slides 列表获取模板工作流可以先创建含占位文本的形状再用replace_all_text或replace_shapes_with_image统一替换实现模板化批量生成。九、错误语义调用 create_shape 可能遇到哪些失败api.rs 定义了统一的错误映射调用方应据此处理失败401→ErrorKind::AuthRequiredcode 固定为google_api_error_status_401令牌失效或权限不足需要重新走 OAuth 授权其他非 2xx 状态码→ErrorKind::Clientcode 形如api_status_429限流、api_status_400参数被 Slides API 拒绝等message 携带服务端响应摘要参数本地校验失败含伪造 action 字段→ErrorKind::Inputcode 为invalid_parameters网络层被宿主拒绝→ErrorKind::NetworkDenied对应NetworkDenied体现 IronClaw 的沙箱网络策略。配套单元测试api.rs验证了 401 → AuthRequired 与 429 → Client 的映射逻辑确保错误语义稳定。十、小结google-slides.create_shape是 IronClaw 扩展体系中「prompt 契约 JSON Schema WASM 实现」三层结构的典型样本prompt 文档用两句话锁定操作语义与调用纪律按 capability id 分发、只传 schema 参数、不传 actionschema 精确约束必填项与默认值WASM 访客则在宿主沙箱内完成坐标换算、batchUpdate 请求构造与错误归一化。理解这一契约既是安全调用该工具的前提也是阅读 IronClaw 其他google-*数据包gmail、docs、drive、sheets 等同类 prompt/schema 文件的通用方法论。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Docs 扩展的 create_document 能力输入契约、行为规则与 WASM 实现剖析IronClaw Google Docs 扩展的 create_document 能力输入契约、行为规则与 WASM 实现剖析 本篇技术指南围绕 IronCl人工智能AI 应用交互助手AI AgentIronClaw Google Drive 扩展 upload_file 能力详解文本文件上传的输入契约与 WASM 实现IronClaw Google Drive 扩展 upload_file 能力详解文本文件上传的输入契约与 WASM 实现 IronClaw 是一个以隐私、安人工智能AI 应用交互助手AI AgentIronClaw 中 Google Slides replace_all_text 工具的完整指南参数契约、WASM 实现与安全模型IronClaw 中 Google Slides replace_all_text 工具的完整指南参数契约、WASM 实现与安全模型 导读 replace_a人工智能AI 应用交互助手AI Agent创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表