diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3550a30 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use flake diff --git a/.gitignore b/.gitignore index eb0cf13..7279f78 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ -# Created by https://www.toptal.com/developers/gitignore/api/windows,linux,macos,visualstudio,rider,csharp -# Edit at https://www.toptal.com/developers/gitignore?templates=windows,linux,macos,visualstudio,rider,csharp +# Created by https://www.toptal.com/developers/gitignore/api/windows,linux,macos,direnv,visualstudio,visualstudiocode,rider,csharp +# Edit at https://www.toptal.com/developers/gitignore?templates=windows,linux,macos,direnv,visualstudio,visualstudiocode,rider,csharp ### Csharp ### ## Ignore Visual Studio temporary files, build results, and @@ -399,6 +399,9 @@ FodyWeavers.xsd # JetBrains Rider *.sln.iml +### direnv ### +/.direnv/ + ### Linux ### # temporary files which can be created if a process still has a handle open of a deleted file @@ -525,6 +528,19 @@ fabric.properties # Android studio 3.1+ serialized cache file .idea/caches/build_file_checksums.ser +### VisualStudioCode ### +!.vscode/*.code-snippets + +# Local History for Visual Studio Code + +# Built Visual Studio Code Extensions +*.vsix + +### VisualStudioCode Patch ### +# Ignore all local history of files +.history +.ionide + ### Windows ### # Windows thumbnail cache files Thumbs.db @@ -727,6 +743,6 @@ $RECYCLE.BIN/ ### VisualStudio Patch ### # Additional files built by Visual Studio -# End of https://www.toptal.com/developers/gitignore/api/windows,linux,macos,visualstudio,rider,csharp +# End of https://www.toptal.com/developers/gitignore/api/windows,linux,macos,direnv,visualstudio,visualstudiocode,rider,csharp *.lscache diff --git a/AGENTS.md b/AGENTS.md index 5610418..f852932 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,146 +1,46 @@ # xidio Agents Instructions -xidio（XiDian Internet Diagnostic Intelligence Operator）是一款跨平台的校园网诊断工具，由 Project Hazelita 基于 C# 和 .NET 开发，专门针对西安电子科技大学的网络环境。 +xidio（Xidian Internet Diagnostic Intelligence Operator）是 Project Hazelita 基于 C# 和 .NET 10 开发的跨平台西电校园网诊断工具。 -在为 xidio 贡献代码前，请先阅读 `README.md` 了解项目最新情况，并仔细阅读本文件、遵循下面的指引。请确保你的修改是**最小化**的，并且与项目的现有内容保持一致、互不冲突。 +## 开始工作前 -## 各部分功能 +1. 阅读 `README.md` 了解当前能力与构建方式。 +2. 阅读 `docs/architecture.md` 和修改模块的相关文档。 +3. 对照 `ROADMAP.md` 确认需求边界；路线图是开发方向，不代表功能已实现。 +4. 检查当前分支和工作区，保留用户的现有修改。 -`xidio.Core` 主要负责诊断、修复和上报。 +## 修改原则 -### 诊断 / Diagnostics +- 保持修改最小化，避免与任务无关的重构、格式化或依赖升级。 +- 优先使用 .NET 跨平台 API；平台专用能力必须放入对应的 `xidio.Platform.*` Provider。 +- 不得在 `xidio.Core` 中使用 `Console`、Spectre.Console、Avalonia 或其他 UI API。 +- `xidio.Core` 应输出结构化数据，并明确分离诊断、修复和上报逻辑。 +- 所有 I/O 与长时间操作使用异步 API，接受 `CancellationToken`，必要时报告结构化进度。 +- 探测失败也是诊断数据；保留目标、时间、耗时、错误类型与必要原始信息，不得只返回布尔值。 +- 未获得用户明确同意时，不收集 hosts、代理、VPN、防火墙、安全软件、账号业务状态等敏感信息，不执行修复。 +- MAC、BSSID、账号、在线设备与日志中的个人信息默认脱敏；任何上报都必须 opt-in 且可预览。 -xidio 需要诊断用户设备，确定网络问题的根源。诊断过程分为**信息收集**和**分析**两步。 +## 架构边界 -#### 收集信息 +- `xidio.Core`：诊断、分析、修复、上报的抽象、模型与通用逻辑。 +- `xidio.CLI`：终端交互、进度展示、结果渲染与平台 Provider 组装。 +- `xidio.Platform.Windows`：Windows 系统 API、WLAN、RAS/PPPoE 及其他 Windows 专用收集。 +- `xidio.Platform.macOS`：macOS 系统命令与 API 适配。 +- `xidio.Platform.Linux`：Linux 系统 API，以及 `ip`、`resolvectl`、`nmcli`、`iw` 等工具的可控适配。 -xidio 将从用户及其设备上收集必要信息。以下列出部分需要采集的信息类别。 +新增平台信息时，先在 Core 定义平台无关的模型和接口，再在各 Provider 中实现。单一平台不支持某项能力时，应返回明确的“不支持/不可用”结果，不得伪造数据或导致整份报告失败。 -##### 用户场景信息 +## 验证 -xidio 会主动询问： +- 根据修改范围运行最小相关构建或测试，再考虑完整解决方案构建。 +- Windows：`dotnet build xidio/xidio.slnx -c Release`。 +- Linux/macOS：`dotnet build xidio/xidio.CLI/xidio.CLI.csproj -c Release -f net10.0`。 +- 平台专用修改必须说明实际验证平台；不得把交叉编译当作真实系统行为验证。 +- 对外部命令的解析应覆盖空输出、命令不存在、非零退出码、本地化输出和权限不足。 -1. 用户所在位置。 -2. 当前连接方式。连接方式划分为： - - **直接连接**：用户直接通过 Wi-Fi 连接校内任意 AP，或通过网口以 PPPoE 方式连接。 - - **间接连接**：用户通过路由器等方式接入，数据经校园网设施传输。 - - **其他连接**：用户通过手机热点等方式连接，数据未经过校园网设施。 -3. 遇到的问题。例如：无法连接 Wi-Fi；已连接但显示“无 Internet”；未跳转到 Portal；Portal 认证成功但无法打开网页；部分应用不能使用；拨号失败；拨号成功但无 Internet 等。 -4. 问题波及范围。例如：仅本机有问题；同宿舍其他人也有问题；同楼层其他人也有问题；不清楚。 +## Git 与文档 -这些信息有助于网管会判断是否为区域性问题。 - -##### 系统与网卡基础信息 - -xidio 需要收集： - -1. 操作系统信息：操作系统类型（Windows、Linux 或 macOS）、版本号；xidio 版本号；xidio 是否以管理员/root 权限运行。 -2. 时间：本机时间、某 NTP 服务器时间，以及两者的差值。 -3. 网络接口：所有网络接口及主网络接口（物理接口）的接口名称、类型、是否启用、是否已连接、（若有）MAC 地址、链路速度、MTU、接口 metric 等，以及当前默认路由所使用的具体网卡。 - -如果用户使用 Wi-Fi 连接，还需收集：当前 Wi-Fi 的 SSID、BSSID、RSSI、频段、信道、PHY 类型、认证/加密类型、连接时长、当前连接速率，以及可见的 SSID 列表。 - -如果用户使用 PPPoE 连接，还需收集：网线是否插好；对端是否有链路；链路速度；是否存在 PPPoE/宽带连接，若存在，则获取 PPPoE 的当前状态、分配到的 IP、DNS、默认路由。在可行的情况下，可尝试进行一次 RAS 拨号并记录 RAS 错误码；（在 Windows 上）还要检查宽带连接名称是否含有非 ASCII 字符，以及用户是否安装了 Npcap 或 WinPcap。 - -##### IP、DHCP、DNS、路由、ARP 信息 - -如果用户已连接到至少一个网络，xidio 将收集：IPv4 地址、IPv6 地址、子网掩码/前缀长度、是否通过 DHCP 获取地址（若是，则收集 DHCP 服务器地址、租约开始和过期时间）、默认网关、DNS 服务器、路由表、ARP/IPv6 Neighbor 表。 - -##### 本机因素 - -在征得用户同意后，xidio 可以进一步收集： - -1. 系统代理设置：包括 Windows Internet Options 代理、WinHTTP 代理、系统代理、环境变量 `HTTP_PROXY`/`HTTPS_PROXY`、macOS 网络代理等。 -2. VPN/TUN/TAP 相关状态：如 Clash TUN、v2rayN、WireGuard、OpenVPN、ZeroTier、Tailscale、WARP、VMware/VirtualBox 虚拟网卡、WSL 虚拟网卡等。 -3. DNS-over-HTTPS 与 Secure DNS 状态。 -4. hosts 文件内容。 -5. 防火墙状态。 -6. 安全软件及过滤型驱动。 -7. 浏览器代理设置。 - -##### 认证与业务状态 - -在征得用户同意后，xidio 可检查：认证服务器是否可达；当前用户是否已通过校园网认证；当前账号是否在线；当前设备是否出现在在线列表中；套餐是否生效；用户所属运营商/套餐类型；宽带优先级；是否欠费；是否达到设备数量上限。 - -##### 主动探测信息 - -我们选定以下目标进行主动探测： - -1. 校园内目标：认证服务器域名和 IP、校内若干服务的 HTTP/HTTPS 域名。 -2. 校园外目标：xidio 官方域名、HTTP 204 端点、HTTPS 固定响应体端点、TCP Echo 或 Connect 端点、UDP Echo/Jitter 端点。 - -执行探测或收集：ARP 默认网关信息；ICMP Ping 情况；到 80、443、53（TCP）的 TCP Connect 情况；UDP DNS 查询；UDP Echo/Jitter/丢包测试；HTTP GET 情况；HTTPS 握手与证书校验；DNS 解析情况（包括使用系统解析器和直接向当前 DNS 服务器查询，分别测试 A 和 AAAA 记录）。更进一步，还可进行 Traceroute/MTR、MTU/PMTUD 测试。 - -#### 分析 - -我们按以下顺序逐层排查问题。每次检测需覆盖所有层，且每层不能仅返回“是/否”，必须附带完整的探测信息。 - -```text -本机网卡 -> 有线/Wi-Fi 情况 -> IP 获取 -> 默认网关可达 -> 认证服务可达 -> 认证服务正常 -> DNS 正常 -> 探测目标可达 -> 具体协议 -``` - -下面给出典型的判断流程，xidio 默认按照该顺序排查，后续也支持用户自定义判断规则。 - -##### Wi-Fi 场景 - -###### 无法连接 Wi-Fi - -适用于设备附近扫不到校园 SSID、信号极弱，或认证失败的情形。SSID 不可见可能是 AP 覆盖不足或无线网卡问题；SSID 可见且信号不弱但无法连接，可能是配置文件损坏、认证方式错误或 AP 故障。xidio 可建议用户忘记网络后重新连接、移动到 AP 附近等。 - -###### Wi-Fi 连接成功但未获取到 IP - -适用于已关联 SSID/BSSID，但 IPv4 地址为 `169.254.x.x` 或为空，DHCP 服务器为空或请求超时等情形。若连接其他 SSID 也失败，则可能是本机 DHCP 服务、防火墙或驱动问题；若同一 AP 下仅个别用户失败，可能是本机网络栈或网卡驱动问题；若多个用户同时失败，则可能是 AP/接入交换机/VLAN/DHCP 中继问题。 - -###### 获取到 IP 但没有默认网关 - -适用于 DHCP 成功分配 IP，但默认网关为空，或路由表中无 `0.0.0.0/0` 的情形。可能由 DHCP 配置异常，或用户自行配置了错误的网络参数导致。 - -###### 有默认网关但不可达 - -适用于有默认网关，但 ARP 表中无对应 MAC 地址，且 Ping/TCP 探测网关失败、校园认证 IP 也不可达等情况。可能是 AP/交换机/网关/VLAN 异常。 - -###### 网关可达但认证页面打不开 - -如果解析 Portal 域名失败但 IP 可达，则可能是 DNS 故障，此时可检查 DNS 和 DoH/公共 DNS 状况。 - -如果 Portal 的域名和 IP 均不可达，可能是校内认证服务存在故障。 - -###### 认证成功但无法上网 - -按层次分析：如果能访问公网 IP 但无法解析域名，则问题可能在 DNS。若 DNS 正常但 TCP 80/443 不通，可能是出口路由、防火墙、代理或 VPN 问题。若 TCP 80/443 正常但浏览器无法打开网页，可能是系统代理、浏览器代理、证书、系统时间或插件问题。若 TCP 正常但 UDP 丢包严重，可能与 UDP/QoS/运营商出口/CDN/上游拥塞有关。若 IPv4 正常但 IPv6 异常（或反之），则可能是双栈配置问题，浏览器 Happy Eyeballs 机制或地址优先级导致体验异常。 - -##### PPPoE 场景 - -###### 以太网无链路 - -适用于以太网未连接、无 carrier 或链路速度为 0 的情形。通常由网线未连接或连接错误导致。 - -###### 有链路但未拨号 - -适用于以太网处于 `up` 状态，但没有 PPP 接口和 PPPoE 默认路由的情形，一般是因为尚未拨号。 - -###### PPPoE 拨号失败 - -若有拨号错误码，可对照错误码进行诊断。如果接口有链路但 PPPoE Discovery 无任何响应，则优先考虑接入侧问题。 - -###### PPPoE 拨号成功但无法联网 - -需检查 PPP 接口是否获取到 IP、DNS，默认路由是否经过 PPP 接口，以及是否开启了系统代理等。 - -##### 其他连接场景 - -对于其他连接方式，xidio 不提供专门的分析帮助，因为这些情况通常与校园网无关。 - -#### 其他问题 - -##### Captive Portal Detection 失效 - -若未自动弹出认证页面，但可手动访问 Portal，则只是 Captive Portal 探测机制失效；若域名访问失败而 IP 访问成功，则为 DNS 问题；若两者均失败，则通常是认证服务器路径或网关问题。 - -##### Windows 侧的“无 Internet”连接 - -Windows 显示的“无 Internet”主要依赖 NCSI 探测结果。xidio 不应仅以此为依据，应手动测试默认网关、Portal、DNS、HTTP 204、HTTPS 以及主动探测目标等情况，以判断是否真正无 Internet 连接。 - -##### 仅部分应用无法访问互联网 - -适用于能上 QQ 但不能打开网页等场景。此类问题成因复杂，xidio 可进行基本探测，如基础 HTTP/HTTPS 连通性、DNS 解析、TCP 443、UDP 443/QUIC 等。 +- 遵循 Git Flow：功能与普通修复从 `develop` 分支开始，已发布版本的紧急修复从 `main` 建立 `hotfix/*`。 +- 提交信息遵循 Conventional Commits，推荐使用精确 scope，例如 `feat(linux): collect wireless details`。 +- 不要重写、压缩或删除用户现有提交，除非用户明确要求。 +- 功能范围或计划变化时更新 `ROADMAP.md`；用户可见的使用、构建或平台状态变化时同步更新 `README.md` 和 `CHANGELOG.md`。 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e7616ad --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +本项目的所有重要变更都将记录在此文件中。 + +本文档格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。 + +## [0.1.0] - 2026-05-22 + +### Added + +- 增加交互式 CLI，用于收集用户场景并展示网络诊断报告。 +- 增加 `xidio.Core` 诊断抽象、结构化模型、进度报告和可取消的信息收集流程。 +- 增加 Windows 平台网络诊断 Provider，覆盖网络接口、地址、网关、DHCP、DNS、metric、路由和 Wi-Fi 信息。 +- 增加 macOS 平台网络诊断 Provider 的初始实现。 +- 增加项目 Logo、图标与 Figma 设计源文件。 +- 增加 CI、标签发布工作流与 Nerdbank.GitVersioning 版本管理。 + +[0.1.0]: https://github.com/LyCecilion/xidio/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a0e6d28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# Contributing to xidio + +感谢你愿意帮助 xidio 更准确地诊断西电校园网问题。我们接受 Issue 和 Pull Request；不论是问题复现、平台适配、诊断规则还是文档改进，都欢迎参与。 + +## 提交 Issue + +在新建 Issue 前，请先搜索是否已有相同问题。报告 Bug 时建议包含： + +- xidio 版本、操作系统与系统版本； +- 连接方式与可稳定复现的步骤； +- 期望结果、实际结果与必要日志； +- 是否以管理员或 root 权限运行。 + +发布日志、截图或诊断报告前，请删除账号、密码、完整 MAC/BSSID、IP 等不必要的个人或网络标识信息。 + +## 提交 Pull Request + +1. 从最新的 `develop` 分支创建短期分支：新功能使用 `feature/`，普通修复使用 `fix/`。仅针对已发布版本的紧急修复从 `main` 创建 `hotfix/`。 +2. 保持修改最小化，不要在同一 PR 中混入无关重构。 +3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)，例如 `feat(linux): collect default route` 或 `fix(core): preserve probe cancellation`。 +4. 根据修改所在平台运行构建和相关测试，并在 PR 中说明未能验证的平台。 +5. 默认将 PR 提交到 `develop`，在描述中关联 Issue，并说明用户可见变化、验证方法与隐私影响。 + +## 开发约定 + +- 先阅读 [`README.md`](./README.md)、[`AGENTS.md`](./AGENTS.md) 与 [`docs/architecture.md`](./docs/architecture.md)。 +- `xidio.Core` 不得依赖 CLI/GUI，应输出结构化数据，并为长任务提供异步、进度与取消支持。 +- 平台专用能力放入相应的 `xidio.Platform.*` 项目，通过 Core 中的抽象调用。 +- 收集敏感信息或执行修复前必须获得用户明确同意；上报始终保持 opt-in。 + +## 构建 + +Windows： + +```powershell +dotnet restore xidio/xidio.slnx +dotnet build xidio/xidio.slnx -c Release --no-restore +``` + +Linux 或 macOS： + +```bash +dotnet restore xidio/xidio.CLI/xidio.CLI.csproj +dotnet build xidio/xidio.CLI/xidio.CLI.csproj -c Release -f net10.0 --no-restore +``` + +更多开发环境信息见 [`README.md`](./README.md#-development)。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c17d067 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Project Hazelita + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 54877af..af48ab2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +
@@ -17,6 +17,109 @@ _✨**Xidian Internet Diagnostic Intelligence Operator**✨_\
-## 简介 +## 📖 About -xidio _(XiDian Internet Diagnostic Intelligence Operator)_ 是一款基于 C# 和 .NET 架构的、由 Project Hazelita 开发的、跨平台的适用于西安电子科技大学的校园网诊断工具。xidio 以 [NanCunChild](https://github.com/NanCunChild) 的项目 [Marduk](https://github.com/NanCunChild/Marduk) 为灵感来源，同时具有 CLI 和 GUI 两种用户界面，致力于成为一款简单易用且足够强大的辅助工具。 +xidio _(Xidian Internet Diagnostic Intelligence Operator)_ 是一款由 Project Hazelita 开发的西安电子科技大学校园网诊断工具。项目基于 C# 和 .NET 10，面向 Windows、Linux 与 macOS，希望将分散的网卡、IP、DHCP、DNS、路由、Wi-Fi 及主动探测信息整理为可理解、可上报的诊断结果。 + +xidio 的灵感来自 [NanCunChild](https://github.com/NanCunChild) 的 [Marduk](https://github.com/NanCunChild/Marduk)。项目当前处于早期开发阶段：v0.1.0 已提供 CLI 与以 Windows 为主的信息收集能力，其他平台与完整分析、修复、上报功能仍在实现中。 + +## ✨ Features + +- **交互式场景问询**：通过 CLI 收集位置、连接方式、问题现象与影响范围，为后续判断补充用户上下文。 +- **分层网络信息收集**：收集操作系统、时间、网络接口、IP、DHCP、DNS、默认路由、邻居表和主动探测结果。 +- **Windows 深度适配**：利用 Windows 系统能力获取网卡、Wi-Fi、路由、代理与 PPPoE 等诊断信息。 +- **跨平台架构**：通用诊断逻辑位于 `xidio.Core`，平台差异由独立 Provider 隔离；当前已有 Windows 和 macOS Provider，Linux Provider 正在路线图中。 +- **结构化与可取消**：核心诊断输出结构化数据，长时间任务支持进度报告和 `CancellationToken`。 + +## 🚀 Quick Start + +当前版本需要 [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)。从源码运行 CLI： + +```bash +git clone https://github.com/LyCecilion/xidio.git +cd xidio +dotnet restore xidio/xidio.CLI/xidio.CLI.csproj +dotnet run --project xidio/xidio.CLI/xidio.CLI.csproj -f net10.0 +``` + +Windows 上需要调用 Windows 平台 Provider 时，请将最后的目标框架改为 `net10.0-windows`。部分系统信息需要管理员或 root 权限；仅在信任项目源码且确有需要时提权运行。 + +## 📁 Project Structure + +```text +xidio/ +├── assets/ # Logo、图标与设计源文件 +├── docs/ # 架构与核心开发准则 +├── xidio/ +│ ├── xidio.CLI/ # 命令行入口与交互式报告 +│ ├── xidio.Core/ # 诊断模型、收集、分析与抽象 +│ ├── xidio.Platform.Windows/ # Windows 平台 Provider +│ ├── xidio.Platform.macOS/ # macOS 平台 Provider +│ └── xidio.slnx # .NET 解决方案 +├── AGENTS.md # 仓库内 AI Agent 协作约定 +├── CONTRIBUTING.md # 贡献指南 +├── ROADMAP.md # 开发路线与诊断范围 +└── flake.nix # 可选的 Nix 开发环境 +``` + +## 💻 Development + +通用要求： + +- 使用 `global.json` 声明的 .NET 10 SDK；代码风格由 `Directory.Build.props` 中的 .NET Analyzer 规则约束。 +- 修改前阅读 [`AGENTS.md`](./AGENTS.md)、[`docs/architecture.md`](./docs/architecture.md) 和相关模块文档。 +- 分支遵循 Git Flow，提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)。 + +### Windows + +安装 .NET 10 SDK，使用 PowerShell 运行： + +```powershell +dotnet restore xidio/xidio.slnx +dotnet build xidio/xidio.slnx -c Debug +dotnet run --project xidio/xidio.CLI/xidio.CLI.csproj -f net10.0-windows +``` + +### Linux + +可以从发行版安装 .NET 10 SDK，也可使用 Nix。原生 SDK 环境下： + +```bash +dotnet restore xidio/xidio.CLI/xidio.CLI.csproj +dotnet build xidio/xidio.CLI/xidio.CLI.csproj -c Debug -f net10.0 +``` + +使用 Nix 时，无需全局安装 .NET SDK： + +```bash +nix develop +dotnet build xidio/xidio.CLI/xidio.CLI.csproj -c Debug -f net10.0 +``` + +### macOS + +安装 .NET 10 SDK 后运行： + +```bash +dotnet restore xidio/xidio.CLI/xidio.CLI.csproj +dotnet build xidio/xidio.CLI/xidio.CLI.csproj -c Debug -f net10.0 +dotnet run --project xidio/xidio.CLI/xidio.CLI.csproj -f net10.0 +``` + +Apple Silicon 与 Intel Mac 也可使用已启用 `aarch64-darwin` 和 `x86_64-darwin` 的 `nix develop`。 + +## 🗺️ Roadmap + +详细的诊断范围、分析顺序与分阶段开发计划见 [`ROADMAP.md`](./ROADMAP.md)。 + +## 📰 Changelog + +版本变更记录见 [`CHANGELOG.md`](./CHANGELOG.md)，文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范。 + +## 🤝 Contributing + +我们欢迎通过 Issue 报告问题或提出建议，也接受 Pull Request。提交前请阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。 + +## 📜 License + +xidio 以 [MIT License](./LICENSE) 开源。 diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..ab65422 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,155 @@ +# xidio Roadmap + +本文档定义 xidio 的开发路线、诊断范围与分析顺序。其中的未勾选项为计划，不代表当前版本已具备对应能力。 + +## 总体目标 + +xidio 需要在 Windows、Linux 和 macOS 上完成“信息收集 → 分层分析 → 可选修复 → 用户同意后上报”的完整流程。每层诊断必须附带完整探测信息，不得只返回“是/否”。 + +```text +本机网卡 -> 有线/Wi-Fi 情况 -> IP 获取 -> 默认网关可达 +-> 认证服务可达 -> 认证服务正常 -> DNS 正常 +-> 探测目标可达 -> 具体协议 +``` + +## 阶段计划 + +### 0.1 基础信息收集 + +- [x] 建立 `xidio.Core`、CLI 和平台 Provider 抽象。 +- [x] 增加用户场景问询与结构化诊断报告。 +- [x] 实现以 Windows 为主的系统、网卡、IP、路由、Wi-Fi 与主动探测信息收集。 +- [x] 提供 macOS Provider 的初始实现。 + +### 0.2 跨平台收集补全 + +- [ ] 建立并接入 `xidio.Platform.Linux`。 +- [ ] 对齐 Windows、Linux 和 macOS 的基础系统、网卡、路由、DNS、邻居表、代理与 Wi-Fi 收集能力。 +- [ ] 补全 PPPoE 链路、会话、错误码与路由检查。 +- [ ] 为外部命令解析与平台特性增加测试。 + +### 0.3 分析引擎与扩展探测 + +- [ ] 实现本文档定义的 Wi-Fi、PPPoE、Captive Portal、NCSI 和部分应用故障判断流程。 +- [ ] 实现可配置、可测试的判断规则，并保留每个结论的证据链。 +- [ ] 补全直接 DNS、UDP Echo/Jitter/丢包、Traceroute/MTR 与 MTU/PMTUD 探测。 +- [ ] 区分 IPv4/IPv6、TCP/UDP 和 HTTP/HTTPS/QUIC 问题。 + +### 0.4 修复与上报 + +- [ ] 按 Drip、Drift、Current、Surge 等级实现权限、确认、回滚与审计日志。 +- [ ] 实现不同平台的基础修复 Provider，优先支持可回滚操作。 +- [ ] 实现崩溃、匿名使用情况与校园网情况三类上报；所有上报保持 opt-in。 +- [ ] 允许用户在上报前预览、脱敏和删除字段。 + +### 1.0 用户体验与稳定发布 + +- [ ] 提供稳定的 CLI 命令与可导出报告格式。 +- [ ] 完成基于 Avalonia 的跨平台 GUI。 +- [ ] 完成三个目标平台的 CI、发布包、安装指南与真实校园网场景验证。 +- [ ] 完成隐私说明、敏感字段盘点与上报数据保留策略。 + +## 信息收集范围 + +### 用户场景 + +xidio 应主动询问： + +1. 用户所在校区、建筑类型，以及可选的楼栋和楼层。 +2. 当前连接方式： + - **直接连接**：直接通过 Wi-Fi 连接校内 AP，或通过网口以 PPPoE 方式连接。 + - **间接连接**：通过路由器等设备接入，数据仍经校园网设施传输。 + - **其他连接**：通过手机热点等方式连接，数据未经校园网设施。 +3. 问题现象：无法连接 Wi-Fi、已连接但显示无 Internet、未跳转 Portal、认证后无法打开网页、仅部分应用不可用、拨号失败、拨号后无 Internet 等。 +4. 影响范围：仅本机、同宿舍、同楼层或不清楚。 + +对于其他连接方式，xidio 仅提供通用信息，不应将其问题归因于校园网。 + +### 系统、时间与网卡 + +- 操作系统类型与版本、xidio 版本、是否以管理员/root 运行。 +- 本机时间、NTP 或可靠网络时间、两者差值。 +- 所有接口及主物理接口的名称、类型、启用/连接状态、脱敏 MAC、链路速率、MTU、metric、收发包、错误包和丢弃包统计。 +- 默认路由使用的具体网卡，以及访问校内/校外目标时实际命中的路由。 + +Wi-Fi 场景还需收集： + +- 关联状态、SSID、脱敏 BSSID、RSSI/信号质量、频段、信道、PHY 类型和认证/加密类型。 +- 连接时长、当前速率、可见 SSID 列表、是否为已知校园 AP，以及可获得时的最近连接失败原因码。 + +PPPoE 场景还需收集： + +- 网线/carrier 状态、对端链路和链路速率。 +- PPPoE/宽带连接是否存在，以及未拨号、连接中、已连接、已断开等状态。 +- PPP 接口获取的 IP、DNS 和默认路由。 +- 可行时进行一次受控 RAS 拨号并记录错误码，包括 691、651、678/718 和 720 等常见情况。 +- Windows 宽带连接名称是否包含非 ASCII 字符，以及是否安装 Npcap/WinPcap。 + +### IP、DHCP、DNS、路由与邻居表 + +当至少连接一个网络时，收集： + +- IPv4/IPv6 地址、子网掩码/前缀长度，以及是否存在 `169.254.x.x` 或可疑静态地址。 +- DHCP 获取状态、服务器地址、租约开始与过期时间。 +- 默认网关、DNS 服务器、路由表、ARP/IPv6 Neighbor 表。 +- 多默认路由及其 metric，以及实际出站选路。 + +### 本机干扰因素 + +以下收集必须先征得用户同意： + +- Windows Internet Options、WinHTTP、系统、环境变量 `HTTP_PROXY`/`HTTPS_PROXY` 与 macOS 网络代理。 +- Clash TUN、v2rayN、WireGuard、OpenVPN、ZeroTier、Tailscale、WARP、VMware/VirtualBox、WSL 等 VPN/TUN/TAP/虚拟网卡状态。 +- DNS-over-HTTPS/Secure DNS、hosts 文件、防火墙、常见安全软件/过滤驱动与浏览器代理设置。 + +### 认证与业务状态 + +征得用户同意后，可检查： + +- 认证服务器可达性与当前认证状态。 +- 账号在线状态、当前设备是否在在线列表、最近登录错误码与强制下线情况。 +- 套餐是否生效、运营商/套餐类型、宽带/出口优先级、欠费与设备数上限。 +- 是否存在异常在线设备。 + +### 主动探测 + +目标包含校内认证服务域名/IP、若干校内 HTTP/HTTPS 服务，以及校外 xidio 官方域名、HTTP 204、HTTPS 固定响应体、TCP Connect/Echo 和 UDP Echo/Jitter 端点。按需执行： + +- ARP 默认网关检查、ICMP Ping，但不得仅根据 ICMP 失败判定网络不可达。 +- 到 80、443、53/TCP 的 TCP Connect，以及 UDP DNS 查询。 +- UDP Echo/Jitter/丢包测试、HTTP GET（可选不跟随重定向）、HTTPS 握手与证书校验。 +- 系统解析器与直接查询当前 DNS 服务器的 A/AAAA 记录对比。 +- 深度模式下的 Traceroute/MTR 与 MTU/PMTUD 测试，尤其关注 PPPoE。 + +## 典型分析流程 + +### Wi-Fi + +1. **无法连接 Wi-Fi**：SSID 不可见可能是 AP 覆盖或网卡问题；SSID 可见且信号不弱但连接失败，检查配置文件、认证方式与 AP 状态。可建议忘记网络后重连或移近 AP。 +2. **已关联但未获取 IP**：检查空地址、`169.254.x.x`、DHCP 服务器缺失或请求超时。其他 SSID 也失败时优先本机 DHCP/防火墙/驱动；单 AP 下多人失败时优先 AP、交换机、VLAN 或 DHCP 中继。 +3. **已获取 IP 但无默认网关**：检查 DHCP 配置和用户手动配置，确认路由表是否存在 `0.0.0.0/0`。 +4. **默认网关不可达**：结合 ARP、Ping/TCP 网关探测和校园认证 IP 可达性，判断 AP/交换机/网关/VLAN 异常。 +5. **网关可达但 Portal 不可用**：Portal 域名失败而 IP 成功时检查 DNS、DoH 和公共 DNS；域名与 IP 都失败时检查校内认证服务。 +6. **认证成功但无法上网**：依次比较公网 IP、DNS、TCP 80/443、浏览器、代理/VPN、证书/系统时间、UDP 质量与 IPv4/IPv6，考虑 Happy Eyeballs 和地址优先级影响。 + +### PPPoE + +1. **以太网无链路**：检查接口连接、carrier 与链路速率，优先提示网线未接或接错。 +2. **有链路但未拨号**：以太网接口 `up` 但不存在 PPP 接口或 PPPoE 默认路由时，提示用户拨号。 +3. **拨号失败**：优先解释 RAS 错误码；有链路但 PPPoE Discovery 无响应时，优先考虑接入侧问题。 +4. **拨号成功但无法上网**：检查 PPP 接口的 IP、DNS、默认路由和系统代理。 + +### 其他典型问题 + +- **Captive Portal Detection 失效**：可手动打开 Portal 时仅判定为自动探测失效；域名失败而 IP 成功时判定 DNS 问题；两者都失败时检查认证服务器路径或网关。 +- **Windows “无 Internet”**：不得仅依赖 NCSI，应独立测试默认网关、Portal、DNS、HTTP 204、HTTPS 和主动探测目标。 +- **仅部分应用无法联网**：比较 HTTP/HTTPS、DNS、TCP 443、UDP 443/QUIC、代理、VPN 和双栈表现，不根据单一应用直接归因。 + +## 修复安全等级 + +- **Drip**：完全只读，仅收集和分析。 +- **Drift**：可回滚且风险较低的修复，如关闭已确认失效的代理、刷新 DNS 缓存、重新获取 DHCP 租约。 +- **Current**：可回滚但会改变网络配置的修复，如修改 DNS、调整 metric、临时禁用冲突虚拟网卡或在有充分证据时临时禁用 IPv6。 +- **Surge**：侵入式修复，如重置 Winsock/IP 协议栈、Windows 网络重置、驱动回滚/更新/设备删除和电源策略修改。 + +所有修复必须获得用户明确确认并留下日志；除 Surge 外的操作必须可回滚。 diff --git a/assets/xidio_icon.png b/assets/xidio_icon.png new file mode 100644 index 0000000..162440d Binary files /dev/null and b/assets/xidio_icon.png differ diff --git a/assets/xidio_logo.png b/assets/xidio_logo.png new file mode 100644 index 0000000..21605d0 Binary files /dev/null and b/assets/xidio_logo.png differ diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..fe90317 --- /dev/null +++ b/flake.lock @@ -0,0 +1,27 @@ +{ + "nodes": { + "nixpkgs": { + "locked": { + "lastModified": 1783522502, + "narHash": "sha256-iffAls3iaNTyJC2faYcUXSI+Gp02cDjYl+MygxKl2GI=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "0bb7ec54c8483066ec9d7720e780a5caa71f8612", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "nixpkgs": "nixpkgs" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..3557606 --- /dev/null +++ b/flake.nix @@ -0,0 +1,59 @@ +{ + description = "xidio .NET development environment"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + }; + + outputs = + { nixpkgs, ... }: + let + supportedSystems = [ + "x86_64-linux" + "aarch64-linux" + "x86_64-darwin" + "aarch64-darwin" + ]; + + forAllSystems = nixpkgs.lib.genAttrs supportedSystems; + in + { + devShells = forAllSystems ( + system: + let + pkgs = import nixpkgs { inherit system; }; + in + { + default = pkgs.mkShell { + packages = with pkgs; [ + dotnet-sdk_10 + git + pkg-config + ] + ++ lib.optionals stdenv.isLinux [ + clang + lld + ]; + + buildInputs = with pkgs; [ + icu + openssl + zlib + ]; + + DOTNET_CLI_TELEMETRY_OPTOUT = "1"; + DOTNET_NOLOGO = "1"; + + LD_LIBRARY_PATH = pkgs.lib.optionalString pkgs.stdenv.isLinux ( + pkgs.lib.makeLibraryPath [ + pkgs.icu + pkgs.openssl + pkgs.stdenv.cc.cc.lib + pkgs.zlib + ] + ); + }; + } + ); + }; +}