dsh-adb 1.1.0 → 1.3.0

package/README.md

@@ -16,11 +16,11 @@ 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, and performance snapshot — plus harness synergy: **send any logcat/snapshot 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 "设备" 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).
 
 ## Ecosystem
 
-- ✅ [npm](https://www.npmjs.com/package/dsh-adb) — `dsh-adb` published (latest: 1.0.0)
+- ✅ [npm](https://www.npmjs.com/package/dsh-adb) — `dsh-adb` published (latest: 1.1.0)
 - ✅ [awesome-deepseek-harness#87](https://github.com/0xsline/awesome-deepseek-harness/pull/87) — **merged**
 - ✅ [awesome-dsh-plugin#85](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/85) — **merged**
 - ✅ [awesome-DSH-plugin#29](https://github.com/Alex-Yanggg/awesome-DSH-plugin/pull/29) — **merged**
@@ -39,6 +39,8 @@ Topics: `dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_perf_snapshot` | Structured `dumpsys meminfo / gfxinfo / battery` snapshots (PSS, frame percentiles, jank rate, battery) |
 | `adb_perf_baseline` | Perf regression: save a snapshot as a baseline (label/tags), compare current state and get a numeric diff (PSS, janky %, percentiles), list/delete baselines (stored locally under `baselineDir`) |
 | `adb_crash_report` | One-call crash scene: parsed logcat crash buffer + dropbox excerpt + process state + memory summary |
+| `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 |
 
 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.
 
@@ -61,6 +63,7 @@ Set the `config` block in `cordis.patch.yml` (or a profile patch):
 | `defaultSerial` | Default target device serial | none |
 | `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` |
 
 ## Development
 
@@ -83,6 +86,7 @@ npm pack --dry-run     # verify publish contents (lib/ + cordis.patch.yml)
 - [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
 
 ## License

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [English](README.md) | 简体中文
 
-让 DSH agent 直接操作 Android 设备 / 车机台架：设备发现、结构化 logcat、apk 安装、文件 pull/push、性能快照。面向实车与台架联调场景，业务内通用（不限 Unity、不限具体车机协议）。
+让 DSH agent 直接操作 Android 设备 / 车机台架：设备发现、结构化 logcat、apk 安装、文件 pull/push、性能快照、一键体检。面向实车与台架联调场景，业务内通用（不限 Unity、不限具体车机协议）。
 
 ## 安装
 
@@ -14,13 +14,13 @@ dsh plugin --profile web add dsh-adb
 
 或从 GitHub 直装：`dsh plugin --profile web add github:SamXiaBing/dsh-adb`
 
-## Web 设备面板（v1.0.0）
+## Web 设备面板（v1.2.0）
 
-会话视图页签「设备」（与 chat/轨迹/任务管理并列）：设备列表/状态、按包名的性能快照（内存/帧率/电量）、过滤 logcat 尾部。数据走 Package RPC；需装入 web profile 并重启 GUI 生效。
+会话视图页签「设备」（与 chat/轨迹/任务管理并列）：设备列表/状态、包名下拉自动补全、实时 logcat 窗口（级别/关键字/包名/pid 过滤、暂停/清空/自动滚动）、设备信息卡、进程列表、性能快照、**一键体检**（设备信息 + Top RSS 进程 + 崩溃缓冲 + W/E/F 日志 + 存储用量，落盘到 `reportDir`，可一键发送到对话诊断）。体检报告先做**证据→信号**提炼再交给 agent：崩溃按签名分类（真实崩溃+堆栈链 / MediaTek 启动标记 / 其他）、W/E/F 按 tag 聚合（计数+样本行）、插件自产健康摘要（verdict + issues）——agent 从结论出发而非从 17k 行原始日志出发。harness 协同：logcat/快照/体检报告**一键发送到对话**、面板顶部实时显示 agent 的 adb 操作、注册 **crash-analysis 技能**（`dsh-adb-crash-analysis`）供自动化流水线使用。数据走 Package RPC；需装入 web profile 并重启 GUI 生效（一键重启见 `scripts/restart-web.ps1`）。
 
 ## 生态收录
 
-- ✅ [npm](https://www.npmjs.com/package/dsh-adb) — `dsh-adb` 已发布（latest: 1.0.0）
+- ✅ [npm](https://www.npmjs.com/package/dsh-adb) — `dsh-adb` 已发布（latest: 1.1.0）
 - ✅ [awesome-deepseek-harness#87](https://github.com/0xsline/awesome-deepseek-harness/pull/87) — **已合并**
 - ✅ [awesome-dsh-plugin#85](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/85) — **已合并**
 - ✅ [awesome-DSH-plugin#29](https://github.com/Alex-Yanggg/awesome-DSH-plugin/pull/29) — **已合并**
@@ -39,6 +39,8 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_perf_snapshot` | `dumpsys meminfo / gfxinfo / battery` 结构化快照（PSS/帧率百分位/卡顿率/电量） |
 | `adb_perf_baseline` | 性能回归：快照存基线（label/tags）、与当前状态数值对比（PSS/卡顿率/百分位）、list/delete（本地存储，`baselineDir`） |
 | `adb_crash_report` | 崩溃现场一键采集：crash buffer 解析 + dropbox 摘录 + 进程状态 + 内存摘要 |
+| `adb_device_report` | 一键体检：设备信息 + Top RSS 进程 + 崩溃缓冲（真实崩溃带堆栈/启动标记分类）+ W/E/F 日志按 tag 聚合 + 存储用量 + 健康结论；每节独立降级；落盘到 `reportDir` |
+| `adb_wait_for` | 等待原语：等设备上线 / 启动完成 / 进程出现 / logcat 出现关键字，轮询到预算上限，替代盲目 sleep；超时返回 `matched:false` |
 
 错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
 
@@ -61,6 +63,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `defaultSerial` | 默认设备 serial | 无 |
 | `timeoutMs` | 命令超时 | 30000 |
 | `baselineDir` | `adb_perf_baseline` 基线存储目录 | `~/.dsh/storages/dsh-adb` |
+| `reportDir` | `adb_device_report` 体检报告存储目录 | `<baselineDir>/reports` |
 
 ## 开发
 
@@ -85,6 +88,7 @@ npm pack --dry-run     # 校验发布包内容（lib/ + cordis.patch.yml）
 - [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) — 里程碑与待办
 
 ## License

package/client.js

@@ -55,6 +55,59 @@ function formatSnapshotBlock(snapshot) {
   return ['以下是从设备面板抓取的性能快照，请分析：', ...rows.map((r) => '- ' + r)].join('\n')
 }
 
+/** Format a one-click health report into a send-to-conversation text block. */
+function formatReportBlock(report) {
+  if (!report || typeof report !== 'object') return '（无体检报告数据）'
+  const lines = []
+  const health = report.health
+  const d = report.device
+  if (d) {
+    const parts = [d.model, d.manufacturer, `Android ${d.release ?? '?'}`].filter(Boolean)
+    if (d.sdk) parts.push(`API ${d.sdk}`)
+    if (d.resolution) parts.push(d.resolution)
+    if (d.memTotalKb) parts.push(`内存 ${Math.round(d.memTotalKb / 1024)}MB`)
+    lines.push(`设备：${parts.join(' · ') || report.serial}`)
+  } else {
+    lines.push(`设备：${report.serial || '未知'}`)
+  }
+  if (health) {
+    lines.push(`体检结论：${health.verdict === 'attention' ? '需关注' : '正常'}`)
+    for (const line of health.lines) lines.push(`- ${line}`)
+    if (health.issues && health.issues.length > 0) {
+      lines.push('关注项：')
+      for (const issue of health.issues) lines.push(`- ⚠ ${issue}`)
+    }
+  } else {
+    const cb = report.crashBuffer
+    const lg = report.logcat
+    lines.push(`崩溃缓冲：${cb ? cb.total : 0} 条`)
+    lines.push(`W/E/F 日志：${lg ? lg.total : 0} 条`)
+  }
+  if (Array.isArray(report.errors) && report.errors.length > 0) {
+    lines.push(`采集失败：${report.errors.map((e) => `${e.section}: ${e.message}`).join('; ')}`)
+  }
+  lines.push(`采集时间：${report.collectedAt ?? '未知'}`)
+  // Evidence: only real crash chains, not the whole (mostly boot-marker) buffer.
+  if (report.crashBuffer && report.crashBuffer.chains && report.crashBuffer.chains.length > 0) {
+    lines.push('', '真实崩溃堆栈：')
+    for (const chain of report.crashBuffer.chains) {
+      lines.push('```log',
+        `${chain.signature.time} ${chain.signature.pid} ${chain.signature.tid} ${chain.signature.level} ${chain.signature.tag}: ${chain.signature.message}`,
+        ...(chain.following || []).map((e) => `${e.time} ${e.pid} ${e.tid} ${e.level} ${e.tag}: ${e.message}`),
+        '```')
+    }
+  }
+  // Evidence: top logcat noise sources with one sample each.
+  if (report.logcat && report.logcat.byTag && report.logcat.byTag.length > 0) {
+    lines.push('', 'W/E/F 主要来源（样本）：')
+    for (const agg of report.logcat.byTag.slice(0, 5)) {
+      const s = agg.sample
+      lines.push(`- ${agg.tag}(${agg.level}) ×${agg.count}：${s.time} ${s.pid} ${s.tid} ${s.tag}: ${s.message}`)
+    }
+  }
+  return ['以下是从设备面板生成的一键体检报告，请结合 dsh-adb-crash-analysis 技能分析设备健康状态：', ...lines].join('\n')
+}
+
 /** Panel dictionary: zh is the key-set source of truth, en mirrors it. */
 const DICTIONARY = {
   zh: {
@@ -85,6 +138,11 @@ const DICTIONARY = {
     'memPss': '内存 PSS (KB)', 'memRss': '内存 RSS (KB)', 'javaHeap': 'Java Heap (KB)', 'nativeHeap': 'Native Heap (KB)',
     'frames': '总帧数', 'janky': '卡顿帧 / %', 'p50p90': 'P50/P90 (ms)', 'p95p99': 'P95/P99 (ms)',
     'battery': '电量', 'temp': '温度 (°C)', 'pkg': '包=', 'pid': 'pid=',
+    'report': '一键体检', 'reportRunning': '采集中…', 'reportDevice': '设备',
+    'reportCrash': '崩溃缓冲', 'reportLogcat': 'W/E/F 日志', 'reportProcesses': 'Top 进程',
+    'reportErrors': '采集失败', 'reportTime': '采集时间', 'reportSaved': '已保存',
+    'reportVerdict': '体检结论', 'reportVerdictOk': '正常', 'reportVerdictAttention': '需关注',
+    'reportSignals': '关注项',
   },
   en: {
     'panel.title': 'ADB Devices',
@@ -114,6 +172,11 @@ const DICTIONARY = {
     'memPss': 'PSS (KB)', 'memRss': 'RSS (KB)', 'javaHeap': 'Java Heap (KB)', 'nativeHeap': 'Native Heap (KB)',
     'frames': 'Total frames', 'janky': 'Janky / %', 'p50p90': 'P50/P90 (ms)', 'p95p99': 'P95/P99 (ms)',
     'battery': 'Battery', 'temp': 'Temp (°C)', 'pkg': 'pkg=', 'pid': 'pid=',
+    'report': 'Health report', 'reportRunning': 'collecting…', 'reportDevice': 'Device',
+    'reportCrash': 'Crash buffer', 'reportLogcat': 'W/E/F logs', 'reportProcesses': 'Top processes',
+    'reportErrors': 'Collection errors', 'reportTime': 'Collected at', 'reportSaved': 'Saved',
+    'reportVerdict': 'Health', 'reportVerdictOk': 'OK', 'reportVerdictAttention': 'needs attention',
+    'reportSignals': 'Concerns',
   },
 }
 
@@ -149,6 +212,7 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
           processList: (payload) => call('processList', payload),
           logcatDelta: (payload) => call('logcatDelta', payload),
           perfSnapshot: (payload) => call('perfSnapshot', payload),
+          deviceReport: (payload) => call('deviceReport', payload),
         }
       }
 
@@ -235,7 +299,7 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
 
         const selectDevice = (device) => {
           actions.setSelected(device)
-          actions.setInfo(null); actions.setSnapshot(null); actions.setProcesses([])
+          actions.setInfo(null); actions.setSnapshot(null); actions.setReport(null); actions.setProcesses([])
           actions.clearLog()
           setBusy(true); actions.setError(null)
           Promise.all([
@@ -263,6 +327,16 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
             .finally(() => setBusy(false))
         }
 
+        const runReport = () => {
+          const device = stateRef.current.selected
+          if (!device) return
+          setBusy(true); actions.setError(null)
+          runtime.deviceReport({ serial: device.serial })
+            .then(actions.setReport)
+            .catch(fail)
+            .finally(() => setBusy(false))
+        }
+
         const applyPackageFilter = (name) => {
           actions.setLogPkg(name)
           actions.clearLog()
@@ -319,6 +393,33 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
           ? [[t('model'), st.info.model], [t('manufacturer'), st.info.manufacturer], [t('android'), st.info.release], [t('api'), st.info.sdk], [t('resolution'), st.info.resolution], [t('memTotal'), st.info.memTotalKb ? `${Math.round(st.info.memTotalKb / 1024)} MB` : undefined]].filter((r) => r[1] !== undefined && r[1] !== null)
           : []
 
+        const reportRows = []
+        if (st.report) {
+          const r = st.report
+          if (r.health) {
+            reportRows.push([t('reportVerdict'), r.health.verdict === 'attention' ? t('reportVerdictAttention') : t('reportVerdictOk')])
+            if (r.health.issues && r.health.issues.length > 0) {
+              reportRows.push([t('reportSignals'), r.health.issues.length])
+            }
+          }
+          if (r.device) {
+            const parts = [r.device.model, r.device.release, r.device.sdk ? `API ${r.device.sdk}` : r.device.sdk].filter(Boolean)
+            reportRows.push([t('reportDevice'), parts.join(' · ')])
+          }
+          if (r.crashBuffer) {
+            const cb = r.crashBuffer
+            reportRows.push([t('reportCrash'), `${cb.realCrashCount} 真实${cb.bootMarkerCount > 0 ? ` + ${cb.bootMarkerCount} 启动标记` : ''} / ${cb.total} 条`])
+          }
+          if (r.logcat && r.logcat.byTag && r.logcat.byTag.length > 0) {
+            const top = r.logcat.byTag[0]
+            reportRows.push([t('reportLogcat'), `${r.logcat.total} 条 · ${top.tag} ×${top.count}`])
+          }
+          if (Array.isArray(r.errors) && r.errors.length > 0) {
+            reportRows.push([t('reportErrors'), r.errors.length])
+          }
+          if (r.savedTo) reportRows.push([t('reportSaved'), r.savedTo])
+        }
+
         const pidsLabel = st.logPids.length > 0 ? ` · ${t('pid')}${st.logPids.join(',')}` : ''
         const statusText = `${t('shownCount').replace('{n}', String(st.logEntries.length))}${st.logPkg ? ` · ${t('pkg')}${st.logPkg}` : ''}${pidsLabel}${st.logPaused ? ` · ${t('paused')}` : ` · ${t('refreshing')}`}`
 
@@ -351,6 +452,14 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
               h(MetricRows, { rows: infoRows }),
             ),
 
+            h('div', { style: SECTION },
+              h('div', { style: ROW },
+                h('button', { style: BTN, onClick: runReport, disabled: busy }, busy ? t('reportRunning') : t('report')),
+                st.report && h('button', { style: BTN, onClick: () => sendToChat(formatReportBlock(st.report)) }, t('sendToChat')),
+              ),
+              st.report && h('div', { style: { marginTop: 8 } }, h(MetricRows, { rows: reportRows })),
+            ),
+
             h('div', { style: SECTION },
               h('div', { style: ROW },
                 h('label', null, t('package')),
@@ -415,7 +524,7 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
         const panelStore = defineStore({
           init: () => ({
             devices: [], selected: null, info: null, packages: [], pkg: 'com.android.systemui',
-            snapshot: null, processes: [], logEntries: [], logSince: '',
+            snapshot: null, report: null, processes: [], logEntries: [], logSince: '',
             logLevel: 'V', logKeyword: '', logPkg: '', logPids: [], logPaused: false, logAuto: true, error: null,
           }),
           actions: {
@@ -425,6 +534,7 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
             setPackages: (d, v) => { d.packages = v },
             setPkg: (d, v) => { d.pkg = v },
             setSnapshot: (d, v) => { d.snapshot = v },
+            setReport: (d, v) => { d.report = v },
             setProcesses: (d, v) => { d.processes = v },
             setError: (d, v) => { d.error = v },
             appendLog: (d, entries) => {
@@ -464,5 +574,5 @@ if (typeof window !== 'undefined' && typeof window.__ModuleLoader__ === 'object'
     },
   })
 } else if (typeof module !== 'undefined' && module.exports) {
-  module.exports = { formatLogcatBlock, formatSnapshotBlock, extractAdbActivity, nodeArrayOf, DICTIONARY }
+  module.exports = { formatLogcatBlock, formatSnapshotBlock, formatReportBlock, extractAdbActivity, nodeArrayOf, DICTIONARY }
 }

package/lib/index.d.ts

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

package/lib/index.js

@@ -2,11 +2,13 @@ import Schema from 'schemastery';
 import { DEFAULT_BASELINE_DIR } from './baseline.js';
 import { registerDeviceTools } from './tools/devices.js';
 import { registerCrashReportTool } from './tools/crash-report.js';
+import { registerDeviceReportTool } from './tools/device-report.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';
 import { registerPerfBaselineTool } from './tools/perf-baseline.js';
+import { registerWaitTool } from './tools/wait.js';
 import { registerRpc } from './rpc.js';
 import { registerSkills } from './skill.js';
 export const name = 'dsh-adb';
@@ -17,9 +19,11 @@ export const Config = Schema.object({
     defaultSerial: Schema.string().description('默认目标设备 serial'),
     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'),
 });
 export function apply(ctx, config) {
     const cfg = config;
+    const reportDir = config.reportDir ?? `${(config.baselineDir ?? DEFAULT_BASELINE_DIR).replace(/\\/g, '/')}/reports`;
     registerDeviceTools(ctx, cfg);
     registerInstallTool(ctx, cfg);
     registerFileTool(ctx, cfg);
@@ -27,10 +31,12 @@ export function apply(ctx, config) {
     registerPerfTool(ctx, cfg);
     registerPerfBaselineTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
     registerCrashReportTool(ctx, cfg);
+    registerDeviceReportTool(ctx, cfg, reportDir);
+    registerWaitTool(ctx, cfg);
     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));
-    ctx.logger.info('[dsh-adb] loaded: 9 tools + web device panel rpc');
+    ctx.inject(['connection'], (readyCtx) => registerRpc(readyCtx, cfg, reportDir));
+    ctx.logger.info('[dsh-adb] loaded: 11 tools + web device panel rpc');
 }

package/lib/parsers/sysinfo.d.ts

@@ -4,6 +4,8 @@ export declare function parseGetprop(text: string): Record<string, string>;
 export interface ProcessEntry {
     pid: string;
     name: string;
+    /** Resident set size in KB (Android `ps -A` column 4), when numeric. */
+    rss?: number;
 }
 /** Parse `ps -A` output (Android toybox: USER PID PPID VSZ RSS WCHAN ADDR S NAME). */
 export declare function parseProcessList(text: string): ProcessEntry[];

package/lib/parsers/sysinfo.js

@@ -29,13 +29,15 @@ export function parseProcessList(text) {
         if (line === '' || /^USER\s+PID/.test(line))
             continue;
         const parts = line.split(/\s+/);
-        // Android ps: index 1 = PID, last = NAME (comm may be in brackets)
+        // Android ps: index 1 = PID, index 4 = RSS, last = NAME (comm may be in brackets)
         if (parts.length < 2)
             continue;
         const pid = parts[1];
         const name = parts[parts.length - 1];
         if (pid !== undefined && name !== undefined && /^\d+$/.test(pid)) {
-            entries.push({ pid, name });
+            const rssRaw = parts[4];
+            const rss = rssRaw !== undefined && /^\d+$/.test(rssRaw) ? Number(rssRaw) : undefined;
+            entries.push({ pid, name, ...(rss !== undefined ? { rss } : {}) });
         }
     }
     return entries;

package/lib/report-store.d.ts

@@ -0,0 +1,18 @@
+import type { DeviceReport } from './report.js';
+/**
+ * Device health report store: one JSON file per report under a configurable
+ * directory (`<baselineDir>/reports` by default). Read/write helpers are pure
+ * fs functions so the store is unit-testable like the baseline store.
+ * Filename: `<serial>--<epoch-ms>.json`; the id is the epoch prefix.
+ */
+export interface StoredReportMeta {
+    id: string;
+    collectedAt: string;
+    serial: string;
+    file: string;
+}
+export declare const DEFAULT_REPORT_DIR: string;
+export declare function reportFileFor(serial: string): string;
+export declare function listReports(dir: string): StoredReportMeta[];
+export declare function saveReport(dir: string, report: DeviceReport): StoredReportMeta;
+export declare function loadReport(dir: string, file: string): DeviceReport;

package/lib/report-store.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export const DEFAULT_REPORT_DIR = `${homedir().replace(/\\/g, '/')}/.dsh/storages/dsh-adb/reports`;
+const FILE_PATTERN = /^(.+)--(\d+)\.json$/;
+/** Parse a report filename back into its meta; undefined for foreign files. */
+function parseMeta(file) {
+    const match = FILE_PATTERN.exec(file);
+    if (match === null)
+        return undefined;
+    return { id: match[2], collectedAt: '', serial: match[1], file };
+}
+export function reportFileFor(serial) {
+    const safeSerial = serial.replace(/[^A-Za-z0-9._-]/g, '_');
+    return `${safeSerial}--${Date.now()}.json`;
+}
+export function listReports(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 saveReport(dir, report) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const file = reportFileFor(report.serial);
+        writeFileSync(join(dir, file), JSON.stringify(report, null, 2), 'utf8');
+        return { id: String(Date.now()), collectedAt: report.collectedAt, serial: report.serial, file };
+    }
+    catch (error) {
+        throw new Error(`report store unwritable at ${dir}: ${describe(error)}`);
+    }
+}
+export function loadReport(dir, file) {
+    try {
+        const raw = readFileSync(join(dir, file), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || !Array.isArray(parsed.errors) || typeof parsed.collectedAt !== 'string') {
+            throw new Error('unexpected shape');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`report store unreadable at ${join(dir, file)}: ${describe(error)}`);
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/report.d.ts

@@ -0,0 +1,103 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from './adb.js';
+import { type LogcatEntry, type LogLevel } from './parsers/logcat.js';
+import { type ProcessEntry } from './parsers/sysinfo.js';
+/**
+ * One-click device health report ("体检"): collect device identity, top
+ * processes, crash buffer, the worrying logcat window (W/E/F), and storage
+ * usage into one structured snapshot. Every section degrades independently —
+ * a failing section lands in `errors` instead of killing the whole report,
+ * so a half-alive device still yields whatever could be read.
+ *
+ * Evidence → signal: raw crash/logcat counts are noisy (boot markers, one
+ * mDNS error repeating thousands of times), so the report classifies crashes
+ * into real crashes vs. startup markers, aggregates logcat by tag, and emits a
+ * compact health summary the agent can reason from instead of 17k raw lines.
+ */
+export type ReportSection = 'device' | 'processes' | 'crash' | 'logcat' | 'storage';
+export declare const REPORT_SECTIONS: readonly ReportSection[];
+export interface ReportDeviceInfo {
+    model?: string;
+    manufacturer?: string;
+    release?: string;
+    sdk?: string;
+    fingerprint?: string;
+    resolution?: string;
+    memTotalKb?: number;
+}
+/** A real crash with the following same-pid lines (its stack trace) attached. */
+export interface CrashChain {
+    signature: LogcatEntry;
+    following: LogcatEntry[];
+}
+export interface CrashSummary {
+    total: number;
+    realCrashCount: number;
+    bootMarkerCount: number;
+    otherCount: number;
+    /** Real crashes, each with its contiguous same-pid tail. */
+    chains: CrashChain[];
+}
+export interface TagAggregate {
+    tag: string;
+    level: LogLevel;
+    count: number;
+    sample: LogcatEntry;
+}
+export interface LogcatSummary {
+    total: number;
+    byTag: TagAggregate[];
+}
+export type HealthVerdict = 'ok' | 'attention';
+export interface HealthSummary {
+    verdict: HealthVerdict;
+    /** Human/agent-readable lines: device, memory hogs, notable signals. */
+    lines: string[];
+    /** Concrete issues that drove the verdict (empty when ok). */
+    issues: string[];
+}
+export interface DeviceReport {
+    collectedAt: string;
+    serial: string;
+    device?: ReportDeviceInfo;
+    processes?: ProcessEntry[];
+    crashBuffer?: CrashSummary;
+    logcat?: LogcatSummary;
+    storage?: {
+        lines: number;
+        truncated: boolean;
+        excerpt: string;
+    };
+    health?: HealthSummary;
+    errors: Array<{
+        section: string;
+        message: string;
+    }>;
+}
+export interface CollectDeviceReportArgs {
+    serial?: string;
+    include?: ReportSection[];
+    /** Cap for crash chains, logcat tag aggregates, and the process/df lists; defaults to 10. */
+    tail?: number;
+}
+export declare function isRealCrash(entry: LogcatEntry): boolean;
+export declare function isBootMarker(entry: LogcatEntry): boolean;
+/**
+ * Classify crash-buffer entries into real crashes vs. MediaTek boot markers
+ * vs. everything else, grouping each real crash with the contiguous same-pid
+ * lines that follow it (the stack trace).
+ */
+export declare function classifyCrashBuffer(entries: LogcatEntry[]): CrashSummary;
+/**
+ * Aggregate logcat entries by tag+level, keeping one sample line per group and
+ * sorting by count descending. Turns "16987 lines" into "AOSP-MdnsDiscovery ×16200".
+ */
+export declare function aggregateByTag(entries: LogcatEntry[], topN?: number): LogcatSummary;
+/**
+ * Compact health summary: verdict + a few lines the agent (or user) can reason
+ * from directly, instead of raw counts. Signals are intentionally coarse —
+ * the report is a triage surface, not a root-cause tool.
+ */
+export declare function buildHealthSummary(report: Pick<DeviceReport, 'device' | 'crashBuffer' | 'logcat' | 'processes'>): HealthSummary;
+/** Collect the one-click device health report with per-section degradation. */
+export declare function collectDeviceReport(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args?: CollectDeviceReportArgs): Promise<DeviceReport>;

package/lib/report.js

@@ -0,0 +1,192 @@
+import { classifyFailure, runAdb } from './adb.js';
+import { matchesLevel, parseLogcat } from './parsers/logcat.js';
+import { parseGetprop, parseMemTotal, parseProcessList, parseWmSize } from './parsers/sysinfo.js';
+export const REPORT_SECTIONS = ['device', 'processes', 'crash', 'logcat', 'storage'];
+function excerpt(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'),
+    };
+}
+// ---- Evidence → signal pure helpers (unit-tested) ----
+const REAL_CRASH = /FATAL EXCEPTION|Fatal signal|beginning of crash|SIGSEGV|SIGABRT|SIGBUS|SIGFPE|SIGILL|SIGTRAP/i;
+const BOOT_MARKER = /mtk-brm-(?:commit|change|merge)-id|libimsma_adapt|SmartRatSwitch.*mtk-brm/i;
+export function isRealCrash(entry) {
+    return REAL_CRASH.test(entry.message) || REAL_CRASH.test(entry.tag);
+}
+export function isBootMarker(entry) {
+    return BOOT_MARKER.test(entry.message) || BOOT_MARKER.test(entry.tag);
+}
+/**
+ * Classify crash-buffer entries into real crashes vs. MediaTek boot markers
+ * vs. everything else, grouping each real crash with the contiguous same-pid
+ * lines that follow it (the stack trace).
+ */
+export function classifyCrashBuffer(entries) {
+    const chains = [];
+    for (let i = 0; i < entries.length; i++) {
+        if (!isRealCrash(entries[i]))
+            continue;
+        const following = [];
+        const pid = entries[i].pid;
+        for (let j = i + 1; j < entries.length && entries[j].pid === pid; j++) {
+            following.push(entries[j]);
+        }
+        chains.push({ signature: entries[i], following });
+    }
+    const bootMarkerCount = entries.filter(isBootMarker).length;
+    return {
+        total: entries.length,
+        realCrashCount: chains.length,
+        bootMarkerCount,
+        otherCount: entries.length - chains.length - bootMarkerCount,
+        chains,
+    };
+}
+/**
+ * Aggregate logcat entries by tag+level, keeping one sample line per group and
+ * sorting by count descending. Turns "16987 lines" into "AOSP-MdnsDiscovery ×16200".
+ */
+export function aggregateByTag(entries, topN = 10) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const key = `${entry.tag}\u0000${entry.level}`;
+        const existing = counts.get(key);
+        if (existing !== undefined) {
+            existing.count++;
+            continue;
+        }
+        counts.set(key, { tag: entry.tag, level: entry.level, count: 1, sample: entry });
+    }
+    const byTag = [...counts.values()].sort((a, b) => b.count - a.count).slice(0, topN);
+    return { total: entries.length, byTag };
+}
+const NETWORK_SIGNAL = /WifiHAL|NETWORK_ABNORMAL|MdnsDiscovery|multicast mDNS|sendto failed: EPERM/i;
+const THERMAL_NOISE = /PowerKeeper\.Thermal/i;
+/**
+ * Compact health summary: verdict + a few lines the agent (or user) can reason
+ * from directly, instead of raw counts. Signals are intentionally coarse —
+ * the report is a triage surface, not a root-cause tool.
+ */
+export function buildHealthSummary(report) {
+    const lines = [];
+    const issues = [];
+    const device = report.device;
+    if (device) {
+        const parts = [device.model, `Android ${device.release ?? '?'}`].filter(Boolean);
+        if (device.memTotalKb !== undefined)
+            parts.push(`内存 ${Math.round(device.memTotalKb / 1024)}MB`);
+        lines.push(`设备：${parts.join(' · ')}`);
+    }
+    const crash = report.crashBuffer;
+    if (crash && crash.total > 0) {
+        if (crash.realCrashCount > 0) {
+            const tags = [...new Set(crash.chains.map((chain) => chain.signature.tag))].join(', ');
+            issues.push(`真实崩溃 ${crash.realCrashCount} 起（${tags}）`);
+            lines.push(`崩溃：${crash.realCrashCount} 真实崩溃 + ${crash.bootMarkerCount} 启动标记 + ${crash.otherCount} 其他（共 ${crash.total}）`);
+        }
+        else {
+            lines.push(`崩溃：无真实崩溃（${crash.bootMarkerCount} 启动标记 + ${crash.otherCount} 其他，共 ${crash.total}）`);
+        }
+    }
+    const logcat = report.logcat;
+    if (logcat && logcat.total > 0) {
+        const top = logcat.byTag[0];
+        if (top)
+            lines.push(`W/E/F 日志：共 ${logcat.total} 条，主要来源 ${top.tag}(${top.level}) ×${top.count}${logcat.byTag.length > 1 ? ` 等 ${logcat.byTag.length} 个来源` : ''}`);
+        const net = logcat.byTag.find((agg) => NETWORK_SIGNAL.test(agg.tag) || NETWORK_SIGNAL.test(agg.sample.message));
+        if (net)
+            issues.push(`网络异常信号（${net.tag}: ${net.sample.message.slice(0, 80)}）`);
+        const thermal = logcat.byTag.find((agg) => THERMAL_NOISE.test(agg.tag));
+        if (thermal)
+            lines.push('注：PowerKeeper.Thermal 为 MIUI 解析噪音，可忽略');
+    }
+    if (report.processes && report.processes.length > 0) {
+        const top = report.processes.slice(0, 3);
+        lines.push(`内存大户：${top.map((p) => `${p.name}(${p.rss}KB)`).join(', ')}`);
+    }
+    const verdict = issues.length > 0 ? 'attention' : 'ok';
+    return { verdict, lines, issues };
+}
+// ---- Section collectors ----
+/** Device identity block: getprop + wm size + /proc/meminfo. */
+async function collectDevice(ctx, cfg, signal, serial) {
+    const [getpropOut, sizeOut, memOut] = await Promise.all([
+        runAdb(ctx, cfg, ['shell', 'getprop'], { signal, serial, maxBytes: 2 * 1024 * 1024 }),
+        runAdb(ctx, cfg, ['shell', 'wm', 'size'], { signal, serial }),
+        runAdb(ctx, cfg, ['shell', 'cat', '/proc/meminfo'], { signal, serial }),
+    ]);
+    for (const result of [getpropOut, sizeOut, memOut]) {
+        if (result.exitCode !== 0)
+            throw classifyFailure(result);
+    }
+    const props = parseGetprop(getpropOut.stdout);
+    const size = parseWmSize(sizeOut.stdout);
+    return {
+        model: props['ro.product.model'],
+        manufacturer: props['ro.product.manufacturer'],
+        release: props['ro.build.version.release'],
+        sdk: props['ro.build.version.sdk'],
+        fingerprint: props['ro.build.fingerprint'],
+        resolution: size === undefined ? undefined : `${size.width}x${size.height}`,
+        memTotalKb: parseMemTotal(memOut.stdout),
+    };
+}
+/** Top processes by RSS (memory hogs first). */
+async function collectProcesses(ctx, cfg, signal, serial, tail) {
+    const result = await runAdb(ctx, cfg, ['shell', 'ps', '-A'], { signal, serial, maxBytes: 2 * 1024 * 1024 });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    return parseProcessList(result.stdout)
+        .filter((entry) => entry.rss !== undefined)
+        .sort((a, b) => (b.rss ?? 0) - (a.rss ?? 0))
+        .slice(0, tail);
+}
+/** Crash buffer classified into real crashes vs. boot markers. */
+async function collectCrash(ctx, cfg, signal, serial) {
+    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 classifyCrashBuffer(parseLogcat(result.stdout));
+}
+/** The worrying logcat window: W/E/F entries from the main buffer, aggregated by tag. */
+async function collectLogcat(ctx, cfg, signal, serial, tail) {
+    const result = await runAdb(ctx, cfg, ['logcat', '-v', 'threadtime', '-d'], { signal, serial, maxBytes: 8 * 1024 * 1024 });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    const entries = parseLogcat(result.stdout).filter((entry) => matchesLevel(entry, 'W'));
+    return aggregateByTag(entries, tail);
+}
+/** Storage usage excerpt (`df`). */
+async function collectStorage(ctx, cfg, signal, serial, tail) {
+    const result = await runAdb(ctx, cfg, ['shell', 'df'], { signal, serial, maxBytes: 1024 * 1024 });
+    if (result.exitCode !== 0)
+        throw classifyFailure(result);
+    return excerpt(result.stdout, tail);
+}
+/** Collect the one-click device health report with per-section degradation. */
+export async function collectDeviceReport(ctx, cfg, signal, args = {}) {
+    const serial = args.serial ?? cfg.defaultSerial;
+    const tail = args.tail !== undefined && args.tail > 0 ? Math.floor(args.tail) : 10;
+    const include = args.include ?? [...REPORT_SECTIONS];
+    const report = { collectedAt: new Date().toISOString(), serial: serial ?? 'default', errors: [] };
+    const guard = async (section, collect, assign) => {
+        try {
+            assign(await collect());
+        }
+        catch (error) {
+            report.errors.push({ section, message: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    await Promise.all([
+        include.includes('device') && guard('device', () => collectDevice(ctx, cfg, signal, serial), (v) => { report.device = v; }),
+        include.includes('processes') && guard('processes', () => collectProcesses(ctx, cfg, signal, serial, tail), (v) => { report.processes = v; }),
+        include.includes('crash') && guard('crash', () => collectCrash(ctx, cfg, signal, serial), (v) => { report.crashBuffer = v; }),
+        include.includes('logcat') && guard('logcat', () => collectLogcat(ctx, cfg, signal, serial, tail), (v) => { report.logcat = v; }),
+        include.includes('storage') && guard('storage', () => collectStorage(ctx, cfg, signal, serial, tail), (v) => { report.storage = v; }),
+    ]);
+    report.health = buildHealthSummary(report);
+    return report;
+}

package/lib/rpc.d.ts

@@ -9,10 +9,10 @@ export type RpcEndpointResult = {
         message: string;
     };
 };
-export declare function handleRpcEndpoint(ctx: Context, cfg: AdbConfig, endpoint: string, raw: unknown, signal: AbortSignal): Promise<RpcEndpointResult>;
+export declare function handleRpcEndpoint(ctx: Context, cfg: AdbConfig, reportDir: string, endpoint: string, raw: unknown, signal: AbortSignal): Promise<RpcEndpointResult>;
 /**
  * Register the Package-private Client↔Host RPC for the Web device panel
  * (conversation.view tab "设备"). Called lazily once the client connection
  * mounts; headless compositions (no connection) stay unaffected.
  */
-export declare function registerRpc(ctx: Context, cfg: AdbConfig): void;
+export declare function registerRpc(ctx: Context, cfg: AdbConfig, reportDir: string): void;

package/lib/rpc.js

@@ -6,6 +6,8 @@ import { parseDevices } from './parsers/devices.js';
 import { matchesKeyword, matchesLevel, parseLogcat } from './parsers/logcat.js';
 import { parseGetprop, parseMemTotal, parsePackageList, parseProcessList, parseWmSize, } from './parsers/sysinfo.js';
 import { capturePerfSnapshot } from './tools/perf.js';
+import { collectDeviceReport, REPORT_SECTIONS } from './report.js';
+import { saveReport } from './report-store.js';
 async function requireDevice(ctx, cfg, argv, options) {
     const result = await runAdb(ctx, cfg, argv, { signal: options.signal, serial: options.serial, maxBytes: options.maxBytes });
     if (result.exitCode !== 0)
@@ -15,7 +17,7 @@ async function requireDevice(ctx, cfg, argv, options) {
 function serialOf(payload) {
     return typeof payload.serial === 'string' ? payload.serial : undefined;
 }
-export async function handleRpcEndpoint(ctx, cfg, endpoint, raw, signal) {
+export async function handleRpcEndpoint(ctx, cfg, reportDir, endpoint, raw, signal) {
     try {
         const payload = (raw ?? {});
         switch (endpoint) {
@@ -118,6 +120,15 @@ export async function handleRpcEndpoint(ctx, cfg, endpoint, raw, signal) {
                 const snapshot = await capturePerfSnapshot(ctx, cfg, signal, { package: pkg, serial: serialOf(payload), metrics: ['meminfo', 'battery'] });
                 return { ok: true, value: { package: pkg, meminfo: snapshot.meminfo, battery: snapshot.battery } };
             }
+            case 'deviceReport': {
+                const include = Array.isArray(payload.include)
+                    ? payload.include.filter((item) => typeof item === 'string' && REPORT_SECTIONS.includes(item))
+                    : undefined;
+                const tail = typeof payload.tail === 'number' ? payload.tail : undefined;
+                const report = await collectDeviceReport(ctx, cfg, signal, { serial: serialOf(payload), include, tail });
+                const saved = saveReport(reportDir, report);
+                return { ok: true, value: { ...report, savedTo: saved.file } };
+            }
             default:
                 return { ok: false, error: { message: `unknown endpoint: ${endpoint}` } };
         }
@@ -131,12 +142,12 @@ export async function handleRpcEndpoint(ctx, cfg, endpoint, raw, signal) {
  * (conversation.view tab "设备"). Called lazily once the client connection
  * mounts; headless compositions (no connection) stay unaffected.
  */
-export function registerRpc(ctx, cfg) {
+export function registerRpc(ctx, cfg, reportDir) {
     const connection = ctx.get('connection');
     const rpc = connection?.rpc;
     if (rpc === undefined)
         return;
-    ctx.effect(() => rpc.handle('/dsh-adb', (endpoint, raw, signal) => handleRpcEndpoint(ctx, cfg, endpoint, raw, signal), 
+    ctx.effect(() => rpc.handle('/dsh-adb', (endpoint, raw, signal) => handleRpcEndpoint(ctx, cfg, reportDir, endpoint, raw, signal), 
     // Browser-only channel: accept requests from the loopback web GUI.
     { authority: 'loopback' }));
 }

package/lib/tools/device-report.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+/**
+ * adb_device_report: one-click device health check ("体检"). Collects device
+ * identity, top RSS processes, crash buffer, the W/E/F logcat window, and
+ * storage usage into one structured report, persists it under the report
+ * store, and returns it for the agent to diagnose (pair with the
+ * dsh-adb-crash-analysis skill).
+ */
+export declare function registerDeviceReportTool(ctx: Context, cfg: AdbConfig, reportDir: string): void;

package/lib/tools/device-report.js

@@ -0,0 +1,52 @@
+import { jsonOutput } from '../adb.js';
+import { collectDeviceReport, REPORT_SECTIONS } from '../report.js';
+import { saveReport } from '../report-store.js';
+/**
+ * adb_device_report: one-click device health check ("体检"). Collects device
+ * identity, top RSS processes, crash buffer, the W/E/F logcat window, and
+ * storage usage into one structured report, persists it under the report
+ * store, and returns it for the agent to diagnose (pair with the
+ * dsh-adb-crash-analysis skill).
+ */
+export function registerDeviceReportTool(ctx, cfg, reportDir) {
+    ctx.tools.register({
+        name: 'adb_device_report',
+        description: 'One-click device health report: collect device identity, top memory processes, the crash buffer (classified into real crashes vs. boot markers, with stack chains), the warning/error logcat window (aggregated by tag), storage usage, and a compact health summary (verdict + issues) into one structured snapshot, persist it to the report store, and return it. Each section degrades independently — a failing section lands in errors instead of failing the whole report. Pair the result with the dsh-adb-crash-analysis skill to diagnose the device state.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial.' },
+                include: {
+                    type: 'array',
+                    items: { type: 'string', enum: [...REPORT_SECTIONS] },
+                    description: 'Which sections to collect; defaults to all five (device, processes, crash, logcat, storage).',
+                },
+                tail: { type: 'integer', description: 'Cap for crash/logcat entries and the process/storage lists; defaults to 100.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            const report = await collectDeviceReport(ctx, cfg, exec.signal, args);
+            let saved;
+            try {
+                saved = saveReport(reportDir, report);
+            }
+            catch {
+                // Persistence is best-effort: the report is still returned to the agent.
+            }
+            return {
+                collectedAt: report.collectedAt,
+                serial: report.serial,
+                ...(report.device !== undefined ? { device: report.device } : {}),
+                ...(report.processes !== undefined ? { topProcesses: report.processes } : {}),
+                ...(report.crashBuffer !== undefined ? { crashBuffer: report.crashBuffer } : {}),
+                ...(report.logcat !== undefined ? { logcat: report.logcat } : {}),
+                ...(report.storage !== undefined ? { storage: report.storage } : {}),
+                ...(report.health !== undefined ? { health: report.health } : {}),
+                errors: report.errors,
+                ...(saved !== undefined ? { savedTo: saved.file } : {}),
+            };
+        },
+    });
+}

package/lib/tools/wait.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+import { type AdbDevice } from '../parsers/devices.js';
+import { type LogcatEntry } from '../parsers/logcat.js';
+import { type ProcessEntry } from '../parsers/sysinfo.js';
+/**
+ * adb_wait_for: wait until a device reaches a condition, instead of sleeping a
+ * fixed number of seconds. Conditions: device-online, boot-complete, process
+ * (a process appears), logcat-pattern (a keyword appears). Polls at
+ * `intervalMs` until `timeoutMs`, then returns `matched: false` (not an error)
+ * so the agent can react to the timeout instead of guessing.
+ */
+export type WaitCondition = 'device-online' | 'boot-complete' | 'process' | 'logcat-pattern';
+export interface WaitArgs {
+    serial?: string;
+    condition: WaitCondition;
+    /** Substring matched against process names (condition=process) or logcat tag/message (condition=logcat-pattern). */
+    pattern?: string;
+    /** Overall wait budget in milliseconds; defaults to 30000, capped at 300000. */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds; defaults to 1000. */
+    intervalMs?: number;
+}
+export interface WaitResult {
+    condition: WaitCondition;
+    matched: boolean;
+    waitedMs: number;
+    attempts: number;
+    reason?: string;
+}
+/** device-online: the serial is present in `adb devices -l` with state `device`. */
+export declare function checkDeviceOnline(devices: AdbDevice[], serial?: string): boolean;
+/** boot-complete: `getprop sys.boot_completed` output is exactly "1". */
+export declare function checkBootComplete(getpropOut: string): boolean;
+/** process: any process name contains the pattern. */
+export declare function checkProcessPresent(processes: ProcessEntry[], pattern: string): boolean;
+/** logcat-pattern: any entry's tag or message contains the keyword. */
+export declare function checkLogcatKeyword(entries: LogcatEntry[], keyword: string): boolean;
+/** Wait until the condition holds or the budget expires (returns matched:false on timeout). */
+export declare function waitForCondition(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: WaitArgs): Promise<WaitResult>;
+/** adb_wait_for: wait until a device condition holds (online / boot complete / process / logcat keyword). */
+export declare function registerWaitTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/wait.js

@@ -0,0 +1,144 @@
+import { classifyFailure, jsonOutput, runAdb } from '../adb.js';
+import { parseDevices } from '../parsers/devices.js';
+import { parseLogcat } from '../parsers/logcat.js';
+import { parseProcessList } from '../parsers/sysinfo.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 300_000;
+const DEFAULT_INTERVAL_MS = 1_000;
+// ---- Pure condition checks (unit-tested) ----
+/** device-online: the serial is present in `adb devices -l` with state `device`. */
+export function checkDeviceOnline(devices, serial) {
+    return devices.some((device) => {
+        if (serial !== undefined && device.serial !== serial)
+            return false;
+        return device.state === 'device';
+    });
+}
+/** boot-complete: `getprop sys.boot_completed` output is exactly "1". */
+export function checkBootComplete(getpropOut) {
+    return getpropOut.trim() === '1';
+}
+/** process: any process name contains the pattern. */
+export function checkProcessPresent(processes, pattern) {
+    return processes.some((entry) => entry.name.includes(pattern));
+}
+/** logcat-pattern: any entry's tag or message contains the keyword. */
+export function checkLogcatKeyword(entries, keyword) {
+    return entries.some((entry) => entry.tag.includes(keyword) || entry.message.includes(keyword));
+}
+// ---- Poll loop ----
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('tool call aborted'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new Error('tool call aborted'));
+        }, { once: true });
+    });
+}
+/** Run one adb probe for the condition; returns true when satisfied. */
+async function probe(ctx, cfg, args, signal) {
+    const serial = args.serial;
+    switch (args.condition) {
+        case 'device-online': {
+            const result = await runAdb(ctx, cfg, ['devices', '-l'], { signal, maxBytes: 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkDeviceOnline(parseDevices(result.stdout), args.serial);
+        }
+        case 'boot-complete': {
+            const result = await runAdb(ctx, cfg, ['shell', 'getprop', 'sys.boot_completed'], { signal, serial });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkBootComplete(result.stdout);
+        }
+        case 'process': {
+            const result = await runAdb(ctx, cfg, ['shell', 'ps', '-A'], { signal, serial, maxBytes: 2 * 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkProcessPresent(parseProcessList(result.stdout), args.pattern);
+        }
+        case 'logcat-pattern': {
+            const result = await runAdb(ctx, cfg, ['logcat', '-v', 'threadtime', '-d'], { signal, serial, maxBytes: 8 * 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkLogcatKeyword(parseLogcat(result.stdout), args.pattern);
+        }
+        default:
+            throw new Error(`unknown condition: ${String(args.condition)}`);
+    }
+}
+/** Validate args that fail fast — before the poll loop so they surface as errors, not timeouts. */
+function validateArgs(args) {
+    if (!['device-online', 'boot-complete', 'process', 'logcat-pattern'].includes(args.condition)) {
+        throw new Error(`unknown condition: ${String(args.condition)}`);
+    }
+    if ((args.condition === 'process' || args.condition === 'logcat-pattern') && (args.pattern === undefined || args.pattern === '')) {
+        throw new Error(`condition "${args.condition}" requires a non-empty "pattern"`);
+    }
+}
+/** Wait until the condition holds or the budget expires (returns matched:false on timeout). */
+export async function waitForCondition(ctx, cfg, signal, args) {
+    validateArgs(args);
+    const timeoutMs = Math.min(Math.floor(args.timeoutMs ?? DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+    const intervalMs = Math.max(Math.floor(args.intervalMs ?? DEFAULT_INTERVAL_MS), 250);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    let attempts = 0;
+    let lastProbe;
+    while (true) {
+        attempts++;
+        try {
+            const satisfied = await probe(ctx, cfg, args, signal);
+            if (satisfied) {
+                return { condition: args.condition, matched: true, waitedMs: Date.now() - start, attempts };
+            }
+        }
+        catch (error) {
+            // A transient probe failure (device offline mid-wait) is not terminal:
+            // keep polling until the budget, but record the reason.
+            lastProbe = error instanceof Error ? error.message : String(error);
+        }
+        if (Date.now() >= deadline) {
+            return {
+                condition: args.condition,
+                matched: false,
+                waitedMs: timeoutMs,
+                attempts,
+                ...(lastProbe !== undefined ? { reason: lastProbe } : { reason: `condition not met within ${timeoutMs}ms` }),
+            };
+        }
+        await sleep(Math.min(intervalMs, deadline - Date.now()), signal);
+    }
+}
+/** adb_wait_for: wait until a device condition holds (online / boot complete / process / logcat keyword). */
+export function registerWaitTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_wait_for',
+        description: 'Wait until a device reaches a condition, then return — instead of sleeping a fixed number of seconds. Conditions: device-online (device is in `adb devices` with state `device`), boot-complete (sys.boot_completed=1), process (a process whose name contains `pattern` appears in ps), logcat-pattern (a keyword appears in logcat tag/message). Polls every `intervalMs` up to `timeoutMs`; on timeout returns matched:false (not an error) so you can react. Use it to sequence multi-step device flows: install → wait for process → snapshot.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['condition'],
+            properties: {
+                condition: {
+                    type: 'string',
+                    enum: ['device-online', 'boot-complete', 'process', 'logcat-pattern'],
+                    description: 'Which condition to wait for.',
+                },
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial. For device-online, omit serial to wait for ANY device to come online.' },
+                pattern: { type: 'string', description: 'Required for process (process-name substring) and logcat-pattern (keyword).' },
+                timeoutMs: { type: 'integer', description: 'Overall wait budget in milliseconds; defaults to 30000, capped at 300000.' },
+                intervalMs: { type: 'integer', description: 'Poll interval in milliseconds; defaults to 1000, minimum 250.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            return waitForCondition(ctx, cfg, exec.signal, args);
+        },
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-adb",
-  "version": "1.1.0",
-  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, web device panel (autocomplete, live logcat, profiler)",
+  "version": "1.3.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, web device panel (autocomplete, live logcat, profiler)",
   "type": "module",
   "main": "lib/index.js",
   "exports": {