From dc92b8857e91edb5dd506ef138c154fb73ca4845 Mon Sep 17 00:00:00 2001 From: ivanberry Date: Mon, 16 Mar 2026 21:48:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20uv=20requirement=20+=20run.sh=20a?= =?UTF-8?q?s=E5=94=AF=E4=B8=80=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 295 ++++++++----------------------------------------------- 1 file changed, 39 insertions(+), 256 deletions(-) diff --git a/SKILL.md b/SKILL.md index db07c6d..797581c 100644 --- a/SKILL.md +++ b/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 [args...] +``` -## 触发条件 +**不要直接使用 `python scripts/xxx.py`，会污染系统环境！** -当用户提及以下关键词时激活此技能： +## 可用脚本 -- Excel 相关：`excel`、`xlsx`、`电子表格`、`工作簿`、`工作表` -- 文件操作：`读取 excel`、`打开 excel`、`合并 excel`、`合并工作表` -- 数据处理：`筛选数据`、`排序数据`、`去重`、`替换内容`、`翻译单元格` -- **翻译相关**：`翻译 excel`、`中文转英文`、`translate excel`、`excel translation`、`翻译表格` -- 批量操作：`批量处理 excel`、`批量合并`、`批量替换` -- CSV 相关：`csv`、`csv 转 excel`、`excel 转 csv` -- **自扩展触发**：`计算`、`转换`、`透视`、`清洗`、`货币`、`汇率`、`公式`、`合并列`、`拆分列` +| 脚本 | 功能 | 示例 | +|------|------|------| +| `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 "计算每列总和"` | ## 核心功能 @@ -29,263 +39,36 @@ - 按行合并多个文件 - 按列合并多个文件 - 合并同一文件中的多个 sheet -- 合并多个文件的指定 sheet ### 3. 数据处理 - 单元格内容替换 - 批量替换（支持正则表达式） -- 数据筛选（按条件筛选行） -- 数据排序（按列排序） -- 数据去重（基于指定列） +- 数据筛选、排序、去重 -### 4. 🆕 翻译功能 -- **中文→英文翻译**：使用 Google Gemini Flash Lite API 翻译 Excel/CSV 中的中文内容 -- **智能检测**：自动检测包含中文字符的单元格 -- **批量处理**：支持批量翻译，提高效率 -- **保留格式**：保留原文件格式、样式、公式和结构 -- **灵活控制**：可指定特定列或工作表进行翻译 -- **预览模式**：支持 dry-run 预览，查看翻译范围 +### 4. 翻译功能 +- 中文→英文翻译（Google Gemini API） +- 智能检测中文字符 +- 保留原始格式 -### 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 文件 -python scripts/translate_excel.py --file data.xlsx +cd {baseDir} -# 翻译整个 CSV 文件 -python scripts/translate_excel.py --file data.csv +# 同步依赖 +uv sync + +# 添加新包 +uv add ``` -#### 指定输出文件 +## 环境变量 ```bash -python scripts/translate_excel.py --file data.xlsx --output translated.xlsx -``` - -#### 指定列翻译 - -```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：通过环境变量（推荐） +# Google Gemini API Key（翻译功能需要） 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 有速率限制，大批量翻译建议分批处理