TapDucky - Android USB HID 击键注入器

用于已 Root 安卓设备的开源 DuckyScript 执行器，支持 USB Gadget (ConfigFS)
TapDucky 允许您通过模拟 USB 键盘、鼠标或复合 HID 设备，在 Android 上创建、自定义、调度和运行 DuckyScript，用于授权测试和自动化。它包括有效载荷参数化、多个调度器触发器、执行日志以及一个由 GitHub 支持的有效载荷库，具有自动 DuckyScript 验证和可选的 Digispark .ino 转换功能。

概述

• USB HID 小工具配置文件（在支持/已 Root 设备上无需外部 USB 加密狗）：
  • 键盘、鼠标和复合配置文件，可配置 VID/PID、制造商/产品字符串和功耗。
• DuckyScript 流水线：
  • 实时验证，附带人类可读的问题/警告、占位符参数、延迟倍增器，以及用于模拟人类操作节奏的可选抖动。
• 有效载荷管理：
  • 使用名称/描述/标签/参数创建/编辑有效载荷，快速分享/导出，内置模板/向导。
• GitHub 有效载荷商店：
  • 添加来源，浏览仓库，预览带验证的文件，导入支持的脚本；自动检测 DuckyScript，并在可能时转换 Digispark .ino 草图。
• 调度器：
  • 一次性（日期/时间）、应用冷启动、应用前台或 HID 会话武装时（device_connected），可选的每日时间窗口。
• 执行与日志：
  • 带标签的执行视图、参数提示、运行/取消、执行历史记录，以及带导出/清除和级别过滤的结构化日志。
• 设备诊断：
  • 设备、内核/小工具状态、UDC 信息、键盘布局的快照；复制到剪贴板；模拟器检测提示。

注意：需要已 Root 且支持 Linux USB 小工具 (ConfigFS) 的设备。请使用物理设备，因为模拟器无法验证 HID 行为。

功能

• 有效载荷编辑器和参数

  • 使用名称/描述/标签创建有效载荷。
  • 添加带默认值、必需标记和每次执行覆盖的键入参数。
  • 内置 DuckyScript 验证器，带行号/问题映射和命令计数。
  • 分享单个有效载荷或导出包。

• GitHub 有效载荷商店

  • 管理多个 GitHub 来源（用户/仓库/分支/路径）。
  • 浏览目录并预览文件，格式检测（DuckyScript、TapDucky JSON、Digispark 脚本 (.ino) 转换）。
  • 直接将已验证脚本导入到您的库中；验证失败会显示带理由的预览。

• 执行与测试

  • 运行前验证；提示参数值；运行或取消，带执行 ID。
  • 快速 HID 测试：键盘按键、鼠标移动和 Ctrl+Alt+Del。
  • 基于引擎的运行时间估算（与实际时序模型匹配）。
  • 唤醒锁控制，在执行期间保持会话活动。

• 调度器与触发器

  • 触发器：一次性、应用冷启动、应用前台、设备连接（会话武装）。
  • 可选的每日时间窗口（HH:MM → HH:MM），包括跨午夜。
  • 启用/禁用、编辑和删除调度；追踪上次运行时间。
  • 通过秘密代码的拨号快捷绑定（自动武装 + 后台执行）。
    • 支持的代码：##38250##、##38251##、##38252##、##38253##
    • 每个代码的绑定键：启用、模式（最后执行 | 选定有效载荷）、有效载荷（当模式 = 选定有效载荷时）

• 设备和 HID 配置文件

  • 激活键盘、鼠标或复合配置文件，可配置 ID/字符串/功耗。
  • 键盘布局选择和代码/ID 解析。
  • 状态流显示 ACTIVE/IDLE、写入器就绪状态和主机配置请求。

• 日志与历史

  • 日志选项卡，带级别过滤（全部/信息/调试/警告/错误）、导出共享、清除全部。
  • 执行历史详情，带元数据和共享。

用户界面

• 仪表板，带快速状态卡片、有效载荷/库统计和调度器摘要。
• 清晰的空状态和首次设置/导入的分步向导。
• Material 3 主题，动态浅色/深色配色方案。

技术/架构

• 平台通道（Android）：
  • 方法通道：org.kaijinlab.tap_ducky/gadget
    • checkRoot、checkSupport、listUdcs、getStatus、getDiagnostics
    • getKeyboardLayouts、setKeyboardLayout、resolveKeyboardLayoutId、setKeyboardLayoutByCode
    • activateProfile、deactivate、panicStop、retryOpenHidWriters
    • executeDuckyScript(script, delayMultiplier, executionId?)、cancelExecution(executionId)
    • 测试辅助：testKeyboardKey(label)、testMouseMove(dx,dy,wheel,buttons)、testCtrlAltDel()
  • 事件通道：
    • org.kaijinlab.tap_ducky/gadget_logs
    • org.kaijinlab.tap_ducky/gadget_status
    • org.kaijinlab.tap_ducky/gadget_exec
• HID 配置文件模型：键盘/鼠标/复合，带 VID/PID、字符串、序列号和功耗。
• DuckyScript：
  • 解析为步骤；支持 DELAY/STRING/键/原始命令；占位符解析；基础按键延迟；抖动。
  • 验证器返回带严重性和行映射的问题；在编辑器/商店/执行流程中使用。
  • TRY/CATCH/END_TRY、WAIT_FOR、SLEEP_UNTIL、FUNCTION 参数和作用域变量。
  • Unicode 回退模式（警告+跳过 / 跳过 / ASCII 音译）。
  • 执行流中的结构化执行错误代码。
• 调度引擎：
  • 触发器（冷启动、前台、武装、一次性）、每日时间窗口规则、SharedPreferences 持久化。
• 状态管理：Riverpod 3、go_router 导航、清晰的仓库/服务/控制器分离。

DuckyScript / 击键引擎

TapDucky 包含一个完整的 DuckyScript 风格引擎，在 Android（Kotlin）上原生实现，支持表达式求值和结构化控制流。它支持键盘、鼠标/指针、时序、变量/定义、函数和简单的随机工具。

支持的命令系列（高级）：

• 文本和时序：STRING、STRINGLN、STRING_DELAY、DELAY、DEFAULTDELAY/DEFAULT_DELAY、REM（以及 REM_BLOCK）
• 键和组合键：ENTER、TAB、ESC、SPACE、BACKSPACE、方向键、导航键（HOME/END/PGUP/PGDN/INS/DEL）、F1–F24、媒体键、数字键盘键
• 修饰键组合：GUI/WIN/COMMAND、CTRL/CONTROL、ALT/OPTION、SHIFT 加附加键令牌（例如 GUI r、CTRL ALT DEL）
• 按住/释放和注入修饰：HOLD、RELEASE、INJECT_MOD（设置/清除持续到后续按键的修饰掩码）
• 指针/鼠标：MOUSE/POINTER CLICK、HOLD、DRAG、MOVE、SCROLL，含按钮 LEFT/RIGHT/MIDDLE 和相对 dx/dy 及重复次数
• 控制流：IF / ELSE IF / ELSE / END_IF、WHILE / END_WHILE
• 函数和调用：FUNCTION / END_FUNCTION、CALL_FUNCTION、RETURN
• 变量和常量：VAR $name = expr、DEFINE NAME value；$?（退出码）保持为无符号 16 位
• 随机生成器：RANDOM_LOWERCASE_LETTER、RANDOM_UPPERCASE_LETTER、RANDOM_LETTER、RANDOM_NUMBER、RANDOM_SPECIAL、RANDOM_CHAR
• 攻击模式透传：ATTACKMODE（在适用时代理到小工具管理器层）

行为说明：

• 默认延迟：DEFAULTDELAY/DEFAULT_DELAY 设置基本延迟，应用于每条可执行命令之后（按运行时延迟倍增器缩放）。
• 表达式求值器：IF/WHILE 和 VAR 赋值支持算术、比较和逻辑表达式；非零视为真。
• 重复：REPEAT N 在预处理期间将前一条命令复制 N 次。
• 键盘映射：完整的 HID 用法映射，带布局选择；支持常用别名（ESC/ESCAPE、BKSP/BACKSPACE 等）。
• 执行流：发出 step/start/done/error 事件，带进度，用于实时 UI 更新和日志。

鼠标/指针语法快速参考：

• MOUSE CLICK [LEFT|RIGHT|MIDDLE] [num]
• MOUSE HOLD [LEFT|RIGHT|MIDDLE] [dx] [dy] [num]
• MOUSE DRAG [LEFT|RIGHT|MIDDLE] [dx] [dy] [num]
• MOUSE MOVE [dx] [dy] [num]
• MOUSE SCROLL [UP|DOWN] [num]

能力矩阵（精选）：

功能组	子功能	支持	备注
文本/时序	STRING / STRINGLN / STRING_DELAY	✅	STRING_DELAY 的逐字符时序；通过 DEFAULTDELAY 实现全局延迟
文本块	STRING/STRINGLN 块	✅	由 END_STRING / END_STRINGLN 终止的多行块
时序	DELAY、DEFAULTDELAY/DEFAULT_DELAY	✅	DEFAULT 在每个可执行步骤后应用
重复	REPEAT N	✅	将前一条命令复制 N 次
注释	REM、REM_BLOCK/END_REM	✅	不可执行
修饰键	GUI/WIN、CTRL、ALT、SHIFT 组合	✅	解析为单个组合键步骤
键命令	显式键名	✅	“显式键和别名支持”中列出的所有键/别名
按住/释放	HOLD、RELEASE	✅	追踪按住集；与 INJECT_MOD 配合使用
显式键状态	KEYDOWN、KEYUP	✅	直接按键/释放控制，用于组合键和按住的键
注入修饰	INJECT_MOD	✅	持续到清除的修饰掩码
鼠标/指针	MOUSE/POINTER CLICK/HOLD/DRAG/MOVE/SCROLL	✅	带重复次数的相对移动
控制流	IF/ELSE IF/ELSE/END_IF	✅	支持嵌套链
循环	WHILE/END_WHILE	✅	使用表达式引擎求值条件
函数	FUNCTION/END_FUNCTION、CALL/CALL_FUNCTION、RETURN	✅	支持参数；RETURN 设置 $?
变量	VAR $name = expr	✅	整数，0..65535 存储；$? 为退出码；作用域局部变量
定义	DEFINE NAME value	✅	解析前的简单文本替换
错误处理	TRY/CATCH/END_TRY	✅	可恢复故障，不会中止脚本
等待	WAIT_FOR、SLEEP_UNTIL	✅	主机/UDC/键盘就绪 + 定时等待
随机	RANDOM_* 生成器	✅	小写/大写/字母/数字/特殊/字符
攻击模式	ATTACKMODE	⚠️	已解析，但尚未实现后端处理器

注意：验证器会在执行前报告语法错误、未知命令和结构错误。请参阅有效载荷编辑器以查看带行号的 UI 内验证结果。

执行时序重点：

• 独立的执行延迟倍增器和打字速度因子（带有可选的风险快速模式）。
• 长 STRING 运行期间定期刷新，以减少主机键盘缓冲区溢出。
• 针对短暂 HID 断开的主机感知退避和宽限窗口。
• 当微睡眠不可用时的硬件感知估算校准。

显式键和别名支持

注意：除了列出的别名外，TapDucky 还接受 snake_case 形式，如 down_arrow、up_arrow、left_arrow、right_arrow、page_up、page_down、print_screen、scroll_lock、num_lock、caps_lock、string_delay、default_delay 等。这些在内部被归一化。

• 修饰键（支持左右变体）：

  • 左侧：CTRL/CONTROL、SHIFT、ALT/OPTION、GUI/WINDOWS/COMMAND/WIN
  • 右侧：RCTRL/RCONTROL、RSHIFT、RALT、RGUI/RWINDOWS/RCOMMAND

• 系统/导航键（包括别名）：

  • ENTER
  • ESC/ESCAPE
  • BACKSPACE/BKSP
  • TAB
  • SPACE
  • DELETE/DEL
  • INSERT/INS
  • HOME、END
  • PAGEUP、PAGEDOWN
  • 方向键：UP/UPARROW、DOWN/DOWNARROW、LEFT/LEFTARROW、RIGHT/RIGHTARROW
  • 锁定键：CAPSLOCK、NUMLOCK、SCROLLLOCK
  • PRINTSCREEN/PRINTSCRN/PRTSCN
  • PAUSE/BREAK
  • MENU/APP

• 功能键：

  • F1–F24