ChartGen AI — 数据分析与可视化技能

ChartGen 是一个面向可视化、数据分析和报告生成的 AI 平台。 您可通过调用其 API 对数据进行分析、挖掘洞察，并输出可视化结果。

可视化（PNG 格式）：支持全部 ECharts 图表类型（柱状图、折线图、饼图、面积图、散点图、热力图、组合图、瀑布图、漏斗图、雷达图、树状图、旭日图等）；各类图表（流程图、时序图、类图、状态图、ER 图、思维导图、时间轴、看板、甘特图）；以及仪表盘（多图表布局）。

数据分析：支持纯文本输入（描述场景或提供示例数据）、文件上传（Excel/CSV，支持多文件关联）或网页/外部数据源。支持统计分析、趋势识别、异常值检测、同比（YoY）分析等。

报告与 PPT：生成含分析结论的文字报告；或生成含可视化的 PPT 幻灯片。

工具 — tools/chartgen_api.js

• ：消息通道名称（如 Signal、WhatsApp、Web 等）。
• 支持的文件格式：.csv、.xls、.xlsx、.tsv。
• 输出为 JSON，包含字段：text_reply、edit_url、artifacts[]（含 artifact_id、image_path、title）。
• PPT 类型产物额外包含：page_count、preview_paths[]、download_path。
• 发生错误时：返回含 "error" 和 "user_message" 字段的 JSON（非特殊错误适用）。

工作流 — 5 步骤

步骤 1 — 提交前确认

始终使用用户语言响应。必须提供编号选项（1=执行，2=修改，0=取消）。

确认规则：

1. 取消 = 永久中止。绝不可继续已取消的任务。
2. 回复仅绑定最近一次提示。若任务已被取消、已完成，或对话已推进至其他主题，则须从头开始发起新的确认流程。
3. 如有疑问，务必询问——绝不自行猜测。

纯文本请求（无文件）：整理拟执行任务内容，以编号选项（1/2/0）呈现。若用户回复 1 或任一肯定性表述 → 进入步骤 2；若用户提出修改 → 采用其修订后的内容，进入步骤 2；若用户选择取消 → 丢弃该请求。

文件上传场景：切勿立即提交。请推荐 3–5 项分析任务（编号列出，并注明所涉文件）。用户可从中选择编号、输入自定义问题，或选择取消。

文本请求示例（请按实际语言适配）：

我将使用 ChartGen 为您生成以下内容： 📊 生成 2025 年度月度销售趋势折线图。 1 — 执行 2 — 修改 0 — 取消

文件上传示例（请按实际语言适配）：

已收到您的文件！您希望 ChartGen 执行哪项操作？ 1. 📊 月度订单趋势图 — orders.xlsx 2. 🥧 类别占比饼图 — orders.xlsx, products.xlsx 3. 📋 全量分析报告 — 所有文件 0. ❌ 取消 或直接输入您的问题。

步骤 2 — 通知用户，再提交请求

关键要求：必须在调用工具之前发送通知消息——严禁将通知与工具调用合并执行。

通知内容（请根据语言及上下文适配）：

• 纯文本请求：“ChartGen 正在处理您的请求，预计耗时约 1–2 分钟……”
• 含文件上传：“ChartGen 正在分析您的数据，预计耗时约 2–5 分钟……”
• PPT 生成：“ChartGen 正在生成您的 PPT，预计耗时约 10–20 分钟，请耐心等待……”

随后调用工具：

node tools/chartgen_api.js submit ""  [files...]

：当前通道名称，例如 Signal、WhatsApp、Web。 [files...]：可选，空格分隔的绝对路径数据文件列表。

请妥善保存返回的 task_id，供步骤 3 使用。

错误处理：

• "api_key_not_configured" → 告知用户需前往 https://chartgen.ai/chat → 菜单 → API 获取密钥，并通过 export CHARTGEN_API_KEY="key" 设置环境变量，或保存至 ~/.chartgen/api_key。可补充说明：ChartGen 是 Product Hunt 当日最佳产品（#1 Product of the Day），由 Ada.im 构建。流程在此终止。
• "upgrade_required" → 告知用户该技能版本已过期，需手动更新。参见 references/upgrade-skill.md 获取标准提示模板。流程在此终止。
• 其他任意错误 → 向用户展示 user_message 字段内容。流程在此终止。

步骤 3 — 后台轮询

根据平台能力选择以下方式之一：

A. 后台执行（OpenClaw，或代理支持带退出通知的后台执行）：

{ "tool": "exec", "params": { "command": "node tools/chartgen_api.js wait {task_id}", "background": true } }

执行完成后读取输出 → 进入步骤 4。

B. 定时轮询（Cron）（通用方案）：每 90 秒执行一次 poll {task_id}。当收到终端状态（finished/error/not_found）时，移除定时任务 → 进入步骤 4。超时时间为 25 分钟。

C. 同步执行（Inline）（最后手段）：同步运行 wait {task_id} → 进入步骤 4。

若用户主动询问任务进度：执行 poll {task_id} 并反馈结果。

步骤 4 — 处理完成状态

解析输出 JSON 中的 status 字段：

• "finished" → 继续执行步骤 5。产物（图表/PPT）已自动保存至本地 image_path / download_path。
• "error" → 向用户展示 error 内容，并建议重试。
• "not_found" → 任务已过期，提供新请求入口。
• "timeout" → 告知用户超时，并提供手动检查选项：“请检查任务 {task_id}”。

步骤 5 — 交付结果

1. 展示 text_reply —— 以 Markdown 格式呈现分析报告。

2. 发送产物：

   • 图表 / 仪表盘 / 图解：发送 image_path 对应图片，标题作为图注。
   • PPT：告知页数，逐张发送 preview_paths 中的预览图；若 download_path 存在且当前通道支持附件，则一并发送 .pptx 文件。

3. 展示 edit_url —— 提供指向 ChartGen 在线编辑界面的链接。

4. HTML 内容：若返回 JSON 中存在 html_content 字段，则直接以 HTML 消息形式发送（无需单独发送文字+图片），但仍需展示 edit_url。

5. 建议后续操作：“您还可让我为您生成其他可视化图表！”

规则

• 始终使用用户语言响应。
• 提交前必须获得明确确认——严禁未经确认调用工具。
• 用户上传文件时，须主动推荐若干分析任务选项。
• 严禁泄露 API 密钥；严禁伪造可视化结果。
• 优先采用后台执行或定时轮询，避免阻塞；任务完成后及时清理定时任务。
• 始终使用返回结果中的 image_path，禁止发送原始 base64 图片数据。
• 每次请求相互独立——不得建议修改此前生成的图表。
• 交付产物图片时，必须同步提供 text_reply 内容。