介绍
# Chart Image Generator
使用 Vega-Lite 从数据生成 PNG 图表图像。非常适合无头服务器环境。
## 为什么选择此技能？
**专为 Fly.io / VPS / Docker 部署构建：** - ✅ **无需原生编译** - 使用带有预构建二进制文件的 Sharp（不像需要构建工具的 `canvas`） - ✅ **无需 Puppeteer/浏览器** - 纯 Node.js，无需下载 Chrome，没有无头浏览器开销 - ✅ **轻量级** - 约 15MB 的总依赖，而基于 Puppeteer 的方案需 400MB+ - ✅ **快速冷启动** - 无浏览器启动延迟，图表生成时间 <500ms - ✅ **离线工作** - 无外部 API 调用（不像 QuickChart.io）
## 设置（一次性）
```bash cd /data/clawd/skills/chart-image/scripts && npm install ```
## 快速使用
```bash 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 ```
## 图表类型
### 折线图（默认） ```bash node chart.mjs --type line --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output line.png ```
### 条形图 ```bash node chart.mjs --type bar --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output bar.png ```
### 面积图 ```bash node chart.mjs --type area --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output area.png ```
### 饼图 / 环形图 ```bash # 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 ```
### 蜡烛图（OHLC） ```bash 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 ```
### 热力图 ```bash 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 ```
### 多系列折线图 在一张图表上对比多个趋势： ```bash 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 ```
### 堆叠条形图 ```bash 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 轴） 价格线配合成交量条形： ```bash 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 ```
### 迷你图（微型内联图表） ```bash 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" | auto |
### 视觉选项 | 选项 | 描述 | 默认值 | |--------|-------------|---------| | `--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 个数据点 | all | | `--show-values` | 标记最小/最大峰值点 | false |
### 多系列/堆叠选项 | 选项 | 描述 | 默认值 | |--------|-------------|---------| | `--series-field` | 多系列折线图的字段 | - | | `--stacked` | 启用堆叠条形模式 | false | | `--color-field` | 堆叠/颜色类别的字段 | - |
### 蜡烛图选项 | 选项 | 描述 | 默认值 | |--------|-------------|---------| | `--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 |
### 成交量叠加选项 | 选项 | 描述 | 默认值 | |--------|-------------|---------| | `--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 数组 | - |
## 警报风格图表（推荐用于监控）
```bash node chart.mjs --type line --data '[...]' \ --title "Iran Strike Odds (48h)" \ --show-change --focus-change --show-values --dark \ --output alert.png ```
仅显示近期操作： ```bash node chart.mjs --type line --data '[hourly data...]' \ --focus-recent 4 --show-change --focus-change --dark \ --output recent.png ```
## 时间轴注释
在图表上标记事件： ```bash node chart.mjs --type line --data '[...]' \ --annotations '[{"x":"14:00","label":"News broke"},{"x":"16:30","label":"Press conf"}]' \ --output annotated.png ```
## 时间 X 轴
用于带有日期间隔的正确时间序列： ```bash 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 轴格式化
格式化坐标轴值以提高可读性： ```bash # 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`
## 图表副标题
在标题下方添加上下文： ```bash 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 本地时间)**：浅色模式（默认）
## 管道数据传输
```bash echo '[{"x":"A","y":1},{"x":"B","y":2}]' | node chart.mjs --output out.png ```
## 自定义 Vega-Lite 规范
用于高级图表： ```bash node chart.mjs --spec my-spec.json --output custom.png ```
## ⚠️ 重要：始终发送图片！
生成图表后，**务必将其发送回用户的频道**。 不要只是保存到文件并描述它——整个重点在于可视化。
```bash # 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*