# AdbDebug.SKILL

**Repository Path**: jimonik/adb_debug_skill

## Basic Information

- **Project Name**: AdbDebug.SKILL
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# adb-debug

面向 AI 编程工具和开发者的 Android / Flutter ADB 调试技能。项目可以只保存 `.adbdebug` 一个文件，就能直接进入真实页面、查询页面状态和日志，减少反复截图识别、逐层点击。

- **统一入口**：`routes / open / status / back`，页面目录从客户端注册表发现。
- **保留页面状态**：重复进入复用实例，显现已有页面；跳转前尊重未保存表单、忙碌状态和正常返回确认。
- **调试隔离**：客户端 debug 模块或独立 Flutter 调试入口，工具核验已安装应用可调试；支持 APK 标记检查。
- **设备证据**：按进程和标签查询日志、多显示屏截图，临时 ADB 端口转发自动清理。
- **结构化诊断**：采集内存、帧、后台任务、网络、权限和崩溃证据，支持快照差异与屏幕录制。
- **系统追踪**：按启动、卡顿和功耗预设采集 Perfetto，自动适配设备支持的 trace 类别。
- **界面定位**：同步采集截图、窗口和规范化页面树，关联源码候选并报告稳定性、覆盖缺口与常见语义问题。
- **兼容升级**：旧 `.adbdebug` 在支持期内继续可用，可先预览迁移、生成候选，再备份并原子升级。
- **统一构建**：按项目配置运行 Flutter / Gradle，不自动改版本、安装或发布。

这是可直接调用的 Python CLI 加技能说明，**不是 MCP 服务**。原生多 Activity 项目可只配置现有 Activity；Compose、单 Activity 和 Flutter 的精确子页跳转需要最小客户端适配，不能通过 ADB 凭空访问内部路由。页面复用和未保存保护依赖项目正确接入真实导航 owner。

## 安装

依赖 Python **3.9+**、可执行的 `adb`、已授权的 Android 设备。构建另需项目原有 Flutter / JDK / Android SDK；`verify-apk` 需要 SDK Build Tools 的 `aapt`。Python 脚本仅使用标准库，无需 pip 安装。

### Codex

```sh
git clone https://gitee.com/jimonik/adb_debug_skill.git "$HOME/.codex/skills/adb-debug"
```

若目标目录已存在，先检查原有安装，避免覆盖。重启或重新加载技能后可调用 `$adb-debug`。已有源码 checkout 可把它链接到技能目录；不要再创建第二份副本。

### Claude Code 与其他 AI 工具

支持 `SKILL.md` 的工具可将整个仓库安装到其技能目录，目录名建议 `adb-debug`。例如 Claude Code 的用户技能目录：

```sh
git clone https://gitee.com/jimonik/adb_debug_skill.git "$HOME/.claude/skills/adb-debug"
```

不支持技能发现的工具同样可用：克隆到任意目录，让 AI **先读取 `SKILL.md`，再读取目标项目 `.adbdebug`**，通过终端执行 `scripts/adbdebug.py`。不依赖 Codex API、插件或用户的本机绝对路径。不同工具的自动加载规则由各自版本决定；直接读取和 CLI 调用不依赖这些规则。

```sh
git clone https://gitee.com/jimonik/adb_debug_skill.git "$HOME/ai-skills/adb-debug"
export SKILL_DIR="$HOME/ai-skills/adb-debug"
python3 "$SKILL_DIR/scripts/adbdebug.py" --help
```

更新时在安装目录执行 `git pull --ff-only`；有本地修改时先保留修改。Windows 可在 PowerShell 中直接使用 Python 和脚本路径；当前 Gradle 构建分支需要 bash，其他设备命令不依赖 bash。

项目发现 `.adbdebug` 后可以安全检查 skill，而不是盲目安装 MCP 或升级到不兼容版本：

```sh
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" skill check
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" skill update --check
# 只有明确要求更新时：
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" skill update --apply
```

检查会核对安装版本、项目兼容约束、origin、当前分支、tracked 修改和远端 commit。发现 `update_available=true` 时，AI 应在开始设备或项目操作前先提示有更新并建议优先更新；兼容只表示可以继续，不表示无需更新。应用更新仍需用户明确要求，只执行可信来源的 `git pull --ff-only`，然后运行单测与可用的 skill 校验；复制或插件托管安装交给对应管理器更新。此技能无需 MCP。

## 已接入项目：直接使用

以下 `SKILL_DIR` 换成实际安装目录，`PROJECT` 是目标项目路径，`DEVICE` 来自 devices 输出。全局参数放在子命令前。

```sh
export SKILL_DIR="$HOME/.codex/skills/adb-debug"
export PROJECT="/path/to/android-or-flutter-project"
python3 "$SKILL_DIR/scripts/adbdebug.py" devices
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" config
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE doctor
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE routes
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE open settings
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE open detail --params '{"id":123}'
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE status
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE back
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE snapshot > /tmp/adbdebug-before.json
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE inspect frames
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE inspect memory
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE inspect crashes
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE trace /tmp/jank.perfetto-trace --preset jank --duration 10
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE ui prepare
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE ui capture /tmp/ui-before
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE ui type --resource-id chat_input --value "完整文本"
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE ui send --text 问我任何问题 --value "用户明确要求发送的文本"
# 执行复现步骤后再次采集，再比较规范化节点：
python3 "$SKILL_DIR/scripts/adbdebug.py" ui diff /tmp/ui-before/tree.json /tmp/ui-after/tree.json
```

旧项目先预览配置升级；预览不会写文件：

```sh
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" upgrade
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" upgrade --output /tmp/adbdebug-v2.json
# 审查候选后才执行：
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" upgrade --apply
```

`settings / detail` 是示例名称，实际名称以 `routes` 输出为准。多台设备必须指定 `--serial`。包名可用全局 `--package` 覆盖，适用于并装 debug 包。

结果为 JSON：`reused` 表示当前实例保留，`revealed` 表示显现已有栈实例，`opened` 表示新建。`blocked / login_required / cancelled / failed / timeout` 返回非零；不能把系统 `am start` 成功当成业务页已加载。activity 后端的 `opened_or_revealed` 只证明 Activity 已前台。

Flutter 使用前先执行一次 `ui prepare`：工具从仓库内可审查源码构建并安装独立 Instrumentation helper，目标项目和目标 APK 均不修改。`ui tap` 使用 Android `ACTION_CLICK`，`ui type` 使用 `ACTION_SET_TEXT` 进入 Flutter Semantics；禁止坐标点击、输入框聚焦、软键盘、ADB Keyboard、Agent IME、剪贴板和按键回退。输入不支持 `--submit`，任何 action 失败都直接报告。`ui cleanup` 可在调试结束后移除 helper。

`ui send` 直接操作当前可见聊天输入框和发送按钮，保护不同的已有草稿，核对完整文本后只点一次发送；不是用 IME 回车模拟发送。默认按钮描述为“发送”，可用 `--send-text`、`--send-description` 或 `--send-resource-id` 指定唯一按钮。默认立即返回 `dispatched`（仅证明点击已发出），后端接收须通过真实会话或 Run 核验，禁止自动重发。可选 `--wait-for-clear` 等待输入框清空，成功返回 `sent`，无法确认返回 `unknown` 和非零退出码；流式回复期间 UIAutomator 可能无法采集，工具只重试读取而不会再点击发送。发送必须处于用户已授权范围内。

### 日志、截图和构建

```sh
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE logs --tag flutter --lines 200
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE displays
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE screenshot /tmp/page.png --display DISPLAY_ID
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE record /tmp/repro.mp4 --duration 30
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" build debug
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" verify-apk /path/app-debug.apk --expect debug
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" --serial DEVICE install /path/app-debug.apk --expect debug
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" build release
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" verify-apk /path/app-release.apk --expect release
```

日志按当前包 PID 和标签过滤，不清空 logcat。截图拒绝覆盖已有文件；多显示屏显式选择。APK 检查核验包名、debuggable 和项目配置的隔离标记，不替代完整发布检查。安装命令单独执行；工具不会卸载或清数据。

## 新项目接入

让 AI 使用以下任务即可：

> 读取 adb-debug/SKILL.md，检查当前项目真实包名、构建方式和导航 owner，创建根目录 .adbdebug。优先复用已有调试能力，使用最少的 debug-only 适配，注册真实页面入口。验证重复打开、参数区分、未保存保护和 debug/release 隔离。

也可以先生成配置骨架（不自动修改客户端）：

```sh
python3 "$SKILL_DIR/scripts/adbdebug.py" --project "$PROJECT" init --platform flutter --package com.example.app --activity com.example.app.MainActivity
# 原生项目使用 --platform android
```

随后按 [接入指南](references/onboarding.md) 补齐配置中的适配代码。`init` 不覆盖已有文件，也不代表已经能跳转。每个生成文件顶部都自带 `about`，说明用途、skill 来源仓库、功能、安装发现及调用命令；新 AI 会话无需之前的对话即可理解。手写或迁移配置也必须保留这些说明。

| 项目结构 | 方案 | 客户端改动 |
| --- | --- | --- |
| 原生多 Activity | `activity` 白名单 | 可零改动；仅访问 shell 能启动的既有 Activity |
| 原生单 Activity / Compose | `intent-result` | 适配源码内联 .adbdebug；构建时临时注入，无常驻模块或适配文件 |
| Flutter | `external` + Semantics | 默认只保留 `.adbdebug`；运行原始 debug APK，外置 helper 不进入目标 APK |

Android 的 `generated_sources` 同样在临时目录准备桥接、合并 debug manifest，并通过 init script 接入 debug source set，构建结束后清理；普通 debug / release 不依赖 skill。详见接入指南。

Flutter 默认不生成调试启动文件，不包装 `main()`，不注入 registry/runtime/observer，也不修改构建。这样测试结论对应项目正常产生的原始 debug APK。旧有 `generated_entry`、`registry_source` 和 `library_patches` 仅作为用户明确选择的增强模式保留；它们即使不落盘修改源码，也会改变实际编译入口和运行时序，不能冒充原始 APK 测试。配置细节见 [.adbdebug 配置](references/config.md)。

## 目录与维护

- `SKILL.md`：AI 工作流与边界。
- `scripts/adbdebug.py`：统一 CLI。
- `assets/flutter`、`assets/android`：可适配的客户端模板。
- `references/onboarding.md`：客户端接入和验收。
- `references/config.md`：配置协议。
- `references/migrations.md`：Life Android / PDA Flutter 的迁移说明；这些项目不包含在本仓库。

不要提交密钥、用户数据、原始日志、截图、APK 或固定设备编号。HTTP 桥仅监听设备回环，临时 ADB forward 自动移除；原生入口使用 debug 模块和 shell 权限。导航不会代为执行消息发送、库存执行、打印等业务写操作。

验证 CLI：

```sh
python3 -m unittest discover -s scripts -p 'test_*.py' -v
python3 scripts/adbdebug.py --help
```

## 为什么不默认使用反射

优先顺序是原始 APK 的 Accessibility/Semantics → 现有公开 Activity/Deep Link → 用户显式授权的增强构建。外置 helper 调用 Android 官方 `ACTION_SET_TEXT`，Flutter Engine 已负责映射到 Dart `SemanticsAction.setText`，无需反射私有字段。反射、VM Service 自定义 extension 和入口注入都会扩大版本耦合或改变被测程序，不能作为默认方案。详细取舍见接入指南的“最少侵入的选择顺序”。

### 单文件配置的含义

默认 Flutter `.adbdebug` 不包含可编译源码。Android 的 `generated_sources.adapter_sources`、Flutter 的 `generated_entry.registry_source` 和 `library_patches` 都属于显式增强模式；配置中的源码应按项目源码审查，不接收不可信来源。详见 [接入指南](references/onboarding.md)。