Chart Image

核心用法

chart-image 是基于 Vega-Lite 的无头图表生成工具，通过 Node.js 脚本将 JSON 数据转换为 PNG/SVG 图像。支持命令行调用，典型工作流：

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

支持的图表类型：线图、柱状图、面积图、散点图、饼图/环形图、K线蜡烛图、热力图、多序列对比、堆叠图、双Y轴叠加（如价格+成交量）。

关键特性：

• 无浏览器依赖：纯 Node.js 实现，对比 Puppeteer 方案减少 400MB+ 体积
• 预编译二进制：使用 Sharp 图像库，无需原生编译工具链
• 冷启动 <500ms：无 Chrome 启动延迟，适合 Serverless/Fly.io 场景
• 完全离线：零外部 API 调用，对比 QuickChart.io 等 SaaS 方案

显著优点

1. 部署友好：专为 Docker/VPS 设计，解决 node-canvas 常见的系统依赖地狱
2. 功能完整：覆盖金融 K 线、热力图、Sparkline 微图、时间序列、双轴组合等复杂场景
3. 输出灵活：内置社交媒体预设尺寸（Twitter/Bluesky/Instagram）、暗黑模式自动切换、自定义 d3-format 格式化
4. 监控优化：--show-change、--focus-recent、--show-values 等选项专为告警图表设计

潜在缺点/局限性

• 数据预处理依赖：仅接受 JSON 数组输入，无内置数据清洗/聚合能力
• 样式定制深度有限：复杂自定义需直接编辑 Vega-Lite spec（--spec 选项），门槛较高
• 无交互性：仅生成静态 PNG/SVG，不支持 tooltip、缩放等动态功能
• Node.js 绑定：非多语言方案，异构技术栈需额外封装

适合人群

• 运维/告警系统开发者：需要低延迟、离线生成监控图表的后端服务
• Fly.io/Docker 部署用户：追求最小镜像体积、零原生编译的容器化场景
• 量化/金融数据团队：需要 K 线、成交量叠加、时间序列标注等专业图表
• 社交媒体自动化：程序化生成固定尺寸图表用于 Bot 推送

常规风险

• 文件系统权限：输出目录需可写，建议使用 /data/clawd/tmp/ 而非系统 /tmp
• JSON 注入风险：--data 参数直接解析用户输入，需确保上游已做注入过滤
• 资源占用：大量并发生成时 Sharp 图像处理可能占用内存，建议队列限流
• 时区感知：--dark 自动模式基于以色列时区（UTC+2/+3），跨国部署需手动覆盖

核心用法

chart-image 是一款专为无头服务器环境设计的图表生成工具，通过命令行将 JSON 数据转换为 PNG/SVG 图表。核心依赖 Vega-Lite（图表定义）和 Sharp（图像渲染），采用预编译二进制方案，彻底规避了传统 Node.js 图表工具常见的原生编译痛点。

基础工作流

cd /data/clawd/skills/chart-image/scripts && npm install  # 一次性安装

# 通用模式：指定类型 → 传入数据 → 输出文件
node chart.mjs --type <chart_type> --data '[...]' --output chart.png

支持的图表类型

| 类型 | 典型场景 | 关键参数 |

|------|---------|---------|

| `line` | 时间序列趋势 | `--no-points`, `--line-width` |

| `bar` | 分类对比 | `--stacked`, `--bar-radius` |

| `area` | 累积趋势 | — |

| `candlestick` | 金融 OHLC | `--open/high/low/close-field` |

| `pie`/`donut` | 占比分布 | `--category-field`, `--y-field` |

| `heatmap` | 矩阵密度 | `--color-value-field` |

高级特性

• 双 Y 轴：--y2-field 实现组合图表（如价格线 + 成交量柱）
• 时间轴智能处理：--x-type temporal 自动处理日期间隔
• 社交预设：--output-size bluesky/portrait 一键适配平台尺寸
• 注解系统：--annotations 标记事件节点，--show-change 自动计算涨跌幅

---

显著优点

部署友好性极佳

• 无 Puppeteer/Chrome 依赖（~400MB → ~15MB）
• 无 node-canvas 编译陷阱（Sharp 预编译二进制）
• Fly.io/Docker 开箱即用，冷启动 <500ms

功能覆盖全面

• 10+ 图表类型、深色模式、 sparkline、双轴、堆叠、热力图
• 货币/百分比/紧凑数字等格式化内置
• Vega-Lite 底层支持，理论上可扩展至几乎任何可视化需求

运维成本低

• 纯离线运行，零外部 API 调用
• 无网络依赖，无密钥管理
• MIT 协议开源，代码透明

---

局限性与注意事项

输入数据需预处理

• 仅接受 JSON 数组，不支持 CSV/Excel 直连
• 无内置数据清洗，异常值需用户预先处理

样式定制有门槛

• 主题系统较简单（仅 light/dark）
• 复杂样式需直接编辑 Vega-Lite spec（--spec 参数）

Sharp 兼容性边界

• 极个别架构（如某些 Alpine Linux 配置）可能遇到二进制加载问题
• 非安全风险，但生产环境建议预验证

社区规模有限

• T2 级别来源（可信组织/个人开发者），非大厂背书
• 功能迭代依赖 Cluka-399 个人维护

---

适合人群

| 场景 | 匹配度 | 说明 |

|------|--------|------|

| 飞书/Discord/Telegram 机器人图表 | ⭐⭐⭐⭐⭐ | 轻量、快速、无浏览器开销 |

| 监控告警可视化 | ⭐⭐⭐⭐⭐ | `--show-change` + `--dark` 专为告警设计 |

| 静态报告生成 | ⭐⭐⭐⭐☆ | 需预先将数据转为 JSON |

| 交互式 BI 仪表板 | ⭐⭐☆☆☆ | 输出为静态图片，无交互能力 |

| 复杂自定义可视化 | ⭐⭐⭐☆☆ | 需掌握 Vega-Lite 语法 |

---

常规风险提示

• RISK-001：Sharp 原生依赖在受限环境（特定 Alpine 版本、ARM 架构）可能需要额外配置
• RISK-002：JSON.parse 解析用户输入，虽无已知原型链污染漏洞，但建议确保数据来源可信
• RISK-003：版本迭代较快（当前 2.6.18），建议锁定版本或定期审计依赖 CVE

> 综合评估：低风险、高实用价值的工具型 Skill，尤其适合容器化部署的自动化图表场景。建议在 /data/clawd/tmp/ 目录输出文件，并通过 action=send 而非 thread-reply 发送图片。