# kvm1

**Repository Path**: sup4ever/kvm1

## Basic Information

- **Project Name**: kvm1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BlikVM 企微自动化控制项目

基于Spring Boot的BlikVM设备控制客户端，用于**物理控制企业微信**实现自动化操作。

---

## 🎯 项目定位

### ❌ 不是调用企微API
本项目**不是**通过企微SDK或API来调用企微接口，而是：

### ✅ 物理控制企微界面（UI自动化）

```
硬件连接方式：
目标电脑（运行企微）
    ↓ HDMI（视频输出）
BlikVM板子（捕获屏幕 + 模拟键鼠）
    ↓ USB OTG（键盘鼠标输入）
目标电脑（接收控制）
```

**工作原理：**
1. **截图** - 通过HDMI捕获目标电脑屏幕
2. **OCR识别** - 识别屏幕上的按钮、文字位置
3. **鼠标点击** - 通过USB模拟鼠标点击
4. **键盘输入** - 通过USB模拟键盘输入

---

## 🚀 快速开始

```bash
# 1. 启动应用
mvn spring-boot:run

# 2. 登录获取Token
curl -X POST http://localhost:8088/blikvm/login

# 3. 启用OTG（必须，否则无法控制键鼠）
curl -X POST http://localhost:8088/blikvm/hid/enable

# 4. 测试OCR识别（识别全屏英文）
curl "http://localhost:8088/blikvm/ocr/recognize-fullscreen?lang=eng"

# 5. OCR识别指定区域
curl -X POST "http://localhost:8088/blikvm/ocr/recognize?lang=eng&left=100&top=100&width=500&height=200"
```

**应用地址：** `http://localhost:8088`

---

## 📋 企微自动化使用场景

### 场景1：自动发送企微消息

```bash
# 1. 截图并OCR识别（找到"搜索"按钮位置）
curl "http://localhost:8088/blikvm/ocr/recognize-fullscreen?lang=chi,eng" > ocr_result.json
# （需解析ocr_result.json，获取"搜索"按钮的坐标）

# 2. 点击"搜索"按钮（假设坐标为500,100）
curl "http://localhost:8088/blikvm/mouse/click?x=500&y=100"

# 3. 输入联系人名字
curl -X POST "http://localhost:8088/blikvm/keyboard/type?text=张三"

# 4. 按Enter打开聊天窗口
curl -X POST "http://localhost:8088/blikvm/keyboard/press?key=Enter"

# 5. 输入消息内容
curl -X POST "http://localhost:8088/blikvm/keyboard/type?text=你好，这是自动发送的消息"

# 6. 按Enter发送
curl -X POST "http://localhost:8088/blikvm/keyboard/press?key=Enter"
```

**说明：** 实际使用中，需要编写Java代码来解析OCR结果，计算按钮的精确坐标。详见`企微自动化完整方案.md`。

### 场景2：实时监控企微消息

```bash
# 方案1：定时截图 + OCR识别（Shell脚本示例）
# 每隔3秒执行一次
while true; do
  curl "http://localhost:8088/blikvm/screenshot" -o latest.png
  curl -X POST "http://localhost:8088/blikvm/ocr/recognize?lang=chi_sim,eng&left=0&top=0&width=1920&height=1080"
  sleep 3
done

# 方案2：使用Java定时任务（推荐）
# 在Spring Boot中使用 @Scheduled 注解，定时调用 takeScreenshot() 和 recognizeText()
# 详见 企微自动化完整方案.md
```

**说明：** 推荐使用Java定时任务来实现连续监控，可以在Service层编写逻辑。

### 场景3：企微群发消息

循环以下步骤：
1. OCR查找下一个联系人
2. 点击联系人
3. 输入消息
4. 发送
5. 返回列表

---

## 🔧 核心接口说明

### 1. 认证接口

#### 登录
```bash
curl -X POST http://localhost:8088/blikvm/login
```

### 2. OTG控制（必须启用）

#### 启用OTG
```bash
curl -X POST http://localhost:8088/blikvm/hid/enable
```

#### 禁用OTG
```bash
curl -X POST http://localhost:8088/blikvm/hid/disable
```

### 3. 截图接口

#### 获取截图
```bash
curl http://localhost:8088/blikvm/screenshot -o screenshot.png
```

### 4. OCR识别接口（核心）

#### 识别屏幕所有文字
```bash
curl http://localhost:8088/blikvm/ocr/recognize
```

#### 查找指定文字位置
```bash
curl "http://localhost:8088/blikvm/ocr/find?text=搜索"
```

**响应示例：**
```json
{
  "success": true,
  "text": "搜索",
  "x": 150,
  "y": 80,
  "message": "找到文字位置"
}
```

#### 识别指定区域文字
```bash
# 识别屏幕左上角(100,100)开始的500x200区域的英文文字
curl -X POST "http://localhost:8088/blikvm/ocr/recognize?lang=eng&left=100&top=100&width=500&height=200"

# 识别指定区域的中英文文字
curl -X POST "http://localhost:8088/blikvm/ocr/recognize?lang=chi_sim,eng&left=0&top=0&width=800&height=600"
```

**说明：** 需要解析返回的JSON，提取文字和坐标信息，然后调用鼠标点击接口。

### 5. 鼠标控制

#### 点击指定坐标
```bash
curl "http://localhost:8088/blikvm/mouse/click?x=500&y=300&button=left"
```

#### 发送完整鼠标事件（支持拖拽、滚轮）
```bash
curl -X POST http://localhost:8088/blikvm/mouse/event \
  -H "Content-Type: application/json" \
  -d '{
    "buttons": 1,
    "relativeX": 0.5,
    "relativeY": 0.5,
    "verticalWheelDelta": 0,
    "horizontalWheelDelta": 0,
    "isAbsoluteMode": true
  }'
```

### 6. 键盘控制

#### 输入文字
```bash
curl -X POST "http://localhost:8088/blikvm/keyboard/type?text=你好"
```

#### 按下单个按键
```bash
curl -X POST "http://localhost:8088/blikvm/keyboard/press?key=Enter"
```

常用按键：`Enter`, `Tab`, `Backspace`, `Escape`, `Delete`, `Space`

#### 按下组合键
```bash
# Ctrl+C（复制）
curl -X POST "http://localhost:8088/blikvm/keyboard/combo?keys=Ctrl,C"

# Ctrl+V（粘贴）
curl -X POST "http://localhost:8088/blikvm/keyboard/combo?keys=Ctrl,V"

# Ctrl+Alt+Delete
curl -X POST "http://localhost:8088/blikvm/keyboard/combo?keys=Ctrl,Alt,Delete"
```

### 7. 系统信息

#### 获取BlikVM设备信息
```bash
curl http://localhost:8088/blikvm/systeminfo
```

### 9. 电源控制（谨慎使用）

#### 短按电源键
```bash
curl -X POST http://localhost:8088/blikvm/atx/power
```

#### 强制关机
```bash
curl -X POST http://localhost:8088/blikvm/atx/forcepower
```

#### 重启
```bash
curl -X POST http://localhost:8088/blikvm/atx/reboot
```

---

## ⚙️ 配置

编辑 `src/main/resources/application.yml`：

```yaml
blikvm:
  host: 172.18.22.82              # BlikVM设备IP
  port: 443                        # 端口（HTTPS: 443）
  username: admin                  # 登录用户名
  password: admin                  # 登录密码
  ssl: true                        # 使用HTTPS
  access-token: ""                 # Token（自动获取）
  ignore-ssl-verification: true    # 开发环境忽略SSL验证
```

---

## 📖 核心概念详解

### 1. OTG（USB On-The-Go）

**作用：** 让BlikVM模拟成USB键盘+鼠标设备

**必须启用：** 在执行任何键鼠操作前，必须先启用OTG

```bash
curl -X POST http://localhost:8088/blikvm/hid/enable
```

### 2. OCR（光学字符识别）

**作用：** 识别屏幕中的文字，找到按钮位置

**技术：** BlikVM设备内置OCR引擎

**为什么需要：** 因为不能调用企微API，只能通过OCR识别界面元素位置

**调用方式：**
- 接口：`POST /api/ocr`
- 参数：`lang`（语言）, `rect`（识别区域）
- 无需额外依赖，直接调用设备接口

### 3. 视频流与截图OCR

**BlikVM设备：** 通过HDMI实时捕获目标电脑的屏幕（通常30fps视频流）

**我们的实现方式：** 
- **不是**持续捕获视频流（客户端无需处理视频）
- **而是**按需截图 + OCR识别
- 调用设备的 `/api/video/screenshot` 获取当前屏幕
- 调用设备的 `/api/ocr` 进行文字识别

**定时监控方案：**
- 使用Java定时任务（`@Scheduled`）
- 每隔3-5秒截图一次
- 对截图进行OCR识别
- 根据识别结果执行自动化操作

**用途：** 实时监控企微界面，检测新消息或状态变化

### 4. 为什么不直接调用企微API？

**限制：**
- 企微API需要企业认证
- API功能有限（只能发文本，不能发图片、文件等）
- 部分功能（如群发、添加好友）API不开放

**物理控制的优势：**
- ✅ 可以模拟任何人工操作
- ✅ 不受API限制
- ✅ 可以操作企微的所有功能
- ✅ 可以控制任何桌面应用（不限于企微）

---

## 📁 项目结构

```
BlikVM/
├── src/main/java/com/blikvm/
│   ├── BlikVMApplication.java              # 启动类
│   ├── config/BlikVMConfig.java            # 配置（设备IP、Token等）
│   ├── controller/BlikVMController.java    # REST接口
│   ├── service/
│   │   ├── BlikVMService.java              # 设备控制（截图、键鼠、OCR）
│   │   └── TokenRefreshService.java        # Token定时刷新
│   └── model/                               # 数据模型
├── screenshots/                             # 截图保存目录
├── 测试页面.html                            # 可视化测试页面
├── 企微自动化完整方案.md                     # 完整技术方案
└── README.md                                # 本文档
```

---

## 🛠️ 技术栈

- **Spring Boot** 3.1.5 - Web框架
- **RestTemplate** - HTTP客户端
- **FastJSON** - JSON解析
- **Lombok** - 简化代码
- **Spring Scheduling** - 定时任务
- **BlikVM OCR** - 设备内置OCR引擎

---

## ⚠️ 重要说明

### 键盘接口限制
- BlikVM设备API文档未提供键盘接口
- 代码尝试调用 `/api/keyboard/event`（实验性）
- 如果键盘功能不可用，请联系设备厂商

### Token管理
- Token有效期：12小时
- 自动刷新：每10小时自动刷新
- 首次使用需手动登录一次

### OCR识别准确度
- 依赖屏幕截图质量
- 依赖BlikVM设备的OCR引擎
- 建议在高分辨率屏幕上运行目标应用
- 支持英文（eng）和简体中文（chi_sim）

### 性能考虑
- 连续截图会占用网络带宽
- OCR识别会占用CPU资源
- 建议根据实际需求调整截图频率

---

## 📞 测试工具

### 1. 可视化测试页面
打开 `测试页面.html`，提供图形化界面测试所有功能

### 2. curl命令测试
参考本文档中的curl命令示例

### 3. 完整自动化方案
查看 `企微自动化完整方案.md` 了解详细技术实现

---

## 🎬 典型使用流程

### 企微自动化完整流程

```bash
# 第1步：登录并启用OTG
curl -X POST http://localhost:8088/blikvm/login
curl -X POST http://localhost:8088/blikvm/hid/enable

# 第2步：OCR识别搜索框位置，然后点击（假设识别到坐标为500,100）
curl "http://localhost:8088/blikvm/ocr/recognize-fullscreen?lang=chi,eng" > ocr_result.json
# （需解析JSON获取"搜索"按钮坐标）
curl "http://localhost:8088/blikvm/mouse/click?x=500&y=100"

# 第3步：输入联系人名字
curl -X POST "http://localhost:8088/blikvm/keyboard/type?text=张三"

# 第4步：等待1秒，按Enter打开聊天
sleep 1
curl -X POST "http://localhost:8088/blikvm/keyboard/press?key=Enter"

# 第5步：等待1秒，输入消息
sleep 1
curl -X POST "http://localhost:8088/blikvm/keyboard/type?text=你好，这是测试消息"

# 第6步：按Enter发送
curl -X POST "http://localhost:8088/blikvm/keyboard/press?key=Enter"

# 完成！消息已发送
```

---

## 📚 相关文档

- [企微自动化完整方案](企微自动化完整方案.md) - 详细技术方案
- [测试页面](测试页面.html) - 可视化测试工具
- [BlikVM API文档](enable otg .md) - 设备API文档

---

**项目版本：** 1.0.0  
**最后更新：** 2025-11-06  
**作者：** lvshou