excel-toolkit/README.md

# Excel Toolkit

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

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

**🆕 新特性：翻译功能** - 使用 Google Gemini Flash Lite API 翻译 Excel/CSV 中的中文内容为英文。

## 功能特性

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

### 🆕 翻译功能
- ✅ 中文→英文翻译（Google Gemini Flash Lite）
- ✅ 自动检测中文内容
- ✅ 批量翻译，提高效率
- ✅ 保留原始格式、样式、公式
- ✅ 支持按列、按工作表指定翻译范围
- ✅ 预览模式（dry-run）
- ✅ 生成独立新文件

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

## 安装依赖

```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. 翻译 Excel/CSV 文件

使用 Google Gemini Flash Lite API 将中文内容翻译为英文。

#### 基础用法

```bash
# 翻译整个文件（自动生成 {原文件名}_en.xlsx）
python scripts/translate_excel.py --file data.xlsx

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

# 指定输出文件名
python scripts/translate_excel.py --file data.xlsx --output translated.xlsx
```

#### 指定翻译范围

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

# 只翻译指定工作表
python scripts/translate_excel.py --file data.xlsx --sheet "Sheet1"

# 组合使用
python scripts/translate_excel.py --file data.xlsx --columns "姓名,职位" --sheet "员工信息"
```

#### 预览模式

```bash
# 预览翻译范围，不生成文件
python scripts/translate_excel.py --file data.xlsx --dry-run
```

#### API 密钥配置

翻译功能需要 Google Gemini API 密钥，支持以下配置方式：

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

# 方法 2：命令行参数
python scripts/translate_excel.py --file data.xlsx --api-key "your-api-key"

# 方法 3：使用 GOOGLE_API_KEY 环境变量
export GOOGLE_API_KEY="your-api-key-here"
python scripts/translate_excel.py --file data.xlsx
```

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

#### 高级选项

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

# 完整示例
python scripts/translate_excel.py \\
  --file employees.xlsx \\
  --output employees_en.xlsx \\
  --columns "姓名,部门,职位" \\
  --sheet "2024年度" \\
  --model "gemini-2.0-flash-lite"
```

#### 翻译策略

- **自动检测中文**：使用正则表达式 `[\u4e00-\u9fff]` 检测中文字符
- **保留专有名词**：人名、地名、品牌名保持原样
- **数字格式不变**：保留数字、日期、时间的原始格式
- **批量处理**：将多个单元格合并为一个 API 请求，提高效率
- **跳过非文本**：自动跳过空单元格、数字、公式单元格

#### 输出示例

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

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

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

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

#### 注意事项

- 翻译功能需要配置有效的 Google Gemini API 密钥
- Gemini Flash Lite 有速率限制，大批量翻译建议分批处理
- 翻译可能会产生 API 费用，建议先用 `--dry-run` 预览翻译范围
- 翻译是生成新文件，不会修改原文件
- 复杂的专业术语可能需要人工校对

### 🆕 7. 自扩展功能

`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` | 批量处理多个文件 |

### 🆕 翻译脚本

| 脚本 | 功能 |
|------|------|
| `translate_excel.py` | 翻译 Excel/CSV 中的中文内容为英文 |

### 🆕 自扩展脚本

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

## 目录结构

```
excel-toolkit/
├── SKILL.md                   # 技能定义文件
├── README.md                  # 本文件
├── requirements.txt           # Python 依赖
├── scripts/                   # 脚本目录
│   ├── auto_script.py        # 🆕 自扩展核心脚本
│   ├── translate_excel.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` 预览
- 建议备份原始文件
- 公式在某些操作中可能会丢失

### 🆕 翻译功能
- 需要配置 Google Gemini API 密钥
- 翻译可能会产生 API 费用
- Gemini Flash Lite 有速率限制
- 大批量翻译建议分批处理
- 复杂专业术语可能需要人工校对
- 建议先用 `--dry-run` 预览翻译范围

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

## 技术栈

- Python 3.8+
- pandas - 数据处理
- openpyxl - Excel 文件读写
- **google-generativeai** - Gemini API（翻译功能）

## 常见问题

### Q: 如何配置翻译功能的 API 密钥？

A: 支持以下方式配置 Google Gemini API 密钥：

```bash
# 环境变量（推荐）
export GEMINI_API_KEY="your-api-key-here"

# 或使用 GOOGLE_API_KEY
export GOOGLE_API_KEY="your-api-key-here"

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

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

### Q: 翻译功能是否收费？

A: Google Gemini API 是收费服务，具体费率请参考：
https://ai.google.dev/pricing

建议先用 `--dry-run` 预览翻译范围，控制 API 调用次数。

### 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

## 中国镜像配置

本项目已配置使用清华大学 PyPI 镜像加速依赖安装：

```bash
# 使用 uv 安装依赖（推荐）
uv pip install -r requirements.txt

# 或手动指定镜像
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

pyproject.toml 已包含镜像配置：
```toml
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
```