IronClaw Google Sheets 扩展 format_cells 能力详解：单元格格式化工具的输入契约与底层实现

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

本篇技术指南围绕 IronClaw 开源仓库中 Google Sheets 扩展包的核心工具format_cells（google-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 扩展协议的两条关键规则：

1. 能力由宿主（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输入错误。
2. 只提供输入 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）。

必填参数：定位目标区间

行/列使用 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中保持一致。

可选参数：九种格式化维度

两点重要约束：

• 所有可选参数均可省略或传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的完整执行路径是：

1. 宿主根据 capability idgoogle-sheets.format_cells从 manifest 加载工具定义并注入调用上下文；
2. WASM 访客端 lib.rs 的execute_inner解析FormatCells变体，构造api::FormatOptions并调用api::format_cells；
3. api.rs 的format_cells把格式化选项编译为一个repeatCell请求，通过batch_updatePOST 到https://sheets.googleapis.com/v4/spreadsheets/{id}:batchUpdate；
4. 请求携带的fields字段掩码精确声明本次要更新的userEnteredFormat子路径，未声明的格式维度保持不变。

选项编译与颜色解析

在format_cells内部（api.rs），格式化选项被逐项编译进userEnteredFormat：

• bold/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转为backgroundColor；
• horizontal_alignment原样写入horizontalAlignment；
• number_format与number_format_type组合为numberFormat: {type, pattern}。

fields 掩码：只改你要改的

编译完成后，代码维护一个fields列表，按“实际设置了哪些选项”追加对应路径：

• userEnteredFormat.textFormat（仅当 bold/italic/font_size/text_color 任一被设置）
• userEnteredFormat.backgroundColor
• userEnteredFormat.horizontalAlignment
• userEnteredFormat.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）完整定义了其安全边界：

几个值得注意的实现细节：

• WASM 访客端永远看不到 OAuth 令牌。所有 API 调用都经由宿主的 HTTP capability（host::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+ PKCE（s256），authorization endpoint 为 Google 官方 OAuth 端点，extra_authorize_params开启access_type=offline、include_granted_scopes与prompt=consent；刷新令牌的 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.json"（format_cells.input.v1.json）
• prompt_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" }

注意事项汇总

1. 区间是半开的：end_row/end_column指向区间之后的第一行/列，别把 A1:D1 写成end_column: 3（那只会覆盖 A–C）。
2. sheet_id是数字 ID 而非名称：须经google-sheets.get_spreadsheet获取；用错 sheet 名会导致 API 报错。
3. 至少提供一个格式化选项，否则收到no_formatting_options输入错误。
4. 只改显式指定的维度：想“去掉加粗”应显式传"bold": false，而不是省略该字段。
5. 颜色只接受 6 位 hex：#RRGGBB格式（#可选），非法值被静默忽略，不会报错，注意核对。
6. 该操作属于外部写入，默认default_permission = "ask"，agent 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.rs（format_cells、parse_hex_color、batch_update及 3 个相关单测）、types.rs（FormatCells变体与FormatResult）、lib.rs（capability 分发与参数防注入）。
• 权限与装配：manifest.toml（[[tools]]的google-sheets.format_cells条目与[auth.google]）、account_policy.rs（gsuite 家族账号可见性策略）。

结合入口文档、JSON Schema 与 WASM 源码，google-sheets.format_cells的完整行为链条——从“宿主按 capability id 选择操作、调用方只提供 Schema 参数”到“repeatCell 请求与 fields 掩码的精确更新”——均可逐一在仓库中得到印证。

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