IronClaw Google Sheets clear_values 工具深度解析：Agent 清除单元格范围的参数契约、WASM 实现与权限模型-平芜编程栈

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

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址：https://gitcode.com/gh_mirrors/iro/ironclaw

本文围绕 IronClaw 扩展包google-sheets中的google-sheets.clear_values操作，完整讲解该工具在 clear_values 提示文档中定义的使用约定、其 JSON Schema 输入契约、底层 WASM 访客实现与宿主侧权限/凭据模型。读完本文，你将掌握如何在 IronClaw 的 Agent 循环中安全、正确地清除 Google Sheets 指定范围的单元格数据（保留格式），并能依据仓库源码与清单文件追溯该操作从提示词到 HTTP 请求的完整调用链。

一、操作定位：clear_values 在 IronClaw 扩展体系中的角色

google-sheets是 IronClaw 的一个纯数据扩展包（data-only package），不包含独立 crate，工具本体以 WASM 访客（guest）形式随包分发。其 README 明确说明：该扩展提供创建电子表格、读写/追加/清除值、管理并格式化工作表共 11 个工具（google-sheets.create_spreadsheet…google-sheets.format_cells），由ironclaw_extension_support::packages::gsuite家族嵌入。

clear_values是其中唯一的"清除类"写操作，与write_values（覆盖写）、append_values（追加写）共同构成单元格值的三类变更手段。它的核心语义在源码注释中有明确界定：清除范围内的值，但保留单元格格式——见 types.rs 中ClearValues变体的注释Clear values from a range (keeps formatting)，以及 lib.rs 工具描述中的同一表述。这意味着它适合"清空后重填"或"重置数据区"场景，而不会破坏已有的字体、颜色、对齐等样式配置。

二、输入契约：clear_values 的 JSON Schema 全解

操作对应的输入模式文件为 clear_values.input.v1.json（JSON Schema draft-07）。完整契约如下：

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Google Sheets clear_values", "description": "Clear 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 to clear." } }, "additionalProperties": false }

参数说明与取值要点

参数	类型	必填	说明
`spreadsheet_id`	string	是	电子表格 ID，与 Google Drive 文件 ID 相同
`range`	string	是	待清除的 A1 表示法范围，例如`Sheet1!A1:D10`

三个关键约定值得注意：

required只有两个字段：spreadsheet_id与range。与write_values相比（见 write_values.input.v1.json，额外要求values与可选的value_input_option），清除操作不需要值数组，因此契约更精简。
additionalProperties: false：调用方传入 schema 之外的任何字段都会被拒绝，这是整个google-sheets家族所有输入模式的统一约束，用于在入口处拦截"附加属性注入"类错误参数。
range使用 A1 表示法：仓库的 lib.rs 工具说明给出规范示例——"Sheet1!A1:D10"（指定工作表与矩形区域）、"A1:B5"（省略工作表名，作用于当前默认表）、"Sheet1!A:E"（整列区域）。types.rs中ReadValues/WriteValues等变体的文档注释也复用了这些示例，说明 A1 表示法是整个扩展的通用约定。

三、调用约定：为什么"不要包含 action 字段"

clear_values.md 的提示文档明确了两条指令：

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

即：操作的选择由宿主（host）依据 capability id 完成，模型/调用方只需按输入 schema 提供参数，不得自行携带action字段。这一约定在 WASM 访客侧被强制实施，源码证据在 lib.rs 的params_with_action函数：

访客从调用上下文解析出 capability id（如google-sheets.clear_values），通过action_from_context映射为内部动作名（见 lib.rs 中"google-sheets.clear_values" => Ok("clear_values")）；
随后把动作名注入参数对象；若调用方已在参数中自行提供action字段，则直接返回invalid_parameters的输入类失败——lib.rs 的单元测试params_with_action_rejects_caller_supplied_action正是验证这一点：传入{"action":"delete_all", ...}会得到ErrorKind::Input与错误码invalid_parameters。

这种"动作由宿主路由、参数由调用方提供"的分离设计，避免了模型在自由文本中猜测操作名造成的歧义，也杜绝了调用方通过action字段越权触发其他能力。

四、底层实现：一次 clear_values 的完整调用链

清除操作的 WASM 实现位于 api.rs：

/// Clear values from a range. pub fn clear_values(spreadsheet_id: &str, range: &str) -> Result<ClearResult, GuestFailure> { let path = format!( "{}/values/{}:clear", url_encode(spreadsheet_id), url_encode(range) ); let response = api_call("POST", &path, Some("{}"))?; let parsed: serde_json::Value = serde_json::from_str(&response).map_err(|e| serialization_failure(&e))?; Ok(ClearResult { cleared_range: parsed["clearedRange"].as_str().unwrap_or("").to_string(), }) }

调用链的关键事实：

端点：以SHEETS_API_BASE = https://sheets.googleapis.com/v4/spreadsheets（见 api.rs）为基址，拼接{spreadsheet_id}/values/{range}:clear，对应 Google Sheets API v4 的values.clear操作。
请求方式：POST，请求体为字面量"{}"——清除操作无需携带任何业务数据，一个空 JSON 对象即满足契约；由于存在请求体，api_call会自动附加Content-Type: application/json头（见 api.rs）。
URL 编码：spreadsheet_id与range均经urlencoding::encode处理（见 api.rs），保证 A1 范围中的!、:等字符在 URL 路径中正确传输。
返回结构：仅解析响应中的clearedRange字段，封装为ClearResult { cleared_range: String }（见 types.rs）。与write_values/append_values返回UpdateResult（含updated_rows/updated_columns/updated_cells计数）不同，清除操作的确认信息就是被清除的实际范围字符串。
分派：execute_inner中GoogleSheetsAction::ClearValues { spreadsheet_id, range }分支调用api::clear_values并序列化结果返回（见 lib.rs）。

与其他值操作的语义对比

操作	方法/端点	语义	返回
`write_values`	`PUT .../values/{range}?valueInputOption=...`	覆盖写入，默认`USER_ENTERED`	`UpdateResult`
`append_values`	`POST .../values/{range}:append?insertDataOption=INSERT_ROWS`	在现有数据后追加行	`UpdateResult`
`clear_values`	`POST .../values/{range}:clear`	清除值，保留格式	`ClearResult{cleared_range}`

三者的实现均在 api.rs 中相邻定义，方便对照阅读（write_values见 api.rs，append_values见 api.rs）。

五、权限与安全模型：谁允许清除、凭据如何注入

clear_values是写操作，其权限配置在 manifest.toml 中有完整声明：

[[tools]] origin_gate_matrix = { loop_run = "gated_unless_granted", product = "forbidden", automation = "forbidden" } id = "google-sheets.clear_values" description = "Clear values from a range." effects = ["network", "use_secret", "external_write"] default_permission = "ask" visibility = "model" input_schema_ref = "schemas/google-sheets/clear_values.input.v1.json" prompt_doc_ref = "prompts/google-sheets/clear_values.md" [[tools.credentials]] handle = "google_runtime_token" vendor = "google" scopes = ["https://www.googleapis.com/auth/spreadsheets"] audience = { scheme = "https", host = "sheets.googleapis.com" } injection = { type = "header", name = "authorization", prefix = "Bearer " }

逐项解读：

origin_gate_matrix：操作在loop_run（Agent 循环运行）中默认gated_unless_granted（未授予则需门控审批），而在product与automation渠道中为forbidden。这意味着清除操作被严格限定在 Agent 会话内，且触发前需要用户授权。
effects：声明network（发起外部网络请求）、use_secret（使用机密凭据）、external_write（对外部系统产生写副作用）三类效应，供宿主的运行时策略引擎进行效应级审查。
default_permission = "ask"：默认每次调用都向用户请求许可，不会静默执行破坏性操作。
visibility = "model"：该工具对模型可见、可被模型选中，但遵循上述权限门控。
凭据注入：工具使用google_runtime_token，作用域为https://www.googleapis.com/auth/spreadsheets（读写级，与read_values使用的spreadsheets.readonly区分），以Authorization: Bearer <token>请求头注入到sheets.googleapis.com。关键安全设计在 api.rs 的模块注释中阐明：所有 API 调用都经由宿主的 HTTP 能力完成，由宿主负责凭据注入与限流，WASM 访客永远接触不到真实的 OAuth token。
账户模型：[auth.google]配置了oauth2_code授权流程、PKCEs256、access_type=offline等参数；Google 的"测试中"应用刷新令牌闲置 7 天即失效，因此宿主认证引擎会通过 keepalive 机制提前刷新闲置账户（见 manifest.toml 中的keepalive_idle_seconds = 604800注释）。此外，gsuite 家族扩展共享同一 Google 账户授予关系，相关判定逻辑见 gsuite/account_policy.rs 中的gsuite_google_account_visible_to_requester。

六、错误处理：清除失败时会得到什么

清除操作的错误路径在 api.rs 中统一收敛为GuestFailure，遵循ErrorKind分类：

HTTP 传输层失败：transport_failure将宿主的HttpFailure映射为对应错误类型，如AuthRequired、NetworkDenied、Client、Executor等（见 api.rs）。
非 2xx 状态码：api_status_error对 401 特殊处理，返回ErrorKind::AuthRequired与稳定错误码google_api_error_status_401，提示凭据失效需重新授权；其余状态码映射为Client类错误，错误码形如api_status_{status}（如 429 限流），并附带截断后的响应正文（见 api.rs）。这些映射行为由 api.rs 的单元测试验证。
参数/序列化失败：JSON 解析失败返回invalid_parameters（Input类）；本地处理失败返回serialization_failed（Executor类）。
消息有界：所有自由文本错误消息经bounded_message截断到 512 字符（见 api.rs），防止不可信上游文本无限膨胀。

七、调用示例与最佳实践

最小调用示例

{"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms", "range": "Sheet1!A1:D10"}

注意：不要在参数中携带action字段，动作由宿主依据 capability idgoogle-sheets.clear_values自动选择。

实操建议

先定位后清除：spreadsheet_id与 Google Drive 文件 ID 相同，若用户只提供了电子表格名称，应先用 Google Drive 的list_files工具按名称/标题查找（见 manifest.toml 与 lib.rs 的提示）；若不确定目标表（tab）名称或范围边界，可先用get_spreadsheet获取工作表元数据、用read_values预览当前内容，确认后再执行清除。
区分"清值"与"删表"：clear_values只清空范围内的值并保留格式；若需要整表（tab）移除，应使用delete_sheet（注意其参数是数字sheet_id，需经get_spreadsheet获取，而非工作表名称——见 types.rs 的注释）。
预期写权限：清除属于external_write效应，且要求凭据具备spreadsheets（读写）作用域；若账号只有只读授权，调用将得到google_api_error_status_401类失败，需要先完成 OAuth 授权流程。
验证结果：响应中的cleared_range即实际清除范围，必要时可随后调用read_values复查该区域已为空。

八、质量保障：该扩展如何被持续校验

google-sheets包的交付物质量由两层检查保障（见 README）：

清单投影测试：cargo test -p ironclaw_extension_registry验证manifest.toml能被扩展注册表正确解析投影；
WASM 制品新鲜度：python3 scripts/ci/check-wasm-artifact-freshness.py校验提交的wasm/google_sheets_tool.wasm与wasm-src/源码是否一致，防止手工制品与源码漂移。

此外，访客源码的schema()方法通过schemars::schema_for!(GoogleSheetsAction)从 serde 契约自动派生对外广告的 JSON Schema（见 lib.rs），而Cargo.toml中声明的schemars依赖注释同样说明"广告的模式与 serde 强制契约永不漂移"（见 wasm-src/Cargo.toml），从机制上保证了clear_values这类操作的输入模式始终与真实反序列化逻辑一致。