# OpenCode Monitor API 接口文档

## 基础信息

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

## 接口列表

### 1. 健康检查

```
GET /api/health
```

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

### 2. 获取所有客户端状态

```
GET /api/clients
```

**响应示例:**
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "port": 4096,
      "status": "工作中",
      "code": "busy",
      "timestamp": "2026-06-03T14:30:00Z"
    }
  ]
}
```

### 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
# 方式1: 独立启动 API 服务
./bin/opencode-monitor serve --addr :8080

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

# 方式3: 启用 HTTPS (自签名证书)
./bin/opencode-monitor serve --addr :8080 --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 私钥文件路径 |

### monitor 子命令

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--host` | `127.0.0.1` | 主机地址 |
| `--ports` | - | 端口列表，逗号分隔 (如: 4096,4097,4098) |
| `--scan` | - | 扫描端口范围 (如: 4096-4100) |
| `--interval` | `1` | 动态扫描间隔(秒) |
| `--api-addr` | - | API 服务地址 (如: :8080) |
| `--db` | `./data/config.db` | 数据库路径 |
| `--tls` | `false` | 启用 HTTPS (使用自签名证书) |
| `--tls-cert` | `./data/tls/cert.pem` | TLS 证书文件路径 |
| `--tls-key` | `./data/tls/key.pem` | TLS 私钥文件路径 |

### config 子命令

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

### version 子命令

```bash
./bin/opencode-monitor version
```

显示版本信息。

## 全局选项

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

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

### 日志示例

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

```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 的版本

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

# 或手动步骤
python -m PyInstaller --onefile --name ble_relay --distpath bin scripts/ble_relay.py
cp bin/ble_relay cmd/monitor/ble_relay
go build -tags ble -o bin/opencode-monitor ./cmd/monitor
rm -f cmd/monitor/ble_relay
```

### 状态映射

| 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 方式需要）

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

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

## WebSocket 实时状态

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

### WebSocket 连接

```
ws://localhost:8080/ws
```

### 消息格式

WebSocket 推送的消息格式为 JSON：

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

### 使用示例

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

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