Touchpoint

Touchpoint

让 AI Agent 能够观察并操作任何桌面。

pip install touchpoint-py

AI Agent 在 Chrome 中调研数据，然后创建格式化的 Excel 表格——约 12 分钟内完成整个任务

Touchpoint 是一个跨平台 Python 库，通过原生辅助功能 API 读取桌面 UI 并与之交互。只需一次导入、一个 API，即可在 Linux、macOS 和 Windows 上使用，并通过 CDP（Chrome DevTools Protocol）内置支持 Chromium 和 Electron 应用。

Touchpoint 不会截取像素或运行视觉模型，而是读取真实的辅助功能树——屏幕上每个元素的结构化名称、角色、状态和位置。运行快速、可靠，无需视觉模型。它附带 MCP 服务，让 Claude、Cursor 等 LLM Agent 或任何本地模型开箱即用地控制任意桌面应用。

import touchpoint as tp

elements = tp.find("Send", role=tp.Role.BUTTON, app="Slack")
tp.click(elements[0])

为什么选择 Touchpoint？

目录

• 目录
• 安装
  • 平台要求
• 快速入门
  • 元素 ID
  • 输出格式
• MCP 服务
  • 工具
  • 客户端设置
  • 环境变量
• 浏览器和 Electron 应用（CDP）
  • 设置
• API 参考
  • 发现
  • 搜索和等待
  • 操作
  • 输入
  • 截图和配置
• 架构
• 配置
• 开发
• 状态
  • 已知限制
• 许可证

安装

需要 Python 3.10+。

pip install touchpoint-py

所有功能均已包含：平台原生后端、浏览器和 Electron 应用的 CDP 支持、MCP 服务以及截图功能。平台专属依赖项会通过 pip 环境标记自动安装。

平台要求

快速开始

import touchpoint as tp

# Discover
apps = tp.apps()                            # ["Firefox", "Slack", "Terminal", ...]
windows = tp.windows()                      # Window objects with title, position, size
all_els = tp.elements(app="Firefox", named_only=True)  # only elements with text labels

# Find
results = tp.find("Search", role=tp.Role.TEXT_FIELD, app="Firefox")

# Act
tp.set_value(results[0], "touchpoint python", replace=True)
tp.press_key("enter")
tp.hotkey("ctrl", "s")                      # keyboard shortcuts

# Wait for UI changes
tp.wait_for("results", app="Firefox", timeout=10)

# Screenshot
img = tp.screenshot()                       # full desktop → PIL.Image
img = tp.screenshot(app="Firefox")           # cropped to app window

元素 ID

每个元素都有唯一 ID，例如 atspi:1234:1:2.0 或 cdp:9222:TID:4。操作函数接受 Element 对象或纯 ID 字符串，方便在多个步骤之间存储引用：

results = tp.find("Send", max_results=1)
element_id = results[0].id                  # "atspi:1234:1:5.2"

# later...
tp.click(element_id)                        # works with just the string

输出格式

控制结果的返回方式：

tp.elements(app="Slack", format="flat")     # one compact line per element (best for LLMs)
tp.elements(app="Slack", format="tree")     # indented parent/child hierarchy
tp.elements(app="Slack", format="json")     # full JSON with all fields

MCP 服务

Touchpoint 提供了一个 MCP（Model Context Protocol） 服务，可供任何兼容 MCP 的客户端使用。借助它，Claude、Cursor、本地模型等大模型 Agent，或任何支持 MCP 的工具都能控制你的桌面。

两种模式 — 视觉与无视觉

设置 TOUCHPOINT_MODE=no-vision（默认值：vision）即可切换模式：

• 视觉模式 — Agent 使用 screenshot() 查看屏幕，并通过元素 ID 或坐标进行交互。最适合视觉能力强的前沿模型。
• 无视觉模式 — Agent 使用 snapshot() 获取活动窗口的精简结构化文本树，然后直接通过元素 ID 执行操作。适用于任何模型，包括不具备视觉能力的本地模型。大多数操作工具都会附加自动验证标记（(new window: ...)、(focus moved)、(no change detected)），以便 Agent 无需截图即可检测状态变化。

工具

MCP 服务内置了指导 Agent 在各种模式下正确执行工作流的说明，包括 定位 → 操作 → 验证 循环、何时使用 read_text 而非 find，以及如何从错误中恢复。

         ┌──────────┐
    ┌───▶│  ORIENT  │  screenshot · apps · windows
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  LOCATE  │  find · snapshot · get_element
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │   ACT    │  click · set_value · type_text · press_key
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  VERIFY  │───▶ Done ✅
    │    └────┬─────┘
    │         │ not yet
    └─────────┘

客户端设置

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "servers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

claude mcp add touchpoint -- touchpoint-mcp

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

浏览器与 Electron 应用（CDP）

对于 Electron 和 Chromium 应用（Slack、Discord、VS Code 等），原生辅助功能 API 返回的数据有限。Touchpoint 的 CDP 后端通过 Chrome DevTools Protocol 连接，以获取完整的网页内容。

默认启用自动发现 — Touchpoint 会自动查找通过调试端口启动的运行中浏览器和 Electron 应用。除了使用标志启动应用外，无需手动配置。

设置

1. 使用调试端口启动应用：

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# macOS
open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# Windows
start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\tp-chrome

2. 配置 Touchpoint：

import touchpoint as tp

tp.configure(cdp_discover=True)             # auto-discover from running processes
# or
tp.configure(cdp_ports={"Google Chrome": 9222})  # explicit mapping

3. 使用 source 参数控制获取的内容：

tp.elements(app="Google Chrome", source="full")     # native chrome + web content (default)
tp.elements(app="Google Chrome", source="cdp_ax")   # web content only (CDP accessibility tree)
tp.elements(app="Google Chrome", source="native")   # native UI only (toolbar, tabs, menus)
tp.elements(app="Google Chrome", source="dom")      # DOM walker (catches what AX misses)

CDP 结果会与原生后端结果合并 — 在一次 elements() 调用中，你可以同时获得 AT-SPI2/UIA/AX 提供的工具栏和窗口控件，以及 CDP 提供的完整网页内容。

source="ax" 仍作为兼容性别名接受，对应 source="cdp_ax"。新代码中请优先使用 cdp_ax，以免与原生 macOS AX 后端混淆。

API 参考

发现

搜索与等待

操作

输入

屏幕截图与配置

所有操作函数都接受 Element 对象或字符串 ID。elements()、find() 和 get_element() 支持 format="flat"、format="json" 或 format="tree"（仅适用于元素），以返回预先格式化的字符串而非对象。窗口管理已通过 Linux AT-SPI2、Windows UIA 和 macOS AX 后端实现。

架构

┌───────────────────────────────────────────────────────┐
│               import touchpoint as tp                 │
│  tp.find() · tp.click() · tp.screenshot() · ...       │
│                    (Public API)                       │
├─────────────────────────┬─────────────────────────────┤
│     Backend (ABC)       │    InputProvider (ABC)      │
├─────────────────────────┼─────────────────────────────┤
│  AT-SPI2     (Linux)    │  Xdotool       (X11)        │
│  UIA         (Windows)  │  SendInput     (Win32)      │
│  AX          (macOS)    │  CGEvent       (macOS)      │
│  CDP         (browsers) │                             │
├─────────────────────────┴─────────────────────────────┤
│  Utilities: formatter · matcher · screenshot · scale  │
└───────────────────────────────────────────────────────┘

双层设计：

• Backend 读取无障碍树并执行结构化操作（单击、set_value、focus）。感知元素，可靠性高。
• InputProvider 模拟原始键盘和鼠标输入。基于坐标，无法感知元素。当无法使用原生无障碍操作时，会自动回退使用。

CDP 与平台后端并行运行。两者的结果会合并：来自 AT-SPI2/UIA/AX 的原生窗口界面（工具栏、标签页、菜单），加上来自 CDP 的完整网页内容，统一到一个 API 中。

如需了解详细的内部实现，请参阅 ARCHITECTURE.md。

配置

tp.configure(
    fuzzy_threshold=0.6,          # minimum match score for find() (0.0–1.0)
    fallback_input=True,          # use InputProvider when native actions fail
    type_chunk_size=40,           # split long text into chunks for typing (0 = disable)
    max_elements=5000,            # max elements per query
    max_depth=20,                 # default tree depth limit
    scale_factor=None,            # display scale override (None = auto-detect)
    cdp_ports={"Chrome": 9222},   # explicit CDP port mapping
    cdp_discover=True,            # auto-discover CDP ports from running processes
    cdp_refresh_interval=5.0,     # seconds between CDP target scans
    ax_messaging_timeout=1.0,     # max seconds to wait for a macOS AX app reply
)

tp.diagnostics() 返回便于转换为 JSON 的健康状况报告。报告包含 当前使用的后端、输入提供程序、CDP 目标、可选的平台工具、已配置的 超时时间，以及最近因 AX 消息超时而跳过的 macOS 应用。

开发

git clone https://github.com/Touchpoint-Labs/touchpoint.git
cd touchpoint
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

状态

Alpha — 已在所有三个平台上实现完整功能并通过测试。根据用户反馈，API 在 1.0 版本发布前可能会有变更。

已知限制

• Wayland 输入 — Linux InputProvider 使用 xdotool，需要 X11。在纯 Wayland（没有 XWayland）环境下，无法模拟键盘和鼠标。辅助功能树和原生操作仍可正常使用。

• 同步 CDP — CDP 调用会阻塞，直到收到 WebSocket 响应。为避免死锁，JavaScript 对话框（alert、confirm、prompt）会自动关闭。计划重写为异步实现。

• 没有浏览器导航 API — Touchpoint 不提供内置的 URL 导航功能。Agent 可以直接与 UI 元素交互来导航：找到地址栏，输入 URL，然后按 Enter。

• CDP 窗口是页面目标，而不是操作系统窗口 — 但窗口管理仍可正常工作：tp.activate_window() 通过 CDP 将目标置于前台，而针对已显示的 cdp: 窗口执行 minimize/fullscreen/close/move/resize 时，会将操作路由到对应的原生操作系统窗口（通过所属 PID 确定），并由平台后端处理。只有在无法找到该目标对应的原生操作系统窗口时（例如该窗口已关闭），才会引发 ActionFailedError。

• 后端角色/状态一致性仍不均衡 — macOS AX 和 Windows UIA 在 0.3.0 中都有显著改进，但 Windows 仍更多依赖启发式方法，且未映射的长尾角色也比其他后端更多。

路线图

高优先级

• 异步 CDP 架构 — 非阻塞 WebSocket、完善的对话框排队机制、并发查询多个标签页

中优先级

• 后端角色/状态一致性 — 弥合剩余的角色映射差异，尤其是 Windows 上 UIA 的长尾角色
• Wayland 输入后端 — 在 X11 不可用时使用 libei / xdg-desktop-portal RemoteDesktop

低优先级

• 工具提示和通知的可见性
• 元素缓存

许可证

MIT