Touchpoint 是 Touchpoint-Labs 在 GitHub 上开源的一个跨平台 Python 库，定位为“给 AI 智能体在任意桌面上装上眼睛和手”。它的核心思路是不使用像素抓取或视觉模型，而是读取系统原生的无障碍（可访问性）API，获取屏幕上每个元素的结构化信息，包括名称、角色、状态和位置，从而做到快速、可靠且无需视觉模型。
用途方面，Touchpoint 用于让 AI 智能体阅读和交互桌面 UI，覆盖 Linux、macOS 和 Windows，并内置对 Chromium 和 Electron 应用（如 Slack、Discord、VS Code 等）的支持，通过 CDP（Chrome DevTools Protocol）获取完整网页内容。它适合需要自动化操作桌面应用、读取界面内容或让 LLM 智能体控制桌面程序的场景，官方展示了一个示例：AI 智能体在 Chrome 中研究数据，然后创建格式化的 Excel 表格，整个任务约 12 分钟完成。
主要能力上，Touchpoint 提供统一的 API，每个元素都有唯一 ID，例如 atspi:1234:1:2.0 或 cdp:9222:TID:4；动作函数同时接受 Element 对象或裸 ID 字符串，方便跨步骤保存引用。它自带 MCP（Model Context Protocol）服务器，可接入 Claude、Cursor、Windsurf、VS Code 等兼容 MCP 的客户端，也可用于本地模型，让 LLM 智能体开箱即用地控制桌面应用。
MCP 服务器支持两种模式：vision 模式（默认）下，智能体使用 screenshot() 查看屏幕，并通过元素 ID 或坐标进行交互，适合视觉能力较强的前沿模型；no-vision 模式下，智能体使用 snapshot() 获取活动窗口的紧凑结构化文本树，然后直接操作元素 ID，适用于任何模型，包括无视觉能力的本地模型。多数动作工具会附加自动验证标记，如 (new window: ...)、(focus moved)、(no change detected)，让智能体无需截图即可检测状态变化。MCP 服务器内置说明，教导智能体每种模式的正确工作流程，包括“定位 → 操作 → 验证”循环、何时使用 read_text 与 find，以及如何从错误中恢复。
使用方式上，安装命令为 pip install touchpoint-py，需要 Python 3.10+。所有内容均已包含：平台原生后端、浏览器与 Electron 应用的 CDP 支持、MCP 服务器以及截图能力；平台相关依赖通过 pip 环境标记自动安装。MCP 客户端配置方面，官方提供了针对 Claude Desktop（macOS 配置路径 ~/Library/Application Support/Claude/claude_desktop_config.json；Windows 配置路径 %APPDATA%\Claude\claude_desktop_config.json；若使用虚拟环境需使用完整路径 "/path/to/venv/bin/touchpoint-mcp"）、VS Code（工作区 .vscode/mcp.json）、Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）以及 OpenClaw（~/.openclaw/openclaw.json 的 mcpServers）的配置方式。浏览器与 Electron 应用需要以调试端口启动，Touchpoint 默认启用自动发现。
API 参考方面，提供 Discovery、Search & Wait、Actions、Input、Screenshot & Config 等类别。elements()、find() 和 get_element() 支持 format="flat"、format="json" 或 format="tree"（仅 elements）返回预格式化字符串。source 参数可控制结果来源，source="ax" 仍作为 source="cdp_ax" 的兼容别名被接受，新代码建议使用 cdp_ax 以避免与原生 macOS AX 后端混淆。CDP 结果会与原生后端结果合并，在同一次 elements() 调用中同时返回来自 AT-SPI2/UIA/AX 的工具栏和窗口控件，以及来自 CDP 的完整网页内容。
架构上采用两层设计：Backend 读取无障碍树并执行结构化动作（点击、设值、聚焦），元素感知且可靠；InputProvider 模拟原始键盘和鼠标输入，基于坐标且不感知元素，当原生无障碍动作不可用时作为自动回退使用。CDP 与平台后端并行运行，结果合并。窗口管理在 Linux AT-SPI2、Windows UIA 和 macOS AX 后端上均有实现。tp.diagnostics() 返回 JSON 友好的健康报告，包含活动后端、输入提供器、CDP 目标、可选平台工具、配置的超时以及近期因 AX 消息超时被跳过的 macOS 应用。
适用场景包括：让 AI 智能体在 Chrome 等浏览器中检索数据并操作办公软件、自动化跨平台桌面应用交互、在无视觉模型的环境下读取界面结构、将桌面控制能力接入 MCP 兼容的 LLM 客户端。
限制方面，官方明确标注为 Alpha 阶段，虽功能完整并在三大平台测试通过，但 API 在 1.0 之前可能根据用户反馈变化。已知限制包括：Wayland 输入——Linux InputProvider 使用 xdotool，需要 X11，在纯 Wayland（无 XWayland）下键盘/鼠标模拟不可用，但无障碍树和原生动作仍可工作；同步 CDP——CDP 调用会阻塞等待 WebSocket 响应，JavaScript 对话框（alert、confirm、prompt）会被自动关闭以防止死锁，异步重写已在计划中；没有内置浏览器导航 API，智能体需直接与 UI 元素交互来导航（找到地址栏、输入 URL、按回车）；CDP 窗口是页面目标而非操作系统窗口，但窗口管理仍可工作，tp.activate_window() 会通过 CDP 将目标带到前台，对已显现的 cdp: 窗口执行最小化/全屏/关闭/移动/调整大小会路由到底层原生 OS 窗口（按所属 PID 解析）并由平台后端处理，仅当找不到该目标对应的原生 OS 窗口（例如已关闭）时才抛出 ActionFailedError；后端角色/状态一致性仍不均衡，macOS AX 和 Windows UIA 在 0.3.0 中均有显著改进，但 Windows 仍依赖更多启发式方法，且存在更多未映射的长尾角色。后续计划包括高优先级：异步 CDP 架构（非阻塞 WebSocket、正确的对话框排队、并发多标签查询）；中优先级：后端角色/状态一致性（弥补剩余角色映射差距，尤其是 Windows 上的 UIA 长尾角色）、Wayland 输入后端（在 X11 不可用时使用 libei / xdg-desktop-portal RemoteDesktop）、工具提示和通知可见性、元素缓存。
