feat: checkpoint device agent runtime milestones

2026-07-06 17:24:03 +08:00
parent 2d4251e98e
commit 5658735bca
153 changed files with 8060 additions and 65 deletions
@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Driver type registry lives in the driver layer
+The system SHALL provide a registry, owned by the `driver` package, that maps a `driver_type` string (e.g. `"wda"`) to a builder function producing a `DriverFactory` for that type, so that any caller needing to construct a driver for a device does so without importing a concrete driver class directly.
+
+#### Scenario: Building a factory for a known driver type
+- **WHEN** a caller requests a driver factory for `driver_type="wda"` with connection info (e.g. `server_url`, `udid`)
+- **THEN** the registry returns a `DriverFactory` that, when invoked, constructs a working `WDADriver` configured with that connection info
+
+#### Scenario: Building a factory for an unknown driver type
+- **WHEN** a caller requests a driver factory for a `driver_type` that is not registered
+- **THEN** the registry raises a clear error naming the unsupported `driver_type`, instead of returning `None` or a factory that fails later at connect time
+
+### Requirement: Adding a driver type requires no changes outside the driver layer
+The system SHALL allow a new driver type to be added by registering it in the `driver` package's registry alone; no other package (`api/`, `device/`, `tools/`, `runtime/`) SHALL need code changes to support constructing devices of the new type.
+
+#### Scenario: API layer is agnostic to registered driver types
+- **WHEN** the console config API resolves a `driver_type` string into a driver factory to register a device
+- **THEN** it does so by calling into the driver registry rather than maintaining its own mapping of `driver_type` to concrete driver classes
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Perception is exposed through a swappable provider port
+The system SHALL define a `PerceptionProvider` interface (`build_scene`) in the `perception` package that any concrete perception implementation (the existing OCR+tree fusion, a future cloud vision API, a future null/mock provider) must satisfy identically, so `tools/`, `runtime/`, and `api/` depend only on the port, never on a specific perception technique.
+
+#### Scenario: Building a scene through the default provider
+- **WHEN** a caller requests a Scene for a screenshot and UI tree via the default (OCR+tree fusion) provider
+- **THEN** the provider returns a `Scene` identical in shape and content to what the existing fusion logic already produces — no change to `scene-perception`'s specified behavior
+
+### Requirement: A null perception provider is available for testing and low-dependency development
+The system SHALL provide a `NullPerceptionProvider` that returns an empty `Scene` (correct screen width/height, zero elements) without requiring OCR/vision dependencies to be installed or invoked.
+
+#### Scenario: Running without OCR dependencies installed
+- **WHEN** the runtime is configured to use `NullPerceptionProvider` (e.g. in a test or a minimal development environment)
+- **THEN** `describe_screen`/Agent Runtime calls succeed and return an empty Scene instead of failing due to missing OCR dependencies
+
+### Requirement: Adding a perception technique requires no changes outside the perception layer
+The system SHALL allow a new perception provider (e.g. a cloud vision API) to be added by registering it within the `perception` package alone; `tools/`, `runtime/`, and `api/` SHALL NOT require code changes to use a newly registered provider.
+
+#### Scenario: Runtime is agnostic to which provider is active
+- **WHEN** the Agent Runtime requests a Scene for the current screenshot and UI tree
+- **THEN** it does so through the `PerceptionProvider` port without importing or knowing about `scene_builder.py`, OCR, or any other concrete technique