---
name: excel-toolkit
description: "Excel 文件智能处理工具，支持读取、合并、编辑、筛选、翻译等操作"
---
> Auth (CLIENT_KEY) is loaded automatically from `~/.openclaw/.env`.

# Excel Toolkit - Excel 文件智能处理

## 调用方式（重要！）

**必须使用 `uv run` 或 `./run.sh` 调用，确保虚拟环境隔离：**

```bash
cd ~/Documents/ai-build-app/skills/excel-toolkit

# 方式 1：使用统一入口脚本（推荐）
./run.sh <script_name> [args...]

# 方式 2：直接使用 uv run
uv run python scripts/<script_name>.py [args...]

# ❌ 不要直接使用 python scripts/xxx.py（会污染系统环境）
```

## 可用脚本

| 脚本 | 功能 | 示例 |
|------|------|------|
| `read_excel` | 读取 Excel/CSV | `./run.sh read_excel --file data.xlsx` |
| `merge_excel` | 合并多个文件 | `./run.sh merge_excel --files a.xlsx b.xlsx` |
| `replace_cells` | 替换内容 | `./run.sh replace_cells --file data.xlsx --old "旧" --new "新"` |
| `filter_data` | 筛选排序 | `./run.sh filter_data --file data.xlsx --column "姓名" --value "张三"` |
| `batch_process` | 批量处理 | `./run.sh batch_process --dir ./files --replace "旧\|新"` |
| `translate_excel` | 翻译中→英 | `./run.sh translate_excel --file data.xlsx` |
| `auto_script` | 自扩展 | `./run.sh auto_script --prompt "计算每列总和"` |

## 完整命令参考

### 1. 读取 Excel/CSV

```bash
./run.sh read_excel --file data.xlsx --rows 10
./run.sh read_excel --file data.csv --all --json
```

### 2. 合并 Excel

```bash
./run.sh merge_excel --files file1.xlsx file2.xlsx --output merged.xlsx
./run.sh merge_excel --dir ./files --output merged.xlsx
```

### 3. 替换内容

```bash
./run.sh replace_cells --file data.xlsx --old "旧值" --new "新值"
./run.sh replace_cells --file data.xlsx --regex "旧值\|新值"
```

### 4. 筛选数据

```bash
./run.sh filter_data --file data.xlsx --column "姓名" --value "张三"
./run.sh filter_data --file data.xlsx --sort "年龄" --desc
```

### 5. 批量处理

```bash
./run.sh batch_process --dir ./files --replace "旧\|新"
./run.sh batch_process --dry-run --replace "旧值\|新值"
```

### 6. 翻译 Excel/CSV

```bash
# 基础翻译
./run.sh translate_excel --file data.xlsx

# 指定列
./run.sh translate_excel --file data.xlsx --columns "姓名，地址，备注"

# 预览模式
./run.sh translate_excel --file data.xlsx --dry-run
```

## 依赖管理

```bash
# 首次使用或添加新依赖
uv sync

# 添加新包
uv add <package-name>

# 运行任意命令（自动使用虚拟环境）
uv run python scripts/xxx.py
```

## 环境变量

```bash
# Google Gemini API Key（翻译功能需要）
export GEMINI_API_KEY="your-api-key"
export GOOGLE_API_KEY="your-api-key"
```