Skywork Excel

    primaryEnv: SKYWORK_API_KEY
---

# Excel Generator

Generate professional Excel files and data analysis reports using the Skywork Excel backend service.

---
## Prerequisites

### API Key Configuration (Required First)
This skill requires a **SKYWORK_API_KEY** to be configured before use.

If you don't have an API key yet, please visit:
**https://skywork.ai**

For detailed setup instructions, see:
[references/apikey-fetch.md](references/apikey-fetch.md)

---

## 🚫 CRITICAL: Pass Query As-Is, Do NOT Read User Files

- **NEVER use the `read` tool on user-provided files** (Excel, PDF, CSV, images, etc.). Pass file paths via `--files` and let the backend handle reading.
- **Do NOT rewrite, expand, or reinterpret the user's query.** Pass it as-is. The backend agent has its own understanding capabilities.
- **Only two modifications are allowed:**
  1. **Time info**: For time-sensitive queries, prepend current time: `[Current time: 2026-03-14] User request: ...`
  2. **File paths**: Replace absolute paths with filenames only (e.g., `/Users/xxx/report.xlsx` → `report.xlsx`)

---

## Workflow

Excel tasks take 5-25 minutes. Run the script in background and poll the log every 60 seconds.

### Step 1: Start Task

```bash
EXCEL_LOG=/tmp/excel_$(date +%s).log

python3 scripts/excel_api_client.py "user's query" \
  --files "/path/to/file1.xlsx" "/path/to/file2.pdf" \
  --language zh-CN \
  --log-path "$EXCEL_LOG" \
  > /dev/null 2>&1 &

echo "Task started. Log: $EXCEL_LOG"
```

- **`--files`**: Upload user-provided files (Excel, CSV, PDF, Image). Omit if no files.
- **`--language`**: `zh-CN` (default) or `en-US` — match the user's language.
- **`--session <id>`**: For follow-up tasks — see [Multi-Turn Sessions](#multi-turn-sessions).

### Step 2: Monitor Progress

**Execution pattern (required):**
- Run the Step 1 start command in background and note the `EXCEL_LOG` path from the output.
- Then execute the Step 2 monitor command separately every 60 seconds (do not use a while loop).
- **`$EXCEL_LOG` does not persist between exec calls** — Step 2 MUST recover the path (see monitor command below).

**Rules — no exceptions:**
- **Poll every 60 seconds** by calling exec tool repeatedly. Do NOT use a while loop.
- **Show only the last TASK PROGRESS UPDATE block.** Do not output full log (`tail -50`, etc.) or summarize/interpret it.
- **Never restart the task.** The agent handles errors internally and auto-recovers.
- **Ignore transient errors in the log** (`❌`, `Missing parameter`, heartbeat pings, etc.) — the agent retries automatically.
- **Use heartbeat as liveness signal**: check heartbeat lines every poll to confirm the task is still running, but **do NOT output raw heartbeat lines to the user**.

**Every 60 seconds, run:**
```bash
# Recover log path: use the path printed by Step 1, or find the most recent log
EXCEL_LOG=$(ls -t /tmp/excel_*.log 2>/dev/null | head -1)
if [ -z "$EXCEL_LOG" ] || [ ! -f "$EXCEL_LOG" ]; then
  echo "ERROR: Log not found. Ensure Step 1 ran with --log-path."; exit 1
fi
sleep 60
echo "=== Progress Update ==="
grep -A8 "TASK PROGRESS UPDATE" "$EXCEL_LOG" | tail -10
grep -E "\[HEARTBEAT\]" "$EXCEL_LOG" | tail -1
grep -E "\[DONE\]|All done" "$EXCEL_LOG" | tail -1
```

### What to report to user

> **CRITICAL: Output ONLY the current status. Do NOT repeat or accumulate previous status messages. Each update should be a single, fresh line.**

After each log read, output ONLY ONE LINE showing the current status:
```
[Main stage] | [current action] | Elapsed: Xs
```

Example (output only this single line, nothing else):
```
Data Processing | Generating charts | Elapsed: 120s
```

| Progress contains | Main stage |
|------------------|------------|
| "读取" / "read" / "load" | Loading data |
| "分析" / "analysis" | Data analysis |
| "图表" / "chart" / "visualization" | Generating charts |
| "Excel" / "xlsx" | Creating Excel file |
| "HTML" / "报告" / "report" | Generating report |
| "保存" / "save" / "output" | Saving output |

**Stop polling** when log contains `[DONE]` or `✅ All done!` → read final output:
```bash
tail -30 "$EXCEL_LOG"
```

- If NOT done → report progress to user, then call `exec` again after 60 seconds with the same monitor command.
- Repeat until done — keep calling `exec` every 60 seconds until `[DONE]` or `All done` appears.
- Do NOT stop after a single poll.

### Step 3: Deliver Result

After completion, provide the user with **both**:
- **OSS download URL** — cloud link for sharing (show as a clickable hyperlink)
- **Local file path** — absolute path on their machine

Example reply:
```
✅ Report generated!

📥 Download: https://picture-search.skywork.ai/skills/upload/2026-03-14/xxx.xlsx
💾 Local: /Users/xxx/.openclaw/workspace/report.xlsx
```

**Do NOT use** `sandbox://` or `[filename](sandbox://...)` format — these are not clickable. If `oss_url` is unavailable, provide the local path only.

---

## Multi-Turn Sessions

To continue a previous task, use `--session` with the ID printed at the end of the previous run:

```bash
# First turn — no --session needed; session ID is printed at end
python3 scripts/excel_api_client.py "Create a sales report" \
  --language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
# Output: 💡 To continue this conversation, use: --session abc123def456

# Follow-up turn — add --session
python3 scripts/excel_api_client.py "Add a pie chart" \
  --session abc123def456 \
  --language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
```

**When to use `--session`**: User says "continue", "modify", "add a chart", "change colors", "based on the previous...", or references prior output.

**⛔ Without `--session`, the agent starts fresh and loses all previous context.**

---

## Error Handling

| Error | Solution |
|-------|----------|
| `Unauthorized (401)` | `SKYWORK_API_KEY` is missing, invalid, or expired — set or rotate the key in OpenClaw skill `env` |
| `Connection timeout` | Use `--timeout 1500` for complex tasks (default: 900s) |
| `Agent produces wrong output` | Be more specific; use multi-turn to refine iteratively |
| **Insufficient benefit** | See below |

### When benefit is insufficient

Script output may show: `Insufficient benefit. Please upgrade your account at {url}`

Reply in the user's language:
- Convey: "Sorry, Excel/report generation failed. This skill requires upgrading your Skywork membership."
- **Format**: One short sentence + `[Upgrade now →](url)` (or equivalent in user's language)
- **URL**: Extract from the `at https://...` part of the log output

---

## Security Notes

- **Never commit `SKYWORK_API_KEY`** to version control
- Set the key in OpenClaw skill `env` or as an environment variable
- Tokens expire — the client will auto-refresh when needed