Agent Touch Layer

核心用法

ATL (Agent Touch Layer) 是专为 iOS Simulator 设计的 HTTP 自动化层，通过双端口架构实现对移动端浏览器（Safari）与原生应用的双模控制：

• Browser Server (9222)：面向移动网页自动化，支持 goto 导航、markElements 标记交互元素、clickMark 按标记点击、JavaScript 注入等标准浏览器操作
• Native Server (9223)：面向任意 iOS 原生应用，基于 XCTest 的 accessibility tree 实现 openApp 启动应用、snapshot 获取可交互元素树、find/tapRef 精准定位点击

典型工作流：启动 Simulator → 部署 AtlBrowser 应用 → HTTP API 控制页面导航/应用启动 → markElements 或 snapshot 获取元素坐标 → 精准点击/输入/截图 → 验证状态。

显著优点

1. Vision-Free 自动化：独创 markElements + captureForVision 组合，为页面元素自动添加数字标记并返回带文本层的 PDF，AI 无需调用视觉模型即可获知"元素在哪里"与"页面上写了什么"，显著降低 token 成本与延迟
2. 双模统一架构：同一套 HTTP API 同时覆盖浏览器与原生应用，无需切换工具链
3. 坐标级确定性：基于标记系统的像素级坐标（x,y）点击，避免视觉模型对按钮边界的误判，同一页面结果可复现
4. 零侵入测试：基于 iOS accessibility tree，无需修改被测应用源码即可自动化任意 App

潜在缺点与局限性

• macOS/Xcode 强依赖：仅能在 macOS 环境运行，需完整 Xcode 工具链与 iOS Simulator，Windows/Linux 用户无法直接使用
• 部署门槛较高：首次使用需克隆仓库、编译 Swift 项目、配置模拟器 UDID，对非 iOS 开发者不够友好
• 稳定性风险：goto 导航存在已知问题（文档明确标注需用 JS 注入替代），Simulator 状态异常时需手动重启应用
• 模拟器局限：无法操作真机，部分依赖硬件传感器的场景（相机、GPS 精确定位）无法完整还原

适合人群

• iOS/macOS 开发者进行移动端自动化测试
• AI Agent 研究者需要低成本、高确定性的移动端交互环境
• 需要同时验证 Web 与原生 App 行为的跨平台测试场景

常规风险

1. 网络端口暴露：9222/9223 端口监听本地，多用户共享 macOS 环境时需防范端口冲突与未授权访问
2. Simulator 状态漂移：长期运行后可能出现内存泄漏或应用无响应，建议工作流中加入健康检查与自动重启机制
3. API 变动风险：项目处于活跃开发期（GitHub 仓库），HTTP API schema 可能随版本迭代调整

核心用法

ATL-Browser 是一个面向 iOS 模拟器的双服务器自动化框架，通过 HTTP API 实现对移动 Safari 浏览器（端口 9222）和原生 iOS 应用（端口 9223）的统一操控。浏览器模式支持完整的 Web 自动化能力，包括页面导航、元素标记、CSS 选择器点击、JavaScript 执行、截图与 PDF 捕获等；原生模式则通过 XCTest 框架的辅助功能树，实现对任意 iOS 应用的打开、关闭、元素查找与触摸操作。

其核心创新在于 "无视觉自动化" 工作流：通过 markElements 为页面交互元素打上数字标签并存储坐标，配合 captureForVision 生成带文本层的 PDF，AI 无需调用视觉模型即可精确定位点击位置。这种"坐标即知识"的设计消除了传统视觉方案的高延迟、高成本和不确定性，实现毫秒级响应和 100% 可复现的自动化流程。

显著优点

1. 双模统一架构：单一框架覆盖浏览器与原生应用，无需切换工具链
2. 零视觉成本：mark + PDF 组合方案彻底替代昂贵的多模态 API 调用
3. 像素级精确：存储的坐标直接映射模拟器触控，杜绝视觉识别的漂移误差
4. 三级故障恢复：坐标级 → 截图诊断 → JS 注入的渐进式降级策略
5. 原生无障碍深度：基于 iOS accessibility tree，可操作设置、通讯录等系统应用
6. 轻量部署：仅依赖 Xcode 自带工具，无额外运行时或浏览器驱动

潜在局限

1. 平台锁定：仅支持 macOS + iOS Simulator，无法操作 Android 或真机设备
2. 前置门槛：需完整安装 Xcode（约 10GB+），且需手动配置模拟器 UDID
3. 维护依赖：项目为个人开发者维护（T3），长期更新存在不确定性
4. 网络白名单：部分企业网络可能限制 GitHub 克隆或本地端口访问
5. 调试复杂度：双服务器模式增加了故障排查的链路长度

适合人群

• 移动应用测试工程师：需要批量回归测试 iOS 应用兼容性
• 自动化流程开发者：构建无需视觉 API 的低延迟网页数据采集流程
• AI Agent 构建者：为 Agent 赋予真实操作移动设备的能力
• iOS 开发者：快速验证应用在不同系统版本下的行为表现
• 教育与研究者：演示移动自动化原理或进行可复现的界面实验

使用风险

| 风险类别 | 说明 | 缓解建议 |

|---------|------|---------|

| 供应链风险 | 代码来自个人 GitHub 账号，无组织级审计 | 审查 `setup.sh` 内容，固定 commit hash 后使用 |

| 系统权限 | 脚本执行 `xcrun`、`simctl` 等系统命令 | 在隔离的 macOS 虚拟机或专用 CI 环境中运行 |

| 端口冲突 | 9222/9223 可能被其他服务占用 | 启动前执行 `lsof -i :9222` 检测冲突 |

| 状态残留 | 模拟器应用状态可能跨会话残留 | 工作流结束执行 `closeApp` 或重置模拟器 |

| 版本漂移 | iOS 更新可能导致 XCTest API 行为变化 | 锁定 Xcode 和模拟器版本，定期回归测试 |

总体而言，ATL-Browser 是移动端自动化领域极具创新性的开源方案，尤其适合追求成本效益和确定性的技术团队。建议在生产部署前完成源码审计并建立版本锁定机制。