NetPulse 一键 VPS 网络体检，开源 + Agent 友好 JSON 输出 Vibe 项目

项目简介

NetPulse 是一款专为 AI Agent 设计的开源 VPS 网络体检工具，单条命令即可对一组 VPS 完成 IP 纯净度、原生 IP、DNS 泄露、11 项流媒体解锁、ChatGPT / Claude / Gemini API 可达性等全方位体检，并以 JSON 格式输出，可直接喂给 AI Agent 做进一步分析。开发者只需在本地笔记本执行一条命令，工具自动经 SSH 在远端机器上运行，结果回传并支持多机对比表输出，特别适合给 Claude / Codex / Cursor 等 AI Agent 当作"外包的运维网络诊断员"。

核心功能

• 一键批量体检：本地一条命令扫描多台 VPS，--host 参数重复即可添加多目标，自动生成多机对比表。
• IP 信息与纯净度检测：出口 IP、地理位置、ASN、ISP、机房 / 住宅 / 代理特征标记。
• 原生 IP 校验：通过 Team Cymru BGP ASN 注册地与 IP 属地对比，识别是否真正原生。
• DNS 泄露检测：检查 DNS 解析器的地理位置是否与出口 IP 一致，避免 DNS 泄漏暴露真实网络位置。
• 11 项流媒体解锁：覆盖 Netflix、Disney+、YouTube Premium、HBO Max、Hulu、Prime Video、TikTok、Spotify 等主流服务。
• AI API 可达性测试：直接探针 ChatGPT、Claude、Gemini 的 API 网关，401（无 key 但抵达网关）即可达，首页 403 反爬不算证据。
• 网络质量评估：IPv6 出口、Cloudflare / Google / Baidu 的 TCP 延迟、下载速度。
• JSON 标准化输出：固定 envelope 格式，stdout 纯净 JSON，方便 AI Agent 直接消费。
• Markdown 报告：--share 选项生成 Markdown 报告，方便群分享或工单提交。
• 细粒度退出码：0 全通过 / 1 部分失败 / 2 全部失败，方便 Agent 编排下一步决策。

技术实现

NetPulse 采用 Python 3 单文件实现，仅依赖 requests 库。本地运行时不依赖任何第三方网络服务，IP 数据直接调用 Team Cymru 的免费 BGP ASN 注册库（keyless），DNS-over-HTTPS 使用 Google Public DNS 与 Cloudflare 备用解析器。SSH 通过系统 ssh 二进制调用，支持 ~/.ssh/config 配置（含跳板机、自定义端口）。远端主机需预装 python3 + requests，BatchMode=yes 强制走密钥认证避免交互密码提示。JSON 输出采用固定 envelope 结构，包含 schema、tool、version、generated_at、results 数组，每条 result 含 status、error_code、checks（每项含 status、value、evidence、error、duration_ms），status 枚举为 ok / negative / unknown / error / skipped。延迟采样三次取中位数；测速响应不足 1MB 直接判 error；自创"风控分"等模糊指标一概拒绝，标 unknown 即 unknown。所有检测都在用户本机或自有 VPS 上运行，IP 数据不经过任何第三方网页服务，定位为"给 VPS 自己体检，不扫描、不追踪他人"。

快速上手

• 一键安装：bash <(curl -sL https://raw.githubusercontent.com/Genuifx/NetPulse/main/install.sh)
• 手动安装：git clone https://github.com/Genuifx/NetPulse.git && cd NetPulse && python3 netpulse.py
• 单台检查：python3 netpulse.py --host root@1.2.3.4
• 批量检查 + JSON：python3 netpulse.py --host root@vps-a --host root@vps-b --host root@vps-c --json | jq .
• 生成报告：python3 netpulse.py --host root@a --share -o report.md
• 跳过测速：--no-speed（按流量计费机器友好）
• 设置超时：--timeout SEC（默认 120 秒）

适用人群

• 自有 VPS 集群的运维 / DevOps 工程师。
• 使用 VPS 跑 AI Agent / 反向代理 / 流媒体的用户。
• 需要批量对比不同机房原生度的 VPS 选购者。
• 关注 AI API 跨区域可达性的开发者。
• 给 AI Agent 当网络诊断 tool call 的工程团队。