Excel

快速开始

# Bash/Linux/macOS
scripts/excel-reader <excel_file> [sheet_name]

# PowerShell/Windows
scripts/excel-reader.ps1 <excel_file> [sheet_name]

参数说明

输出格式

执行成功后，会在源文件所在目录生成两个文件：

Success: <文件名>
Markdown: <源文件目录>/<文件名>.excel_reader.md
JSON: <源文件目录>/<文件名>.excel_reader.json

输出文件命名规则：

• 源文件 demo.xlsx → 输出 demo.excel_reader.md 和 demo.excel_reader.json
• 源文件 /path/to/data.xlsx → 输出 /path/to/data.excel_reader.md 和 /path/to/data.excel_reader.json

Markdown 文件：包含格式化的表格，适合直接阅读。

JSON 文件：包含完整元数据（合并单元格信息、数据类型等），适合程序处理。

读取示例

# 读取所有 sheets
scripts/excel-reader data.xlsx
# 输出:
# Success: data.xlsx
# Markdown: /current/path/data.excel_reader.md
# JSON: /current/path/data.excel_reader.json

# 读取指定 sheet
scripts/excel-reader data.xlsx "销售数据"

# 查看生成的 Markdown
cat data.excel_reader.md

功能特性

合并单元格支持：自动识别合并单元格，左上角包含实际值，其他标记为 merged。

数据类型识别：自动识别 string、number、boolean、date、empty、merged 类型。

多 Sheet 支持：不指定 sheet_name 时读取所有 sheets，指定时只读取指定 sheet。

功能二：创建 Excel

通过 JSON 文件描述表格结构，生成带样式的标准 Excel 文件。

工作流程

1. AI 模型从任意来源（网页、文档、API 等）获取数据
2. AI 模型理解数据后，生成 JSON 格式文件描述 Excel 结构
3. 调用脚本将 JSON 转换为带样式的 Excel 文件

快速开始

# Bash/Linux/macOS
scripts/excel-writer <input.json> [output.xlsx]

# PowerShell/Windows
scripts/excel-writer.ps1 <input.json> [output.xlsx]

参数说明

JSON 格式规范

{
  "sheets": [
    {
      "name": "员工信息",
      "title": "2024年度员工信息表",
      "headers": ["姓名", "年龄", "部门", "入职日期"],
      "data": [
        ["张三", 28, "技术部", "2022-03-15"],
        ["李四", 32, "市场部", "2020-08-01"],
        ["王五", 25, "技术部", "2023-01-10"]
      ],
      "column_widths": [12, 8, 12, 15],
      "merge_cells": []
    }
  ]
}

字段说明

*data 和 headers 至少提供一个，否则该 sheet 会被跳过。

数据类型自动转换

JSON 中的值会自动转换为 Excel 原生类型：

• 数字字符串 "25" → Excel 数字 25
• 浮点字符串 "3.14" → Excel 数字 3.14
• 纯文本 → Excel 文本
• null → 空单元格
• 布尔值 → Excel 布尔值

默认样式

创建的 Excel 文件自动包含以下样式：

创建示例

最简示例（无标题无表头）：

{
  "sheets": [
    {
      "data": [
        ["张三", 25, "北京"],
        ["李四", 30, "上海"]
      ]
    }
  ]
}

完整示例（多 Sheet、标题、表头、列宽）：

{
  "sheets": [
    {
      "name": "销售数据",
      "title": "2024年Q1销售报表",
      "headers": ["产品", "销量", "单价", "销售额"],
      "data": [
        ["产品A", 150, 29.9, 4485],
        ["产品B", 200, 19.9, 3980],
        ["产品C", 80, 49.9, 3992]
      ],
      "column_widths": [15, 10, 10, 12]
    },
    {
      "name": "汇总",
      "headers": ["指标", "数值"],
      "data": [
        ["总销量", 430],
        ["总销售额", 12457]
      ]
    }
  ]
}

使用方式：

# 将 JSON 数据写入文件后调用
scripts/excel-writer data.json report.xlsx
# 输出:
# Success: /path/to/report.xlsx

# 不指定输出路径，默认生成同目录同名 .xlsx
scripts/excel-writer data.json
# 输出:
# Success: /path/to/data.xlsx

AI 使用模式

当用户需要将任意数据创建为 Excel 时：

1. 收集数据：从用户提供的信息、文件、网页等来源获取结构化数据
2. 生成 JSON：将数据组织为上述 JSON 格式，保存为临时文件（如 .tmp/data.json）
3. 调用脚本：执行 scripts/excel-writer .tmp/data.json [output.xlsx]
4. 告知用户：输出 Excel 文件路径

依赖要求

• Python 3.12+
• openpyxl
• uv（用于依赖管理）

首次运行会自动初始化虚拟环境并安装依赖。

常见问题

文件不存在（读取）

Error: Excel file not found: /path/to/file.xlsx

检查文件路径是否正确。

不支持的格式（读取）

Error: Unsupported file format: .xls

只支持 .xlsx 和 .xlsm 格式，不支持旧版 .xls。

Sheet 不存在（读取）

Error: Sheet 'Data' not found. Available sheets: Sheet1, Sheet2

使用列出的可用 sheet 名称。

JSON 格式错误（创建）

Error: Invalid JSON format: Expecting value: line 1 column 1

检查 JSON 文件语法是否正确。

缺少 sheets 配置（创建）

Error: 'sheets' array is required and must not be empty

JSON 必须包含 sheets 数组且至少一个 sheet 配置。