docs: add uv requirement + run.sh as唯一入口

SKILL.md

@@ -1,22 +1,32 @@
+---
+name: excel-toolkit
+description: "Excel 文件智能处理工具，支持读取、合并、编辑、筛选、翻译等操作"
+metadata: {"openclaw":{"requires":{"bins":["uv"]},"install":[{"kind":"uv","label":"Install uv"}]}}
+---
+
 # Excel Toolkit - Excel 文件智能处理
 
-## 技能描述
+## ⚠️ 调用方式（必须遵守）
 
-提供 Excel 文件的智能处理功能，包括读取、合并、编辑、筛选、翻译等操作。支持 .xlsx 和 .csv 格式，可批量处理多个文件。
+**所有脚本必须通过 `{baseDir}/run.sh` 执行，确保使用 uv 虚拟环境：**
 
-**核心特性：自扩展能力** - 遇到不支持的操作时，自动生成并执行临时脚本。
+```bash
+{baseDir}/run.sh <script_name> [args...]
+```
 
-## 触发条件
+**不要直接使用 `python scripts/xxx.py`，会污染系统环境！**
 
-当用户提及以下关键词时激活此技能：
+## 可用脚本
 
-- Excel 相关：`excel`、`xlsx`、`电子表格`、`工作簿`、`工作表`
+| 脚本 | 功能 | 示例 |
-- 文件操作：`读取 excel`、`打开 excel`、`合并 excel`、`合并工作表`
+|------|------|------|
-- 数据处理：`筛选数据`、`排序数据`、`去重`、`替换内容`、`翻译单元格`
+| `read_excel` | 读取 Excel/CSV | `./run.sh read_excel --file data.xlsx` |
-- **翻译相关**：`翻译 excel`、`中文转英文`、`translate excel`、`excel translation`、`翻译表格`
+| `merge_excel` | 合并多个文件 | `./run.sh merge_excel --files a.xlsx b.xlsx` |
-- 批量操作：`批量处理 excel`、`批量合并`、`批量替换`
+| `replace_cells` | 替换内容 | `./run.sh replace_cells --file data.xlsx --old "旧" --new "新"` |
-- CSV 相关：`csv`、`csv 转 excel`、`excel 转 csv`
+| `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 "计算每列总和"` |
 
 ## 核心功能
 
@@ -29,263 +39,36 @@
 - 按行合并多个文件
 - 按列合并多个文件
 - 合并同一文件中的多个 sheet
-- 合并多个文件的指定 sheet
 
 ### 3. 数据处理
 - 单元格内容替换
 - 批量替换（支持正则表达式）
-- 数据筛选（按条件筛选行）
+- 数据筛选、排序、去重
-- 数据排序（按列排序）
-- 数据去重（基于指定列）
 
-### 4. 🆕 翻译功能
+### 4. 翻译功能
-- **中文→英文翻译**：使用 Google Gemini Flash Lite API 翻译 Excel/CSV 中的中文内容
+- 中文→英文翻译（Google Gemini API）
-- **智能检测**：自动检测包含中文字符的单元格
+- 智能检测中文字符
-- **批量处理**：支持批量翻译，提高效率
+- 保留原始格式
-- **保留格式**：保留原文件格式、样式、公式和结构
-- **灵活控制**：可指定特定列或工作表进行翻译
-- **预览模式**：支持 dry-run 预览，查看翻译范围
 
-### 5. 🆕 自扩展功能
+### 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 文件
+cd {baseDir}
-python scripts/translate_excel.py --file data.xlsx
 
-# 翻译整个 CSV 文件
+# 同步依赖
-python scripts/translate_excel.py --file data.csv
+uv sync
+
+# 添加新包
+uv add <package-name>
 ```
 
-#### 指定输出文件
+## 环境变量
 
 ```bash
-python scripts/translate_excel.py --file data.xlsx --output translated.xlsx
+# Google Gemini API Key（翻译功能需要）
-```
-
-#### 指定列翻译
-
-```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 有速率限制，大批量翻译建议分批处理