IronClaw Google Sheets 批量读取指南：batch_read_values 工具的参数契约与 WASM 实现剖析

• 人工智能
• AI 应用
• 交互助手
• AI Agent

本篇技术指南以 IronClaw 扩展包google-sheets中的batch_read_values工具为对象，讲解如何通过 capability id 驱动的调用方式一次性读取多个 A1 记法区间（range）的单元格数据，并深入其 WASM 沙箱实现与 JSON Schema 参数契约，帮助读者掌握批量读表的最佳实践及背后的权限、凭证与错误处理机制。

工具定位：capability id 驱动的批量读取操作

batch_read_values是 IronClaw 的google-sheets扩展（extension id 为google-sheets）提供的 11 个工具之一。根据包内 README，该扩展是一个data-only package：不包含 Rust crate，工具本体以 WASM guest 形式随wasm/google_sheets_tool.wasm交付，源码位于 wasm-src/src。

该工具的功能一句话概括：Read values from multiple ranges（从多个区间读取值），对应 Google Sheets API v4 的spreadsheets.values.batchGet端点。

工具的原始提示文档 batch_read_values.md 只有三句话，但含义精炼：

Read values from multiple ranges. The host selects this operation from the capability id. Provide only the parameters described by the input schema; do not include an action field.

这三句话揭示了 IronClaw 扩展工具调用的两个核心约定：

1. 能力标识（capability id）选择操作：调用方不需要在参数里声明"我要执行哪个动作"，操作由宿主（host）根据 capability id 决定。对批量读取而言，capability id 就是google-sheets.batch_read_values。
2. 严格遵循输入 Schema：请求参数只能包含输入 Schema 中声明的字段，严禁携带action字段——这一点在源码层面有强制校验，下文会展开。

输入参数契约：spreadsheet_id 与 ranges

batch_read_values的输入由 batch_read_values.input.v1.json 定义（JSON Schema draft-07）：

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Google Sheets batch_read_values", "description": "Read values from multiple ranges.", "type": "object", "required": ["spreadsheet_id", "ranges"], "properties": { "spreadsheet_id": { "type": "string", "description": "The spreadsheet ID." }, "ranges": { "type": "array", "items": { "type": "string", "description": "A1 notation range." }, "description": "A1 notation ranges." } }, "additionalProperties": false }

两个必填参数：

additionalProperties: false意味着传入任何未声明的字段都会被拒绝，从 Schema 层面杜绝了多余参数与注入风险。

关于 spreadsheet_id 的获取

从 lib.rs 的模块文档可以确认：

• Spreadsheet ID 与 Google Drive 文件 ID 相同；
• 若用户只提供了电子表格名称/标题，应先用google-drive扩展的list_files工具按名称/标题查找文件，拿到 ID 后再调用本工具。

A1 记法要点

ranges数组中的每个元素都是 A1 记法字符串，支持多种写法（见 lib.rs）：

• 指定工作表与矩形区域："Sheet1!A1:D10"
• 省略工作表名（使用第一个工作表）："A1:B5"
• 整列范围："Sheet1!A:E"
• 整行范围："Sheet1!1:10"

注意：批量读取与单区间读取共用同一套 A1 解析约定，因此格式完全一致。

底层实现：WASM 工具如何调用 batchGet 端点

batch_read_values的实现位于 api.rs，其核心逻辑如下：

pub fn batch_read_values( spreadsheet_id: &str, ranges: &[String], ) -> Result<BatchValuesResult, GuestFailure> { let range_params: Vec<String> = ranges .iter() .map(|r| format!("ranges={}", url_encode(r))) .collect(); let path = format!( "{}/values:batchGet?{}", url_encode(spreadsheet_id), range_params.join("&") ); let response = api_call("GET", &path, None)?; // 解析 response["valueRanges"]，逐个映射为 ValuesResult // ... Ok(BatchValuesResult { value_ranges }) }

关键调用链：

1. URL 构造：基于常量SHEETS_API_BASE = "https://sheets.googleapis.com/v4/spreadsheets"（见 api.rs），拼出GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}/values:batchGet?ranges=A1&ranges=B2这样的请求；
2. URL 编码：每个ranges参数都经过urlencoding::encode（api.rs），因此包含特殊字符的区间名也能安全传输；
3. 宿主 HTTP 能力：所有网络请求都经由host::http_request发出（api.rs），WASM 工具永远看不到真实的 OAuth token——凭证注入由宿主完成，这是 IronClaw 安全模型的核心设计。

返回结构：valueRanges 数组

batch_read_values的响应类型是BatchValuesResult，定义在 types.rs：

pub struct BatchValuesResult { pub value_ranges: Vec<ValuesResult>, }

其中每个ValuesResult（types.rs）对应一个被请求的区间：

pub struct ValuesResult { pub range: String, // 返回区间（服务端归一化后的 A1 记法） pub values: Vec<Vec<serde_json::Value>>, // 二维数组：外层行，内层列 }

解析逻辑位于 api.rs：从响应的valueRanges数组中取出每一项，提取range与values字段并映射为ValuesResult。由于values的元素类型是serde_json::Value，单元格内容可以是字符串、数字、布尔值等任意 JSON 标量。

一次真实的调用示例

假设要同时读取Sheet1!A1:D10与Sheet2!A1:B5：

{ "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms", "ranges": ["Sheet1!A1:D10", "Sheet2!A1:B5"] }

返回结果形如：

{ "value_ranges": [ { "range": "Sheet1!A1:D10", "values": [ ["Name", "Age", "City", "Score"], ["Alice", 30, "Shanghai", 95], ["Bob", 25, "Beijing", 88] ] }, { "range": "Sheet2!A1:B5", "values": [ ["Item", "Price"], ["Laptop", 7999] ] } ] }

注意：若某个区间为空，服务端返回的values可能缺失，此时解析逻辑会退化为空数组（unwrap_or_default），调用方应做好空结果容错。

调用约束：为什么不能携带 action 字段

提示文档明确要求"do not include an action field"，这在 lib.rs 的params_with_action中有强制实现：

if obj.contains_key("action") { return Err(input_failure("invalid_parameters")); } obj.insert("action", serde_json::Value::String(action.to_string()));

也就是说：宿主根据 capability id 解析出动作名（google-sheets.batch_read_values→batch_read_values，映射见 lib.rs），由工具内部注入action字段；如果调用方自己带上了action，会直接得到ErrorKind::Input、code 为invalid_parameters的失败响应。该行为有单元测试背书（lib.rs）。

此外，工具对外公布的 Schema 由GoogleSheetsAction枚举通过schemars派生生成（lib.rs），保证"广告的 schema 与 serde 反序列化契约永不漂移"。

权限模型：只读 scope 与逐工具凭证注入

batch_read_values在 manifest.toml 中声明如下元数据：

[[tools]] origin_gate_matrix = { loop_run = "gated_unless_granted", product = "forbidden", automation = "forbidden" } id = "google-sheets.batch_read_values" description = "Read values from multiple ranges." effects = ["network", "use_secret"] default_permission = "ask" visibility = "model" input_schema_ref = "schemas/google-sheets/batch_read_values.input.v1.json" prompt_doc_ref = "prompts/google-sheets/batch_read_values.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 " }

几个值得注意的细节：

• 只读 scope：batch_read_values申请的是spreadsheets.readonly，而不是写操作使用的spreadsheets。这是最小权限原则的体现——批量读取工具永远不需要写权限；
• Bearer 头注入：凭证以Authorization: Bearer <token>形式由宿主注入请求头，WASM guest 不可见 token 本身；
• 效果声明：effects = ["network", "use_secret"]，即该工具会发起网络请求并消费密钥，但不会产生外部写入（对比write_values等工具还带external_write）；
• 来源门控：origin_gate_matrix规定该工具在 loop 运行中是gated_unless_granted（默认询问、授权后可免确认），在 product 与 automation 场景下被禁止；
• 默认权限：default_permission = "ask"，即默认需要用户确认后才执行。

OAuth 流程本身配置在[auth.google]（manifest.toml）：oauth2_code授权码模式、PKCE S256、access_type=offline换取长期 refresh token，并要求prompt=consent。宿主还会在 604800 秒（7 天）空闲前主动刷新 token（keepalive_idle_seconds），规避 Google 对 testing 状态应用 refresh token 7 天失效的限制。

同时，宿主在 network.rs 维护了 HTTPS 域名白名单（www.googleapis.com、gmail.googleapis.com、calendar.googleapis.com、oauth2.googleapis.com），WASM 工具只能访问白名单内的主机，网络层面进一步收敛攻击面。

与单区间读取 read_values 的对比

google-sheets包同时提供read_values（单区间）与batch_read_values（多区间）两个只读工具。选择建议：

当模型需要同时汇总多个 sheet 或多个不相邻区域的数据时，batch_read_values可将多次往返合并为一次请求，既减少网络开销，也让单次工具调用携带更完整的上下文。若要读取的只是单一区域，使用read_values语义更简洁。

错误处理与失败信号

工具失败的返回遵循 IronClaw 的GuestFailure契约（lib.rs），包含kind（错误类别）与稳定的code（机器可读信号）。针对 Google Sheets 批量读取，重点错误码包括：

• 401 认证失败：kind = AuthRequired，code 为google_api_error_status_401（api.rs），提示 token 失效或用户未授权，应触发重新授权流程；
• 非 2xx 状态：kind = Client，code 为api_status_{status}（如 429 限流），message 内含服务端返回的受限文本（上限 512 字符，见bounded_message）；
• 网络/传输失败：由host::http_request的错误映射为NetworkDenied、Executor等类别（api.rs）；
• 参数非法：kind = Input，如invalid_parameters（调用方携带action或 JSON 无法反序列化）。

这些错误码有单元测试覆盖（api.rs），是宿主与工具之间稳定、可编程的失败信号，Agent 侧可根据 code 决定是重试、提示授权还是转交人工。

验证与测试入口

google-sheets包的正确性由以下机制保障：

• manifest 投影校验：cargo test -p ironclaw_extension_registry校验 manifest 中input_schema_ref与prompt_doc_ref的引用完整性与 schema 一致性（见 README）；
• WASM 产物新鲜度：python3 scripts/ci/check-wasm-artifact-freshness.py校验提交的wasm/google_sheets_tool.wasm与wasm-src/源码是否一致，防止产物漂移；
• gsuite 包集成：ironclaw_extension_support通过packages::gsuite将本包嵌入宿主（见 packages/mod.rs），相关契约在 gsuite_core.rs 中有集成测试覆盖。

小结

google-sheets.batch_read_values是 IronClaw 扩展体系中"小工具、严契约"设计的典型样本：输入侧由 JSON Schema 强制约束（spreadsheet_id+ranges，拒绝多余字段），输出侧返回结构化的value_ranges二维数组；实现上由 WASM guest 构造values:batchGet请求，经宿主 HTTP 能力与只读 scope 凭证（spreadsheets.readonly）完成调用，全程 token 对 guest 不可见。掌握它的参数契约、A1 记法与错误码约定，即可在 Agent 工作流中高效、安全地实现跨区域批量取数。

• 人工智能
• AI 应用
• 交互助手
• AI Agent