ai-status-light-web/docs/api.md

后端 API 文档

基础地址：http://localhost:8045

所有接口返回统一格式：

{
  "code": 0,
  "message": "success",
  "data": ...
}

code 为 0 表示成功，非 0 表示失败。

---

1. 获取监控客户端列表

获取当前所有被监控的 AI 客户端（端口）及其状态。

GET /api/clients

响应

data 为数组，每个元素结构如下：

字段	类型	说明
port	number	客户端端口号
status	string	状态描述文本
code	string	状态码（见下方枚举）
timestamp	string	最后更新时间，ISO 8601 格式

状态码枚举

code	说明
idle	空闲
busy	忙碌
retry	重试中
pending	修改中
reasoning	思考中
using_tool	使用工具中
running	运行中
completed	工具执行完成
session_completed	会话完成
permission	等待权限
error	错误

示例

请求

GET /api/clients

响应

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "port": 8001,
      "status": "空闲",
      "code": "idle",
      "timestamp": "2026-06-04T10:00:00Z"
    },
    {
      "port": 8002,
      "status": "运行中",
      "code": "running",
      "timestamp": "2026-06-04T10:05:00Z"
    }
  ]
}

---

2. MQTT 配置管理

2.1 获取所有配置

GET /api/mqtt

响应

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "broker": "mqtt://broker.example.com:1883",
      "client_id": "opencode-monitor",
      "username": "admin",
      "password": "secret",
      "topic": "opencode/status",
      "enabled": true
    }
  ]
}

2.2 获取单个配置

GET /api/mqtt/:id

2.3 创建配置

POST /api/mqtt
Content-Type: application/json

字段	类型	必填	说明
broker	string	是	MQTT 地址
client_id	string	是	客户端 ID
username	string	否	用户名
password	string	否	密码
topic	string	是	订阅主题
enabled	boolean	否	是否启用

2.4 更新配置

PUT /api/mqtt/:id
Content-Type: application/json

请求体同创建。

2.5 删除配置

DELETE /api/mqtt/:id

---

3. WebSocket

前端通过 WebSocket 接收实时端口状态推送。

ws://localhost:8045/ws

消息格式

后端主动推送 JSON 消息：

{
  "port": 8001,
  "status": "运行中",
  "code": "running",
  "timestamp": "2026-06-04T10:05:00Z"
}

字段说明同 GET /api/clients 响应中的元素结构。