dsh-adb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiabing7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# dsh-adb
+
+> ADB 设备·台架运维工具集 for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+
+让 DSH agent 直接操作 Android 设备 / 车机台架：设备发现、结构化 logcat、apk 安装、文件 pull/push、性能快照。面向实车与台架联调场景，业务内通用（不限 Unity、不限具体车机协议）。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-adb
+```
+
+> v0.1 发布前可从 GitHub 直装：`dsh plugin --profile web add github:SamXiaBing/dsh-adb`
+
+## 生态收录
+
+- ✅ [awesome-deepseek-harness#87](https://github.com/0xsline/awesome-deepseek-harness/pull/87) — **已合并**（2026-08-14）
+- ✅ [awesome-dsh-plugin#85](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/85) — **已合并**（2026-08-14）
+- ⏳ [awesome-DSH-plugin#29](https://github.com/Alex-Yanggg/awesome-DSH-plugin/pull/29) — 待合并
+
+Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
+
+## 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `adb_devices` | 列出设备（serial/state/product/model），先发现再操作 |
+| `adb_connect` / `adb_disconnect` | 无线台架连接（host:port，默认 5555） |
+| `adb_logcat` | 过滤读取（tag/级别/关键字/时间窗/tail）；`run_in_background` 后台连续采集，job_output 读增量、job_kill 停止 |
+| `adb_install` | 安装 apk（-r/-d/-g 选项），校验本地文件存在 |
+| `adb_file` | pull / push / ls / rm，设备隔离 |
+| `adb_perf_snapshot` | `dumpsys meminfo / gfxinfo / battery` 结构化快照（PSS/帧率百分位/卡顿率/电量） |
+
+错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
+
+## 配置
+
+`cordis.patch.yml` 的 `config` 块（或 profile patch）：
+
+```yaml
+- id: dsh-adb
+  name: dsh-adb
+  config:
+    adbPath: C:\Users\me\AppData\Local\Android\Sdk\platform-tools\adb.exe
+    defaultSerial: emulator-5554
+    timeoutMs: 30000
+```
+
+| 键 | 说明 | 默认 |
+| --- | --- | --- |
+| `adbPath` | adb 可执行文件绝对路径 | 自动探测 PATH / ANDROID_HOME / ANDROID_SDK_ROOT/platform-tools |
+| `defaultSerial` | 默认设备 serial | 无 |
+| `timeoutMs` | 命令超时 | 30000 |
+
+## 开发
+
+```sh
+npm install            # 本机 NODE_ENV=production 时加 --include=dev
+npm run build          # tsc → lib/
+npm test               # 解析器/错误分类单测（node --test）
+npm pack --dry-run     # 校验发布包内容（lib/ + cordis.patch.yml）
+```
+
+注意：本机若设了 `NODE_ENV=production`，npm 会跳过 devDependencies，安装时用 `npm install --include=dev`。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-adb
+      name: dsh-adb

package/lib/adb.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolOutputDefinition } from '@deepseek-ai/dsh-tools';
+/**
+ * dsh-adb execution core: locate the adb executable, run one adb command
+ * through the host `subprocess` service, and normalize failures into
+ * structured {@link AdbError} codes. No shell layer: every argument is an
+ * unquoted argv element.
+ */
+export interface AdbConfig {
+    /** Absolute path to the adb executable. */
+    adbPath?: string;
+    /** Default target device serial used when a tool omits `serial`. */
+    defaultSerial?: string;
+    /** Per-command timeout in milliseconds. */
+    timeoutMs?: number;
+}
+export declare class AdbError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Shared tool `output` declaration: permissive schema + pretty-printed JSON rendering. */
+export declare function jsonOutput(): ToolOutputDefinition;
+/**
+ * Resolve the adb executable: configured `adbPath` (must be absolute), then
+ * the provider's PATH, then ANDROID_HOME / ANDROID_SDK_ROOT platform-tools.
+ */
+export declare function resolveAdb(ctx: Context, cfg: AdbConfig, signal?: AbortSignal): Promise<string>;
+export interface AdbRunOptions {
+    /** Target device serial; defaults to the plugin `defaultSerial`. */
+    serial?: string;
+    /** Caller-owned cancellation (the tool `exec.signal`). */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxBytes?: number;
+}
+export interface AdbRunResult {
+    stdout: string;
+    stdoutTruncated: boolean;
+    stderr: string;
+    stderrTruncated: boolean;
+    exitCode: number;
+}
+/** Run one adb command to completion with collected stdout/stderr. */
+export declare function runAdb(ctx: Context, cfg: AdbConfig, argv: readonly string[], options?: AdbRunOptions): Promise<AdbRunResult>;
+/** Map a non-zero adb exit to a structured {@link AdbError}. */
+export declare function classifyFailure(result: AdbRunResult): AdbError;

package/lib/adb.js

@@ -0,0 +1,144 @@
+import { isAbsolute, join } from 'node:path';
+export class AdbError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'AdbError';
+        this.code = code;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_STDOUT_MAX_BYTES = 8 * 1024 * 1024;
+const DEFAULT_STDERR_MAX_BYTES = 1 * 1024 * 1024;
+/** Shared tool `output` declaration: permissive schema + pretty-printed JSON rendering. */
+export function jsonOutput() {
+    return {
+        schema: {},
+        render: (_args, value) => [
+            { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+    };
+}
+function requireSubprocess(ctx) {
+    const subprocess = ctx.get('subprocess');
+    if (subprocess === undefined) {
+        throw new AdbError('ADB_UNAVAILABLE', 'subprocess service is not available: load @deepseek-ai/dsh-subprocess (e.g. dsh-subprocess-local) in the composition');
+    }
+    return subprocess;
+}
+function exeName(base) {
+    return process.platform === 'win32' ? `${base}.exe` : base;
+}
+function platformToolsCandidates() {
+    const names = [];
+    for (const root of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+        if (root !== undefined && root !== '') {
+            names.push(join(root, 'platform-tools', exeName('adb')));
+        }
+    }
+    return names;
+}
+/**
+ * Resolve the adb executable: configured `adbPath` (must be absolute), then
+ * the provider's PATH, then ANDROID_HOME / ANDROID_SDK_ROOT platform-tools.
+ */
+export async function resolveAdb(ctx, cfg, signal) {
+    const subprocess = requireSubprocess(ctx);
+    if (cfg.adbPath !== undefined && !isAbsolute(cfg.adbPath)) {
+        throw new AdbError('ADB_CONFIG_INVALID', `adbPath must be an absolute path, got: ${cfg.adbPath}`);
+    }
+    const candidates = [...(cfg.adbPath !== undefined ? [cfg.adbPath] : []), 'adb', ...platformToolsCandidates()];
+    let lastCause;
+    for (const candidate of candidates) {
+        try {
+            const resolved = await subprocess.resolveExecutable(candidate, undefined, signal);
+            if (resolved !== '')
+                return resolved;
+        }
+        catch (error) {
+            lastCause = error;
+        }
+    }
+    throw new AdbError('ADB_NOT_FOUND', 'adb executable not found. Set `adbPath` in the dsh-adb plugin config to the absolute adb path, or install Android platform-tools and expose them via PATH / ANDROID_HOME / ANDROID_SDK_ROOT.', { cause: lastCause });
+}
+/** Run one adb command to completion with collected stdout/stderr. */
+export async function runAdb(ctx, cfg, argv, options = {}) {
+    const adb = await resolveAdb(ctx, cfg, options.signal);
+    const serial = options.serial ?? cfg.defaultSerial;
+    const args = serial === undefined ? argv : ['-s', serial, ...argv];
+    const timeoutMs = options.timeoutMs ?? cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal === undefined ? timeoutSignal : AbortSignal.any([options.signal, timeoutSignal]);
+    let handle;
+    try {
+        handle = requireSubprocess(ctx).spawn({
+            argv: [adb, ...args],
+            cwd: process.cwd(),
+            stdio: {
+                stdin: 'ignore',
+                stdout: { maxBytes: options.maxBytes ?? DEFAULT_STDOUT_MAX_BYTES },
+                stderr: { maxBytes: DEFAULT_STDERR_MAX_BYTES },
+            },
+            graceMs: 3000,
+            signal,
+        });
+    }
+    catch (error) {
+        throw new AdbError('ADB_LAUNCH_FAILED', `failed to start adb process: ${describe(error)}`, { cause: error });
+    }
+    let outcome;
+    try {
+        outcome = await handle.done;
+    }
+    catch (error) {
+        throw new AdbError('ADB_LAUNCH_FAILED', `adb process could not start: ${describe(error)}`, { cause: error });
+    }
+    const stdout = handle.collected.stdout?.readFrom(0);
+    const stderr = handle.collected.stderr?.readFrom(0);
+    const stdoutText = stdout?.text ?? '';
+    const stderrText = stderr?.text ?? '';
+    if (options.signal?.aborted) {
+        const error = new Error('tool call aborted');
+        error.name = 'AbortError';
+        throw error;
+    }
+    if (outcome.signal !== null || outcome.exitCode === null) {
+        throw new AdbError('ADB_KILLED', `adb was killed by signal ${outcome.signal ?? '(unknown)'}`);
+    }
+    return {
+        stdout: stdoutText,
+        stdoutTruncated: stdout?.lossy ?? false,
+        stderr: stderrText,
+        stderrTruncated: stderr?.lossy ?? false,
+        exitCode: outcome.exitCode,
+    };
+}
+/** Map a non-zero adb exit to a structured {@link AdbError}. */
+export function classifyFailure(result) {
+    const stderr = result.stderr;
+    const stdout = result.stdout;
+    if (/error: device .* not found/i.test(stderr)) {
+        return new AdbError('DEVICE_NOT_FOUND', excerpt(stderr));
+    }
+    if (/no devices\/emulators found/i.test(stderr)) {
+        return new AdbError('NO_DEVICES', 'no connected devices/emulators; run adb_devices first, or connect one via adb_connect');
+    }
+    if (/failed to connect|cannot connect|connection refused/i.test(stderr)) {
+        return new AdbError('CONNECT_FAILED', excerpt(stderr));
+    }
+    if (/error: closed/i.test(stderr)) {
+        return new AdbError('ADB_DEVICE_CLOSED', 'adb device connection closed (device unplugged or crashed)');
+    }
+    const failure = /Failure \[([^\]]+)\]/.exec(`${stdout}\n${stderr}`);
+    if (failure !== null) {
+        return new AdbError('INSTALL_FAILED', `install failed: ${failure[1]}`);
+    }
+    return new AdbError(`ADB_EXIT_${result.exitCode}`, `adb exited with code ${result.exitCode}: ${excerpt(stderr || stdout)}`);
+}
+function excerpt(text, max = 500) {
+    const trimmed = text.trim();
+    return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max)}…`;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+import Schema from 'schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-adb";
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+    /** Absolute path to the adb executable. */
+    adbPath?: string;
+    /** Default target device serial used when a tool omits `serial`. */
+    defaultSerial?: string;
+    /** Per-command timeout in milliseconds. */
+    timeoutMs?: number;
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,21 @@
+import Schema from 'schemastery';
+import { registerDeviceTools } from './tools/devices.js';
+import { registerFileTool } from './tools/file.js';
+import { registerInstallTool } from './tools/install.js';
+import { registerLogcatTool } from './tools/logcat.js';
+import { registerPerfTool } from './tools/perf.js';
+export const name = 'dsh-adb';
+export const Config = Schema.object({
+    adbPath: Schema.string().description('adb 可执行文件绝对路径；缺省自动探测 PATH / ANDROID_HOME / ANDROID_SDK_ROOT / platform-tools'),
+    defaultSerial: Schema.string().description('默认目标设备 serial'),
+    timeoutMs: Schema.number().default(30000).description('adb 命令超时（毫秒）'),
+});
+export function apply(ctx, config) {
+    const cfg = config;
+    registerDeviceTools(ctx, cfg);
+    registerInstallTool(ctx, cfg);
+    registerFileTool(ctx, cfg);
+    registerLogcatTool(ctx, cfg);
+    registerPerfTool(ctx, cfg);
+    ctx.logger.info('[dsh-adb] loaded: adb_devices / adb_connect / adb_disconnect / adb_logcat / adb_install / adb_file / adb_perf_snapshot');
+}

package/lib/parsers/devices.d.ts

@@ -0,0 +1,10 @@
+/** Parser for `adb devices -l` output. */
+export interface AdbDevice {
+    serial: string;
+    state: string;
+    product?: string;
+    model?: string;
+    device?: string;
+    transportId?: string;
+}
+export declare function parseDevices(text: string): AdbDevice[];

package/lib/parsers/devices.js

@@ -0,0 +1,32 @@
+/** Parser for `adb devices -l` output. */
+export function parseDevices(text) {
+    const devices = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === '' || line === 'List of devices attached')
+            continue;
+        const parts = line.split(/\s+/);
+        const serial = parts[0];
+        const state = parts[1];
+        if (serial === undefined || state === undefined)
+            continue;
+        const device = { serial, state };
+        for (const part of parts.slice(2)) {
+            const eq = part.indexOf(':');
+            if (eq === -1)
+                continue;
+            const key = part.slice(0, eq);
+            const value = part.slice(eq + 1);
+            if (key === 'product')
+                device.product = value;
+            else if (key === 'model')
+                device.model = value;
+            else if (key === 'device')
+                device.device = value;
+            else if (key === 'transport_id')
+                device.transportId = value;
+        }
+        devices.push(device);
+    }
+    return devices;
+}

package/lib/parsers/logcat.d.ts

@@ -0,0 +1,14 @@
+/** Parser for `adb logcat -v threadtime` output. */
+export type LogLevel = 'V' | 'D' | 'I' | 'W' | 'E' | 'F';
+export interface LogcatEntry {
+    time: string;
+    pid: string;
+    tid: string;
+    level: LogLevel;
+    tag: string;
+    message: string;
+}
+/** Parse threadtime lines; unrecognized lines are skipped (headers, sections). */
+export declare function parseLogcat(text: string): LogcatEntry[];
+export declare function matchesLevel(entry: LogcatEntry, minimum: LogLevel): boolean;
+export declare function matchesKeyword(entry: LogcatEntry, keyword: string): boolean;

package/lib/parsers/logcat.js

@@ -0,0 +1,27 @@
+/** Parser for `adb logcat -v threadtime` output. */
+const THREADTIME_LINE = /^(\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+([^:]+):\s?(.*)$/;
+/** Parse threadtime lines; unrecognized lines are skipped (headers, sections). */
+export function parseLogcat(text) {
+    const entries = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const match = THREADTIME_LINE.exec(rawLine);
+        if (match === null)
+            continue;
+        entries.push({
+            time: match[1],
+            pid: match[2],
+            tid: match[3],
+            level: match[4],
+            tag: match[5],
+            message: match[6] ?? '',
+        });
+    }
+    return entries;
+}
+const LEVEL_ORDER = { V: 0, D: 1, I: 2, W: 3, E: 4, F: 5 };
+export function matchesLevel(entry, minimum) {
+    return LEVEL_ORDER[entry.level] >= LEVEL_ORDER[minimum];
+}
+export function matchesKeyword(entry, keyword) {
+    return entry.message.includes(keyword) || entry.tag.includes(keyword);
+}

package/lib/parsers/perf.d.ts

@@ -0,0 +1,26 @@
+/** Parsers for `dumpsys` performance snapshots (meminfo / gfxinfo / battery). */
+export interface MeminfoSummary {
+    totalPssKb?: number;
+    totalRssKb?: number;
+    javaHeapKb?: number;
+    nativeHeapKb?: number;
+    graphicsKb?: number;
+}
+export interface GfxinfoSummary {
+    totalFrames?: number;
+    jankyFrames?: number;
+    jankyPercent?: number;
+    percentile50Ms?: number;
+    percentile90Ms?: number;
+    percentile95Ms?: number;
+    percentile99Ms?: number;
+    missedVsync?: number;
+}
+export interface BatterySummary {
+    levelPercent?: number;
+    status?: string;
+    temperatureC?: number;
+}
+export declare function parseMeminfo(text: string): MeminfoSummary;
+export declare function parseGfxinfo(text: string): GfxinfoSummary;
+export declare function parseBattery(text: string): BatterySummary;

package/lib/parsers/perf.js

@@ -0,0 +1,67 @@
+/** Parsers for `dumpsys` performance snapshots (meminfo / gfxinfo / battery). */
+export function parseMeminfo(text) {
+    const summary = {};
+    const total = /TOTAL PSS:\s+(\d+)\s+TOTAL RSS:\s+(\d+)/.exec(text);
+    if (total !== null) {
+        summary.totalPssKb = Number(total[1]);
+        summary.totalRssKb = Number(total[2]);
+    }
+    const byName = {
+        'Java Heap': 'javaHeapKb',
+        'Native Heap': 'nativeHeapKb',
+        Graphics: 'graphicsKb',
+    };
+    for (const [name, key] of Object.entries(byName)) {
+        const match = new RegExp(`^\\s+${name}:\\s+(\\d+)`, 'm').exec(text);
+        if (match !== null)
+            summary[key] = Number(match[1]);
+    }
+    return summary;
+}
+export function parseGfxinfo(text) {
+    const summary = {};
+    const total = /Total frames rendered:\s+(\d+)/.exec(text);
+    if (total !== null)
+        summary.totalFrames = Number(total[1]);
+    const janky = /Janky frames:\s+(\d+)\s*\(([\d.]+)%\)/.exec(text);
+    if (janky !== null) {
+        summary.jankyFrames = Number(janky[1]);
+        summary.jankyPercent = Number(janky[2]);
+    }
+    const percentiles = [
+        [/50th percentile:\s+(\d+)ms/, 'percentile50Ms'],
+        [/90th percentile:\s+(\d+)ms/, 'percentile90Ms'],
+        [/95th percentile:\s+(\d+)ms/, 'percentile95Ms'],
+        [/99th percentile:\s+(\d+)ms/, 'percentile99Ms'],
+    ];
+    for (const [pattern, key] of percentiles) {
+        const match = pattern.exec(text);
+        if (match !== null)
+            summary[key] = Number(match[1]);
+    }
+    const missed = /Number Missed Vsync:\s+(\d+)/.exec(text);
+    if (missed !== null)
+        summary.missedVsync = Number(missed[1]);
+    return summary;
+}
+const BATTERY_STATUS = {
+    '1': 'unknown',
+    '2': 'charging',
+    '3': 'discharging',
+    '4': 'not-charging',
+    '5': 'full',
+};
+export function parseBattery(text) {
+    const summary = {};
+    const level = /level:\s+(\d+)/.exec(text);
+    if (level !== null)
+        summary.levelPercent = Number(level[1]);
+    const status = /status:\s+(\d+)/.exec(text);
+    if (status !== null)
+        summary.status = BATTERY_STATUS[status[1]] ?? status[1];
+    // temperature is reported in tenths of a degree Celsius
+    const temperature = /temperature:\s+(\d+)/.exec(text);
+    if (temperature !== null)
+        summary.temperatureC = Number(temperature[1]) / 10;
+    return summary;
+}

package/lib/tools/devices.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/** adb_devices / adb_connect / adb_disconnect. */
+export declare function registerDeviceTools(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/devices.js

@@ -0,0 +1,61 @@
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+import { parseDevices } from '../parsers/devices.js';
+/** adb_devices / adb_connect / adb_disconnect. */
+export function registerDeviceTools(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_devices',
+        description: 'List connected Android devices (serial, state, product, model) visible to the adb server. Run this first to discover device serials before other adb_* tools.',
+        parameters: { type: 'object', properties: {}, additionalProperties: false },
+        output: jsonOutput(),
+        async execute(_args, exec) {
+            const result = await runAdb(ctx, cfg, ['devices', '-l'], { signal: exec.signal });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return { server: 'ok', devices: parseDevices(result.stdout) };
+        },
+    });
+    ctx.tools.register({
+        name: 'adb_connect',
+        description: 'Connect to a bench/device over TCP/IP (adb connect host:port). Wireless bench devices must be reachable from this machine.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['host'],
+            properties: {
+                host: { type: 'string', description: 'Device IP address or hostname, e.g. 192.168.1.100.' },
+                port: { type: 'integer', description: 'TCP port; defaults to 5555.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            const target = `${args.host}:${args.port ?? 5555}`;
+            const result = await runAdb(ctx, cfg, ['connect', target], { signal: exec.signal });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            const message = result.stdout.trim();
+            if (/failed to connect|cannot connect/i.test(message)) {
+                throw new AdbError('CONNECT_FAILED', message);
+            }
+            return { target, connected: /connected|already connected/i.test(message), message };
+        },
+    });
+    ctx.tools.register({
+        name: 'adb_disconnect',
+        description: 'Disconnect a TCP/IP device (adb disconnect [host:port]). Omit host to disconnect every wireless device.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                host: { type: 'string', description: 'Host or host:port to disconnect; omit to disconnect all.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            const argv = ['disconnect', ...(args.host !== undefined ? [args.host] : [])];
+            const result = await runAdb(ctx, cfg, argv, { signal: exec.signal });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return { message: result.stdout.trim() };
+        },
+    });
+}

package/lib/tools/file.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/** adb_file: pull / push / ls / rm on the target device. */
+export declare function registerFileTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/file.js

@@ -0,0 +1,58 @@
+import { existsSync } from 'node:fs';
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+/** adb_file: pull / push / ls / rm on the target device. */
+export function registerFileTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_file',
+        description: 'Transfer or inspect files on an Android device: pull (device -> local), push (local -> device), ls (list a device directory), rm (delete a device file/dir).',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['operation', 'devicePath'],
+            properties: {
+                operation: {
+                    type: 'string',
+                    enum: ['pull', 'push', 'ls', 'rm'],
+                    description: 'What to do: pull copies devicePath to localPath; push copies localPath to devicePath; ls lists devicePath; rm deletes devicePath.',
+                },
+                devicePath: { type: 'string', description: 'Path on the device (for pull/ls/rm) or the destination (for push).' },
+                localPath: { type: 'string', description: 'Local path: destination for pull, source for push.' },
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                recursive: { type: 'boolean', description: 'Recursive for ls (long format) or rm (delete directory trees).' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            if (args.operation === 'push') {
+                if (args.localPath === undefined) {
+                    throw new AdbError('ARGS_INVALID', 'push requires localPath (the source file)');
+                }
+                if (!existsSync(args.localPath)) {
+                    throw new AdbError('LOCAL_FILE_NOT_FOUND', `local file not found: ${args.localPath}`);
+                }
+            }
+            const argv = buildArgv(args);
+            const result = await runAdb(ctx, cfg, argv, { signal: exec.signal, serial: args.serial });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            const text = result.stdout.trim();
+            if (args.operation === 'ls') {
+                const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+                return { operation: args.operation, devicePath: args.devicePath, entries: lines };
+            }
+            return { operation: args.operation, devicePath: args.devicePath, ...(args.localPath !== undefined ? { localPath: args.localPath } : {}), message: text };
+        },
+    });
+}
+function buildArgv(args) {
+    if (args.operation === 'pull') {
+        return ['pull', args.devicePath, args.localPath ?? '.'];
+    }
+    if (args.operation === 'push') {
+        return ['push', args.localPath, args.devicePath];
+    }
+    if (args.operation === 'ls') {
+        return ['shell', 'ls', ...(args.recursive === true ? ['-lR'] : ['-l']), args.devicePath];
+    }
+    return ['shell', 'rm', ...(args.recursive === true ? ['-rf'] : ['-f']), args.devicePath];
+}

package/lib/tools/install.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/** adb_install: push and install an apk on the target device. */
+export declare function registerInstallTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/install.js

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs';
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+/** adb_install: push and install an apk on the target device. */
+export function registerInstallTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_install',
+        description: 'Install an APK on the target Android device (adb install). Requires a local path to the apk file.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['apk'],
+            properties: {
+                apk: { type: 'string', description: 'Local absolute path to the .apk file.' },
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                reinstall: { type: 'boolean', description: 'Reinstall an existing app, keeping its data (-r).' },
+                downgrade: { type: 'boolean', description: 'Allow version downgrade (-d).' },
+                grantPermissions: { type: 'boolean', description: 'Grant all runtime permissions (for targetSdk >= 23, -g).' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            if (!existsSync(args.apk)) {
+                throw new AdbError('LOCAL_FILE_NOT_FOUND', `apk not found: ${args.apk}`);
+            }
+            const flags = [
+                ...(args.reinstall === true ? ['-r'] : []),
+                ...(args.downgrade === true ? ['-d'] : []),
+                ...(args.grantPermissions === true ? ['-g'] : []),
+            ];
+            const result = await runAdb(ctx, cfg, ['install', ...flags, args.apk], {
+                signal: exec.signal,
+                serial: args.serial,
+            });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            const output = result.stdout.trim();
+            return { installed: output.includes('Success'), package: args.apk, message: output };
+        },
+    });
+}

package/lib/tools/logcat.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/** adb_logcat: foreground buffer dump with filters, or a continuous background stream job. */
+export declare function registerLogcatTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/logcat.js

@@ -0,0 +1,131 @@
+import { AdbError, classifyFailure, jsonOutput, resolveAdb, runAdb } from '../adb.js';
+import { matchesKeyword, matchesLevel, parseLogcat } from '../parsers/logcat.js';
+const MAX_ENTRIES = 500;
+const FOREGROUND_MAX_BYTES = 16 * 1024 * 1024;
+const BACKGROUND_MAX_BYTES = 64 * 1024 * 1024;
+/** adb_logcat: foreground buffer dump with filters, or a continuous background stream job. */
+export function registerLogcatTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_logcat',
+        description: 'Read or stream the Android logcat. Foreground: dump the current buffer (optionally last `tail` entries) filtered by tag/level/keyword/since/until. Background: stream new entries continuously as a background job — the call returns a job id, read deltas with job_output and stop with job_kill.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                tag: { type: 'string', description: 'Only entries whose tag equals this value.' },
+                level: { type: 'string', enum: ['V', 'D', 'I', 'W', 'E', 'F'], description: 'Minimum log level (V < D < I < W < E < F).' },
+                keyword: { type: 'string', description: 'Only entries whose tag or message contains this keyword.' },
+                tail: { type: 'integer', description: 'Foreground: return only the last N entries.' },
+                since: { type: 'string', description: 'Foreground: only entries at/after this time, e.g. "08-14 10:00:00.000".' },
+                until: { type: 'string', description: 'Foreground: only entries at/before this time, e.g. "08-14 10:30:00.000".' },
+                run_in_background: { type: 'boolean', description: 'Stream as a background job and return a job id immediately.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            if (args.run_in_background === true) {
+                return startBackgroundLogcat(ctx, cfg, args, exec);
+            }
+            const result = await runAdb(ctx, cfg, ['logcat', '-v', 'threadtime', '-d'], {
+                signal: exec.signal,
+                maxBytes: FOREGROUND_MAX_BYTES,
+                serial: args.serial,
+            });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            const { since, until, tag, level, keyword, tail } = args;
+            let entries = parseLogcat(result.stdout);
+            // threadtime timestamps ("MM-DD HH:MM:SS.mmm") sort lexicographically.
+            if (since !== undefined)
+                entries = entries.filter((entry) => entry.time >= since);
+            if (until !== undefined)
+                entries = entries.filter((entry) => entry.time <= until);
+            if (tag !== undefined)
+                entries = entries.filter((entry) => entry.tag === tag);
+            if (level !== undefined)
+                entries = entries.filter((entry) => matchesLevel(entry, level));
+            if (keyword !== undefined)
+                entries = entries.filter((entry) => matchesKeyword(entry, keyword));
+            if (tail !== undefined && tail >= 0)
+                entries = entries.slice(-tail);
+            const truncated = entries.length > MAX_ENTRIES;
+            const returned = truncated ? entries.slice(-MAX_ENTRIES) : entries;
+            return {
+                total: entries.length,
+                truncated,
+                entries: returned.map((entry) => ({
+                    time: entry.time,
+                    pid: entry.pid,
+                    tid: entry.tid,
+                    level: entry.level,
+                    tag: entry.tag,
+                    message: entry.message,
+                })),
+            };
+        },
+    });
+}
+function startBackgroundLogcat(ctx, cfg, args, exec) {
+    const jobs = ctx.get('jobs');
+    if (jobs === undefined) {
+        throw new AdbError('JOBS_UNAVAILABLE', 'background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs');
+    }
+    const subprocess = ctx.get('subprocess');
+    if (subprocess === undefined) {
+        throw new AdbError('ADB_UNAVAILABLE', 'subprocess service is not available: load @deepseek-ai/dsh-subprocess (e.g. dsh-subprocess-local) in the composition');
+    }
+    if (exec.signal.aborted) {
+        const error = new Error('tool call aborted');
+        error.name = 'AbortError';
+        throw error;
+    }
+    const serial = args.serial ?? cfg.defaultSerial;
+    const argv = [
+        ...(serial !== undefined ? ['-s', serial] : []),
+        'logcat',
+        '-v',
+        'threadtime',
+        ...(args.tag !== undefined ? ['-s', `${args.tag}:V`] : []),
+    ];
+    // Preflight: resolve adb before committing the job, so a broken setup fails
+    // the call instead of leaving a dead background job.
+    const adbPromise = resolveAdb(ctx, cfg, exec.signal);
+    const id = jobs.start({
+        kind: 'adb-logcat',
+        label: `logcat${args.tag !== undefined ? ` tag=${args.tag}` : ''}`,
+        ...(exec.agent !== undefined ? { owner: exec.agent } : {}),
+        run: () => {
+            // The stream must outlive the tool call, so the spawn carries no exec.signal.
+            let handle;
+            let cursor = 0;
+            return {
+                cancel: () => {
+                    handle?.terminate();
+                },
+                done: adbPromise.then(async (adb) => {
+                    handle = subprocess.spawn({
+                        argv: [adb, ...argv],
+                        cwd: process.cwd(),
+                        stdio: {
+                            stdin: 'ignore',
+                            stdout: { maxBytes: BACKGROUND_MAX_BYTES },
+                            stderr: { maxBytes: 1024 * 1024 },
+                        },
+                        graceMs: 3000,
+                    });
+                    const outcome = await handle.done;
+                    return { exitCode: outcome.exitCode, signal: outcome.signal };
+                }),
+                readOutput: () => {
+                    const read = handle?.collected.stdout?.readFrom(cursor);
+                    if (read === undefined)
+                        return { added: 0, text: '' };
+                    cursor += Buffer.byteLength(read.text, 'utf8');
+                    return { added: read.text.length, text: read.text };
+                },
+            };
+        },
+    });
+    return { kind: 'background', jobId: id };
+}

package/lib/tools/perf.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/** adb_perf_snapshot: dumpsys meminfo / gfxinfo / battery for one app. */
+export declare function registerPerfTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/perf.js

@@ -0,0 +1,44 @@
+import { classifyFailure, jsonOutput, runAdb } from '../adb.js';
+import { parseBattery, parseGfxinfo, parseMeminfo } from '../parsers/perf.js';
+/** adb_perf_snapshot: dumpsys meminfo / gfxinfo / battery for one app. */
+export function registerPerfTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_perf_snapshot',
+        description: 'Capture a performance snapshot of one installed app on an Android device: memory (dumpsys meminfo), rendering (dumpsys gfxinfo: janky frames, percentiles), and battery. Use it for bench/regression checks before or after a change.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['package'],
+            properties: {
+                package: { type: 'string', description: 'App package id, e.g. com.example.hmi.' },
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                metrics: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['meminfo', 'gfxinfo', 'battery'] },
+                    description: 'Which metrics to collect; defaults to all three.',
+                },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            const metrics = args.metrics ?? ['meminfo', 'gfxinfo', 'battery'];
+            const result = { package: args.package, metrics: [...metrics] };
+            for (const metric of metrics) {
+                const output = await runAdb(ctx, cfg, ['shell', 'dumpsys', metric, args.package], {
+                    signal: exec.signal,
+                    serial: args.serial,
+                    maxBytes: 4 * 1024 * 1024,
+                });
+                if (output.exitCode !== 0)
+                    throw classifyFailure(output);
+                if (metric === 'meminfo')
+                    result.meminfo = parseMeminfo(output.stdout);
+                else if (metric === 'gfxinfo')
+                    result.gfxinfo = parseGfxinfo(output.stdout);
+                else
+                    result.battery = parseBattery(output.stdout);
+            }
+            return result;
+        },
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dsh-adb",
+  "version": "0.1.0",
+  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "adb",
+    "android",
+    "automotive",
+    "bench"
+  ],
+  "license": "MIT",
+  "author": "xiabing7",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "schemastery": "^3.13.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-jobs": "0.0.1-rc.3",
+    "@deepseek-ai/dsh-llm": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.2"
+  }
+}