# Excel2MD
**Repository Path**: simon1239/excel2-md
## Basic Information
- **Project Name**: Excel2MD
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-31
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Excel2MD
**Excel 处理逻辑逆向解析工具**
自动将 Excel 文件中的公式、VBA 宏、依赖关系转化为结构化的 Markdown 技术文档
[快速开始](#快速开始) • [功能特性](#功能特性) • [使用文档](#使用文档) • [API 文档](#api-文档)
---
## 介绍
Excel2MD 是一款专为后端开发、数据开发和业务系统迁移工程师设计的工具，能够精准提取 Excel 全链路数据处理逻辑，完成「Excel 公式 → 自然语言描述 → 目标代码片段」的自动转译，解决 Excel 逻辑黑盒问题。
### 核心价值
- **逻辑透明化** — 将隐藏在 Excel 单元格中的公式逻辑转化为可读文档
- **业务理解** — 自动生成公式业务逻辑的自然语言描述
- **代码迁移** — 直接输出可执行的 Pandas DataFrame 代码
- **风险识别** — 自动检测硬编码、循环引用、VBA 高危操作
### 适用场景
- 🔄 业务系统迁移时理解 Excel 计算逻辑
- 📊 数据开发人员对接 Excel 数据处理流程
- 🔍 代码审查时验证计算逻辑正确性
- 📚 构建 Excel 文件的自动化技术文档
---
## 功能特性
### 核心功能
| 功能 | 说明 | 状态 |
|------|------|------|
| 📄 **多格式支持** | 支持 `.xlsx` 和 `.xlsm` 文件 | ✅ v1.0 |
| 🔗 **依赖分析** | 构建单元格依赖关系 DAG 图，检测循环引用 | ✅ v1.0 |
| 📝 **公式解析** | 全量提取公式原文，识别绝对/相对/混合引用 | ✅ v1.0 |
| 🤖 **VBA 解析** | 提取 `.xlsm` 中的 VBA 宏代码，解析过程/函数 | ✅ v1.0 |
| 🌐 **自然语言转译** | 将公式转译为中文业务逻辑描述 | ✅ v1.0 |
| 🐍 **代码生成** | 输出可执行的 Python Pandas DataFrame 代码 | ✅ v1.0 |
| ⚠️ **风险检测** | 检测硬编码常量、外部引用、高危 VBA 操作 | ✅ v1.0 |
| 📊 **Mermaid 图表** | 生成 Sheet 间数据流图和公式依赖图 | ✅ v1.0 |
### 支持的函数
Excel2MD 支持 **80+** 常用 Excel 函数的转译，包括但不限于：
- **聚合函数**: SUM, AVERAGE, COUNT, MAX, MIN, SUMIF, SUMIFS, COUNTIF, COUNTIFS
- **查找函数**: VLOOKUP, HLOOKUP, INDEX, MATCH, LOOKUP
- **逻辑函数**: IF, IFS, AND, OR, NOT
- **文本函数**: LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER
- **日期函数**: TODAY, NOW, YEAR, MONTH, DAY
- **数学函数**: ROUND, INT, MOD, POWER, SQRT
对于不支持的函数，系统会优雅降级为「函数名 + 参数列表」格式。
### 输出文档结构
生成的 Markdown 文档包含以下模块：
1. **文档概览** — 文件基础信息、Sheet 清单、统计数据
2. **Sheet 间数据流图** — Mermaid 可视化依赖关系
3. **工作表逻辑详情** — 每个 Sheet 的：
- 基础信息（使用范围、行数、列数）
- 核心公式表（原始公式、业务描述、Pandas 代码）
- 公式业务逻辑详解（业务含义、引用单元格）
4. **VBA 模块详情**（如有） — 宏代码、逻辑说明、风险标记
5. **风险分级表** — 按高/中/低风险分类展示检测到的风险点
---
## 软件架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 五层流水线架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 接入层 (Access Layer) │
│ └─ ExcelFileLoader — 文件加载与校验 │
│ │
│ 2. 解析层 (Parse Layer) │
│ ├─ SheetParser — Sheet 信息提取 │
│ ├─ CellParser — 单元格解析 │
│ ├─ FormulaParser — 公式解析 │
│ └─ VbaParser — VBA 宏提取 │
│ │
│ 3. 分析层 (Analyze Layer) │
│ ├─ DependencyAnalyzer — DAG 依赖分析 │
│ ├─ FormulaNLTranslator — 自然语言转译 │
│ ├─ FormulaCodeGenerator — 代码生成 │
│ └─ RiskDetector — 风险检测 │
│ │
│ 4. 渲染层 (Render Layer) │
│ └─ MarkdownGenerator — 模板渲染 │
│ │
│ 5. 输出层 (Output Layer) │
│ └─ 文件写入 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 技术栈
| 组件 | 技术 | 版本要求 | 用途 |
|------|------|----------|------|
| 核心语言 | Python | 3.9+ | 项目主语言 |
| Excel 解析 | openpyxl | ≥3.1.0 | .xlsx/.xlsm 文件读取 |
| 公式分析 | pycel | ≥1.0b30 | 公式编译与依赖提取 |
| 依赖图 | networkx | ≥2.0,<2.7 | DAG 构建与拓扑排序 |
| VBA 提取 | oletools | ≥0.60.1 | .xlsm 宏代码提取 |
| 模板引擎 | Jinja2 | ≥3.1.0 | Markdown 模板渲染 |
| 代码生成 | pandas | ≥2.0.0 | DataFrame 代码片段 |
| CLI 框架 | click | ≥8.0.0 | 命令行工具 |
| 测试框架 | pytest | ≥8.0.0 | 单元测试 |
---
## 快速开始
### 环境要求
- Python 3.9 或更高版本
- pip 包管理器
### 安装
#### 方式一：使用 pip 安装（推荐）
```bash
pip install excel2md
```
#### 方式二：从源码安装
```bash
# 克隆仓库
git clone https://github.com/yourusername/Excel2MD.git
cd Excel2MD
# 安装依赖
pip install -r requirements.txt
# 安装项目
pip install -e .
```
### 验证安装
```bash
# 查看版本信息
excel2md --version
# 预期输出
# Excel2MD v1.0.0
```
---
## 使用文档
### CLI 命令行工具
#### 基础用法
```bash
# 最简用法：解析 Excel 文件并生成 Markdown 文档
excel2md --input data.xlsx --output logic_doc.md
```
#### 完整参数
```bash
excel2md \
--input data.xlsm \
--output report.md \
--enable-vba \
--enable-code-gen \
--enable-risk-detect \
--template custom_template.md.j2 \
--verbose
```
#### 参数说明
| 参数 | 短参数 | 类型 | 默认值 | 说明 |
|------|---------|--------|------|
| `--input` | `-i` | **必填** | 输入的 Excel 文件路径（支持 .xlsx/.xlsm） |
| `--output` | `-o` | **必填** | 输出的 Markdown 文档路径 |
| `--enable-vba` | - | `False` | 开启 VBA 宏解析（用于 .xlsm 文件） |
| `--enable-code-gen` | - | `True` | 开启 Python 代码生成 |
| `--enable-risk-detect` | - | `True` | 开启风险点检测 |
| `--template` | `-t` | `None` | 自定义 Markdown 模板路径（Jinja2 格式） |
| `--verbose` | `-v` | `False` | 开启详细日志输出 |
| `--version` | - | - | 显示版本信息 |
| `--help` | - | - | 显示帮助信息 |
#### 使用示例
**示例 1：基础 Excel 解析**
```bash
# 解析普通 Excel 文件
excel2md -i ./财务报表.xlsx -o ./财务逻辑.md
```
**示例 2：包含 VBA 宏的文件**
```bash
# 解析包含宏的 Excel 文件
excel2md -i ./业务系统.xlsm -o ./系统文档.md --enable-vba
```
**示例 3：详细模式调试**
```bash
# 开启详细日志查看处理过程
excel2md -i ./test.xlsx -o ./output.md -v
```
**示例 4：自定义模板**
```bash
# 使用自定义模板生成文档
excel2md -i ./data.xlsx -o ./custom.md -t ./my_template.md.j2
```
### Python SDK
#### 基础用法
```python
from excel2md import Excel2MDExecutor
# 使用默认配置
executor = Excel2MDExecutor()
result = executor.run(
excel_path="./data.xlsx",
output_path="./output.md"
)
if result['success']:
print("处理成功！")
print(f"公式数量: {result['parse_summary']['formula_count']}")
print(f"耗时: {result['execute_time']}秒")
else:
print(f"处理失败: {result['error_msg']}")
```
#### 自定义配置
```python
from excel2md import Excel2MDExecutor
# 自定义配置
config = {
'enable_vba_parse': True, # 开启 VBA 解析
'enable_code_generation': True, # 开启代码生成
'enable_risk_detect': True, # 开启风险检测
'enable_mermaid_graph': True, # 开启 Mermaid 图表
'custom_template_path': './my_template.md.j2', # 自定义模板
'lazy_load': False, # 懒加载模式
}
executor = Excel2MDExecutor(config=config)
result = executor.run(
excel_path="./data.xlsm",
output_path="./output.md"
)
```
#### 获取执行日志
```python
from excel2md import Excel2MDExecutor
executor = Excel2MDExecutor()
result = executor.run(excel_path="./data.xlsx", output_path="./output.md")
# 获取详细执行日志
logs = executor.get_execute_log()
for log in logs:
print(f"[LOG] {log}")
```
#### 处理结果
```python
{
'success': True,
'execute_time': 1.23,
'md_file_size': 4567,
'parse_summary': {
'sheet_count': 3,
'formula_count': 45,
'vba_module_count': 2,
'risk_count': 5,
'circular_deps': 0
},
'warning_list': [],
'error_msg': None
}
```
---
## 输出示例
以下是一个生成的 Markdown 文档示例：
### 文档概览
| 指标 | 值 |
| :--- | :--- |
| 工作表总数 | 3 |
| 公式总数 | 45 |
| VBA 模块数 | 2 |
| 检测到的风险点 | 5 |
### 公式业务逻辑
| 单元格地址 | 原始公式 | 业务逻辑描述 | Pandas 代码 |
| :--- | :--- | :--- | :--- |
| D2 | `=SUMIF(B:B,"已付款",C:C)` | 对 B 列中值为"已付款"的行，求和对应 C 列的数值 | ```python\n# 对 B 列中值为"已付款"的行，求和对应 C 列的数值\ndf.loc[df['B'] == '已付款', 'C'].sum()\n``` |
| E5 | `=VLOOKUP(A2,Sheet2!A:B,2,FALSE)` | 在 Sheet2 的 A:B 范围中查找 A2，返回第 2 列的值（精确匹配） | ```python\n# 在 Sheet2 的 A:B 范围中查找 A2，返回第 2 列的值（精确匹配）\nlookup_value = df['A'].iloc[0]\nlookup_df = pd.read_excel('Sheet2.xlsx')\nresult = lookup_df.loc[lookup_df['A'] == lookup_value, 'B'].iloc[0]\n``` |
### 风险分级表
| 风险等级 | 描述 | 位置 |
| :--- | :--- | :--- |
| 🔴 高 | 检测到循环引用：A1 ↔ B1 | A1, B1 |
| 🟡 中 | 硬编码常量：3.14 | C5 |
| 🟢 低 | 空值无处理 | D10 |
---
## 开发与测试
### 运行测试
```bash
# 运行所有测试
pytest
# 运行特定测试文件
pytest tests/test_parsers.py
# 运行测试并生成覆盖率报告
pytest --cov=excel2md --cov-report=html
```
### 项目结构
```
excel2md/
├── excel2md/
│ ├── __init__.py
│ ├── cli.py # CLI 入口
│ ├── executor.py # 主执行器
│ ├── core/
│ │ ├── base.py # 抽象基类
│ │ ├── loader.py # Excel 文件加载
│ │ ├── parsers/ # 解析器模块
│ │ ├── analyzers/ # 分析器模块
│ │ └── generator.py # Markdown 生成
│ └── templates/ # Jinja2 模板
├── tests/
│ ├── test_loader.py
│ ├── test_parsers.py
│ ├── test_analyzers.py
│ └── test_integration.py
├── requirements.txt
├── setup.py
└── README.md
```
---
## 常见问题
### Q: 支持 .xls 格式吗？
A: 不支持。Excel2MD 仅支持 `.xlsx` 和 `.xlsm` 格式，这是基于 openxml 的现代 Excel 格式，提供更好的公式解析能力。
### Q: 如何处理加密的 Excel 文件？
A: 当前版本不支持加密文件。如需处理，请先在 Excel 中取消密码保护，再使用 Excel2MD 解析。
### Q: 生成的 Pandas 代码可以直接运行吗？
A: 可以。生成的代码是基于 Pandas DataFrame 的完整代码片段，可以直接复制到 Python 环境中执行。但对于跨表引用的场景，需要确保相关的 DataFrame 已正确加载。
### Q: VBA 宏函数会被转译吗？
A: 当前版本不会转译 VBA 函数，只会提取并展示宏代码原文，标记其中的 Excel 公式调用和高危操作。VBA 函数转译计划在 v1.0+ 版本中支持。
### Q: 如何处理非常大的 Excel 文件？
A: 对于 10 万行级的大文件，建议在配置中启用 `lazy_load` 模式以减少内存占用。大文件性能优化计划在 v1.1 版本中实现。
### Q: Windows 控制台显示乱码怎么办？
A: 这是 Windows 控制台编码（GBK）与 UTF-8 不匹配的问题。输出文件本身是正确的 UTF-8 编码，仅在控制台显示时可能出现乱码，不影响实际结果。
---
## 参与贡献
我们欢迎任何形式的贡献！
### 贡献流程
1. **Fork** 本仓库
2. 创建特性分支 (`git checkout -b feat/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feat/AmazingFeature`)
5. 创建 Pull Request
### 提交规范
提交信息请遵循以下格式：
```
():