\n 使用 YAML 生成专业 Excel 文档\n
\n\n\n 特性 •\n 安装 •\n 快速开始 •\n 文档 •\n 示例\n
\n\n---\n\n## 简介\n\nExcel Creator 是一个强大的 Excel 文档生成工具，通过 YAML 格式定义文档结构和样式，自动生成专业的 Microsoft Excel (.xlsx) 文档。采用严格的样式白名单机制，确保生成的文档风格一致、格式规范。\n\n## 特性\n\n- 🎯 **严格的样式约束** - 预定义样式白名单，防止样式不一致\n- 📝 **YAML 格式** - 结构清晰，易于编写和维护\n- ✅ **自动验证** - 内置验证器确保格式正确\n- 🎨 **丰富的格式支持** - 单元格样式、合并单元格、多级表头\n- 📊 **数据可视化** - 支持柱状图、折线图、饼图、雷达图等多种图表\n- 🔍 **数据验证** - 支持下拉列表、数字范围、日期范围验证\n- 📄 **标准输出** - 生成标准 .xlsx 文件，兼容 Microsoft Excel\n\n## 技术栈\n\n- **Python 3.8+** - 核心运行时\n- **XlsxWriter** - Excel 文档生成\n- **PyYAML** - YAML 解析\n\n## 安装\n\n### 环境要求\n\n- **Python** 3.8 或更高版本\n\n### 安装依赖\n\n```bash\ncd python\npip install -r requirements.txt\n```\n\n### MCP 配置\n\n将 Excel Creator 配置到你的 AI 客户端中：\n\n#### Claude Desktop\n\n编辑 `claude_desktop_config.json`：\n\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"excel-creator\": {\n \"command\": \"python\",\n \"args\": [\n \"C:/path/to/excel-creator/python/server.py\"\n ]\n }\n }\n}\n```\n\n#### Cursor\n\n在 Cursor 设置中找到 MCP 配置，添加：\n\n```json\n{\n \"mcpServers\": {\n \"excel-creator\": {\n \"command\": \"python\",\n \"args\": [\n \"C:/path/to/excel-creator/python/server.py\"\n ]\n }\n }\n}\n```\n\n## 快速开始\n\n### 1. AI 使用流程（4步）\n\n```\nget-excel-guide → 生成 YAML → validate-yaml → convert-yaml-to-excel\n```\n\n### 2. 创建 YAML 文件\n\n```yaml\nversion: \"1.0\"\nmetadata:\n title: \"销售报表\"\n author: \"张三\"\n\nsheets:\n - name: \"月度销售\"\n config:\n columnWidths:\n A: 12\n B: 18\n C: 18\n defaultStyle:\n fontSize: 11\n fontFamily: \"微软雅黑\"\n \n styles:\n header:\n fontSize: 12\n bold: true\n bgColor: darkBlue\n color: white\n align: center\n valign: center\n border: true\n currency:\n format: \"currency\"\n align: right\n valign: center\n \n rows:\n - height: 28\n cells:\n - content: \"月份\"\n style: header\n - content: \"销售额\"\n style: header\n - content: \"占比\"\n style: header\n \n - cells:\n - content: \"1月\"\n align: center\n valign: center\n - content: 85000\n style: currency\n - content: \"=B2/SUM($B$2:$B$7)\"\n format: \"percent_2\"\n```\n\n### 3. 命令行使用\n\n```bash\ncd python\npython yaml_to_excel.py input.yaml output.xlsx\n```\n\n### 4. Python API\n\n```python\nfrom yaml_document import ExcelDocument\nfrom yaml_to_excel import ExcelConverter\n\n# 读取 YAML\nwith open('input.yaml', 'r', encoding='utf-8') as f:\n yaml_content = f.read()\n\ndocument = ExcelDocument.from_yaml(yaml_content)\n\n# 转换\nconverter = ExcelConverter()\nconverter.convert(document, 'output.xlsx')\n```\n\n## 核心功能\n\n### 样式白名单\n\n所有样式值必须来自预定义白名单：\n\n| 属性 | 可选值 | 示例 |\n|------|--------|------|\n| `fontSize` | 8, 10, 11, 12, 14, 16, 18, 20, 22, 24 | `fontSize: 12` |\n| `fontFamily` | 微软雅黑, 宋体, 黑体, 楷体, Arial, Calibri, Consolas | `fontFamily: \"微软雅黑\"` |\n| `color` | black, white, red, blue, green, yellow, darkBlue, lightBlue... | `color: red` |\n| `align` | left, center, right | `align: center` |\n| `valign` | top, center, bottom | `valign: center` |\n| `format` | currency, percent, number, date... | `format: currency` |\n\n### 支持的图表类型\n\n| 类型 | 说明 |\n|------|------|\n| `bar` | 柱状图（垂直） |\n| `barh` | 条形图（水平） |\n| `line` | 折线图 |\n| `pie` | 饼图 |\n| `scatter` | 散点图 |\n| `area` | 面积图 |\n| `radar` | 雷达图 |\n\n## 示例\n\n### 多级表头\n\n```yaml\nsheets:\n - name: \"学生成绩表\"\n headerRows:\n - cells:\n - content: \"年级\"\n style: header\n rowspan: 2\n - content: \"语文\"\n style: header\n colspan: 2\n - cells:\n - content: \"平时\"\n style: subheader\n - content: \"期末\"\n style: subheader\n rows:\n - cells:\n - content: \"高一\"\n - content: 85\n - content: 90\n```\n\n### 图表\n\n```yaml\ncharts:\n - type: bar\n title: \"月度销售额\"\n position: \"E2\"\n width: 15\n height: 10\n data:\n categories: \"A2:A7\"\n series:\n - name: \"销售额\"\n values: \"B2:B7\"\n xAxis:\n title: \"月份\"\n yAxis:\n title: \"销售额（元）\"\n```\n\n### 数据验证\n\n```yaml\nvalidations:\n - range: \"A2:A100\"\n type: \"list\"\n formula: \"产品A,产品B,产品C\"\n allowEmpty: true\n showError: true\n errorTitle: \"输入错误\"\n errorMessage: \"请从列表中选择\"\n```\n\n## 文档\n\n- [AI 使用指南](AI_USAGE_GUIDE.md) - 详细的 AI 使用说明\n- [功能文档](python/FUNCTIONS.md) - 完整的格式规范\n\n## 项目结构\n\n```\nexcel-creator/\n├── python/\n│ ├── server.py # MCP 服务器\n│ ├── yaml_schema.py # YAML 格式定义（含白名单）\n│ ├── yaml_document.py # 文档模型\n│ ├── yaml_validator.py # 验证器\n│ ├── yaml_to_excel.py # 转换器\n│ └── sample/ # 示例文档\n├── AI_USAGE_GUIDE.md # AI 使用指南\n├── FUNCTIONS.md # 功能文档\n└── README.md # 本文档\n```\n\n## MCP 工具\n\n本项目提供 MCP (Model Context Protocol) 工具供 AI 使用：\n\n| 工具 | 说明 |\n|------|------|\n| `get-excel-guide` | **【第一步】获取完整使用指南** |\n| `get-yaml-schema` | 获取 YAML 格式规范 |\n| `validate-yaml` | 验证 YAML 格式 |\n| `convert-yaml-to-excel` | 转换为 XLSX |\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 许可证\n\n[MIT](LICENSE)\n\n---\n\n\n Made with ❤️ for better Excel generation\n
\n","readmeFilename":"README.md","_rev":"1-54abfdb918fd2c79378c49e98d28143c"}