flint-chart-author

flint-chart-author — Flint 图表规格作者

你把已经拿到手的结构化数据变成一个合法的 ```flint 围栏块。 Flint 是微软研究院的可视化中间语言：给它 「数据 + 图型 + 编码」，它自己推导刻度、轴、标签、图例、布局——所以你不需要写任何 Vega-Lite / ECharts 的底层配置，写多了反而会被丢弃。

图型清单、通道语义、语义类型表、完整示例与失败模式对照见 references/flint-spec.md，按需载入。

边界

输入	已有的结构化数据、表格、或查询结果（对象数组形态）
职责	选图型与编码 · 必要时先聚合 · 生成 / 修复 / 解释 / 校验 flint 规格
输出	一个 ```flint 围栏块（JSON），块外配一句人话说明它在说什么
不负责	数据库连接与取数权限 · 知识库/wiki 维护 · markdown 存放在哪一页 · 浏览器端渲染

数据从哪来、图放到哪儿去，都由调用你的那条工作流决定；你只对**「这段 JSON 合法且画出来是对的」**负责。

工作流

1. 先看数据，再选图

看三件事：行数、每列的类型（数值 / 类别 / 日期）、你想让读者看出什么。 最后一件决定图型——参考的图型表按用途分组（对比 / 趋势 / 分布 / 相关 / 构成层级 / 流向 / 时间安排）。

拿不准就选最朴素的那个：类别比大小用 Bar Chart，随时间变化用 Line Chart，两个数值的关系用 Scatter Plot。朴素的图被读懂的概率远高于花哨的图。

2. 必要时先聚合——这是你的活，不是 flint 的

flint 不做聚合（encodings.*.aggregate 只在部分模板生效，别指望）。原始明细表要先自己算成 结论性的聚合结果再内联：GROUP BY 之后的几行、十几行，而不是几百行明细。

判据：这张图要说的那句话，需要几行数据才够？ 只要那几行。 搬原始表进来既撞行数上限，也让读者自己去找结论——那是表格的活，不是图的活。

3. 写块

最小形态（semantic_types 可整段省略，flint 会自行推断）：

```flint
{"data":{"values":[{"模型":"model-a","评测得分":72.4},{"模型":"model-b","评测得分":81.9}]},
 "chart_spec":{"chartType":"Bar Chart",
               "encodings":{"x":{"field":"模型"},"y":{"field":"评测得分"}}}}
```

写清楚一点（推荐）：加 semantic_types 让刻度/格式/排序更合理，加 baseSize 定尺寸。 字段名用数据里的原名（中文列名完全可以）。想让轴上显示得更好看，就在数据里把列名改好—— flint 0.4.1 没有「显示名」这种字段（写了不报错也不生效）。

4. 自校验（每次输出前逐条过，不要跳）

• 整块是合法 JSON（不是 YAML、没有注释、没有尾逗号、没有单引号）
• 顶层只有 data / semantic_types / chart_spec / options 之内（别的键一律被丢弃）
• data.values 是对象数组且非空；没有 data.url（渲染端一律拒绝，图不会出现）
• 每个单元格是标量（字符串 / 数字 / 布尔）——不放嵌套对象或数组
• 行数 ≤ 1000
• 类别数别太多：color / column / row 上的取值超出图表容量时，flint 会整批丢掉多余的， 渲染端据此拒渲并显示「数据被截断」——先做 Top-N 聚合，别把几十个类别硬塞进一张图
• chart_spec.chartType 与参考里的写法逐字符一致（大小写敏感：Bar Chart 对，Bar chart 错）
• 每个 encodings.*.field 都能在数据列里找到（任一行有即可）
• 数据形状与图型匹配（Histogram 的 x 必须是数值列、Calendar Heatmap 的 x 必须是日期串……见参考）
• 若写了 baseSize：宽高都是有限正数（baseSize 是基准不是上限——flint 会按类别数/ 分面数把它放大，实测 420×260 在多序列下会长到 657×514）。不必为了栏宽去调它： 渲染端会按正文栏宽让 flint 重新编译一遍；只有大到离谱（宽 >1600 或高 >1200 仍收不住） 才会被判「数据过大」