AI 生成
让图表从数据与一句话需求里长出来：粘贴表格数据，引擎自动识别列类型（时间 / 数值 / 类目）、选择图表类型、映射字段并渲染；描述里带「趋势 / 占比 / 排行 / 堆叠 / 关系」等意图词时按意图选型，留空则按数据形状推断。年份列（1970 这类裸年份，或数值型年份配「年份 / year」表头）自动认作时间维度；多个度量之间量级悬殊（峰值相差百倍以上）时自动切双轴——大度量柱走左轴、其余线走右轴，小度量不再被压成贴地直线。三维同一条路径可达：明确要三维或数据天然三维（三个数值列无类目维度）时产出三维 Spec。要接自己的大模型？buildChartPrompt() 产出标准提示词，模型返回的 JSON 过一遍 lintChartSpec() 自检修正，setSpec() 回放即得图。
数据直生
下面是一个可编辑的完整闭环：改表格或改描述，点「生成图表」——列推断、选型理由与自检结论全部可见。
· 识别到 3 个数值列、0 个时间列、1 个类目列；意图「trend」
· 折线图：维度有序（时间/类目），看走势与多系列对比
· 叙述注解 2 处（峰值 callout / 末点环比 delta）
查看生成的 Spec
{
"title": "渠道月度销售额",
"type": "line",
"labels": [
"1月",
"2月",
"3月",
"4月",
"5月",
"6月"
],
"series": [
{
"name": "线上商城",
"data": [
320,
356,
401,
388,
520,
560
]
},
{
"name": "线下门店",
"data": [
280,
302,
346,
331,
352,
428
]
},
{
"name": "社群团购",
"data": [
120,
98,
131,
145,
167,
183
]
}
],
"legend": {
"show": true
},
"annotations": [
{
"type": "callout",
"x": "6月",
"y": 560,
"series": "线上商城",
"label": "峰值 560",
"anchor": "top-right"
},
{
"type": "delta",
"x": "6月",
"y": 560,
"series": "线上商城",
"direction": "up",
"text": "环比 +8%"
}
]
}setSpec() 是整体替换：每点一次「生成图表」就是换一张图，图例、缩放、焦点等交互态一并重置。
三维生成
二维能讲清的数据不会硬上三维。两种情况进三维选型：描述里明确要「三维 / 立体 / 3D」，或数据天然三维——三个数值列且没有类目维度（二维散点必丢一维）。三个数值列恰好构成完整网格（前两列取值的组合覆盖全部行）时产出 surface3d 高度场，稀疏三元组则是 scatter3d；带类目或时间维度时按意图映射 bar3d 柱林 / line3d 空间折线 / pie3d 三维饼，维度不足则告警并回退二维。lintChartSpec() 遇到 *3d 图型会自动切三维契约校验。
· 识别到 3 个数值列、0 个时间列、0 个类目列；意图「relation」
· 三维曲面：温度 × 压力 构成 4×2 完整高度场（产率）
· 三维 spec 已过 schema 校验（几何层自检仅覆盖二维图型）
三维图型与相机配置详见三维篇章。
接入大模型
库不做内置模型调用——buildChartPrompt() 把 Schema、数据预览与硬性规则打包成提示词，喂给你自己的模型（在线 API 或私有部署均可），返回的 JSON 自检后回放：
import { buildChartPrompt, lintChartSpec } from '@wil-works/evoke-charts'
// 1. 组提示词（含 options JSON Schema、数据预览与硬性规则）
const prompt = buildChartPrompt({ data: tableText, requirement: '近半年各渠道销售额占比' })
// 2. 喂给你的模型，取回 JSON（示意）
const spec = JSON.parse(await myLLM.complete(prompt))
// 3. 自检修正后 setSpec 回放
const { spec: safe, issues } = lintChartSpec(spec)
if (!issues.some((i) => i.level === 'error')) chartRef.value.setSpec(safe)模型不可用或返回不合格时，generateChartSpec() 的确定性推断就是兜底路径——同一段数据，两条路产出同一份 Spec 契约。要生成三维配置，把 mode 换成 '3d'：Schema、few-shot 示例与硬性规则整套切到三维篇章契约（EvChart3d options）。
API
AI 生成
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| generateChartSpec | 数据 + 意图 → Spec。返回 { spec, report }：spec 为 null 时 report 说明缘由；report 给出列推断、选型理由与告警。hint 支持意图关键词，narrative: true 自动注入峰值 callout 与末点环比 delta（受三处注解预算约束）。需求带三维/立体/3D 或三个数值列（无类目维度）时产出三维 Spec（surface3d / scatter3d / bar3d / line3d / pie3d） | (data, hint?) => { spec, report } | — |
| lintChartSpec | 渲染自检：schema 校验 → 焦点预算（注解 ≤3）→ 扇区数量 → 类目拥挤自动转横向 → 无头渲染文本越界与相互重叠 → 自定义色板明暗双模式 WCAG 对比度。*3d 图型自动切三维 schema 校验。能修则修，返回 { issues, spec }（修后的副本，原对象不动） | (spec, opts?) => { issues, spec } | — |
| buildChartPrompt | 提示词契约：Schema + 数据预览 + few-shot 示例（examples: false 关闭）+ 需求 + 硬性规则。mode: 3d 时整套切到三维篇章（EvChart3d options + 三维示例与规则） | ({ data, requirement, extraRules?, examples?, mode? }) => string | 2d（缺省） |
| parseDataTable | CSV / TSV 文本、对象数组、二维数组 → { headers, rows }；首行表头自动识别 | (input) => table | null | — |