Flint Chart

Flint 图表

Flint 是一个图表渲染服务，通过 MCP 暴露给 agent。能力：95 个图表模板 × 3 个可渲染后端 × 10 套主题。

本 skill 的核心目标不只是「把图渲染出来」，而是让用户在对话里直接看到图。这两件事不是一回事——渲染成功但用户看不见，等于没做。

三条铁律（先读这个）

1. 图必须在「你自己的回复正文」里，不能只在工具结果里

工具返回的 markdown 图片链接，只有被复制进助手回复正文时才会渲染。留在工具结果卡片里用户是看不到的。

✅ 正确：工具返回 ![](http://localhost:3000/api/flint/artifacts/xxx)
        → 你在回复正文里原样写一遍这一行
❌ 错误：调完工具就直接说「图已生成」 —— 用户什么也看不到

2. 用 delivery="url" + format="png"

• delivery 服务端默认已是 url（返回图片链接）。不要用 inline——console 会丢弃内联图片块，历史上就这么踩过坑。
• format="png" 最稳。chartjs 后端只支持 png（传 svg 会报错）；vegalite/echarts 两者都行，但展示场景一律 png。

3. 你看不见自己生成的图

你是纯文本模型，图片字节会被剥离。所以：

• 不要声称「图看起来不错」「配色很协调」——你没看过。
• 只能说客观事实：尺寸、后端、是否成功、有没有警告。
• 用户如果问视觉问题（文字重叠、配色），如实说需要他自己确认。

一次调用的完整流程

1. 想清楚图型 → 见下方「图表类型选择」
2. 调用 flint__render_chart，参数：data + semantic_types + chart_spec + backend + format + delivery
3. 读返回：第一行是 `后端 · 格式 · 宽×高px`
4. 取出返回里的 ![chart](url) 那一行
5. 把这一行写进你的回复正文
6. 顺带说明：图型、维度、尺寸；有 warnings 就转述

工具返回怎么读

vegalite · png · 720×587px          ← 后端 · 格式 · 尺寸（用来向用户汇报）
![chart](http://localhost:3000/...)  ← ★ 必须粘贴进正文的就是这一行
产物链接: http://localhost:3000/...
artifactId: 20260910-b8f4e9b7642058e8-25aa3b
mimeType: image/png
expiresAt: 2026-09-17T10:16:55.956Z  ← 产物 7 天后过期，用户要长期保存就得下载

失败时会返回 isError: true 和中文错误说明；有 warnings 时把警告如实转述给用户（很多警告是在提示数据语义问题，很有价值）。

请求参数

{
  "data": { "values": [ {"字段A": "...", "字段B": 123}, ... ] },
  "semantic_types": { "字段A": "Category", "字段B": "Quantity" },
  "chart_spec": {
    "chartType": "Bar Chart",
    "title": "一句话结论（强烈建议）",
    "subtitle": "统计口径，如 2025 年月活（万）",
    "encodings": { "x": {"field": "字段A"}, "y": {"field": "字段B"} },
    "baseSize": { "width": 720, "height": 420 }
  },
  "field_display_names": { "字段A": "展示名" },
  "theme_spec": "economist",
  "backend": "vegalite",
  "format": "png",
  "delivery": "url"
}

plotly 和 excel 后端只能编译不能渲染，MCP 里调不通，别用。

图表类型选择

完整清单（95 个模板 + 各自支持的通道）见 references/chart-types.md。 不确定有哪些模板时，也可以调 flint__list_chart_types。

已知陷阱

这些是实测确认过的行为，踩了会浪费时间。下表尺寸类结论为 2026-09-10 构建直接实测所得：

回退：如果图还是显示不出来

极少数情况下图片链接可能不渲染。此时把图落盘后作为文件发给用户：

cd {本 skill 目录} && python3 scripts/fetch_chart.py <产物URL> <输出路径>

拿到本地文件后调用 send_file_to_user 发出去。这一步是兜底，正常情况下不需要。

完整示例

用户：「帮我把这几个渠道的营收画个柱状图」

{
  "data": { "values": [
    {"渠道": "官网", "营收": 128},
    {"渠道": "应用商店", "营收": 96},
    {"渠道": "合作方", "营收": 74},
    {"渠道": "线下", "营收": 52}
  ]},
  "semantic_types": { "渠道": "Category", "营收": "Quantity" },
  "chart_spec": {
    "chartType": "Bar Chart",
    "title": "官网渠道贡献最高，占四成营收",
    "subtitle": "各渠道营收（万元）",
    "encodings": { "x": {"field": "渠道"}, "y": {"field": "营收"} },
    "baseSize": { "width": 720, "height": 420 }
  },
  "theme_spec": "economist",
  "backend": "vegalite",
  "format": "png",
  "delivery": "url"
}

然后在回复里：

已生成，官网渠道最高（128 万）：

「然后在回复里贴链接」这一步不能省。