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

人工智能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.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.jsonJSON 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_idstring是电子表格 ID与 Google Drive 文件 ID 相同rangestring是待清除的 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) - ResultClearResult, 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_valuesPUT .../values/{range}?valueInputOption...覆盖写入默认USER_ENTEREDUpdateResultappend_valuesPOST .../values/{range}:append?insertDataOptionINSERT_ROWS在现有数据后追加行UpdateResultclear_valuesPOST .../values/{range}:clear清除值保留格式ClearResult{cleared_range}三者的实现均在 api.rs 中相邻定义方便对照阅读write_values见 api.rsappend_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_runAgent 循环运行中默认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_typeoffline等参数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_parametersInput类本地处理失败返回serialization_failedExecutor类。消息有界所有自由文本错误消息经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这类操作的输入模式始终与真实反序列化逻辑一致。赞分享人工智能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 能力深度解析A1 范围读取的调用链、参数契约与权限模型IronClaw Google Sheets read_values 能力深度解析A1 范围读取的调用链、参数契约与权限模型 本文以 IronClaw 扩展包人工智能AI 应用交互助手AI AgentIronClaw Google Drive 权限清单list_permissions 工具的参数、Schema 与 WASM 实现解析IronClaw Google Drive 权限清单list_permissions 工具的参数、Schema 与 WASM 实现解析 IronClaw 以「人工智能AI 应用交互助手AI AgentIronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考