ios-agent

ios-agent 是一个让 AI 智能体操作 iOS 模拟器或真实 iPhone 的开源项目，使用 Apple 公开的 XCTest/XCUIAutomation 框架与 WebDriverAgent 驱动设备，支持通过线缆或 Wi-Fi 连接。其核心设计是每次操作都返回操作后实际生成的屏幕状态，并附带 screen_changed 标志，因此智能体能够立即发现点击未生效或输入文字未落位的情况；即使在真实 iPhone 上，无操作也会返回 screen_changed=False。输入文本时会从输入框中回读校验，未成功输入会返回 ok: false 并附带字段实际显示内容。智能体通过元素引用（如 e2）而非坐标定位元素，若屏幕变化导致引用失效，宿主会按元素身份在六层机制中重新查找，若引用指向其他元素则拒绝执行。开关操作是设置为目标状态而非切换，重放步骤通过幂等键避免重复点击。\n\n在 token 消耗方面，屏幕以紧凑摘要而非无障碍 XML 返回，实测在真实第三方屏幕上将 251 个原始节点压缩为 12 个元素，十三个黄金流程中每步约 50 至 474 个 token；当下一屏相似时，操作只返回变化部分。300 行联系人列表可在一次观察中以 438 个 token 返回。ios_find 可搜索完整树以弥补摘要遗漏，避免压缩永久隐藏控件。\n\n安全方面，默认开启审批门：发送、支付、购买、删除、确认、退出以及任何触达他人的操作（点赞、关注、评论、回复、分享、邀请、消息、发布）在发生前需要审批；无审批人时全部拒绝。审批限定于单次操作，批准发送不会批准删除。密码通过 ios_type_secret 从主机钥匙串读取并直接发送到设备，不进入提示词或审计记录，输入后所有返回屏幕中以 [secret] 替代；卡号（含分组形式）和邮箱地址在会话内脱敏，MCP 服务器、内置智能体和终端应用看到的都是脱敏后屏幕。重复失败或检测到循环会终止会话。设备选择器不会预选真实手机，连接真实设备始终需要一次按键。所有默认值可通过 IOS_MCP_* 环境变量、.env 或 ios-mcp.toml 调整。\n\n使用方式包括三种：终端应用可流式显示模型推理过程与屏幕摘要，并显示操作数、设备 token 和成本，manual 模式无需 API 密钥；MCP 服务器提供 31 个工具、5 个资源和 ios_operator 提示词，支持 stdio 或 HTTP，可接入 Claude Code、Cursor、Claude Desktop、VS Code 等 MCP 客户端；Python 库 IosSession 可直接调用。模型提供者通过 LangChain 的 init_chat_model 配置，支持 Anthropic、OpenAI、Azure OpenAI、Gemini、Vertex AI、Bedrock、Groq、Mistral 及本地 Ollama，切换只需两个环境变量。\n\n适用场景包括：验证代码改动在运行应用中的效果、修改设置、从无 API 的应用读取答案、在无法交给测试套件的手机上走通流程。它不适用于 Android、其他平台、构建或性能分析；Flutter 画布和 WebView 没有可读树，摘要会提示并指向截图而非返回空屏幕；审批门不防御屏幕中植入的指令；真实 iPhone 需要签名运行器，免费 Apple ID 的配置文件仅七天有效。