Excel Creator

简介

Excel Creator 是一个强大的 Excel 文档生成工具，通过 YAML 格式定义文档结构和样式，自动生成专业的 Microsoft Excel (.xlsx) 文档。采用严格的样式白名单机制，确保生成的文档风格一致、格式规范。

特性

• 🎯 严格的样式约束 - 预定义样式白名单，防止样式不一致
• 📝 YAML 格式 - 结构清晰，易于编写和维护
• ✅ 自动验证 - 内置验证器确保格式正确
• 🎨 丰富的格式支持 - 单元格样式、合并单元格、多级表头
• 📊 数据可视化 - 支持柱状图、折线图、饼图、雷达图等多种图表
• 🔍 数据验证 - 支持下拉列表、数字范围、日期范围验证
• 📄 标准输出 - 生成标准 .xlsx 文件，兼容 Microsoft Excel

技术栈

• Python 3.8+ - 核心运行时
• XlsxWriter - Excel 文档生成
• PyYAML - YAML 解析

安装

环境要求

• Python 3.8 或更高版本

安装依赖

cd python
pip install -r requirements.txt

MCP 配置

将 Excel Creator 配置到你的 AI 客户端中：

Claude Desktop

编辑 claude_desktop_config.json：

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "excel-creator": {
      "command": "python",
      "args": [
        "C:/path/to/excel-creator/python/server.py"
      ]
    }
  }
}

Cursor

在 Cursor 设置中找到 MCP 配置，添加：

{
  "mcpServers": {
    "excel-creator": {
      "command": "python",
      "args": [
        "C:/path/to/excel-creator/python/server.py"
      ]
    }
  }
}

快速开始

1. AI 使用流程（4步）

get-excel-guide → 生成 YAML → validate-yaml → convert-yaml-to-excel

2. 创建 YAML 文件

version: "1.0"
metadata:
  title: "销售报表"
  author: "张三"

sheets:
  - name: "月度销售"
    config:
      columnWidths:
        A: 12
        B: 18
        C: 18
      defaultStyle:
        fontSize: 11
        fontFamily: "微软雅黑"
    
    styles:
      header:
        fontSize: 12
        bold: true
        bgColor: darkBlue
        color: white
        align: center
        valign: center
        border: true
      currency:
        format: "currency"
        align: right
        valign: center
    
    rows:
      - height: 28
        cells:
          - content: "月份"
            style: header
          - content: "销售额"
            style: header
          - content: "占比"
            style: header
      
      - cells:
          - content: "1月"
            align: center
            valign: center
          - content: 85000
            style: currency
          - content: "=B2/SUM($B$2:$B$7)"
            format: "percent_2"

3. 命令行使用

cd python
python yaml_to_excel.py input.yaml output.xlsx

4. Python API

from yaml_document import ExcelDocument
from yaml_to_excel import ExcelConverter

# 读取 YAML
with open('input.yaml', 'r', encoding='utf-8') as f:
    yaml_content = f.read()

document = ExcelDocument.from_yaml(yaml_content)

# 转换
converter = ExcelConverter()
converter.convert(document, 'output.xlsx')

核心功能

样式白名单

所有样式值必须来自预定义白名单：

| 属性 | 可选值 | 示例 | |------|--------|------| | fontSize | 8, 10, 11, 12, 14, 16, 18, 20, 22, 24 | fontSize: 12 | | fontFamily | 微软雅黑, 宋体, 黑体, 楷体, Arial, Calibri, Consolas | fontFamily: "微软雅黑" | | color | black, white, red, blue, green, yellow, darkBlue, lightBlue... | color: red | | align | left, center, right | align: center | | valign | top, center, bottom | valign: center | | format | currency, percent, number, date... | format: currency |

支持的图表类型

| 类型 | 说明 | |------|------| | bar | 柱状图（垂直） | | barh | 条形图（水平） | | line | 折线图 | | pie | 饼图 | | scatter | 散点图 | | area | 面积图 | | radar | 雷达图 |

示例

多级表头

sheets:
  - name: "学生成绩表"
    headerRows:
      - cells:
          - content: "年级"
            style: header
            rowspan: 2
          - content: "语文"
            style: header
            colspan: 2
      - cells:
          - content: "平时"
            style: subheader
          - content: "期末"
            style: subheader
    rows:
      - cells:
          - content: "高一"
          - content: 85
          - content: 90

图表

charts:
  - type: bar
    title: "月度销售额"
    position: "E2"
    width: 15
    height: 10
    data:
      categories: "A2:A7"
    series:
      - name: "销售额"
        values: "B2:B7"
    xAxis:
      title: "月份"
    yAxis:
      title: "销售额（元）"

数据验证

validations:
  - range: "A2:A100"
    type: "list"
    formula: "产品A,产品B,产品C"
    allowEmpty: true
    showError: true
    errorTitle: "输入错误"
    errorMessage: "请从列表中选择"

文档

• AI 使用指南 - 详细的 AI 使用说明
• 功能文档 - 完整的格式规范

项目结构

excel-creator/
├── python/
│   ├── server.py              # MCP 服务器
│   ├── yaml_schema.py         # YAML 格式定义（含白名单）
│   ├── yaml_document.py       # 文档模型
│   ├── yaml_validator.py      # 验证器
│   ├── yaml_to_excel.py       # 转换器
│   └── sample/                # 示例文档
├── AI_USAGE_GUIDE.md          # AI 使用指南
├── FUNCTIONS.md               # 功能文档
└── README.md                  # 本文档

MCP 工具

本项目提供 MCP (Model Context Protocol) 工具供 AI 使用：

| 工具 | 说明 | |------|------| | get-excel-guide | 【第一步】获取完整使用指南 | | get-yaml-schema | 获取 YAML 格式规范 | | validate-yaml | 验证 YAML 格式 | | convert-yaml-to-excel | 转换为 XLSX |

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT