人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文以 IronClaw 开源仓库中 add_sheet.md 这份工具提示文档为切入点完整拆解google-sheets.add_sheet这一 Capability 从宿主按 capability id 选路到WASM 沙箱内组装spreadsheets.batchUpdate请求的整条实现链路。读完本文你将掌握该工具的输入 Schema 与参数约束、为什么调用时不能携带action字段、底层如何调用 Google Sheets API、返回结果的字段结构以及它背后所依托的权限、凭据与安全模型并能在 Agent 会话中正确、合规地使用它。一份工具提示文档在 IronClaw 中扮演什么角色add_sheet.md 全文只有三句话Add a sheet tab.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 扩展包体系中为 LLM 准备的prompt doc提示文档与每个工具一一对应。从包结构可以看到google-sheets扩展的每个工具都同时具备三件套prompts/google-sheets/*.md给模型看的操作提示、schemas/google-sheets/*.input.v1.json参数 JSON Schema、以及 WASM 客端实现。在 manifest.toml 中add_sheet工具通过两个字段把这三者绑定起来input_schema_ref schemas/google-sheets/add_sheet.input.v1.json prompt_doc_ref prompts/google-sheets/add_sheet.md宿主在加载扩展时会校验这些引用确实存在。例如 available_extensions.rs 会逐一核对prompt_doc_ref指向的资源文件是否随包提供见其中对assets.contains(prompt_doc_ref)的断言逻辑确保提示文档、输入 Schema 与工具注册声明不会漂移失配。这份提示文档的定位决定了它不是给开发者看的 API 手册而是给 Agent 模型看的如何发起一次能力调用的操作指引。它刻意保持极简模型只需要知道两件事——①宿主会根据 capability id 自动选择对应操作②只需按输入 Schema 提供参数且不得自行添加action字段。宿主如何按 capability id 选择操作提示文档第一句 The host selects this operation from the capability id 背后是一段真实的运行时逻辑。WASM 客端入口 lib.rs 中execute_inner首先调用action_from_context(context)fn action_from_context(context: Optionstr) - Resultstatic str, GuestFailure { let context context.ok_or_else(|| input_failure(missing_invocation_context))?; let context: ToolContext serde_json::from_str(context).map_err(|_| input_failure(invalid_invocation_context))?; match context.capability_id.as_str() { // ... google-sheets.add_sheet Ok(add_sheet), // ... _ Err(input_failure(unsupported_google_sheets_capability)), } }也就是说宿主在调用沙箱工具时会把一个包含capability_id的调用上下文ToolContext定义见 types.rs传给 WASM 客端客端据此把google-sheets.add_sheet这一能力 id 映射为内部的add_sheet动作。如果上下文缺失、无法解析或携带了未注册的能力 id则会分别返回missing_invocation_context、invalid_invocation_context、unsupported_google_sheets_capability等稳定的错误码。输入 Schema只有两个必填参数add_sheet.input.v1.json 是调用方模型唯一需要遵循的参数契约{ $schema: http://json-schema.org/draft-07/schema#, title: Google Sheets add_sheet, description: Add a sheet tab., type: object, required: [spreadsheet_id, title], properties: { spreadsheet_id: { type: string, description: The spreadsheet ID. }, title: { type: string, description: New sheet title. } }, additionalProperties: false }参数要点参数类型必填说明spreadsheet_idstring是目标电子表格的 ID与 Google Drive 文件 ID 相同titlestring是新工作表tab的名称其他任何字段—否additionalProperties: false多余字段会被拒绝spreadsheet_id与 Google Drive 文件 ID 相同这一点值得强调官方包描述manifest.toml 与 README.md都建议先用 Google Drive 的list_files按名称/标题找到现有表格再取它的 ID 来调用本工具这与 WASM 客端模块文档lib.rs 顶部注释中的提示一致。为什么不要包含 action 字段提示文档第二句 do not include an action field 是客端的一种防御性设计而非单纯的风格建议。在 lib.rs 的params_with_action中客端会主动把由 capability id 解析出的动作名注入参数对象fn params_with_action(params: str, action: str) - Resultserde_json::Value, GuestFailure { let mut params: serde_json::Value if params.trim().is_empty() { serde_json::json!({}) } else { serde_json::from_str(params).map_err(|_| input_failure(invalid_parameters))? }; let obj params.as_object_mut().ok_or_else(|| input_failure(invalid_parameters))?; if obj.contains_key(action) { return Err(input_failure(invalid_parameters)); } obj.insert(action.to_string(), serde_json::Value::String(action.to_string())); Ok(params) }两个关键点如果调用方自己传了action直接返回invalid_parameters错误。这一行为有单元测试锁定params_with_action_rejects_caller_supplied_action用{action:delete_all,...}验证被拒绝lib.rs 测试模块。这样设计是为了让动作选择完全由宿主通过 capability id 决定防止模型侧注入一个与当前能力不匹配的动作比如通过add_sheet能力去尝试删除表格。之所以能这样做是因为客端的数据模型GoogleSheetsAction是一个以action为判别字段的 tagged enum#[serde(tag action, rename_all snake_case)]见 types.rs其中AddSheet { spreadsheet_id, title }就是对应变体。客端注入action:add_sheet之后serde_json::from_value才能正确反序列化出对应变体并分发执行。底层实现一次batchUpdate请求真正的调用发生在 api.rs 的add_sheet函数中它复用batch_update把请求封装成 Google Sheets API v4 的spreadsheets.batchUpdate调用pub fn add_sheet(spreadsheet_id: str, title: str) - ResultAddSheetResult, GuestFailure { let requests vec![serde_json::json!({ addSheet: { properties: { title: title } } })]; let parsed batch_update(spreadsheet_id, requests)?; let reply parsed[replies] .as_array() .and_then(|arr| arr.first()) .map(|r| r[addSheet][properties]); let reply reply.ok_or_else(|| GuestFailure { /* batch_update_missing_reply */ })?; Ok(AddSheetResult { sheet: SheetInfo { sheet_id: reply[sheetId].as_i64().unwrap_or(0), title: reply[title].as_str().unwrap_or().to_string(), index: reply[index].as_i64().unwrap_or(0), row_count: reply[gridProperties][rowCount].as_i64().unwrap_or(1000), column_count: reply[gridProperties][columnCount].as_i64().unwrap_or(26), }, }) }实现要点请求体为{requests: [{addSheet: {properties: {title: ...}}}]}走POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}:batchUpdate新增工作表使用 Google 侧默认网格尺寸1000 行 × 26 列成功响应中的replies[0].addSheet.properties会被解析为SheetInfo若响应中没有预期的replies结构返回batch_update_missing_reply的Executor类错误add_sheet属于写操作因而在 manifest.toml 中声明了effects [network, use_secret, external_write]。返回结果结构成功后客端返回 JSON 序列化的AddSheetResult定义见 types.rs{ sheet: { sheet_id: 123456789, title: Q3 汇总, index: 2, row_count: 1000, column_count: 26 } }其中sheet_id是数字型工作表 ID与title工作表名称是两回事后续delete_sheet、rename_sheet、format_cells等操作需要的都是这个数字 ID而它只能通过get_spreadsheet或本操作的返回获取。这一点在客端模块文档lib.rs与类型注释types.rs中都有明确提醒。注册、权限与凭据一次调用背后的治理机制add_sheet不是凭空可用的——它在 manifest.toml 中的注册声明定义了它的全部治理约束[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id google-sheets.add_sheet description Add a sheet tab. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/google-sheets/add_sheet.input.v1.json prompt_doc_ref prompts/google-sheets/add_sheet.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主循环中为gated_unless_granted默认询问、授权后放行在product与automation渠道中为forbidden即写操作默认需要用户显式授权权限默认值default_permission ask与上面的门控矩阵呼应效果声明effects网络请求、使用密钥、外部写入供宿主做资源核算与披露凭据注入OAuth 令牌由宿主在 HTTP 边界注入Authorization: Bearer token请求头作用域为https://www.googleapis.com/auth/spreadsheets写权限。WASM 客端永远看不到令牌本身——这一点在沙箱接口契约 tool.wit 的安全模型中明文规定Secrets are NEVER exposed to WASM; credentials are injected at host boundary。在更早期的 v2 清单first_party_v2/google-sheets.toml中可以看到同一能力的等价声明它还额外列出required_host_ports [host.runtime.http_egress]说明该工具依赖宿主的 HTTP 出口能力。错误处理与安全边界当 Google API 返回非 2xx 状态时api.rs 的api_status_error会把错误映射为结构化的GuestFailure401→AuthRequired错误码固定为google_api_error_status_401有单元测试api_status_error_401_maps_to_auth_required锁定其他状态码→Client错误码形如api_status_{status}如 429 限流对应api_status_429消息被bounded_message截断到 512 字符以内再上抛。这些GuestFailure会通过tool接口tool.wit返回宿主宿主在沙箱出口对code与message做密钥形状的清洗scrub后才会让错误信息对外可见。客端自身的任何自由文本消息也一律先做长度截断避免把不受控的长字符串交给下游。整个链路体现了 IronClaw WASM 工具不可信、能力默认关闭、凭据永不进入沙箱的设计原则。典型调用示例与实操提示在 Agent 会话中一次合法的add_sheet调用应该长这样注意没有action字段{ spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms, title: 月度对账 }实操提示与客端模块文档、包 README 保持一致先用google-drive的list_files按名称定位表格取回其文件 ID 作为spreadsheet_id用户只给了表格名时尤其要这么做新增工作表默认 1000 × 26如需定制尺寸可在创建后使用format_cells或结合get_spreadsheet元数据核对记住数字型sheet_id后续改名、删除、格式化都用它而不是用title写操作需要用户授权由于default_permission ask与gated_unless_granted门控首次调用通常要经过确认流程若返回 401说明令牌失效或作用域不足宿主会以google_api_error_status_401提示需要重新授权。验证方式如果你想在仓库内验证本文涉及的行为可以关注manifest.toml 与 add_sheet.input.v1.json工具注册与参数契约的单一事实来源lib.rs 的测试模块验证调用方携带action会被拒绝api.rs 的测试模块验证 401/非 401 错误映射WASM 产物新鲜度由scripts/ci/check-wasm-artifact-freshness.py校验清单投影测试可运行cargo test -p ironclaw_extension_registry见包 README.md。小结从一份只有三行的提示文档出发我们还原了google-sheets.add_sheet的完整技术图景capability id 驱动的动作分发、严格的双必填参数 Schema、禁止携带action的防御式设计、基于batchUpdate的底层实现、结构化的结果与错误返回以及注册、门控、凭据注入所构成的治理与安全边界。对于希望扩展 IronClaw 工具或深入理解其扩展机制的开发者而言add_sheet是一个麻雀虽小、五脏俱全的绝佳范例。赞分享人工智能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 Agent最完整Qwen3-Coder-480B-A35B-Instruct API文档从基础调用到高级工具链集成最完整Qwen3 Coder 480B A35B Instruct API文档从基础调用到高级工具链集成 读完你将获得 480B参数模型的零成本部署方案 25基础模型大模型QwenIronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型IronClaw Google Sheets 扩展 create_spreadsheet 能力全解析参数契约、WASM 调用链与安全模型 IronClaw 是人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考