| name | network-path-diagnose |
| version | 1.0.0 |
| description | Diagnose network path quality from this host to a target using ping/mtr/curl. Investigate packet loss, high latency, jitter, and reachability failures; interpret hop results and suggest follow-up tests. Do not change network config. Also matches Chinese requests such as 网络丢包、延迟高、链路质量、ping 不通、网络抖动.
|
| author | aish |
| context | subagent |
| agent | troubleshoot |
| allowed-tools | ["bash","read_file","grep","glob"] |
| triggers | ["network-path-diagnose","path quality","packet loss","high latency","mtr","ping failed","network jitter","网络路径诊断","链路质量","网络丢包","延迟高","ping 不通","网络抖动"] |
| platforms | ["linux"] |
| distributions | ["deepin","debian","ubuntu","uos"] |
Network path diagnosis
Measure reachability and path quality (packet loss, latency, jitter) from this host to a user-specified target.
Out of scope: cloud VPC/security-group debugging, whole-host lag checks (diagnose_system_lag), DNS-only failures (dns-diagnose), changing routes or firewall rules.
Rules
- Need a target first: ask for IP/host/URL if missing; do not invent defaults.
- Read-only probes: ping/mtr/curl/ss are fine; do not change NICs, routes, or firewall.
- Stop when enough: stop once the symptom is explained; do not add unrelated probes.
- Missing tools: if
mtr is absent, fall back to ping + traceroute/tracepath and note that in Evidence.
- Uncontrollable peers: for public DNS and similar hosts you cannot log into, run forward tests only and state that reverse MTR is impossible.
Workflow
Confirm target & symptom → quick reachability → path quality (mtr) → TCP/port follow-up if needed → answer
1. Confirm inputs
| Input | Notes |
|---|
| Target | IP, hostname, host:port, or URL |
| Symptom | unreachable / slow / intermittent loss / bad at certain times |
| Port/protocol | record TCP port if the app uses one (e.g. 443/22) |
2. Quick reachability
getent ahosts <host> | head -5
ping -c 5 -W 2 <host>
curl -sS -o /dev/null -w '%{http_code} time=%{time_total}\n' --connect-timeout 5 <URL>
nc -zv -w 3 <host> <port> 2>&1
- Resolve fails → use or hand off to
dns-diagnose; continue only with a user-provided IP.
- ICMP all lost but TCP port works → ICMP likely filtered; switch to TCP path tests; do not call the path “dead”.
3. Path quality (prefer mtr)
command -v mtr
mtr -rwzc 50 <host>
traceroute -n <host> 2>/dev/null || tracepath -n <host>
ping -c 20 -W 2 <host>
