AI Status Light API 接口文档

基础信息

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

接口列表

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

POST /api/event

请求体:

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

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

响应示例:

{
  "code": 0,
  "message": "ok"
}

状态码说明:

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

2. 健康检查

GET /api/health

响应示例:

{
  "code": 0,
  "message": "ok"
}

3. 获取所有 MQTT 配置

GET /api/mqtt

响应示例:

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

请求体:

{
  "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	是否启用

响应示例:

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

响应示例:

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

请求体:

{
  "broker": "tcp://192.168.1.100:1883",
  "client_id": "my-monitor",
  "username": "user",
  "password": "pass",
  "topic": "my/topic",
  "enabled": false
}

响应示例:

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

响应示例:

{
  "code": 0,
  "message": "删除成功"
}

8. 获取所有 BLE 配置

GET /api/ble

响应示例:

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

请求体:

{
  "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)

响应示例:

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

请求体:

{
  "device_name": "MyLight",
  "service_uuid": "xxx",
  "char_uuid": "yyy",
  "enabled": false
}

12. 删除 BLE 配置

DELETE /api/ble/:id

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

错误响应

所有错误响应格式:

{
  "code": -1,
  "message": "错误信息"
}

启动方式

# 启动 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 子命令

./ai-status-light version

显示版本信息。

全局选项

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

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

日志示例

# 默认日志到 ./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：

{
  "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 的版本

# 一键构建
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 方式需要）

pip install -r scripts/requirements.txt

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

设备配置（通过 MQTT 下发）

获取所有设备配置

GET /api/device/config

响应示例:

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

请求体:

{
  "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 并重启。

请求体:

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

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

响应示例:

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

说明:

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

SSE 实时状态

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

SSE 端点

GET /api/events

事件类型

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

消息格式

SSE 推送的消息格式为 JSON：

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

使用示例

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 测试

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

api.md 12 KB История Исходник

AI Status Light API 接口文档

基础信息

接口列表

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

2. 健康检查

3. 获取所有 MQTT 配置

4. 创建 MQTT 配置

5. 获取单个 MQTT 配置

6. 更新 MQTT 配置

7. 删除 MQTT 配置

8. 获取所有 BLE 配置

9. 创建 BLE 配置

10. 获取单个 BLE 配置

11. 更新 BLE 配置

12. 删除 BLE 配置

错误响应

启动方式

子命令选项

serve 子命令

config 子命令

version 子命令

全局选项

日志示例

日志文件轮转

CORS

MQTT 推送说明

推送的状态类型

BLE 蓝牙推送说明

构建含 BLE 的版本

状态映射

Python 依赖（仅 Python 方式需要）

设备配置（通过 MQTT 下发）

获取所有设备配置

创建设备配置

获取单个设备配置

更新设备配置

删除设备配置

推送配置到设备

SSE 实时状态

SSE 端点

事件类型

消息格式

使用示例

curl 测试

api.md 12 KB

История Исходник