跳到主要内容

# 简介

XXTLanControl 是一个局域网中控平台，用来批量管理和控制 XXTouch 设备。它主要包含以下几个部分：

- 后端服务：提供 HTTP API，负责设备通信、文件管理、数据存储等核心逻辑
- Web 前端：基于浏览器的管理界面，涵盖设备列表、脚本管理、远程控制、文件管理、KVDB、TableDB、取色工作台等功能
- 托盘程序（可选）：Windows / macOS 下的系统托盘，方便快速启停后端和打开浏览器
- Lua 模块 `XXTLanControl.lua`：运行在设备端的脚本库，提供连接中控、日志上报、KVDB、TableDB、文件操作等接口

## 发行包结构​

不同系统的发行包名称不完全一样，常见内容如下：

### Windows​

路径 / 文件 | 说明
--- | ---
`XXTLanControl-tray-windows-amd64.exe` | 托盘启动器，双击后会拉起后端并常驻托盘。
`bin/XXTLanControl-backend-windows-amd64.exe` | 中控后端服务。
`bin/xxtlancontrol-mcpserver.exe` | MCP 服务程序。
`dist/` | Web 控制台静态资源。
`start-backend.cmd` | 命令行模式启动脚本，适合排查问题时使用。
`XXTLanControl.lua` | 设备端调用中控能力时使用的 Lua 模块。

### macOS​

路径 / 文件 | 说明
--- | ---
`XXTLanControl.app` | 主应用包，双击即可启动托盘和后端。
`XXTLanControl.app/Contents/MacOS/xxtlancontrol-mcpserver` | MCP 服务程序。
`XXTLanControl.app/Contents/Resources/dist/` | Web 控制台静态资源。
`start-backend.command` | 终端模式启动脚本，适合排查问题时使用。
`XXTLanControl.lua` | 设备端调用中控能力时使用的 Lua 模块。

### Linux​

路径 / 文件 | 说明
--- | ---
`XXTLanControl-backend-linux-amd64` / `XXTLanControl-backend-linux-arm64` | 按架构提供的后端二进制。
`xxtlancontrol-mcpserver` | MCP 启动脚本，会自动选择对应架构的 MCP 二进制。
`xxtlancontrol-mcpserver-linux-amd64` / `xxtlancontrol-mcpserver-linux-arm64` | 按架构提供的 MCP 二进制。
`dist/` | Web 控制台静态资源。
`start-backend.sh` | 命令行模式启动脚本。
`XXTLanControl.lua` | 设备端调用中控能力时使用的 Lua 模块。

## 主要能力​

- 设备管理：扫描并导入局域网内的 XXTouch 设备，支持按分组统一管理
- 脚本运行：把脚本上传到设备端，随时启动、停止或暂停
- 远程控制：实时查看设备屏幕，支持触控和按键操作，也可以同时远控多台设备
- 文件管理：管理中控端的脚本、资源、报告等文件，支持上传下载和在线编辑
- 数据管理：内置 KVDB（队列 + 词典）和 TableDB（结构化表格），方便脚本间共享状态或存储业务数据
- 计划任务：支持定时、间隔、一次性、用户触发、KVDB 队列消费等多种触发方式，提供步骤编排和可视化工作流
- 取色工作台：截图取色、选区裁切、点阵字库、脚本界面编辑等脚本开发辅助工具
- 批量操作：批量授权、批量安装新版 XXTouch、批量重命名、批量截屏、批量锁屏/解锁等

## 使用前提​

- 设备端需要安装 XXTouch 并开启 `远程访问`
- 设备和中控需要在同一局域网内，并且中控防火墙已放行 HTTP 端口（默认 `46990`）

## 首次启动​

- Windows：双击 `XXTLanControl-tray-windows-amd64.exe`，通常会自动打开浏览器进入控制台
- macOS：打开 `XXTLanControl.app`，通常会自动打开浏览器进入控制台
- Linux：运行 `start-backend.sh`，然后手动访问 `http://127.0.0.1:46990/`

更多用法请参阅后续章节。