tiance-gui
by LikeMirage
README.md
# Tiance GUI MCP · 天策 GUI MCP
**递归网格定位，让 AI 从整屏逐层看清目标，再用格内比例坐标操作 Windows。**
[English](README.en.md) · [操作指南](docs/usage.md) · [架构与边界](docs/architecture.md) · [反馈问题](https://github.com/LikeMirage/Tiance-GUI-MCP/issues)
[](#环境)
[](#接入-mcp-客户端)
[](#安装)
[](LICENSE)
[](https://github.com/LikeMirage/Tiance-GUI-MCP/actions/workflows/tests.yml)
## 核心特点
传统截图操作经常要求模型估算目标的绝对像素坐标。这套工具把定位过程变成可逐层确认的步骤：
1. 获取窗口或屏幕截图，叠加编号网格。
2. 选择一个格子，或组成完整矩形的多个格子，放大该区域。
3. 放大视图重新划分网格，可以继续选格、继续放大。
4. 使用当前视图的格号与格内 `x/y` 比例定位；程序负责映射回真实屏幕像素。
例如：整屏 → 第 4 格 → 放大视图第 2 格 → `x=0.5037, y=0.62`。无需手算每层裁剪偏移、缩放倍率或绝对坐标。
**坐标规则很重要：** 格号从左上角开始按行排列；格内比例原点在**左下角**，`x` 向右增加、`y` 向上增加，范围均为 `0～1`。支持任意小数，最终才取整到物理屏幕像素。放大只帮助观察，不生成新的图像细节，也不会突破原始像素精度。
此外支持：
- Windows UIAutomation 控件读取、分页、身份/焦点校验与可写控件赋值。
- 鼠标点击、拖动、移动、滚动；键盘文字、按键和组合键。
- 可选落点预览；直接点击不要求先预览。
- `gui_batch` 顺序执行连续动作，失败即停止并报告已经完成的步骤。
- 输入锁、柔和边框提示、Esc 退出、空闲释放、进程退出释放。
- 标准 MCP 图片结果，不依赖天策客户端读取本地图片。
这是从 [天策](https://github.com/LikeMirage/Tiance) GUI 工具提取的独立项目。**不需要天策、模型密钥、供应商配置或会话数据库。** 当前是首个独立版本，支持 Windows 本地 stdio；不提供远程桌面服务。
## 环境
- Windows 10/11，交互式用户桌面；推荐 64 位 Python 3.11 或更新版本。
- Windows PowerShell 5.1（用于系统 UIAutomation 桥）。
- 支持本地 stdio MCP 和图片结果的客户端。
- 默认只为 GUI 辅助进程请求管理员权限，AI 客户端本身不必提权。UAC 弹窗需要人确认。
Windows 服务的 Session 0、锁屏、UAC 安全桌面和断开后的远程桌面不属于支持的操作环境。即使管理员身份，也不能控制所有受保护界面。Electron、游戏和自绘控件不保证提供完整控件树，可使用截图网格路径。
## 安装
在准备保存项目的位置打开 PowerShell：
```powershell
git clone https://github.com/LikeMirage/Tiance-GUI-MCP.git
cd Tiance-GUI-MCP
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
```
也可使用已安装的 Python 3.11/3.12/更新版本创建虚拟环境。此仓库尚未发布到 PyPI；请从源码安装，不要假设同名 PyPI 包属于本项目。
## 接入 MCP 客户端
在客户端的 MCP 配置中添加以下内容，把示例路径换成实际项目位置：
```json
{
"mcpServers": {
"tiance-gui": {
"command": "C:\\path\\to\\Tiance-GUI-MCP\\.venv\\Scripts\\python.exe",
"args": ["-m", "tiance_gui_mcp"]
}
}
}
```
不同客户端配置文件位置不同；支持表单配置时，分别填写上述 `command` 和 `args`。服务只向标准输出写 MCP 协议，诊断走标准错误。
首次使用 `gui_runtime start` 时，如果服务不是管理员，默认通过 Windows UAC 启动管理员 GUI 辅助进程；取消授权则返回失败，不静默降级。空闲释放后再次 start 可能再次请求授权。
可选启动参数：
| 参数 | 默认值与含义 |
|---|---|
| `--data-dir PATH` | `%LOCALAPPDATA%\Tiance-GUI-MCP`；截图和运行状态的位置 |
| `--screenshot-retention keep\|session` | `keep` 保留截图；`session` 在关闭 GUI 会话或运行器退出时删除对应截图目录 |
| `--elevation auto\|require\|never` | `auto` 按需为辅助进程提权；`require` 要求服务已经是管理员；`never` 仅使用当前权限 |
| `--version` | 显示版本号 |
例如把数据保存在便携目录：
```json
"args": ["-m", "tiance_gui_mcp", "--data-dir", "D:\\Tiance-GUI-MCP\\data"]
```
## 五个工具
| 工具 | 用途 |
|---|---|
| `gui_runtime` | `start` / `status` / `stop` 管理输入锁 |
| `gui_inspect` | 列窗口、创建截图会话、递归放大、刷新、等待、读控件、激活原目标窗口 |
| `gui_mouse` | 比例坐标或控件定位、直接操作、可选预览 |
| `gui_keyboard` | 基于最新截图/焦点输入文字、按键、组合键、UIA 赋值 |
| `gui_batch` | 一次提交 1～50 个**按顺序**执行的动作 |
基本顺序：`gui_runtime start` → 等待成功 → `gui_inspect start` → 观察/操作 → `gui_runtime stop`。
`list_windows` 也要求先锁定。跨工具的并行调用不代表先后依赖；需要连续操作时使用批量工具。
## 数据与生命周期
```text
Tiance-GUI-MCP/
├─ screenshots/
│ └─ gui_<id>/
│ ├─ session.json
│ ├─ frame_000/
│ └─ previews/
└─ runtime/
└─ mcp_<id>.json
```
截图默认保留，包含模型看到的屏幕、网格、预览和坐标记录。没有隐藏的保留天数、自动数量截断或自动上传；可在运行器停止后手动清理，或明确选用 `session` 策略。被连接的 AI 客户端如何把图片发送给模型，由客户端控制。
运行状态不是正式会话数据库；里面含本机辅助进程连接凭据，正常停止时删除，不能提交到仓库或发到 Issue。源码目录的 `data/` 已加入 Git 忽略。
同一个交互式 Windows 会话内，各实例共用系统互斥锁，即使配置不同数据目录也不能同时控制桌面。连接之间不共享截图操作引用。**MCP 连接不等于某一条 AI 对话**；如果宿主把一个连接共享给多个聊天，本服务无法识别宿主未提供的聊天身份，应由宿主隔离连接。
默认空闲 120 秒释放，可在 `gui_runtime start` 中设置 `idle_timeout_seconds`。正在执行的动作不算空闲，`status` 不续期。Esc、显式 stop、活动调用被取消、stdio 关闭或 MCP 进程退出都会进入释放流程；强制结束进程仍由辅助进程的父进程监测和空闲超时处理。**聊天回复结束本身不是标准 MCP 退出事件**，模型必须显式 stop。
## 开发与验证
```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build
```
常规测试不操作用户应用。真实桌面测试单独启用，只创建并操作测试自身窗口，但会短暂锁定输入：
```powershell
$env:TIANCE_GUI_MCP_DESKTOP_TEST = "1"
.\.venv\Scripts\python.exe -m pytest tests/test_desktop.py
```
取消测试、UAC、任务栏、不同 DPI 与多显示器的实测情况见 [验证记录](docs/validation.md)。不要把模拟测试通过当作对所有 Windows 应用的兼容承诺。
## 贡献与许可
欢迎带复现步骤反馈网格、坐标、控件识别和生命周期问题。请先阅读 [贡献指南](CONTRIBUTING.md) 与 [安全边界](SECURITY.md)，不要上传含私人内容的截图或运行状态文件。
Apache-2.0，来源与修改说明见 [NOTICE](NOTICE)。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues