excel-toolkit/SKILL.md

# Excel Toolkit - Excel 文件智能处理

## 技能描述

提供 Excel 文件的智能处理功能，包括读取、合并、编辑、筛选等操作。支持 .xlsx 和 .csv 格式，可批量处理多个文件。

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

## 触发条件

当用户提及以下关键词时激活此技能：

- Excel 相关：`excel`、`xlsx`、`电子表格`、`工作簿`、`工作表`
- 文件操作：`读取 excel`、`打开 excel`、`合并 excel`、`合并工作表`
- 数据处理：`筛选数据`、`排序数据`、`去重`、`替换内容`、`翻译单元格`
- 批量操作：`批量处理 excel`、`批量合并`、`批量替换`
- CSV 相关：`csv`、`csv 转 excel`、`excel 转 csv`
- **自扩展触发**：`计算`、`转换`、`透视`、`清洗`、`货币`、`汇率`、`公式`、`合并列`、`拆分列`

## 核心功能

### 1. 基础文件操作
- 读取 Excel 文件（.xlsx, .csv）
- 创建新的 Excel 文件
- 保存和导出

### 2. 合并功能
- 按行合并多个文件
- 按列合并多个文件
- 合并同一文件中的多个 sheet
- 合并多个文件的指定 sheet

### 3. 数据处理
- 单元格内容替换
- 批量替换（支持正则表达式）
- 数据筛选（按条件筛选行）
- 数据排序（按列排序）
- 数据去重（基于指定列）

### 4. 🆕 自扩展功能
- **自动脚本生成**：根据自然语言需求自动生成处理脚本
- **模板复用**：常用操作使用预置模板，确保稳定可靠
- **智能缓存**：相同需求自动复用已生成的脚本
- **灵活扩展**：无模板时自动生成通用脚本框架

## 脚本说明

所有脚本位于 `scripts/` 目录，使用 Python 编写：

### 基础脚本
- `read_excel.py` - 读取 Excel 文件并显示内容
- `merge_excel.py` - 合并多个 Excel 文件
- `replace_cells.py` - 替换单元格内容
- `filter_data.py` - 筛选和排序数据
- `batch_process.py` - 批量处理多个文件

### 🆕 自扩展脚本
- `auto_script.py` - 核心脚本引擎，分析需求并生成/执行脚本

## 🆕 自扩展能力详解

### 工作原理

1. **需求分析**：解析用户的自然语言描述
2. **模板匹配**：检查是否有可用的脚本模板
3. **脚本生成**：
   - 有模板：使用模板 + 参数生成
   - 无模板：自动生成通用脚本框架
4. **执行并缓存**：执行脚本并保存到 `temp_scripts/` 供复用
5. **结果返回**：输出执行结果和统计信息

### 可用模板

模板位于 `script_templates/` 目录：

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

### 自然语言触发示例

```bash
# 货币转换
python scripts/auto_script.py "把金额列从美元转换为人民币，汇率7.2" --file sales.xlsx --output converted.xlsx

# 数据透视
python scripts/auto_script.py "按地区和产品透视汇总销售额" --file sales.xlsx --output summary.xlsx --group_by "地区,产品" --agg_column "销售额" --agg_func "sum"

# 数据清洗
python scripts/auto_script.py "清洗数据，删除空行并去除空格" --file data.xlsx --output cleaned.xlsx --drop_na --strip_whitespace

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

# 仅生成不执行（预览）
python scripts/auto_script.py "计算利润" --dry-run
```

### 脚本缓存

相同需求会自动复用已生成的脚本，存储位置：
- `temp_scripts/script_[hash].py`
- 哈希值基于需求描述生成
- 手动清理：删除 `temp_scripts/` 目录

## 基础功能使用示例

### 读取 Excel
```bash
python scripts/read_excel.py /path/to/file.xlsx
```

### 合并文件
```bash
# 按行合并
python scripts/merge_excel.py --mode row file1.xlsx file2.xlsx output.xlsx

# 按列合并
python scripts/merge_excel.py --mode col file1.xlsx file2.xlsx output.xlsx
```

### 替换内容
```bash
python scripts/replace_cells.py input.xlsx "旧值" "新值" output.xlsx
```

### 筛选数据
```bash
python scripts/filter_data.py input.xlsx --filter "列A > 100" --sort "列B" output.xlsx
```

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

## 技术依赖

- Python 3.8+
- openpyxl (读写 .xlsx)
- pandas (数据处理)

安装依赖：
```bash
pip install -r requirements.txt
```

## 注意事项

- 大文件处理可能需要较多内存
- 合并前请确保文件结构兼容
- 备份原始文件后再进行批量操作
- 公式可能在某些操作中丢失，建议保留原始文件
- 自扩展生成的脚本默认超时时间为 5 分钟
- 自动生成的脚本可能需要手动调整参数以适应特定需求