# AI Status Light API 接口文档

## 基础信息

- Base URL: `http://localhost:8045`
- Content-Type: `application/json`
- 响应格式: `{ "code": 0, "message": "ok", "data": {} }`

## 接口列表

### 1. 接收事件（AI 工具 Hooks 调用）

```
POST /api/event
```

**请求体:**
```json
{
  "code": "busy",
  "timestamp": "2026-06-27T14:30:00Z"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | string | 是 | 状态码 |
| timestamp | string | 否 | 时间戳 |

**响应示例:**
```json
{
  "code": 0,
  "message": "ok"
}
```

**状态码说明:**

| code | 说明 |
|------|------|
| idle | 空闲 |
| busy | 工作中 |
| reasoning | 思考中 |
| using_tool | 使用工具中 |
| tool_done | 工具执行完成 |
| permission | 等待权限 |
| error | 错误 |
| init | 初始化 |

---

### 2. 健康检查

```
GET /api/health
```

**响应示例:**
```json
{
  "code": 0,
  "message": "ok"
}
```

### 3. 获取所有 MQTT 配置

```
GET /api/mqtt
```

**响应示例:**
```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "broker": "tcp://127.0.0.1:1883",
      "client_id": "opencode-monitor",
      "username": "user",
      "password": "pass",
      "topic": "opencode/status",
      "enabled": true
    }
  ]
}
```

### 4. 创建 MQTT 配置

```
POST /api/mqtt
```

**请求体:**
```json
{
  "broker": "tcp://127.0.0.1:1883",
  "client_id": "opencode-monitor",
  "username": "user",
  "password": "pass",
  "topic": "opencode/status",
  "enabled": true
}
```

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| broker | string | 是 | - | MQTT Broker 地址 |
| client_id | string | 否 | opencode-monitor | 客户端 ID |
| username | string | 否 | - | MQTT 用户名 |
| password | string | 否 | - | MQTT 密码 |
| topic | string | 否 | opencode/status | 推送主题 |
| enabled | boolean | 否 | true | 是否启用 |

**响应示例:**
```json
{
  "code": 0,
  "message": "创建成功",
  "data": {
    "id": 1,
    "broker": "tcp://127.0.0.1:1883",
    "client_id": "opencode-monitor",
    "username": "user",
    "password": "pass",
    "topic": "opencode/status",
    "enabled": true
  }
}
```

### 5. 获取单个 MQTT 配置

```
GET /api/mqtt/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

**响应示例:**
```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1,
    "broker": "tcp://127.0.0.1:1883",
    "client_id": "opencode-monitor",
    "username": "user",
    "password": "pass",
    "topic": "opencode/status",
    "enabled": true
  }
}
```

### 6. 更新 MQTT 配置

```
PUT /api/mqtt/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

**请求体:**
```json
{
  "broker": "tcp://192.168.1.100:1883",
  "client_id": "my-monitor",
  "username": "user",
  "password": "pass",
  "topic": "my/topic",
  "enabled": false
}
```

**响应示例:**
```json
{
  "code": 0,
  "message": "更新成功",
  "data": {
    "id": 1,
    "broker": "tcp://192.168.1.100:1883",
    "client_id": "my-monitor",
    "username": "user",
    "password": "pass",
    "topic": "my/topic",
    "enabled": false
  }
}
```

### 7. 删除 MQTT 配置

```
DELETE /api/mqtt/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

**响应示例:**
```json
{
  "code": 0,
  "message": "删除成功"
}
```

### 8. 获取所有 BLE 配置

```
GET /api/ble
```

**响应示例:**
```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "device_name": "AI-Light",
      "service_uuid": "b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001",
      "char_uuid": "b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001",
      "enabled": true
    }
  ]
}
```

### 9. 创建 BLE 配置

```
POST /api/ble
```

**请求体:**
```json
{
  "device_name": "AI-Light",
  "service_uuid": "b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001",
  "char_uuid": "b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001",
  "enabled": true
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| device_name | string | 是 | BLE 设备名称 |
| service_uuid | string | 是 | BLE 服务 UUID |
| char_uuid | string | 是 | BLE 特征 UUID |
| enabled | boolean | 否 | 是否启用 (默认 true) |

**响应示例:**
```json
{
  "code": 0,
  "message": "创建成功",
  "data": {
    "id": 1,
    "device_name": "AI-Light",
    "service_uuid": "b8b7e001-7a6b-4f4f-9a8b-11c0ffee0001",
    "char_uuid": "b8b7e002-7a6b-4f4f-9a8b-11c0ffee0001",
    "enabled": true
  }
}
```

### 10. 获取单个 BLE 配置

```
GET /api/ble/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

### 11. 更新 BLE 配置

```
PUT /api/ble/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

**请求体:**
```json
{
  "device_name": "MyLight",
  "service_uuid": "xxx",
  "char_uuid": "yyy",
  "enabled": false
}
```

### 12. 删除 BLE 配置

```
DELETE /api/ble/:id
```

**路径参数:**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | integer | 配置 ID |

## 错误响应

所有错误响应格式:
```json
{
  "code": -1,
  "message": "错误信息"
}
```

## 启动方式

```bash
# 启动 API 服务
./ai-status-light serve --addr :8045

# 启用 HTTPS (自签名证书)
./ai-status-light serve --addr :8045 --tls
```

## 子命令选项

### serve 子命令

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--addr` | `:8080` | 监听地址 |
| `--db` | `./data/config.db` | 数据库路径 |
| `--tls` | `false` | 启用 HTTPS (使用自签名证书) |
| `--tls-cert` | `./data/tls/cert.pem` | TLS 证书文件路径 |
| `--tls-key` | `./data/tls/key.pem` | TLS 私钥文件路径 |
| `--log-file` | `./logs` | 日志文件路径 |
| `--log-level` | `info` | 日志级别：`debug`、`info`、`warn`、`error` |

### config 子命令

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--db` | `./data/config.db` | 数据库路径 |

### version 子命令

```bash
./ai-status-light version
```

显示版本信息。

## 全局选项

以下选项适用于 `serve` 和 `config` 子命令：

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--log-file` | `./logs` | 日志文件路径。默认 `./logs/monitor.log`，按天自动轮转，同时输出到控制台和文件 |
| `--log-level` | `info` | 日志级别：`debug`、`info`、`warn`、`error` |

### 日志示例

```bash
# 默认日志到 ./logs/monitor.log
./ai-status-light serve --addr :8045

# 指定日志路径
./ai-status-light serve --log-file /var/log/ai-status-light.log

# 开启 debug 日志
./ai-status-light serve --log-level debug
```

### 日志文件轮转

日志按天自动轮转，跨天后旧文件自动重命名：

```
logs/
├── monitor.log           # 当天日志
├── monitor.log.2026-06-03  # 历史日志
└── monitor.log.2026-06-02  # 历史日志
```

## CORS

API 已启用 CORS，支持跨域请求。

## MQTT 推送说明

配置启用后，收到事件时会自动推送到配置的 topic。消息格式为 JSON：

```json
{
  "code": "busy",
  "timestamp": "2026-06-27T14:30:00Z"
}
```

### 推送的状态类型

| code | 说明 |
|------|------|
| idle | 空闲 |
| busy | 工作中 |
| reasoning | 思考中 |
| using_tool | 使用工具中 |
| tool_done | 工具执行完成 |
| permission | 等待权限 |
| error | 错误 |
| init | 初始化 |

## BLE 蓝牙推送说明

配置 BLE 后，监控到状态变化时会自动通过蓝牙发送到设备。BLE 中继已嵌入 Go 二进制，无需额外文件或 Python 环境。

### 构建含 BLE 的版本

```bash
# 一键构建
scripts/build.sh --ble      # Linux/macOS
scripts\build.bat --ble     # Windows
```

### 状态映射

| API 状态码 | 蓝牙模式 | 说明 |
|-----------|---------|------|
| idle | idle | 空闲 |
| busy | busy | 工作中 |
| reasoning | thinking | 思考中 |
| using_tool | ai | 使用工具 |
| tool_done | success | 工具完成 |
| permission | alarm | 等待权限 |
| error | error | 错误 |
| init | init | 初始化 |

### Python 依赖（仅 Python 方式需要）

```bash
pip install -r scripts/requirements.txt
```

如果使用预编译二进制则不需要安装。

## 设备配置（通过 MQTT 下发）

### 获取所有设备配置

```
GET /api/device/config
```

**响应示例:**

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "device_name": "AI-Light",
      "config_topic": "agent/status/config",
      "wifi_ssid": "MyWiFi",
      "mqtt_broker": "192.168.1.100",
      "mqtt_port": 1883,
      "mqtt_client": "AI-Light",
      "mqtt_topic": "agent/status",
      "pin_red": 4,
      "pin_green": 3,
      "pin_yellow": 2,
      "enabled": true
    }
  ]
}
```

### 创建设备配置

```
POST /api/device/config
```

**请求体:**

```json
{
  "device_name": "AI-Light",
  "config_topic": "agent/status/config",
  "wifi_ssid": "MyWiFi",
  "wifi_pass": "MyPassword",
  "mqtt_broker": "192.168.1.100",
  "mqtt_port": 1883,
  "mqtt_user": "user",
  "mqtt_pass": "pass",
  "mqtt_client": "AI-Light",
  "mqtt_topic": "agent/status",
  "mqtt_status": "agentLight/status",
  "pin_red": 4,
  "pin_green": 3,
  "pin_yellow": 2,
  "enabled": true
}
```

| 字段           | 类型      | 必填 | 默认值                 | 说明              |
|--------------|---------|----|---------------------|-----------------|
| device_name  | string  | 是  | -                   | 设备名称            |
| config_topic | string  | 否  | agent/status/config | 配置 topic        |
| wifi_ssid    | string  | 否  | -                   | WiFi SSID       |
| wifi_pass    | string  | 否  | -                   | WiFi 密码         |
| mqtt_broker  | string  | 否  | -                   | MQTT Broker 地址  |
| mqtt_port    | integer | 否  | 1883                | MQTT 端口         |
| mqtt_user    | string  | 否  | -                   | MQTT 用户名        |
| mqtt_pass    | string  | 否  | -                   | MQTT 密码         |
| mqtt_client  | string  | 否  | -                   | MQTT 客户端 ID     |
| mqtt_topic   | string  | 否  | -                   | MQTT 状态 topic   |
| mqtt_status  | string  | 否  | -                   | MQTT 状态上报 topic |
| pin_red      | integer | 否  | 4                   | 红灯引脚            |
| pin_green    | integer | 否  | 3                   | 绿灯引脚            |
| pin_yellow   | integer | 否  | 2                   | 黄灯引脚            |
| enabled      | boolean | 否  | true                | 是否启用            |

### 获取单个设备配置

```
GET /api/device/config/:id
```

### 更新设备配置

```
PUT /api/device/config/:id
```

### 删除设备配置

```
DELETE /api/device/config/:id
```

### 推送配置到设备

```
POST /api/device/config/push
```

通过 MQTT 向设备下发配置，设备会自动保存到 NVS 并重启。

**请求体:**

```json
{
  "id": 1,
  "reset": false
}
```

| 字段    | 类型      | 必填 | 说明                  |
|-------|---------|----|---------------------|
| id    | integer | 是  | 设备配置 ID             |
| reset | boolean | 否  | 是否恢复出厂设置 (默认 false) |

**响应示例:**

```json
{
  "code": 0,
  "message": "配置已推送"
}
```

**说明:**

- 只推送非空字段到设备
- 设备收到配置后自动保存到 NVS 并重启
- 设置 `reset: true` 可恢复设备出厂设置

---

## SSE 实时状态

启动服务后，可以通过 SSE (Server-Sent Events) 接收实时状态更新。

### SSE 端点

```
GET /api/events
```

### 事件类型

- `connected` - 连接成功
- `status` - 状态更新

### 消息格式

SSE 推送的消息格式为 JSON：

```json
{
  "code": "busy",
  "timestamp": "2026-06-27T14:30:00Z"
}
```

### 使用示例

```javascript
const eventSource = new EventSource('/api/events');

eventSource.addEventListener('connected', (e) => {
  console.log('已连接');
});

eventSource.addEventListener('status', (e) => {
  const data = JSON.parse(e.data);
  console.log('状态更新:', data);
});

eventSource.onerror = () => {
  console.log('连接断开，自动重连中...');
};
```

### curl 测试

```bash
curl -N http://localhost:8045/api/events
```