excel-toolkit/SKILL.md

# Excel Toolkit - Excel 文件智能处理

## 技能描述

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

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

## 触发条件

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

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

## 核心功能

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

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

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

### 4. 🆕 翻译功能
- **中文→英文翻译**：使用 Google Gemini Flash Lite API 翻译 Excel/CSV 中的中文内容
- **智能检测**：自动检测包含中文字符的单元格
- **批量处理**：支持批量翻译，提高效率
- **保留格式**：保留原文件格式、样式、公式和结构
- **灵活控制**：可指定特定列或工作表进行翻译
- **预览模式**：支持 dry-run 预览，查看翻译范围

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

## 脚本说明

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

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

### 🆕 翻译脚本
- `translate_excel.py` - 翻译 Excel/CSV 中的中文内容为英文（使用 Google Gemini Flash Lite）

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

## 翻译功能详解

### 功能特性

- **自动检测中文**：使用正则表达式检测包含中文字符的单元格
- **批量翻译**：将多个单元格合并为一个 API 请求，提高效率
- **保留原始格式**：工作表结构、样式、公式完整保留
- **生成新文件**：不修改原文件，生成 `{原文件名}_en.xlsx` 或 `{原文件名}_en.csv`
- **灵活控制**：支持按列、按工作表指定翻译范围
- **预览模式**：`--dry-run` 参数可预览翻译范围而不实际生成文件

### 使用方法

#### 翻译整个文件

```bash
# 翻译整个 Excel 文件
python scripts/translate_excel.py --file data.xlsx

# 翻译整个 CSV 文件
python scripts/translate_excel.py --file data.csv
```

#### 指定输出文件

```bash
python scripts/translate_excel.py --file data.xlsx --output translated.xlsx
```

#### 指定列翻译

```bash
# 只翻译指定列
python scripts/translate_excel.py --file data.xlsx --columns "姓名,地址,备注"
```

#### 指定工作表（Excel）

```bash
python scripts/translate_excel.py --file data.xlsx --sheet "Sheet1"
```

#### 预览模式

```bash
# 查看将要翻译的内容，不生成文件
python scripts/translate_excel.py --file data.xlsx --dry-run
```

#### 使用自定义 API 密钥

```bash
# 方法 1：通过参数提供
python scripts/translate_excel.py --file data.xlsx --api-key "your-api-key"

# 方法 2：通过环境变量（推荐）
export GEMINI_API_KEY="your-api-key"
python scripts/translate_excel.py --file data.xlsx
```

#### 使用不同模型

```bash
# 使用其他 Gemini 模型
python scripts/translate_excel.py --file data.xlsx --model "gemini-2.0-flash-exp"
```

### API 密钥配置

翻译功能需要 Google Gemini API 密钥，配置方法：

1. **环境变量（推荐）**：
   ```bash
   export GEMINI_API_KEY="your-api-key-here"
   # 或
   export GOOGLE_API_KEY="your-api-key-here"
   ```

2. **命令行参数**：
   ```bash
   python scripts/translate_excel.py --file data.xlsx --api-key "your-api-key"
   ```

获取 API 密钥：https://aistudio.google.com/app/apikey

### 翻译策略

- **保留专有名词**：人名、地名、品牌名等保持原样
- **数字格式**：保留数字、日期、时间的原始格式
- **技术术语**：使用标准英文翻译技术术语
- **空值跳过**：自动跳过空单元格、数字、公式单元格

### 输出示例

```
输入文件: data.xlsx
输出文件: data_en.xlsx
翻译列: 姓名, 地址, 职位

翻译工作表 'Sheet1' 中的 25 个单元格...
已保存翻译结果到: data_en.xlsx

翻译统计 - data.xlsx
============================================================
总单元格数: 100
包含中文: 25
已翻译: 25
跳过: 75

工作表: Sheet1
  翻译列: 姓名, 地址, 职位
  总数: 25, 中文: 25, 已翻译: 25
```

## 🆕 自扩展能力详解

### 工作原理

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 (数据处理)
- **google-generativeai** (翻译功能，>=0.3.0)

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

## 注意事项

- 大文件处理可能需要较多内存
- 合并前请确保文件结构兼容
- 备份原始文件后再进行批量操作
- 公式可能在某些操作中丢失，建议保留原始文件
- 自扩展生成的脚本默认超时时间为 5 分钟
- 自动生成的脚本可能需要手动调整参数以适应特定需求
- **翻译功能**：
  - 需要配置 Google Gemini API 密钥
  - 大量翻译可能产生 API 费用
  - 建议先用 `--dry-run` 预览翻译范围
  - Gemini Flash Lite 有速率限制，大批量翻译建议分批处理