移动网络把脉师

定位

融合两个能力，统一入口、统一报告：

1. WiFi 把脉师的七维体检（本 skill 主体）——像中医把脉，客观呈现网络健康状况；
2. 宽带网络质差自检工具的质差定位（scripts/pulse_* 增量模块）——像分段拍片，把问题定位到接入/出口/跨网/网关具体环节。

> 本 skill 是原「WiFi 把脉师」的升级版：功能从"只看 WiFi"扩展到"有线 / WiFi / 蜂窝无线数据都看"，
> 并融合了宽带质差定位与路由器深度分析，因此改名为「移动网络把脉师」。

只读不写：不改任何网络配置；读不到的字段如实写"读不到"，绝不编造。

新增能力（在原七维体检之上）

何时使用

用户提到以下任意情形时使用本 skill：

• 网络卡、网速慢、上网卡顿、视频卡、延迟高、WiFi 信号差、连不上网
• 帮我把把脉、测测网速、网络体检、看看网络正不正常

用户问"这个技能怎么用 / 怎么调用"时：只需给出触发词清单 + 常用配方 + 参数速查，不要真的去跑采集。
教程文档见 references/usage_guide.md。

核心原则（必须遵守）

1. 中立客观：结果可能是健康、有点小毛病、问题明显，三者皆可，不得预设立场。
2. 数据说话：所有结论必须基于本次实测数据，不得凭经验臆断。
3. 说人话：杜绝术语（不说 RSSI、SNR、TCP 三次握手），让不懂技术的人一眼看懂。
4. 分维度独立评级：七大维度各自分析、各自评级，最后再汇总，绝不混在一起谈。
5. 硬性提示必须输出：命中下方"硬性提示"规则时，对应建议必须出现在报告中。

执行流程

第 1 步：一把跑完（默认路径，含宽带质差定位）

python scripts/run_pulse.py --out <输出目录>

一条命令完成全流程：深检采集 → 增量采集 → 规则引擎 → 融合报告，无需 GUI、无需 exe。
全程约 3 分钟；--out 目录内落盘：融合报告 移动网络体检报告.html、深检数据 report.json、数据包 zip、manifest.json。

调用方式：用户直接说触发词即可（如"帮我把把脉""测试一下网络""测测网速"）；也可用 @skill:mobile-pulse-doctor 显式引用。
用户说"别压测""快一点"等要求时，自动映射成 --skip-session-test / --quick。

数据来源：默认由内置采集脚本 scripts/probe_deep.py 现场采集（纯 Python 标准库 + 本机只读命令，产出 report.json）。
如果本机另装有增强引擎（本地完整版才带，市场版不含），run_pulse.py 会优先用它，报告内容更完整；
两者产出的数据结构完全一致，下游规则与报告脚本一行不用改。manifest.json 里的 data_source 字段标明本次实际用了哪一套。
所有子进程强制隐藏窗口，不弹黑框；采集需要 Windows（读 netsh 等原生命令）。

第 2 步：报告已生成，直接看

runner 已直接产出融合报告，无需再手动渲染。报告分三部分，先结论、后细节：

第一部分 · 整体结论（说人话优先）
  1. 🩺 一句话结论      你怎么上网的（连接方式 + SSID + 频段 + 代际 + 信号）
                        → 实际体感（能跑多快、稳不稳）→ 总体判断 → 最需留意哪一项
                        全部用大白话，不堆参数（参数留给详细报告）
  2. 📊 综合健康度 + 七维状态矩阵（评分环 + 每维色条，一眼看完）
  3. 📌 硬性提示        命中硬性规则时必出
  4. 🎯 需要处理的点    只列 ⚠️/❌，每条一句原因 + 一句怎么做
  5. ✅ 没问题的方面    正常项直接列出，不逐条展开
  6. 🔎 路由器深度分析邀请  未授权 → 引导客户提供账密换更深分析；已授权 → 列出已读到的真实字段与可继续调优项

第二部分 · 详细报告（七维图文）
  维度一 ~ 维度七：每维的关键数字、图表、人话解读**直接呈现**；
  只有「🔬 专业数据详情」（测速口径、深检原始数据）收在折叠区，点击展开。

第三部分 · 宽带质差整治（装维视角）
  九节：接入与出口 / 网卡物理层 / 丢包时延分运营商 / MTU 会话速率 / DNS 与无线环境 /
  本机资源 / 路由器只读 / 站点专项 / 采集口径。每节的基础数据表**直接呈现**，
  只有「🔬 深检原始明细（专业数据）」收在折叠区，点击展开。

呈现铁律：每一项都必须先给基础内容（人话 + 关键数字 + 图表），
较专业的数据明细才放进标注「🔬」的折叠区——不允许只露一个标题、内容全靠点开。

文字要求：能一句说清就不写两句。人话解读由脚本按阈值规则生成，长度固定在一两句；
不要为了凑篇幅把总览里的内容在详情里再抄一遍。

备选路径：轻量七维体检（不跑深检，任何平台，约 70 秒）

只做七维体检、不需要宽带质差定位时（如非 Windows 环境，或用户只要快速看看），走原版轻量链路：

python scripts/wifi_diagnose.py --output wifi_report.json
python scripts/render_report.py wifi_report.json -o 网络体检报告.html

采集脚本会自行完成：连接方式判定、WiFi 信号读取、空口扫描、网速与延迟、稳定性采样、路由器负载探测、会话数压测，并输出结构化 JSON。

会话压测前必须提示用户：脚本会打印"即将占用网络"的说明。若用户在对话中已表示不希望压测，直接加 --skip-session-test。

JSON 关键字段：

dimensions.1_connection        连接方式（对外只呈现 有线连接 / WiFi 连接 / 蜂窝无线数据连接 三种）
dimensions.2_wifi_signal       WiFi 详情；未连 WiFi 时为 {"not_applicable": ...}
dimensions.3_speed             下载/上传/延迟/抖动；skipped=true 表示已跳过
dimensions.4_airspace          周边 BSSID 数、同信道数、邻道干扰数、my_ap_station_count
dimensions.5_router_load       网关、下挂终端数、型号提示、网关可达性
dimensions.6_sessions          压测各档成功率、critical_concurrency、estimated_remaining_sessions
dimensions.7_stability         多次延迟采样统计 + TCP 丢包率 + ICMP 结果
auto_grade                     脚本给出的参考评级（按维度逐项）
hard_hints                     已命中的硬性提示，必须原样体现在报告中

补充字段：
- 2_wifi_signal.ssid_raw / ssid_source：SSID 原始值与还原来源，ssid 为已修复的可用值。
- 4_airspace.my_ap_station_count：路由器自己广播的、挂在当前这个热点下的终端数（比 ARP 更准）。
- 5_router_load.attached_device_count_estimate：综合 ARP 与路由器广播值后的下挂终端数估计，评级以此为准。
- 6_sessions.reachable_targets / unreachable_targets：压测实际使用的目标与已排除的不可达目标。
- 7_stability.unreachable_targets：被排除的目标；tcp_loss_rate 已剔除它们，可直接用于评级。

auto_grade 与 hard_hints 是脚本给出的参考基线：报告必须覆盖它们，但措辞由模型撰写得更自然，且需结合上下文（例如本机文件描述符上限导致压测被截断时要额外说明）。

第 2.5 步（融合）：质差分段与双视角

以下模块由 run_pulse.py 在内部自动编排（默认路径无需手动运行）；单独调试时可手动执行：

python scripts/pulse_rules.py   # 规则引擎：融合七维 + 质差数据，输出客户/装维两版建议
python scripts/pulse_ext.py     # 增量采集：本机健康 / 无线环境 / 路由器只读 / 站点排查 / 挂机

质差分段数据来源（内置深检采集层 probe_deep.py）：上游接入方式（WAN 侧）与公网出口、网卡物理状态、网关/公网丢包抖动、路径 MTU、跨网对比/TCP/DNS、整线会话数、重点站点 tracert 定位。分段结论与七维体检合并进同一份报告，不重复展开。

双视角规则：
- 客户视角（默认）：通俗优先，专业分析放后台；每条结论必须给"为什么 + 怎么做 + 成本"，让普通技术水平的人能听懂、能照做。
- 装维视角：详尽，含阈值、原始证据、技术依据，便于装维师傅远程定位。

第 3 步：对话里给精简版

报告文件生成后，对话回复只给三样东西，细节引导用户看报告：

1. 一句话结论（含连接基本情况）
2. 七维评级一览（一行一项，不展开）
3. 需要处理的点（逐条给"原因 + 怎么做"）

若有个性化补充（用户提到带宽套餐、当前在打游戏/开会等），写在对话里，不要塞进报告。

第 4 步：主动邀请「路由器深度分析」（报告里已有入口，对话里再问一次）

报告「第一部分」末尾会固定出现一张 🔎 路由器深度分析邀请卡（客户未授权时）：
说明可以提供路由器账密换一份更深的分析与调优。对话里必须主动把这句问出口，不要等用户
自己发现：

> 报告里涉及路由器的几项（型号、CPU、内存、NAT 会话数、下挂终端、双频与信道配置）
> 现在只能靠外围推断。如果你愿意提供路由器的管理地址 + 管理员账号 + 密码，
> 我可以登录进去只读拉取这些真实数据，把结论做得更准，并给出调优建议；
> 你同意的话，还能顺手帮你调（拆双频、换信道、限速、查有没有陌生设备蹭网）。
> 不方便提供也没关系，现在这份报告已经够用。

用户同意并提供账密后，补做深度分析（几秒完成，不必重跑整轮体检）：

python scripts/run_pulse.py --reuse-dir <上次输出目录> \
    --router-host 192.168.1.1 --router-user admin --router-pass <客户提供的密码>

要点（必须遵守）：
1. 先问、后做：必须用户明确同意才登录，不得擅自尝试猜测账密。
2. 只读优先：默认只读状态页；任何改动配置的动作（拆双频、改信道等）先说明再征得二次确认。
3. 密码不落盘：密码只在进程内存中使用，不写入报告 / manifest / 日志；提醒用户慎在公开场合粘贴。
4. 不硬猜：多数 2022 年后的固件对密码做前端加密，脚本可能登录不成功；失败就照实说，
改为「由装维师傅登录后台按同一口径读取」或引导用户自己按菜单操作，不要编造读到的值。
5. 管理地址不清楚时留空 --router-host，脚本会自动取本机默认网关。

连接方式分支

连接方式口径（硬约束）：报告里「连接方式」这一项只允许三种取值——
有线连接 / WiFi 连接 / 蜂窝无线数据连接，不得出现其它表述。
深检采集给的 ip_type（如「经网关 NAT 上网…」）描述的是 WAN 侧上游接入，不是本机连接方式，
只能在第三部分按「上游接入方式（WAN 侧）」单独列出，不能拿来当连接方式。

判定依据（本机侧，见 pulse_report.classify_conn）：
网卡名称/描述/介质命中蜂窝特征（WWAN、4G/5G 模块、USB 上网卡、Mobile Broadband 等）⇒ 蜂窝；
介质为无线、或有 SSID / 无线电类型 ⇒ WiFi；其余 ⇒ 有线。

七大维度

每个维度在详细报告里都是同样的小结构：一张图 + 几个关键数字 + 一句话解读 + 评级（✅正常 / ⚠️注意 / ❌异常 / 不适用）。解读只写一到两句，不重复图表里已经看得见的信息。

硬性提示（命中必须输出）

1. 蜂窝无线数据连接 → 「当前未连 WiFi，测的是手机信号，建议连 WiFi 再测」
2. WiFi 代际 < WiFi 6 → 「路由器代际偏老，多设备并发易卡，建议换支持 WiFi 6 的路由器」
3. 频段非 5G（即 2.4G） → 「当前连 2.4G，网速低干扰大，建议优先连 5G 频段」
4. 信号 < -75 dBm → 「信号弱，离路由器远或隔墙，建议调整路由器位置到居中开阔处，或增加一台路由器/Mesh 节点」
5. WiFi 代际 < WiFi6（网卡或路由器任一） → 必须建议更换 WiFi6 及以上路由器，并从 scripts/pulse_rules.py 内置产品库按预算三档各推 1 款型号；同时可推荐移动智能组网（FTTR/Mesh），建议联系 10086 或装维师傅
6. 频段与双频合一判断（判据已修正，别再靠"只扫到一个频段"直接报双频合一）：
   - 当前 SSID 带频段后缀（如 7楼B-5G、Home_2.4G）⇒ 路由器是分频命名，
   不存在双频合一问题，报告写「未发现双频合一」；此时"只扫到一个频段"
   多半只是网卡驱动缓存没扫全，不算问题。
   - 当前 SSID 不带任何频段后缀，且只扫到一个频段 ⇒ 才提示「疑似双频合一」。
   - 同名 SSID 同时出现在 2.4G 与 5G ⇒ 确认开了双频合一，报告说明它属常见配置
   （不算故障），并给出"有老式智能家居掉线时再拆开"的建议。
   - 需要拆分频段时，征得同意并拿到路由器权限后可代做，名称密码按用户要求填。
7. 电脑资源吃紧（CPU>85% / 内存>88% / 磁盘>90%） → 必须先指出"卡顿主因可能在电脑本身"，给出可自行排查的方向（关掉占用高的软件、加内存等），避免用户白折腾网络
8. 路由器深度分析邀请 → 报告第一部分末尾必须固定输出邀请卡（未授权时说明可提供账密换更深分析；已授权时显示"深度分析已开启"与可继续调优项）；对话里必须再主动问一次，见「第 4 步」

输出结构（两部分）

第一部分 · 整体结论
  1. 🩺 一句话结论        必须含整体连接基本情况：连接方式 + SSID + 频段 + 代际 + 信号/速率
  2. 📊 综合健康度 + 七维状态矩阵（评分环 + 每维色条）
  3. 📌 硬性提示          命中硬性规则时必出
  4. 🎯 需要处理的点      只列 ⚠️/❌，每条：一句原因 + 一句怎么做
  5. ✅ 没问题的方面      正常项一行带过，不逐条展开

第二部分 · 详细报告
  维度一 ~ 维度七，每个维度独立成块：图 + 关键数字 + 一句话解读 + 评级

文字精简原则：结论区不重复详情区内容，详情区不重复图表内容；能一句说清就不写两句。

详细阈值与措辞见 references/diagnosis_rules.md，报告骨架见 references/report_template.md。

诊断规则（人话版）

判定阈值以 references/diagnosis_rules.md 为准。

会话数维度说明（重要）

不依赖静态读取，改为主动模拟建立会话压测：

• 用 Python socket 并发向多个公网目标（1.1.1.1:80、8.8.8.8:53、223.5.5.5:443 等）发起 TCP 连接
• 逐步增加并发，记录成功与失败的临界点，得出真实剩余可用会话数
• 安全上限最多模拟 2000 条，仅做 TCP 握手后立即释放，不传输业务数据
• 若本机可选装有路由器管理接口（hg-router / pyasuswrt），优先读真实会话表并与压测结果交叉验证
• 预警红线：剩余 < 200 → ❌ 忙时可能超限；200~500 → ⚠️ 偏紧；> 500 → ✅ 宽裕
• 提供 --skip-session-test 参数；压测前脚本会提示用户可能短暂占用网络

技术约束

• Python 标准库为主；测速优先 speedtest-cli（若已安装），否则用标准库 HTTP 端点兜底
• 跨平台：Windows / macOS / Linux
• 采集输出 JSON；报告由 render_report.py 渲染成单文件 HTML，图表为内联 SVG（无外部依赖、离线可看）
• 测速可选，加 --skip-speedtest 参数

环境适配与降级

• Windows：用 netsh wlan show interfaces 读信号（百分比按 dBm = 百分比/2 - 100 折算）、netsh wlan show networks mode=bssid 扫描空口，中英文系统输出均已兼容。
• netsh 会把中文/emoji SSID 双重编码（如 7楼A-5G 输出成 7妤糀-5G）。脚本会自动还原，并用「配置文件」字段交叉校验，ssid_source 会标明来源（ssid-repaired / profile-name / ssid-raw）。
• netsh 空口扫描返回的是缓存的扫描结果，有时只能看到自己一个 SSID。若 nearby_bssid_count 明显偏小，报告中应说明"本次扫描结果可能不完整"。
• macOS：优先 airport -I，不可用时回退 system_profiler SPAirPortDataType（macOS 14+ 已移除 airport）。
• Linux：优先 iw dev <if> link / iw scan，回退 nmcli。
• 移动网络：macOS 看 pdp_ip*，Linux 看 wwan*/rmnet*，Windows 看 netsh mbn。
• 任何取不到的字段在 JSON 中为 null，报告中标注「无法读取」，不得编造数据。
• 路由器 CPU / 内存 / 型号等需管理权限，默认尽力探测（ARP 邻居表 + 路由器广播的下挂终端数 + 网关首页），取不到时如实说明。

可达性预筛（避免误判）

• 延迟 / 丢包只统计至少成功过一次的目标；完全不可达的目标（如境外的 1.1.1.1、8.8.8.8）会记入 unreachable_targets，不计入丢包率——否则会给出"丢包 50%"这类误报。
• 会话压测前会先逐个试连，只对可达目标加压，并在 reachable_targets / unreachable_targets 中列明。
• 报告中若出现"某个目标不可达"，应表述为"该地址在当前网络下不可达（多为网络策略限制）"，不要说成丢包或网络故障。

安全与权限声明

本 skill 只做本机网络状况测量，不修改任何系统配置、不写入任何远端数据。为便于上架审核，权限与行为逐项列明：

边界自证（逐条对应常见审核关注点）：

• 源码完全可读：全部为可直接阅读的 Python 源码，逐行可审阅，未做任何加密或变形处理；
• 不加载外部代码：运行期只执行本 skill 自带的源码，不引入、不拼接、不执行任何来路不明的代码片段；
• 只取整机资源使用率：CPU / 内存 / 磁盘三项占比，不读取其它进程的名称、命令行或内存内容；
• 不看本机标识：不读取系统盘符、用户名、主机名等与本机身份相关的信息（盘符由系统路径推导，不查配置）；
• 不采集个人数据：不碰账号、身份、文件内容、浏览记录等任何个人信息；
• 不出本机：全部数据留在本机；报告 HTML 为单文件，不含任何外链脚本与统计埋点；
• 不偷跑：会话压测前先在终端打印占用提示；不开机自启、不后台驻留、不注册系统服务；
• 不动系统：不改任何系统设置、不改网络配置、不装驱动、不提权。

压测安全上限：并发连接数硬上限 2000，逐档递增、单档超时即止；所有 socket 立即关闭并释放。用户可用 --skip-session-test 完全跳过；未跳过时脚本会在开始前打印占用提示。

资源

scripts/

• run_pulse.py — 无界面总入口（默认路径）：选数据源 + 增量采集 + 规则引擎 + 融合报告一把跑完
• probe_deep.py — 内置深检采集层（默认数据源）：纯标准库 + 本机只读命令，现场采集接入/出口/网卡/丢包时延/DNS/会话/物理层，产出与下游完全同构的 report.json
• pulse_rules.py — 规则引擎：融合七维 + 质差数据，输出客户/装维两版建议
• pulse_ext.py — 增量采集：本机健康 / 无线环境 / 路由器只读 / 站点排查 / 挂机
• pulse_report.py — 融合报告渲染：把七维与质差结果合成一份单文件 HTML
• wifi_diagnose.py — 轻量路径主采集入口，编排七大维度并输出 JSON
• render_report.py — 轻量路径：把 JSON 渲染成两部分结构的图表化 HTML 报告（内联 SVG）
• probe_net.py — 连接方式、WiFi 信号、空口环境、路由器负载
• probe_perf.py — 网速与延迟抖动、链路稳定性
• probe_session.py — 会话数并发压测
• lib_common.py — 公共工具（命令执行、编码兼容、键值解析、TCP 探测、网关识别）
• engine_bridge.py — 可选增强：本机若装有深检引擎则走它（仅本地完整版带，市场版不含此文件；缺失时自动回落到 probe_deep.py）
• engine/ — 同上，引擎本体目录（仅本地完整版保留）

references/

• diagnosis_rules.md — 各维度阈值、评级标准、硬性提示触发条件与措辞
• report_template.md — 两部分报告骨架 + 图表规范 + 精简文字要求
• usage_guide.md — 调用方式与指令速查（回答"怎么用"时引用）

assets/（仅本地保留，不随上架包分发）

• icon.png — 技能图标 512×512（「脉象 + WiFi」扁平风，透明背景）
• icon@2x.png — 技能图标 1024×1024（高清版，用于商店大图/宣传物料）
• icon-white.png — 技能图标 512×512 白金反色版（深色背景或浅色底图时使用）

> 为什么 assets/ 不在上架包里：平台发布通道只接收文本资产，图片/字体/压缩包等二进制会被
> 服务端以 400 不允许的文件类型 拒收，且 --dry-run 阶段检测不到，只有真发布才报错。
> 因此图标不进上架包，改由 SkillHub 网页控制台的 Skill 详情页单独上传。
> 本 skill 的运行不依赖 assets/ 下的任何文件，缺了不影响体检功能。
>
> 本 skill 上架包内全部是可读源码：默认数据源 probe_deep.py 与其余 probe_* / pulse_* /
> render_report.py 均为可直接逐行审阅的 Python 明文实现，没有任何加密、变形或不可读的封装。
> engine/ 目录与 engine_bridge.py 只保留在本地完整版中，不进上架包（pack_skill.py 会主动排除）；
> 市场版安装后 run_pulse.py 自动回落到内置采集层，七维体检、宽带质差分段、路由器深度分析全部照常可用。
>
> 打包时请用工作区的 pack_skill.py：它一次产出两个 zip——
> 完整包保留全部文件（含图标与本地引擎，用于留档 / 分发）；
> 上架包只留可读源码与文本资产（图标、引擎目录、桥接模块一律剔除）。
> 不要直接对技能目录执行 skillhub publish，否则会踩上面这些坑。