内容
# Trope CUA
用于Windows和macOS的后台计算机使用代理。
Trope CUA允许AI代理检查和操作真正的桌面应用程序，同时避免意外移动真正的鼠标光标或更改活动应用程序，当操作系统和目标应用程序支持安全路由时。它通过MCP、守护进程或直接CLI调用提供截图、辅助功能树、操作回执和轨迹记录。
Windows实现位于存储库根目录。macOS Swift实现位于[`native/macos/trope-cua`](native/macos/trope-cua)。
## 演示
<p align="center">
<a href="https://x.com/mattchowx/status/2049134343801450559">
<img src="assets/trope-cua-demo.gif" alt="Trope CUA演示：代理在后台操作桌面应用程序">
</a>
</p>
<p align="center">
点击演示以观看完整视频（跳转到X）。
</p>
## 从源代码安装
Trope CUA以源代码形式分发。克隆存储库或从[发布页面](https://github.com/voctory/trope-cua/releases)下载GitHub生成的源代码存档，然后在本地运行安装脚本。
Windows要求：
- Windows 10 1903+ 或 Windows 11。
- PowerShell。
- 与[`global.json`](global.json)匹配的.NET SDK。
安装自包含的Windows构建：
```powershell
.\scripts\install-windows.ps1 -SelfContained
```
macOS要求：
- macOS 14 或更新版本。
- Xcode命令行工具。
- 为`TropeCUA.app`启用辅助功能和屏幕录制权限。
安装本地macOS构建：
```bash
./scripts/install-macos.sh
```
在任一平台上验证已安装的命令：
```bash
trope-cua --help
trope-cua check_permissions
trope-cua list_windows
```
与MCP客户端注册：
```powershell
trope-cua mcp-config
trope-cua mcp-config --client cursor
```
或将任何MCP客户端指向：
```text
trope-cua mcp
```
## 安全合约
变更操作返回回执。只有当所有三个字段都指示时，才将操作视为后台安全：
```json
{
"background_safe": true,
"cursor_moved": false,
"foreground_changed": false
}
```
`ok=true`表示请求的路由已完成。它本身并不意味着路由保留了用户的 foreground 工作。不安全的路由和备用方案在回执中报告，而不是被隐藏。
## 功能
- 列出桌面窗口和应用程序。
- 将特定目标窗口快照为像素、辅助功能树或两者。
- 通过后台安全路由点击、输入、按键、滚动和设置值（当目标公开它们时）。
- 作为MCP_stdio服务器、长时间运行的守护进程或直接CLI工具调用运行。
- 显示视觉代理光标叠加层，而不移动用户的硬件光标。
- 记录和重放轨迹以进行调试和回归测试。
- 拒绝已知的父会话不安全路由，而不是假装传递成功。
## 已知限制
- Trope CUA不是虚拟机或沙盒。同一会话的工具在真正的用户桌面上操作。
- 并非每个应用程序都公开安全的UIA/MSAA路由。
- Chromium和Electron并行工作需要单独的配置文件和CDP端口才能实现真正的隔离。
- 游戏、DirectX、Unity、Unreal、原始输入曲面和许多 canvas-heavy 应用程序需要子会话或AppBroadcast样式隔离。
- Trope CUA以源代码形式分发；从存储库或GitHub源代码存档安装。
在赋予代理对已认证应用程序的权限之前，请阅读完整的[已知限制](docs/limits.md)。
## 首次循环
对于作用于快照中的`element_index`值的 工作流，请使用MCP或守护进程。 使用守护进程时，在一个终端中保持`serve`运行，并在另一个终端中调用工具：
```powershell
trope-cua serve --instance demo
```
```powershell
trope-cua call --instance demo list_windows '{}'
trope-cua call --instance demo get_window_state '{"pid":1234,"window_id":456789}'
trope-cua call --instance demo click '{"pid":1234,"window_id":456789,"element_index":14}'
```
有关完整的工作流程，请参阅[快速入门](docs/quickstart.md)。
## 文档
- [安装](docs/installation.md)
- [快速入门](docs/quickstart.md)
- [工作流程](docs/workflows.md)
- [工具和命令模式](docs/reference-tools.md)
- [安全](SAFETY.md)
- [隐私](PRIVACY.md)
- [威胁模型](docs/threat-model.md)
- [已知限制](docs/limits.md)
## 开发
Windows：
```powershell
dotnet build trope-cua.sln
.\scripts\build.ps1
dotnet format --verify-no-changes --no-restore --verbosity minimal
.\scripts\run-tests.ps1
```
macOS：
```bash
cd native/macos/trope-cua
swift build
./scripts/test.sh
./scripts/install-local.sh
```
macOS开发和权限检查必须在macOS上运行。Windows集成测试必须在Windows上运行。
## 许可证
Trope CUA在MIT许可证下发布。参见[LICENSE](LICENSE)和[NOTICE](NOTICE)。
## 商标
Apple、macOS、Microsoft、Windows、OpenAI、Anthropic、Claude、Cua等引用的名称是其各自所有者的商标或注册商标。本项目与这些公司或项目无关，也未得到他们的认可。
