ai-status-light/docs/api.md

OpenCode Monitor API 接口文档

基础信息

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

接口列表

1. 健康检查

GET /api/health

响应示例:

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

2. 获取所有 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
    }
  ]
}

3. 创建 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
  }
}

4. 获取单个 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
  }
}

5. 更新 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
  }
}

6. 删除 MQTT 配置

DELETE /api/mqtt/:id

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

响应示例:

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

7. 获取所有 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
    }
  ]
}

8. 创建 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	否	AI-Light	BLE 设备名称
service_uuid	string	否	b8b7e001-...	BLE 服务 UUID
char_uuid	string	否	b8b7e002-...	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
  }
}

9. 获取单个 BLE 配置

GET /api/ble/:id

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

10. 更新 BLE 配置

PUT /api/ble/:id

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

请求体:

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

11. 删除 BLE 配置

DELETE /api/ble/:id

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

错误响应

所有错误响应格式:

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

启动方式

# 方式1: 独立启动 API 服务
./bin/opencode-monitor serve --addr :8080

# 方式2: 监控时同时启动 API 服务
./bin/opencode-monitor monitor --ports 4096 --api-addr :8080

全局选项

以下选项适用于 monitor、serve、config 三个子命令：

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

日志示例

# 默认日志到 ./logs/monitor.log
./bin/opencode-monitor monitor --ports 4096

# 指定日志路径
./bin/opencode-monitor serve --log-file /var/log/monitor.log

# 开启 debug 日志
./bin/opencode-monitor monitor --scan 4096-4100 --log-level debug

日志文件轮转

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

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

CORS

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

MQTT 推送说明

配置启用后，监控到状态变化时会自动推送到配置的 topic。消息格式为 JSON：

{
  "port": 4096,
  "status": "工作中",
  "code": "busy",
  "timestamp": "2026-06-03T14:30:00Z"
}

推送的状态类型

status	code	说明
空闲	idle	会话空闲
工作中	busy	会话工作中
重试中	retry	会话重试中
修改中	pending	会话修改中
思考中	reasoning	模型推理中
使用工具中	using_tool	AI 正在使用工具
等待中	pending	工具等待执行
运行中	running	工具执行中（可附带工具名，如 运行中: read）
工具执行完成	completed	工具执行完成（可附带工具名，如 工具执行完成: read）
会话完成	session_completed	会话执行完成
等待权限	permission	AI 向用户申请权限
错误	error	会话错误

BLE 蓝牙推送说明

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

构建含 BLE 的版本

# 一键构建（打包 Python 脚本 + 嵌入 Go 二进制）
make build-with-ble

# 或手动两步
scripts\build_ble_relay.bat
go build -tags ble -o bin/opencode-monitor.exe ./cmd/monitor

Python 依赖（仅开发时需要）

pip install -r scripts/requirements.txt

状态映射

Go 状态码	蓝牙模式	说明
idle	idle	空闲
busy	busy	工作中
retry	thinking	重试中
pending	thinking	等待/修改中
reasoning	thinking	思考中
using_tool	ai	使用工具
running	ai	工具运行中
completed	success	完成
session_completed	success	会话完成
permission	alarm	等待权限
error	error	错误

Python 依赖（仅 Python 方式需要）

pip install -r scripts/requirements.txt

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

WebSocket 实时状态

启动监控服务后，可以通过浏览器访问 http://localhost:8080 查看实时状态页面。

WebSocket 连接

ws://localhost:8080/ws

消息格式

WebSocket 推送的消息格式为 JSON：

{
  "port": 4096,
  "status": "工作中",
  "code": "busy",
  "timestamp": "2026-06-03T14:30:00Z"
}

使用示例

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('状态更新:', data);
};