# China Network Diagnostics

> 面向中国大陆家庭、办公和小型局域网的本地网络诊断与低风险优化。当用户说网速慢、DNS 慢、网页打不开、只有某个网站异常、游戏延迟高、丢包、Wi-Fi 卡、后台占带宽、代理/VPN 相关问题、投屏或局域网设备发现失败，需要先基线、只读优先、按最小路径排查、修改前征得同意并给出回滚时使用。

- Skill: `minervaowl7/china-network-diagnostics` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add minervaowl7/china-network-diagnostics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/minervaowl7/china-network-diagnostics/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Minervaowl7 (https://skillmd.com/u/minervaowl7)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/minervaowl7/china-network-diagnostics

---


# 中国大陆网络诊断与优化

证据优先、国内优先、先诊断后修改。默认 **standard** 模式，只走症状对应的最小路径。

## 不可违反的约束

- **只读优先**：接口/路由/DNS/代理状态、Wi-Fi 与邻居 AP、连接与计数器、`ping`/`tracert`、DNS 查询、测速都可直接执行。
- **任何写操作先确认**：改 DNS/MTU/路由/代理、禁用网卡或服务、`netsh winsock reset`、网络重置、删除网络配置，都必须先展示影响、保存原值、给出精确回滚命令，并逐项取得用户同意。未确认时只给方案，不执行。
- **不安装软件**：不自动 `winget`/`choco`/`msiexec`。需要安装（例如 Ookla CLI）时先说明理由并取得确认；**不得为了测速擅自安装**。
- **不自动提权**、不使用 `sudo`、不终止进程、不关闭安全软件。
- **不修改**企业代理、PAC、VPN、证书、MDM、组策略或公司网络位置；发现即暂停并交回管理员。
- 一次只改一个变量，优先可逆操作。

## 上下文卫生（唯一 invariant）

诊断代理、连接配置和邻居 AP 会产生大量原始文本（订阅与配置正文、节点清单、IP、MAC、SSID/BSSID、路由明细、进程名）。这类文本一旦进入会话历史，可能污染**整个请求体**并触发服务商内容审核，导致该会话后续请求全部被拒，且重试、换模型、重发都无法恢复。

因此：

1. **原始输出一律写入 `work/<run-id>/<invocation-id>/raw/`；每次脚本执行新建一个 `invocation-NNN-<时间戳>-<随机数>` 目录，旧证据只增不改。stdout 只允许出现 JSON／计数／比例／分位数／布尔值／固定枚举／分类结果。**
2. **默认禁止把 `work/**/raw/*` 读入模型上下文**；只有用户明确要求深挖某一项异常时，才按字段提取（`Select-String`/`Group-Object`）取聚合值，不整文件读入、不整段回显。
3. 被测域名与跨境目标编号化（`D1…`/`T1…`/`C1…`），编号与真实名称的映射只写落盘文件。
4. 用户开始粘贴订阅链接、节点清单或 `ipconfig /all` 原文时先中断，请其改为给文件路径或聚合数字。

`scripts/` 下的脚本按此契约实现：raw 自动落盘、stdout 只吐聚合 JSON，并在输出前做泄漏自检。机制、敏感字段清单与拦截后的恢复策略见 [references/context-hygiene.md](references/context-hygiene.md)。

## 症状路由

**先用用户原话路由，不要凭症状名字猜：**

```powershell
pwsh -NoProfile -File scripts/route.ps1 -Prompt "<用户原话>" -Json
```

返回 `plan`（按序执行的最小探针）、`conditional_escalation`（触发条件满足才加）、`forbidden_by_default`（本轮不要跑）、`budget`。按 `plan` 顺序执行，**任一步的判定已能解释症状就停止**。

匹配不到任何症状词时返回 `symptom=no_match`、`confidence=low`、`mode=none`、`plan=[]`：**「未知」不等于 `full`**。此时不要擅自展开巡检或 quick 快扫，先问一个收敛问题，或从 `suggested_symptoms` 里选一个症状；最多允许执行一次低成本的 `preflight`。

| 症状 | 最小路径（standard） | 允许的升级条件 |
|---|---|---|
| `dns` | preflight → dns-benchmark | A 通而 AAAA 失败 → IPv6；启用 DoH/PAC → 代理只读检查；解析正常但 HTTPS 失败 → TLS |
| `wifi` | preflight → 网关 ICMP → 国内公网 ICMP → wifi-summary → 吞吐 | 网关干净、公网差 → 运营商路径；速率正常但吞吐低 → 后台连接；大包卡小包通 → PMTU |
| `throughput` | preflight → baseline → 吞吐 → 后台连接 | 有线/无线差异 → wifi-summary；TCP 停滞但 ICMP 正常 → PMTU |
| `latency-loss` | preflight → 网关 ICMP → 国内公网 ICMP → traceroute | 抖动/丢包集中在出口 → PMTU/后台连接 |
| `single-site` | preflight → dns-benchmark → TCP 443 | TLS 全程无 ServerHello → TLS 本机过滤排查；A/AAAA 表现不同 → IPv6 A/B；再不行才看路径 |
| `tls` | preflight → TCP 443 → TLS 握手探针 → 本机过滤排查 → IPv6 | 单站点特征 → single-site；代理存在 → 代理只读检查 |
| `proxy` | preflight → 代理只读检查 → TCP 443 | 单站点异常 → single-site；解析异常 → dns-benchmark |
| `mdns` | preflight → mDNS 服务检查 → 网关 ICMP | 无线侧可疑 → wifi-summary |

**`full` 只在**用户明确要求完整体检、多类症状同时存在、或最小路径无法解释证据时执行。默认不是 full；**路由匹配不到症状（`no_match`）同样不是 full**，见上。

分流依据、判定阈值与证据等级见 [references/decision-matrix.md](references/decision-matrix.md)。

## 模式

| 模式 | 目标 | 用法 |
|---|---|---|
| `quick` | 几分钟内定位故障大类 | 只跑最低成本探针；用于用户已给出症状、但想先要一个快速判断 |
| `standard`（默认） | 按症状路由、逐级升级 | 绝大多数排查 |
| `full` | 完整体检 | 仅上述三种情形 |
| `none` | 不执行 | 路由返回 `no_match` 时的默认：`plan` 为空，先问一个收敛问题，最多做一次 `preflight` |

## 执行契约

每条命令记录四列：命令 | 目的 | 实际结果（仅聚合指标） | 解释/下一步。命令失败记录错误类别，不用“看起来正常”代替结果。国内测试默认不经过 VPN/代理；需要保留时分列“直连”和“转发通道”两组结果并编号。

**不要产生伪精确结论**：

- 重复 `Resolve-DnsName` 不等于“系统 DNS 热缓存”——Windows DNS Client 缓存与上游递归缓存是两层，分别测量。
- `Get-NetTCPConnection` 能做连接/进程关联，但**推不出 per-process Mbps**；没有 ETW/性能计数证据就只写“连接数高/疑似相关”。
- TLS/本机过滤只能给证据等级（`confirmed`/`strong-suspect`/`weak-suspect`/`excluded`/`unknown`），不能凭驱动名、证书或目录存在就定元凶。
- 改善判定结合测量噪声、前后样本量、多指标一致性；不能确认时写“未证实改善”，不要用固定百分比阈值。

## 修改确认流程

1. 给出瓶颈归类与候选修复：预期收益、影响范围、是否需要管理员、预计中断、保存的原值、精确回滚命令、验证指标。
2. 用户逐项确认后执行，一次一个变量。
3. 用与基线完全相同的矩阵复测（同设备/位置/频段、同测试服务器、同 DNS 域名、同 ICMP 目标，前后各至少 3 轮），沿用同一编号与聚合口径。

## 最小报告要求

1. **环境与范围**：地区/运营商/接入方式/设备/时间窗/通道类别（直连｜转发通道｜不明），隐私脱敏说明。
2. **基线表**：命令、目的、结果、样本数、限制。
3. **诊断证据**：每项标证据等级，不只写“已证实/未发现”。
4. **瓶颈结论**：按影响与置信度排序，区分本地、国内路径、跨境/单站点（用编号引用）。
5. **已执行修改**：仅列已批准动作及原值/新值/回滚/验证结果；未批准的列为“建议，不执行”。
6. **前后对比** 与 **后续建议**（含停止条件），末尾附**原始输出落盘清单**（只列路径与用途）。

字段模板见 [references/report-template.md](references/report-template.md)。

## scripts 索引

全部只读、不自动提权、不安装、不改配置。`-OutputDir` 默认 `./work`。

**run-id 不再按时间猜测复用**：首次执行自动新建并在 stdout 返回 `run_id`，之后由 agent 显式 `-RunId` 传回。时间无法区分「同一次排查的下一步」和「另一个 agent／另一个会话／另一件不相干的事」，猜错就会把两次的证据混进同一个目录。不传 `-RunId` 就新建一个 run。每次执行都在该 run 下新建 `invocation-NNN-<时间戳>-<随机数>`，同名文件不覆盖旧证据，前测／后测可以并存比对。

**stdout 只有一个出口**：成功走 `Emit-SafeJson`，失败走 `Emit-SafeError`。两者都先过结构性白名单（只允许数字、布尔、null、固定枚举/代码、安全编号与明确允许的固定说明文本；拒绝盘符路径、UNC、URL、`@`、地址字面量、超过 240 字符的自由文本、非标量叶子），再过敏感信息黑名单。失败时完整异常（含堆栈与调用位置）写入 `raw/error-<时间戳>.txt`，stdout 只留 `{ok:false, tool, error:{code, category, message}}`——`$_.Exception.Message` 永远不会出现在 stdout。

| 脚本 | 用途 |
|---|---|
| `scripts/route.ps1` | 症状路由：`-Prompt`/`-Symptom` + `-Mode quick\|standard\|full` → 最小探针计划 |
| `scripts/preflight.ps1` | 一次性环境快照：OS、提权、接口、默认路由、DNS 形态、代理形态、工具能力 |
| `scripts/baseline.ps1` | 网关 + 国内公网 ICMP 与本地化判定；可选测速（已安装才用）/HTTP 回退 |
| `scripts/ping-summary.ps1` | 单目标 ICMP 聚合与判定 |
| `scripts/dns-benchmark.ps1` | 系统解析器 vs 国内公共解析器，客户端缓存层与上游递归层分开测 |
| `scripts/pmtu-test.ps1` | DF 二分探测 IPv4 路径 MTU |
| `scripts/ipv6-diagnose.ps1` | IPv6 readiness 分类器（按需） |
| `scripts/wifi-summary.ps1` | 信号/频段/信道/速率/邻居拥塞聚合 |
| `scripts/trace-summary.ps1` | TTL 逐跳 ICMP 路径聚合：跳数、响应跳数、起始恶化跳、是否可达、分类；跳地址只落盘 |
| `scripts/tcp443-summary.ps1` | ICMP 被过滤时的 TCP 443 可达性：是否可达、连接耗时中位数、固定分类；真实目标只落盘（编号化） |
| `scripts/proxy-summary.ps1` | 代理/PAC/VPN 形态只读聚合：只有 5 个布尔或计数，代理地址、PAC URL、客户端名、节点、端口一律不打印 |
| `scripts/connection-summary.ps1` | 连接计数与 TCP 状态分布，按匿名化进程编号（P1…Pn）分组；真实进程名与 PID 只落盘 |

## references 索引

| 文件 | 内容 |
|---|---|
| [context-hygiene.md](references/context-hygiene.md) | 污染机制、敏感字段、落盘规范、触发拦截后的恢复 |
| [decision-matrix.md](references/decision-matrix.md) | 症状→最小探针→判定→升级矩阵、证据等级、改善判定 |
| [windows-command-playbook.md](references/windows-command-playbook.md) | Windows 只读命令、低风险动作与回滚、采样与统计 |
| [tls-filtering.md](references/tls-filtering.md) | 本机 TLS 过滤/中间人组件排查（“TCP 通、明文通、TLS 必挂”） |
| [ipv6.md](references/ipv6.md) | IPv6 分类器语义与按需 A/B 流程 |
| [wifi.md](references/wifi.md) | 2.4/5/6 GHz、Wi-Fi 6E/7、MLO、160/320 MHz 的按需判断 |
| [china-domestic-network.md](references/china-domestic-network.md) | 国内 DNS 候选、目标选择、运营商与测速约束 |
| [report-template.md](references/report-template.md) | 报告字段模板与脱敏示例 |

自检：`pwsh -NoProfile -File tests/run-tests.ps1`；路由与 fixture 校验：`pwsh -NoProfile -File evals/run-evals.ps1`。