fullread/DeepADB
GitHub: fullread/DeepADB
一个专为 AI 代理设计的全功能 ADB MCP 服务器，简化并扩展了 Android 设备调试的覆盖面与自动化水平。
Stars: 2 | Forks: 1
# DeepADB
MCP (Model Context Protocol) 服务器，提供完整的 Android Debug Bridge (ADB) 集成，专为 AI 代理设计。使得 MCP 客户端能够直接与连接的 Android 设备进行交互——检查状态、运行命令、管理应用、捕获日志、控制设备设置、分析 UI 层次结构、录制屏幕、管理模拟器、运行结构化测试会话、协调多设备操作、捕获网络流量、运行 CI 流水线、审计无障碍性、检测性能退化、执行云设备农场测试、通过 WiFi 调试、构建项目以及管理社区插件。
**180 种工具、4 种资源和 4 条提示**，覆盖 43 个模块——这是目前最全面的 ADB MCP 服务器，提供三重传输（stdio + HTTP/SSE + WebSocket）、可选 GraphQL API、纵深防御安全机制、调制解调器固件分析、工作流市场、AT 命令接口（支持多芯片组）、RIL 消息拦截、设备配置、基础带/调制解调器集成、自动化测试生成、OTA 更新监控、SELinux 审计、热/功耗分析、网络设备发现、视觉回归检测、工作流编排、无障碍审计以及上下文截断。
## 架构
```
┌──────────────────────────────────────────────────┐
│ MCP Client │
│ (Claude Code / claude.ai) │
└──────────────────────┬───────────────────────────┘
│ stdio (JSON-RPC) or HTTP/SSE or WebSocket
┌──────────────────────▼───────────────────────────┐
│ DeepADB Server │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Tool Modules (43) │ │
│ │ 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 │ │
│ │ split-apk │ mirroring │ test-gen │ │
│ │ ota-monitor │ ril-intercept │ │
│ │ device-profiles │ firmware-analysis │ │
│ │ workflow-market │ selinux-audit │ │
│ │ thermal-power │ network-discovery │ │
│ ├─────────────────────────────────────────────┤ │
│ │ Resources (4) │ 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 与设备通信。所有 180 种工具均通过 ADB 桥接工作，并在出现临时性故障时自动重试。
### 设备端模式——直接本地执行
```
AI Agent (Termux) ←→ MCP (stdio/HTTP) ←→ DeepADB (Termux) ←→ sh/su (local)
```
当 DeepADB 直接在 Android 设备上运行（例如在 Termux 中）时，它会自动检测环境并切换到 `LocalBridge`。命令直接通过 `sh`/`su` 执行——无需 ADB 服务器、无需 USB、无需序列化开销。所有 180 种工具功能相同，且延迟显著降低。
**在以下硬件上验证通过：** 在设备端模式下，257/257 项测试均通过（Pixel 6a，Android 16，Termux + Magisk + QEMU 10.2.1），包括 QEMU/KVM 虚拟化测试（覆盖设置检测、磁盘镜像生命周期、资源预算报告、Alpine Linux VM 启动（使用 KVM 加速）、big.LITTLE CPU 拓扑检测、访客 ADB 连接错误处理以及干净的 VM 关机）。在 ADB 模式下：总计 235 项（230 项通过 DA_TEST_PIN，5 项 QEMU 测试自动跳过）。
**权限提升：** 在 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 && 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
```
## 快速开始
```
npm install
npm run build
npm run inspector # Test with MCP Inspector
npm start # Run directly (stdio mode)
# 基于浏览器的客户端的 HTTP/SSE 模式
DA_HTTP_PORT=3000 npm start
# WebSocket 模式（需要：npm install ws）
DA_WS_PORT=3001 npm start
# GraphQL API（需要：npm install graphql）—— 与任何传输方式并行运行
DA_GRAPHQL_PORT=4000 npm start
```
## Claude Code 配置
```
{
"mcpServers": {
"deepadb": {
"command": "node",
"args": ["/path/to/DeepADB/build/index.js"]
}
}
}
```
## 可用工具（180 种）
### 运行状况（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` — 发现已注册的活动、服务与接收器及其 Intent 过滤器
### 文件（4 种工具）
- `adb_push` — 将本地文件推送到设备
- `adb_pull` — 从设备拉取文件到本地文件系统
- `adb_ls` — 列出设备目录内容（简单或详细）
- `adb_cat` — 读取设备上的文本文件（可选行数限制）
### 日志 — 快照（3 种工具）
- `adb_logcat` — 带标签、优先级、grep 和缓冲区选择的过滤日志快照
- `adb_logcat_clear` — 清除所有日志缓冲区
- `adb_logcat_crash` — 崩溃缓冲区的日志快照
### 日志 — 持续监视器（4 种工具）
- `adb_logcat_start` — 启动后台日志监视器，使用环形缓冲区累积
- `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` — ANR 跟踪与 tombstone 崩溃转储（来自 /data/anr/ 和 /data/tombstones/）
- `adb_heap_dump` — 从运行中的进程捕获堆转储（.hprof）用于内存分析
### 用户界面（10 种工具）
- `adb_screencap` — 截取屏幕并保存到本地（文件名已净化）
- `adb_screencap_annotated` — 带有 UI 元素边界框和编号标签的注释截图（返回图像路径及文本图例），适用于需要按编号引用元素的 LLM 工作流
- `adb_current_activity` — 获取当前前台活动与顶层窗口栈
- `adb_input` — 发送点击、滑动、文本或按键事件
- `adb_start_activity` — 通过 Intent 或组件启动活动
- `adb_ui_dump` — 转储完整 UI 层次结构。支持三种输出格式：`text`（默认，人可读）、`tsv`（紧凑的制表符分隔格式，适合令牌高效的自动化循环）、`xml`（原始 uiautomator XML）
- `adb_ui_find` — 按文本、资源 ID 或内容描述搜索 UI 层次结构（返回点击坐标）
- `adb_screen_state` — 合并的屏幕状态：前台活动、屏幕尺寸与密度、方向、电量水平，以及可交互元素的 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` — 读取任意 Android 设置（系统/安全/全局命名空间）
- `adb_settings_put` — 写入任意 Android 设置并验证回读
- `adb_reboot` — 重启设备（普通模式/恢复模式/引导加载程序模式）
### 无线调试（4 种工具）
- `adb_pair` — 使用配对码通过 WiFi 与设备配对
- `adb_connect` — 通过 WiFi/TCP 连接到设备
- `adb_disconnect` — 断开无线设备
- `adb_tcpip` — 将 USB 设备切换为 TCP/IP 模式（自动检测设备 IP）
### 端口转发（3 种工具）
- `adb_forward` — 将本地端口转发到设备端口（主机 → 设备）
- `adb_reverse` — 反向转发设备端口到主机（设备 → 主机）
- `adb_forward_list` — 列出所有活动的转发与反向映射
### 模拟器管理（3 种工具）
- `adb_avd_list` — 列出可用的 AVD（PC 模式）或检测 KVM/QEMU 虚拟化能力（设备端模式）
- `adb_emulator_start` — 启动 AVD（PC 模式，支持无头、冷启动和 GPU 选项）或报告 QEMU 替代方案（设备端模式）
- `adb_emulator_stop` — 优雅关闭运行中的模拟器
### QEMU/KVM 虚拟化（8 种工具）
- `adb_qemu_setup` — 检查并安装 QEMU（验证 KVM，通过 Termux pkg 安装）
- `adb_qemu_images` — 管理 VM 磁盘镜像：列出、创建（qcow2/raw）、删除。包含路径包含性验证以防止遍历
- `adb_qemu_start` — 启动支持 KVM 加速的 VM。自动检测最优 CPU（总数减一，保留一个给主机）和内存（物理 RAM 的 65%）。支持内核/initrd/append 以启动 Android、ABD 端口转发
- `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` — 在访客 VM 上执行 Shell 命令（受安全中间件限制）。访客串口由内部派生，不将用户提供的宿主 IP/地址传递给 ADB 二进制文件
### 测试会话（3 种工具）
- `adb_test_session_start` — 启动命名测试会话，组织输出目录
- `adb_test_step` — 捕获编号步骤的截图与日志cat到会话中
- `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 的滑动回退）
- `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` — 按文本、资源 ID 或内容描述查找元素并点击其中心
- `adb_wait_element` — 轮询 UI 层次结构直到元素出现或消失（可配置超时/轮询间隔）
- `adb_wait_stable` — 轮询直到连续 UI 转储匹配（屏幕在过渡后稳定）
- `adb_scroll_until` — 反复滚动直到找到目标元素（可选自动点击）
- `adb_screenshot_compressed` — 捕获带尺寸/质量元数据的截图，适用于令牌高效工作流
- `adb_batch_actions` — 在单次调用中执行多个输入动作（点击/滑动/快速滑动/长按/双击/按键事件/文本/拖动/捏合/返回/主页/睡眠），带安全校验
### 设备感知（3 种工具）
- `adb_screen_size` — 屏幕分辨率、显示密度（DPI）、纵横比与 DP 宽度（单次调用）
- `adb_device_state` — 合并快照：电量状态/类型、温度、网络类型、WiFi 状态、屏幕开关、方向、前台活动
- `adb_notifications` — 解析活动通知（按软件包、标题、文本、重要性、渠道、标志与时间戳过滤）
### 快照/恢复（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 种工具）
- `_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` — 蜂窝 ID（CID）、TAC/LAC、EARFCN、PCI、PLMN，来自 dumpsys phone
- `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 Farm 运行结果或列出近期测试矩阵
- `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` — 自动检测调制解调器 AT 命令设备节点（Shannon、Qualcomm、MediaTek、Unisoc、通用）。探测已知路径并返回首个响应节点
- `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 解码（IHDR 解析、IDAT 解压缩、全部 5 种 PNG 滤波类型）并比较实际 RGB 值。报告变化像素数/百分比、变化区域边界框（带垂直屏幕位置）及尺寸/大小差值。支持 `tolerancePercent` 参数（0–100）以吸收时钟等动态元素的微小变化——1% 容差可可靠吸收导航栏时钟变化（约 0.5% 像素）同时捕获真实 UI 回归。SHA-256 快速路径用于精确匹配。无外部依赖。
- `adb_screenshot_history` — 列出所有保存的截图基线及其元数据
### 工作流编排（3 种工具）
- `adb_workflow_run` — 执行 JSON 定义的流程：顺序设备操作（含变量替换 `{{pkg}}`）、条件步骤（`if` 表达式含 ==、!=、contains）、循环（`repeat`，上限 100）及结果捕获到变量供后续步骤使用。操作直接映射到 ADB 桥接操作并强制执行安全中间件。工作流验证限制步骤数（200）及每步暂停上限（5 分钟）以防止资源耗尽
- `adb_workflow_validate` — 验证流程结构而不执行。显示执行计划
- `adb_workflow_list` — 列出工作流目录中的保存流程文件
### 分包 APK 管理（4 种工具）
- `adb_install_bundle` — 通过 `install-multiple` 安装分包 APK（含替换与降级选项）
- `adb_list_splits` — 显示软件包的所有 APK 分路径（基础、密度、语言等）及总大小
- `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` — 分析当前屏幕的交互元素并生成与之兼容的工作流程 JSON（含点击、截图、崩溃检测）
- `adb_test_gen_from_intents` — 分析软件包已注册的活动并生成启动每个导出活动的工作流程（含崩溃检测）
- `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` — 启动从无线电日志缓冲区捕获 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 完整性、hypervisor 与 OTA 分区库存。支持 Pixel/Tensor（g5123b-*）、经典三星（S5123AP_CL*）格式
- `adb_firmware_diff` — 比较所有固件组件（基带、引导加载程序、内核、安全补丁、构建 ID、Android 版本、RIL）在保存指纹与实时设备之间的差异。深度解析基带与引导加载程序变更
- `adb_firmware_history` — 跟踪所有保存指纹的多组件固件演进（含基带、引导加载程序、内核、安全补丁、构建 ID、Android 版本）并解析基带差异
### 无线固件（4 种工具）
- `adb_wifi_firmware` — WiFi 芯片组与固件识别：驱动版本、固件版本、支持频段（2.4/5/6 GHz）、WiFi 标准检测（5/6/6E/7）、当前连接信息。MAC 地址为可选
- `adb_bluetooth_firmware` — 蓝牙固件与芯片组识别：固件版本、BT 版本（4.0–5.4 LMP）、适配器状态、LE 能力（2M 物理层、编码物理层、扩展广播）、活动配置文件（A2DP/HFP/HID/LE 音频）、已配对设备数。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_market_export` — 打包本地工作流程（含市场元数据：作者、版本、标签、SHA-256）并生成注册表清单条目以供分享
### GraphQL API
可选的 HTTP 端点，提供 GraphQL API 以进行组合设备查询。允许客户端在单个请求中获取设备信息、电量、网络与任意属性，替代多次 MCP 工具调用。POST 体大小限制为 1 MB。设备属性在每次解析前预取以最小化子进程调用。需可选 `graphql` npm 包。设置 `DA_GRAPHQL_PORT` 以启用。
### 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 可用设备。探测端口 5555–5558 的批处理并行 TCP 探测
- `adb_network_device_ip` — 通过多种方法获取连接设备的 WiFi IP。显示 ADB TCP 状态与无线连接说明
- `adb_network_auto_connect` — 一步式发现并连接：扫描 ADB 设备并自动对每个监听器执行 adb connect。简化无线调试流程
## MCP 资源（4 种）
只读设备状态接口，供 MCP 客户端访问：
- `device://list` — 所有连接设备的列表（含状态与型号信息）
- `device://info/{serial}` — 设备属性（型号、操作系统、构建、ABI）
- `device://battery/{serial}` — 解析后的电池状态（电量、充电、温度、电压）
- `device://telephony/{serial}` — 蜂窝网络注册状态
## MCP 提示（4 种）
针对常见多步骤调试任务预置的工作流模板：
- **`debug-crash`** — 清除日志 → 重启应用 → 等待复现 → 捕获崩溃缓冲区 → 分析
- **`deploy-and-test`** — 构建 → 安装 → 清除日志 → 启动监视器 → 启动 → 截屏 → 报告
- **`telephony-snapshot`** — 捕获蜂窝状态、SIM/网络运营商、网络类型 → 汇总异常
- **`airplane-cycle-test`** — 启动监视器 → 基线蜂窝 → 循环飞行模式 → 比较前后状态
## 核心特性
### 设备缓存
设备发现结果带有可配置 TTL（默认 5 秒）缓存，避免在快速工具序列中重复调用 `adb devices` 子进程。缓存会在连接错误或无线连接/断开/配对操作后自动失效。
### 瞬态故障重试
ADB 桥接对临时性故障（设备离线、连接重置、协议错误）自动重试（可配置重试次数与指数退避）。诊断命令跳过重试以立即暴露真实问题。
### 输出保护
所有 ADB 输出均经过 OutputProcessor 处理：标准化行尾、强制执行可配置字符限制、在逻辑边界（换行、分隔符）处提供上下文截断（而非行中截断）。包含电池、meminfo 与 getprop 输出的结构化解析器。
### 持久化日志监视
后台日志监视器作为子进程运行，使用环形缓冲区累积。每次轮询仅返回自上次读取后的新行。支持多个并发会话（最多 10 个），各自拥有独立过滤器。进程清理处理程序确保服务器退出时不会遗留 `adb logcat` 进程。
### UI 层次结构分析
通过 `uiautomator dump` 捕获完整视图树，并解析 XML。返回结构化元素数据，包括文本、资源 ID、内容描述、类名、边界坐标（带可点击中心点）以及交互标志。预编译正则表达式用于高效属性提取。
### 安全中间件
通过 `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 从快照文件反序列化前会进行验证。每个工具的所有 `z.number()` 参数均带有显式的 `.min()/.max()` Zod 边界，防止极端值导致资源耗尽。LocalBridge 对每个 ADB命令均有显式处理程序，防止未加引用的回退到默认 Shell 处理程序。在设备端模式下，权限提升使用冻结的 16 条命令允许列表与受限路径正则表达式——提升集合为 `ReadonlySet` + `Object.freeze`，运行时不可配置。HTTP/SSE 传输默认拒绝跨域请求（可通过 `DA_HTTP_CORS_ORIGIN` 配置允许特定来源）。插件注册表验证 SHA-256 完整性哈希并防止路径遍历（目录包含性检查），工作流引擎限制步骤数（200）、睡眠时长（5 分钟）与重复次数（100）。获取助手限制响应体为 5 MB。getprop 输出解析在正则匹配前使用 `.trim()` 处理 Windows 的 `\r\n` 行尾；双 SIM 槽计数上限为 4，以防止因损坏的设备属性导致资源耗尽。
### 多设备协同
并行运行命令、安装 APK 并跨多个连接设备比较输出，适用于跨 Android 版本与设备型号的对比测试。
### 快照/恢复
将综合设备状态（软件包、所有命名空间下的设置、系统属性）保存为 JSON 文件。与保存的快照对比以检测漂移。从快照恢复设置以实现可重复的测试环境。
### 网络流量捕获
通过 tcpdump 在设备上进行本地抓包，拉取 pcap 文件供 Wireshark 分析。包含通过 ss/netstat 的活动连接列表（/proc/net 回退），适用于缺少这些工具的设备。
### CI/CD 集成
面向流水线的专用工具：轮询等待设备启动、结构化就绪检查（启动、PM、屏幕、网络、磁盘）以及通过 `am instrument` 运行仪器化测试并解析通过/失败结果。
### 插件架构
从可配置的插件目录动态加载工具模块。插件为标准 JavaScript ESM 模块，导出 `register(ctx)` 函数，接收完整的 ToolContext。服务器启动时加载，支持社区贡献而无需修改核心代码。
### 社区插件注册表
搜索、安装与管理来自可配置注册表 URL 的插件。显示安装状态、版本对比与可用更新。下载插件文件及配套元数据至插件目录，供下次重启加载。安全特性包括 SHA-256 完整性验证（如注册表提供）、路径遍历防护与 `register()` 导出健全性检查。
### 基带/调制解调器集成
深入的蜂窝无线调试工具，适用于高级 Android 开发与研究。提取调制解调器固件识别、小区标识参数（CID、TAC、EARFCN、PCI）、原始无线测量（RSRP、RSRQ、SINR、RSSI）、邻区普查、运营商配置以及多源调制解调器日志（RIL 无线电缓冲器、电信框架、内核 dmesg）。支持 Shannon/Exynos、Qualcomm、MediaTek、Unisoc 芯片组家族，并通过标准 Android 电信 API 包含 Google Tensor SoC（gs101/gs201/zuma/zumapro）的自动 Shannon 调制解调器路径路由。双 SIM 检测报告每槽 SIM 状态、运营商、网络类型与国家（DSDS、DSDA、TSTS）。
### 无障碍审计
对实时 UI 层次结构执行自动 WCAG 审计。检测交互元素上的缺失标签、低于 48dp 的触摸目标（密度感知）、缺少内容描述的图像、不可点击的元素以及重复的内容描述。生成结构化报告并包含严重级别。提供专用的无障碍树视图用于屏幕阅读器调试。
### 回归检测
捕获性能基线（内存、CPU、帧统计、电量、网络状态）并与后续运行对比。配置可调整的回归阈值（内存 +20%、CPU +50%、卡顿率 +25%）。维护基线历史记录以进行趋势分析。
### 设备农场集成
通过 gcloud CLI 在 Firebase Test Lab 上执行基于云端的测试。跨多个设备型号与 API 层级运行仪器化测试，获取结构化结果并列出可用测试矩阵配置。若 gcloud 不可用则提供设置说明。
### HTTP/SSE 传输
替代 stdio 的浏览器友好 MCP 传输。设置 `DA_HTTP_PORT` 启动带有 SSE 流式传输的 HTTP 服务器。提供 `/sse`（客户端订阅）、`/message`（JSON-RPC）与 `/health` 端点。默认拒绝跨域请求——设置 `DA_HTTP_CORS_ORIGIN` 以显式允许特定来源。
### 测试会话管理
带编号步骤的结构化测试流程。每个步骤捕获截图与日志 cat 到组织化的目录，并附带 Markdown 清单。适用于可重现的测试文档。
### AT 命令接口
通过 Root 权限直接透传 AT 命令到调制解调器，实现超越 Android 电信框架的原始查询。支持多芯片组自动检测设备节点（Samsung Shannon/Exynos、Qualcomm Snapdragon、MediaTek、Unisoc/Spreadtrum 及通用 USB 调制解调器）。在 AT 命令字符串与设备节点路径中均对 Shell 元字符进行输入验证。安全黑名单可防止意外执行危险命令（如 AT+CFUN=0、AT+EGMR 等），并提供明确的强制覆盖选项。
### 截图差异检测
真正的像素级视觉回归检测。捕获命名截图基线并通过解码 PNG 像素数据（IHDR 解析、IDAT 解压缩、全部 5 种 PNG 滤波类型）比较当前屏幕状态与基线的实际 RGB 值。报告变化像素数与百分比、变化区域边界框（带垂直屏幕位置）及尺寸/大小差值。支持 `tolerancePercent` 参数（0–100）以吸收时钟等动态元素的微小变化——1% 容差可可靠吸收导航栏时钟变化（约 0.5% 像素）同时捕获真实 UI 回归。SHA-256 快速路径用于精确匹配。无外部依赖。
### 工作流编排
声明式 JSON 引擎，用于可重复的多步骤设备操作。支持变量替换（`{{pkg}}`）、条件步骤（`if` 表达式含 ==、!=、contains）、循环（`repeat`，上限 100）以及结果捕获到变量供后续步骤使用。操作直接映射到 ADB 桥接操作并强制执行安全中间件。工作流验证限制步骤数（200）与每步暂停上限（5 分钟），防止资源耗尽。
### 分包 APK 管理
支持现代 Android 交付格式。通过 `install-multiple` 安装应用分包，检视分包结构（基础 + 密度/语言/ABI 等配置拆分）、本地提取所有分包用于分析，以及列出 APEX 模块。
### 设备镜像
通过 scrcpy 实现的实时屏幕镜像。支持窗口模式与无头模式、录制、比特率/FPS/分辨率控制、常驻唤醒及屏幕关闭。每设备会话跟踪，进程清理处理程序防止孤儿 scrcpy 进程。
### 自动化测试生成
分析实时 UI 层次结构与软件包已注册活动，自动生成兼容工作流编排引擎的测试 JSON。UI 生成基于点击每个交互元素并截图与崩溃检测；意图生成则启动每个导出活动并附带崩溃检测。
### OTA 更新监控
跨会话跟踪综合系统指纹（构建 ID、Android 版本、安全补丁、引导加载程序、基础带/调制解调器固件、内核版本、A/B 分区槽）。与保存的指纹对比以检测 OTA 更新。精确标识变更字段并建议在更新后重新建立基线与截图。
### RIL 消息拦截
从 Android 无线电日志缓冲区持续捕获 RIL 消息。启动后台进程，将消息分类为：注册、小区信息、信号、网络、安全、切换、数据、无线电状态、短信与 NAS 事件。轮询检索与分类过滤。适用于被动监控基带-框架通信以进行无线诊断与蜂窝网络研究。会话限制（5）与进程清理处理程序防止资源耗尽。
### 设备配置库
设备特定知识库，包含硬件标识、芯片组家族、已知调制解调器设备节点、AT 命令兼容性、Root 要求、双 SIM 槽位数量与缺陷信息。自动从连接设备检测配置并匹配内置库以识别已知设备特性。支持跨会话持久化保存以提升自动检测准确性。
### WebSocket 传输
替代 stdio 与 HTTP/SSE 的 MCP 客户端方案，适用于需要真正双向流式传输的场景。延迟低于 SSE 轮询，与 Web 框架兼容性更好。需可选 `ws` npm 包作为对等依赖。设置 `DA_WS_PORT` 以启用。
### 调制解调器固件分析
全面的多组件固件识别、差异与历史追踪。解析 6 个芯片组的基带版本字符串：Shannon/Exynos（含 Google Pixel/Tensor `g5123b-*` 格式与经典三星 `S5123AP_CL*` 格式）、Qualcomm MPSS 分支/版本/构建、MediaTek MOLY 分支/发布/里程碑、Unisoc/Spreadtrum SoC 型号/、HiSilicon/Kirin 型号/运营商代码、Intel XMM 型号/分支。还解析引导加载程序版本（Pixel 代号/版本/构建、三星型号/运营商/修订版）与 RIL 实现字符串（Samsung S.LSI 厂商/ID/API/构建日期、Qualcomm、MediaTek）。固件探测报告 8 个部分：基带、引导加载程序、RIL、内核、安全/构建、分区/引导（A/B 槽、Secure Boot、Verified Boot、Flash Lock）、VBMeta 完整性与 OTA 分区库存。差异工具比较保存指纹与实时设备的所有固件组件（含深度解析的基带与引导加载程序变更）。历史工具跟踪多组件固件演进。
### 工作流市场
社区共享的工作流程定义、诊断序列与审计流程的注册表层。搜索、下载并安装直接可运行的市场工作流。导出本地工作流并附带市场元数据（作者、版本、标签、SHA-256）以生成注册表清单条目供分享。下载时进行 SHA-256 完整性验证。
### GraphQL API
可选的 HTTP 端点，提供 GraphQL API 以进行组合设备查询。允许客户端在单个请求中获取设备信息、电量、网络与任意属性，替代多次 MCP 工具调用。POST 体大小限制为 1 MB。设备属性在每次解析前预取以最小化子进程调用。需可选 `graphql` npm 包。设置 `DA_GRAPHQL_PORT` 以启用。
### SELinux 与权限审计
检查 SELinux 强制执行模式、策略版本、Shell 上下文与最近的 AVC 拒绝计数。Root 可提供内核 dmesg 拒绝统计。列出最近的 AVC 拒绝消息并解析源/目标上下文、权限类别与拒绝的操作。支持进程过滤。按危险权限类别（相机、位置、电话、短信 等）审计运行时权限授予，并标记高敏感权限（如后台位置、外部存储）。扩展了安全审计至操作系统权限层。
### 热/功耗分析
捕获热区温度、每个 CPU 频率/调度器、冷却设备状态以及电池放电速率。补充回归检测，提供热/功耗基线以识别发热或耗电异常而非仅帧率下降。包含定时放电测量（3–60 秒），报告平均 mA、mW、估算 %/小时。可选针对特定软件包的 batterystats。
### 网络设备发现
通过 ARP 表查询与可选 IP 范围扫描在本地网络中发现 ADB 可用设备。探测常用 ADB 端口（5555–5558）的批处理并行 TCP 连接尝试。通过多种方法提取设备 WiFi IP。自动连接模式可一步完成发现与连接，简化无线调试流程。
### QEMU/KVM 虚拟化
在设备上使用 QEMU 与 KVM 硬件加速运行虚拟机（VM）。这是 DeepADB 独有的能力——可在物理设备上直接运行 Android 访客 VM。动态资源分配自动检测主机 CPU 核心与物理 RAM，保留 1 个核心与 35% 内存给主机以防止资源争用。多 VM 支持跟踪各 VM 资源消耗，拒绝新 VM 以避免主机性能下降。磁盘镜像管理支持 qcow2（稀疏、快照友好）与 raw 格式。ADB 端口转发至访客 VM，使全套工具可同时针对主机与访客设备操作。进程生命周期通过集中清理注册表管理，路径包含性验证防止目录遍历。
### ToolContext 架构
全部 43 个工具模块接收统一的 `ToolContext` 依赖包，包含服务器、桥接、设备管理器、日志记录器、安全与配置。新增跨切面依赖无需修改模块签名。
## 环境变量
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `DA_LOCAL` | 自动检测 | 强制启用设备端模式（`true`/`false`）。自动检测依据 `/system/build.prop` |
| `ADB_PATH` | 自动检测 | ADB 二进制文件路径（设备端模式下忽略） |
| `DA_TIMEOUT` | `30000` | 默认命令超时（毫秒） |
| `DA_MAX_OUTPUT` | `50000` | 输出截断前的最大字符数 |
| `DA_MAX_LOGCAT` | `500` | 每次快照的最大日志cat行数 |
| `DA_DEVICE` | （自动） | 默认设备序列号（单设备时自动选择） |
| `DA_TEMP_DIR` | OS 临时目录 | 截图、下载文件、Bug 报告、测试会话、截图存储目录 |
| `DA_CACHE_TTL` | `5000` | 设备列表缓存 TTL（毫秒），设为 0 禁用缓存 |
| `DA_RETRY_COUNT` | `1` | 瞬态 ADB 故障重试次数 |
| `DA_RETRY_DELAY` | `500` | 基础重试延迟（毫秒），每次尝试指数递增 |
| `DA_LOG_LEVEL` | `info` | 日志级别：debug、info、warn、error |
| `DA_SECURITY` | `false` | 启用安全中间件（命令过滤、速率限制、审计） |
| `DA_BLOCKED_COMMANDS` | （无） | 以逗号分隔的阻塞 Shell 命令子字符串列表 |
| `DA_ALLOWED_COMMANDS` | （无） | 以逗号分隔的命令允许列表（若设置，仅匹配命令可执行） |
| `DA_RATE_LIMIT` | `0` | 每分钟最大命令数（0 表示无限制） |
| `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 绑定地址 |
| `DA_AUTH_TOKEN` | （无——开放） | Bearer Token，用于网络传输。设置后所有 HTTP/SSE/WS/GraphQL 请求需携带 `Authorization: Bearer ` 头，健康端点除外 |
| `DA_HTTP_CORS_ORIGIN` | （无——拒绝） | 允许的 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 |
## 项目结构
```
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 # Push, pull, ls, cat (4 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)
│ │ ├── 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 and reverse forwarding (3 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 and plugin info tools (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)
│ │ └── wireless-firmware.ts # WiFi, Bluetooth, NFC, GPS firmware identification (4 tools)
│ │ ├── build.ts # Gradle build and install (2 tools)
│ │ ├── resources.ts # MCP Resources — device state surfaces (4 resources)
│ │ └── 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)
│ └── 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 # MIT 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 (25 tests)
│ ├── test-security.mjs # Input sanitization, shell injection, AT command safety (25 tests)
│ ├── test-lifecycle.mjs # App lifecycle, file push/pull, input, port forwarding, screen recording, test sessions (22 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 (31 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, KVM acceleration, topology detection, guest ADB connectivity (14 on-device tests)
│ └── lib/
│ └── harness.mjs # Shared test harness (stdio JSON-RPC transport, 6 assertion types)
└── docs/
└── future-roadmap.md # Feature history and future ideas
```
## 技术栈
- **运行时**：Node.js ≥22（ES2024，ESM）
- **语言**：TypeScript 6.0（严格模式，NodeNext 模块解析）
- **MCP SDK**：`@modelcontextprotocol/sdk` ^1.24.0（当前解析为 1.29.0）
- **校验**：Zod ^3.25.0
- **传输**：stdio（JSON-RPC）、HTTP/SSE、WebSocket（可选 `ws`）、GraphQL API（可选 `graphql`）
## 许可证
MIT
标签：ADB, AI代理集成, Android Debug Bridge, Android开发工具, Android设备控制, AT命令接口, CI/CD流水线, DNS解析, GraphQL API, MCP Server, MCP工具生态, MITM代理, OTA更新监控, RIL消息拦截, SELinux审计, UI检查, 上下文截断, 云设备农场测试, 代码构建, 可访问性审计, 基带调制解调器, 多传输协议(stdio/HTTP/SSE/WebSocket), 多设备操作, 威胁情报, 安全防护防御纵深, 屏幕录制, 工作流程编排市场, 应用管理, 开发者工具, 开源项目, 性能回归检测, 数据可视化, 日志捕获, 暗色界面, 模块化架构, 模型上下文协议, 模拟器管理, 热功耗分析, 目录枚举, 社区插件管理, 移动安全, 移动测试, 移动自动化, 结构化测试会话, 网络流量捕获, 自动化攻击, 自动化测试生成, 视觉回归测试, 设备发现, 设备画像, 远程调试WiFi