Management Features

Management Features

中文 · ADB Connection Lifecycle

Management provides device-operation capabilities after ADB is established. It does not require a video Surface or the complete scrcpy session. Management availability does not prove remote-control availability; management failure should first be classified as transport, permission, command, parsing, or remote-capability failure.

Current sections

SessionManagementSection defines seven sections:

Section	Capabilities	Main boundary
DeviceInfo	System, display, storage, memory, battery, CPU, and network snapshot	Read-model aggregation; does not repair connections
Utility	Fixed wireless port, screenshot, reboot/power, app activation, DPI/resolution, animation, sleep/wake	Device-changing actions require confirmation and results
Files	Browse, upload/download, copy, move, rename, delete, preview/edit	Path quoting, permission, temporary local files, large-file lifetime
Apps	List, icons, details, running state, launch, install/uninstall, enable/disable, force-stop, clear data, single/split/batch export	Helper/cache use and dangerous-action confirmation
Process	Dynamic process list, search, memory, and termination	Dynamic snapshot, not static app-cache performance
PortForward	Saved session rules and active ADB forwards	Port conflicts, symmetric setup/removal, session ownership
Command	One-shot commands, built-in and user-defined presets, history, and interactive terminal	Ordinary command versus streaming shell and PTY lifetime

Connection ownership

• Pages reuse or create an exact transport-identity connection through AdbConnectionManager.
• screen-remote://session/{selector}/manage/{section} may connect a saved session or a transient TCP endpoint and open one of the seven sections. File URLs may select an initial path; command URLs only prefill text and never execute it.
• One-shot work uses AdbConnection.executeShell() or AdbShellManager; continuous output uses streaming or PTY APIs rather than polling to imitate a terminal.
• Leaving the page currently retains an ADB connection protected by the foreground service; it does not imply automatic disconnect. A product change must implement this explicitly at entry and exit.
• scrcpy and management no longer switch based on a delayed-ACK product profile. One network connection assigns work between primary and streaming lanes.

Data and performance

• Device information is an app-side DeviceDashboardSnapshot built from the helper's typed RemoteDeviceSnapshot; loading and error are part of the app snapshot.
• As soon as the management connection is ready, SessionManagementDataProvider starts three session-scoped warm-ups in parallel: the device dashboard, the /sdcard file snapshot, and the default application-data request. The screen reuses those results instead of starting its first ADB request during composition. Each source is single-flight, and a failed request may be retried.
• The device helper first queries the current filter set's basic application attributes, including version code, version name, and last update time. After that inventory is published, full details and missing or stale icons load concurrently. The app uses a global icon cache keyed by package and version metadata; icon requests contain only cache misses and return the final version metadata with each image. Icon validation does not render or hash remote icons.
• The home summary uses one typed RemoteDeviceSnapshot whose fields correspond to the supported device facts. Every field carries its own value or English error, and missing fields are reported without aborting valid fields. Parsing and presentation remain in the app.
• Every helper feature first calls the shared version guard for 1.4.2 at /data/local/tmp/dadb-helper.jar. A matching JAR is reused; any missing, mismatched, or unreadable readiness response causes one upload followed by verification. Protocol or behavior changes must bump the shared helper version rather than introducing per-feature upload state.
• File directory listings and process snapshots use structured dadb-helper responses instead of parsing device-dependent find/ls/ps text in the app. The same bundled helper asset provides device snapshots, version-metadata-based application icons, compatibility screenshots and live touch, and non-ASCII text injection.
• The prefetched /sdcard file snapshot is consumed once when Files first opens; later path loads read the requested directory again rather than retaining an unbounded per-directory cache. Manual or section refresh bypasses the ready state for only that section; refresh tokens are not shared across Files, Apps, Process, and PortForward.
• App inventory, details, and file state are scoped to the selected session and released when the management screen is disposed. The icon store is intentionally global and survives session changes; completed background work must still verify the active session before publishing inventory or detail state.
• The Apps page reuses the process helper to derive package-level running state and folds package:child processes into the main package. Long-press enters selection mode; batch shell operations run sequentially and report succeeded/failed counts. A single APK remains an .apk, split packages are archived as .apks, and batch export creates a ZIP grouped by package name.
• App details preserve per-field helper Value, Missing, and Error semantics. A cached fallback may remain visible, but the UI also identifies values not reported by the device or fields that failed to load.
• Dynamic process, storage, and network data uses an explicit refresh token or trigger and must not execute unbounded commands on Compose recomposition.
• Lists are virtualized. Large results are parsed off the UI thread and committed as stable models.
• File, app, and process parsers should be testable pure functions; pages coordinate state and actions.

Interactive terminal

• The command page owns one reconnecting raw shell with keepalive, an unbounded de-duplicated history for the current management-screen lifetime, and explicit clear/close behavior. Up/down keys or controls navigate history.
• A new shell starts in /sdcard. Tab or the Complete control requests case-insensitive command/path completion; repeated completion cycles candidates, and a unique directory match advances to its children.
• Preset buttons are composed from built-in commands plus user-defined shell commands. Users can manage those custom commands from Settings → Custom Commands, including replacing all built-in presets.
• Each submitted command appends a private completion marker carrying its exit status. The marker is buffered across fragmented reads, hidden from output, and rendered as a separator between commands.
• The toolbar and physical keyboard can send Ctrl+C. Full-screen interactive programs such as vi, nano, less, screen, and tmux are blocked because the raw shell does not provide their required terminal model; non-interactive and streaming commands such as cat, grep, sed, and tail -f remain allowed.
• ANSI control sequences are removed. Output uses a fixed dark terminal palette, semantic success/warning/error tones, token highlighting, and the final grep/rg pattern for match highlighting; these colors are presentation only and are not parsed as command state.
• PTY output normalizes CRLF, including a \r and \n split across packets, while a standalone carriage return still replaces the current line.

Safety and failure

• Uninstall, clear data, process termination, file delete/overwrite, reboot, and power-off require an explicit target and confirmation.
• Shell arguments, paths, and package names use the quoting required by their command; raw user values must not become executable structure.
• Present the failure stage, exit or exception summary, and an actionable suggestion. Logs may contain redacted commands but not tokens, clipboard content, or private-file content.
• Connection closure cancels terminals, file transfer, and background loads. Old tasks must not update a page after the selected device changes.

Regression anchors

• SessionManagementAppSizeTest, SessionManagementFileTypeTest, SessionManagementFileCopyTest.
• SessionManagementNetworkInfoTest, SessionManagementProcessSearchTest.
• SessionManagementPortForwardSupportTest.
• SessionManagementAppIconCacheTest: version code/name/update-time cache validation and invalidation.
• SessionManagementDeviceInfoSupportTest: complete /proc/uptime field parsing.
• SessionManagementAppSortTest: repeated sort selection toggles direction; title, size, and enabled-state comparators honor ascending/descending order.
• SessionManagementTerminalHighlightTest: semantic output, grep matches, hidden command markers/separators, completion, unsupported interactive commands, and session-lifetime history.
• Device coverage for permission refusal, command failure, mid-operation disconnect, large directories/app lists, cancelled dangerous actions, and Android/ROM command differences.