# PowerTools Agent Skill

PowerTools 是一个车辆性能测试数据分析平台。Agent 可以提交 CSV 数据文件，获取专业的性能分析报告。

> **本文档会经常更新。** 如果你在使用 API 时遇到问题（接口报错、字段变化、新功能不可用等），请重新访问本 Skill 的地址，获取最新版本后再重试。不要依赖缓存中的旧版本。

---

## 概述

PowerTools 提供以下核心能力：

| 功能 | 说明 |
|------|------|
| **提交报告** | 上传 CSV 文件，生成车辆性能分析报告 |
| **查询报告** | 获取报告列表和详细信息 |
| **额度管理** | 查询账户剩余额度 |

---

## 快速开始

### 1. 获取 API Key

你需要从 PowerTools 管理员处获取 API Key：
- 格式：`sk_` + 8位前缀 + 56位十六进制字符
- 示例：`sk_ptAB12cd_abc123def456...`

**重要**：API Key 需要管理员手动创建，暂不支持自动注册。

### 2. 认证方式

所有 API 请求必须在请求头中携带 API Key：

```http
Authorization: Bearer YOUR_API_KEY
```

### 3. 第一个请求

```bash
# 查询额度
curl -X GET "https://4hbhqk5w93.coze.site/api/user/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## 核心流程

### 方式一：上传文件后提交（推荐）

```bash
# Step 1: 上传 CSV 文件
curl -X POST "https://4hbhqk5w93.coze.site/api/user/upload-csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "csvFile=@vehicle_data.csv"

# 返回：{ "success": true, "file_id": "xxx", "file_url": "..." }

# Step 2: 使用 file_id 提交报告
curl -X POST "https://4hbhqk5w93.coze.site/api/user/reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "上一步返回的file_id",
    "vehicle_name": "BMW M4 S55 Stage3",
    "test_type": "TMC"
  }'
```

### 方式二：直接提交 Base64 数据

```bash
# 适用于已有 CSV 内容的场景
curl -X POST "https://4hbhqk5w93.coze.site/api/user/reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv_base64": "Q1NWIGRhdGEgaW4gYmFzZTY0...",
    "vehicle_name": "BMW M4 S55 Stage3",
    "test_type": "TMC"
  }'
```

---

## API 接口详情

### 1. 查询额度

```
GET /api/user/quota
```

**响应示例：**

```json
{
  "quota": {
    "role": "user",
    "unlimited": false,
    "total": 100,
    "used": 25,
    "remaining": 75
  }
}
```

管理员或高级用户：

```json
{
  "quota": {
    "role": "admin",
    "unlimited": true,
    "message": "无额度限制"
  }
}
```

---

### 2. 上传 CSV 文件

```
POST /api/user/upload-csv
Content-Type: multipart/form-data
```

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| csvFile | File | ✅ | CSV 格式的数据文件 |

**响应示例：**

```json
{
  "success": true,
  "file_id": "YXBpX3VwbG9hZHMvMTczNzg...",
  "file_url": "https://storage.example.com/...",
  "file_name": "vehicle_data.csv",
  "file_size": 12345,
  "expires_in": 604800
}
```

**限制：**
- 文件格式：仅支持 CSV
- 文件大小：最大 10MB
- 有效期：文件 URL 7 天内有效

---

### 3. 提交报告

```
POST /api/user/reports
Content-Type: application/json
```

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| csv_base64 | string | 二选一 | Base64 编码的 CSV 内容 |
| file_id | string | 二选一 | 上传文件返回的 ID |
| vehicle_name | string | ✅ | 车辆名称，如 "BMW M4 S55 Stage3" |
| test_type | string | ❌ | 测试类型，如 "TMC"、"马力机" |
| hardware1 | string | ❌ | 硬件配置1 |
| hardware2 | string | ❌ | 硬件配置2 |
| brand_text | string | ❌ | 品牌文字（高级用户专属） |
| report_title | string | ❌ | 报告标题（高级用户专属） |

**响应示例（成功）：**

```json
{
  "success": true,
  "report_id": "uuid-xxx-xxx",
  "report_url": "https://storage.example.com/report.png",
  "vehicle_name": "BMW M4 S55 Stage3",
  "test_type": "TMC",
  "peak_summary": "Peak Power: 488.1Ps / 686.3Nm",
  "message": "报告生成成功"
}
```

**响应示例（失败）：**

```json
{
  "success": false,
  "report_id": "uuid-xxx-xxx",
  "error": "报告生成失败",
  "details": "未返回报告图片"
}
```

---

### 4. 查询报告列表

```
GET /api/user/reports
```

**查询参数：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| limit | int | 20 | 每页数量 (1-100) |
| offset | int | 0 | 偏移量 |

**响应示例：**

```json
{
  "reports": [
    {
      "id": "uuid-xxx",
      "reportName": "BMW M4 S55",
      "vehicleBrand": "TMC",
      "vehicleModel": "API 提交",
      "testDate": "2025-01-15",
      "status": "completed",
      "reportImageUrl": "https://...",
      "peakSummary": "Peak Power: 488.1Ps",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}
```

---

### 5. 查询报告详情

```
GET /api/user/reports/{report_id}
```

**响应示例：**

```json
{
  "id": "uuid-xxx",
  "reportName": "BMW M4 S55",
  "vehicleBrand": "TMC",
  "vehicleModel": "API 提交",
  "testDate": "2025-01-15",
  "status": "completed",
  "csvFileUrl": "https://...",
  "reportImageUrl": "https://...",
  "peakSummary": "Peak Power: 488.1Ps / 686.3Nm",
  "hardware1": null,
  "hardware2": null,
  "createdAt": "2025-01-15T10:30:00Z"
}
```

---

## 元数据接口（无需认证）

这些接口供 Agent 动态获取系统信息，无需 API Key。

### 版本信息

```
GET /api/version
```

```json
{
  "version": "1.6.6",
  "fullVersion": "v1.6.6",
  "buildDate": "2025-01-15",
  "environment": "production"
}
```

### 变更日志

```
GET /api/changelog
```

```json
{
  "changelog": [
    {
      "version": "1.6.6",
      "date": "2025-01-15",
      "changes": ["新增飞书 Webhook 通知通道", "新增元数据接口"]
    }
  ]
}
```

### 健康检查

```
GET /api/health
```

```json
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "services": {
    "database": "ok",
    "storage": "ok"
  }
}
```

---

## 错误处理

### 错误码说明

| 状态码 | 错误信息 | 说明 |
|--------|----------|------|
| 400 | 参数错误 | 缺少必填参数或参数格式错误 |
| 401 | 认证失败 | API Key 无效或已过期 |
| 403 | 权限不足 | 额度用尽或无权访问 |
| 404 | 资源不存在 | 报告或文件不存在 |
| 429 | 请求过于频繁 | 超过频率限制 |
| 500 | 服务器错误 | 内部处理失败 |

### 错误响应格式

```json
{
  "error": "错误标题",
  "details": "详细错误信息"
}
```

---

## 频率限制

| 操作 | 限制 |
|------|------|
| 上传文件 | 10 次/分钟 |
| 提交报告 | 5 次/分钟 |
| 查询接口 | 60 次/分钟 |

超过限制返回 **429 Too Many Requests**。

---

## 注意事项

1. **额度限制**：普通用户需要购买套餐，管理员和高级用户不限额度
2. **文件格式**：仅支持 CSV 格式的车辆测试数据
3. **处理时间**：报告生成需要 10-30 秒，请耐心等待
4. **文件有效期**：上传的文件 URL 7 天内有效
5. **Demo 用户**：同一 IP 或设备每天最多生成 2 次报告

---

## 使用建议

### 心跳流程（每 5 分钟执行一次）

```
1. GET /api/user/quota → 检查额度
2. GET /api/user/reports?limit=5 → 查看最近报告
3. 如果有新 CSV 数据 → 提交报告
```

### 最佳实践

1. **优先使用 file_id**：先上传文件，再提交报告，更稳定
2. **缓存 file_id**：同一文件可重复提交（7天内）
3. **检查额度**：提交前先查询额度，避免浪费请求
4. **处理异步**：报告生成可能需要时间，建议轮询查询

---

## API 快速索引

| 功能 | 方法 | 路径 | 认证 |
|------|------|------|------|
| 查询额度 | GET | /api/user/quota | ✅ |
| 上传文件 | POST | /api/user/upload-csv | ✅ |
| 提交报告 | POST | /api/user/reports | ✅ |
| 报告列表 | GET | /api/user/reports | ✅ |
| 报告详情 | GET | /api/user/reports/{id} | ✅ |
| 版本信息 | GET | /api/version | ❌ |
| 变更日志 | GET | /api/changelog | ❌ |
| 健康检查 | GET | /api/health | ❌ |

---

## 联系支持

如有问题或需要获取 API Key，请联系 PowerTools 管理员。

---

*最后更新：2025-01-15 | 版本：1.0.0*