svg-chart

SVG Chart

把数据画成一个独立的 .svg 文件。纯标准库，无第三方依赖。

什么时候用

用户给了一组数字（直接写在对话里、或一个 JSON / CSV 文件），并想看图： 对比、趋势、占比、分布、「画个图」「可视化一下」。

选哪种图

脚本	适用	判据
bar.py	类目之间比大小	各项之间没有先后顺序，或顺序不重要
line.py	沿时间/序列看变化趋势	横轴有内在顺序（月份、天、版本号）
pie.py	一个整体的构成占比	各项相加等于 100%；超过 7 项就别用饼图，改 bar.py

拿不准就用 bar.py。它出错的方式最少。

数据格式

JSON（推荐 —— 结构明确，不会被分隔符坑）

{
  "title": "2026 上半年各区销售额",
  "x_label": "月份",
  "y_label": "销售额（万元）",
  "categories": ["1月", "2月", "3月", "4月", "5月", "6月"],
  "series": [
    { "name": "华东", "values": [120, 135, 150, 148, 162, 175] },
    { "name": "华南", "values": [90, 95, 88, 102, 110, 118] }
  ]
}

• categories 与每个系列的 values 必须等长，否则脚本会报错并告诉你差多少。
• 缺失值写 null。不要用 0 代替缺失 —— 0 是「值就是零」，柱状图会画出实心柱、折线图会把线拉到底，都是错的读数。
• title / x_label / y_label 可省，但尽量给 —— 没有标题的图基本没法用。
• 饼图只读第一个系列，x_label 无意义。

CSV / TSV（用户已经有表格文件时直接喂）

月份,华东,华南
1月,120,90
2月,135,95

首行是表头（第一格是纵轴名，其后每格一个系列名），其后每行第一格是类目名。 分隔符自动识别，TSV 无需额外参数。空格子视为缺失。

怎么跑

python <本 skill 目录>/scripts/bar.py  --data <草稿区>/data.json  --out <交付区>/chart.svg
python <本 skill 目录>/scripts/line.py --data <草稿区>/data.csv   --out <交付区>/trend.svg --no-dots
python <本 skill 目录>/scripts/pie.py  --data <草稿区>/share.json --out <交付区>/share.svg --donut

路径一律写绝对路径（尖括号是占位符，别照抄）。草稿区 / 交付区的实际位置见系统提示的「文件放哪」那节 —— --data 是中间数据、放草稿区；--out 是要交给用户的成果、必须放交付区。

通用参数：--width（默认 800）、--height（默认 480）。 类目多或名字长时把 --width 调到 960~1200，否则横轴标签会挤成一团。

line.py 专有：--no-dots 不画数据点（点超过 40 个时自动省略）。 pie.py 专有：--donut 画成环形图。

工作流

1. 先把数据落成文件，写到草稿区。 用户在对话里报的数字，先写成 data.json， 别想着传命令行参数。落成文件的好处：出错时能回头核对原始数据，改一个数重跑即可。 数据文件是中间产物，放草稿区 —— 用户要的是那张图，不是这份 json。
2. 选图、跑脚本，--out 指向交付区。 脚本会打印「已生成 xxx.svg（N 类目 × M 系列）」， 核对这个数字跟你的预期一致 —— 不一致说明数据解析跟你想的不一样。
3. 读一遍产出的 SVG，确认三件事：标题在、坐标轴有刻度、系列数量对得上。 SVG 是文本，直接 read_file 就能看。
4. 确认 .svg 落在交付区里，再把路径告诉用户。放在别处用户下载不到，等于白做。

注意

• 数据不对就报错，不猜。列数不齐、非数字、饼图给负值 —— 脚本一律退出并说明原因， 不会硬画出一张似是而非的图。看到报错先回去改数据，别改脚本参数硬顶。
• 纵轴刻度是自动取整的（1 / 2 / 2.5 / 5 的十进制倍数），所以轴范围通常比数据范围略宽， 这是正常的、为了刻度可读。
• 纵轴从 0 起（基线始终包含 0）。这是刻意的：截断纵轴会放大差异、误导读者。 真需要放大局部差异，请在结论文字里说明，而不是靠裁轴。
• 中文标签直接写，不用管字体 —— SVG 的文字由查看器渲染，无需嵌入字体文件。
• 输出是确定性的：同样输入必得同样字节。