dsh-adb 1.4.0 → 1.5.0

package/README.md

@@ -42,6 +42,7 @@ Topics: `dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_device_report` | One-click health report: device identity + top-RSS processes + crash buffer (real crashes w/ stacks vs. boot markers) + W/E/F logcat aggregated by tag + storage + health verdict; each section degrades independently; persisted under `reportDir` |
 | `adb_wait_for` | Wait until a device condition holds — device-online / boot-complete / process appeared / logcat keyword — polling up to a budget, instead of sleeping a fixed number of seconds; returns `matched:false` on timeout |
 | `adb_operation_ledger` | Append-only device operation ledger (record/list/rollback): record installs/pushes/etc., list history, or roll an app back to its last known-good APK (`adb install -r`); persisted as `operations.json` — the trust base for agent-driven device modification |
+| `adb_screenshot` | Capture the device screen into a local PNG (screencap → pull), returning the saved path, byte size, and pixel dimensions — durable evidence for crash scenes / UI states / test frames |
 
 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.
 
@@ -65,6 +66,7 @@ Set the `config` block in `cordis.patch.yml` (or a profile patch):
 | `timeoutMs` | Per-command timeout | 30000 |
 | `baselineDir` | Directory for `adb_perf_baseline` storage | `~/.dsh/storages/dsh-adb` |
 | `reportDir` | Directory for `adb_device_report` storage | `<baselineDir>/reports` |
+| `screenshotDir` | Directory for `adb_screenshot` storage | `<baselineDir>/screenshots` |
 
 ## Development
 

package/README.zh-CN.md

@@ -42,6 +42,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_device_report` | 一键体检：设备信息 + Top RSS 进程 + 崩溃缓冲（真实崩溃带堆栈/启动标记分类）+ W/E/F 日志按 tag 聚合 + 存储用量 + 健康结论；每节独立降级；落盘到 `reportDir` |
 | `adb_wait_for` | 等待原语：等设备上线 / 启动完成 / 进程出现 / logcat 出现关键字，轮询到预算上限，替代盲目 sleep；超时返回 `matched:false` |
 | `adb_operation_ledger` | 操作回滚台账（record/list/rollback）：追加记录安装/推送等操作，查询历史，或回滚到最近一次成功安装的 APK（`adb install -r`）；落盘 `operations.json` —— agent 自主改设备的信任基础 |
+| `adb_screenshot` | 截图落盘 PNG（screencap → pull），返回路径/字节数/像素尺寸 —— 崩溃现场、UI 状态、测试前后对比的持久证据 |
 
 错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
 
@@ -65,6 +66,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `timeoutMs` | 命令超时 | 30000 |
 | `baselineDir` | `adb_perf_baseline` 基线存储目录 | `~/.dsh/storages/dsh-adb` |
 | `reportDir` | `adb_device_report` 体检报告存储目录 | `<baselineDir>/reports` |
+| `screenshotDir` | `adb_screenshot` 截图存储目录 | `<baselineDir>/screenshots` |
 
 ## 开发
 

package/lib/index.d.ts

@@ -15,6 +15,8 @@ export interface Config {
     baselineDir?: string;
     /** Directory for adb_device_report storage; defaults to <baselineDir>/reports. */
     reportDir?: string;
+    /** Directory for adb_screenshot storage; defaults to <baselineDir>/screenshots. */
+    screenshotDir?: string;
 }
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,6 +10,7 @@ import { registerPerfTool } from './tools/perf.js';
 import { registerPerfBaselineTool } from './tools/perf-baseline.js';
 import { registerWaitTool } from './tools/wait.js';
 import { registerOperationLedgerTool } from './tools/operation-ledger.js';
+import { registerScreenshotTool } from './tools/screenshot.js';
 import { registerRpc } from './rpc.js';
 import { registerSkills } from './skill.js';
 export const name = 'dsh-adb';
@@ -21,24 +22,28 @@ export const Config = Schema.object({
     timeoutMs: Schema.number().default(30000).description('adb 命令超时（毫秒）'),
     baselineDir: Schema.string().description('adb_perf_baseline 基线存储目录；缺省 ~/.dsh/storages/dsh-adb'),
     reportDir: Schema.string().description('adb_device_report 报告存储目录；缺省 ~/.dsh/storages/dsh-adb/reports'),
+    screenshotDir: Schema.string().description('adb_screenshot 截图存储目录；缺省 ~/.dsh/storages/dsh-adb/screenshots'),
 });
 export function apply(ctx, config) {
     const cfg = config;
-    const reportDir = config.reportDir ?? `${(config.baselineDir ?? DEFAULT_BASELINE_DIR).replace(/\\/g, '/')}/reports`;
+    const baselineDir = config.baselineDir ?? DEFAULT_BASELINE_DIR;
+    const reportDir = config.reportDir ?? `${baselineDir.replace(/\\/g, '/')}/reports`;
+    const screenshotDir = config.screenshotDir ?? `${baselineDir.replace(/\\/g, '/')}/screenshots`;
     registerDeviceTools(ctx, cfg);
     registerInstallTool(ctx, cfg);
     registerFileTool(ctx, cfg);
     registerLogcatTool(ctx, cfg);
     registerPerfTool(ctx, cfg);
-    registerPerfBaselineTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
+    registerPerfBaselineTool(ctx, cfg, baselineDir);
     registerCrashReportTool(ctx, cfg);
     registerDeviceReportTool(ctx, cfg, reportDir);
     registerWaitTool(ctx, cfg);
-    registerOperationLedgerTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
+    registerOperationLedgerTool(ctx, cfg, baselineDir);
+    registerScreenshotTool(ctx, cfg, screenshotDir);
     registerSkills(ctx);
     // The RPC channel needs the client connection, which mounts after this
     // plugin starts in web compositions; register lazily so headless profiles
     // (no connection) stay unaffected.
     ctx.inject(['connection'], (readyCtx) => registerRpc(readyCtx, cfg, reportDir));
-    ctx.logger.info('[dsh-adb] loaded: 12 tools + web device panel rpc');
+    ctx.logger.info('[dsh-adb] loaded: 13 tools + web device panel rpc');
 }

package/lib/tools/screenshot.d.ts

@@ -0,0 +1,37 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+interface ScreenshotArgs {
+    serial?: string;
+    /** Local directory to save the PNG into; defaults to the plugin screenshotDir. */
+    dir?: string;
+    /** Basename for the PNG; defaults to <serial>-<epoch>.png. */
+    name?: string;
+}
+export interface ScreenshotResult {
+    savedTo: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    serial: string;
+}
+/** Stable local-path convention for screenshot saves: <dir>/<serial>-<epoch>.png. */
+export declare function screenshotPathFor(dir: string, serial: string): string;
+/**
+ * Capture the device screen into a local PNG: screencap on the device, pull to
+ * the local dir, then best-effort rm of the on-device temp. Returns the saved
+ * path, byte size, and (when the PNG header parses) pixel dimensions.
+ */
+export declare function captureScreenshot(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: ScreenshotArgs, screenshotDir: string): Promise<ScreenshotResult>;
+/** Parse PNG dimensions from the IHDR chunk (pure; unit-tested). */
+export declare function pngDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * adb_screenshot: capture the device screen (screencap → pull) into a local
+ * PNG under the screenshot dir, and return its path + byte size. Screenshots
+ * are durable evidence: crash scenes, UI states, before/after test frames —
+ * the primitive behind the vision-based features (ROADMAP ③).
+ */
+export declare function registerScreenshotTool(ctx: Context, cfg: AdbConfig, screenshotDir: string): void;
+export {};

package/lib/tools/screenshot.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AdbError, classifyFailure, jsonOutput, runAdb } from '../adb.js';
+/** Stable local-path convention for screenshot saves: <dir>/<serial>-<epoch>.png. */
+export function screenshotPathFor(dir, serial) {
+    return join(dir, `${serial.replace(/[^A-Za-z0-9._-]/g, '_')}-${Date.now()}.png`);
+}
+/**
+ * Capture the device screen into a local PNG: screencap on the device, pull to
+ * the local dir, then best-effort rm of the on-device temp. Returns the saved
+ * path, byte size, and (when the PNG header parses) pixel dimensions.
+ */
+export async function captureScreenshot(ctx, cfg, signal, args, screenshotDir) {
+    const serial = args.serial ?? cfg.defaultSerial;
+    const devicePath = `/data/local/tmp/dsh-shot-${Date.now()}.png`;
+    const dir = args.dir ?? screenshotDir;
+    mkdirSync(dir, { recursive: true });
+    const localPath = args.name !== undefined
+        ? join(dir, args.name.endsWith('.png') ? args.name : `${args.name}.png`)
+        : screenshotPathFor(dir, serial ?? 'device');
+    try {
+        const cap = await runAdb(ctx, cfg, ['shell', 'screencap', '-p', devicePath], { signal, serial });
+        if (cap.exitCode !== 0)
+            throw classifyFailure(cap);
+        const pull = await runAdb(ctx, cfg, ['pull', devicePath, localPath], { signal, serial });
+        if (pull.exitCode !== 0)
+            throw classifyFailure(pull);
+    }
+    finally {
+        // Best-effort cleanup of the on-device temp file.
+        try {
+            await runAdb(ctx, cfg, ['shell', 'rm', '-f', devicePath], { signal, serial });
+        }
+        catch { /* cleanup is best-effort */ }
+    }
+    if (!existsSync(localPath)) {
+        throw new AdbError('SCREENSHOT_FAILED', `screencap succeeded but no file at ${localPath}`);
+    }
+    const bytes = readFileSync(localPath);
+    const dimensions = pngDimensions(bytes);
+    return {
+        savedTo: localPath,
+        bytes: bytes.length,
+        ...(dimensions !== undefined ? { width: dimensions.width, height: dimensions.height } : {}),
+        serial: serial ?? 'default',
+    };
+}
+/** Parse PNG dimensions from the IHDR chunk (pure; unit-tested). */
+export function pngDimensions(bytes) {
+    // PNG signature (8 bytes) + IHDR length (4) + "IHDR" (4) + width (4) + height (4).
+    if (bytes.length < 24)
+        return undefined;
+    const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+    for (let i = 0; i < 8; i++) {
+        if (bytes[i] !== sig[i])
+            return undefined;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return {
+        width: view.getUint32(16),
+        height: view.getUint32(20),
+    };
+}
+/**
+ * adb_screenshot: capture the device screen (screencap → pull) into a local
+ * PNG under the screenshot dir, and return its path + byte size. Screenshots
+ * are durable evidence: crash scenes, UI states, before/after test frames —
+ * the primitive behind the vision-based features (ROADMAP ③).
+ */
+export function registerScreenshotTool(ctx, cfg, screenshotDir) {
+    ctx.tools.register({
+        name: 'adb_screenshot',
+        description: 'Capture the device screen into a local PNG (screencap on device → pull to host) and return the saved path, byte size, and pixel dimensions. Screenshots are durable evidence for crash scenes, UI states, or before/after test frames. Saves under the screenshotDir (default ~/.dsh/storages/dsh-adb/screenshots).',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                dir: { type: 'string', description: 'Local directory to save into; defaults to the plugin screenshotDir.' },
+                name: { type: 'string', description: 'Basename for the PNG; defaults to <serial>-<epoch>.png.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            return captureScreenshot(ctx, cfg, exec.signal, args, screenshotDir);
+        },
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-adb",
-  "version": "1.4.0",
-  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, condition waits, operation ledger w/ rollback, web device panel (autocomplete, live logcat, profiler)",
+  "version": "1.5.0",
+  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, condition waits, operation ledger w/ rollback, screenshots, web device panel (autocomplete, live logcat, profiler)",
   "type": "module",
   "main": "lib/index.js",
   "exports": {