命令行与 AI 用法
桌面版适合手动排查一次。要接进脚本、CI，或者交给 AI 助手自己走完诊断，用命令行 —— 退出码和 --json 都是接口的一部分，不用解析文本。
命令行
$ portbug nodes $ portbug quick --to sh-01 # 常见端口体检 + 基线 $ portbug port "8080;3389" --to sh-01 # 端口深测，分号分隔，自动带对照端口 $ portbug port "3389" --udp --to sh-01 # 测 UDP $ portbug probe "22,80,443" --to sh-01 # 只看通不通，不跑流量 $ portbug proto --to sh-01 # 协议 × 端口：上行按端口、按协议还是按匹配限速 $ portbug matrix --ports 443,8080 --nodes sh-01
退出码是接口
CI 和脚本据此判断，不用去 grep 输出：
| 码 | 含义 |
|---|---|
| 0 | 达标 |
| 1 | 未达阈值 / 判定异常（被限速、降级） |
| 2 | 端口不通 |
| 3 | 节点不可达 |
| 4 | 配额耗尽 |
| 5 | 用法错误 |
$ portbug port "3389" --udp --to sh-01 --min-mbps 50 $ echo $? 1 # 低于阈值，CI 直接失败
结构化输出
--json 输出 portbug/v1：字段只增不改，含每 100 ms 一个的采样序列，可以自己重算判定。--publish 则把它变成一个带编号和方法学、可打印 A4 的报告页。
给 AI 助手用
把 skill 包给 Claude Code、Cursor 之类的助手，它就能自己按排障决策树走完诊断，而不是每一步都等你指路。
下载 skill 包
一个
SKILL.md，放进助手的 skills 目录即可。
它装进去的不是「能调哪些命令」——那看 portbug help 就够了——而是方法论：
先建立基线，再谈端口
链路本身就慢的时候，不能把结论往端口级上引。
某端口慢 → 加测相邻端口
只有 8080 慢，和 8079/8081 一起慢，性质完全不同。
TCP 正常但业务仍卡 → 必须测 UDP
最常被跳过、也最常是真凶的一步。RDP 画面、游戏、音视频都走 UDP，只测 TCP 会得出「链路没问题」的错误结论。
出结论前检查对照组
对照端口也掉档，就不是端口级问题。没有对照组，就不下判定。
不替工具把话说满
标了「置信度 低」就照实说，建议加长时长或换时段重测 —— 虚报比漏报危害大得多。
还没有 MCP server。 目前 skill 是直接驱动命令行的，这样今天就能用。
portbug mcp（五个正交工具、异步返回 test_id）还在计划里，没发布 —— 这里不会假装它已经有了。
一条不会松动的限制
客户端只能测 portbug 自己的节点，不接受任意目标 IP。 一个能对任意地址打流量的工具就是压测/攻击工具，这条是从架构上堵死的，不是提示语。在 AI 场景下它还从合规问题升级成安全问题：一旦允许任意目标，一段恶意网页文本就能让别人的 agent 变成流量来源。
要测你自己的服务器，正确做法是在那台机器上部署一个节点，而不是绕过这条限制。