chart-image

图表图像生成器

使用 Vega-Lite 根据数据生成 PNG 图表图像。非常适合无头服务器环境。

为什么选择此工具？

专为 Fly.io / VPS / Docker 部署打造：

• ✅ 无需原生编译 - 使用带预构建二进制文件的 Sharp（而 canvas 需要构建工具）
• ✅ 无需 Puppeteer/浏览器 - 纯 Node.js，无需下载 Chrome，也没有无头浏览器的额外开销
• ✅ 轻量 - 依赖总大小约为 15MB，而基于 Puppeteer 的解决方案超过 400MB
• ✅ 冷启动快速 - 没有浏览器启动延迟，图表可在 500ms 内生成
• ✅ 支持离线运行 - 不会调用外部 API（与 QuickChart.io 不同）

一次性设置

cd /data/clawd/skills/chart-image/scripts && npm install

快速使用

node /data/clawd/skills/chart-image/scripts/chart.mjs \
  --type line \
  --data '[{"x":"10:00","y":25},{"x":"10:30","y":27},{"x":"11:00","y":31}]' \
  --title "Price Over Time" \
  --output chart.png

图表类型

折线图（默认）

node chart.mjs --type line --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output line.png

柱状图

node chart.mjs --type bar --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output bar.png

面积图

node chart.mjs --type area --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output area.png

饼图 / 环形图

# Pie
node chart.mjs --type pie --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output pie.png

# Donut (with hole)
node chart.mjs --type donut --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output donut.png

K 线图（OHLC）

node chart.mjs --type candlestick \
  --data '[{"x":"Mon","open":100,"high":110,"low":95,"close":105}]' \
  --open-field open --high-field high --low-field low --close-field close \
  --title "Stock Price" --output candle.png

热力图

node chart.mjs --type heatmap \
  --data '[{"x":"Mon","y":"Week1","value":5},{"x":"Tue","y":"Week1","value":8}]' \
  --color-value-field value --color-scheme viridis \
  --title "Activity Heatmap" --output heatmap.png

多系列折线图

在一张图表中比较多种趋势：

node chart.mjs --type line --series-field "market" \
  --data '[{"x":"Jan","y":10,"market":"A"},{"x":"Jan","y":15,"market":"B"}]' \
  --title "Comparison" --output multi.png

堆叠柱状图

node chart.mjs --type bar --stacked --color-field "category" \
  --data '[{"x":"Mon","y":10,"category":"Work"},{"x":"Mon","y":5,"category":"Personal"}]' \
  --title "Hours by Category" --output stacked.png

成交量叠加图（双 Y 轴）

带成交量柱状图的价格折线：

node chart.mjs --type line --volume-field volume \
  --data '[{"x":"10:00","y":100,"volume":5000},{"x":"11:00","y":105,"volume":3000}]' \
  --title "Price + Volume" --output volume.png

迷你折线图（内嵌小图表）

node chart.mjs --sparkline --data '[{"x":"1","y":10},{"x":"2","y":15}]' --output spark.png

迷你折线图默认尺寸为 80x20，背景透明且不显示坐标轴。

选项参考

基本选项

选项	说明	默认值
--type	图表类型：line、bar、area、point、pie、donut、candlestick、heatmap	line
--data	数据点的 JSON 数组	-
--output	输出文件路径	chart.png
--title	图表标题	-
--width	宽度（像素）	600
--height	高度（像素）	300

坐标轴选项

选项	说明	默认值
--x-field	X 轴的字段名称	x
--y-field	Y 轴的字段名称	y
--x-title	X 轴标签	字段名称
--y-title	Y 轴标签	字段名称
--x-type	X 轴类型：ordinal、temporal、quantitative	ordinal
--y-domain	Y 轴范围，格式为 "min,max"	自动

视觉选项

选项	说明	默认值
--color	折线/柱状图颜色	#e63946
--dark	深色模式主题	false
--svg	输出 SVG 而非 PNG	false
--color-scheme	Vega 配色方案（category10、viridis 等）	-

警报/监控选项

选项	说明	默认值
--show-change	在最后一个数据点显示 +/-% 变化标注	false
--focus-change	将 Y 轴缩放至数据范围的 2 倍	false
--focus-recent N	仅显示最后 N 个数据点	全部
--show-values	标注最小值/最大值峰值点	false

多系列/堆叠选项

选项	说明	默认值
--series-field	多系列折线图所用字段	-
--stacked	启用堆叠柱状图模式	false
--color-field	用于堆叠/分类着色的字段	-

K 线图选项

选项	说明	默认值
--open-field	OHLC 开盘价字段	open
--high-field	OHLC 最高价字段	high
--low-field	OHLC 最低价字段	low
--close-field	OHLC 收盘价字段	close

饼图/环形图选项

选项	说明	默认值
--category-field	饼图切片分类字段	x
--donut	渲染为环形图（带中心孔）	false

热力图选项

选项	说明	默认值
--color-value-field	热力图强度字段	value
--y-category-field	Y 轴分类字段	y

双轴选项（通用）

选项	说明	默认值
--y2-field	第二个 Y 轴字段（独立的右侧坐标轴）	-
--y2-title	第二个 Y 轴标题	字段名称
--y2-color	第二组数据的颜色	#60a5fa（深色）/ #2563eb（浅色）
--y2-type	第二个坐标轴的图表类型：line、bar、area	line

示例： 营收柱状图（左侧）+ 客户流失率面积图（右侧）：

node chart.mjs \
  --data '[{"month":"Jan","revenue":12000,"churn":4.2},...]' \
  --x-field month --y-field revenue --type bar \
  --y2-field churn --y2-type area --y2-color "#60a5fa" \
  --y-title "Revenue ($)" --y2-title "Churn (%)" \
  --x-sort none --dark --title "Revenue vs Churn"

成交量叠加选项（蜡烛图）

选项	描述	默认值
--volume-field	成交量柱的字段（启用双轴）	-
--volume-color	成交量柱的颜色	#4a5568

格式选项

选项	描述	默认值
--y-format	Y 轴格式：percent、dollar、compact、decimal4、integer、scientific，或 d3-format 字符串	auto
--subtitle	图表标题下方的副标题文本	-
--hline	水平参考线："value"、"value,color" 或 "value,color,label"（可重复）	-

注释选项

选项	描述	默认值
--annotation	静态文本注释	-
--annotations	事件标记的 JSON 数组	-

警报风格图表（监控场景推荐）

node chart.mjs --type line --data '[...]' \
  --title "Iran Strike Odds (48h)" \
  --show-change --focus-change --show-values --dark \
  --output alert.png

仅显示近期操作：

node chart.mjs --type line --data '[hourly data...]' \
  --focus-recent 4 --show-change --focus-change --dark \
  --output recent.png

时间线注释

在图表上标记事件：

node chart.mjs --type line --data '[...]' \
  --annotations '[{"x":"14:00","label":"News broke"},{"x":"16:30","label":"Press conf"}]' \
  --output annotated.png

时间型 X 轴

适用于存在日期间隔的时间序列：

node chart.mjs --type line --x-type temporal \
  --data '[{"x":"2026-01-01","y":10},{"x":"2026-01-15","y":20}]' \
  --output temporal.png

当 X 值为 ISO 日期，且你希望间距反映实际时间间隔（而非均匀分布）时，请使用 --x-type temporal。

Y 轴格式

设置轴值格式，以便于阅读：

# Dollar amounts
node chart.mjs --data '[...]' --y-format dollar --output revenue.png
# → $1,234.56

# Percentages (values as decimals 0-1)
node chart.mjs --data '[...]' --y-format percent --output rates.png
# → 45.2%

# Compact large numbers
node chart.mjs --data '[...]' --y-format compact --output users.png
# → 1.2K, 3.4M

# Crypto prices (4 decimal places)
node chart.mjs --data '[...]' --y-format decimal4 --output molt.png
# → 0.0004

# Custom d3-format string
node chart.mjs --data '[...]' --y-format ',.3f' --output custom.png

可用的快捷选项：percent、dollar/usd、compact、integer、decimal2、decimal4、scientific

图表副标题

在标题下方添加上下文信息：

node chart.mjs --title "MOLT Price" --subtitle "20,668 MOLT held" --data '[...]' --output molt.png

主题选择

使用 --dark 启用深色模式。根据时间自动选择：

• 夜间（当地时间 20:00-07:00）：--dark
• 白天（当地时间 07:00-20:00）：浅色模式（默认）

通过管道传递数据

echo '[{"x":"A","y":1},{"x":"B","y":2}]' | node chart.mjs --output out.png

自定义 Vega-Lite 规范

用于高级图表：

node chart.mjs --spec my-spec.json --output custom.png

⚠️ 重要：始终发送图像！

生成图表后，务必将其发送回用户所在的频道。 不要只保存到文件并进行描述——图表的核心价值就在于视觉呈现。

# 1. Generate the chart
node chart.mjs --type line --data '...' --output /data/clawd/tmp/my-chart.png

# 2. Send it! Use message tool with filePath:
#    action=send, target=<channel_id>, filePath=/data/clawd/tmp/my-chart.png

提示：

• 保存到 /data/clawd/tmp/（持久化目录），而不是 /tmp/（可能会被清理）
• 使用 action=send 和 filePath——thread-reply 不支持文件附件
• 在消息文本中附上简短说明
• 以色列时间 20:00-07:00 期间自动使用 --dark

---

更新日期：2026-02-04 - 新增 --y-format（percent/dollar/compact/decimal4）和 --subtitle