544 lines
15 KiB
Markdown
544 lines
15 KiB
Markdown
# 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"
|
||
```
|