Install
openclaw skills install @aitubiao/aitubiao-ai-chartAI智能图表生成。根据用户数据生成图表配置并创建可视化项目。当用户想要创建图表、可视化数据时使用,触发词包括"创建图表"、"做个图表"、"可视化数据"、"用表格生成图表"、"create chart"、"make a chart"、"visualize data"等。y
openclaw skills install @aitubiao/aitubiao-ai-chart根据用户提供的数据,生成图表配置并创建可视化项目。
以下规则必须严格执行,不得跳过、变通或使用替代方案:
create-chart,请求体设置 "maxCharts": N;禁止按每张图循环调用 CLI。⚠️ 以下想法是错误的,如果你发现自己在这样想,请立即停止:
在调用任何 API 之前,先检查凭证状态。
bash scripts/aitubiao-cli.sh check-auth
sk_v1_...)。如果没有,引导用户前往 API Key 管理页面 创建一个新的 API Key,然后将创建好的 Key 粘贴回来。bash scripts/aitubiao-cli.sh auth <用户提供的key>
bash scripts/aitubiao-cli.sh check-auth 确认配置成功。凭证保存在 ~/.aitubiao/credentials,跨会话持久生效。
在 Windows 上,禁止用 PowerShell / Python / heredoc / echo / Set-Content / shell 重定向来生成含中文等非 ASCII 字符的 JSON 请求体。这些方式容易经过 Windows 系统代码页(常为 GBK/CP936)或 MSYS argv 转换,导致传到后端的中文乱码。
正确做法:先用 Write 工具把完整 UTF-8 JSON 写到临时文件,然后用 --body-file 让 CLI 从文件读取,绕过 argv/控制台编码转换。
Windows 调用:
scripts\aitubiao-cli.cmd --body-file C:\Users\%USERNAME%\AppData\Local\Temp\aitubiao-payload.json create-chart
Git Bash 调用:
bash scripts/aitubiao-cli.sh --body-file /tmp/aitubiao-payload.json create-chart
--body-file 可用于所有读取 stdin JSON 的命令:create-chart / create-ppt / create-sankey / create-3d / download-project。CLI 会自动剥离 UTF-8 BOM 和 CRLF。
CSV/TXT 文件也只用 Read 工具读取。不要写 Python/PowerShell 脚本做本地解析、转码或聚合;如果 Read 出来的文本已经明显乱码,要求用户提供 UTF-8 文件或直接粘贴数据。
macOS / Linux 上仍可使用 heredoc,但包含中文的请求体也优先使用 --body-file。
每一步必须在前一步完成后才能开始。禁止跳步。
运行检查凭证流程。认证未通过时按"认证"章节流程处理。
认证未通过时,停止。不要读取用户数据,不要做任何分析。
判断用户如何提供数据:
把用户已确认要画图的数据整理成结构化 sources 数组:每张表给一个 index(0-based)、可选 title、header(列名数组)、rows(二维数组,单元格只能是字符串或数字)。后端不再做任何文本解析。
向用户展示整理后的数据预览,并询问:
同时确定图表数量:
maxCharts = N,N 必须在 1-10 之间。maxCharts = 5。在创建图表前,必须检查用户的 AI贝余额和项目配额,并向用户确认费用后才能继续。
bash scripts/aitubiao-cli.sh quota --skill chart
CLI 返回配额 JSON(含 shellBalance、projectsUsed/projectsLimit/projectsRemaining、feature 等字段)。
图表项目按"个"计费:单图单价 = .feature.cost 个 AI贝。创建接口会先按 maxCharts × .feature.cost 预扣,若实际生成数量少于 maxCharts,服务端会按实际生成数自动部分退款。
预估最高费用 = maxCharts × .feature.cost。maxCharts 使用第二步确定的图表数量;未指定数量时默认 5。
必须在调用生成接口前向用户展示费用确认信息,并等待用户确认后才能继续:
本次操作最多预扣 {maxCharts × cost} 个 AI贝({cost} AI贝/个 × {maxCharts} 个)
当前余额: {shellBalance} 个 AI贝
预扣后余额: {shellBalance - maxCharts × cost} 个 AI贝(实际生成较少时会自动部分退款)
项目数: 已用 {projectsUsed}/{projectsLimit}
是否继续?
shellBalance < maxCharts × cost:告知用户当前 AI贝余额不足,需前往 aitubiao 网站购买会员或充值后再继续,不要继续projectsRemaining <= 0:告知用户当前项目数已满,需前往 aitubiao 网站升级会员,或在网站中删除旧项目后再继续,不要继续只有用户明确确认费用后才能执行此步骤。
先用 Write 工具把请求体保存为 UTF-8 JSON 文件。
请求体文件内容:
{
"sources": [
{
"index": 0,
"title": "<可选:源表标题>",
"header": ["<列名1>", "<列名2>"],
"rows": [
["<标签>", 100],
["<标签>", 150]
]
}
],
"maxCharts": 3,
"projectName": "<项目名称>",
"requirement": "生成3张图,覆盖用户要求的多个分析角度"
}
macOS / Linux 调用:
bash scripts/aitubiao-cli.sh --body-file <请求体文件路径> create-chart
Windows 调用:
scripts\aitubiao-cli.cmd --body-file <请求体文件路径> create-chart
请求体字段说明:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sources | array | 是 | 结构化数据源数组,最多 10 个。每项含 index / title? / header / rows,详见下方嵌套字段说明 |
| markdownTable | string | 否 | 已废弃,仅用于旧客户端兼容。sources 与 markdownTable 至少提供其一 |
| maxCharts | number | 否 | 预期最多生成图表数,范围 1–10;用户要求 N 张图时填 N,未指定时默认 5;按 maxCharts × .feature.cost 预扣 AI贝,实际生成较少时部分退款 |
| projectName | string | 否 | 项目名称,默认"AI图表" |
| requirement | string | 否 | 用户需求(配色、图表类型偏好、关注点等) |
sources[].* 嵌套字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| index | number | 是 | 源表 0-based 下标,多源场景用于绑定每张图与源表 |
| title | string | 否 | 源表标题,作为 plan / per-chart prompt 的语义锚点 |
| header | string[] | 是 | 列名数组,非空 |
| rows | (string|number)[][] | 是 | 数据行二维数组;单元格只能是字符串或有限数字。数值列必须是 number(不要传 "100" 字符串),以免影响图表数值轴判断 |
检查 CLI 退出码:
project)、初始 charts(此时 screenshotSuccess 为 false、无 screenshotUrl)、以及 snapshotJob.id(截图作业 ID)。默认不要主动获取截图——直接进入第五步交付项目即可。仅当用户明确要求"我要截图 / 给我图片 / 把图发我"等时,才执行下方"可选:获取图表截图"。
响应字段说明详见下方"响应字段参考"。
向用户提供:
project.projectUrl 获取)project.id 获取)charts[].screenshotSuccess 为 true)仅当用户在项目创建成功后明确要求时(含「截图 / 图片 / 配图 / 把图发我 / screenshots / images」等触发词,或追问「图呢 / 我看不到图」),才执行此节。
如果第四步响应里没有 snapshotJob.id,不要进入此节。
snapshotJob.idbash scripts/aitubiao-cli.sh query-snapshot-job <snapshotJob.id>
status:
success:用 results[] 替换第四步响应中的 charts[],把 results[].screenshotUrl 提供给用户failed:把 errorMessage 告知用户,项目本体仍可在 projectUrl 访问processing:告知用户「截图还在生成,约 10 秒后再试」,等用户再次明确要求时再查询processing 时告知用户「截图生成较慢,可稍后访问 projectUrl 查看,项目本体已经创建成功」query-snapshot-job 都是独立的 Bash 调用,禁止在同一次 Bash 调用里 sleep 循环{
"id": "...",
"status": "processing | success | failed",
"totalCharts": 9,
"results": [
{
"index": 1,
"type": "basic-bar",
"title": "Revenue Trend",
"description": "...",
"screenshotSuccess": true,
"screenshotUrl": "https://oss.xxx/ai-snapshot/..."
}
],
"errorMessage": "...",
"completedAt": "2026-05-14T08:31:14.000Z"
}
如果用户在项目创建成功后要求“帮我下载或者导出这个项目”,使用统一 CLI 下载命令:
bash scripts/aitubiao-cli.sh download-project <本地保存路径> <<'EOF'
{
"projectId": "<project.id>",
"format": "png"
}
EOF
规则:
projectId 使用上一步返回的 project.idformat 按用户需求填写:PPT 项目可用 ppt/pdf/png,图表/桑基图项目可用 png/jpg/pdf/pptpng/jpg/pdf 任何用户均可免费导出;ppt 需要 PPT 导出权限(付费会员);其它特殊格式(svg/gif/mp4/mov/透明 PNG/2x 及以上倍率)也需对应会员权益。如果用户尝试受限格式但权益不足,CLI 会返回 exit 2 并附服务端错误,应告知用户升级会员或改用免费格式$HOME/Downloads/<filename> 或当前工作目录下的具体文件名),不要省略命令参数not writable 或 cannot be created),此时禁止自动改路径重试——必须先告诉用户当前路径不可写,请用户给一个可写的位置projectId 并发执行 download-project:服务端默认每个项目只允许 1 个 API Key 并发导出任务。需要重试时,等待上一次下载彻底完成(成功或失败)再重新发起*.partial 临时文件,校验文件大小与已知格式(png/jpg/pdf/ppt/zip)的魔数后再原子重命名为最终路径。如果 CLI 返回 exit 3 且 stderr 含 integrity check failed,说明服务端返回的文件已损坏;不要伪装成功,告知用户重试或联系支持png/jpg/pdf 格式导出多页时,服务端会把所有页面压缩成一个 ZIP 包返回。CLI 检测到这种情况会自动把保存路径改为 .zip(例如 report.png → report.zip),并在 stderr 输出 Note: server returned a multi-page ZIP bundle ...。返回 JSON 中的 savedPath 和 fileName 是真实落盘路径——告诉用户文件位置时必须使用这两个字段,不要使用最初传入的路径savedPath(绝对路径)告诉用户文件保存在哪里| CLI Exit Code | 含义 | 处理方式 |
|---|---|---|
| 1 | 认证失败(HTTP 401/403 或凭证无效) | 立即停止,引导用户前往 API Key 管理页面 |
| 2 | 业务错误(code 90001=AI贝不足,40007=项目数已满,15009=同一项目已有 API Key 导出任务进行中) | 向用户展示详情,引导充值或删除旧项目;遇到 15009 时,提示用户等待上一个导出完成后再重试 |
| 3 | 网络/超时错误 | 告知用户稍后重试 |
CLI 成功时(exit 0)stdout 输出的 JSON 结构:
{
"success": true,
"project": {
"id": "cuid_string",
"title": "Sales Analysis",
"status": "generated",
"width": 960,
"height": 540,
"projectUrl": "https://app.aitubiao.com/workspace/cuid_string?utm_source=skill_skill-clawhub&channel=skill-clawhub"
},
"charts": [
{
"index": 1,
"type": "basic-bar",
"title": "Revenue Trend",
"description": "Monthly revenue analysis.",
"screenshotSuccess": false
}
],
"snapshotJob": {
"id": "snapshot_job_id",
"status": "processing",
"totalCharts": 1
},
"quota": {
"shellCoinCost": 10,
"shellBalance": 90,
"projectsUsed": 6,
"projectsLimit": 50,
"projectsRemaining": 44,
"canCreateProject": true
},
"totalCharts": 1,
"processingTime": "25000ms"
}
注意:
charts[].screenshotSuccess 为 false、无 screenshotUrl;如需截图请走「可选:获取图表截图」节,用 snapshotJob.id 轮询。quota 可能为 null。quota.shellCoinCost 是实际扣费金额(已按真实生成的图表数结算),可能小于预扣的 maxCharts × .feature.cost。quota.shellBalance 已包含部分退款。基础: basic-bar, basic-column, basic-line, basic-pie, basic-radar, bar-progress, donut-progress 分组: grouped-bar, grouped-column 堆叠: stacked-bar, stacked-column, stacked-area, percent-bar, percent-column, percent-stacked-bar, percent-stacked-column 混合: mixed-line-grouped-column, mixed-line-stacked-column 特殊: funnel, cascaded-area, river-area, butterfly, dynamic-bar, dynamic-ranking, jade-jue 高级: sankey, chord, voronoi, descartes-heatmap, single-layer-treemap, word-cloud, rose-pie, symbol-bar, symbol-column, symbol-pie, difference-arrow-bar, difference-arrow-column, liquid, compose-waterfall, check-in-bubble
Q1:这个技能收费吗?
A:技能本身完全免费,任何人都可以安装使用。但生成图表时会调用爱图表的 AI 服务,该服务会按生成的图表个数消耗 AI贝(爱图表平台的虚拟点数)。
Q2:AI贝怎么获得?用完怎么办?
A:AI贝通过订阅爱图表会员获得。
💡 建议先用免费体验效果,确认满足需求后再订阅。
Q3:API Key 是什么?怎么获取?
A:API Key 是你的"爱图表平台通行证",用于验证你的身份和账户余额。
获取步骤:
sk_v1_... 格式字符串🔒 安全提示:Key 只保存在你本地电脑的
~/.aitubiao/credentials文件中,不会泄露给任何人。
Q4:我需要在电脑上安装什么额外软件吗?
A:需要确保你的电脑已安装以下工具(通常系统自带或开发环境已有):
| 系统 | 需要安装 |
|---|---|
| macOS/Linux | curl、jq(jq 可能需要手动安装:brew install jq 或 apt install jq) |
| Windows | Git Bash(推荐)、curl、jq |
如果不确定是否已安装,可以告诉 AI "帮我检查环境",系统会自动检测并提示缺失项。
Q5:支持哪些数据格式?文件大小有限制吗?
A:支持常见的数据格式:
| 数据来源 | 说明 |
|---|---|
| 直接粘贴 | 在对话中直接粘贴表格数据,AI 会自动识别结构 |
| Excel 文件(.xlsx / .xls) | 上传 Excel 文件,AI 自动读取 |
| CSV 文件 | 上传 .csv 文件,AI 自动读取 |
| TXT 文件 | 上传包含结构化文本的 .txt 文件 |
⚠️ 文件大小限制:单个文件不超过 100K。如果文件较大,建议拆分成多个小文件分批上传,或直接粘贴数据。
💡 推荐使用 Excel 或 CSV,数据结构更清晰,AI 识别更准确。
Q6:AI 怎么处理我上传的数据?
A:上传数据后,AI 会按以下流程处理:
💡 如果对某张图表不满意,可以返回数据块列表,对同一个数据块重新生成图表,或对未生成过的数据块进行新的图表生成。
Q7:提示 401/403 错误怎么办?
A:401 或 403 表示 API Key 无效或已过期。请按以下步骤处理:
⚠️ 401/403 不是网络超时,不要重试,重试只会浪费时间,直接换新 Key 即可。
Q8:提示"AI贝余额不足"怎么办?
A:说明你的爱图表账户AI贝已用完,无法生成新的图表。
解决方案:
💡 你可以在生成前的费用确认界面看到当前余额,提前判断是否需要充值。
Q9:提示"项目数已满"怎么办?
A:爱图表免费版对"未删除的旧项目"有数量上限(通常为 10个左右),满了之后无法创建新项目。
解决方案:
Q10:生成过程中卡住或报错"超时"怎么办?
A:生成图表是后台任务,通常需要 1-3 分钟。
⚠️ 禁止重复提交:如果已经收到"项目创建成功"的提示,说明任务已经在后台排队,不要再次提交,否则可能重复扣费。
Q11:生成后的图表在哪里查看?
A:项目创建成功后,AI 会立即返回一个专属链接,格式类似:
点击该链接即可在浏览器中实时查看生成进度和最终效果。
Q12:生成的图表可以编辑吗?
A:可以。爱图表提供了灵活的编辑方式:
Q13:怎么下载图表文件?
A:生成完成后,对 AI 说 "帮我下载这个图表项目",AI 会通过爱图表 API 导出文件。
你也可以在爱图表工作台手动下载:
各格式说明:
| 格式 | 适用场景 | 是否需要付费 |
|---|---|---|
png / jpg / pdf | 预览、插入文档 | 免费导出 |
ppt(PPTX 源文件) | 继续编辑 | 需付费会员权益 |
如果提示"当前会员不支持 PPT 导出",可以选择 pdf 或 png 格式免费导出。
Q14:可以保存图表到项目吗?
A:可以。点击图表下方的「保存」,系统会创建一个新的项目,将当前图表保存到项目中。这样你可以把多次生成的图表汇总到同一个项目里统一管理。
遇到问题时,可以按此流程自行判断:
遇到问题 │ ├─ 401/403 错误 → 去爱图表官网重新创建 API Key → 粘贴新 Key │ ├─ "余额不足" → 去爱图表官网充值或订阅 → 重新发起 │ ├─ "项目数已满" → 去爱图表工作台删除旧项目 → 重新发起 │ ├─ 文件上传失败 → 检查文件是否超过 100K → 拆分或直接粘贴数据 │ ├─ 生成超过 3 分钟没反应 → 点击返回的链接查看进度 → 正常排队中 │ └─ 其他报错 → 将报错信息完整复制给 AI → AI 会引导你处理