# win-web-control

**Repository Path**: lp9906/win-web-control

## Basic Information

- **Project Name**: win-web-control
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Windows Web 遥控器

Windows Web 遥控器是一款通过 Web 浏览器远程控制 Windows 系统的应用。它允许您使用手机或平板通过 Web 界面控制鼠标、键盘、音量和媒体播放，无需安装任何客户端软件。

## 功能特点

- **鼠标控制**：单指移动、单指单击左键、双指单击右键、双指滑动拖拽（按住左键移动）
- **平滑移动**：鼠标移动经过平滑插值处理，操作更跟手
- **触摸滚轮**：左侧垂直滚轮，底部水平滚轮
- **键盘支持**：完整虚拟键盘（Esc/F1-F12/方向键/编辑键等），支持 Ctrl/Shift/Alt 功能键长按保持
- **十字键**：右下角方向按键，支持长按连续移动，中间按钮映射鼠标左键
- **媒体控制**：播放/暂停快捷键
- **音量控制**：滑动调节系统音量

## 支持平台

- **服务端**：仅支持 Windows 系统（需要 Node.js 环境）
- **客户端**：支持任何现代浏览器（手机、平板、电脑）

## 环境要求

- Node.js 20.19+ 或 22.12+（由 Vite 8 要求决定）
- Windows 7/8/10/11 系统

## 安装与运行

### 1. 安装服务端依赖

在项目根目录执行：

```bash
npm install
```

### 2. 构建客户端

```bash
cd src/client
npm install
npm run build
```

构建产物输出到 `src/public`，由服务端直接托管。

### 3. 启动服务

返回根目录启动：

```bash
cd ../..
npm run dev
```

服务启动后默认运行在 `http://localhost:8080`，并在控制台打印本机访问地址和局域网手机访问地址。

## 开发模式

客户端支持 Vite 开发服务器（热更新），代理指向本地服务端：

```bash
# 终端 1：先启动服务端（根目录）
npm run dev

# 终端 2：启动客户端开发服务器（src/client 目录）
npm run dev
```

## 使用方法

### 获取本机 IP

服务启动后会自动显示您的局域网 IP 地址，使用手机或平板访问 `http://<您的IP>:8080` 即可（需与电脑处于同一局域网）。

### 操作指南

| 操作区域 | 操作方式 | 功能说明 |
|---------|---------|---------|
| 顶部左侧栏 | 单击 | 显示/隐藏键盘 |
| 顶部右侧栏 | 单击 | 播放/暂停 |
| 顶部右侧栏 | 滑动 | 控制音量 |
| 左侧窄栏 | 滑动 | 垂直滚轮 |
| 底部左侧栏 | 滑动 | 水平滚轮 |
| 主区域 | 单指滑动 | 鼠标移动 |
| 主区域 | 单指单击 | 鼠标左键 |
| 主区域 | 双指单击 | 鼠标右键 |
| 主区域 | 双指滑动 | 鼠标拖拽（按住左键移动） |
| 右下角十字键 | 长按 | 方向键（↑ ↓ ← →）连续输入 |
| 右下角十字键 | 单击中间 | 鼠标左键 |

### 键盘操作

- **普通按键**：按下/松开触发对应键盘输入
- **功能键短按**：按下后立即松开，触发一次按键
- **功能键长按**：按下后保持，触发按键按下；松开后触发按键抬起（Ctrl/Shift/Alt 等）

## 通信协议

客户端与服务端通过 WebSocket 进行通信，使用自定义二进制协议：

- 首字节编码 `type * 5 + subType`，其中 subType 表示整数参数的长度档位（1 字节 / 2 字节 / 4 字节等）
- 支持消息类型：鼠标移动、左/右键点击、垂直/水平滚轮、播放/暂停、音量增减与音量调节、键盘按下/抬起

## 项目结构

```
├── src/
│   ├── index.ts           # 服务端入口（Express 静态托管 + WebSocket 服务）
│   ├── types/             # 类型定义
│   ├── utils/             # 服务端工具与 Windows API 封装
│   │   ├── win-api.ts             # koffi FFI 调用 user32.dll SendInput
│   │   ├── win-mouse-api.ts       # 鼠标 API
│   │   ├── win-mouse-move-api.ts  # 鼠标移动封装
│   │   ├── win-keyboard-api.ts    # 键盘 / 媒体键 / 音量 API
│   │   ├── smooth-move.ts         # 鼠标平滑移动
│   │   ├── message-handle.ts      # WebSocket 消息解析与分发
│   │   └── buffer-view.ts         # 二进制缓冲读取
│   ├── public/            # 客户端构建产物（由服务端托管）
│   └── client/            # 前端 Web 应用（Vite + TypeScript）
│       ├── src/
│       │   ├── api/       # API 通信模块（WebSocket 封装）
│       │   ├── control/   # 触摸控制逻辑
│       │   ├── triggers/  # 触摸触发器（含 common/ 公共触发器）
│       │   ├── views/     # 键盘、十字键渲染
│       │   ├── styles/    # 样式文件
│       │   ├── types/     # 类型定义
│       │   └── utils/     # 工具函数
│       └── public/        # 客户端静态资源
├── package.json
└── tsconfig.json
```

## 技术栈

- **前端**：TypeScript + Vite 8
- **后端**：Node.js + Express 5 + WebSocket (ws)
- **系统调用**：koffi (FFI) 调用 user32.dll `SendInput`


## AI 协作

本项目在开发过程中由 AI 辅助编码完成：

- **模型**：DeepSeek v4 Flash（`deepseek-v4-flash`）
- **开发框架**：DeepSeek Harness（`deepseek-harness`）

## 许可证

GNU Affero General Public License v3.0 (AGPL-3.0)