人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本篇文章聚焦 IronClaw 开源仓库中 Google Sheets 扩展包google-sheets的核心读取操作get_spreadsheet围绕其官方工具提示词文档get_spreadsheet.md结合同包内的输入 Schema、扩展清单manifest.toml以及 WASM 客端源码完整剖析该操作由谁调用、传什么参数、如何解析 ID、返回什么结构、如何鉴权的端到端实现。读完本文你将掌握在 IronClaw 的沙箱化扩展体系下安全获取 Google Sheets 表格元数据的调用契约与底层原理并能在开发或调试扩展时快速定位关键代码。一、操作定位基于 capability 的工具提示词在 IronClaw 的扩展体系里每个可执行操作都由三件套定义manifest.toml中的工具声明含 capability id、prompts/下的模型提示词说明何时使用、如何使用、schemas/下的输入 JSON Schema约束参数结构。get_spreadsheet正是其中的只读元数据操作对应 capability idgoogle-sheets.get_spreadsheet。其提示词文档原文仅用三句话完整定义了该操作的调用约定通过 spreadsheet ID 获取 spreadsheet 元数据Get spreadsheet metadata by spreadsheet ID。如果用户只提供了 spreadsheet 的名称/标题应先用 Google Drive 的google-drive.list_files查找该文件的 ID。host 根据 capability id 选择此操作只提供 input schema 描述的参数不要包含 action 字段。这三点分别回答了调什么ID 从哪来参数怎么传三个关键问题。其中由 host 根据 capability id 选择操作体现了 IronClaw 的分派机制——模型侧无需自行拼装 action 名从而避免调用方伪造操作。二、输入契约spreadsheet_id 唯一必填get_spreadsheet的输入由 get_spreadsheet.input.v1.json 约束采用 JSON Schema draft-07 格式{ $schema: http://json-schema.org/draft-07/schema#, title: Google Sheets get_spreadsheet, description: Get spreadsheet metadata., type: object, required: [spreadsheet_id], properties: { spreadsheet_id: { type: string, description: The spreadsheet ID. } }, additionalProperties: false }要点解析spreadsheet_id必填Google Sheets 的表格 ID其本质与 Google Drive 的文件 ID 相同。该 ID 出现在表格 URL 中https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit。additionalProperties: false禁止传入任何额外字段参数必须严格符合 schema。无action字段与提示词文档一致——操作类型由 host 依据 capability id 注入调用方传 action 会被拒绝详见下文源码分析。这是google-sheets包中参数最精简的操作之一因为元数据读取不需要 range、values 等数据操作参数仅凭 ID 即可命中资源。三、ID 解析路径名称 → Drive 搜索 → ID提示词文档明确要求当用户只给出文件名/标题而非 ID 时不能直接猜测 ID而应调用同属 Google 产品族的google-drive.list_files工具先行搜索。该工具在 google-drive/manifest.toml 中声明id google-drive.list_files配有自己的 input schema 与 prompt doc其定位在 google-sheets 包 README 中也有呼应——Use Google Drive list_files to find existing spreadsheets by name/title。推荐的解析流程判断用户输入若为形如1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms的长字符串视为 ID 直接使用若为自然语言名称/标题如Q1 销售报表调用google-drive.list_files可按名称检索从返回结果中提取目标文件的id将取得的 ID 作为spreadsheet_id调用get_spreadsheet。从源码结构看google-drive与google-sheets同属vendor.google管理组共享google_oauth_client_id/google_oauth_client_secret部署级凭据见 manifest.toml 的[admin_configuration]因此两者的凭据与账号体系天然互通跨工具协作无需额外授权。四、底层实现WASM 客端的元数据拉取google-sheets是一个data-only 包无 Rust crate可执行逻辑以 WASM 客端形式打包产物wasm/google_sheets_tool.wasm源码位于 wasm-src/src。get_spreadsheet的实现位于 api.rs/// Get spreadsheet metadata. pub fn get_spreadsheet(spreadsheet_id: str) - ResultSpreadsheetMetadata, GuestFailure { let path format!( {}?fieldsspreadsheetId,properties.title,spreadsheetUrl,sheets.properties,namedRanges, url_encode(spreadsheet_id) ); let response api_call(GET, path, None)?; let parsed: serde_json::Value serde_json::from_str(response).map_err(|e| serialization_failure(e))?; Ok(SpreadsheetMetadata { spreadsheet_id: parsed[spreadsheetId].as_str().unwrap_or().to_string(), title: parsed[properties][title].as_str().unwrap_or().to_string(), url: parsed[spreadsheetUrl].as_str().unwrap_or().to_string(), sheets: parsed[sheets] .as_array() .map(|arr| arr.iter().map(parse_sheet_info).collect()) .unwrap_or_default(), named_ranges: parsed[namedRanges] .as_array() .map(|arr| arr.iter().map(parse_named_range).collect()) .unwrap_or_default(), }) }4.1 请求构造方法GET基础地址常量SHEETS_API_BASE https://sheets.googleapis.com/v4/spreadsheetsapi.rs路径为{SHEETS_API_BASE}/{url_encode(spreadsheet_id)}字段裁剪通过fields参数只请求spreadsheetId, properties.title, spreadsheetUrl, sheets.properties, namedRanges避免拉取整表数据显著降低响应体积与带宽开销ID 编码spreadsheet_id经url_encode处理保证特殊字符安全。4.2 统一出站通道与凭据隔离所有 API 调用统一走api_call→host::http_requestapi.rs由 host 侧负责凭据注入与限流。文件头部注释点明安全设计关键api.rsAll API calls go through the hosts HTTP capability, which handles credential injection and rate limiting.The WASM tool never sees the actual OAuth token.即WASM 客端永远接触不到真实的 OAuth Token凭据由宿主注入这是 IronClaw 隐私/安全定位在扩展层的直接体现。4.3 响应解析与返回结构响应按SpreadsheetMetadata结构定义于 types.rs序列化返回pub struct SpreadsheetMetadata { pub spreadsheet_id: String, pub title: String, pub url: String, pub sheets: VecSheetInfo, // 空时省略 named_ranges 字段 #[serde(skip_serializing_if Vec::is_empty)] pub named_ranges: VecNamedRange, }其中嵌套结构结构字段说明SheetInfo每个 sheet/tabsheet_id、title、index、row_count、column_count由parse_sheet_info从properties/properties.gridProperties解析api.rs数值缺失时回退为 0NamedRange命名区域named_range_id、name、rangerange由format_grid_range渲染为sheetId…, rows a:b, cols c:d人类可读形式api.rssheet_id是数字型ID非 sheet 名称这是后续format_cells、delete_sheet、rename_sheet等操作必需的输入——因此get_spreadsheet也是这些表格管理操作的前置步骤见 lib.rs 的 TipsSheet IDs (numeric) are different from sheet names. Get them via get_spreadsheet.。4.4 分派与参数防注入execute_inner通过action_from_context从 host 注入的调用上下文ToolContext.capability_id解析出本次动作名再经params_with_action将动作注入参数lib.rs若调用方参数中已包含action字段直接返回invalid_parameters输入错误测试params_with_action_rejects_caller_supplied_action验证了此行为lib.rs若capability_id不在白名单返回unsupported_google_sheets_capability。这从机制上落实了提示词中只提供 schema 描述的参数不要包含 action 字段的约定。五、权限模型只读 Scope 与门控manifest.toml 中google-sheets.get_spreadsheet的完整声明[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-sheets.get_spreadsheet description Get spreadsheet metadata by spreadsheet ID. If the user only provided a spreadsheet name/title, search Google Drive first. effects [network, use_secret] default_permission ask visibility model input_schema_ref schemas/google-sheets/get_spreadsheet.input.v1.json prompt_doc_ref prompts/google-sheets/get_spreadsheet.md [[tools.credentials]] handle google_runtime_token vendor google scopes [https://www.googleapis.com/auth/spreadsheets.readonly] audience { scheme https, host sheets.googleapis.com } injection { type header, name authorization, prefix Bearer }安全设计要点最小权限 Scopeget_spreadsheet仅申请spreadsheets.readonly而write_values、append_values、format_cells等写操作申请的是spreadsheetsmanifest.toml。按操作粒度拆分 scope读取不持有写权限。效果声明effects [network, use_secret]——需要出网且使用密钥但不含external_write属于纯读取操作。默认许可default_permission ask即每次调用需经用户/审批门控确认。来源门控矩阵loop_run gated_unless_granted循环运行场景需显式授权product与automation场景直接forbidden——限制了该工具的暴露面。凭据注入OAuth token 以Authorization: Bearer token头注入目标 audience 限定为sheets.googleapis.com同时[auth.google]段配置了 OAuth2 授权码流程与 PKCES256等参数manifest.toml。六、错误处理可预期的失败语义get_spreadsheet的错误均映射为带kindcode的GuestFailure便于 host 与模型侧做稳定分支api.rsHTTP 状态kindcode说明401AuthRequiredgoogle_api_error_status_401凭据失效/未授权触发重新授权流程其他非 2xxClientapi_status_{status}如 429 限流、404 表格不存在等消息附带 API 原文传输层失败依HttpErrorKind映射google_api_transport_error等网络拒绝、执行器失败等WASM 客端内置单测验证了关键映射api.rs401 →AuthRequired、429 →Client且保留错误正文片段。所有错误消息经bounded_message截断至 512 字符防止不受控的超长字符串流入下游api.rs。七、与表格操作族的协作get_spreadsheet在google-sheets包的 11 个工具中扮演目录与入口角色完整清单见 READMEID 确认create_spreadsheet返回新建表格的spreadsheet_id与url之后可用get_spreadsheet复核元数据。Sheet 定位read_values/write_values/append_values需要 A1 记法 range如Sheet1!A1:D10format_cells、delete_sheet、rename_sheet需要数字 sheet_id——两者都可通过get_spreadsheet返回的sheets数组获得lib.rs 的 Tips 对此有明确说明。命名区域发现返回的named_ranges可让模型直接以名称引用预定义区域避免硬编码行列号。在模型侧一个典型的多步调用序列为google-drive.list_files按标题搜 ID→google-sheets.get_spreadsheet拿元数据与 sheet_id→google-sheets.read_values按 A1 区域读数据→ 视需要format_cells等写操作。每一步都遵循各自的 schema 与权限声明。八、测试与验证方式该包的可验证性保障包括清单投影测试cargo test -p ironclaw_extension_registry会校验manifest.toml的工具声明、schema 引用与凭据配置的一致性见 README 的 Tests / checks 一节WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py确保wasm/google_sheets_tool.wasm与wasm-src/源码同步防止发布过期二进制客端单元测试api.rs与lib.rs内置的#[cfg(test)]覆盖了错误映射与参数防注入等关键行为。这些测试共同保证了提示词 → schema → manifest → WASM 实现四层契约的一致性。九、小结google-sheets.get_spreadsheet是 IronClaw 扩展体系中只读元数据操作的典型样本提示词文档定义了模型侧的最小调用约定凭 ID 读取、名称先走 Drive 搜索、不传 action输入 schema 将契约收敛为单一必填参数WASM 客端通过 host 统一出站通道完成字段裁剪的 GET 请求并返回结构化的表格/Sheet/命名区域元数据manifest 则从 scope、effects、门控矩阵与凭据注入四个维度落实了最小权限与安全隔离。理解这一操作即可触类旁通地掌握整个google-sheets包乃至 Google 产品族扩展的调用与实现模式。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐如何在Obsidian中无缝管理电子表格终极Excel插件完整指南如何在Obsidian中无缝管理电子表格终极Excel插件完整指南 你是否曾为在笔记软件中处理表格数据而烦恼当需要在Obsidian中创建预算表、项目进度表人工智能AI 应用交互助手AI AgentCherry Studio gh-pr-review 代码评审清单A/B/C 三级检查体系与项目规则落地Cherry Studio gh pr review 代码评审清单A/B/C 三级检查体系与项目规则落地 本文以 Cherry Studio 仓库中的自动化代人工智能AI 应用交互助手AI AgentIronClaw google-docs 扩展完全指南语义化文档工作流与 WASM 工具实现解析IronClaw google docs 扩展完全指南语义化文档工作流与 WASM 工具实现解析 本文以 IronClaw 开源仓库中 google docs人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
