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, launch, install/uninstall, clear data, export APK	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, 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 a DeviceDashboardSnapshot aggregated from multiple commands; loading and error are part of the 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 queries application attributes in batches using user/system, enabled/disabled, and field parameters; icons use a separate helper request. Only the current filter set is queried, with no per-app pm path, dumpsys package, or stat calls. Filter results, details, and icons remain cached for the management-page scope and are cleared when that scope exits.
• The home summary uses one generic helper batch to collect multiple read-only sources without adding a dedicated helper API for every infrequent command. Each query and application field returns its value or an English error independently, so one failed item never aborts the batch.
• Every helper call uses one guard shell and a stable remote path on the target device. A missing remote JAR returns DADB_HELPER_MISSING; otherwise the shell enters the helper through invoke <version> <request...>. A version mismatch returns DADB_HELPER_VERSION_MISMATCH. The app overwrites the JAR only for these two states, then retries the original request once. Any helper protocol or behavior change must bump the helper version.
• File directory listings and process snapshots now use structured dadb-helper responses instead of parsing device-dependent find/ls/ps text in the app. The same bundled helper asset also provides compatibility screenshots 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 and file state is scoped to the selected session and released when the management screen is disposed; a cache key or completed background task must not leak across sessions or devices.
• 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.
• 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.
• 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.