NetRoute-Diagnose

中文文档 · English documentation

Why did this app domain go DIRECT or PROXY? Read-only DNS → rule → policy → egress diagnostics for Clash, OpenClash, and Mihomo.

为什么这个 App 域名走直连或代理？面向 Clash、OpenClash、Mihomo 的只读 DNS → 规则 → 策略 → 出口诊断。

NetRoute-Diagnose is a read-only network path diagnostic tool for Clash and OpenClash/Mihomo users. It explains the first matching YAML rule for an app domain and can add optional DNS and egress observations. NetRoute-Diagnose 是 面向 Clash/OpenClash/Mihomo 用户的只读网络路径诊断工具：解释 App 域名的 YAML 首个 命中规则，并可补充可选的 DNS 与出口观测；内置微信、Apple、Google 和 OpenAI 示例。

Start here / 从这里开始

• Problem / 问题: identify whether a domain expected to be DIRECT or PROXY conflicts with the first matching Clash/OpenClash/Mihomo rule. 定位预期直连或代理的域名是否与首个匹配规则冲突。
• For / 适合谁: users who want a readable report instead of manually tracing long rule lists. 适合不想手工追踪长规则列表的用户。
• Start / 如何开始: install from PyPI when the release upload is available, then run the included offline example below. PyPI 发布可用后安装，再运行下方的 离线示例即可。

Typical scenarios / 三个典型场景

1. WeChat unexpectedly uses a proxy / 微信意外走代理 — compare the expected DIRECT route with the first matching Clash/OpenClash rule.
2. Apple, Google, or OpenAI takes the wrong route / Apple、Google 或 OpenAI 路径异常 — use the built-in profiles to see which rule is responsible and whether static analysis is certain.
3. Compare egress observations / 比较出口观测 — compare system, direct, or an explicit HTTP-proxy request to help distinguish a route assumption from an observed public egress result.

Quick Start / 快速开始

When the current release is available on PyPI, ordinary users can install it without Git knowledge or a development checkout. 当前版本在 PyPI 可用后，普通用户无需 了解 Git 或准备开发环境即可安装：

python -m pip install --upgrade netroute-diagnose

The GitHub release source package remains available when you prefer that installation method. 若希望使用 GitHub 发布源码包，仍可执行：

python -m pip install "https://github.com/HHHTTT-1977/NetRoute-Diagnose/archive/refs/tags/v0.1.2.zip"

Then run the built-in, fully offline example. 下面的示例完全离线，不会执行 DNS 或出口 IP 请求：

30-second demo / 30 秒演示

netroute-diagnose \
  --config examples/diagnosis.yaml \
  --clash-config examples/clash-config.yaml \
  --offline \
  --output reports/demo.html

Open reports/demo.html in any browser, or view the repository's sanitized demo report.

随后用浏览器打开 reports/demo.html，也可以直接查看仓库中的 脱敏 Demo 报告。

For source development, clone the repository and use python -m pip install -e .. 开发安装请克隆仓库后使用 python -m pip install -e .。

The tool does not edit Clash/OpenClash configuration, restart services, change DNS settings, or modify system proxy settings.

本工具不会修改 Clash/OpenClash 配置、重启服务、更改 DNS 或修改系统代理设置。

Privacy and data flow / 隐私与数据流

Clash/OpenClash rule parsing and report generation run locally. Configuration files and report contents are not uploaded, and NetRoute-Diagnose does not collect users' network configurations or provide a telemetry service.

Clash/OpenClash 规则解析和报告生成在本地执行。配置文件及报告内容不会上传， NetRoute-Diagnose 不收集用户网络配置，也不提供遥测服务。

Online checks are optional and are skipped with --offline:

• DNS checks send configured domain names to the system or explicitly configured DNS resolver.
• Egress IP checks make an HTTP(S) request to the configured public-IP service; the default endpoint is api.ipify.org, which necessarily sees the request's source IP and normal connection metadata.
• These requests are used only to produce the diagnostic result. The tool does not transmit configuration files or report contents. Results are written only to the local output files selected by the user.

在线检查是可选的，使用 --offline 时会跳过：

• DNS 检测会把配置中的域名发送给系统 DNS 或用户明确指定的 DNS 解析器。
• 出口 IP 检测会向配置的公网 IP 服务发起 HTTP(S) 请求；默认端点为 api.ipify.org，该服务必然能够看到请求源 IP 和常规连接元数据。
• 这些请求仅用于生成诊断结果。工具不会传输配置文件或报告内容，结果只写入用户 指定的本地输出文件。

Documentation: 中文 · English · Changelog · License: MIT