适用场景

当智能体必须交付一个 .xlsx Excel 文件时使用 —— 例如销售报表、查询结果、多工作表数据导出、财务汇总，或任何需要专业电子表格格式的结构化数据。本技能**仅支持工作簿创建**，不可用于读取、编辑或保留现有 Excel 文件。

环境配置

python3 -m venv ~/.openclaw/workspace/.venv_excel
~/.openclaw/workspace/.venv_excel/bin/pip install xlsxwriter

无需凭证（credentials）。

执行方式

~/.openclaw/workspace/.venv_excel/bin/python skills/excel-export/scripts/build_xlsx.py 
  --input   
  --output 

默认导出目录：~/.openclaw/workspace/exports/excel/。

执行成功后，脚本将向标准输出（stdout）打印一份 JSON 汇总信息：

{
  "success": true,
  "output": "/absolute/path/to/report.xlsx",
  "sheets": [
    { "sheet": "Ventes", "rows": 42 },
    { "sheet": "Charges", "rows": 18 }
  ]
}

输入格式

输入为单个 JSON 文件，顶层结构如下：

{
  "sheets": [ ... ]
}

每个工作表对象定义如下：

每个列对象定义如下：

数据行（rows）是**以列 key 为键的对象（object）**，而非位置索引数组（positional array）。缺失的键将生成空白单元格；出现未知键则触发校验错误。

列类型

可在任意列上使用 numfmt 字段，以覆盖其类型对应的默认格式。

渲染规则

布局 — 固定、确定性、不可按工作表单独配置：

• 无标题/副标题 → 表格表头位于第 1 行。
• 仅有标题 → 标题位于第 1 行，第 2 行为空行，表头位于第 3 行。
• 含标题 + 副标题 → 标题位于第 1 行，副标题位于第 2 行，第 3 行为空行，表头位于第 4 行。

冻结窗格 — 始终冻结在首行数据行（根据是否存在标题，对应 A2、A4 或 A5）。

表格样式 — 每个工作表均为一个矩形 Excel 表格：启用筛选器、斑马纹行（banded rows），并应用样式 Table Style Medium 9。

列宽 — 自动基于列头和采样值估算，上限为 50 字符；若列定义中指定了 width，则优先采用该显式值。

公式 — 使用 Excel 结构化引用（如 =[@Revenue]/SUM([Revenue])）。公式列通过表格定义注入，而非逐单元格写入，因此会自动应用于所有数据行。

汇总行 — 若任一列设置了 total，则表格将包含汇总行。第一列默认显示 “Total” 标签，除非该列自身也定义了 total 函数。

空数据集 — 将生成一个合法的工作簿，包含表头、筛选器、样式，但数据行为零。

数据完整性准则

以下规则强制执行，不可跳过或禁用：

1. 保留原始数据类型。 带前导零的字符串、电话号码（如 +212…）、长度超过 15 位的数字字符串，一律以文本形式存储。若作为数字写入 Excel，将被静默损坏。

2. 计算逻辑保留在 Excel 中。 当工作簿需保持可交互状态时，应写入公式而非 Python 预计算的静态值。使用结构化引用，确保公式在插入/删除行后仍有效。

3. 日期必须显式处理。 Excel 日期本质为带历史兼容问题的序列号。本脚本写入真实的日期对象，并显式应用 dd/mm/yyyy 格式 — 绝不写入原始序列号或歧义字符串。

4. 交付前严格校验。 脚本对每个输入字段进行校验，拒绝未知键，并在出错时快速失败、给出清晰错误信息。工作簿绝不可因静默丢数而发布。

5. 区域默认设置为法语 / 摩洛哥。 日期格式为 dd/mm/yyyy，货币单位为 MAD，布尔值显示为 Oui / Non。注意：最终显示效果仍部分取决于用户本地 Excel 的区域设置。

完整示例

{
  "sheets": [
    {
      "name": "Ventes Q1",
      "title": "Rapport des Ventes — Q1 2026",
      "subtitle": "Direction Commerciale",
      "columns": [
        { "key": "region",  "header": "Région",     "type": "text" },
        { "key": "ca",      "header": "CA (MAD)",   "type": "currency", "total": "sum" },
        { "key": "volume",  "header": "Volume",     "type": "integer",  "total": "sum" },
        { "key": "growth",  "header": "Croissance", "type": "percent" },
        { "key": "date",    "header": "Date",       "type": "date" },
        { "key": "active",  "header": "Actif",      "type": "boolean" }
      ],
      "rows": [
        { "region": "Casablanca", "ca": 1250000, "volume": 340, "growth": 0.15, "date": "2026-03-31", "active": true },
        { "region": "Rabat",      "ca": 980000,  "volume": 210, "growth": -0.03, "date": "2026-03-31", "active": true },
        { "region": "Tanger",     "ca": 670000,  "volume": 155, "growth": 0.08,  "date": "2026-03-31", "active": false }
      ]
    }
  ]
}

~/.openclaw/workspace/.venv_excel/bin/python skills/excel-export/scripts/build_xlsx.py 
  --input  ~/.openclaw/workspace/exports/ventes_q1.json 
  --output ~/.openclaw/workspace/exports/excel/ventes_q1.xlsx

校验规则

脚本将在以下情况中快速失败，并输出明确错误信息：

• JSON 格式非法或缺失
• 工作表名称重复
• 工作表名称超过 31 字符、包含 [ ] : * ? / 字符，或以单引号（'）开头/结尾
• 存在 subtitle 但未提供 title
• 行数超过 1,048,576 或列数超过 16,384
• 行对象中存在未知键
• type 或 total 值非法
• formula 定义非字符串类型
• 布尔值无法识别（仅接受 true/false、1/0、yes/no、oui/non）
• integer 列中出现非整数值（例如 12.9 将被拒绝，而非截断）
• 日期、日期时间或数值型列中存在无法解析的内容

基于 SQL 的导出

若从 SQL 查询结果生成 Excel 文件，请阅读 references/SQL_TO_EXCEL_RECIPE.md 中的标准流水线文档：使用 mssql 执行查询 → 规范化数据值 → 构建 JSON 规格 → 渲染输出。该文档涵盖 SQL 到 JSON 的类型映射、规范化规则、开箱即用模板及常见错误。

限制（v1 版）

• 仅支持创建工作簿 — 不支持读取或编辑已有工作簿。
• 不支持模板保留、合并单元格或条件格式。
• 仅有一种固定视觉主题 — 不支持自定义配色系统。
• 不支持 CSV 输入 — 上游步骤必须生成 JSON。
• xlsxwriter 不执行公式计算；接收方 Excel 客户端在打开文件时重新计算。