Excel Toolkit

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

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

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

功能特性

基础功能

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

🆕 翻译功能

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

🆕 自扩展功能

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

安装依赖

pip install -r requirements.txt

使用说明

1. 读取 Excel/CSV 文件

# 读取文件并显示前 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. 合并多个文件

# 按行合并（纵向拼接）
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. 替换单元格内容

# 简单替换
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. 筛选、排序、去重

# 筛选数据
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. 批量处理

# 批量替换
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 将中文内容翻译为英文。

基础用法

# 翻译整个文件（自动生成 {原文件名}_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

指定翻译范围

# 只翻译指定列
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 "员工信息"

预览模式

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

API 密钥配置

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

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

高级选项

# 使用不同的 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 是自扩展能力的核心，通过自然语言描述自动生成并执行脚本。

工作流程

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

使用示例

货币转换

# 美元转人民币
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"

数据透视汇总

# 按地区汇总销售额
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"

数据清洗

# 基本清洗
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"

列计算

# 两列相乘
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=新价格"

列合并/拆分

# 合并列
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=姓,名"

预览模式

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

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

脚本缓存机制

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

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

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

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

清空缓存：

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 密钥：

# 环境变量（推荐）
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。

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 镜像加速依赖安装：

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

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

pyproject.toml 已包含镜像配置：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

环境变量配置

方式 1: 使用 .env 文件（推荐）

在项目根目录创建 .env 文件：

# .env
GEMINI_API_KEY=your-api-key-here

脚本会自动加载 .env 文件中的环境变量。

注意: .env 文件已添加到 .gitignore，不会被提交到 git。

方式 2: 命令行设置

export GEMINI_API_KEY="your-api-key"
uv run python scripts/translate_excel.py --file data.xlsx

方式 3: 命令行参数

uv run python scripts/translate_excel.py --file data.xlsx --api-key your-api-key

获取 API Key

访问：https://aistudio.google.com/app/apikey