视觉HID桥
视觉HID桥 是一种自主代理能力系统，旨在弥合硬化环境中的气隙。它允许AI代理在没有网络连接的情况下（通过HDMI捕获）在物理计算机上进行查看和操作（通过USB键盘模拟）。
该项目实现了 模型上下文协议（MCP） 将这些硬件功能暴露给LLM。
🚀 特性
- HDMI屏幕截图： 使用标准USB HDMI采集卡进行实时视觉反馈。
- 击键注射： 通过Raspberry Pi Zero（USB小工具模式）模拟标准USB键盘。
- OCR集成： 针对CLI环境（PowerShell、CMD）优化了文本提取。
- 类人打字： 实现抖动和可变延迟，以避免机器人检测。
- 视觉验证循环： 自动验证键入的文本是否出现在屏幕上，并具有重试逻辑。
- 布局自动检测： 启动时自动推断目标系统的键盘布局（US/DE）。
- 数据采集： 主动文件系统扫描工具和全面的OCR日志记录，用于审计跟踪。
- 标准化API： 使用MCP轻松插入Claude Desktop或其他代理运行时。
📦 项目结构
/
├── control_node/ # Logic running on the Laptop/Controller
│ ├── src/
│ │ ├── main.py # Entry point (not used in library mode)
│ │ ├── server.py # MCP Server Definition
│ │ ├── vision.py # OpenCV & OCR Pipeline
│ │ ├── hid.py # USB HID Injection Logic
│ │ ├── layout_detection.py # Auto-detect keyboard layout
│ │ └── data_harvester.py # OCR Logger and File Scanner
│ └── tests/ # Unit tests
├── interface_unit/ # Configuration for the Raspberry Pi Zero
│ ├── setup_gadget.sh # Script to enable USB HID Gadget
│ ├── verify_pi_setup.sh # Script to verify Pi configuration
│ └── usb_gadget.service # Systemd service for auto-start
└── demo_simulation.py # Script to demonstrate logic without hardware🛠️ 硬件设置
您需要：
- Raspberry Pi Zero W/2W： 充当“键盘”。
- USB HDMI采集卡： 充当“眼睛”。
- 目标PC： 你想要控制的电脑。
- 控制节点： 运行Python MCP服务器的笔记本电脑。
1.Raspberry Pi Zero设置（接口单元）
Pi Zero将来自控制节点的命令转换为USB按键。
- Flash Raspberry Pi操作系统精简版。
- 通过SSH连接到Pi。
- 复制
interface_unit/setup_gadget.sh和interface_unit/usb_gadget.service对于Pi。 - 运行安装程序：
sudo cp setup_gadget.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/setup_gadget.sh
sudo cp usb_gadget.service /etc/systemd/system/
sudo systemctl enable usb_gadget.service
sudo systemctl start usb_gadget.service- 验证设置：
使用提供的验证脚本确保一切正确：
chmod +x interface_unit/verify_pi_setup.sh
./interface_unit/verify_pi_setup.sh- 连接Pi USB数据端口 到目标PC。
2.控制节点设置
控制节点运行情报。
- 将HDMI采集卡连接到控制节点（USB）和目标PC（HDMI）。
- 将Pi Zero连接到控制节点（通过串行GPIO或单独的USB以太网适配器进行控制）。
- 安装依赖项：
pip install -r control_node/requirements.txt*注意：您需要 tesseract-ocr 安装在您的系统上（例如。， sudo apt install tesseract-ocr).*
💻 用法
运行MCP服务器
启动服务器，向LLM公开工具。
# From the root directory
python3 -m control_node.src.main注： 有关设置VLM Integration（Ollama）和配置的详细说明，请参阅 手册-mcp-md.
可用工具
capture_screen(mode="ocr_text")：返回屏幕上的文本。inject_keystrokes(text="echo hello", verify=True)：键入带有可选视觉验证的文本。execute_shortcut(modifiers=["CTRL", "ALT"], key="DELETE")：发送组合。scan_directory(path=".")：列出文件、解析输出并将JSON结构保存到的主动扫描工具logs/.
日志记录
- OCR日志： 默认情况下，所有识别的文本都会记录到
logs/ocr_stream_YYYY-MM-DD.log. - 扫描结果： JSON结构来自
scan_directory保存到logs/.
🧪 测试与模拟
您可以运行测试套件或模拟硬件的模拟脚本。
# Run Unit Tests
python3 -m unittest discover control_node/tests
# Run Simulation Demo
python3 demo_simulation.py🗺️ 功能路线图
第一阶段：基础（已完成）
- \[x\] 基本USB HID小工具设置
- \[x\] 通过OpenCV进行屏幕截图
- \[x\] 文本提取（OCR）
- \[x\] MCP服务器实现
第二阶段：稳健性和可靠性（已完成）
- \[x\] 视觉验证循环： 自动验证键入的命令是否出现在屏幕上。
- \[x\] 布局自动检测： 根据试打字推断键盘布局（美国/德国/英国）。
- \[x\] 数据采集： 将OCR输出结构化为JSON和日志流。
第三阶段：高级情报（计划中）
- \[ \] 隐形增强功能： 在每次启动时随机化USB供应商ID。
- \[ \] VLM集成： 使用局部视觉模型（Llama 3.2 Vision）来理解文本之外的GUI元素。
- \[ \] 恢复模式： “Kill Switch”硬件加密狗，用于在代理出现问题时物理断开USB连接。
⚠️ 安全警告
此工具在较低级别与硬件交互。负责任地使用。在连接到气隙系统之前，请确保您有授权。