Skywork Excel

Excel 生成器

使用 Skywork Excel 后端服务生成专业的 Excel 文件和数据分析报告。

---

前置条件

API 密钥配置（必须先完成）

此技能需要在 OpenClaw 中配置 SKYWORK_API_KEY。

如果你还没有 API 密钥，请访问： https://skywork.ai

详细的设置说明请参阅： references/apikey-fetch.md

---

🚫 重要：原样传递查询，不要读取用户文件

• 绝不要使用 read 工具读取用户提供的文件（Excel、PDF、CSV、图像等）。通过 --files 传递文件路径，让后端处理读取。
• 不要改写、扩展或重新解释用户的查询。 原样传递即可。后端 Agent 有自己的理解能力。
• 只允许进行两项修改：
  1. 时间信息：对于有时效性的查询，在前面添加当前时间：[Current time: 2026-03-14] User request: ...
  2. 文件路径：将绝对路径替换为仅包含文件名的路径（例如：/Users/xxx/report.xlsx → report.xlsx）

---

工作流

Excel 任务需要 5-25 分钟。请在后台运行脚本，并每隔 60 秒轮询一次日志。

步骤 1：开始任务

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：上传用户提供的文件（Excel、CSV、PDF、图像）。如果没有文件，则省略。
• --language：zh-CN（默认）或 en-US，与用户的语言保持一致。
• --session <id>：用于后续任务，参见多轮会话。

步骤 2：监控进度

执行模式（必需）：

• 在后台运行步骤 1 的启动命令，并记录输出中的 EXCEL_LOG 路径。
• 然后每隔 60 秒单独执行步骤 2 的监控命令（不要使用 while 循环）。
• $EXCEL_LOG 不会在不同的 exec 调用之间保留——步骤 2 必须重新获取该路径（参见下方的监控命令）。

规则——无一例外：

• 每隔 60 秒轮询一次，反复调用 exec 工具。不要使用 while 循环。
• 只显示最新的 TASK PROGRESS UPDATE 区块。 不要输出完整日志（例如 tail -50 等），也不要对其进行总结或解读。
• 绝不要重启任务。 Agent 会在内部处理错误并自动恢复。
• 忽略日志中的暂时性错误（❌、Missing parameter、心跳 ping 等）——Agent 会自动重试。
• 使用心跳作为存活信号：每次轮询时检查心跳行，确认任务仍在运行，但不要向用户输出原始心跳行。

每隔 60 秒运行：

# 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

向用户报告的内容

重要：只输出当前状态。不要重复或累积之前的状态消息。每次更新都应是一行全新的状态。

每次读取日志后，只输出一行，显示当前状态：

[Main stage] | [current action] | Elapsed: Xs

示例（只输出这一行，不要输出其他内容）：

Data Processing | Generating charts | Elapsed: 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——用于分享的云端链接（显示为可点击的超链接）
• 本地文件路径——用户机器上的绝对路径

回复示例：

✅ Report generated!

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

不要使用 sandbox:// 或 [filename](sandbox://...) 格式——这些链接无法点击。如果 oss_url 不可用，则只提供本地路径。

多轮会话

要继续之前的任务，请使用 --session，并指定上次运行结束时打印的 ID：

# 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 &

何时使用 --session：用户说“继续”“修改”“添加图表”“更改颜色”“基于之前的……”，或提及之前的输出。

⛔ 不使用 --session 时，Agent 会从头开始，并丢失之前的所有上下文。

---

错误处理

错误	解决方案
Unauthorized (401)	SKYWORK_API_KEY 缺失、无效或已过期——请在 OpenClaw 技能的 env 中设置或轮换密钥
Connection timeout	对于复杂任务，请使用 --timeout 1500（默认值：900s）
Agent produces wrong output	提供更具体的说明；使用多轮会话迭代优化
收益不足	见下文

收益不足时

脚本输出可能会显示：Insufficient benefit. Please upgrade your account at {url}

请使用用户的语言回复：

• 传达：“抱歉，Excel/报告生成失败。此技能需要升级您的 Skywork 会员资格。”
• 格式：一个简短句子 + [立即升级 →](url)（或使用用户语言的等效表述）
• URL：从日志输出中的 at https://... 部分提取

---

安全说明

• 切勿将 SKYWORK_API_KEY 提交到版本控制中
• 在 OpenClaw 技能的 env 中设置密钥，或将其设为环境变量
• 令牌会过期——客户端会在需要时自动刷新