🚫 关键：请勿读取用户文件

切勿对用户提供的文件（Excel、PDF、CSV、图像等）使用 read 工具。

后端代理会自行读取和处理文件。您只需要：

1. 使用 CLI 脚本的 --files 参数上传文件
2. 直接传递用户的查询，无需修改

读取文件会浪费时间并导致超时。只需上传并让后端处理一切。

⚠️ 重要：带进度监控的后台执行

Excel 任务需要 5-25 分钟。您必须在后台运行脚本，并每 5 秒轮询一次日志，以保持 UI 响应并避免超时。

步骤 1：在后台启动脚本

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

python3 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"

步骤 2：监控进度（必需）

严格规则 — 无例外：

1. 通过重复调用 exec 工具，每 60 秒轮询一次。 Excel 任务需要 10-25 分钟。
2. 仅显示最后的任务进度更新。 请勿输出完整日志或对其进行总结。
3. 切勿重新启动任务。 Excel 代理会在内部处理错误并自动恢复。
4. 忽略日志中的所有错误（例如，❌、Missing parameter、jupyter_execute 错误）。这些是正常的 — 代理会自动重试。

每 60 秒，运行以下确切序列（每次调用 exec 工具，请勿使用 while 循环）：

# 步骤 1：等待 60 秒
sleep 60
# 步骤 2：检查进度
echo "=== 进度更新 ==="
grep -A8 "TASK PROGRESS UPDATE" "$EXCEL_LOG" | tail -10
# 步骤 3：检查是否完成
grep -E "\[DONE\]|All done" "$EXCEL_LOG" | tail -1

• 如果日志包含 [DONE] 或 ✅ All done! → 停止轮询，使用 tail -30 "$EXCEL_LOG" 读取最终输出，然后交付结果。
• 如果未完成 → 向用户报告进度，然后在 60 秒后再次调用 exec 工具，使用相同的命令。
• 重复直到完成 — 您必须每 60 秒调用一次 exec 工具，直到看到 [DONE] 或 All done。

规则

• 重复调用 exec 工具 — 请勿使用 while 循环（它会阻塞输出）。请自行每 60 秒调用一次 exec。
• 即使看到错误也切勿重新启动任务。代理会在内部处理错误。
• 请勿总结或解释日志 — 只需显示原始的任务进度更新块。

向用户报告什么

关键：仅输出当前状态。请勿重复或累积先前的状态消息。每次更新都应该是单行、全新的内容。

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

[主要阶段] | [当前操作] | 已用时间：Xs

示例（仅输出此行，其他内容不输出）：

数据处理 | 生成图表 | 已用时间：120s

将任务进度更新映射到主要阶段：

示例状态更新：

加载数据 | 读取 Excel 文件 | 已用时间：30s
数据分析 | 处理股票数据 | 已用时间：90s
生成报告 | 创建 HTML 分析 | 已用时间：180s

请勿：

• 输出 tail -50 或完整的日志内容
• 提及错误或心跳消息
• 因任何原因重新启动任务
• 重复或累积先前的状态消息 — 每次更新都必须是全新的，而不是附加到先前的消息上

一项专业技能，利用具有 AI 驱动数据分析、图表制作、公式验证和报告生成能力的复杂后端服务，生成和更新高质量的 Excel 文件。

身份验证（首次必需）

在使用此技能之前，必须完成身份验证。首先运行身份验证脚本：

# 身份验证：检查环境变量令牌 / 缓存的令牌 / 浏览器登录
python3 <skill-dir>/scripts/skywork_auth.py || exit 1

令牌优先级：

1. 环境变量 SKYBOT_TOKEN → 如果已设置，则直接使用
2. 缓存的令牌文件 ~/.skywork_token → 通过 API 验证，如果有效，则使用它
3. 没有有效令牌 → 打开浏览器登录，轮询直到完成，保存令牌

重要 - 登录 URL 处理：如果脚本输出包含以 [LOGIN_URL] 开头的行，您必须立即将该 URL 以可点击消息的形式发送给用户（例如，"请打开此链接登录："）。用户可能处于浏览器无法自动打开的环境中，因此请始终提供登录 URL。

何时使用此技能

当用户想要以下操作时，请使用此技能：

• 从头创建 Excel 文件，包含数据、公式、图表和专业格式
• 分析现有数据文件（Excel、CSV、PDF）并生成摘要报告或可视化
• 更新或转换 Excel 文件（添加计算、图表、数据透视表、格式）
• 生成数据驱动报告 - 输出可以是 Excel (.xlsx) 或用于查看/共享的专业 HTML 报告
• 执行复杂的数据分析，需要 pandas、numpy 或统计操作
• 创建仪表板或可视化，包含图表、条件格式和样式化表格
• 从上传的文档中提取和结构化数据为 Excel 格式
• 搜索网络数据 - 代理可以搜索实时信息以包含在生成的输出中（您这边不需要外部搜索工具）

输出格式

代理支持多种输出格式：

• Excel (.xlsx) - 用于数据操作和编辑
• HTML 报告 - 用于查看和共享

后端代理会根据用户的请求自动选择合适的格式。只需直接传递用户的自然语言请求。

后端服务特别适用于那些受益于专业 Excel 知识、公式验证和视觉质量保证的任务。

工作原理

该技能使用 ReAct 代理循环，该循环：

1. 接受用户请求，通过自然语言（英文或中文）
2. 处理上传的文件（Excel、CSV、PDF），如果提供的话
3. 流式传输实时进度，显示 LLM 推理和工具执行情况
4. 执行专用工具，如用于数据操作的 jupyter_execute、validate_excel_formulas、validate_excel_charts 等
5. 在 /workspace/output/ 中生成输出文件（自动注册以供下载）
6. 支持多轮对话，用于迭代优化

⚠️ 重要：保留用户的原始查询（严格禁止重写策略）

向 Excel 代理发送请求时：

• 保持用户的原始查询完全不变 - 请勿重写、扩展或重新解释查询
• 将查询原样传递给后端代理，后者有自己的理解能力
• 只允许进行两种修改：

  1. 时间信息：对于时间敏感的查询（例如，"最新数据"、"今年"、"本季度"），在开头添加当前时间。只有在您能可靠地获取真实时间时才添加：

     [当前时间：2026-03-14] 用户请求：获取小米本周股价...
     

  2. 文件路径：将绝对路径替换为仅文件名（例如，/Users/xxx/report.xlsx → report.xlsx）

• 查询中提到的所有文件都必须上传 - 在调用 run_agent() 之前，对每个文件使用 upload_file()。如果您在指定路径找不到文件，请先询问用户提供正确的文件路径，然后再继续。将返回的 file_ids 传递给 run_agent()，以便后端可以访问上传的文件
• 请勿读取文件内容来修改查询 - 直接上传文件即可。后端代理会自行读取和处理文件。在您的查询中，只需提供 file_id 和文件名之间的映射关系（例如，"file_id abc123 是 sales_data.xlsx"）
• 不允许进行其他修改 - 不要添加额外的指令，不要扩展需求，不要"优化"用户的措辞

核心工作流程

步骤 1：健康检查（必需）

始终从检查后端服务是否健康开始：

from excel_api_client import ExcelAgentClient

# 自动登录：如果没有可用令牌，将提示浏览器登录
client = ExcelAgentClient()

if not client.health_check():
    print("服务不可用或身份验证失败")
    exit(1)

print("服务已就绪！")

步骤 2：上传文件（如果需要）

如果用户提到现有文件或您有文件需要分析，请先上传它们：

from excel_api_client import ExcelAgentClient

client = ExcelAgentClient()  # 自动登录

# 上传文件
file_id = client.upload_file("/path/to/data.xlsx")
print(f"已上传：{file_id}")

步骤 3：调用 Excel 代理

通过 SSE 流式端点将用户的请求发送到后端：

from excel_api_client import ExcelAgentClient

client = ExcelAgentClient()  # 自动登录

# 运行代理并流式传输进度
output_files = client.run_agent(
    message="创建一个带图表的销售报告",
    file_ids=["uploaded_file_id"],  # 可选
    language="zh-CN"  # 或 "en-US"
)

# output_files 包含：[{"file_id": "...", "name": "...", "size": ...}, ...]

客户端在内部处理所有 SSE 流式传输，并将进度显示到标准输出。

步骤 4：下载生成的文件

代理完成后，为用户下载输出文件：

from excel_api_client import ExcelAgentClient

client = ExcelAgentClient()  # 自动登录

# 下载所有输出文件
for f in output_files:
    client.download_file(f["file_id"], f"./{f['name']}")

CLI 输出包含两种路径 — 使用命令行脚本时，它会自动输出：

• 📁 本地： — 文件下载到的本地绝对路径
• ☁️ OSS： — 用于共享的云下载 URL

向用户总结结果时，始终包含脚本输出中的本地文件路径和 OSS 下载链接。

重要实现说明

进度流式传输

SSE 端点返回实时进度更新。始终向用户显示这些信息，以便他们了解正在发生的情况：

• progress 事件：显示代理的推理和思考过程
• tool_start 事件：指示诸如 jupyter_execute 之类的工具何时开始运行
• tool_result 事件：显示工具是否成功及其输出摘要

这种透明度至关重要，因为对于复杂任务，Excel 生成可能需要 30-120 秒。

多轮对话（重要）

后端通过 session_id 完全支持多轮会话。 这对于迭代优化任务至关重要。

多轮对话如何工作

1. 在对话开始时生成唯一的 session_id（例如，uuid.uuid4()[:12]）
2. 将相同的 session_id 传递给同一对话中所有后续的 run_agent() 调用
3. 代理自动：
   • 记住先前的对话历史记录（最多 40 条消息）
   • 保留 Jupyter 命名空间中的 Python 变量
   • 将输出文件保存在同一个 /workspace/<session_id>/output/ 目录中

多轮对话示例（推荐：让服务器生成 session_id）

from excel_api_client import ExcelAgentClient

client = ExcelAgentClient()

# 第一轮：不传递 session_id，服务器生成一个并返回
output_files, session_id = client.run_agent(
    message="创建一个包含第一季度数据的销售报告"
)
# session_id 现在可用，例如 "a1b2c3d4e5f6"

# 第二轮：传递返回的 session_id
output_files, _ = client.run_agent(
    message="添加一个显示产品类别细分的饼图",
    session_id=session_id  # ← 使用返回的 session_id
)

# 第三轮：继续使用相同的 session_id
output_files, _ = client.run_agent(
    message="将图表颜色更改为蓝色主题",
    session_id=session_id
)

多轮对话示例（替代方案：预先生成 session_id）

import uuid

# 预先生成 session_id
session_id = str(uuid.uuid4())[:12]

# 所有调用都使用相同的 session_id
client.run_agent(message="创建一个报告", session_id=session_id)
client.run_agent(message="添加图表", session_id=session_id)

CLI 多轮对话示例

# 第一轮（无 --session，服务器生成一个）
python scripts/excel_api_client.py "创建一个销售报告"
# 输出：💡 要继续此对话，请使用：--session abc123def456

# 第二轮（使用打印的 session_id）
python scripts/excel_api_client.py "向报告添加图表" --session abc123def456

清除会话（重新开始）

要清除对话历史记录并使用相同的 session_id 重新开始：

# 选项 1：使用 new_session=True（清除历史记录但保留 session_id）
output_files, _ = client.run_agent(message="...", session_id=session_id, new_session=True)

# 选项 2：不传递 session_id 以获取新的 session_id
output_files, new_session_id = client.run_agent(message="...")

⚠️ 常见错误

• 使用不同的 session_id 值：代理将每次调用视为独立的
• 未捕获返回的 session_id：如果您不传递 session_id，请捕获返回值用于后续调用

错误处理

常见问题及处理方法：

1. 身份验证失败 (401)：令牌无效或已过期 - 请用户提供有效的令牌
2. 文件上传失败：确保文件路径正确，检查文件大小限制
3. 代理超时：复杂任务（尤其是使用 AI 推理模型的 PDF 转 Excel）可能需要 5-25 分钟 - 通知用户并建议分解为更小的步骤
4. 需要澄清：当触发 clarification_needed 事件时，暂停并获取用户输入后再继续
5. 权益不足：脚本或日志可能显示例如 Insufficient benefit. Please upgrade your account at {url} — 请按照下面的"权益不足时如何回复"进行回复

权益不足时如何回复

当您检测到上述情况时，请使用用户当前的语言回复 — 不要回显英文消息。使用以下模式：

• 传达："抱歉，Excel/报告生成失败。此技能需要升级您的 Skywork 会员才能使用。" 然后是一个单一的号召性用语链接。
• 格式：用户语言中的一句简短句子 + 一个链接，如 [立即升级 →](url) 或用户语言中的等效内容。
• URL：从日志/脚本输出中提取升级 URL（例如 at https://... 部分）。

语言选择

后端支持中文和英文：

• "language": "zh-CN" - 中文提示和输出（默认）
• "language": "en-US" - 英文提示和输出

根据用户的语言或其明确偏好进行选择。

后端能力（代理可用的工具）

后端代理可以访问以下强大工具：

• jupyter_execute：运行 Python 代码，使用 pandas、openpyxl、matplotlib 等进行数据操作和 Excel 生成
• validate_excel_formulas：在保存前验证 Excel 公式语法是否正确
• validate_excel_charts：将图表渲染为图像以视觉验证其外观是否正确
• excel_data_llm_analysis：对大型数据集执行语义分析（翻译、分类、摘要）
• grep_by_keyword：在上传的文件中搜索特定内容
• read_document_pages：从 PDF/DOCX 文件中提取文本
• excel_visual_agent：从图像/PDF 中提取结构化数据到 Excel
• parallel_search_full：搜索网络数据以包含在报告中
• browse_urls：从特定 URL 获取内容
• todo_write：维护任务列表，以防止在复杂的多步骤任务中出现目标漂移

您不需要显式调用这些工具 - 代理会根据用户的请求自动决定使用哪些工具。

使用模式示例

常见场景（完整代码请参阅核心工作流程）：

示例请求：

• "创建一个月度支出跟踪器，包含日期、类别、金额列"
• "分析 sales.xlsx，用条形图显示按收入排名的前 10 名客户"
• "生成一份总结季度销售数据的报告"
• "将 jan.csv、feb.csv、mar.csv 合并到一个工作簿中，并包含摘要工作表"

输出文件处理

所有输出文件都保存在后端服务器的 /workspace/<session_id>/output/ 目录中。代理自动：

1. 在文件注册表中注册每个输出文件

2. 将文件上传到 OSS 以供 CDN 访问（xlsx、csv、html、pdf、png、jpg、zip）

3. 在 output_files 事件中返回文件元数据：

   {
     "file_id": "abc123xyz",
     "name": "report.xlsx",
     "size": 15360,
     "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     "path": "/tmp/excel_agent_workspace/session_123/output/report.xlsx",
     "oss_url": "https://xxx.oss-cn-xxx.aliyuncs.com/excel-agent/session_123/report.xlsx"
   }
   

4. 通过 /api/download/{file_id} 使文件可用（如果 OSS 不可用，则作为备用方案）

⚠️ 重要：向用户呈现下载链接

代理完成后，您必须向用户显示 OSS 下载链接：

• 直接显示原始 OSS URL（请勿使用 sandbox:// 或其他格式）

• 如果文件已下载到本地，也请提供本地路径

• 对用户的示例响应：

  ✅ 报告生成成功！
  
  📥 下载链接：
  - report.xlsx：https://picture-search.skywork.ai/skills/upload/2026-03-14/xxx.xlsx
  
  💾 本地文件：/Users/xxx/.openclaw/workspace/report.xlsx
  

• 请勿使用 sandbox:// 或 [filename](sandbox://...) 格式 - 这些不可点击

• 如果 oss_url 不可用，请通知用户文件已保存在本地并提供完整路径

最佳结果提示

1. 请求要具体：您提供的细节越多，输出效果越好

   • ❌ "做一个销售报告"
   • ✅ "创建一个销售报告，包含列：日期、产品、数量、收入。包含一个按产品类别汇总的数据透视表和一个显示前 5 名产品的条形图。"

2. 使用辅助脚本：为方便起见，请使用 scripts/excel_api_client.py，它处理 SSE 流式传输、文件上传/下载和错误处理

3. 监控进度：始终向用户显示进度事件 - 对于复杂任务，Excel 生成可能需要时间

4. 处理澄清请求：如果代理发送 clarification_needed 事件，请暂停并在继续之前获取用户输入

5. 会话管理：对于相关任务，使用一致的 session_ids 以保持上下文

6. 验证输出：下载文件后，通知用户文件位置，并建议他们打开文件以验证结果

故障排除

"未经授权 (401)"

• 令牌缺失、无效或已过期
• 运行 python scripts/skywork_auth.py --login 重新进行身份验证

"连接超时"

• 复杂任务（尤其是使用 AI 推理模型的 PDF 转 Excel）可能需要 5-25 分钟
• 默认超时时间现在是 900 秒（15 分钟）
• 对于非常复杂的任务，请使用 --timeout 1500
• 考虑将非常大的任务分解为更小的步骤

"下载后找不到文件"

• 检查在尝试下载之前是否收到了 output_files 事件
• 验证 file_id 是否正确
• 尝试直接使用 curl 下载（需要在请求头中包含有效的令牌）

"代理产生错误输出"

• 在请求中更加具体（包括列名、图表类型、格式细节）
• 尝试多轮对话：先生成一个基本版本，然后在后续消息中进行优化

脚本参考

使用捆绑的 scripts/excel_api_client.py 进行简化的集成：

from excel_api_client import ExcelAgentClient

# 初始化并自动登录（推荐）
client = ExcelAgentClient()

# 检查服务是否就绪
if not client.health_check():
    print("服务不可用或身份验证失败。")
    exit(1)

# 如果需要，上传文件
file_ids = [client.upload_file("data.xlsx")]

# 运行代理并流式传输进度
output_files = client.run_agent(
    message="创建一个带图表的摘要报告",
    file_ids=file_ids
)

# 下载结果
for f in output_files:
    client.download_file(f["file_id"], f"./{f['name']}")

安全说明

⚠️ 重要的安全实践：

• 切勿将令牌提交到版本控制中
• 切勿记录完整的令牌 - 使用掩码格式（例如，qGXpDd6H...cv0）
• 令牌存储在 ~/.skywork_token 中（用户主目录，不在项目中）
• 在 CI/CD 流水线中使用环境变量
• 令牌会过期 - 客户端会在需要时自动刷新

完整实现请参阅 scripts/excel_api_client.py 和 scripts/skywork_auth.py。

每周安装次数

–

代码仓库

skyworkai/skywork-skills

GitHub 星标数

51

首次出现时间

–

安全审计

Gen Agent Trust HubPassSocketWarnSnykWarn