# 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