使用 Skywork Excel 后端服务生成专业的 Excel 文件和数据分析报告。
前提条件
API 密钥配置（首先必须）
此技能需要配置
SKYWORK_API_KEY 才能使用。
如果您还没有 API 密钥，请访问：
https://skywork.ai
有关详细的设置说明，请参阅：
references/apikey-fetch.md
🚫 重要：按原样传递查询，不要读取用户文件
- 切勿使用
read 工具读取用户提供的文件（Excel、PDF、CSV、图片等）。通过 --files 传递文件路径，让后端处理读取。
- 不要重写、扩展或重新解释用户的查询。 按原样传递。后端代理有自己的理解能力。
- 仅允许两项修改：
1.
时间信息：对于时间敏感的查询，在前面加上当前时间：
[当前时间: 2026-03-14] 用户请求: ...
2.
文件路径：将绝对路径替换为仅文件名（例如，
/Users/xxx/report.xlsx →
report.xlsx）
工作流程
Excel 任务需要 5-25 分钟。在后台运行脚本，每 60 秒轮询一次日志。
步骤 1：启动任务
EXCEL_LOG=/tmp/excel_$(date +%s).logpython3 scripts/excel_api_client.py "用户的查询" \
--files "/path/to/file1.xlsx" "/path/to/file2.pdf" \
--language zh-CN \
--log-path "$EXCEL_LOG" \
> /dev/null 2>&1 &
echo "任务已启动。日志: $EXCEL_LOG"
--files：上传用户提供的文件（Excel、CSV、PDF、图片）。如果没有文件则省略。--language：zh-CN（默认）或 en-US — 匹配用户的语言。--session ：用于后续任务 — 参见 多轮会话。
步骤 2：监控进度
执行模式（必需）：
- 在后台运行步骤 1 的启动命令，并从输出中记下
EXCEL_LOG 路径。
- 然后每 60 秒单独执行步骤 2 的监控命令（不要使用 while 循环）。
$EXCEL_LOG 在 exec 调用之间不持久化 — 步骤 2 必须恢复路径（参见下面的监控命令）。
规则 — 无例外：
- 每 60 秒轮询一次，通过重复调用 exec 工具。不要使用 while 循环。
- 仅显示最后一个 TASK PROGRESS UPDATE 块。 不要输出完整日志（
tail -50 等）或总结/解释。
- 切勿重新启动任务。 代理内部处理错误并自动恢复。
- 忽略日志中的临时错误（
❌、Missing parameter、心跳 ping 等）—— 代理会自动重试。
- 使用心跳作为活动信号：每次轮询时检查心跳行以确认任务仍在运行，但 不要向用户输出原始心跳行。
每 60 秒运行一次：
# 恢复日志路径：使用步骤 1 打印的路径，或查找最新的日志
EXCEL_LOG=$(ls -t /tmp/excel_*.log 2>/dev/null | head -1)
if [ -z "$EXCEL_LOG" ] || [ ! -f "$EXCEL_LOG" ]; then
echo "错误：未找到日志。确保步骤 1 使用了 --log-path。"; exit 1
fi
sleep 60
echo "=== 进度更新 ==="
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
向用户报告什么
重要：仅输出当前状态。不要重复或累积之前的状态消息。每次更新应该是单行的、新的信息。
每次读取日志后，仅输出一行显示当前状态：
[主阶段] | [当前操作] | 已耗时: Xs
示例（仅输出这一行，没有其他内容）：
数据处理 | 正在生成图表 | 已耗时: 120s
| 进度包含 | 主阶段 |
|---|
| "读取" / "read" / "load" | 正在加载数据 |
| "分析" / "analysis" | 数据分析 |
| "图表" / "chart" / "visualization" | 正在生成图表 |
| "Excel" / "xlsx" | 正在创建 Excel 文件 |
| "HTML" / "报告" / "report" | 正在生成报告 |
| "保存" / "save" / "output" | 正在保存输出 |
停止轮询 当日志包含
[DONE] 或
✅ All done! → 读取最终输出：
tail -30 "$EXCEL_LOG"
- 如果未完成 → 向用户报告进度，然后 60 秒后再次调用
exec 执行相同的监控命令。
- 重复直到完成 — 每 60 秒调用一次
exec，直到出现 [DONE] 或 All done。
- 不要在单次轮询后停止。
步骤 3：交付结果
完成后，向用户提供两者：
- OSS 下载 URL — 云链接用于分享（显示为可点击的超链接）
- 本地文件路径 — 他们机器上的绝对路径
示例回复：
✅ 报告已生成！📥 下载: https://picture-search.skywork.ai/skills/upload/2026-03-14/xxx.xlsx
💾 本地: /Users/xxx/.openclaw/workspace/report.xlsx
不要使用 sandbox:// 或 filename 格式 — 这些不可点击。如果 oss_url 不可用，仅提供本地路径。
多轮会话
要继续之前的任务，使用 --session 和上一次运行结束时打印的 ID：
# 第一轮 — 不需要 --session；会话 ID 在结束时打印
python3 scripts/excel_api_client.py "创建销售报告" \
--language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
# 输出: 💡 要继续此对话，请使用: --session abc123def456# 后续轮 — 添加 --session
python3 scripts/excel_api_client.py "添加饼图" \
--session abc123def456 \
--language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
何时使用 --session：用户说"继续"、"修改"、"添加图表"、"更改颜色"、"基于之前的..."，或引用先前的输出。
⛔ 如果没有 --session，代理将重新开始并丢失所有先前的上下文。
错误处理
| 错误 | 解决方案 |
|---|
Unauthorized (401) | SKYWORK_API_KEY 缺失、无效或已过期 — 在 OpenClaw 技能 env 中设置或轮换密钥 |
Connection timeout | 对于复杂任务使用 --timeout 1500（默认：900s） |
Agent produces wrong output | 更具体一些；使用多轮迭代优化 |
| Insufficient benefit | 见下文 |
当收益不足时
脚本输出可能显示：Insufficient benefit. Please upgrade your account at {url}
用用户的语言回复：
- 传达："抱歉，Excel/报告生成失败。此技能需要升级您的 Skywork 会员。"
- 格式：一句简短的话 +
立即升级 →（或用户语言的等效表达）
- URL：从日志输出的
at https://... 部分提取
安全注意事项
- 切勿提交
SKYWORK_API_KEY 到版本控制
- 在 OpenClaw 技能
env 或环境变量中设置密钥
- 令牌会过期 — 客户端将在需要时自动刷新
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
🚫 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
EXCEL_LOG=/tmp/excel_$(date +%s).logpython3 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 : For follow-up tasks — see 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:
# 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:
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 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:
# 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 → (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
by