内容
# WinCommander
> **手机大脑 → Windows 四肢**。把任意 Windows 设备变成远程可操控的 MCP 工具集。
> 手机 Termux 里的 Hermes 是唯一的 AI Agent，Windows 只管执行，无需 API Key。
## 架构
```
┌─────────────────────────────┐
│ 手机 (Termux + Hermes) │
│ 唯一 AI 大脑 │
│ │
│ "帮我在 Win 上打开浏览器 │
│ 搜索 Python 文档" │
│ │
│ Agent 调用工具: │
│ mcp_win_browser_navigate │
│ mcp_win_input_type │
│ mcp_win_cli_run │
└──────────┬──────────────────┘
│ LAN / Tailscale
▼
┌─────────────────────────────┐
│ Windows (WinCommander) │
│ 无脑执行器 │
│ │
│ ✅ CLI (CMD/PowerShell) │
│ ✅ GUI (UIA 桌面自动化) │
│ ✅ 浏览器 (Playwright) │
│ ✅ 键鼠 (pyautogui) │
│ ✅ USB 设备管理 │
│ ✅ 截图 / 剪贴板 │
│ ✅ 文件系统 │
│ ✅ 进程管理 │
│ │
│ 无需 API Key · 全离线 │
└─────────────────────────────┘
```
## 功能 (35+ 工具)
| 类别 | 工具 | 说明 |
|------|------|------|
| **CLI** | `cli_run` | 执行 CMD 命令 |
| | `cli_powershell` | 执行 PowerShell |
| **GUI** | `gui_snapshot` | 获取桌面 UI 元素树 |
| | `gui_click` | 点击元素 |
| | `gui_double_click` | 双击元素 |
| | `gui_type` | 向元素输入文本 |
| | `gui_press` | 发送按键 |
| | `gui_focus` | 聚焦元素 |
| | `gui_invoke` | 触发按钮 |
| | `gui_window_list` | 列出所有窗口 |
| | `gui_window_focus` | 前置窗口 |
| | `gui_window_close` | 关闭窗口 |
| **输入** | `input_click` | 鼠标点击坐标 |
| | `input_double_click` | 鼠标双击 |
| | `input_move` | 移动鼠标 |
| | `input_drag` | 拖拽 |
| | `input_type` | 键盘输入文本 |
| | `input_hotkey` | 组合键 (Ctrl+C, Win+R…) |
| | `input_scroll` | 滚轮 |
| **浏览器** | `browser_navigate` | 打开网页 |
| | `browser_click` | 点击元素 |
| | `browser_type` | 输入框填字 |
| | `browser_snapshot` | 获取页面文本 |
| | `browser_exec` | 执行 JS |
| | `browser_scroll` | 滚动页面 |
| | `browser_close` | 关闭浏览器 |
| **截图** | `screen_screenshot` | 全屏/区域截图 |
| | `screen_size` | 屏幕分辨率 |
| **USB** | `usb_list` | 列出 USB 设备 |
| | `usb_detailed` | USB 详细信息 |
| **系统** | `system_info` | 系统信息 |
| | `system_processes` | 进程列表 |
| | `system_kill` | 终止进程 |
| **文件** | `file_list` | 列目录 |
| | `file_read` | 读文件 |
| | `file_write` | 写文件 |
| | `file_delete` | 删文件 |
| | `file_exists` | 检查存在 |
| **剪贴板**| `clipboard_get` | 读剪贴板 |
| | `clipboard_set` | 写剪贴板 |
| **应用** | `app_start` | 启动应用 |
## 快速开始
### 1. Windows 端部署
```batch
git clone https://github.com/你的仓库/win-commander.git
cd win-commander
setup_win.bat
```
脚本自动完成：
- 检测 Python 3.10+
- 创建 venv 并安装所有依赖
- 下载 Playwright Chromium 浏览器 (~150MB)
- 生成启动批处理
### 2. 启动
```batch
启动_WinCommander.bat # 无白名单限制
启动_WinCommander_安全模式.bat # 限制用户目录
```
启动后终端显示：
```
╔══════════════════════════════════════════════════╗
║ WinCommander — Windows 远程控制 ║
╠══════════════════════════════════════════════════╣
║ 局域网 IP : 192.168.1.100 ║
║ 端口 : 9600 ║
║ MCP URL : http://192.168.1.100:9600/mcp ║
╠══════════════════════════════════════════════════╣
║ Termux 端配置: ║
║ hermes config set mcp_servers.win.url ║
║ "http://192.168.1.100:9600/mcp" ║
╚══════════════════════════════════════════════════╝
```
### 3. 手机 (Termux) 端配置
```bash
# 方法 A: 自动配置 (在 Linux/Termux 上)
bash setup_termux.sh
# 方法 B: 手动配置
hermes config set mcp_servers.win.url "http://192.168.1.100:9600/mcp"
# 重启 Hermes
hermes gateway restart
```
### 4. 开始使用
在手机 Hermes 中直接对话：
```
"看看 Windows 上有什么窗口"
"用 mcp_win_system_info 看看系统状态"
"在 Windows 上打开 Chrome 搜索 Python 文档"
"帮我在 Windows 桌面上建一个 test.txt 文件"
```
所有工具以 `mcp_win_` 为前缀。Hermes 会自动发现并调用。
## 安全
| 机制 | 说明 |
|------|------|
| **白名单** | `--whitelist` 限制文件访问目录 |
| **SSRF 防护** | 浏览器禁止访问 localhost/私有 IP/云元数据 |
| **Tailscale** | 跨网络使用时走 WireGuard 加密隧道 |
| **HMAC** | `--secret` 可选认证密钥 |
## 可选依赖
| 库 | 用途 | 缺失影响 |
|---|---|---|
| `uiautomation` | GUI 自动化 | gui_* 工具不可用 |
| `pyautogui` | 键鼠模拟 | input_* 工具不可用 |
| `playwright` | 浏览器 | browser_* 工具不可用 |
| `pyperclip` | 剪贴板 | clipboard_* 工具不可用 |
| `mss` + `Pillow` | 截图 | screen_* 回退到 pyautogui |
| `psutil` | 系统信息 | 内存/磁盘信息缺失 |
## 与 Hermes-Desktop / remote-device-mcp 的关系
WinCommander 吸收了这两个项目的精华：
- **Hermes-Desktop** 提供了 Windows GUI 自动化 (FlaUI.UIA3 → uiautomation) 和浏览器自动化 (Playwright) 的工具设计模式
- **hermes-remote-device-mcp** 提供了 MCP Server 远程控制的架构思路，但修复了其 HMAC 认证缺失、shell 注入等问题
区别：
| | Hermes-Desktop | remote-device-mcp | **WinCommander** |
|---|---|---|---|
| 平台 | Windows only | 跨平台 | **Windows only** |
| AI 位置 | 本地 agent runtime | 远程 Hermes | **远程 Hermes (手机)** |
| API Key | 需要 | 不需要 | **不需要** |
| GUI 自动化 | FlaUI.UIA3 (C#) | ❌ | **uiautomation (Python)** |
| 浏览器 | Playwright (已实现但未注册) | ❌ | **Playwright** |
| 键鼠 | 嵌入 UIA | ❌ | **独立 pyautogui 工具** |
| USB | ❌ | ❌ | **✅** |
| 安全性 | HMAC + 白名单 | HMAC 假实现 | **真 HMAC + SSRF + 白名单** |
## License
MIT
