DeepADB

面向 AI 代理的 MCP（模型上下文协议）服务器，用于通过 ADB 检查、控制、测试和诊断 Android 设备——或直接在设备上通过 Termux 运行。

204 个工具、5 个资源和 4 个提示词，分布在 45 个模块中——从 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 客户端配置中，然后从以下工作流开始：

有关引导式本地连接，请参阅 Claude Code 配置。在将 HTTP、WebSocket 或 GraphQL 传输暴露到回环地址之外之前，请阅读 SECURITY.md。

Related MCP server: android-mcp-server

架构

┌──────────────────────────────────────────────────┐
│                   MCP Client                     │
│             (Claude Code / claude.ai)            │
└──────────────────────┬───────────────────────────┘
                       │ stdio (JSON-RPC) or HTTP/SSE or WebSocket
┌──────────────────────▼───────────────────────────┐
│               DeepADB Server                     │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Tool Modules (45)                 │ │
│  │  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         │ │
│  ├─────────────────────────────────────────────┤ │
│  │  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 主机上运行，通过 USB 经由 ADB 与设备通信。全部 204 个工具均通过 ADB 桥接工作，并在瞬时故障时自动重试。

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

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

当 DeepADB 直接在 Android 设备上运行（例如在 Termux 内）时，它会自动检测环境并切换到 LocalBridge。命令通过 sh/su 直接执行——无需 ADB 服务器、无需 USB、无序列化开销。全部 204 个工具以相同方式工作，且延迟显著更低。

已在真实硬件上验证（Pixel 6a、Android 16、Termux + Magisk + QEMU 10.2.1），覆盖四单元测试矩阵——主机（ADB）和设备端（LocalBridge），每种模式分别在有和没有设备 PIN 的情况下——每个单元均为 0 失败。完整测试套件在主机/ADB 配置下为 577 个测试，设备端为 613 个；差异在于 QEMU 虚拟化和 Alpine VM 启动套件，它们仅在设备端运行：

• 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 VM 启动、big.LITTLE CPU 拓扑检测、客户机 ADB 连接错误处理以及干净的 VM 关闭；tcpdump 和 gracefulKill 套件也在此运行（root + POSIX）。跳过项：3 个 QEMU 设置步骤（当 Alpine 内核/initrd/磁盘已缓存时为空操作）、4 个屏幕状态测试（需要 PIN）。

• 设备端模式，有 PIN： 610 通过 / 0 失败 / 3 跳过（共 613 个）。环境中启用的每个测试均运行；3 个跳过项为缓存 VM 的设置步骤。

权限提升： 在 ADB 模式下，所有 shell 命令以 uid=2000（shell 用户）运行，该用户具有系统级权限。在 Termux 中，命令以普通应用用户身份运行。LocalBridge 在 root（Magisk）可用时，自动通过 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"]
    }
  }
}

可用工具（204 个）

从与您的任务匹配的能力区域开始；完整参考见下文。

完整工具参考

健康检查（1 个工具）

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

设备（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 — 按软件包名称启动应用（解析启动器 Activity）

• adb_restart_app — 在一次调用中强制停止然后重新启动（可配置延迟）

• adb_resolve_intents — 发现已注册的 Activity、服务和接收器及其 Intent 过滤器

文件（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 — 带标签、优先级、grep 和缓冲区选择的过滤 logcat 快照

• 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）以进行内存分析

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（紧凑制表符分隔，适合令牌高效的自动化循环）、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 — 设置定位模式（关闭/传感器/电池/高精度）

• adb_screen — 唤醒、休眠、切换、锁定或解锁屏幕。锁定通过 dumpsys window 验证锁屏状态。解锁使用 wm dismiss-keyguard（适用于滑动锁屏）；提供 pin 可执行完整 PIN 输入流程：唤醒屏幕、上滑显示键盘、输入 PIN、确认，并验证锁屏令牌已释放

• adb_settings_get — 从 system/secure/global 命名空间读取任意 Android 设置

• adb_settings_put — 写入任意 Android 设置并回读验证

• adb_reboot — 重启设备（正常、恢复模式或引导加载程序模式）

无线调试（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 — 启动 AVD，支持无头模式、冷启动和 GPU 选项（PC 模式）或报告 QEMU 替代方案（设备端模式）

• adb_emulator_stop — 优雅关闭正在运行的模拟器

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

• adb_qemu_setup — 检查并安装用于设备端虚拟化的 QEMU。验证 KVM，报告主机 CPU/内存，通过 Termux pkg 安装

• adb_qemu_images — 管理虚拟机磁盘镜像：列出、创建（qcow2/raw）、删除。路径包含验证防止目录遍历

• adb_qemu_start — 以动态资源分配启动 KVM 加速虚拟机。自动检测最佳 CPU 数量（总数减 1，为宿主机保留一个）和内存（物理 RAM 的 65%）。支持 kernel/initrd/append 参数用于 Android 启动，支持 ADB 端口转发

• adb_qemu_stop — 停止正在运行的虚拟机（优雅 SIGTERM 或强制 SIGKILL）。终止前自动断开客户机 ADB。未指定名称时报告正在运行的虚拟机

• adb_qemu_status — 完整状态：KVM/QEMU 可用性、宿主机资源预算、运行中的虚拟机（PID/资源/运行时长/端口/ADB 连接状态）、镜像清单

• adb_qemu_connect — 连接到运行中虚拟机的客户机 ADB 服务。仅限 localhost——端口从虚拟机运行状态派生，绝不接受用户输入。支持多设备工具操作客户机虚拟机

• adb_qemu_disconnect — 断开与客户机虚拟机的 ADB 服务连接。清除连接状态并从设备列表中移除客户机

• adb_qemu_guest_shell — 通过 ADB 在客户机虚拟机上执行 shell 命令。受安全中间件约束。客户机序列号内部派生——用户提供的主机/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 客户机在内的所有设备上运行预定义诊断配置文件（固件/安全/网络/身份/完整）或自定义命令列表，逐项比较，报告匹配和差异

手势输入与 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 — 获取或设置屏幕方向（自动/竖屏/横屏/反向）

• 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 — 截取带尺寸/质量元数据的截图，适合令牌高效工作流

• 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 — 解析活动通知，包含包名、标题、文本、重要性、渠道、标志和时间戳（可按包名过滤）

快照/恢复（3 个工具）

• adb_snapshot_capture — 将完整设备状态（包、设置、属性）保存为 JSON

• adb_snapshot_compare — 将当前状态与已保存快照进行差异对比（新增/移除的包、变更的设置）

• adb_snapshot_restore_settings — 从已保存快照恢复 global/secure 设置

网络捕获（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 — 结构化的通过/失败就绪检查（启动、包管理器、屏幕、网络、磁盘）

• adb_ci_run_tests — 通过 am instrument 运行仪器化测试，解析通过/失败结果

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

• adb_baseband_info — 调制解调器固件、RIL 实现、芯片组、SIM 配置（双 SIM 检测，含每卡槽状态）、网络注册。IMEI 获取仅限主动选择（includeImei=true）

• adb_cell_identity — 从 dumpsys phone 获取小区 ID（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 命令（5 个工具）

• 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 — 列出工作流目录中已保存的工作流文件

拆分 APK 管理（4 个工具）

• adb_install_bundle — 通过 install-multiple 安装拆分 APK（应用捆绑包），支持替换和降级选项

• adb_list_splits — 显示包的所有 APK 拆分路径，带分类（base、config.density、config.language 等）和总大小

• adb_extract_apks — 将包的所有拆分拉取到本地目录以进行分析或备份

• 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 保存到工作流目录以供后续执行

OTA 更新监控（3 个工具）

• adb_ota_fingerprint — 捕获系统指纹：构建 ID、Android 版本、安全补丁、引导加载程序、基带固件、内核、A/B 槽位

• adb_ota_check — 将当前系统状态与已保存的指纹进行对比以检测 OTA 更新。识别已更改的字段并建议重新建立基线

• adb_ota_history — 列出设备的所有已保存指纹，显示随时间推移的版本演进

RIL 消息拦截（3 个工具）

• adb_ril_start — 开始从无线电 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 — 蓝牙固件和芯片组识别：固件版本、蓝牙版本（来自 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-60 秒）内测量电池消耗速率。报告平均 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 个类别）和 listOnly 发现模式。无需 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（默认 5 秒）进行缓存，消除了快速工具序列期间重复的 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 插值之前会进行校验。所有 204 个工具中的每个 z.number() 参数都设置了显式的 .min()/.max() Zod 边界，以防止极端值导致资源耗尽。LocalBridge 为工具模块使用的每个 ADB 子命令提供了显式处理程序，防止未加引号时回退到默认 shell 处理程序。在设备端模式下，权限提升使用冻结的 16 条命令白名单和受限路径正则表达式——提升集合为 ReadonlySet + Object.freeze，运行时不可配置。HTTP/SSE 传输默认拒绝跨源请求（可通过 DA_HTTP_CORS_ORIGIN 配置），插件注册表验证 SHA-256 完整性哈希，并通过目录包含检查防止路径遍历，工作流引擎强制步骤数（200）、睡眠时长（5 分钟）和重复迭代次数（100）限制。Fetch 辅助函数强制 5 MB 响应体限制。Getprop 输出解析在正则匹配前通过 .trim() 处理 Windows \r\n 行尾，双 SIM 卡槽数量上限设为 4，以防止损坏的设备属性导致资源耗尽。

多设备编排

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

快照/恢复

将全面的设备状态快照（包、所有命名空间下的设置、系统属性）捕获到 JSON 文件。将当前状态与已保存的快照进行比较，以检测漂移。从快照恢复设置，以获得可重现的测试环境。

网络流量捕获

通过 tcpdump 在设备端进行数据包捕获，并拉取 pcap 文件以供 Wireshark 分析。包括通过 ss/netstat 列出活动连接，并为缺少这些工具的设备提供 /proc/net 回退。

CI/CD 集成

为自动化流水线专门构建的工具：轮询等待设备启动、结构化就绪检查，以及带解析通过/失败结果的插桩测试执行。

插件架构

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

社区插件注册表

从可配置的注册表 URL 搜索、安装和管理插件。显示安装状态、版本比较和可用更新。将插件文件连同配套元数据下载到插件目录，供下次启动时加载。安全功能包括 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 检测报告每个卡槽的 SIM 状态、运营商、网络类型和国家，适用于 DSDS、DSDA 和 TSTS 配置。

无障碍审计

在实时 UI 层级上自动执行 WCAG 无障碍检查。检测交互元素缺少标签、触摸目标小于 48dp 指南（密度感知）、图像缺少 content-descriptions、可点击元素缺少可聚焦性，以及重复的 content-descriptions。生成带有严重级别的结构化报告。包含专门的无障碍树视图，用于屏幕阅读器调试。

回归检测

捕获性能基线（内存、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 电话框架进行原始查询。多芯片组支持自动检测三星 Shannon/Exynos、高通 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 的 if 表达式）、循环（repeat，上限 100 次迭代），以及将结果捕获到变量中以供下游步骤使用。操作直接映射到 ADB 桥接操作，并强制执行完整的安全中间件。工作流验证强制最大 200 步和每步 5 分钟睡眠上限，以防止恶意或畸形工作流定义导致资源耗尽。

Split APK 管理

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

设备镜像

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

自动化测试生成

分析实时 UI 层级和包 intent 注册，自动生成与工作流编排引擎兼容的测试工作流 JSON。基于 UI 的生成会点击每个交互元素、截图并检查崩溃。基于 Intent 的生成会启动每个导出的 activity，并检测崩溃。

OTA 更新监控

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

RIL 消息拦截

持续从 Android 无线电 logcat 缓冲区捕获无线接口层（RIL）消息。派生一个后台进程，将 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核心和物理RAM，为宿主操作系统保留1个核心和35%的内存，以防止资源耗尽。多虚拟机支持跟踪并发虚拟机之间的资源消耗，当资源池耗尽时拒绝新虚拟机，而不是降低主机性能。磁盘镜像管理支持qcow2（稀疏、可快照）和raw格式。ADB端口转发到客户虚拟机，使DeepADB的完整工具套件能够同时针对主机和客户设备。通过集中式清理注册表跟踪进程生命周期，使用SIGTERM/SIGKILL关闭。对所有镜像操作进行路径包含验证，防止目录遍历。

ToolContext架构

所有45个工具模块接收统一的ToolContext依赖包，包含服务器、桥接器、设备管理器、日志器、安全性和配置。添加新的跨领域依赖无需修改模块签名。

环境变量

项目结构

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)
│   │   ├── 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)
│   │   ├── 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, multi-chipset, cross-validation (5 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)
│   │   ├── 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.12+ 用于覆盖率）

• 语言：TypeScript 6.0（严格模式，NodeNext 模块解析）

• MCP SDK：@modelcontextprotocol/sdk ^1.24.0（当前解析为 1.30.0）

• 校验：Zod ^4.4.3

• 传输：stdio（JSON-RPC）、HTTP/SSE、WebSocket（可选 ws）、GraphQL API（可选 graphql）

许可证

Apache License 2.0 — 参见 LICENSE 和 NOTICE。v1.1.2 版本从 MIT 迁移到 Apache 2.0，以满足明确的专利授权和贡献者署名要求；现有的分支/安装仍按之前的 MIT 条款有效。