aitubiao-sankey（爱土标桑基）

AI 桑基图生成

根据用户提供的数据，自动整理为桑基图（Sankey Diagram）流向格式并创建可视化项目。

强制规则

以下规则必须严格执行，不得跳过、变通或使用替代方案：

1. 认证优先：在执行任何操作之前，必须先检查凭证状态。认证未通过时，禁止执行任何后续步骤。
2. 按顺序执行：工作流程的 5 个步骤必须按顺序执行，禁止跳步。
3. 确认后才能创建：必须成功查询配额（确认项目数未满）、并获得用户确认后，才能调用创建接口。
4. 仅通过 API 创建桑基图：禁止使用本地工具（D3.js、ECharts、matplotlib、Plotly 等）生成图表。无论 API 因何种原因失败，都绝对禁止使用本地工具，没有任何例外。API 失败时正确做法是停止并告知用户，不是寻找替代方案。
5. 401/403 立即停止：任何步骤中收到 HTTP 401/403（CLI exit 1），立即停止并引导用户前往 API Key 管理页面 检查或重新创建 API Key。401/403 不是超时，禁止重试。
6. 超时/500 不自动重试创建接口：创建接口不可重试（可能重复创建项目）。告知用户失败原因，由用户决定是否重新发起。

⚠️ 以下想法是错误的，如果你发现自己在这样想，请立即停止：

• ❌ "API 不可用，我可以用本地工具生成桑基图作为替代" → 违反规则 4
• ❌ "至少让用户看到一些可视化结果" → 本技能唯一输出方式是 aitubiao API
• ❌ "401 可能是暂时性的，重试几次" → 401 是认证失败，重试无意义，按规则 5 处理

认证

在调用任何 API 之前，先检查凭证状态。

检查凭证

bash scripts/aitubiao-cli.sh check-auth

• Exit 0 → 认证通过
• Exit 1 → 凭证问题，按 stderr 提示处理：

- 文件不存在/API_KEY 为空 → 执行下方"配置凭证"流程 - API_KEY 格式无效 → 告知用户"当前 API Key 已失效，请前往 API Key 管理页面 重新创建一个 API Key" - BASE_URL 与当前技能包环境不一致 → 说明凭证中残留了旧环境地址；向用户索要当前仍有效的 API Key，并执行下方"配置凭证"流程重写凭证（通常不需要重新创建 API Key）

配置凭证

1. 向用户索要 API Key（格式：sk_v1_...）。如果没有，引导用户前往 API Key 管理页面 创建一个新的 API Key，然后将创建好的 Key 粘贴回来。
2. 保存凭证：

bash scripts/aitubiao-cli.sh auth <用户提供的key>

1. 验证：再次运行 bash scripts/aitubiao-cli.sh check-auth 确认配置成功。

凭证保存在 ~/.aitubiao/credentials，跨会话持久生效。

Windows / Git Bash 注意事项（仅 Windows 用户需要关注）

在 Windows 上通过 Git Bash 运行本 CLI 时，禁止把含中文等非 ASCII 字符的 JSON 直接写在 heredoc 里——MSYS 会按 Windows 系统代码页（常为 GBK/CP936）转换 argv 字节，传到后端就是乱码。

正确做法：先用 Write 工具把完整 UTF-8 JSON 写到一个临时文件，然后用 --body-file 让 CLI 从文件读取（绕过任何 argv/控制台编码转换）：

# 第一步：用 Write 工具把请求体写到 /tmp/aitubiao-payload.json（内容必须是 UTF-8）
# 第二步：用 --body-file 调用 CLI
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。

macOS / Linux 上无需改动，仍然可以使用 heredoc。

桑基图数据要求

桑基图用于展示数据的流向关系，要求输入数据至少包含：

• 两个分类列（文本类型）：作为"来源"和"目标"节点
• 一个数值列：表示流向的值/权重

示例数据结构：

| 来源部门 | 目标项目 | 预算金额 |
|---------|---------|---------|
| 研发部   | 产品A   | 500    |
| 研发部   | 产品B   | 300    |
| 市场部   | 产品A   | 200    |
| 市场部   | 产品C   | 400    |

如果数据有多个分类列（如：地区 → 部门 → 产品），系统会自动构建多层级流向。

工作流程

每一步必须在前一步完成后才能开始。禁止跳步。

第一步：认证（前置条件：无）

运行检查凭证流程。认证未通过时按"认证"章节流程处理。

认证未通过时，停止。不要读取用户数据，不要做任何分析。

第二步：识别和确认数据（前置条件：第一步认证通过）

判断用户如何提供数据：

• 直接粘贴文本：自行解析为二维数组格式 (string|number)[][]，第一行为表头。
• 本地文件（CSV/TXT）：用 Read 工具读取，然后解析为二维数组。
• Excel 文件（.xlsx/.xls）：使用 xlsx skill 或 Read 工具读取，禁止手动编写 Python 脚本解析 XML。

向用户展示解析后的数据（表格形式），并询问：

• 数据是否正确？
• 有没有特殊要求？

如果数据明显不适合桑基图（例如只有一列、没有分类列），应提前告知用户。

第三步：检查配额并确认（前置条件：第二步数据已确认）

在创建桑基图前，检查用户的项目配额。本操作免费（0 AI贝），但仍需确认项目数未满。

3.1 查询配额

bash scripts/aitubiao-cli.sh quota --skill sankey

桑基图当前免费：.feature.cost 应为 0。如服务端返回值非 0，请以服务端为准并向用户重新确认费用。

3.2 向用户确认

本操作免费（0 AI贝）
当前余额: {shellBalance} 个 AI贝
项目数: 已用 {projectsUsed}/{projectsLimit}

是否继续创建桑基图？

• 如果 projectsRemaining <= 0：告知用户当前项目数已满，需前往 aitubiao 网站升级会员，或在网站中删除旧项目后再继续，不要继续

第四步：创建桑基图项目（前置条件：第三步用户已确认）

只有用户明确确认后才能执行此步骤。

bash scripts/aitubiao-cli.sh create-sankey <<'EOF'
{
  "data": [["来源","目标","值"],["A","B",100],["A","C",200]],
  "projectName": "<项目名称>"
}
EOF

请求体字段说明：

检查 CLI 退出码：

• Exit 0：成功。解析 stdout JSON 获取项目信息。
• Exit 1：认证失败。引导用户前往 API Key 管理页面。
• Exit 2：业务错误。向用户展示错误详情。
• Exit 3：网络/超时错误。告知用户稍后重试。

更多请求字段：pageSize（页面尺寸，默认 960x540）、elementSize（图表元素尺寸，默认 700x500）。

第五步：返回结果（前置条件：第四步创建成功）

向用户提供：

• 项目 URL（从 project.projectUrl 获取）
• 项目 ID（从 project.id 获取）
• 摘要：桑基图标题
• 截图链接（如果 charts[].screenshotSuccess 为 true）
• 资源消耗：本次消耗 0 AI贝、剩余 AI贝、已用项目数/上限

下载已创建项目（可选后续操作）

如果用户在项目创建成功后要求“帮我下载或者导出这个项目”，使用统一 CLI 下载命令：

bash scripts/aitubiao-cli.sh download-project <本地保存路径> <<'EOF'
{
  "projectId": "<project.id>",
  "format": "png"
}
EOF

规则：

• projectId 使用上一步返回的 project.id
• format 按用户需求填写：PPT 项目可用 ppt/pdf/png，图表/桑基图项目可用 png/jpg/pdf/ppt
• 格式费用：png/jpg/pdf 任何用户均可免费导出；ppt 需要 PPT 导出权限（付费会员）；其它特殊格式（svg/gif/mp4/mov/透明 PNG/2x 及以上倍率）也需对应会员权益。如果用户尝试受限格式但权益不足，CLI 会返回 exit 2 并附服务端错误，应告知用户升级会员或改用免费格式
• 本地保存路径处理：

- 优先使用用户明确指定的路径；如果用户没指定，传绝对路径（如 $HOME/Downloads/<filename> 或当前工作目录下的具体文件名），不要省略命令参数 - 不要把文件写入项目源码目录或不可写目录 - CLI 会在启动导出任务之前检查目标目录是否可写：如果失败会立即报错（exit 4，stderr 含 not writable 或 cannot be created），此时禁止自动改路径重试——必须先告诉用户当前路径不可写，请用户给一个可写的位置

• 下载清晰度由服务端按会员权益自动决定：免费用户较低，付费用户更高
• 仅通过此 API 下载，禁止使用本地工具导出替代文件
• 禁止对同一 projectId 并发执行 download-project：服务端默认每个项目只允许 1 个 API Key 并发导出任务。需要重试时，等待上一次下载彻底完成（成功或失败）再重新发起
• 下载完整性：CLI 会先写入 *.partial 临时文件，校验文件大小与已知格式（png/jpg/pdf/ppt/zip）的魔数后再原子重命名为最终路径。如果 CLI 返回 exit 3 且 stderr 含 integrity check failed，说明服务端返回的文件已损坏；不要伪装成功，告知用户重试或联系支持
• 多页导出会自动打成 zip：当 PPT 项目（或多页项目）以 png/jpg/pdf 格式导出多页时，服务端会把所有页面压缩成一个 ZIP 包返回。CLI 检测到这种情况会自动把保存路径改为 .zip（例如 report.png → report.zip），并在 stderr 输出 Note: server returned a multi-page ZIP bundle ...。返回 JSON 中的 savedPath 和 fileName 是真实落盘路径——告诉用户文件位置时必须使用这两个字段，不要使用最初传入的路径
• 告知用户文件位置：成功后必须使用 CLI 返回 JSON 中的 savedPath（绝对路径）告诉用户文件保存在哪里

错误处理

业务错误码