SuperAPI AI 工具集

data-chart

数据与分析

查看项目

更新于 10-16 14:58

技能介绍

用途

data-chart 用于将实测数据渲染为静态图表,例如折线图、柱状图、散点图、点阵图、直方图、热力图或小倍数图。它的判断依据是图表的内容而非名称:包含真实数字、大量数据点、真实刻度的图表(如对数轴、分布、时间序列)属于该技能的适用范围;而结构示意图(方框、箭头、图层、流水线)或包含少量示意性数值的图形则属于同类的技术图表技能。当请求中明确要求使用原生 draw.io 格式时,才使用 drawio-diagram。对于边界情况(3 到 8 根柱子),如果表示的是可能变化的真实测量值,应使用本技能,因为图表可以从数据重新生成;如果是图表中的装饰性草图,则使用技术图表技能。

主要能力

该技能从读者的问题出发选择图表类型,并参考 chart-selection.md 中的问题到图表对照表、反模式以及可访问性说明。它支持两种样式决策:一种是内置的编辑风格预设,另一种是嵌入文档的自有样式。使用预设时,需要编写一个小型脚本导入样式模块 scripts/editorial_mpl.py,按 ed.use() 启用样式,使用系列颜色绘图,再通过 ed.mono_ticks / ed.axis_label 设置刻度与轴标签,可选地调用 ed.header,最后用 ed.save(fig, stem) 输出 stem.svg 和 stem.png。模块从 assets/editorial-tokens.json 读取内置的令牌值,scripts/example_chart.py 是一个可工作的参考示例,包含折线图和分组柱状图,可以复制其中的 subplots_adjust 边距设置。

执行时不假设系统已安装 matplotlib,应使用 uv run --with matplotlib python <script>.py 的方式来运行,其他依赖也以相同方式添加。在没有 Inter 或 IBM Plex Mono 字体的机器上,findfont 警告是预期行为,回退字体会承载相应的视觉风格。

使用方式

设计底线在任何样式中都适用,包括预设、自有样式或纯 matplotlib。关键规则包括:只强调一个焦点对比,强调通过颜色和位置实现,而不是更粗的线条或更大的字体;优先使用直接标签而非分离的图例,只在端点或一个强调点上显示数值标签,绝不标注每个点;坐标轴和刻度文字保持中性;柱状图必须从零开始,对数轴不能使用柱状图(应使用点),每个图表只使用一个 y 轴刻度,不同量级的度量应拆分为两个图表;默认不添加网格线、四边框、3D 效果、渐变、背景色或装饰性插图;当嵌入文档已经为图表命名时,不添加标题;当直接标签已能说明每个系列时,不添加图例;不得仅为填充画布而添加副标题带、要点带、来源脚注、徽章或插图。

可选的编辑风格预设适用于干净的博客配图外观。完整规则集(结构、令牌、标记、暗色模式)记录在 references/chart-language.md 中,包括无网格的墨水坐标轴、克制的直接标签、每页一个强调色系、等宽数字。该外观仅参考 openai.com 编辑图表的几何、调色板和排版结构,不得添加 OpenAI 的 logo、花朵标志或文字商标,也不得将输出标注为 OpenAI 品牌或暗示关联。OpenAI Sans 是专有字体,样式模块中的 Inter/IBM Plex Mono 堆栈是经批准的替代字体。

适用场景与限制

该技能适用于需要将真实测量数据可视化为静态图表的场景,特别是博客配图或没有自有样式的宿主环境。它也适用于需要矢量输出的消费方,可以在保留 PNG 的同时保留 SVG。它不适合结构示意图或包含少量示意性数值的图形。数据必须来自用户或其文件,绝不能编造或平滑数字;在询问之前应先检查提供的数据。当缺失值的间隙表示有效时应保留间隙;如果省略会改变请求的对比,应在准备支持的图表部分时询问该系列,并披露省略的系列而不是静默丢弃。脚本必须确定性:不使用随机数生成器,输出文件名中不含时间戳。

渲染前检查需要在首次渲染之前以断言方式捕获失败,而不是通过视觉审查循环。检查包括:所有系列共享相同的 x 值(或长度与框架匹配);没有静默的 NaN 丢弃,应统计缺失值并明确决定是保留间隙还是省略;坐标轴范围覆盖数据并为端点标签留出空间,柱状图基线包含零;同一系列内单位一致,当一个主题出现在多个配置中时,说明测量基准(努力或模式,每次尝试还是完整运行);对数轴没有柱状图,每个类别超过约 3 组的分组柱状图应改用点阵图。

在声称完成之前,需要确认脚本运行干净并写出了渲染结果(始终有 PNG;需要矢量时还有 SVG);渲染并实际以预期的显示尺寸查看 PNG;冷读测试:仅从图表本身,读者就能用一句话说出要点;图表中的每个数字都能追溯到用户提供的数据。交付时应报告状态:PASSED、PASSED WITH FIXES(说明修复了什么并重新渲染)或 BLOCKED(缺少哪个输入)。

常见问题包括:端点直接标签位于坐标轴之外,在图边缘会被裁剪,应先预留边距(subplots_adjust(right≈0.88)),通过边距而不是更小的字体来解决裁剪;预设中的珊瑚色中值 (#FF9365) 在白色背景上对比度不足 3:1,珊瑚色系列应保持虚线或直接标注,珊瑚色数值标签应设置为 #804126;ed.header() 会绘制画布以测量每个图例标签,因此应在图形尺寸和边距最终确定后调用,迟到的 subplots_adjust 调用会将绘图移到已放置的标题下方;对数成本或价格轴没有零,因此柱长不承载意义,应改为绘制点;配置比较应使用共享刻度上的小倍数图,小于源自身散布的差距不算结果。