人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本篇技术指南围绕 IronClaw 开源仓库中 Google Sheets 扩展包的核心工具format_cellsgoogle-sheets.format_cells展开从能力入口文档、JSON Schema 输入契约、WASM 访客端实现到权限与凭据配置完整还原“在一个单元格区间内格式化数据”这一能力在 Agent OS 中的定义、约束与调用方式。读完本文你将掌握该工具的每一个输入参数的含义与取值范围、它如何在底层映射为 Google Sheets API 的batchUpdate/repeatCell请求以及如何构造可直接运行的调用载荷。能力定位格式化单元格区间在 IronClaw 的扩展体系中google-sheets是一个data-only 扩展包不包含 Rust crate可移植工具半区以 WASM 访客形式分发共暴露 11 个工具google-sheets.create_spreadsheet至google-sheets.format_cells并附带[auth.google]认证段。其包级说明见 README.md包结构由 manifest.toml 声明。format_cells是其中唯一一个专门负责“样式与格式”的工具。它不写入单元格的值而是对指定区间批量施加文本样式、背景色、对齐方式和数字格式。它与其他值操作类工具write_values、append_values、clear_values正交清除值不会清除格式源码注释明确clear_values是 “Clears values (keeps formatting)”。能力入口文档 format_cells.md 只用了两句话定义该操作Format cells in a range.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 扩展协议的两条关键规则能力由宿主host从 capability id 选择调用方通常是 LLM Agent无需、也不能自行指定action字段。在 WASM 访客端动作名来自调用上下文invocation context中的capability_id由宿主注入见 lib.rs 中的action_from_context它把google-sheets.format_cells映射为内部动作名format_cells其他未知 capability id 一律返回unsupported_google_sheets_capability输入错误。只提供输入 Schema 声明的参数参数契约完全由 format_cells.input.v1.json 约束additionalProperties: false多余字段会被拒绝并且访客端在params_with_action中会拒绝调用方自行携带action字段的载荷返回invalid_parameters相关防御逻辑有单测params_with_action_rejects_caller_supplied_action佐证。输入契约format_cells 的完整参数表format_cells.input.v1.json 采用 JSON Schema draft-07声明了 6 个必填参数区间定位与 9 个可选的格式化参数均可为null。必填参数定位目标区间参数类型说明备注spreadsheet_idstring电子表格 ID与 Google Drive 文件 ID 相同可用 google-drive 的list_files按名称查找sheet_idinteger工作表tab的数字 ID注意不是工作表名称通过get_spreadsheet获取start_rowinteger起始行0 基、含例如第 1 行 0end_rowinteger结束行0 基、不含半开区间[start, end)start_columninteger起始列0 基、含例如 A 列 0end_columninteger结束列0 基、不含半开区间[start, end)行/列使用 0 基的半开区间inclusive start, exclusive end是理解该工具最重要的约定要格式化“第 1 行到第 3 行含”应写start_row: 0, end_row: 3要覆盖 A 到 D 四列应写start_column: 0, end_column: 4。该语义在 JSON Schema 描述、types.rs 的FormatCells变体字段注释以及 api.rs 的FormatOptions中保持一致。可选参数九种格式化维度参数类型含义有效取值/示例boldboolean | null加粗文本true/falseitalicboolean | null斜体文本true/falsefont_sizeinteger | null字号如11、14text_colorstring | null文本颜色hex如#FF0000#前缀可选background_colorstring | null背景颜色hex如#FFFF00horizontal_alignmentstring | null水平对齐LEFT、CENTER、RIGHTnumber_formatstring | null数字格式模式如#,##0.00、yyyy-mm-dd、0.00%number_format_typestring | null数字格式类型NUMBER、CURRENCY、PERCENT、DATE、TIME、TEXT两点重要约束所有可选参数均可省略或传null且未提供的维度不会被修改——工具不会“重置”既有格式而是只覆盖你显式指定的字段见下文fields掩码机制。number_format_type仅在同时提供number_format时生效单独提供number_format_type不会产生任何请求api.rs 中只在number_format分支内消费 type默认类型为NUMBER。一个可运行的完整载荷示例{ spreadsheet_id: abc123, sheet_id: 0, start_row: 0, end_row: 1, start_column: 0, end_column: 4, bold: true, background_color: #4285F4, text_color: #FFFFFF, horizontal_alignment: CENTER }该载荷把第一个工作表的首行表头A1:D1设为白字蓝底加粗并居中。此示例与 lib.rs 文档注释中的format_cells用例一致可直接作为调用蓝本。底层实现从输入到 batchUpdate 请求调用链概览format_cells的完整执行路径是宿主根据 capability idgoogle-sheets.format_cells从 manifest 加载工具定义并注入调用上下文WASM 访客端 lib.rs 的execute_inner解析FormatCells变体构造api::FormatOptions并调用api::format_cellsapi.rs 的format_cells把格式化选项编译为一个repeatCell请求通过batch_updatePOST 到https://sheets.googleapis.com/v4/spreadsheets/{id}:batchUpdate请求携带的fields字段掩码精确声明本次要更新的userEnteredFormat子路径未声明的格式维度保持不变。选项编译与颜色解析在format_cells内部api.rs格式化选项被逐项编译进userEnteredFormatbold/italic/font_size进入textFormat的bold、italic、fontSize键text_color经parse_hex_color把#RRGGBB十六进制转为 Sheets API 需要的 0.0–1.0 浮点分量{red, green, blue}写入textFormat.foregroundColor非法 hex长度非 6 或非十六进制字符会被静默忽略不产生对应字段background_color同样经parse_hex_color转为backgroundColorhorizontal_alignment原样写入horizontalAlignmentnumber_format与number_format_type组合为numberFormat: {type, pattern}。fields 掩码只改你要改的编译完成后代码维护一个fields列表按“实际设置了哪些选项”追加对应路径userEnteredFormat.textFormat仅当 bold/italic/font_size/text_color 任一被设置userEnteredFormat.backgroundColoruserEnteredFormat.horizontalAlignmentuserEnteredFormat.numberFormat最终请求结构为{ repeatCell: { range: { sheetId: 0, startRowIndex: 0, endRowIndex: 1, startColumnIndex: 0, endColumnIndex: 4 }, cell: { userEnteredFormat: { ...: ... } }, fields: userEnteredFormat.textFormat,userEnteredFormat.backgroundColor } }fields掩码确保repeatCell只覆写被请求的格式维度其余格式原样保留——这是“可选参数不重置既有格式”承诺的实现基础。空载荷防御no_formatting_options如果调用方只提供了必填的区间参数而未提供任何格式化选项api::format_cells会在发出任何网络请求前返回Input类错误错误码no_formatting_options消息 “No formatting options specified”。api.rs 中的单测format_cells_rejects_no_formatting_options明确验证了该行为kind ErrorKind::Input且code no_formatting_options。这意味着调用时至少应携带一个格式化参数否则工具会直接拒绝。权限、凭据与安全模型format_cells的 manifest 声明见 manifest.toml完整定义了其安全边界配置项值含义origin_gate_matrixloop_run gated_unless_granted,product forbidden,automation forbidden仅在 agent loop 运行上下文中可用且默认需要授权门控product/automation 来源一律禁止effects[network, use_secret, external_write]涉及网络请求、使用密钥、外部写入属于高风险工具default_permissionask默认每次调用向用户请求确认visibilitymodel工具只对模型可见不直接暴露给用户界面credentialsgoogle_runtime_tokenscopehttps://www.googleapis.com/auth/spreadsheets通过authorization: Bearer token头注入受众为sheets.googleapis.com几个值得注意的实现细节WASM 访客端永远看不到 OAuth 令牌。所有 API 调用都经由宿主的 HTTP capabilityhost::http_request由宿主负责凭据注入与限流api.rs 模块头注释明确说明。这意味着即便 WASM 被攻破令牌也不会泄露。401 响应被映射为AuthRequired错误码固定为google_api_error_status_401其余非 2xx 状态映射为Client错误错误码形如api_status_{status}如api_status_429。这些映射均有单测覆盖api_status_error_401_maps_to_auth_required、api_status_error_non_401_maps_to_client。写入类工具统一使用spreadsheets读写scope而只读工具read_values、get_spreadsheet、batch_read_values使用spreadsheets.readonly——format_cells与写值类工具同属前者。OAuth 配置[auth.google]采用oauth2_code PKCEs256authorization endpoint 为 Google 官方 OAuth 端点extra_authorize_params开启access_typeoffline、include_granted_scopes与promptconsent刷新令牌的 keepalive 周期为 604800 秒7 天注释说明这是为了赶在 Google “testing” 发布状态应用 7 天不活动过期策略之前主动刷新闲置账号。此外google-sheets属于 gsuite 扩展家族与 gmail、google-drive 等同属vendor.google其账号可见性遵循家族共享策略管理员配置的共享 Google 账号只有在对该家族精确授权后才对google-sheets可见相关逻辑见 account_policy.rs 及is_gsuite_extension_id判定。在扩展包中的装配方式format_cells工具并不是运行时动态发现的而是由宿主静态嵌入。google-sheets包的 manifest、prompts、schemas 与 WASM 二进制由ironclaw_extension_support的 packages 模块在编译期打包include_str!/include_bytes!见 packages/gsuite.rs。manifest 中format_cells条目显式引用了input_schema_ref schemas/google-sheets/format_cells.input.v1.jsonformat_cells.input.v1.jsonprompt_doc_ref prompts/google-sheets/format_cells.md即本文围绕的入口文档在 WASM 访客端schema()方法通过schemars::schema_for!(GoogleSheetsAction)从 Rust 类型自动推导 JSON Schema确保“对外广告的 schema 与 serde 契约永不同步漂移”lib.rs 注释。因此format_cells在types.rs中的FormatCells变体与format_cells.input.v1.json必须保持一致——两者当前也确实逐字段对应。典型使用场景与注意事项场景一表头美化对首行加粗、居中、设置品牌色背景上文完整载荷示例随后可将格式化后的表头作为后续write_values写入数据区域的视觉参照。场景二金额列数字格式{ spreadsheet_id: abc123, sheet_id: 0, start_row: 1, end_row: 20, start_column: 3, end_column: 4, number_format: #,##0.00, number_format_type: CURRENCY, horizontal_alignment: RIGHT }把 D2:D20 格式化为带千分位的货币格式并右对齐number_format_type显式声明为CURRENCY。场景三日期列格式{ spreadsheet_id: abc123, sheet_id: 0, start_row: 1, end_row: 100, start_column: 0, end_column: 1, number_format: yyyy-mm-dd, number_format_type: DATE }注意事项汇总区间是半开的end_row/end_column指向区间之后的第一行/列别把 A1:D1 写成end_column: 3那只会覆盖 A–C。sheet_id是数字 ID 而非名称须经google-sheets.get_spreadsheet获取用错 sheet 名会导致 API 报错。至少提供一个格式化选项否则收到no_formatting_options输入错误。只改显式指定的维度想“去掉加粗”应显式传bold: false而不是省略该字段。颜色只接受 6 位 hex#RRGGBB格式#可选非法值被静默忽略不会报错注意核对。该操作属于外部写入默认default_permission askagent loop 之外product/automation 来源被 manifest 门控矩阵禁止。验证与进一步探索包级说明与测试入口README.md 提到 manifest 投影测试cargo test -p ironclaw_extension_registry与 WASM 产物新鲜度检查python3 scripts/ci/check-wasm-artifact-freshness.py。完整参数契约format_cells.input.v1.json。实现与单测api.rsformat_cells、parse_hex_color、batch_update及 3 个相关单测、types.rsFormatCells变体与FormatResult、lib.rscapability 分发与参数防注入。权限与装配manifest.toml[[tools]]的google-sheets.format_cells条目与[auth.google]、account_policy.rsgsuite 家族账号可见性策略。结合入口文档、JSON Schema 与 WASM 源码google-sheets.format_cells的完整行为链条——从“宿主按 capability id 选择操作、调用方只提供 Schema 参数”到“repeatCell 请求与 fields 掩码的精确更新”——均可逐一在仓库中得到印证。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw google-sheets.write_values 能力详解向表格区域写入数据的 Prompt 契约、输入 Schema 与 WASM 实现IronClaw google sheets.write_values 能力详解向表格区域写入数据的 Prompt 契约、输入 Schema 与 WASM 实人工智能AI 应用交互助手AI AgentIronClaw Google Drive 扩展 upload_file 能力详解文本文件上传的输入契约与 WASM 实现IronClaw Google Drive 扩展 upload_file 能力详解文本文件上传的输入契约与 WASM 实现 IronClaw 是一个以隐私、安人工智能AI 应用交互助手AI AgentIronClaw Google Slides 扩展指南create_shape 能力契约、输入参数与 WASM 实现解析IronClaw Google Slides 扩展指南create_shape 能力契约、输入参数与 WASM 实现解析 在 IronClaw 的扩展体系中人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考