wifit3 Textual TUI架构：三屏流程、热键与模态交互完整指南

【免费下载链接】wifit3Wifite but USB-only & cross-platform.项目地址: https://gitcode.com/GitHub_Trending/wi/wifit3

wifit3 是一个跨平台（Linux / Windows / macOS）的USB 专用 Wi-Fi 审计工具，基于 Python 的 Textual 框架构建纯终端 TUI 界面——无需aircrack-ng、reaver等外部依赖，UI 全部由 Textual 的App/Screen/ModalScreen三层结构实现。本文带你读懂它的主 App 装配方式、Splash → Scanner → Focus 的三屏流转、各屏热键设计，以及 6 类模态交互的细节。

一、主App装配：一切从 WifiteApp 开始

整个 TUI 的入口是 src/wifit3/ui/app.py 中的WifiteApp（继承 Textual 的App）。on_mount里一次性注册三张屏幕并压入栈底：

• SplashView（名splash）——启动页/选卡页
• ScannerView（名scanner）——AP 扫描列表页
• FocusViewV2（名focus）——单目标"路由器管理"页

同时启动两个常驻轮询：每0.5 秒轮询一次 USB 总线（DeviceWatch，热插拔感知），每2 秒轮询一次破解任务状态（_poll_jobs）。屏幕之间用push_screen/switch_screen切换，文本选中后还会自动复制到剪贴板并弹出 Toast 提示（on_text_selected）。

全局热键只有两个，定义在WifiteApp.BINDINGS：

二、第一屏 Splash：设备选择与一键启动

Splash 屏（splash.py）由四部分构成：ANSI Logo、状态行、设备列表、START/Uninstall按钮。它的核心交互是按设备数量自适应：

• 单张网卡：显示纯高亮列表（ListView），双击或按Enter直接启动；
• 多张网卡：切换为复选框列表（SelectionList），默认全选，可勾选子集再启动（多卡聚合嗅探）；
• 启动过程是异步 worker：perform_start逐卡调用device_manager.bringup，期间冻结设备轮询防止列表跳动，任一张就绪即switch_screen("scanner")；
• Uninstall按钮把选中网卡交还给操作系统（删除 udev 规则 / 卸载 WinUSB），macOS 无安装步骤会自动隐藏该按钮。

三、第二屏 Scanner：15FPS 实时扫描列表

Scanner 屏（scanner.py）是信息密度最高的一屏：

• AP 表：DataTable展示 SSID / 信道 / 信号 / Beacon 数 / 客户端数 / 加密 / WPS / 厂商指纹，以15 FPS原地刷新单元格——只有值变化才重绘，隐藏 SSID 显示斜体<Hidden>或"同父 BSSID 猜测"后缀?；
• 生命周期管理：10 秒无 Beacon 的行变暗（stale），30 秒后整行清除（evict）；
• 表头信道读数：_ChannelReadout用 Reactive 把 Header 右侧时钟位置替换为实时跳频信道（CH: 006 | CH: 048），多卡各自显示；
• Beacon 闪烁：Beacon 计数增长时，🥓列加粗闪烁 0.2 秒；
• WPS PBC 自动入侵（默认开启）：检测到物理按键窗口时自动暂停跳频、锁信道、抓取 PSK，完成后恢复扫描。

光标停在某行时按Enter，即可进入第三屏 Focus。

四、第三屏 Focus：路由器管理视图

Focus 屏（focus_v2/screen.py）采用横向"网络拓扑"布局，自上而下三条带：

1. 顶栏：‹ Scanner返回按钮 + 一排攻击按钮（ARP Replay / ChopChop / AutoDeauth / PMKID / WPS PIN / EvilTwin / Stop PBC），按钮的显示、禁用、文案全部由refresh_buttons从 Campaign 状态直接读取——目标加密是 WEP 才出 Replay 按钮，WPA3-only 会禁用 Deauth；
2. 中栏：网卡卡片 | 包速率仪表盘 | 路由器三端点，网卡与路由器用 20 列宽的 ANSI 艺术图，收到包时对应端点的 LED 会闪烁（_drive_leds）；
3. 底栏：左侧 LOG（带时间戳的树形日志，treelog.py），右侧 CLIENTS 客户端列表，每个客户端行内带红色✕单发去认证按钮。

进入 Focus 时自动把信道池锁到目标信道（array.set_channel），并打印历史捕获摘要。攻击热键来自 campaigns/ 各战役类注册的hotkey属性，与按钮一一对应：

底部 Footer 的按键提示会通过check_action+_sync_bindings与按钮状态实时同步——按钮灰掉的键，Footer 里也同步变灰。

五、模态交互：6 类 ModalScreen 覆盖全生命周期

wifit3 的模态全部基于 TextualModalScreen，按语义分为几类：

1. 错误模态（error_modals.py）——两级设计：

• FatalErrorModal：USB 后端级不可恢复错误，红色边框，禁用所有键位（Escape 也不可关闭），只能"Copy details / Quit"，trace 支持 OSC-52 一键复制；
• RecoverableErrorModal：网卡中途丢失，橙色边框，提供"Back to Splash"——App 会弹空屏幕栈、重置 Splash 状态并关闭死掉的网卡池（recover_to_splash）。

2. 热插拔对话框（new_device.py）：会话中插入新支持的网卡时弹出友好提示"Yes / No"，Escape等于"No"；选"Yes"则就地 bring up 并入池，多卡聚合立即生效。

3. 信道过滤对话框（channel_filter.py）：热键a全选、2/5一键选 2.4G / 5G、n清空、Enter确认，Escape取消；选全频段会被归一化为"无过滤"，便于热插拔后重新铺满频段。

4. Vault 抽屉（vault_drawer.py）：v呼出的底部滑出式模态——内容面板用offset-y: 100% → 0%的 200ms 三次缓动动画上滑，左表右详情 + 任务面板；热键z导出 Zip、o打开捕获目录、再按v或点击遮罩关闭。

5. 业务模态：EvilTwin 输入模态（eviltwin_modal.py）、客户端指纹详情（clients_list 的FingerprintModal）、安装/卸载确认（confirm_install.py / confirm_uninstall.py，y/n应答）、重插提示（replug.py）等。

6. 轻提示 Toast：非阻塞的notify用于任务完成（如SUCCESS PSK: xxx）、复制成功等场景，成功/警告/错误三种 severity 配色，默认 6 秒自动消失。

六、细节速查：让 TUI 像桌面应用的关键

• 主题系统：themes.py 注册多套 Textual 主题，Ctrl+P内换肤即时生效，Logo 的 ANSI 艺术会随主题重着色（recolor_logo）；
• 防抖与防抖重绘：Scanner 用set_interval(1/15)合并刷新，Focus 用_last_status快照跳过无变化重绘，避免终端刷屏；
• 线程安全：RX 读线程回调通过call_soon_threadsafe回到事件循环，模态统一用call_later延迟到消息泵上下文中 push，避免NoActiveAppError；
• 优雅退出：action_quit先持久化配置、杀掉所有运行中任务、关闭网卡池，再exit。

想动手看实现，建议从 src/wifit3/ui/app.py 入手，沿SplashView → ScannerView → FocusViewV2的阅读顺序走一遍三屏，再对照 tests/ui/ 下的 40+ 个交互测试理解每个热键的行为契约。

⚠️ 免责声明：wifit3 直接操作 USB 硬件寄存器，请仅用于你拥有或已获明确授权审计的网络。

【免费下载链接】wifit3Wifite but USB-only & cross-platform.项目地址: https://gitcode.com/GitHub_Trending/wi/wifit3