Flint 完全指南：Microsoft 为 AI Agent 打造的声明式可视化语言

AI 编码 Agent（Claude Code、Codex、Cursor）擅长写代码、调试错误、重构架构，但让它们生成一张好看的图表——折线图、柱状图、热力图甚至桑基图——往往是一场灾难。你要在提示词里反复描述颜色、轴标签、图例位置，得到的却是一段残缺的 matplotlib 代码或一张格式错乱的 SVG。

Microsoft Research 与中国人民大学 IDEAS Lab 联合开源的 Flint 就是为解决这个问题而生的。它是一个可视化中间语言——AI Agent 用简洁的声明式描述「要什么图」，Flint 编译器自动推导出缩放、轴、标签、间距、图例等所有细节，输出 Vega-Lite、ECharts 或 Chart.js 三种后端的原生配置。MIT 许可证，TypeScript 编写，GitHub 1563⭐。

核心架构

Flint 的核心理念是一次 Spec，多端渲染。它的输入是一个 ChartAssemblyInput 对象，包含三部分：

语义类型（semantic types）是 Flint 最巧妙的设计。它内置 70+ 种语义类型（Rank、Temperature、Price、Country 等），告诉编译器每个字段在真实世界中”是什么”。有了这个信息，编译器才能自动决定轴标签格式（摄氏度带 °C、金额带 $）、色阶方案（国家用分类色、温度用连续色）和图例位置。

安装

npm install flint-chart

npx -y flint-chart-mcp

Node.js 18+ 即可，零外部依赖。Python 版目前是源码预览，PyPI 发布计划在后续版本中。

在代码中使用 Flint

基础用法

三个后端导出函数接受完全相同的输入，返回对应库的原生配置对象：

import { assembleVegaLite, assembleECharts, assembleChartjs } from 'flint-chart';

const input = {
  data: { values: myData },
  semantic_types: { weight: 'Quantity', mpg: 'Quantity', origin: 'Country' },
  chart_spec: {
    chartType: 'Scatter Plot',
    encodings: {
      x: { field: 'weight' },
      y: { field: 'mpg' },
      color: { field: 'origin' },
    },
    baseSize: { width: 400, height: 300 },
  },
};

const vlSpec = assembleVegaLite(input);   // Vega-Lite JSON
const ecSpec = assembleECharts(input);    // ECharts option
const cjsSpec = assembleChartjs(input);   // Chart.js config

替换后端只需换一个函数名——输入形状完全不变。

语义标注进阶

简单的字段用字符串简写即可，复杂场景可以用完整 SemanticAnnotation 对象：

const input = {
  data: { values: reviews },
  semantic_types: {
    score: { semanticType: 'Rating', intrinsicDomain: [1, 5], unit: '分' },
    department: { semanticType: 'Category', sortOrder: ['工程', '产品', '设计', '市场'] },
    date: 'Date',
  },
  chart_spec: {
    chartType: 'Grouped Bar Chart',
    encodings: { x: { field: 'department' }, y: { field: 'score' }, color: { field: 'quarter' } },
  },
};

intrinsicDomain 告诉编译器分数的天然范围是 1-5，unit 让轴标签显示”分”字，sortOrder 让部门按自定义顺序排列而非字母序。

支持的图表类型

Flint 的 Vega-Lite 后端（参考实现）支持 34 种图表类型，分为 6 大类：

每种图表的编码通道（x、y、color、size、opacity、column、row）和专用参数（如 cornerRadius、stackMode、regressionMethod）都在项目的 Vega-Lite chart reference 中有完整表格。

为 AI Agent 配置 Flint MCP 服务器

Flint 的 MCP 服务器让 Agent 在对话中直接创建、验证和渲染图表——这是 Flint 的杀手级场景。

Claude Code 配置

在 ~/.claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "flint": {
      "command": "npx",
      "args": ["-y", "flint-chart-mcp"]
    }
  }
}

Codex CLI 配置

在 ~/.codex/config.json 中添加：

{
  "mcpServers": {
    "flint": {
      "command": "npx",
      "args": ["-y", "flint-chart-mcp"]
    }
  }
}

配置完成后，Agent 就能自动调用 Flint 的 MCP 工具来创建图表。它会在对话中打开交互式图表预览，同时返回静态 PNG/SVG 输出或后端原生 Spec。

MCP 工具的工作流

Agent 通过 MCP 工具可以：

1. 选择模板：根据数据类型和意图推荐合适的图表类型
2. 验证 Spec：检查 chart_spec 的编码通道是否完整
3. 编译渲染：将 Spec 编译为后端配置并渲染为可视化
4. 嵌入数据：直接在 data.values 中嵌入行数据，或通过 data.url 读取本地 JSON/CSV/TSV

如果不使用 MCP，可以直接使用项目提供的 agent skill 作为独立技能。

最佳实践

1. 语义类型一次标注，多次复用

对一个数据集写好 semantic_types 后，可以在不同图表中复用——切换到折线图、热力图或饼图时只需修改 chart_spec.chartType 和 encodings，语义信息不变。

2. 用 baseSize 控制布局

baseSize 是目标布局尺寸，Flint 编译器会根据数据基数、图表类型和画布约束自动调整间距、标签密度和图例位置。传 { width: 400, height: 300 } 即可，不需要手动调参。

3. 用 canvasSize 设置硬上限

如果渲染环境有严格的尺寸限制（如 Slack 内嵌预览的 500px 宽），用 canvasSize 设置硬上限。

4. 用前缀检查后端支持

不是所有 34 种图表类型在每个后端都可用。用 vlGetTemplateDef、ecGetTemplateDef 或 cjsGetTemplateDef 函数检查特定后端的支持情况，不支持的 chartType 会在编译时抛出明确的错误。

注意事项

• Python 包尚未正式发布：当前 packages/flint-py 是源码预览，输入形状对标 JS API，但还不能通过 pip 安装。Python 用户需要等 PyPI 发布。
• Vega-Lite 是参考实现：34 种图表类型中最全的是 Vega-Lite 后端。ECharts 和 Chart.js 后端覆盖了常用的 15-20 种类型，复杂图表（如 Sankey、Parallel Coordinates）建议使用 Vega-Lite。
• Agent 生成的 Spec 仍需人工审阅：虽然 Flint 大幅降低了图表生成的不确定性，但涉及数据安全的场景（如内部报表自动生成），建议在发布前人工检查编译后的 Spec 是否包含了不应曝光的数据字段。

总结

Flint 解决了 AI Agent 生成可视化时的一个核心矛盾——人类和机器对”好看”的定义不同。通过声明式 Spec + 语义标注 + 自动布局，让 Agent 能以人类可读的形式描述意图，让编译器处理所有细节工程。如果你是 Claude Code、Codex 或 Cursor 的重度用户，经常需要让 Agent 生成图表，Flint 的 MCP 服务器值得一试——一行 npx -y flint-chart-mcp 就能把 Agent 变成一个靠谱的数据可视化助手。

相关链接：

• GitHub: microsoft/flint-chart
• API Reference
• Flint MCP Server Guide
• npm: flint-chart
• npm: flint-chart-mcp