# keywave

**Repository Path**: xhongc/keywave

## Basic Information

- **Project Name**: keywave
- **Description**: 自部署局域网远程控制器（Remote Controller）
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KeyWave

一个现代化的跨平台远程控制工具，让您能够通过手机或平板电脑的触摸屏无缝控制电脑的鼠标和键盘。

## 功能特性

### 精确鼠标控制
- **流畅触摸板体验**: 在移动设备上模拟笔记本电脑触摸板，支持精确的鼠标移动
- **多键点击支持**: 左键、右键、中键点击功能
- **实时响应**: 基于 WebSocket 的低延迟通信

### 完整键盘功能
- **MacBook 风格界面**: 精美的键盘布局，提供原生体验
- **功能键支持**: F1-F12、Escape、Tab、Shift、Control、Alt 等所有常用按键
- **组合键操作**: 支持 Ctrl+C、Cmd+V 等组合键功能
- **响应式设计**: 自适应不同屏幕尺寸的移动设备

### 技术特点
- **现代 Python 技术栈**: 基于 FastAPI 构建的高性能异步服务
- **跨平台兼容**: 支持 Windows、macOS、Linux 系统
- **零配置**: 开箱即用，无需复杂设置
- **轻量级部署**: 单文件运行，资源占用低

## 快速开始

### 环境要求

- Python 3.11 或更高版本
- [UV](https://github.com/astral-sh/uv) 包管理器（推荐）

### 安装步骤

1. **克隆项目**
   ```bash
   git clone https://github.com/xhongc/keywave.git
   cd keywave
   ```

2. **安装依赖**
   ```bash
   # 使用 UV（推荐）
   uv sync
   
   # 或使用 pip
   pip install fastapi uvicorn pynput
   ```

3. **启动服务**
   ```bash
   # 开发模式（自动重载）
   uv run uvicorn main:app --reload
   
   # 或直接运行
   uv run python main.py
   ```

4. **访问控制界面**
   
   在移动设备的浏览器中访问：`http://your-computer-ip:8000`

## 界面展示
## 使用方法
![KeyWave](keywave.png)

### 基本操作

1. **鼠标控制**
   - 在触摸板区域滑动手指来移动鼠标光标
   - 点击左键/右键/中键按钮进行鼠标点击

2. **键盘输入**
   - 使用屏幕键盘进行文字输入
   - 支持所有常用功能键和组合键操作

3. **连接状态**
   - 界面顶部显示实时连接状态
   - 连接断开时会自动尝试重连

### 网络配置

确保您的移动设备和电脑连接在同一个局域网内，并获取电脑的 IP 地址：

```bash
# Windows
ipconfig

# macOS/Linux  
ifconfig
```

## 权限设置

### macOS
首次使用时，系统会要求授予辅助功能权限：
1. 打开"系统偏好设置" → "安全性与隐私" → "隐私"
2. 选择"辅助功能"
3. 添加并允许 Python 或终端应用

### Windows
某些防病毒软件可能会阻止鼠标/键盘控制，请将程序添加到白名单。

### Linux
确保用户具有输入设备的访问权限，可能需要将用户添加到 `input` 组。

## 开发相关

### 项目结构

```
keywave/
├── main.py          # 主应用程序（后端 + API）
├── index.html       # 前端界面
├── pyproject.toml   # 项目配置
├── uv.lock         # 依赖锁定文件
└── README.md       # 项目说明
```

### 技术架构

- **后端**: FastAPI + Uvicorn + PyNput
- **前端**: 原生 HTML/CSS/JavaScript
- **通信**: WebSocket 实时双向通信
- **部署**: 单体应用，支持容器化

### 消息协议

WebSocket 消息格式：

```javascript
// 鼠标移动
{"type": "move", "dx": number, "dy": number}

// 鼠标点击  
{"type": "click", "button": "left"|"right"|"middle"}

// 按键按下
{"type": "keydown", "key": string}

// 按键释放
{"type": "keyup", "key": string}
```

### 本地开发

```bash
# 安装开发依赖
uv sync --dev

# 运行开发服务器
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 代码格式化
uv run black main.py

# 类型检查
uv run mypy main.py
```

## 贡献指南

我们欢迎所有形式的贡献！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 致谢

- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架
- [PyNput](https://pynput.readthedocs.io/) - 跨平台输入控制库
- [UV](https://github.com/astral-sh/uv) - 超快速 Python 包管理器

## 支持

如果您遇到问题或有建议，请：

- 查看 [Issues](https://github.com/xhongc/keywave/issues) 页面
- 创建新的 Issue 报告问题
- 参与 [Discussions](https://github.com/xhongc/keywave/discussions) 讨论

---

**如果这个项目对您有帮助，请给我们一个 Star！**