SamXiaBing/dsh-adb

dsh-adb

ADB 设备·台架运维工具集 for DeepSeek Harness

English | 简体中文

让 DSH agent 直接操作 Android 设备 / 车机台架：设备发现、结构化 logcat、apk 安装、文件 pull/push、性能快照、一键体检。面向实车与台架联调场景，业务内通用（不限 Unity、不限具体车机协议）。

安装

dsh plugin --profile web add dsh-adb

或从 GitHub 直装：dsh plugin --profile web add github:SamXiaBing/dsh-adb

Web 设备面板（v1.2.0）

会话视图页签「设备」（与 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 — dsh-adb 已发布（latest: 1.6.0）
• ✅ awesome-deepseek-harness#87 — 已合并
• ✅ awesome-dsh-plugin#85 — 已合并
• ✅ awesome-DSH-plugin#29 — 已合并

Topics：dsh-plugin dsh adb android automotive bench

工具

错误码：ADB_NOT_FOUND、ADB_UNAVAILABLE、DEVICE_NOT_FOUND、NO_DEVICES、CONNECT_FAILED、INSTALL_FAILED、ADB_EXIT_<code> 等，均为结构化 AdbError。

审批 guard（破坏性操作）

改设备的调用在执行前走 harness 审批 seam：adb_install、adb_file push/rm、adb_operation_ledger rollback 会返回 pre-execute ask 决策（reason 含工具名 + serial + 目标），由会话的审批应答方（web UI 审批卡、ACP 机器策略）裁决。设计上 fail-closed：未加载审批服务（headless）或策略为 never 时一律拒绝——只读工具不受影响，无需任何审批接线。与全插件原则一致：「查不到」≠「允许」。

用法：adb_watch_crash（崩溃看门狗）

监控设备 crash buffer 里的新真实崩溃。启动时先读一遍当前 buffer，记住所有已有崩溃签名（seed），所以只报 watch 开始之后新出现的崩溃。启动标记（mtk-brm-*）不算崩溃，自动忽略。

前台模式（默认）——阻塞到新崩溃出现或预算耗尽：

// Agent 调用：
{ "name": "adb_watch_crash", "args": { "timeoutMs": 60000 } }

// 检测到新崩溃：
{ "matched": true, "waitedMs": 3200, "crashes": [{ "time": "08-26 06:22:56.714", "pid": "2947", "tag": "AndroidRuntime", "message": "FATAL EXCEPTION: WM.task-1", "stack": ["AndroidRuntime: Process: com.miui.weather2, PID: 2947", "..."] }] }

// 预算内无新崩溃（不是错误）：
{ "matched": false, "waitedMs": 60000, "crashes": [], "reason": "no new crash within 60000ms" }

后台模式（run_in_background）——立即返回 job id，持续轮询：

// 启动后台监控：
{ "name": "adb_watch_crash", "args": { "run_in_background": true, "timeoutMs": 300000 } }
// → { "kind": "background", "jobId": "adb-watch-crash-1" }

// 用 job_output 读最新检测结果：
// [adb_watch_crash] detected 1 new crash(es) after 5400ms
// - 08-26 06:22:56.714 pid=2947 AndroidRuntime: FATAL EXCEPTION: WM.task-1
//     AndroidRuntime: Process: com.miui.weather2, PID: 2947
//     ...

与现场采集衔接——检测到崩溃后，配 adb_crash_report 和 adb_screenshot 抓现场：

1. adb_watch_crash（盯新崩溃）
2. → 崩溃出现 → adb_crash_report（采集完整现场：buffer + dropbox + 进程 + 内存）
3.             → adb_screenshot（截取崩溃时的屏幕状态）

配置

cordis.patch.yml 的 config 块（或 profile patch）：

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

开发

npm install            # 本机 NODE_ENV=production 时加 --include=dev
npm run build          # tsc → lib/
npm test               # 解析器/错误分类单测（node --test）
npm pack --dry-run     # 校验发布包内容（lib/ + cordis.patch.yml）

注意：本机若设了 NODE_ENV=production，npm 会跳过 devDependencies，安装时用 npm install --include=dev。

测试与验证

• 原则：提交即测 —— 全部已提交功能均有实测覆盖（单元 + headless 端到端 + 车机台架/真机）。
• 验证设备：Android 13 车机台架 + Android 14 真机（Redmi K50 Pro）+ 模拟器。
• 版本化变更与每版验证记录见 CHANGELOG.md；测试方法与覆盖现状见 docs/TESTING.md。

项目文档（双语，供 AI 对话/协作者参考）

• docs/AGENTS.md / docs/AGENTS.zh-CN.md — 进项目先读：定位、铁律、命令、环境事实、文档地图
• docs/REQUIREMENTS.md / docs/REQUIREMENTS.zh-CN.md — 目的/范围/非目标/验收标准
• docs/TESTING.md / docs/TESTING.zh-CN.md — 测试哲学（提交即测）、三层测试方法、E2E 步骤、回归清单
• docs/ROADMAP.md / docs/ROADMAP.zh-CN.md — harness×adb 协同功能路线图（诊断报告/崩溃归因/截图视觉/台架自动化测试/等待原语/审批/多设备对比/定时巡检/回滚台账）
• docs/SCHEDULED-PATROL.md / docs/SCHEDULED-PATROL.zh-CN.md — 用 dsh-automation 定时无人值守巡检（prompt 模板 + 运维注意）
• PLAN.md / PLAN.zh-CN.md — 里程碑与待办

License

MIT