SamXiaBing/dsh-adb

dsh-adb

ADB device & bench operations for DeepSeek Harness

Give DSH agents direct control over Android devices and automotive bench rigs: device discovery, structured logcat, APK install, file pull/push, and performance snapshots. Built for on-vehicle and bench debugging workflows — generic within the domain (no Unity, no vendor protocol lock-in).

English | 简体中文

Install

dsh plugin --profile web add dsh-adb

Or install directly from GitHub: dsh plugin --profile web add github:SamXiaBing/dsh-adb

Web device panel (v1.1.0)

A Devices tab (UI label 设备) in the conversation view ring (next to chat / trajectory / automation): device list with status, package autocomplete (fuzzy search), live streaming logcat window (level/keyword/package/pid filters, pause/clear/auto-scroll), device info card, process list, performance snapshot, and a one-click health report (UI label 设备体检 / Device Checkup: device identity, top-RSS processes, crash buffer, W/E/F logcat window, storage — persisted under reportDir, sendable to the conversation for diagnosis). The report turns raw evidence into signal before it reaches the model: crash-buffer entries are classified into real crashes (with stack chains) vs. MediaTek boot markers, repetitive logcat is aggregated by tag ("AOSP-MdnsDiscoveryManag ×3264" instead of 3k identical lines), and a compact health summary (verdict + issues) is attached — so the agent reasons from conclusions, not 17k raw lines. Plus harness synergy: send any logcat/snapshot/report to the conversation (the agent analyzes it), a live strip of the agent's adb operations, and a registered crash-analysis skill (dsh-adb-crash-analysis) for automation pipelines. Data flows over the package RPC channel; install into a web profile and restart the GUI (see scripts/restart-web.ps1 for a one-click restart).

Ecosystem

• ✅ npm — dsh-adb published (latest: 1.6.0)
• ✅ awesome-deepseek-harness#87 — merged
• ✅ awesome-dsh-plugin#85 — merged
• ✅ awesome-DSH-plugin#29 — merged

Topics: dsh-plugin dsh adb android automotive bench

Tools

Errors are structured AdbError with stable codes: ADB_NOT_FOUND, ADB_UNAVAILABLE, DEVICE_NOT_FOUND, NO_DEVICES, CONNECT_FAILED, INSTALL_FAILED, ADB_EXIT_<code>, etc.

Approval guard (destructive operations)

Device-mutating calls route through harness's approval seam before executing: adb_install, adb_file push/rm, and adb_operation_ledger rollback return a pre-execute ask decision with a human-readable reason (tool + serial + target), and the session's approval answerer (web UI card, ACP machine policy) decides. Fail closed by design: with no approval service loaded (headless) or a never policy, these calls are denied — read-only tools are unaffected and need no approval wiring. This mirrors the plugin-wide rule that "couldn't check" ≠ "allowed".

Usage: adb_watch_crash (Crash Watchdog)

Watch the device's crash buffer for new real crashes. On start, it reads the current buffer and remembers every existing crash signature (seed), so only crashes that appear after the watch begins are reported. Boot markers (mtk-brm-*) are not crashes and are ignored.

Foreground mode (default) — blocks until a new crash appears or the budget expires:

// Agent calls:
{ "name": "adb_watch_crash", "args": { "timeoutMs": 60000 } }

// New crash detected:
{ "matched": true, "waitedMs": 3200, "crashes": [{ "time": "08-26 06:22:56.714", "pid": "2947", "tag": "AndroidRuntime", "message": "FATAL EXCEPTION: WM.task-1", "stack": ["AndroidRuntime: Process: com.miui.weather2, PID: 2947", "..."] }] }

// No new crash within budget (not an error):
{ "matched": false, "waitedMs": 60000, "crashes": [], "reason": "no new crash within 60000ms" }

Background mode (run_in_background) — returns a job id immediately, keeps polling:

// Start watching in the background:
{ "name": "adb_watch_crash", "args": { "run_in_background": true, "timeoutMs": 300000 } }
// → { "kind": "background", "jobId": "adb-watch-crash-1" }

// Read latest detections with job_output:
// [adb_watch_crash] detected 1 new crash(es) after 5400ms
// - 08-26 06:22:56.714 pid=2947 AndroidRuntime: FATAL EXCEPTION: WM.task-1
//     AndroidRuntime: Process: com.miui.weather2, PID: 2947
//     ...

Chain with crash capture — when a crash is detected, pair with adb_crash_report and adb_screenshot to capture the scene:

1. adb_watch_crash (watch for new crash)
2. → crash detected → adb_crash_report (full crash scene: buffer + dropbox + process + memory)
3.                    → adb_screenshot (screen state at crash time)

Configuration

Set the config block in cordis.patch.yml (or a profile patch):

- id: dsh-adb
  name: dsh-adb
  config:
    adbPath: C:\Users\me\AppData\Local\Android\Sdk\platform-tools\adb.exe
    defaultSerial: emulator-5554
    timeoutMs: 30000

Development

npm install            # add --include=dev when NODE_ENV=production
npm run build          # tsc → lib/
npm test               # parser/classification unit tests (node --test)
npm pack --dry-run     # verify publish contents (lib/ + cordis.patch.yml)

Testing & Verification

• Principle: ship only what is tested — every committed feature has unit and/or end-to-end coverage.
• Verified on: Android 13 automotive bench + Android 14 phone (Redmi K50 Pro) + emulator.
• Per-version changes and verification: CHANGELOG.md; test methodology and coverage: docs/TESTING.md (Chinese).

Project Docs (bilingual; for AI agents & contributors)

• docs/AGENTS.md / docs/AGENTS.zh-CN.md — read first: purpose, rules, commands, environment facts, doc map
• docs/REQUIREMENTS.md / docs/REQUIREMENTS.zh-CN.md — purpose / scope / non-goals / acceptance criteria
• docs/TESTING.md / docs/TESTING.zh-CN.md — testing philosophy, three test layers, E2E steps, regression checklist
• docs/ROADMAP.md / docs/ROADMAP.zh-CN.md — harness×adb synergy feature roadmap (diagnosis report, crash attribution, screenshot vision, bench automation tests, wait primitives, approvals, multi-device compare, scheduled monitoring, rollback ledger)
• docs/SCHEDULED-PATROL.md / docs/SCHEDULED-PATROL.zh-CN.md — run the patrol unattended on a schedule (dsh-automation prompt template + gotchas)
• PLAN.md / PLAN.zh-CN.md — milestones & backlog

License

MIT