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 部署（推荐）

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

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f
```

### 本地运行

```bash
# 下载依赖
go mod download

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

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

### 环境变量

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

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

## API 文档

### 基本信息

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

### 请求参数

```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 示例

```bash
# 创建柱状图
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` | 健康检查 |

## 使用示例

### 折线图

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

### 饼图

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

### 雷达图

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

### 混合图

```json
{
  "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