OK

README.md

@@ -1,39 +1,214 @@
-# Network-tools
+# NetPilot 网络调试工具
 
-一个基于 Tkinter 的 Windows 网络调试工具，重构版命名为 **NetPilot**。
+NetPilot 是一个基于 Python Tkinter 的 Windows 网络调试工具，面向日常桌面网络排障、网卡配置、局域网资产发现和连通性检测场景。
 
-## 功能
+应用采用左侧功能导航、右侧公共输出控制台的布局。所有功能页的执行日志、诊断过程和错误提示都会统一输出到右侧控制台，便于在不同工具之间切换时保留排障上下文。
 
-- 网卡配置：读取网卡、IPv4/IPv6、网关、DNS、DHCP、链路速率、接口索引、DHCP 服务器与租约时间。
+## 功能概览
-- 配置模板：保存常用网卡配置、套用模板到表单、删除模板。
-- DNS 诊断：读取本机 DNS 并补充常用 DNS 服务器做对比，支持多域名、多记录类型解析、耗时/失败原因统计、诊断摘要复制与 CSV 导出。
-- Ping 探测：支持持续/指定次数、间隔、超时、包大小、TTL、禁止分片、本地源 IP 下拉、CIDR/范围/列表批量探活、目标导入、CSV 导出、实时丢包率/平均延迟/抖动/质量统计。
-- 端口扫描：支持单端口测试、端口列表/范围、常用端口预设、批量主机/CIDR/IP 段扫描、并发/超时控制、只显示开放端口、服务名识别、可选 Banner 探测、开放端口复制与 CSV 导出。
-- 路由追踪：支持 IPv4/IPv6、主机名解析开关、单次/指定次数/持续追踪、最大跳数、单跳超时、高延迟阈值、逐跳 RTT 表格、超时/高延迟/波动诊断、原始输出保留、诊断摘要复制与 CSV 导出。
-- 环网检测：基于本机网卡统计、广播/组播流量、ARP/邻居表变化和网关 Ping 稳定性，判断疑似二层环路/广播风暴风险，支持单网卡/全部活动网卡、诊断摘要复制与 CSV 导出。
-- IP 冲突：支持本机 IP 冲突检测与安全限速网段扫描，结合地址状态、Tcpip 系统事件、ARP/邻居表和 IP/MAC 异常判断冲突风险，支持摘要复制与 CSV 导出。
-- 设备发现：支持当前网卡安全限速局域网扫描，发现在线/ARP 可见设备，展示 IP、MAC、主机名、厂商、来源网卡、延迟与发现方式，支持设备清单复制与 CSV 导出。
 
-## 运行
+### 网卡配置
+
+- 读取本机所有网卡，包括已启用和已禁用的网卡。
+- 显示网卡描述、MAC 地址、连接状态、IPv4 地址、子网掩码、默认网关、DNS 等信息。
+- 支持启用网卡、禁用网卡。
+- 支持 DHCP 自动获取和静态 IPv4 / DNS 配置切换。
+- 支持重新读取网卡信息，便于配置变更后快速刷新。
+- 支持网卡配置模板保存、套用和删除。
+
+说明：修改网卡状态、IP、网关、DNS 等配置通常需要以管理员权限运行程序。
+
+### DNS 诊断
+
+- 读取本机网卡 DNS 配置，并支持选择不同网卡进行诊断。
+- 支持手动填写或自动补全 DNS 服务器。
+- 支持多个域名、多个记录类型的解析测试。
+- 对不同 DNS 服务器的解析结果、耗时、失败原因进行对比。
+- 诊断结果以表格展示，支持复制摘要和导出 CSV。
+- 提供“修复异常”功能，用于处理常见 DNS 配置异常。
+
+### 设备发现
+
+- 按所选网卡的配置网段进行局域网设备发现。
+- 通过 Ping 探活和 ARP 信息补充发现设备。
+- 展示 IP、MAC、厂商、来源网卡、延迟、发现方式和备注。
+- 支持自动范围、刷新网卡、开始发现、停止发现。
+- 支持复制设备清单和导出 CSV。
+
+当前设备发现按配置网段扫描，不再做跨网段邻居表扩展，也不做主机名解析。
+
+### Ping 探测
+
+- 支持单目标 Ping 和批量 Ping。
+- 支持指定次数、持续探测、间隔、超时、包大小、TTL、禁止分片。
+- 支持选择本地源 IP。
+- 批量目标支持 CIDR、IP 范围和列表输入。
+- 输出实时探测结果，并统计丢包率、平均延迟、抖动和质量状态。
+- 支持导入目标和导出 CSV。
+
+### 端口扫描
+
+- 支持单主机单端口连通性测试。
+- 支持端口列表、端口范围和常用端口预设。
+- 支持批量主机扫描，目标可使用 CIDR、IP 范围或列表。
+- 支持并发数、超时、仅显示开放端口等控制项。
+- 支持服务名识别和可选 Banner 探测。
+- 支持复制开放端口和导出 CSV。
+
+### 路由追踪
+
+- 支持 IPv4 / IPv6 路由追踪。
+- 支持主机名解析开关。
+- 支持单次、指定次数和持续追踪。
+- 支持最大跳数、单跳超时、高延迟阈值等参数。
+- 展示逐跳 RTT 表格，并保留原始命令输出。
+- 对超时、高延迟、波动等情况给出诊断摘要。
+- 支持复制摘要和导出 CSV。
+
+### 环网检测
+
+- 基于本机网卡统计、广播 / 组播流量、ARP / 邻居表变化和网关 Ping 稳定性进行综合判断。
+- 用于辅助发现疑似二层环路、广播风暴或局域网异常波动。
+- 支持检测单个网卡或全部活动网卡。
+- 输出诊断摘要，支持复制和导出 CSV。
+
+### IP 冲突
+
+- 支持检测本机 IP 冲突风险。
+- 支持按网段进行安全限速扫描。
+- 结合地址状态、系统事件、ARP / 邻居信息、IP / MAC 异常关系判断冲突风险。
+- 支持自动范围、刷新网卡、复制摘要和导出 CSV。
+
+## 界面说明
+
+- 左侧为功能导航区。
+- 中间为当前功能页的参数和结果区域。
+- 右侧为公共输出控制台，所有页面共用。
+- 底部状态栏显示当前状态、本机名、操作系统和权限状态。
+
+公共控制台可用于查看执行过程、错误提示和诊断摘要；点击“清空”可以清除当前控制台内容。
+
+## 运行环境
+
+- 操作系统：Windows 10 / Windows 11
+- Python：建议 Python 3.10 或更高版本
+- UI 框架：Tkinter
+- 系统依赖：PowerShell、Windows 网络相关命令
+
+大部分只读诊断功能可以普通权限运行。涉及以下操作时建议使用管理员权限：
+
+- 启用或禁用网卡
+- 修改 IP、网关、DNS、DHCP
+- 执行部分需要系统网络信息的诊断或修复动作
+
+## 源码运行
+
+在项目根目录执行：
 
 ```powershell
 python main.py
 ```
 
-修改网卡配置需要以管理员权限运行程序。
+如果需要管理员权限，可以使用管理员 PowerShell 进入项目目录后再执行：
+
+```powershell
+cd E:\Git\Network-tools
+python main.py
+```
 
 ## 打包
 
-直接执行：
+项目提供了 Windows 打包脚本：
 
 ```powershell
 .\打包.bat
 ```
 
-打包输出：
+打包完成后，输出文件位于：
 
 ```text
-dist/NetworkTool.exe
+dist\NetworkTool.exe
 ```
 
-配置模板运行时会保存到程序同级目录的 `network_profiles.json`。
+打包脚本会优先使用本机指定的 Python 运行时，并在 `.packaging\pyinstaller` 下安装 PyInstaller；如果指定运行时不存在，则尝试直接调用系统中的 `pyinstaller`。
+
+## 目录结构
+
+```text
+Network-tools
+├─ assets                  # 图标等静态资源
+├─ core
+│  ├─ Function             # 网络检测和配置相关业务逻辑
+│  └─ ui                   # Tkinter 界面、主题和各功能页
+├─ main.py                 # 程序入口
+├─ 打包.bat                # PyInstaller 打包脚本
+├─ NetworkTool.spec        # PyInstaller 配置
+└─ README.md
+```
+
+## 配置和导出文件
+
+- 网卡配置模板会保存到程序同级目录的 `network_profiles.json`。
+- 各功能页的 CSV 导出文件由用户在导出时选择保存路径。
+- 程序不会主动上传网络检测结果，所有诊断和导出均在本机完成。
+
+## 常见问题
+
+### 为什么修改网卡配置失败？
+
+请确认程序以管理员权限运行。Windows 对网卡启用/禁用、IP 配置、DNS 配置等操作有权限限制。
+
+### 为什么设备发现扫不到某些设备？
+
+常见原因包括：
+
+- 目标设备禁用了 ICMP Echo 响应，无法被 Ping 探活。
+- 目标设备与当前网卡不在同一配置网段内。
+- 本机防火墙或安全软件限制了探测行为。
+- 交换机、VLAN、无线隔离或终端防火墙阻止了局域网发现。
+- 扫描期间目标设备未产生可见 ARP 信息。
+
+当前设备发现按所选网卡的配置网段扫描，不会跨网段扫描，也不会解析主机名。
+
+### 为什么 DNS 诊断的网卡数量和系统里看到的不一样？
+
+程序会尽量读取启用和禁用网卡，但部分虚拟网卡、隧道网卡、隐藏适配器或驱动异常的网卡，可能无法提供完整 DNS/IP 信息。可以先在网卡配置页刷新网卡，确认目标网卡是否能被系统命令读取。
+
+### 为什么部分按钮是灰色不可用？
+
+按钮状态会根据当前任务状态和网卡状态变化。例如扫描正在运行时会禁用开始按钮；没有选择有效网卡或当前网卡状态不支持某项操作时，也会禁用对应按钮。
+
+### 导出的 CSV 用 Excel 打开乱码怎么办？
+
+建议使用 Excel 的“数据 -> 自文本/CSV”导入方式，并选择 UTF-8 编码。也可以先用支持 UTF-8 的编辑器检查文件内容。
+
+## 开发说明
+
+界面层主要位于 `core/ui`：
+
+- `ui_main.py`：主窗口布局、侧边栏、公共输出控制台、页面切换。
+- `theme.py`：全局颜色、字体、ttk 样式。
+- `components.py`：公共 Page、Console、字段、按钮等组件。
+- `tab_*.py`：各功能页 UI 和事件逻辑。
+
+业务逻辑主要位于 `core/Function`：
+
+- `network_fun.py`：网卡读取和配置。
+- `dns_diag_fun.py`：DNS 诊断。
+- `device_discovery_fun.py`：设备发现。
+- `ping_fun.py`：Ping 探测。
+- `telnet_fun.py`：端口连通性和扫描。
+- `tracert_fun.py`：路由追踪。
+- `loop_fun.py`：环网检测。
+- `ip_conflict_fun.py`：IP 冲突检测。
+
+开发时建议先运行：
+
+```powershell
+python -m compileall main.py core
+```
+
+再启动界面进行手动验证：
+
+```powershell
+python main.py
+```