## Why

Traditional "device farm" (群控) tools work by having a human write a fixed automation script that the system blindly replays. That model breaks the moment a UI changes, and it caps the system at whatever the script author anticipated. This project inverts the model: an LLM observes the real screen state, decides the next action itself, and the system's only job is to expose stable, semantic capabilities (screenshot, tap, OCR, launch, ...) that the LLM can call. We are building **Apex Agent**, an AI-native iPhone Agent Platform (working name "IPA"), starting from an empty repository. WebDriverAgent (WDA) is treated as just one interchangeable driver behind a capability layer, not the platform itself — so Android/other drivers can be added later without touching the agent or tool layers.

## What Changes

- Introduce a **Device Manager** that discovers, connects to, and tracks the lifecycle/state (idle/busy/offline/error) of physical iPhones.
- Introduce a **driver-independent Capability Layer** (screenshot, tap, swipe, input, launch, terminate, tree, home, lock/unlock) implemented first via a stateless **WDA Driver** adapter (Appium Python Client / WDA HTTP), designed so a future `AndroidDriver` can implement the same interface.
- Introduce a **Vision/Perception pipeline** that fuses screenshot + UI tree + OCR into a single unified **Scene** model (JSON: screen size + elements with type/text/bounds/confidence) — the only representation the AI ever sees; raw XCUIElement/XML types are never exposed.
- Introduce an **Agent Runtime** (Planner + Executor + Memory/Context) that runs the Observe → Think → Act → Observe loop, decomposing a high-level goal (e.g. "open Taobao and search Mac mini") into tool calls, with retry/wait handling in the Executor so the LLM doesn't have to micromanage timing.
- Introduce a **Task Memory / Timeline** store that persists each step's screenshot, OCR result, UI tree, prompt, tool call, and result to disk (per-task history), laying the groundwork for future replay.
- Introduce an **MCP Tool Server** (and a thin REST API) that exposes all of the above as semantic, LLM-facing tools (`take_screenshot`, `tap`, `swipe`, `input_text`, `launch_app`, `find_text`, `find_icon`, `get_ui_tree`, `describe_screen`, `list_devices`, `device_status`, ...) so any MCP-compatible client (Claude Desktop, GPT function calling, etc.) can drive a real iPhone without ever knowing Appium/WDA/HTTP exist underneath.
- Explicitly out of scope for this change (non-goals): scripted "keystroke wizard" style macros, a script recorder/IDE, a visual flow orchestrator, Android/browser/Windows drivers (interface must allow them later, but no second driver ships now), and a production task queue (Redis/RabbitMQ) — synchronous execution is enough for the MVP loop.

## Capabilities

### New Capabilities
- `device-management`: Device discovery/connection/state tracking (DeviceManager) plus the driver-independent device capability interface (connect/disconnect/screenshot/tap/swipe/input/launch/terminate/tree/home/lock/unlock) and its first concrete implementation, the stateless WDA driver.
- `scene-perception`: Turns a raw screenshot + UI tree + OCR pass into the unified Scene JSON model that the agent and LLM consume instead of raw XML/XCUIElement data.
- `agent-runtime`: Planner + Executor + Memory/Context implementing the Observe → Think → Act → Observe loop, including retry and wait handling around tool calls.
- `task-memory`: Per-task timeline persistence of each step's screenshot, OCR, tree, prompt, tool call, and result to local storage (artifact store), forming the basis for future replay.
- `mcp-tool-server`: MCP server (plus thin REST surface) exposing device, perception, and agent capabilities as stable, semantic tools for LLM function calling, with no Appium/WDA concepts leaking through.

### Modified Capabilities
(none — this is the first change in an empty project)

## Impact

- **New code**: entire initial codebase — `core/` (device manager, driver interface, WDA driver, scene model, memory, models), `tools/` (screenshot, tap, swipe, input_text, launch_app, ui_tree, describe_screen), `vision/` (ocr, ui_parser, scene_builder, icon_detector), `runtime/` (planner, executor, context, task), `api/` (rest, mcp), `storage/` (timeline, artifact_store), `tests/`.
- **Dependencies**: Python 3.14 (per existing `pyproject.toml`), Appium Python Client / WDA HTTP client, an OCR engine (e.g. PaddleOCR), FastAPI, an MCP server SDK, SQLite for MVP metadata storage, local filesystem for screenshots/artifacts.
- **External systems**: requires a real (or simulator) iPhone reachable via WebDriverAgent/Appium; no cloud services required for the MVP.
- **Follow-on work explicitly deferred**: Android/browser/Windows drivers, PostgreSQL migration, MinIO/object storage, Redis/RabbitMQ task queue, icon-detection model beyond a basic stub.