IronClaw 扩展实战：Google Slides `get_presentation` 工具解析与演示文稿元数据读取

IronClaw 扩展实战Google Slidesget_presentation工具解析与演示文稿元数据读取【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw本篇技术指南聚焦 IronClaw 开源仓库中 Google Slides 扩展包extension idgoogle-slides的google-slides.get_presentation能力它如何以能力 ID 驱动、输入 Schema 校验、凭据由宿主托管的方式读取演示文稿元数据以及模型侧应遵循的调用契约。读完本文你将掌握该工具的输入/输出模型、底层 Slides API 调用链、权限与来源治理配置以及如何在模板化工作流中用它发现对象 ID、驱动后续编辑操作。关联文档说了什么一句话理解get_presentation本主题的权威来源是扩展包内的操作提示文档 get_presentation.md全文核心只有两句话却定义了完整的调用契约Get presentation metadata.The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.翻译成工程语言就是两点用途读取演示文稿Presentation的元数据调用方式操作由宿主Host根据 capability id 自动选择模型只需按输入 Schema 提供参数不得自行携带action字段。这两点不是随口规定而是 IronClaw 扩展架构的真实约束下面结合仓库源码逐层展开。调用契约能力 ID 驱动的操作选择与禁止 action 字段为什么提示文档要强调不要包含 action 字段看 WASM 工具端源码 lib.rs 即可理解action_from_context()从宿主注入的调用上下文ToolContext中读取capability_id并将其映射为具体动作名。google-slides.get_presentation被映射为get_presentation其余 13 个能力同理create_presentation、create_slide、batch_update等params_with_action()会先把模型传来的参数 JSON 反序列化然后显式拒绝任何包含action键的调用返回invalid_parameters错误码。也就是说操作语义由宿主根据能力 ID 决定模型侧参数与动作被强制解耦。仓库中还为此写了一个针对性测试params_with_action_rejects_caller_supplied_action当调用方传入{action:delete_all,presentation_id:presentation-1}时工具端直接以ErrorKind::Inputinvalid_parameters拒绝。这解释了提示文档do not include an action field的底层原因——动作字段属于宿主不属于模型。输入参数唯一的presentation_idget_presentation的输入定义在 get_presentation.input.v1.json是标准 JSON Schemadraft-07{ $schema: http://json-schema.org/draft-07/schema#, title: Google Slides get_presentation, description: Get presentation metadata., type: object, required: [presentation_id], properties: { presentation_id: { type: string, description: The presentation ID. } }, additionalProperties: false }要点必填且唯一presentation_id是字符串类型无默认值additionalProperties: false不接受任何额外字段与按 Schema 提供参数的契约严格对应该 Schema 通过manifest.toml中的input_schema_ref schemas/google-slides/get_presentation.input.v1.json挂接到工具定义上。在工具内部types.rs中对应的变体也完全一致GetPresentation { presentation_id: String }其注释明确说明presentation ID 与 Google Drive 文件 ID 相同。底层实现一次经过宿主托管的 Slides API GET 请求get_presentation的实现位于 api.rs 的get_presentation()函数核心调用链非常简洁构造路径GET https://slides.googleapis.com/v1/presentations/{presentation_id}基地址常量SLIDES_API_BASEpresentation_id经 URL 编码通过宿主提供的 HTTP 能力发起请求host::http_requestWASM 工具本身永远看不到 OAuth Token——凭据注入与限流完全由宿主侧完成非 2xx 响应走api_status_error()统一错误映射响应体经 UTF-8 校验后解析为结构化结果。该工具的凭据声明在 manifest.toml 中[[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/presentations.readonly] audience { scheme https, host slides.googleapis.com } injection { type header, name authorization, prefix Bearer }注意get_presentation与get_thumbnail是包内仅有的两个使用只读 scopepresentations.readonly的工具其余 12 个编辑类工具都使用完整的presentationsscope。宿主按audience匹配请求目标slides.googleapis.com并以Authorization: Bearer token头注入凭据。整个扩展的 OAuth 流程同样声明在manifest.toml的[auth.google]中oauth2_code授权方式、PKCEs256、access_typeoffline、promptconsent且refresh段将闲置刷新阈值keepalive_idle_seconds设为 6048007 天以主动规避 Google 测试状态应用刷新令牌 7 天不活跃即失效的供应商限制。返回结构演示文稿元数据模型get_presentation的返回值由 types.rs 中的PresentationMetadata定义原始 JSON 透传形态见 raw_output.v1.json字段类型说明presentation_idstring演示文稿 IDtitlestring演示文稿标题revision_idstring当前修订版本 ID可感知内容变更slide_countnumber幻灯片数量slidesarray每张幻灯片的摘要信息slides数组中的每个SlideInfo包含object_id幻灯片对象 ID、layout_object_id布局 ID以及elements元素列表。每个ElementInfo由parse_element()依据 Google Slides API 的 pageElements 结构解析字段包括object_id元素对象 IDelement_type按载荷类型分类取值包括shape、image、table、line、video、group、unknowntext_content仅对 shape 有效通过extract_text_from_shape()拼接text.textElements[].textRun.content得到无文本时省略placeholder_typeshape 为占位符时给出占位符类型。这正是get_presentation在模板化工作流中的价值先用它扫描整份演示文稿拿到所有幻灯片与元素的 object_id 及占位符类型再据此下发create_shape、insert_text、replace_all_text等后续编辑动作。权限与来源治理一个默认询问、仅循环运行、仅模型可见的工具manifest.toml中google-slides.get_presentation的完整工具定义如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-slides.get_presentation description Get presentation metadata. effects [network, use_secret] default_permission ask visibility model input_schema_ref schemas/google-slides/get_presentation.input.v1.json prompt_doc_ref prompts/google-slides/get_presentation.md逐项解读origin_gate_matrix该工具仅在 Agent 循环loop_run中可用且需授权放行gated_unless_granted在 product 与 automation 场景下被禁止effects [network, use_secret]声明副作用为发起网络请求并使用密钥与只读元数据、不写外部的能力一致相比编辑类工具的[network, use_secret, external_write]少了写操作default_permission ask默认向用户请求确认符合隐私优先原则visibility model该工具仅对模型可见供 Agent 自主调用不暴露给其他表面。实践要点如何找到presentation_id并融入工作流从 lib.rs 的模块文档可以提炼出几条直接可用的实操经验presentation ID 就是 Google Drive 文件 ID。需要读取已有演示文稿时可先用google-drive工具的list_files按名称搜索取其文件 ID 作为presentation_id对象 ID 的发现机制对已有文稿执行编辑前先调用get_presentation获取幻灯片/元素 object_id避免凭空猜测模板工作流先创建带占位符文本的 shape再用replace_all_text或replace_shapes_with_image批量填充get_presentation在此用于校验模板结构与占位符内容坐标与尺寸单位位置与尺寸使用 point1 英寸 72 point标准幻灯片为 720×405 point工具内部会将 point 换算为 EMU1 point 12700 EMU再上送 API。模型侧的最简调用形如示意实际由宿主注入动作{presentation_id: abc123}错误处理与可观测信号get_presentation失败时的错误码由 api.rs 统一生成仓库自带的单元测试可以佐证其稳定性401映射为ErrorKind::AuthRequired错误码固定为google_api_error_status_401测试api_status_error_401_maps_to_auth_required验证此场景通常意味着凭据缺失或失效宿主可据此触发重新授权流程其他非 2xx映射为ErrorKind::Client错误码形如api_status_429测试api_status_error_non_401_maps_to_client验证消息体截断至 512 字符以内HTTP 传输层失败由transport_failure()按宿主的HttpErrorKindAuthRequired / Input / OutputTooLarge / NetworkDenied / Client / OperationFailed 等逐一映射参数非法返回invalid_parameters输入类错误。验证与回归扩展包的工程质量保障按 README.md 的说明该扩展是一个data-only 包不含 crate工具本体以 WASM 访客形式发布仓库同时提交了编译产物wasm/google_slides_tool.wasm与源码wasm-src/并由ironclaw_extension_support::packages::gsuite内嵌分发。对应的校验手段包括Manifest 投影测试cargo test -p ironclaw_extension_registry验证manifest.toml中每个工具的 Schema 引用、凭据声明、权限矩阵能被正确投影与注册Artifact 新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保提交的 WASM 产物与wasm-src/源码哈希一致防止产物与源码漂移Schema 与代码契约一致WASM 端的schema()通过schemars::schema_for!(GoogleSlidesAction)从 serde 枚举直接生成广告 Schema从机制上杜绝文档 Schema 与实际反序列化契约不一致。扩展包的家族规则与设计约束可进一步参考 crates/extensions/AGENTS.md。小结google-slides.get_presentation是 IronClaw Google Slides 扩展中最基础的读取能力模型侧只需按 get_presentation.input.v1.json 提供presentation_id动作由宿主依据 capability id 注入宿主负责凭据托管只读 scopepresentations.readonly与来源治理循环运行、默认询问、仅模型可见WASM 端负责将其翻译为一次对slides.googleapis.com的 GET 请求并结构化为包含标题、修订 ID、幻灯片与元素清单的元数据模型。理解了它的调用契约与实现链路也就掌握了整个google-slides扩展包读-写分离、凭据隔离、Schema 驱动的设计范式。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考