terminal-chart-server/README.md

Picoclaw Chart

一个轻量级的图表生成 API 服务，支持多种图表类型，返回多种格式（ANSI、SVG、PNG、Markdown），适配命令行和 Web 场景。

功能特性

• 多种图表类型：折线图、柱状图、饼图、散点图、气泡图、圆环图、混合图、极区图、雷达图
• 多格式输出：ANSI（终端）、SVG（矢量图）、PNG（位图）、Markdown（Web）
• 轻量高效：Go 语言编写，单二进制部署
• Docker 支持：开箱即用的容器化部署

支持的图表类型

类型	英文名	说明
line	折线图	展示数据趋势变化
bar	柱状图	对比分类数据
pie	饼图	展示占比关系
scatter	散点图	展示数据分布
bubble	气泡图	展示多维度数据
donut	圆环图	饼图的变体
mixed	混合图	柱状图+折线图组合
polar	极区图	展示方向/角度数据
radar	雷达图	展示多维度对比

快速开始

Docker 部署（推荐）

# 克隆项目
git clone <your-repo-url>
cd picoclaw-chart

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

本地运行

# 下载依赖
go mod download

# 运行服务
go run ./cmd/server

# 或者编译后运行
go build -o server ./cmd/server
./server

环境变量

复制 .env.example 为 .env 并修改：

SERVER_PORT=3100
BASE_URL=http://localhost:3100

API 文档

基本信息

属性	值
端点	http://localhost:3100/api/v1/chart
方法	POST
内容类型	application/json

请求参数

{
  "type": "bar",
  "title": "图表标题",
  "data": {
    "labels": ["一月", "二月", "三月"],
    "datasets": [
      {
        "name": "销售额",
        "values": [100, 150, 120],
        "color": "#f9c2c8"
      }
    ]
  },
  "options": {
    "width": 600,
    "height": 400
  }
}

参数说明

字段	类型	必填	说明
type	string	否	图表类型，默认 line
title	string	否	图表标题
data.labels	array	是	数据标签
data.datasets	array	是	数据系列
datasets[].name	string	否	系列名称
datasets[].values	array	是	数值数组
datasets[].color	string	否	十六进制颜色
options.width	integer	否	图表宽度
options.height	integer	否	图表高度

响应字段

字段	说明
chart_id	图表唯一标识
text	纯文本描述
ansi	ANSI 彩色文本（终端）
svg	SVG 矢量图代码
png_url	PNG 下载 URL
markdown	Markdown 格式

API 示例

# 创建柱状图
curl -X POST http://localhost:3100/api/v1/chart \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bar",
    "title": "月度销售额",
    "data": {
      "labels": ["一月", "二月", "三月", "四月"],
      "datasets": [
        { "name": "销售额", "values": [100, 150, 120, 180] }
      ]
    }
  }'

# 下载 PNG
curl -O http://localhost:3100/api/v1/chart/{chart_id}.png

# 健康检查
curl http://localhost:3100/api/v1/health

API 端点

方法	路径	说明
POST	/api/v1/chart	创建图表
GET	/api/v1/chart/:id	获取 SVG
GET	/api/v1/chart/:id.png	下载 PNG
GET	/api/v1/health	健康检查

使用示例

折线图

{
  "type": "line",
  "title": "温度趋势",
  "data": {
    "labels": ["周一", "周二", "周三", "周四", "周五"],
    "datasets": [
      { "name": "最高温", "values": [22, 25, 28, 27, 30], "color": "#f9c2c8" },
      { "name": "最低温", "values": [15, 17, 18, 16, 19], "color": "#8fa3c4" }
    ]
  }
}

饼图

{
  "type": "pie",
  "title": "市场份额",
  "data": {
    "labels": ["苹果", "三星", "华为", "其他"],
    "datasets": [
      { "name": "销量", "values": [35, 25, 20, 20] }
    ]
  }
}

雷达图

{
  "type": "radar",
  "title": "员工能力评估",
  "data": {
    "labels": ["速度", "力量", "耐力", "智力", "敏捷"],
    "datasets": [
      { "name": "张三", "values": [80, 70, 90, 85, 75] }
    ]
  }
}

混合图

{
  "type": "mixed",
  "title": "销售与目标对比",
  "data": {
    "labels": ["一月", "二月", "三月", "四月"],
    "datasets": [
      { "name": "实际", "values": [100, 150, 120, 180] },
      { "name": "目标", "values": [120, 140, 130, 160] }
    ]
  }
}

默认配色

柔和莫兰迪色系：

索引	颜色	HEX
0	粉橙	#f9c2c8
1	杏色	#f3d2b1
2	淡绿	#e1e9c5
3	浅蓝	#b2d5e8
4	灰蓝	#8fa3c4
5	青绿	#75B4A0
6	深青	#3b7f8d
7	棕灰	#a18b7c

项目结构

picoclaw-chart/
├── cmd/server/          # 程序入口
├── internal/
│   ├── config/          # 配置管理
│   ├── handler/          # HTTP 处理层
│   ├── renderer/         # 图表渲染器
│   │   ├── svg.go       # SVG 渲染
│   │   ├── png.go       # PNG 渲染
│   │   ├── ansi.go      # ANSI 渲染
│   │   ├── text.go      # 文本渲染
│   │   └── utils.go     # 工具函数
│   ├── service/          # 业务逻辑层
│   └── types/            # 数据结构
├── .env.example          # 环境变量示例
├── Dockerfile
├── docker-compose.yml
├── skill.md              # Skill 文档
└── README.md

与 picoclaw 集成

将此服务与 picoclaw Agent 集成，只需在 picoclaw 的 skills 配置中添加 skill.md 的内容即可。

Agent 可以通过 curl 调用此 API 生成图表，根据使用场景选择返回的格式：

• 终端显示：使用 ansi 字段
• Web 展示：使用 markdown 字段
• 内嵌 SVG：使用 svg 字段

技术栈

• 语言：Go 1.21+
• 框架：Fiber v2
• 图表库：gonum/plot
• 容器：Docker, Docker Compose

License

MIT License