Requirements & Scope (REQUIREMENTS.md)

English | 简体中文

Purpose

dsh-adb lets a DSH agent operate Android devices and automotive bench rigs directly: device discovery, log collection, APK install, file transfer, performance snapshots. It targets on-vehicle / bench debugging workflows and raises "agent can run adb" from raw text shell output to structured, composable semantic tools.

Positioning: four criteria (selection basis)

1. Scenario-anchored: maps to one real recurring workflow (debugging, release verification, perf regression), not a single technique.
2. Generic within the domain: usable across roles (dev/QA/test) and projects; no Unity, no vendor protocol lock-in.
3. Self-sufficient: the plugin encapsulates adb — the agent does not need to become a domain expert.
4. Composable: works with ctx.jobs (background collection), config overrides, and the error-code system.

Explicit non-goals (scope creep guard): vendor business-protocol parsing (SR/perception/SOME-IP — that belongs to domain skills), GUI automation / click injection, binding to a single vendor or engine.

Scope

v0.1–v1.2 (shipped; current v1.6.1)

Fourteen tools (all host-side, registered via ctx.tools, JSON schema):

Tool	Capability	Key semantics
adb_devices	device list	structured array (serial/state/product/model/transport)
adb_connect / adb_disconnect	wireless connect/disconnect	host+port (default 5555); failure → CONNECT_FAILED
adb_logcat	log read/collect	filters: tag/level/keyword/since/until/tail; run_in_background streams via ctx.jobs
adb_install	APK install	local file checked first (LOCAL_FILE_NOT_FOUND); -r/-d/-g flags
adb_file	file operations	pull/push/ls(-lR)/rm; push validates local existence
adb_perf_snapshot	perf snapshot	meminfo/gfxinfo need a package; battery is device-global, must not receive a package
adb_perf_baseline	perf baseline (v0.2)	save snapshot (label/tags); compare numeric diff; list/delete; local JSON storage (baselineDir)
adb_crash_report	crash scene (v0.2)	crash buffer (parsed entries) + dropbox excerpt + process excerpt + optional meminfo; since/tail control
adb_device_report	one-click health report (v1.2)	device info + top-RSS processes + crash buffer + W/E/F logcat window + storage; per-section independent degradation; persisted to report store (reportDir, default <baselineDir>/reports)
adb_wait_for	condition wait (v1.3)	poll until device-online / boot-complete / process appeared / logcat keyword; returns matched:false on timeout, not an error
adb_operation_ledger	operation rollback ledger (v1.4)	record/list/rollback device ops; persisted as operations.json
adb_screenshot	screen capture (v1.5)	screencap → pull → local PNG with dimensions
adb_watch_crash	crash watchdog (v1.6)	watch crash buffer for NEW real crashes; seed-dedup; boot markers ignored; matched:false on timeout
adb_patrol_check	one-click patrol (v1.7)	crash scan + perf vs latest baseline (thresholded regressions) + battery/storage → verdict + issues; compareToLast delta (new/gone crashes, worsening regressions, verdict transition); fail-closed; persisted to <reportDir>/patrol

Config (Config schema, overridable via cordis.patch.yml): adbPath (absolute; auto-detect PATH/ANDROID_HOME/ANDROID_SDK_ROOT), defaultSerial, timeoutMs (default 30000), baselineDir (default ~/.dsh/storages/dsh-adb), reportDir (default <baselineDir>/reports), screenshotDir (default <baselineDir>/screenshots).

Error codes (model-visible contract, stable): ADB_NOT_FOUND, ADB_UNAVAILABLE, ADB_CONFIG_INVALID, ADB_LAUNCH_FAILED, ADB_KILLED, DEVICE_NOT_FOUND, NO_DEVICES, CONNECT_FAILED, ADB_DEVICE_CLOSED, INSTALL_FAILED, LOCAL_FILE_NOT_FOUND, ARGS_INVALID, JOBS_UNAVAILABLE, ADB_EXIT_<code> (fallback).

v1.x candidates (unscheduled, on demand)

• am start -W cold-start timing

Explicit non-goals

• Vehicle business protocol parsing (SR/perception/SOME-IP/MMKV etc.) — domain skills' job
• Full GUI automation framework (UIAutomator/Appium integration) — scripted smoke tests via input tap/swipe are tracked under ROADMAP ④ (script execution + AI image comparison), but test-framework binding is out of scope
• Binding to Unity / a single vendor

Acceptance criteria (per tool)

• Success path: returns structured JSON (fields per tool schema) the model can consume directly.
• Failure path: throws AdbError with a stable enumerable code and an actionable message (e.g. ADB_NOT_FOUND suggests configuring adbPath).
• Degradation: missing adb → ADB_NOT_FOUND; no devices → empty list, not an error; missing target device → DEVICE_NOT_FOUND.
• Background path: run_in_background returns a job id; job_output reads the stream; job_kill terminates; readOutput returns a string.
• Approval path (destructive tools: adb_install, adb_file push/rm, adb_operation_ledger rollback): a pre-execute ask decision with a human-readable reason is raised; with the approval seam absent (headless) or policy never the call is denied (fail-closed); read-only tools are never gated.

Ecosystem goals (done / in flight)

• GitHub public + 6 topics incl. #dsh-plugin ✅
• npm dsh-adb published (latest) ✅
• Three catalog PRs merged: 0xsline#87, awesome-dsh-plugin#85, Alex-Yanggg#29 ✅
• Anyone can install with dsh plugin --profile web add dsh-adb ✅