excel-toolkit/README.md

# Excel Toolkit

Excel 文件智能处理工具包，提供读取、合并、编辑、筛选等操作。

**🆕 新特性：自扩展能力** - 遇到不支持的操作时，自动生成并执行临时脚本。

## 功能特性

### 基础功能
- ✅ 读取 Excel (.xlsx) 和 CSV 文件
- ✅ 合并多个文件（按行/按列/按 sheet）
- ✅ 单元格内容替换（支持正则表达式）
- ✅ 数据筛选、排序、去重
- ✅ 批量处理多个文件
- ✅ 自动检测表头
- ✅ 处理合并单元格
- ✅ 支持中文路径和内容

### 🆕 自扩展功能
- ✅ 自然语言需求理解
- ✅ 自动脚本生成和执行
- ✅ 预置模板库（货币转换、数据透视、清洗、计算、合并拆分）
- ✅ 智能脚本缓存和复用
- ✅ 无模板时自动生成通用框架

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用说明

### 1. 读取 Excel/CSV 文件

```bash
# 读取文件并显示前 10 行
python scripts/read_excel.py --file data.xlsx

# 指定 sheet
python scripts/read_excel.py --file data.xlsx --sheet "Sheet2"

# 显示所有行
python scripts/read_excel.py --file data.csv --all

# JSON 格式输出
python scripts/read_excel.py --file data.xlsx --json
```

### 2. 合并多个文件

```bash
# 按行合并（纵向拼接）
python scripts/merge_excel.py --mode row file1.xlsx file2.xlsx merged.xlsx

# 按列合并（横向拼接）
python scripts/merge_excel.py --mode col file1.xlsx file2.xlsx merged.xlsx

# 合并特定 sheet
python scripts/merge_excel.py --mode sheet --sheet "Sheet1" file1.xlsx file2.xlsx merged.xlsx
```

### 3. 替换单元格内容

```bash
# 简单替换
python scripts/replace_cells.py --input data.xlsx --search "旧值" --replace "新值" --output output.xlsx

# 正则表达式替换
python scripts/replace_cells.py --input data.csv --search "\\d{4}-\\d{2}-\\d{2}" --replace "YYYY-MM-DD" --regex --output output.csv

# 替换特定列
python scripts/replace_cells.py --input data.xlsx --search "北京" --replace "上海" --column "城市"
```

### 4. 筛选、排序、去重

```bash
# 筛选数据
python scripts/filter_data.py --input data.xlsx --output filtered.xlsx --filter "年龄 > 30"

# 筛选并排序
python scripts/filter_data.py --input data.csv --output result.csv --filter "薪资 > 10000" --sort "薪资" --sort-desc

# 去重
python scripts/filter_data.py --input data.xlsx --output unique.xlsx --dedup "姓名"

# 组合操作
python scripts/filter_data.py --input data.xlsx --output final.xlsx --filter "部门 == \"技术部\"" --sort "入职日期" --dedup "工号"
```

### 5. 批量处理

```bash
# 批量替换
python scripts/batch_process.py --replace "旧值|新值" --pattern "*.xlsx"

# 批量筛选和排序
python scripts/batch_process.py --filter "年龄 > 30" --sort "薪资" --sort-desc --pattern "data/*.xlsx"

# 递归处理子目录
python scripts/batch_process.py --recursive --replace "北京|上海" --pattern "*.xlsx"

# 预览模式（不实际修改）
python scripts/batch_process.py --dry-run --replace "旧值|新值"
```

### 🆕 6. 自扩展功能

`auto_script.py` 是自扩展能力的核心，通过自然语言描述自动生成并执行脚本。

#### 工作流程

```
用户自然语言需求 
    → 分析需求关键词
    → 查找匹配的模板
    → 生成或复用脚本
    → 执行并返回结果
    → 缓存脚本供复用
```

#### 使用示例

##### 货币转换

```bash
# 美元转人民币
python scripts/auto_script.py "把金额列从美元转换为人民币，汇率7.2" \\
  --file sales.xlsx \\
  --output converted.xlsx \\
  --param "column=金额" \\
  --param "from_currency=USD" \\
  --param "to_currency=CNY" \\
  --param "rate=7.2"

# 批量货币转换
python scripts/auto_script.py "将所有价格列从欧元转换为美元" \\
  --file products.xlsx \\
  --output usd_products.xlsx \\
  --param "column=价格" \\
  --param "from_currency=EUR" \\
  --param "to_currency=USD" \\
  --param "rate=1.08"
```

##### 数据透视汇总

```bash
# 按地区汇总销售额
python scripts/auto_script.py "按地区透视汇总销售额" \\
  --file sales.xlsx \\
  --output summary.xlsx \\
  --param "group_by=地区" \\
  --param "agg_column=销售额" \\
  --param "agg_func=sum"

# 多维度汇总
python scripts/auto_script.py "按地区和产品汇总销售额和数量" \\
  --file sales.xlsx \\
  --output pivot.xlsx \\
  --param "group_by=地区,产品" \\
  --param "agg_column=销售额" \\
  --param "agg_func=sum"
```

##### 数据清洗

```bash
# 基本清洗
python scripts/auto_script.py "清洗数据，删除空行并去除空格" \\
  --file raw_data.xlsx \\
  --output cleaned.xlsx \\
  --param "drop_na=true" \\
  --param "strip_whitespace=true"

# 高级清洗
python scripts/auto_script.py "清洗数据，删除空行、填充缺失值、去除空格、标准化日期" \\
  --file messy.xlsx \\
  --output clean.xlsx \\
  --param "drop_na=true" \\
  --param "fill_na_value=0" \\
  --param "strip_whitespace=true" \\
  --param "standardize_date=true"
```

##### 列计算

```bash
# 两列相乘
python scripts/auto_script.py "计算总价 = 单价 * 数量" \\
  --file products.xlsx \\
  --output result.xlsx \\
  --param "operation=multiply" \\
  --param "column1=单价" \\
  --param "column2=数量" \\
  --param "result_column=总价"

# 列加减常量
python scripts/auto_script.py "给所有价格增加 10%" \\
  --file prices.xlsx \\
  --file output.xlsx \\
  --param "operation=multiply" \\
  --param "column1=价格" \\
  --param "value=1.1" \\
  --param "result_column=新价格"
```

##### 列合并/拆分

```bash
# 合并列
python scripts/auto_script.py "将姓和名列合并为姓名" \\
  --file users.xlsx \\
  --file merged.xlsx \\
  --param "operation=merge" \\
  --param "merge_columns=姓,名" \\
  --param "merge_separator=" \\
  --param "result_column=姓名"

# 拆分列
python scripts/auto_script.py "将姓名列拆分为姓和名" \\
  --file users.xlsx \\
  --file split.xlsx \\
  --param "operation=split" \\
  --param "split_column=姓名" \\
  --param "split_separator=" \\
  --param "new_columns=姓,名"
```

##### 预览模式

```bash
# 仅生成脚本不执行
python scripts/auto_script.py "计算利润" --dry-run

# JSON 格式输出
python scripts/auto_script.py "清洗数据" --output-format json
```

#### 脚本缓存机制

相同的需求会自动复用已生成的脚本，避免重复生成：

```bash
# 第一次执行：生成并执行脚本
python scripts/auto_script.py "计算总价 = 单价 * 数量" --file data.xlsx

# 第二次执行相同需求：直接复用已有脚本
python scripts/auto_script.py "计算总价 = 单价 * 数量" --file data2.xlsx
```

缓存文件位置：`temp_scripts/script_[hash].py`

清空缓存：
```bash
rm -rf temp_scripts/
```

#### 可用模板

| 模板 | 功能 | 关键词 |
|------|------|--------|
| `currency_convert.py` | 货币/汇率转换 | 货币、汇率、转换、currency、convert |
| `pivot_summary.py` | 数据透视汇总 | 透视、汇总、聚合、pivot、summary |
| `data_clean.py` | 数据清洗 | 清洗、去空、格式化、clean |
| `column_calc.py` | 列计算 | 计算、加减乘除、公式、calc、calculate |
| `merge_columns.py` | 列合并/拆分 | 合并列、拆分、split、join |

## 脚本说明

### 基础脚本

| 脚本 | 功能 |
|------|------|
| `read_excel.py` | 读取并显示 Excel/CSV 文件内容 |
| `merge_excel.py` | 合并多个 Excel/CSV 文件 |
| `replace_cells.py` | 替换单元格内容 |
| `filter_data.py` | 筛选、排序、去重数据 |
| `batch_process.py` | 批量处理多个文件 |

### 🆕 自扩展脚本

| 脚本 | 功能 |
|------|------|
| `auto_script.py` | 核心脚本引擎，分析需求并生成/执行脚本 |

## 目录结构

```
excel-toolkit/
├── SKILL.md                   # 技能定义文件
├── README.md                  # 本文件
├── requirements.txt           # Python 依赖
├── scripts/                   # 脚本目录
│   ├── auto_script.py        # 🆕 自扩展核心脚本
│   ├── read_excel.py         # 读取 Excel
│   ├── merge_excel.py        # 合并文件
│   ├── replace_cells.py      # 替换内容
│   ├── filter_data.py        # 筛选数据
│   └── batch_process.py      # 批量处理
├── script_templates/          # 🆕 脚本模板库
│   ├── currency_convert.py   # 货币转换模板
│   ├── pivot_summary.py     # 数据透视模板
│   ├── data_clean.py        # 数据清洗模板
│   ├── column_calc.py       # 列计算模板
│   └── merge_columns.py     # 列合并拆分模板
└── temp_scripts/              # 🆕 临时脚本缓存目录
```

## 注意事项

### 基础功能
- 处理大文件可能需要较多内存
- 合并前请确保文件结构兼容
- 批量操作前建议先使用 `--dry-run` 预览
- 建议备份原始文件
- 公式在某些操作中可能会丢失

### 🆕 自扩展功能
- 自动生成的脚本默认超时时间为 5 分钟
- 无模板时生成的脚本需要手动调整才能完成复杂逻辑
- 脚本缓存基于需求哈希值，修改需求会生成新脚本
- 建议在正式使用前先用 `--dry-run` 预览脚本
- 模板参数可能需要根据具体文件调整

## 技术栈

- Python 3.8+
- pandas - 数据处理
- openpyxl - Excel 文件读写

## 常见问题

### Q: 自扩展功能支持哪些操作？

A: 支持以下模板操作：
- 货币/汇率转换
- 数据透视汇总
- 数据清洗（去空、格式化）
- 列计算（加减乘除、公式）
- 列合并/拆分

对于其他操作，系统会生成一个通用脚本框架，需要手动补充具体实现。

### Q: 如何查看生成的临时脚本？

A: 脚本保存在 `temp_scripts/` 目录，命名格式为 `script_[hash].py`。

```bash
ls temp_scripts/
cat temp_scripts/script_[hash].py
```

### Q: 如何自定义脚本模板？

A: 在 `script_templates/` 目录创建新的模板文件，然后在 `auto_script.py` 的 `DEMAND_MAPPING` 中添加映射关系。

### Q: 脚本执行超时怎么办？

A: 默认超时时间是 300 秒（5 分钟），可以在 `auto_script.py` 的 `execute_script` 函数中调整 `timeout` 参数。

## License

MIT