deepadb

DeepADB

面向需要通过 ADB 检查、控制、测试和诊断 Android 设备的 AI Agent 的 MCP（Model Context Protocol）服务，也可通过 Termux 直接在设备上运行。

49 个模块中的 209 个工具、5 个资源和 4 个提示词——涵盖 UI 自动化和应用管理，以及日志、网络抓包、基带、固件、安全和硬件诊断。

快速开始

DeepADB 作为本地 MCP 服务运行。默认使用 ADB，并会在检测到 Android 设备上运行 Termux 时自动切换为直接执行。

git clone https://github.com/fullread/DeepADB.git
cd DeepADB
npm ci
npm run build
npm start

将 build/index.js 添加到 MCP 客户端配置中，然后从以下工作流开始：

目标	从这里开始
确认工具链和已连接的设备	adb_health_check，然后是 adb_devices
检查当前 Android UI	adb_screen_state，然后是 adb_ui_dump
诊断设备或应用	adb_device_info、adb_logcat 和 adb_dumpsys

如需本地连接指南，请参阅 Claude Code 配置。在将 HTTP、WebSocket 或 GraphQL 传输暴露到回环地址之外之前，请阅读 SECURITY.md。

架构

┌──────────────────────────────────────────────────┐
│                   MCP Client                     │
│             (Claude Code / claude.ai)            │
└──────────────────────┬───────────────────────────┘
                       │ stdio (JSON-RPC) or HTTP/SSE or WebSocket
┌──────────────────────▼───────────────────────────┐
│               DeepADB Server                     │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Tool Modules (49)                 │ │
│  │  device │ shell │ packages │ files │ logs   │ │
│  │  diagnostics │ ui │ build │ health          │ │
│  │  wireless │ control │ logcat-watch          │ │
│  │  forwarding │ screen-record │ emulator      │ │
│  │  testing │ multi-device │ snapshot          │ │
│  │  network-capture │ ci │ plugins │ baseband  │ │
│  │  accessibility │ regression                 │ │
│  │  device-farm │ registry │ at-commands       │ │
│  │  screenshot-diff │ workflow │ sensors       │ │
│  │  split-apk │ mirroring │ test-gen           │ │
│  │  ota-monitor │ ril-intercept                │ │
│  │  device-profiles │ firmware-analysis        │ │
│  │  workflow-market │ selinux-audit            │ │
│  │  thermal-power │ network-discovery          │ │
│  │  input-gestures │ wireless-firmware         │ │
│  │  app-network │ database-inspector           │ │
│  │  runtime-audit │ wear                       │ │
│  ├─────────────────────────────────────────────┤ │
│  │  Resources (5) │ Prompts (4)                │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │          ToolContext (unified DI)           │ │
│  │  server │ bridge │ deviceManager            │ │
│  │  logger │ security │ config                 │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │           Middleware Layer                  │ │
│  │  OutputProcessor │ SecurityMiddleware       │ │
│  │  InputSanitizer │ Logger (stderr-safe)      │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │         Bridge Layer (auto-detect)          │ │
│  │                                             │ │
│  │  ┌─────────────┐    ┌────────────────────┐  │ │
│  │  │  ADB Bridge  │ OR │  Local Bridge      │ │ │
│  │  │  (PC mode)   │    │  (on-device mode)  │ │ │
│  │  │  via adb.exe │    │  via sh/su direct  │ │ │
│  │  └──────┬───────┘    └────────┬───────────┘ │ │
│  │         │                     │             │ │
│  │  Retry │ Timeout │ Cache │ Serial routing   │ │
│  └─────────┼─────────────────────┼─────────────┘ │
└────────────┼─────────────────────┼───────────────┘
             │                     │
     ┌───────▼───────┐    ┌───────▼───────┐
     │  ADB Binary   │    │   sh / su     │
     │  (USB/WiFi)   │    │   (local)     │
     └───────┬───────┘    └───────┬───────┘
             │                    │
       ┌─────▼────────────────────▼─────┐
       │          Android Device        │
       └────────────────────────────────┘

双模式架构

DeepADB 会在启动时自动检测并以两种模式之一运行：

ADB 模式（默认）——PC 端桥接

AI Agent (PC) ←→ MCP ←→ DeepADB (PC) ←→ ADB (USB) ←→ Android Device

标准模式：DeepADB 在 PC/Mac/Linux 主机上运行，并通过 ADB 经由 USB 与设备通信。完整的 209 个工具均通过 ADB 桥接注册，并在发生暂时性故障时自动重试；当主机无法运行特定环境的工具时，这些工具会说明其所需的功能。

设备端模式 — 直接本地执行

AI Agent (Termux) ←→ MCP (stdio/HTTP) ←→ DeepADB (Termux) ←→ sh/su (local)

当 DeepADB 直接在 Android 设备上运行时（例如在 Termux 内），它会自动检测环境并切换到 LocalBridge。命令通过 sh/su 直接执行，无需 ADB 服务、USB，也没有序列化开销。系统会注册相同的 209 个工具 MCP 接口；如果设备端缺少 sqlite3 等可选二进制文件，还会提供基于功能支持情况的指导。

v1.1.4 主机硬件验证： Pixel 6a / Android 16 的完整回归测试已完成，结果为 604 项通过、0 项失败，另有 17 项符合预期的环境特定跳过（共 621 项）。测试包括在 /dev/umts_router 上进行实时 AT/OK 验证、带清理操作的只读 SQLite 架构快照、统一运行时审计、按应用区分的路由上下文，以及单设备 Wear 预检。跳过项包括 5 项仅限设备端的 QEMU 检查，以及 12 项 Windows 主机或缺少 tcpdump 时的安全检查。

v1.1.3 硬件基线： 已在 Pixel 6a（Android 16、Termux + Magisk + QEMU 10.2.1）上通过四格测试矩阵验证，涵盖主机（ADB）和设备端（LocalBridge）两种模式，各自测试了有无设备 PIN 的情况——每种情况下均 0 项失败。v1.1.3 测试套件在主机/ADB 配置下包含 577 项测试，在设备端包含 613 项；差异在于 QEMU 虚拟化和 Alpine 虚拟机启动测试套件，这些测试仅在设备端运行：

• ADB 模式，无 PIN： 556 项通过 / 0 项失败 / 21 项跳过（共 577 项）。跳过项：5 项 QEMU（仅限设备端）、7 项 gracefulKill 单元测试（需要 POSIX 信号，在 Windows 主机上跳过）、3 项 tcpdump 清理测试（tcpdump 仅 root 可用，且无法通过非 root 的 ADB shell 访问）、2 项主机 shell 往返测试（需要 POSIX /bin/sh）、4 项屏幕状态测试（需要 DA_TEST_PIN）。
• ADB 模式，有 PIN： 560 项通过 / 0 项失败 / 17 项跳过（共 577 项）。4 项屏幕状态测试会解锁并运行。
• 设备端模式，无 PIN： 606 项通过 / 0 项失败 / 7 项跳过（共 613 项）。所有 QEMU 测试均会运行，包括使用 KVM 加速启动 Alpine Linux 虚拟机、检测 big.LITTLE CPU 拓扑、处理访客 ADB 连接错误，以及正常关闭虚拟机；tcpdump 和 gracefulKill 测试套件也会在此运行（需要 root + POSIX）。跳过项：3 项 QEMU 设置步骤（如果 Alpine 内核/initrd/磁盘已缓存，则为空操作）、4 项屏幕状态测试（需要 PIN）。
• 设备端模式，有 PIN： 610 项通过 / 0 项失败 / 3 项跳过（共 613 项）。环境允许的所有测试均会运行；3 项跳过项为缓存虚拟机设置步骤。

权限提升： 在 ADB 模式下，所有 shell 命令都以 uid=2000（shell 用户）运行，该用户拥有系统级权限。在 Termux 中，命令以普通应用用户身份运行。如果有 root 权限（Magisk），LocalBridge 会自动通过 su 提升特权命令：

• 命令允许列表： 16 个系统命令（settings、dumpsys、am、input、screencap、screenrecord、uiautomator、app_process、getenforce、setenforce、cmd、pm、wm、svc、ip、ifconfig）会通过 su -c 执行，以匹配 ADB 模式的行为。
• 基于路径的权限提升： 对引用 /sdcard、/storage 或 /system/ 路径的命令提升权限，以绕过 Android 分区存储限制。
• Root 检测： 首次使用时通过一次 su -c id 探测，并缓存结果。若无法获取 root 权限，则会平稳降级。
• 权限提升允许列表已冻结（ReadonlySet + Object.freeze），无法通过环境变量或运行时 API 配置。

自动检测： 检查 /system/build.prop（所有 Android 设备上均存在，主机上则不会存在）。可通过 DA_LOCAL=true 或 DA_LOCAL=false 覆盖。

设备端设置（Termux）：

pkg install nodejs-lts git
git clone <deepadb-repo> && cd deepadb
npm install && npm run build
npm start                              # stdio — for local AI agents (Claude Code, OpenCode)
DA_HTTP_PORT=3000 npm start            # HTTP/SSE — for remote AI access over WiFi

Claude Code 配置

{
  "mcpServers": {
    "deepadb": {
      "command": "node",
      "args": ["/path/to/DeepADB/build/index.js"]
    }
  }
}

可用工具（209）

从与你的任务匹配的能力领域开始；完整参考仍列在下方。

领域	包含内容
检查与诊断	设备、软件包、文件、日志、诊断、运行时审计和 SQLite
控制与自动化	UI、设备控制、输入自动化和测试会话
连接与扩展	无线调试、端口转发、按应用路由、Wear 预检、多设备编排和 CI/CD
分析 Android 内部机制	网络捕获、基带、固件、SELinux和传感器
扩展工作流	插件、工作流编排、设备配置和结果句柄

完整工具参考

健康检查（1 个工具）

• adb_health_check — 全面的工具链验证：ADB 二进制文件、服务端、设备连接、授权、root 访问权限和存储可写性

运行时审计（1 个工具）

• adb_runtime_audit — 统一的只读就绪状态审计，涵盖传输、Android 用户空间、root、SELinux、存储、命令功能、UI/网络诊断、SQLite、调制解调器节点和 Wear 前置条件

设备（3 个工具）

• adb_devices — 列出所有已连接设备及其状态、型号和产品信息
• adb_device_info — 设备属性详情（型号、操作系统、SDK、构建版本、安全补丁、ABI）
• adb_getprop — 读取指定系统属性或转储所有属性

Shell（2 个工具）

• adb_shell — 执行任意 Shell 命令，可配置超时时间（经过安全检查）
• adb_root_shell — 通过 su 以 root 身份执行命令（需要已 root 的设备，并经过安全检查）

软件包（12 个工具）

• adb_install — 安装 APK，可选择替换或降级
• adb_uninstall — 移除软件包，可选择保留数据
• adb_list_packages — 按名称或类型（所有/系统/第三方）筛选并列出软件包
• adb_package_info — 软件包详情（版本、权限、路径）
• adb_clear_data — 清除所有应用数据和缓存
• adb_grant_permission — 向软件包授予运行时权限
• adb_revoke_permission — 撤销软件包的运行时权限（重置权限状态，以便测试拒绝权限的流程）
• adb_list_permissions — 列出软件包声明和已获授的所有权限，可按已授予/已拒绝状态筛选
• adb_force_stop — 立即强行停止应用
• adb_start_app — 按软件包名称启动应用（解析启动器活动）
• adb_restart_app — 在一次调用中强行停止并重新启动应用（可配置延迟）
• adb_resolve_intents — 查找已注册的活动、服务和接收器及其 Intent 过滤器

Room 和 SQLite 检查（1 个工具）

• adb_sqlite_inspect — 按软件包列出数据库、检查架构，并执行经过验证的只读 SQL，同时严格限制行数和输出量。优先使用 run-as，失败时回退到 root；拒绝符号链接数据库/WAL 文件；设备上存在 sqlite3 时优先使用，否则在检查后删除有大小限制的私有主机端快照

文件（18 个工具）

• adb_push — 将本地文件推送到设备（硬性阻止访问内核路径、识别文件系统类型、报告存储信息）
• adb_pull — 将设备上的文件拉取到本地文件系统
• adb_ls — 列出设备目录内容（简洁或详细）
• adb_cat — 读取设备上的文本文件，可选限制行数
• adb_file_write — 通过 heredoc 创建或覆盖文本文件（缓冲区大小限制警告、识别文件系统、写入后验证）
• adb_find — 按名称／模式搜索文件，可控制深度并限制结果数量
• adb_file_stat — 文件元数据：大小、权限、时间戳、所有权、SELinux 上下文
• adb_file_checksum — 计算 SHA-256／SHA-1／MD5 哈希，并根据大小估算超时时间
• adb_mkdir — 创建目录，可创建父目录（-p），硬性阻止访问内核路径
• adb_rm — 删除文件／目录，提供基于深度的递归保护并解析符号链接
• adb_file_move — 移动／重命名文件，提供源路径深度保护并在操作后验证
• adb_file_copy — 复制文件，操作前检查大小和空间，并在操作后验证大小是否一致
• adb_file_chmod — 更改权限（使用 Zod 验证八进制模式，提供基于深度的递归保护）
• adb_file_touch — 创建空文件或更新时间戳（支持显式指定时间戳）
• adb_file_fsinfo — 文件系统报告：类型、挂载信息、容量、功能、SELinux、限制
• adb_file_chown — 更改所有权（需要 root 权限，提供基于深度的递归保护）
• adb_grep — 搜索文件内容，默认使用固定字符串匹配，可控制递归深度并限制结果数量
• adb_file_replace — 查找并替换文件中的文本（基于 sed，正确处理转义，支持备份选项）

日志 — 快照（3 个工具）

• adb_logcat — 筛选 logcat 快照，可选择标签、优先级、grep 和缓冲区
• adb_logcat_clear — 清除所有 logcat 缓冲区
• adb_logcat_crash — 崩溃缓冲区日志快照

日志 — 持续监视器（4 个工具）

• adb_logcat_start — 启动后台 logcat 监视器，并通过环形缓冲区累积日志
• adb_logcat_poll — 从运行中的监视器获取自上次轮询以来的新行
• adb_logcat_stop — 停止监视器会话（或所有会话）
• adb_logcat_sessions — 列出所有活动监视器会话及其统计信息

诊断（9 个工具）

• adb_dumpsys — 对任意服务运行 dumpsys（或列出所有服务）
• adb_telephony — 小区信息、信号强度和网络注册状态（并行查询）
• adb_battery — 电池状态、电量、温度和充电信息
• adb_network — WiFi、蜂窝网络和 IP 连接状态（并行查询）
• adb_top — CPU 和内存使用情况快照
• adb_perf_snapshot — 并行采集内存、帧统计信息，并为指定软件包执行 CPU 性能分析
• adb_bugreport — 完整 Bug 报告 ZIP 文件采集（设备状态、日志、系统信息）
• adb_crash_logs — 从 /data/anr/ 和 /data/tombstones/ 获取 ANR 跟踪信息和 tombstone 崩溃转储
• adb_heap_dump — 从运行中的进程采集堆转储（.hprof），用于内存分析

单应用路由上下文（1 个工具）

• adb_app_route_context — 将已安装的软件包解析为其 UID，并关联其生效的 ip rule 范围、路由表、网络策略、VPN 和默认网络状态，而不会更改路由或策略

UI（10 个工具）

• adb_screencap — 截取屏幕，清理文件名后保存到本地
• adb_screencap_annotated — 截屏并将 UI 元素的边界框和编号标签合成到 PNG 中。返回标注图像路径和文本图例。适用于按编号引用元素的 LLM 工作流
• adb_current_activity — 获取当前焦点 Activity 和顶部窗口堆栈
• adb_input — 发送点击、滑动、文本或按键事件输入
• adb_start_activity — 通过 intent 或组件名称启动 Activity
• adb_ui_dump — 导出完整 UI 层级结构。支持三种输出格式：text（默认，便于阅读）、tsv（紧凑的制表符分隔格式，适用于节省 token 的自动化循环）、xml（原始 uiautomator XML）
• adb_ui_find — 按文本、resource-id 或 content-description 搜索 UI 层级结构（返回点击坐标）
• adb_screen_state — 在一次调用中获取组合屏幕状态：前台 Activity、屏幕尺寸和密度、方向、电池电量，以及交互元素的 TSV 列表。可替代 3–4 次单独的工具调用
• adb_screenrecord_start — 开始录制设备屏幕（1–180 秒，录制文件存储在设备上）
• adb_screenrecord_stop — 停止录制，并将 mp4 视频文件拉取到本地

设备控制（9 个工具）

• adb_airplane_mode — 切换飞行模式，并通过广播进行验证
• adb_airplane_cycle — 循环切换飞行模式，以强制蜂窝网络重新注册
• adb_wifi — 启用或禁用 WiFi
• adb_mobile_data — 启用或禁用移动数据
• adb_location — 设置定位模式（off/sensors/battery/high）
• adb_screen — 唤醒、休眠、切换、锁定或解锁屏幕。锁定时通过 dumpsys window 验证 keyguard 状态。解锁时使用 wm dismiss-keyguard（适用于滑动解锁界面）；提供 pin 可执行完整的 PIN 输入流程：唤醒屏幕、向上滑动以显示键盘、输入 PIN、确认，并验证 keyguard 的休眠令牌已释放
• adb_settings_get — 从 system/secure/global 命名空间读取任意 Android 设置
• adb_settings_put — 写入任意 Android 设置，并通过回读验证
• adb_reboot — 重启设备（普通、recovery 或 bootloader 模式）

无线调试（4 个工具）

• adb_pair — 使用配对码通过 WiFi 与设备配对
• adb_connect — 通过 WiFi/TCP 连接到设备
• adb_disconnect — 断开无线设备的连接
• adb_tcpip — 将 USB 设备切换到 TCP/IP 模式（自动检测设备 IP）

端口转发（8 个工具）

• adb_forward — 将本地端口转发到设备端口（主机 → 设备）
• adb_reverse — 将设备端口反向转发到主机（设备 → 主机）
• adb_forward_list — 列出所有活动的正向和反向端口映射
• adb_forward_remove — 移除端口转发或所有转发
• adb_reverse_remove — 移除反向转发或所有反向转发
• adb_tunnel_open — 使用不透明 ID 打开受管理的隧道。若未指定正向转发的主机端口，则自动选择一个空闲端口；注册清理操作，以便在服务退出时移除隧道
• adb_tunnel_list — 列出活动的受管理隧道（通过 adb_tunnel_open 打开的隧道）。可选设备筛选；显示 ID、方向、端点和已持续时间
• adb_tunnel_close — 按 ID 关闭受管理的隧道，或使用 id="all" 一次关闭所有隧道

模拟器管理（3 个工具）

• adb_avd_list — 列出可用的 AVD（PC 模式），或检测 KVM/QEMU 虚拟化能力（设备端模式）
• adb_emulator_start — 使用无头、冷启动和 GPU 选项启动 AVD（PC 模式），或报告 QEMU 替代方案（设备端模式）
• adb_emulator_stop — 正常关闭正在运行的模拟器

QEMU/KVM 虚拟化（8 个工具）

• adb_qemu_setup — 检查并安装 QEMU，以支持设备端虚拟化。验证 KVM，报告主机 CPU/RAM，并通过 Termux pkg 安装
• adb_qemu_images — 管理 VM 磁盘映像：列出、创建（qcow2/raw）、删除。通过路径包含关系验证防止路径遍历
• adb_qemu_start — 启动由 KVM 加速的 VM，并动态分配资源。自动检测最佳 CPU 数量（总数减 1，为主机预留一个）和内存（物理 RAM 的 65%）。支持 Android 启动所需的 kernel/initrd/append，以及 ADB 端口转发
• adb_qemu_stop — 停止运行中的 VM（优雅地发送 SIGTERM 或强制发送 SIGKILL）。终止前自动断开来宾 ADB 连接。未指定名称时报告正在运行的 VM
• adb_qemu_status — 完整状态：KVM/QEMU 可用性、主机资源预算、运行中的 VM（包含 PID/资源/运行时间/端口/ADB 连接状态）以及映像清单
• adb_qemu_connect — 连接到运行中 VM 的来宾 ADB 服务。仅限 localhost，端口根据运行中的 VM 状态确定，绝不使用用户输入。使多设备工具能够在来宾 VM 上运行
• adb_qemu_disconnect — 断开与来宾 VM 的 ADB 服务的连接。清除连接状态，并从设备列表中移除来宾设备
• adb_qemu_guest_shell — 通过 ADB 在来宾 VM 上执行 shell 命令。受安全中间件约束。来宾 serial 在内部确定，不会将用户提供的 host/IP 传递给 ADB 二进制文件

测试会话（3 个工具）

• adb_test_session_start — 启动命名测试会话，并创建结构化输出目录
• adb_test_step — 截取带编号的步骤，将截图和 logcat 保存到会话中
• adb_test_session_end — 结束会话，写入摘要清单，并返回目录路径

多设备编排（4 个工具）

• adb_multi_shell — 并行在所有设备或选定设备上执行命令（经过安全检查）
• adb_multi_install — 同时在多台设备上安装 APK
• adb_multi_compare — 在所有设备上运行命令，并突出显示输出差异
• adb_multi_test — 对比测试工作流：在所有设备（包括 QEMU 来宾设备）上运行预定义的诊断配置文件（firmware/security/network/identity/full）或自定义命令列表，逐项对比检查结果，并报告匹配项和差异

Wear 数据层（1 个工具）

• adb_wear_datalayer_preflight — 只读预检手机/手表角色、Google Play 服务、Bluetooth、可选软件包、配套设备关联状态和 Data Layer 服务；有意省略配对标识符

输入手势与 UI 自动化（15 个工具）

• adb_input_drag — 从 A 点拖动到 B 点（使用 draganddrop；较旧的 Android 版本会回退到 swipe）
• adb_input_fling — 高速滑动手势，用于惯性滚动列表和分页视图（可配置时长：20–200ms）
• adb_input_long_press — 在指定坐标长按，可配置按住时长
• adb_input_double_tap — 双击，可配置两次点击之间的间隔
• adb_input_text — 专用文本输入，支持空格和特殊字符
• adb_open_url — 通过 VIEW intent 在设备上打开 URL
• adb_orientation — 获取或设置屏幕方向（auto/portrait/landscape/reverse）
• adb_clipboard — 读取或写入设备剪贴板
• adb_input_pinch — 多点触控捏合（缩小）或张开（放大）手势。两根手指围绕中心点对称移动。分层注入：并行执行 input swipe（通用，无需 root），或使用原始 sendevent MT Type B 协议（真正的多点触控，需要 root）。通过 getevent -p 自动检测触摸屏设备及其能力。可配置中心点、半径、时长、角度和插值步数
• adb_tap_element — 根据文本/resource-id/content-description 查找元素，并点击其中心
• adb_wait_element — 轮询 UI 层级，直到元素出现或消失（可配置超时时间和轮询间隔）
• adb_wait_stable — 轮询，直到连续的 UI 转储内容一致（用于转场后的屏幕稳定检测）
• adb_scroll_until — 重复滚动，直到找到目标元素；可选择自动点击
• adb_screenshot_compressed — 截取屏幕截图，并附带大小/质量元数据，适用于节省 token 的工作流
• adb_batch_actions — 在一次工具调用中执行多个输入操作（tap/swipe/fling/long_press/double_tap/keyevent/text/drag/pinch/back/home/sleep），并进行安全验证

设备感知（3 个工具）

• adb_screen_size — 在一次调用中获取屏幕分辨率、显示密度（DPI）、宽高比和 DP 宽度
• adb_device_state — 综合快照：电池电量/状态/温度、网络类型、WiFi 状态、屏幕开关状态、方向、前台 Activity
• adb_notifications — 解析活动通知，包括 package、title、text、importance、channel、flags 和 timestamp（可按 package 筛选）

快照/恢复（3 个工具）

• adb_snapshot_capture — 将综合设备状态（软件包、设置、属性）保存为 JSON
• adb_snapshot_compare — 将当前状态与已保存的快照进行比较（新增/移除的软件包、已更改的设置）
• adb_snapshot_restore_settings — 从已保存的快照恢复全局/安全设置

网络抓包（3 个工具）

• adb_tcpdump_start — 通过 tcpdump 启动后台抓包（需要 root）
• adb_tcpdump_stop — 停止抓包，并将 pcap 文件拉取到本地，以便使用 Wireshark 分析
• adb_network_connections — 显示活动的 TCP/UDP 连接（使用 ss/netstat，或回退到 /proc/net）

CI/CD 集成（3 个工具）

• adb_ci_wait_boot — 等待设备/模拟器完全启动，可配置超时时间
• adb_ci_device_ready — 结构化的通过/失败就绪状态检查（启动、PM、屏幕、网络、磁盘）
• adb_ci_run_tests — 通过 am instrument 运行插桩测试，并解析通过/失败结果

基带/调制解调器（6 个工具）

• adb_baseband_info — 调制解调器固件、RIL 实现、芯片组、SIM 配置（检测双 SIM，并提供各插槽状态）、网络注册信息。仅在选择启用时获取 IMEI（includeImei=true）
• adb_cell_identity — 从 dumpsys phone 获取 CID、TAC/LAC、EARFCN、PCI、PLMN，用于蜂窝网络分析
• adb_signal_detail — RSRP、RSRQ、SINR、RSSI、定时提前量——用于信号分析的原始无线电测量数据
• adb_neighboring_cells — 所有可见的 LTE/5G/WCDMA/GSM 小区及其标识和信号强度
• adb_carrier_config — 运营商配置转储、运营商 ID、首选 APN
• adb_modem_logs — RIL 无线电缓冲区、电话框架、RILJ/RILC、内核 dmesg（root）调制解调器日志

无障碍审计（3 个工具）

• adb_a11y_audit — 自动化 WCAG 审计：缺少标签、触控目标尺寸过小（<48dp）、描述重复、无法聚焦的可点击元素
• adb_a11y_touch_targets — 列出所有交互元素的触控目标尺寸（以 dp 为单位），并标记尺寸过小的目标
• adb_a11y_tree — 以无障碍功能为重点的 UI 树，仅显示屏幕阅读器相关元素及其角色、标签和状态

回归检测（3 个工具）

• adb_regression_baseline — 捕获性能基线（内存、CPU、帧统计、电池、网络）并保存为 JSON
• adb_regression_check — 根据可配置的回归阈值，将当前性能与已保存的基线进行比较
• adb_regression_history — 列出所有已保存的基线及趋势，可按软件包筛选

设备农场（3 个工具）

• adb_farm_run — 在 Firebase Test Lab 上运行插桩测试，覆盖多种设备型号和 API 级别
• adb_farm_results — 获取 Test Lab 运行结果，或列出最近的测试矩阵
• adb_farm_matrix — 列出 Firebase Test Lab 上可用的设备型号和 Android 版本

插件注册表（3 个工具）

• adb_registry_search — 搜索社区插件注册表，显示安装状态和可用更新
• adb_registry_install — 按名称从注册表下载并安装插件
• adb_registry_installed — 列出本地已安装的插件及其版本和更新可用情况

插件（2 个工具）

• adb_plugin_list — 列出所有已加载插件的路径和加载时间
• adb_plugin_info — 插件系统文档和示例插件格式

构建（2 个工具）

• adb_gradle — 在项目目录中运行任意 Gradle 任务
• adb_build_and_install — 构建调试 APK，并通过 ANDROID_SERIAL 指定目标设备进行安装

AT 命令（6 个工具）

• adb_shannon_session — 同时检查 Shannon/Exynos 芯片组检测、root 权限、字符设备调制解调器端口，以及无害的 AT/OK 握手；支持 Google Tensor 的 /dev/umts_router，会重新启用有界 CPIF 读取，直到收到终止结果；可选发送只读的 ATI，绝不会发送调制解调器配置命令
• adb_at_detect — 按芯片组系列（Shannon、Qualcomm、MediaTek、Unisoc、通用型）自动检测调制解调器 AT 命令设备节点。探测已知路径并返回第一个有响应的节点
• adb_at_send — 向调制解调器发送单条 AT 命令并捕获响应。自动检测端口，也可手动指定。包含危险命令阻止列表，并支持强制覆盖
• adb_at_batch — 依次发送多条 AT 命令并提供每条命令的结果。可配置命令间延迟
• adb_at_probe — 运行标准诊断探测：调制解调器 ID、信号质量、网络注册、SIM 状态、运营商、功能模式
• adb_at_cross_validate — 通过将 AT 命令响应（ATI、AT+CGMR、AT+CGMM）与系统属性进行比较，交叉验证基带固件。将差异标记为可能的固件篡改、不完整的 OTA 或属性伪造。支持 Shannon 专用的 AT+DEVCONINFO。需要 root 权限

截图差异对比（3 个工具）

• adb_screenshot_baseline — 捕获并保存带有元数据（尺寸、SHA-256、时间戳）的命名截图基线
• adb_screenshot_diff — 使用像素级 PNG 解码，将当前屏幕与已保存的基线进行比较。报告变化像素的数量/百分比、变化区域的边界框，并支持设置容差阈值，以忽略时钟等动态元素
• adb_screenshot_history — 列出所有已保存的截图基线及其元数据

工作流编排（3 个工具）

• adb_workflow_run — 执行以 JSON 定义的工作流：依次执行设备操作，支持变量替换、条件步骤、循环和结果捕获。操作包括：shell、root_shell、install、screenshot、logcat、getprop、sleep
• adb_workflow_validate — 验证工作流结构但不执行，并显示执行计划
• adb_workflow_list — 列出 workflows 目录中已保存的工作流文件

Split APK 管理（4 个工具）

• adb_install_bundle — 通过 install-multiple 安装拆分 APK（应用套件），支持替换和降级选项
• adb_list_splits — 显示某个软件包的所有 APK 拆分路径及分类（base、config.density、config.language 等）和总大小
• adb_extract_apks — 将某个软件包的所有拆分 APK 拉取到本地目录，用于分析或备份
• adb_apex_list — 列出已安装的 APEX 模块及版本信息

设备镜像（3 个工具）

• adb_mirror_start — 通过 scrcpy 启动实时屏幕镜像。支持窗口和无头模式、录制、比特率/FPS/分辨率控制、保持唤醒和关闭屏幕
• adb_mirror_stop — 停止指定设备或所有设备的屏幕镜像
• adb_mirror_status — 检查 scrcpy 是否可用，并列出活跃的镜像会话

自动化测试生成（3 个工具）

• adb_test_gen_from_ui — 分析当前屏幕上的可交互元素，并生成一个逐一点击这些元素、截取屏幕截图并检查崩溃的工作流
• adb_test_gen_from_intents — 分析软件包已注册的 Activity，并生成一个逐一启动每个已导出 Activity 且检测崩溃的工作流
• adb_test_gen_save — 将生成的工作流 JSON 保存到 workflows 目录，供日后执行

OTA 更新监控（3 个工具）

• adb_ota_fingerprint — 捕获系统指纹：构建 ID、Android 版本、安全补丁、引导加载程序、基带固件、内核、A/B 槽位
• adb_ota_check — 将当前系统状态与已保存的指纹进行比较，以检测 OTA 更新。标识发生变化的字段，并建议重新建立基准
• adb_ota_history — 列出设备所有已保存的指纹及其随时间推移的版本变化

RIL 消息拦截（3 个工具）

• adb_ril_start — 开始从 radio logcat 缓冲区捕获 RIL 消息。按注册、蜂窝信息、信号、网络、安全、切换和 NAS 事件分类
• adb_ril_poll — 检索捕获的 RIL 消息，可按类别筛选。显示类别分布
• adb_ril_stop — 停止 RIL 捕获会话并显示类别摘要

设备配置档案（3 个工具）

• adb_profile_detect — 自动检测并构建设备配置档案：硬件 ID、芯片组系列、调制解调器节点、Root 状态、5G 支持、双 SIM 配置。与内置库匹配以识别已知问题
• adb_profile_save — 将设备配置档案保存到配置档案库
• adb_profile_list — 列出内置和用户保存的设备配置档案

调制解调器固件分析（3 个工具）

• adb_firmware_probe — 全面识别固件：将基带（Shannon/Qualcomm/MediaTek/Unisoc/HiSilicon/Intel）、引导加载程序和 RIL 实现解析为结构化组件。报告内核、安全补丁、A/B 槽位、验证启动状态、VBMeta、虚拟机监控程序和 OTA 分区清单
• adb_firmware_diff — 比较已保存指纹或实时设备之间的所有固件组件（基带、引导加载程序、内核、安全补丁、构建 ID、Android 版本、RIL）。检测到变化时，提供基带和引导加载程序的深度解析差异
• adb_firmware_history — 跟踪所有已保存 OTA 指纹中的固件变化，检测多个组件的变更（基带、引导加载程序、内核、安全补丁、构建 ID、Android 版本），并提供解析后的基带差异

无线固件（4 个工具）

• adb_wifi_firmware — WiFi 芯片组和固件识别：驱动版本、固件版本、支持的频段（2.4/5/6 GHz）、WiFi 标准检测（5/6/6E/7）、当前连接信息。MAC 地址仅在用户选择时提供
• adb_bluetooth_firmware — Bluetooth 固件和芯片组识别：固件版本、BT 版本（根据 LMP 判断，4.0–5.4）、适配器状态、LE 功能（2M PHY、Coded PHY、扩展广播）、活动配置文件（A2DP/HFP/HID/LE Audio）、已绑定设备数量。MAC 地址和名称仅在用户选择时提供
• adb_nfc_firmware — NFC 控制器固件：控制器类型（NXP/Broadcom/Samsung/ST）、固件版本、支持的技术（NFC-A/B/F/V、MIFARE）、安全元件（eSE/UICC）、HCE 支持
• adb_gps_firmware — GNSS/GPS 芯片组和固件识别：硬件型号（制造商、芯片、固件）、支持的星座（GPS/GLONASS/Galileo/BeiDou/QZSS/NavIC/SBAS）、含频率的信号类型、双频（L1+L5）检测、原始 GNSS 测量能力、A-GPS 模式（MSB/MSA）、SUPL 服务配置、载波相位测量

工作流市场（3 个工具）

• adb_market_search — 按关键词和标签筛选，在工作流市场中搜索社区分享的工作流定义。显示安装状态
• adb_market_install — 下载、验证（JSON 结构 + SHA-256 完整性）并安装市场工作流，以便立即通过 adb_workflow_run 使用
• adb_market_export — 为本地工作流打包市场元数据（作者、版本、标签、SHA-256），并生成注册表清单条目以供分享

SELinux 和权限审计（3 个工具）

• adb_selinux_status — SELinux 强制模式、策略版本、shell 上下文、近期 AVC 拒绝次数。Root 权限可提供内核 dmesg 拒绝统计
• adb_selinux_denials — 列出近期 AVC 拒绝消息，并解析源/目标上下文、权限类别和被拒绝的操作。支持按进程筛选
• adb_permission_audit — 按危险权限类别（相机、位置、电话、短信等）对软件包的运行时权限授权进行审计。标记高敏感度授权

热量和电源分析（3 个工具）

• adb_thermal_snapshot — 捕获所有热区温度、各 CPU 频率/调速器、散热设备状态、电池温度/电流/电压/功耗。可选择保存为 JSON 基线
• adb_thermal_compare — 将当前热状态与已保存的基线进行比较，显示各热区温度变化和电池电流变化
• adb_battery_drain — 在可配置的时长（3-60s）内测量电池耗电率。报告平均 mA、mW 和估算的每小时百分比。可选择获取特定软件包的 batterystats

网络发现（3 个工具）

• adb_network_scan — 通过 ARP 表和可选的 IP 范围扫描，在本地网络中扫描启用了 ADB 的设备。通过批量并行 TCP 探测检查端口 5555-5558
• adb_network_device_ip — 通过多种方法获取已连接设备的 WiFi IP。显示 ADB TCP 状态和无线连接说明
• adb_network_auto_connect — 一步完成发现和连接：扫描 ADB 设备，并自动对每个找到的监听设备运行 adb connect

硬件传感器访问（2 个工具）

• adb_sensor_read — 通过 dumpsys sensorservice 读取当前硬件传感器值。枚举所有传感器及其供应商、类型、模式、速率范围和唤醒能力。返回带时间戳的最近读数，并按坐标轴标注格式显示。支持类别筛选（13 个类别）和仅列出发现模式。无需 Root 权限
• adb_iio_read — 从 Linux IIO 子系统读取原始硬件数据。自动发现 IIO 设备，并按内核驱动分类。在 Tensor/Exynos 设备上：提供各电源轨的 ODPM 功耗监视器，显示 SoC 子系统的实时功耗。通用 IIO 路径支持带校准比例和偏移的原始通道数据。需要 Root 权限

结果句柄（3 个工具）

• adb_result_list — 列出临时目录缓存中的活动结果句柄。显示每个句柄对应的工具、名称、大小、存续时间和剩余 TTL
• adb_result_get — 按工具和名称检索已存储句柄的内容。返回源工具生成的原始内容块，并更新最近访问时间。若要通过 URI 检索，请改用 result://{tool}/{name} MCP 资源
• adb_result_drop — 删除已存储的结果句柄，或清空当前命名空间中的所有句柄。传入 tool 和 name 可删除指定句柄；传入 all: true 可删除全部句柄。在更改 DA_AUTH_TOKEN 前使用此工具很有帮助（否则旧令牌哈希目录下会留下孤立句柄）

MCP 资源（5 个）

MCP 客户端可访问的只读设备状态：

• device://list — 列出所有已连接设备及其状态和型号信息
• device://info/{serial} — 设备属性（型号、操作系统、构建版本、ABI）
• device://battery/{serial} — 解析后的电池状态（电量、充电状态、温度、电压）
• device://telephony/{serial} — 用于蜂窝网络分析的电话注册状态
• result://{tool}/{name} — 已存储的工具结果句柄。通过 URI 解析；由通过 result_handle 参数启用结果句柄存储的工具创建。由 adb_result_list 列出

MCP 提示词（4 个）

针对常见多步骤调试任务预先构建的工作流模板：

• debug-crash — 清除 logcat → 重启应用 → 等待复现 → 捕获崩溃缓冲区 → 分析
• deploy-and-test — 构建 → 安装 → 清除 logcat → 启动监视器 → 启动应用 → 截屏 → 报告
• telephony-snapshot — 捕获电话状态、SIM 卡／网络运营商、网络类型 → 总结异常
• airplane-cycle-test — 启动监视器 → 获取电话状态基线 → 切换飞行模式 → 比较切换前后的状态

主要功能

设备缓存

设备发现结果会按可配置的 TTL 进行缓存（默认 5s），避免在快速连续调用工具时重复启动 adb devices 子进程。缓存会在连接错误时自动失效，也会在无线连接、断开连接或配对操作后失效。

瞬时故障重试

ADB 桥接会针对瞬时故障（设备离线、连接重置、协议错误）自动重试，重试次数和指数退避时间均可配置。诊断命令会跳过重试，以便立即显示实际问题。

输出保护

所有 ADB 输出都会经过 OutputProcessor 处理，用于规范换行符、限制可配置的字符数，并在逻辑边界（换行、章节分隔符）处截断以保留上下文，而不是从行中间截断。还包含用于解析电池、meminfo 和 getprop 输出的结构化解析器。

持久化 Logcat 流

后台 logcat 监视器作为生成的进程运行，并使用环形缓冲区累积内容。每次轮询只返回自上次读取后新增的行。支持多个并发会话（最多 10 个），每个会话可使用独立筛选条件。进程清理处理程序可在服务退出时防止残留 adb logcat 进程。

UI 层级分析

通过 uiautomator dump 完整捕获视图树，并解析 XML。返回结构化的元素数据，包括文本、resource-id、content-description、类名、边界坐标及可直接用于点击的中心点，以及交互标记。通过预编译的正则表达式提取属性，提高解析效率。

安全中间件

通过 DA_SECURITY=true 启用多层安全防护。提供命令阻止列表／允许列表筛选、速率限制（每分钟命令数）以及自动隐藏凭据的审计日志。安全检查集成于 adb_shell、adb_root_shell、adb_multi_shell、adb_multi_compare、adb_input、adb_batch_actions 和 adb_start_activity。可通过环境变量针对不同部署场景进行配置。

输入净化

所有将用户提供的参数插入 shell 命令字符串的工具，都会在执行前检查输入中是否包含 shell 元字符。包名、属性键、服务名称、设置键、测试标识符、网络接口名称和 tcpdump 过滤器都会通过集中式 validateShellArg() 函数进行验证，该函数会拒绝 ;、|、&、$、反引号、括号和其他注入途径。文件路径使用单引号进行 shell 转义，以防止 $() 命令替换。adb_input 工具会按类型验证输入：tap/swipe 只接受数字坐标，keyevent 只接受字母数字键码，text 则会进行 shell 转义，以便按字面内容输入。adb_batch_actions 工具会针对每种操作类型执行相同的验证（坐标只能包含数字，键码只能包含字母数字字符，文本进行 shell 转义），并通过安全中间件传递每条组装后的命令。对快照文件反序列化得到的 JSON 会先经过验证，再插入 shell 命令。全部 209 个工具中的每个 z.number() 参数都显式设置了 .min()/.max() Zod 边界，以防止极端值导致资源耗尽。LocalBridge 针对工具模块使用的每条 ADB 子命令都有显式处理程序，避免未加引号的命令落入默认 shell 处理程序。在设备端模式下，权限提升使用固定的 16 条命令允许列表和受限路径正则表达式——权限提升集合采用 ReadonlySet + Object.freeze，运行时无法配置。HTTP/SSE 传输默认拒绝跨域请求（可通过 DA_HTTP_CORS_ORIGIN 配置），插件注册表会验证 SHA-256 完整性哈希，并通过目录包含性检查防止路径遍历；工作流引擎会限制步骤数量（200）、休眠时长（5 min）和重复迭代次数（100）。获取辅助函数会将响应正文限制为 5 MB。解析 getprop 输出时，会在正则匹配前调用 .trim()，以处理 Windows 的 \r\n 行尾；双 SIM 卡槽数量上限为 4，以防设备属性损坏导致资源耗尽。

多设备编排

并行运行命令、安装 APK，并比较多台已连接设备的输出。对于跨 Android 版本和设备型号的对比测试至关重要。

快照/还原

将全面的设备状态快照（软件包、所有命名空间中的设置、系统属性）保存为 JSON 文件。将当前状态与已保存的快照进行比较，以检测状态偏移。从快照还原设置，以创建可复现的测试环境。

网络流量捕获

在设备端通过 tcpdump 捕获数据包，并拉取 pcap 文件供 Wireshark 分析。还可通过 ss/netstat 列出活动连接；对于不具备这些工具的设备，则回退使用 /proc/net。

CI/CD 集成

为自动化流水线打造的工具：通过轮询等待设备启动，执行结构化就绪检查，并运行带解析后通过/失败结果的插桩测试。

插件架构

从可配置的 plugins 目录动态加载工具模块。插件是标准 JavaScript ESM 模块，会导出接收完整 ToolContext 的 register(ctx) 函数。插件会在服务器启动时加载，支持社区贡献者参与，而无需修改核心代码。

社区插件注册表

从可配置的注册表 URL 搜索、安装和管理插件。显示安装状态、版本比较和可用更新。将插件文件及其配套元数据下载到 plugins 目录，以便在下次重启时加载。安全功能包括 SHA-256 完整性验证（注册表清单提供时）、路径遍历防护，以及 register() 导出检查。

基带／调制解调器集成

面向高级 Android 开发和研究的深度蜂窝无线电检查工具。可提取调制解调器固件标识、小区身份参数（CID、TAC、EARFCN、PCI）、原始信号测量值（RSRP、RSRQ、SINR）、邻近小区扫描结果、运营商配置，以及来自多个来源的调制解调器日志（RIL 无线电缓冲区、电话框架、内核 dmesg）。通过标准 Android 电话 API 支持 Shannon／Exynos、Qualcomm、MediaTek 和 Unisoc 芯片组系列。包含 Google Tensor SoC 检测（gs101／gs201／zuma／zumapro），可在 Pixel 6–9 设备上自动路由到 Shannon 调制解调器路径。双 SIM 检测会针对 DSDS、DSDA 和 TSTS 配置，报告每个卡槽的 SIM 状态、运营商、网络类型和国家／地区。

无障碍审计

对实时 UI 层级进行自动化 WCAG 无障碍检查。可检测交互元素是否缺少标签、触控目标是否小于 48dp 指南尺寸（会根据屏幕密度调整）、图片是否缺少 content-description、可点击元素是否缺少可聚焦性，以及 content-description 是否重复。生成带有严重级别的结构化报告。包含专用无障碍树视图，便于调试屏幕阅读器。

回归检测

采集性能基线（内存、CPU、帧统计、电池、网络状态），并与后续运行结果进行比较。可配置内存（+20%）、CPU（+50%）和卡顿率（+25%）的回归阈值。保留基线历史记录，以便分析不同版本间的趋势。

设备群集成

通过 gcloud CLI 使用 Firebase Test Lab 在云端执行测试。可在多种设备型号和 API 级别上运行检测测试、获取结构化结果，并列出可用的测试矩阵配置。如果 gcloud 不可用，则会优雅地回退并提供设置说明。

HTTP／SSE 传输

作为面向基于浏览器的 MCP 客户端的 stdio 替代方案。设置 DA_HTTP_PORT 即可启动支持 SSE 流式传输的 HTTP 服务。提供 /sse（客户端订阅）、/message（JSON-RPC）和 /health 端点。默认拒绝跨域请求；设置 DA_HTTP_CORS_ORIGIN 可明确允许特定来源。

测试会话管理

通过编号步骤组织测试工作流。每个步骤都会将屏幕截图和 logcat 快照保存到结构化目录中，并附带 Markdown 清单。专为可复现的测试文档设计。

AT 命令接口

通过 root 权限直接将 AT 命令传递给调制解调器，从而实现 Android 电话框架之外的原始查询。支持多种芯片组，可自动检测 Samsung Shannon／Exynos、Qualcomm Snapdragon、MediaTek、Unisoc／Spreadtrum 和通用 USB 调制解调器的设备节点。在插入 root shell 前，会对 AT 命令字符串和设备节点路径中的输入进行验证，拒绝 shell 元字符。安全阻止列表可防止意外执行危险命令（AT+CFUN=0、AT+EGMR 等），并提供明确的强制覆盖选项。

屏幕截图差异比较

真正的像素级视觉回归检测。捕获命名的屏幕截图基线，并通过解码 PNG 像素数据（IHDR 解析、IDAT 解压、全部 5 种 PNG 过滤器类型）并比较实际 RGB 值，来对比当前屏幕状态。报告变化像素的数量和百分比、变化区域的边界框及其垂直屏幕位置，以及尺寸／大小差异。支持 tolerancePercent 参数（0–100），可忽略时钟显示或通知徽章等细微动态变化——1% 的容差可可靠地忽略导航栏时钟变化（约占 0.5% 的像素），同时捕获任何真实 UI 回归。完全匹配时使用 SHA-256 快速检查。无外部依赖。

工作流编排

声明式 JSON 工作流引擎，用于可重复执行多步骤设备操作。支持变量替换（{{pkg}}）、条件步骤（使用 ==、!=、contains 表达式）、循环（repeat，最多 100 次迭代），以及将结果捕获到变量中供后续步骤使用。操作直接映射到 ADB 桥接操作，并完整执行安全中间件检查。工作流验证将步骤数限制为最多 200 步，并将每步休眠时间限制为 5 分钟，以防恶意或格式错误的工作流定义耗尽资源。

Split APK 管理

支持现代 Android 分发格式。通过 install-multiple 安装应用套件，检查 Split APK 结构（基础 APK + 语言、密度、ABI 配置拆分包），在本地提取所有拆分包以供分析，并列出 APEX 模块。

设备镜像

通过 scrcpy 集成实时镜像屏幕。支持窗口模式以提供视觉反馈，也支持仅录制工作流所需的无头模式。按设备跟踪会话，支持同时镜像多个已连接设备。进程清理处理程序可防止 scrcpy 进程成为孤儿进程。

自动生成测试

分析实时 UI 层级结构和软件包 Intent 注册信息，自动生成与工作流编排引擎兼容的测试工作流 JSON。基于 UI 的生成会点击每个可交互元素、截取屏幕截图并检查是否发生崩溃。基于 Intent 的生成会启动每个已导出的 Activity 并检测崩溃。

OTA 更新监控

跨会话跟踪完整的系统指纹（构建 ID、Android 版本、安全补丁、引导加载程序、基带固件、内核版本、A/B 分区槽位）。将当前状态与已保存的指纹进行比较，以检测 OTA 更新。准确识别发生变化的字段，并建议在更新后重新建立性能指标和屏幕截图的基准。

RIL 消息拦截

从 Android radio logcat 缓冲区持续捕获 Radio Interface Layer 消息。启动后台进程，将 RIL 消息累积并分类为：registration、cell_info、signal、network、security、handover、data、radio_state、sms 和 NAS 事件。支持按类别筛选并通过轮询获取结果。适用于被动监控基带与框架之间的通信，以进行无线电诊断和蜂窝网络研究。会话数量上限（5）和进程清理处理程序可防止资源耗尽。

设备配置文件库

包含特定设备知识的知识库，涵盖硬件识别信息、芯片组系列、已知调制解调器设备节点、AT 命令兼容性、Root 要求、双 SIM 卡槽数量及设备特性。自动检测已连接设备的配置文件，并与内置的已知设备库进行匹配。已保存的配置文件会在不同会话间保留，并提高 adb_at_detect 等工具的自动检测准确率。可通过已保存的配置文件进行社区扩展。

WebSocket 传输

为适合使用真正双向流式传输的 MCP 客户端提供 stdio 和 HTTP/SSE 之外的另一种选择。与 SSE 轮询相比延迟更低，且与 Web 框架的兼容性更好。需要将 ws npm 包作为可选的对等依赖项。设置 DA_WS_PORT 即可启用。

调制解调器固件分析

全面识别、比较并追踪多组件固件历史。解析 6 个芯片组系列的基带版本字符串：Shannon/Exynos（包括 Google Pixel/Tensor g5123b-* 格式和经典 Samsung S5123AP_CL* 格式）、Qualcomm MPSS 分支/版本/构建、MediaTek MOLY 分支/发行版/里程碑、Unisoc/Spreadtrum SoC 型号/版本、HiSilicon/Kirin 型号/运营商代码，以及 Intel XMM 型号/分支。还会解析引导加载程序版本（Pixel 代号/版本/构建、Samsung 型号/运营商/修订版）和 RIL 实现字符串（Samsung S.LSI 供应商/ID/API/构建日期、Qualcomm、MediaTek）。固件探测器会报告 8 个部分：基带、引导加载程序、RIL、内核、安全/构建、分区/启动（A/B 槽位、安全启动、验证启动、刷写锁定）、VBMeta 完整性，以及 OTA 分区清单。差异工具会比较已保存的指纹或实时设备状态中的所有固件组件，并提供基带和引导加载程序的深度解析差异。历史工具会跨 OTA 指纹追踪多组件固件的演进。

工作流市场

为工作流编排引擎提供社区共享层。搜索由社区贡献的测试工作流、诊断序列和审计流程注册表。直接下载并安装工作流，即可立即通过 adb_workflow_run 执行。导出本地工作流时，会附带市场元数据并自动生成注册表清单条目，以便提交。下载时会进行 SHA-256 完整性验证。

GraphQL API

可选 HTTP 端点，提供用于组合设备查询的 GraphQL API。客户端可在单个请求中获取设备信息、电池、网络和任意属性，而无需多次调用 MCP 工具。POST 正文大小限制为 1 MB。每次解析时都会预先获取设备属性一次，以尽量减少子进程调用。需要将 graphql npm 包作为可选对等依赖项。设置 DA_GRAPHQL_PORT 即可启用。

SELinux 与权限审计

检查 SELinux 强制模式，从 logcat 和内核审计日志中查询 AVC 拒绝记录，并审计各个包的运行时权限授予情况。按危险类别（相机、位置、电话、短信等）对已授予权限进行分组，并标记后台位置和管理外部存储等高敏感度授权。将安全审计范围扩展至操作系统权限层。

温度与电源分析

从 sysfs 捕获温度区域温度、每个 CPU 的频率缩放状态和调速器、散热设备活动情况，以及电池耗电速度。通过温度/电源基线补充回归检测，以排查表现为发热或耗电而非帧率下降的问题。包含定时耗电测量，并计算 mA、mW 和每小时估算百分比。

网络设备发现

通过查询 ARP 表和可选的 IP 范围扫描，在本地网络中搜索启用了 ADB 的设备。通过批量并行 TCP 连接尝试探测常见 ADB 端口（5555-5558）。使用多种方法提取设备的 WiFi IP。自动连接模式可在一个步骤中发现并连接设备。简化无线调试工作流。

QEMU/KVM 虚拟化

使用 QEMU 和 KVM 硬件加速，在设备上管理虚拟机。可直接在实体设备上运行来宾 Android 虚拟机——这是 DeepADB 独有的功能。动态资源分配会自动检测主机 CPU 核心数和物理内存，并为主机操作系统预留 1 个核心和 35% 的内存，以防资源耗尽。多虚拟机支持会跟踪并发虚拟机的资源消耗；资源池耗尽时会拒绝启动新虚拟机，而不是降低主机性能。支持使用 qcow2（稀疏、支持快照）和 raw 格式管理磁盘映像。通过 ADB 端口转发连接来宾虚拟机，使 DeepADB 的完整工具套件能够同时面向主机和来宾设备。进程生命周期通过集中式清理注册表进行跟踪，并使用 SIGTERM/SIGKILL 关闭进程。所有映像操作均会验证路径包含关系，以防止目录遍历。

ToolContext 架构

所有 49 个工具模块都会接收统一的 ToolContext 依赖包，其中包含 server、bridge、deviceManager、logger、security 和 config。添加新的横切依赖无需更改模块签名。

环境变量

变量	默认值	描述
DA_LOCAL	自动检测	强制启用设备端模式（true/false）。通过 /system/build.prop 自动检测
ADB_PATH	自动检测	ADB 二进制文件的路径（设备端模式下忽略）
DA_TIMEOUT	30000	默认命令超时时间，单位为毫秒
DA_MAX_OUTPUT	50000	截断前的最大输出字符数
DA_MAX_LOGCAT	500	每个快照的最大 logcat 行数
DA_DEVICE	（自动）	默认设备序列号（仅有一台设备时自动选择）
DA_TEMP_DIR	操作系统临时目录	截图、拉取的文件、错误报告、测试会话和快照的临时目录
DA_CACHE_TTL	5000	设备列表缓存生存时间，单位为毫秒（0 = 禁用）
DA_RETRY_COUNT	1	ADB 瞬时故障的重试次数
DA_RETRY_DELAY	500	基础重试延迟，单位为毫秒（每次尝试时翻倍）
DA_LOG_LEVEL	info	日志级别：debug、info、warn、error
DA_ASCII_ONLY	（自动检测）	设置为 1，在启动警告横幅中强制仅输出 ASCII。默认通过 WT_SESSION/TERM_PROGRAM/TERM 自动检测终端是否支持 Unicode；对于旧版 cmd.exe，则回退为 ASCII。
DA_RESOURCE_CACHE_TTL_MS	0（禁用）	MCP 资源缓存生存时间，单位为毫秒。设置为正值后，将在此时间内缓存资源读取结果（device://info、device://battery 等）。
DA_RESULT_HANDLE_DIR	{tempDir}/result-handles	临时目录支持的工具结果句柄的存储根目录。可通过覆盖此值，将存储位置移出默认临时目录。
DA_RESULT_HANDLE_TTL	43200（12 小时）	每个句柄的生存时间，单位为秒。超过此时间的句柄会在启动扫描和定期清理时被移除。范围限制为 [60, 7 天]。
DA_RESULT_HANDLE_MAX_BYTES	5242880（5 MB）	每个句柄的大小上限。尝试存储超过此大小的内容块时，工具会报错。
DA_RESULT_HANDLE_TOTAL_BYTES	104857600（100 MB）	所有句柄的结果句柄存储总大小上限。超过此上限时会触发 LRU 淘汰。
DA_RESULT_HANDLE_MAX_COUNT	100	活跃句柄的最大数量。超过此上限时会触发 LRU 淘汰。
DA_SECURITY	false	启用安全中间件（命令过滤、速率限制）
DA_BLOCKED_COMMANDS	（无）	以逗号分隔的被阻止 shell 命令子字符串列表
DA_ALLOWED_COMMANDS	（无）	以逗号分隔的允许列表（若设置，则仅运行匹配的命令）
DA_RATE_LIMIT	0	每分钟最大命令数（0 = 不限）
DA_CI_PING_TARGET	1.1.1.1	adb_ci_device_ready 使用的网络可达性检测目标（网络可达性是就绪检查之一，其他检查包括启动完成、ADB 授权和软件包管理器可用）。如果 1.1.1.1 被防火墙阻止，可覆盖此值以指向内部目标。
DA_AUDIT_LOG	true	记录所有已执行的命令以供审计（设置为 false 可禁用）
DA_PLUGIN_DIR	{tempDir}/plugins	启动时扫描插件 .js 模块的目录
DA_REGISTRY_URL	GitHub 默认值	社区插件注册表 JSON 清单的 URL
DA_HTTP_PORT	（禁用）	设置端口号以启用 HTTP/SSE 传输模式
DA_HTTP_HOST	127.0.0.1	HTTP/SSE、WebSocket 和 GraphQL 服务的绑定地址
DA_AUTH_TOKEN	（无 — 开放）	网络传输的 Bearer 令牌。设置后，所有 HTTP/SSE/WS/GraphQL 请求都必须包含 Authorization: Bearer <token> 标头。健康检查端点除外。
DA_HTTP_CORS_ORIGIN	（无 — 拒绝）	HTTP/SSE 允许的 CORS 源
DA_WS_PORT	（禁用）	设置端口号以启用 WebSocket 传输模式（需要 npm install ws）
DA_WS_CORS_ORIGIN	（无 — 拒绝）	WebSocket 健康检查端点允许的 CORS 源
DA_GRAPHQL_PORT	（禁用）	设置端口号以启用 GraphQL API 端点（需要 npm install graphql）
DA_GRAPHQL_CORS_ORIGIN	（无 — 拒绝）	GraphQL API 允许的 CORS 源
DA_WORKFLOW_REGISTRY_URL	（根据 DA_REGISTRY_URL 派生）	工作流市场 JSON 清单的 URL
DA_TEST_PIN	（无）	tests/test-ui-control.mjs 用于执行屏幕锁定/解锁测试的数字 PIN。未设置时，4 项锁定状态测试会跳过。格式：DA_TEST_PIN=0000 npm test。

项目结构

DeepADB/
├── src/
│   ├── index.ts                # Entry point — stdio, HTTP/SSE, WebSocket, or GraphQL transport
│   ├── server.ts               # MCP server wiring, config, module registration (exports CreateServerResult)
│   ├── http-transport.ts       # HTTP/SSE transport server for browser clients
│   ├── ws-transport.ts         # WebSocket transport (optional `ws` peer dependency)
│   ├── graphql-api.ts          # GraphQL API endpoint (optional `graphql` peer dependency)
│   ├── tool-context.ts         # Unified dependency bundle (ToolContext interface)
│   ├── bridge/
│   │   ├── adb-bridge.ts       # Core ADB subprocess wrapper, retry logic, error types
│   │   ├── local-bridge.ts     # On-device direct execution bridge with privilege escalation (Termux/local mode)
│   │   └── device-manager.ts   # Device discovery, TTL cache, serial routing
│   ├── tools/
│   │   ├── health.ts           # Toolchain health check (1 tool)
│   │   ├── runtime-audit.ts    # Unified read-only runtime readiness audit (1 tool)
│   │   ├── device.ts           # Device info and properties (3 tools)
│   │   ├── shell.ts            # Shell and root command execution (2 tools)
│   │   ├── packages.ts         # App lifecycle, install, permissions, intents (12 tools)
│   │   ├── database-inspector.ts # Package-scoped read-only Room/SQLite inspection (1 tool)
│   │   ├── files.ts            # File operations — push, pull, write, find, grep, replace, stat, checksum, chmod, chown, touch, fsinfo (18 tools)
│   │   ├── logs.ts             # Logcat snapshots — filtered (3 tools)
│   │   ├── logcat-watch.ts     # Persistent logcat with ring buffer and poll (4 tools)
│   │   ├── diagnostics.ts      # dumpsys, telephony, battery, network, perf, bugreport, crash logs, heap dump (9 tools)
│   │   ├── ui.ts               # Screenshots, input, activity, UI hierarchy, annotated screencap, screen state (8 tools)
│   │   ├── input-gestures.ts   # Drag, long press, double tap, text, URL, orientation, clipboard, tap-element, wait-element, wait-stable, scroll-until, compressed screenshot, batch actions, fling, pinch, screen size, device state, notifications (18 tools)
│   │   ├── screen-record.ts    # Screen video recording start/stop (2 tools)
│   │   ├── control.ts          # Airplane, WiFi, data, location, screen, settings, reboot (9 tools)
│   │   ├── wireless.ts         # WiFi pairing, connect, disconnect, TCP/IP (4 tools)
│   │   ├── forwarding.ts       # Port forwarding — forward, reverse, list, remove, managed tunnels with auto-port-pick (8 tools)
│   │   ├── emulator.ts         # AVD list, start, stop with on-device KVM/QEMU detection (3 tools)
│   │   ├── qemu.ts             # QEMU/KVM VM management — setup, images, start, stop, status, guest ADB connect/disconnect/shell (8 tools)
│   │   ├── testing.ts          # Structured test sessions with numbered steps (3 tools)
│   │   ├── multi-device.ts     # Multi-device shell, install, compare, comparative testing (4 tools)
│   │   ├── snapshot.ts         # Device state capture, compare, restore (3 tools)
│   │   ├── network-capture.ts  # tcpdump start/stop, network connections (3 tools)
│   │   ├── ci.ts               # CI wait-boot, device-ready, run-tests (3 tools)
│   │   ├── plugins.ts          # Plugin loader, info, and dynamic tool loading (2 tools)
│   │   ├── baseband.ts         # Modem/baseband inspection and radio diagnostics (6 tools)
│   │   ├── accessibility.ts    # Automated WCAG accessibility auditing (3 tools)
│   │   ├── regression.ts       # Performance baseline and regression detection (3 tools)
│   │   ├── device-farm.ts      # Firebase Test Lab integration via gcloud (3 tools)
│   │   ├── registry.ts         # Community plugin registry search/install (3 tools)
│   │   ├── at-commands.ts      # AT command modem interface, Shannon session, cross-validation (6 tools)
│   │   ├── screenshot-diff.ts  # Visual regression — screenshot baseline/diff (3 tools)
│   │   ├── workflow.ts         # Declarative workflow orchestration engine (3 tools)
│   │   ├── split-apk.ts        # App bundles, split APKs, APEX modules (4 tools)
│   │   ├── mirroring.ts        # Live screen mirroring via scrcpy (3 tools)
│   │   ├── test-gen.ts         # Automated test workflow generation (3 tools)
│   │   ├── ota-monitor.ts      # OTA update monitoring and fingerprinting (3 tools)
│   │   ├── ril-intercept.ts    # RIL message interception from radio buffer (3 tools)
│   │   ├── device-profiles.ts  # Device profile library with built-in entries (3 tools)
│   │   ├── firmware-analysis.ts # Modem firmware version parsing and diffing (3 tools)
│   │   ├── workflow-market.ts  # Workflow marketplace — search, install, export (3 tools)
│   │   ├── selinux-audit.ts    # SELinux status, AVC denials, permission auditing (3 tools)
│   │   ├── thermal-power.ts    # Thermal zones, CPU frequency, battery drain (3 tools)
│   │   ├── network-discovery.ts # ADB-over-network scanning and auto-connect (3 tools)
│   │   ├── app-network.ts      # Per-app UID routing and network-policy context (1 tool)
│   │   ├── wear.ts             # Wear OS Data Layer phone/watch preflight (1 tool)
│   │   ├── sensors.ts          # Hardware sensor enumeration, IIO power monitor reading (2 tools)
│   │   ├── result-handles.ts   # Tempdir-backed result handle store — list, drop, drop-all (3 tools) + the result://{tool}/{name} resource
│   │   ├── wireless-firmware.ts # WiFi, Bluetooth, NFC, GPS firmware identification (4 tools)
│   │   ├── build.ts            # Gradle build and install (2 tools)
│   │   ├── resources.ts        # MCP Resources — 4 device-state surfaces: device://info|battery|telephony|list (5th, result://, lives in result-handles.ts)
│   │   └── prompts.ts          # MCP Prompts — workflow templates (4 prompts)
│   ├── middleware/
│   │   ├── auth.ts             # Bearer token authentication for network transports (DA_AUTH_TOKEN)
│   │   ├── output-processor.ts # Contextual truncation, structured parsers, settledValue helper
│   │   ├── security.ts         # Command filtering, rate limiting, audit logging with redaction
│   │   ├── sanitize.ts         # Shell injection prevention — validateShellArg/validateShellArgs/shellEscape
│   │   ├── chipset.ts          # Shared chipset family detection, modem path mapping, SIM config detection
│   │   ├── fetch-utils.ts      # Shared HTTP helpers with 5 MB streaming response size limit
│   │   ├── png-utils.ts        # Zero-dependency PNG decode/encode/draw primitives for screenshot annotation and diffing
│   │   ├── ui-dump.ts          # Shared uiautomator XML capture with concurrent-safe paths, on-device /data/local/tmp routing, and cleanup
│   │   ├── cleanup.ts          # Centralized process cleanup registry for SIGINT/SIGTERM/exit
│   │   ├── logger.ts           # stderr-safe logging (MCP-compliant)
│   │   ├── fs-utils.ts         # Filename sanitization, atomic write, private-dir helpers, within-dir containment check
│   │   ├── parse-utils.ts      # Shared parseIntSafe for env-var numeric parsing (single source of truth)
│   │   └── result-handle.ts    # Tempdir-backed tool result content cache with TTL, LRU, and token-hash isolation
│   └── config/
│       └── config.ts           # Configuration, env vars, startup validation
├── package.json
├── tsconfig.json
├── server.json                  # MCP Registry metadata (io.github.fullread/deepadb)
├── .gitignore
├── README.md
├── SECURITY.md                  # Threat model, security architecture, deployment hardening, vulnerability reporting
├── CHANGELOG.md                 # Version history from v0.1.0 to current
├── LICENSE                      # Apache 2.0 license
└── tests/
    ├── run-all.mjs              # Run all test suites sequentially with summary (tracks skipped counts)
    ├── test-hw.mjs              # Hardware core: health, identity, baseband, thermal, profiles, wireless firmware, crash analysis (34 tests)
    ├── test-shell-files.mjs     # Shell, filesystem, packages, diagnostics (24 tests)
    ├── test-ui-control.mjs      # UI hierarchy, screenshots, settings, input gestures, UI automation, device awareness, accessibility, screen lock/unlock, multi-touch (46 tests)
    ├── test-monitoring.mjs      # Logcat watchers, snapshots, OTA, regression, workflows (43 tests)
    ├── test-security.mjs        # Input sanitization, shell injection, AT command safety, QEMU shell escaping, heap-dump validation (116 on-device, 105 host)
    ├── test-lifecycle.mjs       # App lifecycle, file push/pull, input, port forwarding, screen recording, test sessions (24 tests)
    ├── test-analysis.mjs        # Thermal/snapshot/regression comparison, firmware diff, screenshot diff, test gen, RIL intercept, AT cross-validation, permission management (23 tests)
    ├── test-boundaries.mjs      # Zod bounds enforcement, input injection, error paths, sensitive data protection, wireless ADB coverage, multi-device basics, tunnel automation, device-free coverage boundaries (78 tests)
    ├── test-sensors.mjs         # HAL sensors, IIO power monitors, category filters, formatting, wake-up, rate display (30 tests)
    ├── test-files-extended.mjs  # File tool coverage — write, find, stat, checksum, mkdir, rm, move, copy, chmod, touch, fsinfo, chown, grep, replace; push safety; sed-escape regression (95 tests)
    ├── test-result-handles.mjs # Result handle store — listing, retrieval, drop, isolation, eviction (19 tests)
    ├── test-qemu.mjs            # QEMU/KVM setup, image management, VM status, guest connectivity errors (13 on-device tests)
    ├── test-qemu-boot.mjs       # QEMU Alpine VM boot with auto-fetch of kernel/initrd, KVM acceleration, topology detection, guest ADB connectivity (17 on-device tests)
    ├── test-supply-chain.mjs    # Supply-chain hardening checks for fetch and network paths (24 tests)
    ├── test-sanitize-fuzz.mjs   # Property-based fuzzing of shell sanitizers — shellQuote/shellEscape round-trip, validateShellArg rejection (19 tests)
    ├── test-transports.mjs      # Transport smoke — HTTP/SSE + WebSocket MCP round-trip, GraphQL health query (8 tests)
    └── lib/
        └── harness.mjs          # Shared test harness (stdio JSON-RPC transport, assertion primitives)

技术栈

• 运行时：Node.js ≥22（ES2024、ESM）
• 开发环境：使用 Node 22 系列的 Node.js 22.13+，或 Node 24+，以支持包括 ESLint 在内的完整工具链。仅 c8 覆盖率需要使用 Node 22 系列的 Node.js 22.12+。
• 语言：TypeScript 6.0（严格模式，NodeNext 模块解析）
• MCP SDK：@modelcontextprotocol/sdk ^1.32.1（当前解析为 1.32.1）
• 验证：Zod ^4.6.5
• 传输：stdio（JSON-RPC）、HTTP/SSE、WebSocket（可选 ws）、GraphQL API（可选 graphql）

许可证

Apache License 2.0 — 参见 LICENSE 和 NOTICE。v1.1.2 版本因明确的专利授权和贡献者署名要求，从 MIT 许可证迁移至 Apache 2.0；现有分支/安装仍适用此前的 MIT 条款。