connectivity-triage

连接性诊断

在不更改网络配置的前提下，定位正在发生的连接故障。收集最小但有用的证据集，区分观察与推断，并在故障域已经足够清晰、可以采取下一步安全操作时停止。

何时使用此技能

当 macOS 终端出现以下正在发生的症状时，使用此工作流：

• API、网站或 MCP 服务超时或断开连接；
• DNS 查询失败或名称解析不一致；
• 丢包、延迟或交互式流量不稳定；
• 某个应用看起来离线，而其他流量正常；
• 不确定问题是出在本地、上游，还是服务端。

这是一个诊断工作流，不是修复工作流。在确定故障域期间，不要更改接口状态、DNS 设置、VPN/防火墙配置或远程服务状态。

快速决策流程

从症状出发，逐步走向区分度最高的最小检查：

symptom
  -> local link / LAN evidence
  -> DNS configuration and resolution
  -> destination reachability
  -> path quality
  -> application / service timing
  -> fault-domain assessment

当证据已经足够时，及早停止。不要机械地运行每一项探测。

1. 定义症状

记录受影响的应用或进程、目标主机名或 URL、故障开始的时间、故障是持续性的还是间歇性的，以及无关目标是否仍然可用。

如果症状是特定于某个应用的，请保留该应用所使用的确切主机名或 URL。测试一个无关的公共站点可以确认一般连接性，但无法证明受影响的服务是健康的。

2. 检查本地链路 / LAN 证据

在可用时，运行一次有界的 networkQuality 采样，以获得整体的响应性和吞吐量信号。如果 networkQuality 不可用，请继续；它是可选的。

如果已知本地网关或同一 LAN 内的目标可用，请将针对该本地目标的短时有界 ping 采样与针对远程目标的短时采样进行对比。不要凭空捏造网关地址。如果不知道任何本地目标，则将 LAN 这一环节视为未经验证并继续。

有用的模式：

ping -c 5 <known-local-target>
ping -c 5 <destination>

3. 将 DNS 配置与 DNS 行为区分开

检查系统解析器状态，尤其是在可能涉及 VPN、拆分 DNS 或作用域解析器时：

scutil --dns

然后用一次有界的 DNS 查询直接测试目标名称：

dig +time=2 +tries=1 <hostname>

将这些视为不同的证据。scutil --dns 显示解析器配置；dig 显示查询行为。查询成功并不能证明返回的端点可达。

4. 测试可达性和路径质量

当 ICMP 是有用的信号时，使用短时 ping 采样：

ping -c 5 <destination>

如果主机名可以解析，只有在这样做有助于区分 DNS 行为与路径故障时，才单独测试返回的地址。如果当前解析失败，只有在先前从可信的故障证据中观察到某个地址时，才使用该地址；否则，将地址级别的可达性视为未知。

当路径可见性有助于减少不确定性时，使用有界的数字 traceroute：

traceroute -n -q 1 -m 20 <destination>

某一跳静默或发生变化是一种观察结果，而不是该跳已损坏的证明。路由器可能会过滤或限速 traceroute 流量，同时正常转发应用流量。

5. 检查受影响应用的实时网络活动

当问题特定于某个进程时，使用有界的 nettop 捕获，而不是无限期地观察：

nettop -n -L 3 -p <process-name-or-pid>

用它来确认该进程是否正在建立连接、正在使用哪些端点，以及流量是否在流动。看不到活动可能意味着该应用从未尝试建立连接；这本身并不能说明原因。

6. 对应用路径进行计时

对于 HTTP(S)，当有安全的只读请求可用时，针对实际受影响的端点使用 curl 阶段计时。确认事件中提供的端点是一个完整的 http:// 或 https:// URL，保留其原始 scheme，并将该 URL 作为一个加引号的参数传入，而不是把任意事件文本插值进 shell 命令：

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  --connect-timeout 5 --max-time 15 '<affected-http-or-https-url>'

以对比的方式解读各阶段。较高的首字节时间可能包含服务器处理时间，因此它并不能证明网络延迟。

证据规则

将结论标注为以下之一：

• 已观察 — 由命令输出或用户提供的证据直接支持。
• 推断 — 在关联各项观察后得出的最可能解释。
• 未知 — 当前证据无法确立。

绝不要将一次探测视为根本原因的证明。尤其要注意：

• ping 失败可能反映的是 ICMP 过滤，而非服务中断；
• ping 成功并不能证明应用健康；
• traceroute 中无响应的跳点并不能证明这些路由器处存在丢包；
• DNS 解析成功并不能证明可达性；
• 较高的 HTTP 首字节时间可能主要由远程应用处理时间主导。

当观察结果相互冲突时，宁可给出 inconclusive，也不要给出自信的猜测。

故障域评估

只返回一个主要类别：

• local-link/LAN — 证据在本地网络边界处或之前就已劣化；
• DNS — 解析器配置或查询行为比路径证据更能解释该故障；
• upstream-path — 本地证据健康，且关联的路径证据在 LAN 之外劣化；
• remote-service/application — 传输/路径证据足够健康，而受影响的服务或进程行为仍然异常；
• inconclusive — 当前证据无法区分剩余的故障域。

使用定性置信度：low、medium 或 high。置信度反映的是证据质量和关联性，而非严重程度。

事件结果格式

症状

重述当前故障以及受影响的目标/应用。

观察结果

仅列出相关测量结果，包括重要的不可用或被阻断的证据。明确标注观察结果、推断和未知项。

故障域评估

报告类别、置信度，以及一段简短的、与证据关联的解释。

下一个最安全的检查

给出一个最能降低不确定性的诊断操作。除非用户另行要求修复，否则不要直接跳到配置更改。

安全与边界

在诊断期间，不要：

• 更改接口状态或重启网络服务；
• 编辑解析器配置或刷新 DNS 缓存；
• 修改防火墙或 VPN 设置；
• 安装软件包或要求使用 Homebrew；
• 向远程服务发送会改变状态的请求；
• 在有界采样即可回答问题时，运行无限期或高强度的探测。

不完整的探测、被阻断的 ICMP、VPN、强制门户、作用域 DNS、代理、端点控制措施以及瞬时故障，都是证据局限，而不是诊断结论。

详细解读

阅读 references/details.md 以了解逐命令解读、歧义处理、间歇性故障指导以及完整示例。

相关技能

• incident-runbook-templates - 将反复出现的连接事件转化为可重复的响应流程
• on-call-handoff-patterns - 在响应人员交接过程中保留当前连接证据
• postmortem-writing - 在事件后记录已确认的原因和纠正措施