Excel 生成器

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

前置条件

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

本技能需预先配置 SKYWORK_API_KEY 才可使用。

如尚未获取 API 密钥，请访问：
https://skywork.ai

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

🚫 关键警告：原样传递用户查询，禁止读取用户文件

• 切勿对用户提供的文件（Excel、PDF、CSV、图片等）使用 read 工具。应通过 --files 参数传入文件路径，由后端自行处理读取。
• 禁止改写、扩展或重新解释用户的原始查询。必须原样传递。后端智能体具备独立的理解能力。
• 仅允许以下两项修改：
  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 ：用于多轮会话中的后续任务 —— 见「多轮会话」章节。

步骤 2：监控进度

执行模式（强制要求）：

• 在后台运行步骤 1 的启动命令，并记录输出中显示的 EXCEL_LOG 路径。
• 随后**单独执行**步骤 2 的监控命令，**每 60 秒一次**（严禁使用 while 循环）。
• $EXCEL_LOG 在不同 exec 调用之间不持久化 —— 步骤 2 **必须重新恢复日志路径**（见下方监控命令）。

规则 —— 无例外：

• 必须每 60 秒调用一次 exec 工具进行轮询。严禁使用 while 循环。
• 仅输出最近一条 TASK PROGRESS UPDATE 区块内容。不得输出完整日志（如 tail -50 等）、也不得总结或解读日志内容。
• 禁止重启任务。智能体内部可自主处理错误并自动恢复。
• 忽略日志中的临时性错误（如 ❌、Missing parameter、心跳探测行等）—— 智能体会自动重试。
• 以心跳（HEARTBEAT）作为存活信号：每次轮询均需检查心跳行以确认任务仍在运行，但不得将原始心跳行输出给用户。

每 60 秒执行以下命令：

# 恢复日志路径：使用步骤 1 输出的路径，或查找最新生成的日志
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

向用户汇报的内容

关键要求：仅输出当前状态。禁止重复或累积之前的状态消息。每次更新必须是单行、全新的状态描述。

每次读取日志后，**仅输出一行**，格式如下：

[主阶段] | [当前动作] | Elapsed: Xs

示例（仅输出该行，不附加任何其他内容）：

Data Processing | Generating charts | Elapsed: 120s

停止轮询的条件：当日志中出现 [DONE] 或 ✅ All done! 时 → 读取最终输出：

tail -30 "$EXCEL_LOG"

• 若任务未完成 → 向用户汇报当前进度，然后等待 60 秒，再次以相同监控命令调用 exec。
• 持续重复此过程，直至日志中出现 [DONE] 或 All done。
• 禁止仅轮询一次即终止。

步骤 3：交付结果

任务完成后，需向用户提供以下两项内容：

• OSS 下载链接 —— 云端共享链接（以可点击的超链接形式展示）
• 本地文件路径 —— 用户设备上的绝对路径

示例回复：

✅ 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：

# 首次运行 —— 无需 --session；会话 ID 将在末尾输出
python3 scripts/excel_api_client.py "Create a sales report" 
  --language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
# 输出： 💡 To continue this conversation, use: --session abc123def456

# 后续轮次 —— 添加 --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，智能体将完全重置上下文，丢失所有历史信息。

错误处理

收益不足（Insufficient benefit）场景

脚本输出可能包含：Insufficient benefit. Please upgrade your account at {url}

请使用用户语言回复：

• 传达含义：“抱歉，Excel/报告生成失败。本技能需升级您的 Skywork 会员权限。”
• 格式要求：一句简短说明 + [Upgrade now →](url)（或对应用户语言的等效表述）
• URL 来源：从日志输出中的 at https://... 部分提取

安全须知

• 切勿将 SKYWORK_API_KEY 提交至版本控制系统
• 应在 OpenClaw 技能的 env 中设置密钥，或设为环境变量
• 令牌具有有效期，客户端将在必要时自动刷新