IronClaw Google Sheets read_values 能力深度解析：A1 范围读取的调用链、参数契约与权限模型

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文以 IronClaw 扩展包 google-sheets 中 read_values 能力说明 为核心结合同包内的 JSON Schema、manifest 清单与 WASM 源码系统讲解如何让 Agent 通过google-sheets.read_values按 Spreadsheet ID 读取指定 A1 范围的单元格值包括“表名转 ID”的两步查找流程、宿主如何依据 capability id 选择操作、参数契约、底层 HTTP 调用链以及只读权限与 OAuth 凭据注入机制。读完本文你将能完整复现并扩展这一读表能力也能将其与批量读取、写入、格式化等姊妹工具正确组合。一、能力定位read_values 是什么在 IronClaw 的扩展体系中google-sheets是一个纯数据包data-only package——没有 crate可移植工具端以 WASM guest 形式发布见 google-sheets 包 README。该包共暴露 11 个工具从google-sheets.create_spreadsheet到google-sheets.format_cells外加[auth.google]认证段而read_values正是其中负责按 ID 读取单个 A1 范围单元格值的只读操作。read_values 能力说明 原文只有三句话却浓缩了三个关键行为约定读取方式通过 Spreadsheet ID 从指定范围读取单元格值名称解析如果用户只提供了表名/标题必须先调用 Google Drive 的google-drive.list_files找到对应的 Spreadsheet 文件 ID调用契约宿主host根据 capability id 选择该操作Agent 只需提供 input schema 描述的参数严禁在参数中携带action字段。这三条约定在源码与清单中都有严格对应下面逐一展开。二、参数契约read_values.input.v1.json 与类型定义2.1 输入 Schema唯一事实来源read_values 的入参由 schemas/google-sheets/read_values.input.v1.json 定义采用 JSON Schema draft-07{ $schema: http://json-schema.org/draft-07/schema#, title: Google Sheets read_values, description: Read cell values from a range., type: object, required: [spreadsheet_id, range], properties: { spreadsheet_id: { type: string, description: The spreadsheet ID. }, range: { type: string, description: A1 notation range. } }, additionalProperties: false }要点两个必填参数spreadsheet_idSpreadsheet ID字符串与rangeA1 记号范围字符串缺一不可additionalProperties: false多传任何字段都会被视为非法输入——这正是“只提供 input schema 描述的参数”的机器可执行约束该 schema 没有action属性对应文档中“不要包含 action 字段”的硬性规定。2.2 类型层的对应在 WASM guest 的 types.rs 中GoogleSheetsAction枚举通过#[serde(tag action, rename_all snake_case)]将每个操作建模为一个带action标签的变体ReadValues变体定义如下/// Read cell values from a range. ReadValues { /// The spreadsheet ID. spreadsheet_id: String, /// A1 notation range (e.g., Sheet1!A1:D10, A1:B5). range: String, },这里 A1 记号范围的示例Sheet1!A1:D10、A1:B5为 Agent 生成range参数提供了直接范式可以带 Sheet 标签限定到某个工作表也可以省略标签默认作用于第一个工作表列可用字母行用数字。三、两步定位表名/标题到 Spreadsheet ID 的解析流程read_values 的入参要求的是Spreadsheet ID即 Google Drive 文件 ID但用户对话中往往只给出表名或标题例如“读取我那个季度销售表”。此时能力说明给出了明确的操作顺序如果用户只提供了表名/标题先使用 Google Drive 的google-drive.list_files找到 Spreadsheet 文件 ID。这一约定与 manifest.toml 中工具描述一致“If the user only provided a spreadsheet name/title, search Google Drive first.”也在 lib.rs 的工具描述中复述“Spreadsheet IDs are the same as Google Drive file IDs, so use the google-drive tool to search for existing spreadsheets.” 推荐的两步调用序列为调用google-drive.list_files可按标题/名称过滤拿到目标 Spreadsheet 的id用该id作为spreadsheet_id调用google-sheets.read_values。例如用户请求“读取『Q1 销售』表的 A1:D10”时Agent 应先在 Drive 中定位标题为“Q1 销售”的文件得到形如1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms的 ID再构造{spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms, range: A1:D10}。四、底层调用链capability id → action → Sheets API v44.1 capability id 驱动操作选择能力说明强调“宿主根据 capability id 选择此操作”。在 lib.rs 的action_from_context中宿主注入的调用上下文ToolContext只携带一个capability_id字段并完成如下映射match context.capability_id.as_str() { ... google-sheets.read_values Ok(read_values), google-sheets.batch_read_values Ok(batch_read_values), ... }也就是说Agent 侧只需要声明使用google-sheets.read_values这个能力 ID工具内部会据此确定实际动作同时params_with_action会拒绝调用方自行携带action字段并返回invalid_parameters错误见 lib.rs 中的单元测试params_with_action_rejects_caller_supplied_action随后由宿主把正确动作注入参数——这就是“不要包含 action 字段”的防御性实现。4.2 实际 HTTP 请求在 api.rs 中read_values被实现为一次对 Google Sheets API v4 的 GET 请求pub fn read_values(spreadsheet_id: str, range: str) - ResultValuesResult, GuestFailure { let path format!( {}/values/{}, url_encode(spreadsheet_id), url_encode(range) ); let response api_call(GET, path, None)?; ... }其中SHEETS_API_BASE https://sheets.googleapis.com/v4/spreadsheets因此最终请求形如GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}/values/{range}spreadsheet_id与range都会经过 URL 编码urlencoding::encode。该调用经由宿主提供的host::http_request能力发出——WASM guest 本身不持有网络能力也不接触 OAuth token凭据注入、限流全部由宿主 HTTP 能力完成api.rs 顶部注释明确说明。五、返回结构ValuesResult 与单元格值解析read_values的返回类型定义在 types.rs#[derive(Debug, Serialize)] pub struct ValuesResult { pub range: String, pub values: VecVecserde_json::Value, }range回显实际生效的范围字符串values二维数组外层是行、内层是列每个单元格值以 JSON 值承载字符串、数字、布尔等类型取决于 Google Sheets 返回。api.rs 的解析逻辑将响应体中的values数组逐行逐列映射为VecVecserde_json::Value若 API 未返回values字段则默认空数组空范围/纯空表时表现为[]。因此 Agent 拿到结果后可按values[row][col]直接取用单元格例如values[0][0]即 A1。六、权限与安全模型只读 scope 与凭据注入read_values 是只读操作这一点在 manifest.toml 的工具声明中体现得最为直接[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-sheets.read_values description Read cell values from a range 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/read_values.input.v1.json prompt_doc_ref prompts/google-sheets/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凭据google_runtime_token仅申请spreadsheets.readonly与写入类工具如write_values、append_values使用的spreadsheets全量 scope 严格区分符合最小权限原则凭据注入方式宿主将运行时 token 以Authorization: Bearer token头注入请求guest 全程看不到明文 token效果声明effects [network, use_secret]——会发起网络请求、使用密钥凭据但不声明external_write写入类工具均带有该 effect进一步印证其只读属性默认权限default_permission ask即默认需要用户确认授权来源门控origin_gate_matrix表明在loop_run场景下为“未授权则门控”gated_unless_granted而在 product/automation 场景下为 forbidden限制该工具的调用来源。OAuth 认证整体配置包级[auth.google]采用 OAuth 2.0 授权码流程method oauth2_code启用 PKCEpkce s256scope 同时包含读写与只读两类extra_authorize_params请求access_typeoffline换取刷新令牌、promptconsent与include_granted_scopestrue[auth.google.refresh]中keepalive_idle_seconds 604800表示宿主认证引擎会通过 keepalive 定期刷新闲置账户的 token避免 Google 测试态应用 7 天不活跃即过期刷新令牌的问题。七、错误处理与可观测性当 Sheets API 返回非 2xx 状态码时api.rs 的api_status_error会做分类处理401映射为ErrorKind::AuthRequired错误码固定为google_api_error_status_401——提示凭据失效宿主可据此触发重新授权其他状态如 404 表示 ID/范围不存在、429 表示限流映射为ErrorKind::Client错误码形如api_status_404、api_status_429并附带截断后的响应体信息所有自由文本错误消息都会被bounded_message限制在 512 字符以内避免无界字符串流出 guest。此外guest 在每次调用前会通过host::log输出调试日志Google Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/...便于在宿主侧跟踪每一次读取请求。八、与姊妹工具的协同从读取到批量读取再到写入read_values 并不是孤立能力它与同包工具协同构成完整的工作流工具说明与 read_values 的关系google-sheets.get_spreadsheet读取元数据标题、各 Sheet 信息、命名区域用于确认 sheet 名/数值型 sheet_id帮助构造 A1 范围google-sheets.batch_read_values一次读取多个范围需要多处读取时更高效入参为ranges: VecString见 batch_read_values 能力说明内部拼装values:batchGet请求google-sheets.write_values/append_values写入/追加数据读取确认结构后再写入形成“先读后写”的数据管线google-drive.list_files按名称定位文件 IDread_values 名称解析的前置步骤典型编排示例Agent 先get_spreadsheet拿到工作表标题与尺寸 →read_values读取表头与数据 → 分析后append_values追加结果行 →format_cells美化。每一步都是独立、可授权、可审计的工具调用。九、快速自查清单仅使用spreadsheet_id与range两个必填参数不添加action字段或任何额外属性range使用 A1 记号如Sheet1!A1:D10、A1:B5、Sheet1!A:E用户只给表名/标题时先调用google-drive.list_files解析出文件 ID 再读取明确这是只读操作spreadsheets.readonlyscope需要用户授权default_permission ask401 错误码google_api_error_status_401表示需要重新授权其他状态按api_status_{code}排查。延伸阅读read_values 能力说明原文read_values 输入 Schemagoogle-sheets 扩展清单工具/凭据/认证全配置WASM guest 入口与 capability 分发Sheets API v4 调用实现与错误映射请求/响应类型定义google-sheets 扩展包总览赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI Agent基于 IronClaw GitHub 扩展的 create_repo 能力深度解析仓库创建的权限模型、参数规范与调用链路基于 IronClaw GitHub 扩展的 create_repo 能力深度解析仓库创建的权限模型、参数规范与调用链路 本篇技术指南以 IronClaw 仓人工智能AI 应用交互助手AI AgentWebLLM 浏览器端 LLM 推理引擎完全指南WebGPU 加速的客户端 AI 推理架构与实战WebLLM 浏览器端 LLM 推理引擎完全指南WebGPU 加速的客户端 AI 推理架构与实战 本文围绕开源仓库 web llm 的核心定位文档 site人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考