141 lines
3.0 KiB
Markdown
141 lines
3.0 KiB
Markdown
---
|
|
name: excel-operations
|
|
description: Read, write, and manipulate Excel (.xlsx) and CSV files
|
|
---
|
|
|
|
## When to use
|
|
Use when the user asks to:
|
|
- Read data from Excel or CSV files
|
|
- Create new spreadsheets
|
|
- Update existing spreadsheet data
|
|
- Perform calculations or data transformations
|
|
- Export data to CSV/Excel format
|
|
- Validate spreadsheet structure
|
|
|
|
## Workflow
|
|
|
|
### 1. Identify the file
|
|
Determine file path and format (.xlsx, .csv, .tsv).
|
|
|
|
### 2. Read the data
|
|
|
|
OpenClaw's `read` is for text files. For Excel/CSV:
|
|
|
|
**For CSV** (plain text):
|
|
```bash
|
|
read path/to/data.csv
|
|
```
|
|
|
|
**For .xlsx** (binary): Use Python or other tools:
|
|
```bash
|
|
python -c "
|
|
import pandas as pd, json, sys;
|
|
df = pd.read_excel('data.xlsx');
|
|
print(df.to_json(orient='records'))
|
|
"
|
|
```
|
|
|
|
Or install `xlsx2csv` and convert first:
|
|
```bash
|
|
xlsx2csv data.xlsx temp.csv
|
|
read temp.csv
|
|
```
|
|
|
|
### 3. Process the data
|
|
- Parse into structured format (list of objects, 2D array)
|
|
- Validate headers/columns if needed
|
|
- Perform transformations (filter, map, aggregate)
|
|
|
|
### 4. Write results
|
|
|
|
**For CSV**:
|
|
```bash
|
|
write output.csv --data "$csv_string"
|
|
```
|
|
|
|
**For .xlsx**: Use Python:
|
|
```bash
|
|
python -c "
|
|
import pandas as pd, json, sys;
|
|
data = json.loads(sys.argv[1]);
|
|
pd.DataFrame(data).to_excel('output.xlsx', index=False)
|
|
" "$structured_data"
|
|
```
|
|
|
|
## Supported Formats
|
|
- **.xlsx** (Excel Open XML) — full support for sheets, formulas, formatting
|
|
- **.csv** (Comma-separated) — plain text, delimiter detection
|
|
- **.tsv** (Tab-separated) — tab delimiter
|
|
|
|
## Common Operations
|
|
|
|
### Read specific sheet
|
|
```bash
|
|
read file.xlsx --sheet "Sheet2"
|
|
```
|
|
|
|
### Read with range
|
|
```bash
|
|
read file.xlsx --range "A1:D100"
|
|
```
|
|
|
|
### Write with formatting
|
|
```bash
|
|
write report.xlsx \
|
|
--data "$table" \
|
|
--header true \
|
|
--autofit columns
|
|
```
|
|
|
|
### Append to existing file
|
|
```bash
|
|
write file.xlsx --data "$new_rows" --append true
|
|
```
|
|
|
|
## Data Structures
|
|
|
|
**Reading returns**:
|
|
```json
|
|
{
|
|
"headers": ["Name", "Email", "Score"],
|
|
"rows": [
|
|
{"Name": "Alice", "Email": "a@example.com", "Score": 95},
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
**Writing accepts**:
|
|
- JSON array of objects
|
|
- 2D array (array of arrays)
|
|
- CSV string (if format=csv)
|
|
|
|
## Examples
|
|
|
|
<Good>
|
|
User: "Tạo báo cáo điểm từ scores.csv"
|
|
Assistant:
|
|
1. Đọc scores.csv
|
|
2. Tính toán điểm trung bình, xếp loại
|
|
3. Ghi vào report.xlsx với định dạng đẹp
|
|
4. Trả về đường dẫn file và tóm tắt kết quả
|
|
</Good>
|
|
|
|
<Bad>
|
|
Ghi đè file gốc mà không backup, không thông báo.
|
|
</Bad>
|
|
|
|
## Error Handling
|
|
- **File not found**: Kiểm tra đường dẫn, dùng `glob` để tìm
|
|
- **Format mismatch**: Đảm bảo file đúng định dạng, kiểm tra extension
|
|
- **Large files**: Có thể cần chunk processing, kiểm tra memory limits
|
|
- **Corrupted data**: Catch parse errors, report specific row/column
|
|
|
|
## Validation Checklist
|
|
- [ ] File exists and is readable
|
|
- [ ] Format matches extension
|
|
- [ ] Headers are present and correct
|
|
- [ ] Data types are correct (numbers, dates, strings)
|
|
- [ ] No missing values in required columns
|
|
- [ ] Output file is well-formed and complete
|