dsh-adb 1.6.1 → 1.7.0

package/README.md

@@ -16,7 +16,7 @@ Or install directly from GitHub: `dsh plugin --profile web add github:SamXiaBing
 
 ## Web device panel (v1.1.0)
 
-A "设备" tab 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** (设备体检: 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).
+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
 
@@ -44,6 +44,7 @@ Topics: `dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `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 |
 | `adb_watch_crash` | Watch the crash buffer for NEW real crashes (foreground poll or background job; boot markers ignored; `matched:false` on timeout) — the first link of the monitor→capture→attribute chain |
+| `adb_patrol_check` | One-click patrol: crash scan (real vs. boot markers) + perf vs. the latest stored baseline (regressions beyond a threshold) + battery/temperature/storage → compact verdict (`ok`/`attention`) with concrete issues; report persisted under `<reportDir>/patrol`. `compareToLast:true` attaches a delta vs. the previous stored patrol (new/gone crashes, worsening regressions, verdict transition). Fail-closed: a section that cannot be collected is itself an issue. No baseline → comparison skipped with a note; omit `package` → the perf section is skipped. Schedule it unattended with dsh-automation — see [docs/SCHEDULED-PATROL.md](docs/SCHEDULED-PATROL.md) |
 
 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.
 
@@ -133,12 +134,12 @@ npm pack --dry-run     # verify publish contents (lib/ + cordis.patch.yml)
 
 ## Project Docs (bilingual; for AI agents & contributors)
 
-- [docs/AGENTS.md](docs/AGENTS.md) / [docs/AGENTS.en.md](docs/AGENTS.en.md) — read first: purpose, rules, commands, environment facts, doc map
-- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) / [docs/REQUIREMENTS.en.md](docs/REQUIREMENTS.en.md) — purpose / scope / non-goals / acceptance criteria
-- [docs/TESTING.md](docs/TESTING.md) / [docs/TESTING.en.md](docs/TESTING.en.md) — testing philosophy, three test layers, E2E steps, regression checklist
-- [docs/DEVELOPMENT-LOG.md](docs/DEVELOPMENT-LOG.md) / [docs/DEVELOPMENT-LOG.en.md](docs/DEVELOPMENT-LOG.en.md) — timeline, fixed-bug lessons, environment & ecosystem notes
-- [docs/ROADMAP.md](docs/ROADMAP.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)
-- [PLAN.md](PLAN.md) / [PLAN.en.md](PLAN.en.md) — milestones & backlog
+- [docs/AGENTS.md](docs/AGENTS.md) / [docs/AGENTS.zh-CN.md](docs/AGENTS.zh-CN.md) — read first: purpose, rules, commands, environment facts, doc map
+- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) / [docs/REQUIREMENTS.zh-CN.md](docs/REQUIREMENTS.zh-CN.md) — purpose / scope / non-goals / acceptance criteria
+- [docs/TESTING.md](docs/TESTING.md) / [docs/TESTING.zh-CN.md](docs/TESTING.zh-CN.md) — testing philosophy, three test layers, E2E steps, regression checklist
+- [docs/ROADMAP.md](docs/ROADMAP.md) / [docs/ROADMAP.zh-CN.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.md) / [docs/SCHEDULED-PATROL.zh-CN.md](docs/SCHEDULED-PATROL.zh-CN.md) — run the patrol unattended on a schedule (dsh-automation prompt template + gotchas)
+- [PLAN.md](PLAN.md) / [PLAN.zh-CN.md](PLAN.zh-CN.md) — milestones & backlog
 
 ## License
 

package/README.zh-CN.md

@@ -44,6 +44,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_operation_ledger` | 操作回滚台账（record/list/rollback）：追加记录安装/推送等操作，查询历史，或回滚到最近一次成功安装的 APK（`adb install -r`）；落盘 `operations.json` —— agent 自主改设备的信任基础 |
 | `adb_screenshot` | 截图落盘 PNG（screencap → pull），返回路径/字节数/像素尺寸 —— 崩溃现场、UI 状态、测试前后对比的持久证据 |
 | `adb_watch_crash` | 崩溃看门狗：监控 crash buffer 的**新**真实崩溃（前台轮询或后台 job；启动标记不算；超时返回 `matched:false`）—— 「盯崩溃→采集→归因」链第一环 |
+| `adb_patrol_check` | 一键巡检：崩溃扫描（真实 vs 启动标记）+ 性能 vs 最近基线（超阈值的回归）+ 电池/温度/存储 → 紧凑结论（`ok`/`attention`）+ 具体问题列表；报告落盘到 `<reportDir>/patrol`。`compareToLast:true` 附上与上次巡检的 delta（新增/消失崩溃、回归恶化、结论变化）。fail-closed：采不到的分区本身就是问题。无基线 → 跳过对比并提示；不传 `package` → 跳过性能整节。配合 dsh-automation 无人值守定时跑——见 [docs/SCHEDULED-PATROL.zh-CN.md](docs/SCHEDULED-PATROL.zh-CN.md) |
 
 错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
 
@@ -135,12 +136,12 @@ npm pack --dry-run     # 校验发布包内容（lib/ + cordis.patch.yml）
 
 ## 项目文档（双语，供 AI 对话/协作者参考）
 
-- [docs/AGENTS.md](docs/AGENTS.md) / [docs/AGENTS.en.md](docs/AGENTS.en.md) — 进项目先读：定位、铁律、命令、环境事实、文档地图
-- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) / [docs/REQUIREMENTS.en.md](docs/REQUIREMENTS.en.md) — 目的/范围/非目标/验收标准
-- [docs/TESTING.md](docs/TESTING.md) / [docs/TESTING.en.md](docs/TESTING.en.md) — 测试哲学（提交即测）、三层测试方法、E2E 步骤、回归清单
-- [docs/DEVELOPMENT-LOG.md](docs/DEVELOPMENT-LOG.md) / [docs/DEVELOPMENT-LOG.en.md](docs/DEVELOPMENT-LOG.en.md) — 进度时间线、4 个已修复 bug 教训、环境/生态经验
-- [docs/ROADMAP.md](docs/ROADMAP.md) — harness×adb 协同功能路线图（诊断报告/崩溃归因/截图视觉/台架自动化测试/等待原语/审批/多设备对比/定时巡检/回滚台账）
-- [PLAN.md](PLAN.md) / [PLAN.en.md](PLAN.en.md) — 里程碑与待办
+- [docs/AGENTS.md](docs/AGENTS.md) / [docs/AGENTS.zh-CN.md](docs/AGENTS.zh-CN.md) — 进项目先读：定位、铁律、命令、环境事实、文档地图
+- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) / [docs/REQUIREMENTS.zh-CN.md](docs/REQUIREMENTS.zh-CN.md) — 目的/范围/非目标/验收标准
+- [docs/TESTING.md](docs/TESTING.md) / [docs/TESTING.zh-CN.md](docs/TESTING.zh-CN.md) — 测试哲学（提交即测）、三层测试方法、E2E 步骤、回归清单
+- [docs/ROADMAP.md](docs/ROADMAP.md) / [docs/ROADMAP.zh-CN.md](docs/ROADMAP.zh-CN.md) — harness×adb 协同功能路线图（诊断报告/崩溃归因/截图视觉/台架自动化测试/等待原语/审批/多设备对比/定时巡检/回滚台账）
+- [docs/SCHEDULED-PATROL.md](docs/SCHEDULED-PATROL.md) / [docs/SCHEDULED-PATROL.zh-CN.md](docs/SCHEDULED-PATROL.zh-CN.md) — 用 dsh-automation 定时无人值守巡检（prompt 模板 + 运维注意）
+- [PLAN.md](PLAN.md) / [PLAN.zh-CN.md](PLAN.zh-CN.md) — 里程碑与待办
 
 ## License
 

package/lib/index.js

@@ -12,6 +12,7 @@ import { registerWaitTool } from './tools/wait.js';
 import { registerOperationLedgerTool } from './tools/operation-ledger.js';
 import { registerScreenshotTool } from './tools/screenshot.js';
 import { registerWatchCrashTool } from './tools/watch-crash.js';
+import { registerPatrolTool } from './tools/patrol.js';
 import { registerRpc } from './rpc.js';
 import { registerSkills } from './skill.js';
 export const name = 'dsh-adb';
@@ -42,10 +43,11 @@ export function apply(ctx, config) {
     registerOperationLedgerTool(ctx, cfg, baselineDir);
     registerScreenshotTool(ctx, cfg, screenshotDir);
     registerWatchCrashTool(ctx, cfg);
+    registerPatrolTool(ctx, cfg, `${reportDir.replace(/\\/g, '/')}/patrol`, baselineDir);
     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: 14 tools + web device panel rpc');
+    ctx.logger.info('[dsh-adb] loaded: 15 tools + web device panel rpc');
 }

package/lib/patrol-store.d.ts

@@ -0,0 +1,19 @@
+import type { PatrolReport } from './patrol.js';
+/**
+ * Patrol report store: one JSON per patrol under `<reportDir>/patrol`.
+ * Kept in a subdirectory of the device-report dir so the existing device
+ * report listing (one readdir, non-recursive) never mixes the two report
+ * kinds. Filename: `patrol-<safeSerial>--<epoch-ms>.json`.
+ */
+export interface StoredPatrolMeta {
+    id: string;
+    collectedAt: string;
+    serial: string;
+    label?: string;
+    verdict: string;
+    file: string;
+}
+export declare function patrolFileFor(serial: string): string;
+export declare function listPatrolReports(dir: string): StoredPatrolMeta[];
+export declare function savePatrolReport(dir: string, report: PatrolReport): StoredPatrolMeta;
+export declare function loadPatrolReport(dir: string, file: string): PatrolReport;

package/lib/patrol-store.js

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FILE_PATTERN = /^patrol-(.+)--(\d+)\.json$/;
+function parseMeta(file) {
+    const match = FILE_PATTERN.exec(file);
+    if (match === null)
+        return undefined;
+    return { id: match[2], collectedAt: '', serial: match[1], file, verdict: '' };
+}
+export function patrolFileFor(serial) {
+    const safeSerial = serial.replace(/[^A-Za-z0-9._-]/g, '_');
+    return `patrol-${safeSerial}--${Date.now()}.json`;
+}
+export function listPatrolReports(dir) {
+    if (!existsSync(dir))
+        return [];
+    const metas = [];
+    for (const name of readdirSync(dir)) {
+        const meta = parseMeta(name);
+        if (meta !== undefined)
+            metas.push(meta);
+    }
+    // Newest first by epoch id.
+    return metas.sort((a, b) => (Number(a.id) < Number(b.id) ? 1 : -1));
+}
+export function savePatrolReport(dir, report) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const file = patrolFileFor(report.serial);
+        writeFileSync(join(dir, file), JSON.stringify(report, null, 2), 'utf8');
+        return {
+            id: String(Date.now()),
+            collectedAt: report.collectedAt,
+            serial: report.serial,
+            ...(report.label !== undefined ? { label: report.label } : {}),
+            verdict: report.verdict,
+            file,
+        };
+    }
+    catch (error) {
+        throw new Error(`patrol store unwritable at ${dir}: ${describe(error)}`);
+    }
+}
+export function loadPatrolReport(dir, file) {
+    try {
+        const raw = readFileSync(join(dir, file), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || parsed.kind !== 'patrol' || !Array.isArray(parsed.errors) || typeof parsed.collectedAt !== 'string') {
+            throw new Error('unexpected shape');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`patrol store unreadable at ${join(dir, file)}: ${describe(error)}`);
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/patrol.d.ts

@@ -0,0 +1,169 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from './adb.js';
+import { type BaselineEntry, type FieldDiff } from './baseline.js';
+import { type PerfSnapshot } from './tools/perf.js';
+import { parseBattery } from './parsers/perf.js';
+/**
+ * One-click device patrol ("巡检"): crash scan + perf baseline comparison +
+ * device essentials in one structured report the agent (or a scheduled task)
+ * can reason from. Evidence → signal again: crash counts are classified (real
+ * crashes vs. boot markers), perf diffs split into regressions / improvements
+ * / stable, and a compact verdict drives attention.
+ *
+ * LLM-free by design: the patrol report is the input a future attribution
+ * step (ROADMAP ②) will consume, but nothing here needs a model.
+ */
+export type PatrolVerdict = 'ok' | 'attention';
+export interface PatrolCrashSection {
+    total: number;
+    realCrashCount: number;
+    bootMarkerCount: number;
+    otherCount: number;
+    /** Newest real crashes first (time/pid/tag/message only, no stacks). */
+    recent: Array<{
+        time: string;
+        pid: string;
+        tag: string;
+        message: string;
+    }>;
+}
+export interface PatrolPerfSection {
+    package: string;
+    /** Baseline metadata, or null when the device has no stored baseline yet. */
+    baseline: {
+        id: string;
+        label: string;
+        createdAt: string;
+        tags: string[];
+    } | null;
+    note?: string;
+    regressions: FieldDiff[];
+    improvements: FieldDiff[];
+    stableCount: number;
+}
+export interface PatrolDeviceSection {
+    battery?: ReturnType<typeof parseBattery>;
+    storage?: {
+        lines: number;
+        truncated: boolean;
+        excerpt: string;
+    };
+}
+export interface PatrolReport {
+    kind: 'patrol';
+    collectedAt: string;
+    serial: string;
+    label?: string;
+    verdict: PatrolVerdict;
+    lines: string[];
+    issues: string[];
+    crash?: PatrolCrashSection;
+    perf?: PatrolPerfSection;
+    device?: PatrolDeviceSection;
+    /** Delta vs. the previous stored patrol report; present when compareToLast is set and a previous report exists. */
+    delta?: PatrolDelta;
+    errors: Array<{
+        section: string;
+        message: string;
+    }>;
+}
+/** Change block vs. the previous patrol report (pure data, unit-tested). */
+export interface PatrolDelta {
+    /** Previous report the comparison ran against. */
+    comparedTo: {
+        collectedAt: string;
+        verdict: string;
+        label?: string;
+    };
+    /** Verdict transition; 'same' when unchanged. */
+    verdictChange: 'same' | 'worse' | 'better';
+    /** Crash signatures (time|pid|tag|message) seen now but not last time. */
+    newCrashes: Array<{
+        time: string;
+        pid: string;
+        tag: string;
+        message: string;
+    }>;
+    /** Crash signatures seen last time but not now (resolved/repaired). */
+    goneCrashes: Array<{
+        time: string;
+        pid: string;
+        tag: string;
+        message: string;
+    }>;
+    /** Regression fields that persisted and got worse (percent moved further up). */
+    worseningRegressions: Array<{
+        field: string;
+        label: string;
+        from: number;
+        to: number;
+    }>;
+    /** Regression fields seen last time that are gone now. */
+    resolvedRegressions: string[];
+    /** Human/agent-readable one-liners summarizing the delta. */
+    lines: string[];
+}
+export interface CollectPatrolArgs {
+    serial?: string;
+    /** Enables the perf comparison; omitted → the perf section is skipped entirely. */
+    package?: string;
+    label?: string;
+    /** Relative threshold (%) beyond which a diff counts as a regression/improvement; default 5. */
+    thresholdPercent?: number;
+    /** Max recent real crashes listed; default 5. */
+    crashTail?: number;
+    /**
+     * Compare against the most recent stored patrol report for this device
+     * (excluding the one being written now) and attach the delta block.
+     */
+    compareToLast?: boolean;
+}
+export interface ClassifiedDiffs {
+    regressions: FieldDiff[];
+    improvements: FieldDiff[];
+    stable: FieldDiff[];
+}
+/**
+ * Split a numeric diff into regressions / improvements / stable. A field with
+ * no percentage (from === 0) falls back to its absolute delta: any increase
+ * from zero on a higher-is-worse field is a regression (e.g. janky 0 → 5).
+ */
+export declare function classifyDiffs(diffs: FieldDiff[], thresholdPercent?: number): ClassifiedDiffs;
+/**
+ * Compact patrol verdict: crash counts + perf regressions + battery
+ * essentials → verdict + human/agent-readable lines + concrete issues.
+ */
+export declare function buildPatrolSummary(parts: {
+    crash?: PatrolCrashSection;
+    perf?: PatrolPerfSection;
+    device?: PatrolDeviceSection;
+    errors: Array<{
+        section: string;
+        message: string;
+    }>;
+}): {
+    verdict: PatrolVerdict;
+    lines: string[];
+    issues: string[];
+};
+/**
+ * Compute the delta block against the previous stored patrol report. Pure:
+ * both reports are inputs, so the store wiring stays in the tool layer.
+ */
+export declare function diffAgainstPrevious(current: PatrolReport, previous: PatrolReport): PatrolDelta;
+/** Compose the perf section from a baseline entry and the current snapshot. */
+export declare function buildPerfSection(packageName: string, input: {
+    baseline: BaselineEntry | undefined;
+    current: PerfSnapshot;
+} | undefined, thresholdPercent: number): PatrolPerfSection | undefined;
+export interface PatrolBaselineHooks {
+    /** Look up the latest baseline for device+package (wired to the baseline store). */
+    latestBaseline: (device: string, pkg: string) => BaselineEntry | undefined;
+    /**
+     * Most recent stored patrol report for this device, excluding the one being
+     * collected now (the store wires this to listPatrolReports/loadPatrolReport).
+     */
+    previousPatrol?: (device: string) => PatrolReport | undefined;
+}
+/** Collect the patrol report with per-section degradation. */
+export declare function collectPatrol(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: CollectPatrolArgs, hooks: PatrolBaselineHooks): Promise<PatrolReport>;

package/lib/patrol.js

@@ -0,0 +1,297 @@
+import { classifyFailure, runAdb } from './adb.js';
+import { classifyCrashBuffer } from './report.js';
+import { diffSnapshots } from './baseline.js';
+import { capturePerfSnapshot } from './tools/perf.js';
+import { parseBattery } from './parsers/perf.js';
+import { parseLogcat } from './parsers/logcat.js';
+// ---- Pure helpers (unit-tested) ----
+/** Which direction is "worse" per diff field (mirrors baseline.ts DIFF_FIELDS). */
+const HIGHER_IS_WORSE = new Set([
+    'meminfo.totalPssKb',
+    'meminfo.totalRssKb',
+    'meminfo.javaHeapKb',
+    'meminfo.nativeHeapKb',
+    'meminfo.graphicsKb',
+    'gfxinfo.totalFrames',
+    'gfxinfo.jankyFrames',
+    'gfxinfo.jankyPercent',
+    'gfxinfo.percentile50Ms',
+    'gfxinfo.percentile90Ms',
+    'gfxinfo.percentile95Ms',
+    'gfxinfo.percentile99Ms',
+    'gfxinfo.missedVsync',
+    'battery.temperatureC',
+]);
+const LOW_BATTERY_PERCENT = 15;
+const HIGH_BATTERY_TEMP_C = 45;
+/**
+ * Split a numeric diff into regressions / improvements / stable. A field with
+ * no percentage (from === 0) falls back to its absolute delta: any increase
+ * from zero on a higher-is-worse field is a regression (e.g. janky 0 → 5).
+ */
+export function classifyDiffs(diffs, thresholdPercent = 5) {
+    const regressions = [];
+    const improvements = [];
+    const stable = [];
+    for (const diff of diffs) {
+        const higherWorse = HIGHER_IS_WORSE.has(diff.field);
+        const percent = diff.deltaPercent;
+        if (percent === undefined) {
+            // from === 0: judge by the absolute delta alone.
+            if (diff.delta === undefined || diff.delta === 0) {
+                stable.push(diff);
+            }
+            else if (higherWorse) {
+                ;
+                (diff.delta > 0 ? regressions : improvements).push(diff);
+            }
+            else {
+                ;
+                (diff.delta < 0 ? regressions : improvements).push(diff);
+            }
+            continue;
+        }
+        if (percent > thresholdPercent)
+            (higherWorse ? regressions : improvements).push(diff);
+        else if (percent < -thresholdPercent)
+            (higherWorse ? improvements : regressions).push(diff);
+        else
+            stable.push(diff);
+    }
+    return { regressions, improvements, stable };
+}
+function crashSectionOf(summary, tail) {
+    return {
+        total: summary.total,
+        realCrashCount: summary.realCrashCount,
+        bootMarkerCount: summary.bootMarkerCount,
+        otherCount: summary.otherCount,
+        recent: summary.chains.slice(-tail).reverse().map((chain) => ({
+            time: chain.signature.time,
+            pid: chain.signature.pid,
+            tag: chain.signature.tag,
+            message: chain.signature.message,
+        })),
+    };
+}
+/**
+ * Compact patrol verdict: crash counts + perf regressions + battery
+ * essentials → verdict + human/agent-readable lines + concrete issues.
+ */
+export function buildPatrolSummary(parts) {
+    const lines = [];
+    const issues = [];
+    const crash = parts.crash;
+    if (crash) {
+        if (crash.realCrashCount > 0) {
+            const newest = crash.recent[0];
+            issues.push(`真实崩溃 ${crash.realCrashCount} 起${newest !== undefined ? `（最新 ${newest.time} ${newest.tag}: ${newest.message.slice(0, 60)}）` : ''}`);
+            lines.push(`崩溃：${crash.realCrashCount} 真实 + ${crash.bootMarkerCount} 启动标记 + ${crash.otherCount} 其他（共 ${crash.total}）`);
+        }
+        else {
+            lines.push(`崩溃：无真实崩溃（${crash.bootMarkerCount} 启动标记 + ${crash.otherCount} 其他，共 ${crash.total}）`);
+        }
+    }
+    const perf = parts.perf;
+    if (perf) {
+        if (perf.baseline === null) {
+            lines.push(`性能：无 ${perf.package} 基线，跳过对比（用 adb_perf_baseline save 先存一次）`);
+        }
+        else {
+            const reg = perf.regressions.map((d) => `${d.label} ${d.deltaPercent !== undefined ? `${d.deltaPercent > 0 ? '+' : ''}${d.deltaPercent.toFixed(1)}%` : `${d.delta ?? ''}`}`);
+            const imp = perf.improvements.length;
+            lines.push(`性能 vs ${perf.baseline.label}：${reg.length} 回归 / ${imp} 改善 / ${perf.stableCount} 持平${reg.length > 0 ? ` — ${reg.join(', ')}` : ''}`);
+            if (reg.length > 0)
+                issues.push(`性能回归（vs ${perf.baseline.label}）：${reg.join(', ')}`);
+        }
+    }
+    const battery = parts.device?.battery;
+    if (battery) {
+        const bits = [];
+        if (battery.levelPercent !== undefined)
+            bits.push(`${battery.levelPercent}%`);
+        if (battery.temperatureC !== undefined)
+            bits.push(`${battery.temperatureC}°C`);
+        lines.push(`电池：${bits.join(' ') || '无数据'}`);
+        if (battery.levelPercent !== undefined && battery.levelPercent <= LOW_BATTERY_PERCENT)
+            issues.push(`电量低（${battery.levelPercent}%）`);
+        if (battery.temperatureC !== undefined && battery.temperatureC >= HIGH_BATTERY_TEMP_C)
+            issues.push(`电池高温（${battery.temperatureC}°C）`);
+    }
+    // Fail-closed: a section we could not collect is itself a patrol finding —
+    // "couldn't check the crash buffer" must not read as "no crashes".
+    for (const error of parts.errors) {
+        lines.push(`⚠ ${error.section} 采集失败：${error.message.slice(0, 80)}`);
+        issues.push(`${error.section} 采集失败（${error.message.slice(0, 60)}）`);
+    }
+    const verdict = issues.length > 0 ? 'attention' : 'ok';
+    return { verdict, lines, issues };
+}
+// ---- Delta vs. the previous patrol report (pure, unit-tested) ----
+function crashSignatureKey(entry) {
+    return `${entry.time}|${entry.pid}|${entry.tag}|${entry.message}`;
+}
+const VERDICT_RANK = { ok: 0, attention: 1 };
+/**
+ * Compute the delta block against the previous stored patrol report. Pure:
+ * both reports are inputs, so the store wiring stays in the tool layer.
+ */
+export function diffAgainstPrevious(current, previous) {
+    const prevCrashes = new Map();
+    for (const entry of previous.crash?.recent ?? [])
+        prevCrashes.set(crashSignatureKey(entry), entry);
+    const nowCrashes = new Map();
+    for (const entry of current.crash?.recent ?? [])
+        nowCrashes.set(crashSignatureKey(entry), entry);
+    const newCrashes = [...nowCrashes.entries()].filter(([key]) => !prevCrashes.has(key)).map(([, entry]) => entry);
+    const goneCrashes = [...prevCrashes.entries()].filter(([key]) => !nowCrashes.has(key)).map(([, entry]) => entry);
+    const prevRegressions = new Map();
+    for (const diff of previous.perf?.regressions ?? []) {
+        if (diff.deltaPercent !== undefined)
+            prevRegressions.set(diff.field, diff.deltaPercent);
+    }
+    const nowRegressions = new Map();
+    for (const diff of current.perf?.regressions ?? []) {
+        if (diff.deltaPercent !== undefined)
+            nowRegressions.set(diff.field, diff.deltaPercent);
+    }
+    const worseningRegressions = [];
+    for (const [field, nowPercent] of nowRegressions) {
+        const prevPercent = prevRegressions.get(field);
+        if (prevPercent !== undefined && nowPercent > prevPercent) {
+            worseningRegressions.push({ field, label: current.perf?.regressions.find((d) => d.field === field)?.label ?? field, from: prevPercent, to: nowPercent });
+        }
+    }
+    const resolvedRegressions = [...prevRegressions.keys()].filter((field) => !nowRegressions.has(field));
+    const rankDelta = VERDICT_RANK[current.verdict] - VERDICT_RANK[previous.verdict];
+    const verdictChange = rankDelta > 0 ? 'worse' : rankDelta < 0 ? 'better' : 'same';
+    const lines = [];
+    if (verdictChange !== 'same')
+        lines.push(`结论变化：${previous.verdict} → ${current.verdict}（${verdictChange === 'worse' ? '恶化' : '好转'}）`);
+    if (newCrashes.length > 0)
+        lines.push(`新增真实崩溃 ${newCrashes.length} 起（最新 ${newCrashes[0].time} ${newCrashes[0].tag}）`);
+    if (goneCrashes.length > 0)
+        lines.push(`${goneCrashes.length} 起上次崩溃已不在缓冲中`);
+    if (worseningRegressions.length > 0) {
+        lines.push(`回归恶化：${worseningRegressions.map((r) => `${r.label} ${r.from.toFixed(1)}%→${r.to.toFixed(1)}%`).join(', ')}`);
+    }
+    if (resolvedRegressions.length > 0)
+        lines.push(`已缓解回归：${resolvedRegressions.length} 项`);
+    if (lines.length === 0)
+        lines.push('与上次巡检相比无显著变化');
+    return {
+        comparedTo: { collectedAt: previous.collectedAt, verdict: previous.verdict, ...(previous.label !== undefined ? { label: previous.label } : {}) },
+        verdictChange,
+        newCrashes,
+        goneCrashes,
+        worseningRegressions,
+        resolvedRegressions,
+        lines,
+    };
+}
+/** Compose the perf section from a baseline entry and the current snapshot. */
+export function buildPerfSection(packageName, input, thresholdPercent) {
+    if (input === undefined)
+        return undefined;
+    if (input.baseline === undefined) {
+        return {
+            package: packageName,
+            baseline: null,
+            note: 'no baseline for this device+package yet; save one with adb_perf_baseline save',
+            regressions: [],
+            improvements: [],
+            stableCount: 0,
+        };
+    }
+    const classified = classifyDiffs(diffSnapshots(input.baseline.snapshot, input.current), thresholdPercent);
+    return {
+        package: packageName,
+        baseline: {
+            id: input.baseline.id,
+            label: input.baseline.label,
+            createdAt: input.baseline.createdAt,
+            tags: input.baseline.tags ?? [],
+        },
+        regressions: classified.regressions,
+        improvements: classified.improvements,
+        stableCount: classified.stable.length,
+    };
+}
+// ---- Collectors ----
+async function collectCrashScan(ctx, cfg, signal, serial, tail) {
+    const result = await runAdb(ctx, cfg, ['logcat', '-b', 'crash', '-v', 'threadtime', '-d'], { signal, serial, maxBytes: 8 * 1024 * 1024 });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    return crashSectionOf(classifyCrashBuffer(parseLogcat(result.stdout)), tail);
+}
+async function collectBattery(ctx, cfg, signal, serial) {
+    // dumpsys battery is device-global and takes no package argument.
+    const result = await runAdb(ctx, cfg, ['shell', 'dumpsys', 'battery'], { signal, serial });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    return parseBattery(result.stdout);
+}
+function storageExcerpt(text, maxLines) {
+    const lines = text.split(/\r?\n/).filter((line) => line !== '');
+    return { lines: lines.length, truncated: lines.length > maxLines, excerpt: lines.slice(-maxLines).join('\n') };
+}
+async function collectStorage(ctx, cfg, signal, serial) {
+    const result = await runAdb(ctx, cfg, ['shell', 'df'], { signal, serial, maxBytes: 1024 * 1024 });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    return storageExcerpt(result.stdout, 12);
+}
+/** Collect the patrol report with per-section degradation. */
+export async function collectPatrol(ctx, cfg, signal, args, hooks) {
+    const serial = args.serial ?? cfg.defaultSerial;
+    const resolved = serial ?? 'default';
+    const crashTail = args.crashTail !== undefined && args.crashTail > 0 ? Math.floor(args.crashTail) : 5;
+    const threshold = args.thresholdPercent !== undefined && args.thresholdPercent > 0 ? args.thresholdPercent : 5;
+    const report = { kind: 'patrol', collectedAt: new Date().toISOString(), serial: resolved, verdict: 'ok', lines: [], issues: [], errors: [] };
+    if (args.label !== undefined)
+        report.label = args.label;
+    const guard = async (section, collect, assign) => {
+        try {
+            assign(await collect());
+        }
+        catch (error) {
+            report.errors.push({ section, message: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    const perfTask = (async () => {
+        if (args.package === undefined)
+            return undefined;
+        try {
+            const baseline = hooks.latestBaseline(resolved, args.package);
+            const current = await capturePerfSnapshot(ctx, cfg, signal, { package: args.package, serial: args.serial });
+            return buildPerfSection(args.package, { baseline, current }, threshold);
+        }
+        catch (error) {
+            report.errors.push({ section: 'perf', message: error instanceof Error ? error.message : String(error) });
+            return undefined;
+        }
+    })();
+    await Promise.all([
+        guard('crash', () => collectCrashScan(ctx, cfg, signal, serial, crashTail), (v) => { report.crash = v; }),
+        guard('device', () => collectBattery(ctx, cfg, signal, serial), (v) => { report.device = { ...report.device, battery: v }; }),
+        guard('storage', () => collectStorage(ctx, cfg, signal, serial), (v) => { report.device = { ...report.device, storage: v }; }),
+    ]);
+    report.perf = await perfTask;
+    const summary = buildPatrolSummary({ crash: report.crash, perf: report.perf, device: report.device, errors: report.errors });
+    report.verdict = summary.verdict;
+    report.lines = summary.lines;
+    report.issues = summary.issues;
+    if (args.compareToLast === true && hooks.previousPatrol !== undefined) {
+        try {
+            const previous = hooks.previousPatrol(resolved);
+            if (previous !== undefined) {
+                report.delta = diffAgainstPrevious(report, previous);
+                report.lines.push(...report.delta.lines.map((line) => `Δ ${line}`));
+            }
+        }
+        catch (error) {
+            report.errors.push({ section: 'delta', message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return report;
+}

package/lib/tools/patrol.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/**
+ * adb_patrol_check: one-click patrol ("巡检"). Crash scan + perf baseline
+ * comparison + battery/storage essentials in one pass, classified into a
+ * compact verdict (ok/attention) with concrete issues — the report a nightly
+ * scheduled task or a morning "巡检一下" prompt consumes. LLM-free.
+ */
+export declare function registerPatrolTool(ctx: Context, cfg: AdbConfig, patrolDir: string, baselineDir: string): void;

package/lib/tools/patrol.js

@@ -0,0 +1,68 @@
+import { jsonOutput } from '../adb.js';
+import { collectPatrol } from '../patrol.js';
+import { savePatrolReport, listPatrolReports, loadPatrolReport } from '../patrol-store.js';
+import { createStore } from '../baseline.js';
+function publicReport(report, saved) {
+    return {
+        kind: report.kind,
+        collectedAt: report.collectedAt,
+        serial: report.serial,
+        ...(report.label !== undefined ? { label: report.label } : {}),
+        verdict: report.verdict,
+        lines: report.lines,
+        issues: report.issues,
+        ...(report.crash !== undefined ? { crash: report.crash } : {}),
+        ...(report.perf !== undefined ? { perf: report.perf } : {}),
+        ...(report.device !== undefined ? { device: report.device } : {}),
+        ...(report.delta !== undefined ? { delta: report.delta } : {}),
+        errors: report.errors,
+        ...(saved !== undefined ? { savedTo: saved.file } : {}),
+    };
+}
+/**
+ * adb_patrol_check: one-click patrol ("巡检"). Crash scan + perf baseline
+ * comparison + battery/storage essentials in one pass, classified into a
+ * compact verdict (ok/attention) with concrete issues — the report a nightly
+ * scheduled task or a morning "巡检一下" prompt consumes. LLM-free.
+ */
+export function registerPatrolTool(ctx, cfg, patrolDir, baselineDir) {
+    ctx.tools.register({
+        name: 'adb_patrol_check',
+        description: 'One-click device patrol: scan the crash buffer (classified into real crashes vs. boot markers), compare current perf against the latest stored baseline for a package (regressions/improvements beyond a threshold), check battery/temperature/storage, and persist a structured patrol report. Returns a compact verdict (ok/attention) with concrete issues — reason from it, then drill in with adb_crash_report / adb_perf_baseline compare / adb_device_report as needed. Omit `package` to skip the perf comparison; with no stored baseline the comparison is skipped with a note, not an error. With `compareToLast:true` a delta block is attached: new/gone crashes, worsening regressions, and the verdict transition vs. the previous stored patrol for this device.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                package: { type: 'string', description: 'App package id; when given, the current perf is captured and diffed against the latest stored baseline for this device+package.' },
+                label: { type: 'string', description: 'Optional patrol label, e.g. soak-night-0828.' },
+                thresholdPercent: { type: 'number', description: 'Relative change (%) beyond which a perf diff counts as a regression/improvement; defaults to 5.' },
+                crashTail: { type: 'integer', description: 'Max recent real crashes listed; defaults to 5.' },
+                compareToLast: { type: 'boolean', description: 'Attach a delta vs. the previous stored patrol report for this device (new/gone crashes, worsening regressions, verdict transition); defaults to false.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            const store = createStore(baselineDir);
+            const device = args.serial ?? cfg.defaultSerial ?? 'default';
+            const report = await collectPatrol(ctx, cfg, exec.signal, args, {
+                latestBaseline: (dev, pkg) => store.latest(dev, pkg),
+                previousPatrol: (dev) => {
+                    const metas = listPatrolReports(patrolDir).filter((meta) => meta.serial === dev.replace(/[^A-Za-z0-9._-]/g, '_'));
+                    if (metas.length === 0)
+                        return undefined;
+                    return loadPatrolReport(patrolDir, metas[0].file);
+                },
+            });
+            let saved;
+            try {
+                saved = savePatrolReport(patrolDir, report);
+            }
+            catch {
+                // Persistence is best-effort: the report is still returned to the agent.
+            }
+            void device;
+            return publicReport(report, saved);
+        },
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-adb",
-  "version": "1.6.1",
-  "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, crash watchdog, web device panel (autocomplete, live logcat, profiler)",
+  "version": "1.7.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, crash watchdog, one-click device patrol (scheduled-watchdog ready), web device panel (autocomplete, live logcat, profiler)",
   "type": "module",
   "main": "lib/index.js",
   "exports": {