httpstat 结构化输出与 SLO 阈值诊断:单文件 curl 计时 CLI 的 Agent 友好化改造
httpstat 结构化输出与 SLO 阈值诊断:单文件 curl 计时 CLI 的 Agent 友好化改造
httpstat 是一个将 curl(1) 计时统计可视化的单文件 Python CLI,本文基于仓库内 AGENTS.md 项目规划,系统梳理其 2.0 时代的现代化改造路径:从补齐类型标注、严格布尔解析等代码卫生工作,到 Phase 1 引入 --format 结构化输出(JSON v1 schema)、--slo 阈值检查、NO_COLOR 与 --save 等 Agent 友好能力。读完本文,你将掌握这套结构化输出与 SLO 诊断机制的完整设计、源码实现原理、测试验证方式,以及面向 AI Agent 的诊断 Skill 层设计思路。
一、项目现状:单文件 CLI 与现代化改造
1.1 单文件、零依赖的技术形态
httpstat 的全部核心逻辑收敛在单个文件 httpstat.py 中(AGENTS.md 记载约 370 行,当前版本实际约 575 行),要求 Python >= 3.9,版本号为 2.0.0(见 httpstat.py 的 __version__)。它本质上是 curl 的薄封装:调用 curl 的 -w 写入格式收集各阶段时间戳,再渲染出 DNS、TCP、TLS、服务端处理、内容传输的分段耗时图。
打包完全由 pyproject.toml 驱动(setuptools 后端,requires = <a href="https://link.gitcode.com/i/6210df7d494bef818b3ecf21602ce03f" target="_blank">"setuptools>=61", "wheel"]),setup.py 已删除;构建与发布使用 uv build / uv publish(见 [Makefile 的 build/publish 目标)。pyproject.toml 还声明了命令行入口 httpstat = "httpstat:main",并支持 Python 3.9 ~ 3.13 全部版本。
1.2 已完成的现代化工作
AGENTS.md 记录了以下已经落地的改造,均可在源码中直接印证:
- 去除所有 Python 2 兼容代码:shebang 改为
#!/usr/bin/env python,并引入from __future__ import annotations(httpstat.py); - 全量 f-string 与新式语法:字符串插值、类型标注全面启用,包括
Env类的@overload声明(httpstat.py)与NoReturn标注(httpstat.py); - 严格布尔解析
parse_bool():替代原先'true' in value.lower()的宽松判断,只接受1/true/yes/on与0/false/no/off两组取值(httpstat.py); - 临时文件
try/finally统一清理:body/header 临时文件在finally块中按需删除,不再泄漏(httpstat.py); quit()重命名为_exit()并标注NoReturn,语义更清晰。
二、剩余技术债:改造的动机所在
AGENTS.md 把未解决的问题归为两类,这直接决定了 Phase 1 的方向:
A. 测试可靠性不足(高优先级)
- 当时仅有 shell 端到端测试(httpstat_test.sh),强依赖公网与第三方站点行为(脚本开头会检查
gstatic.com/generate_204与http2.akamai.com的可达性),CI/本地结果不稳定; - 缺少单元测试,核心逻辑——指标换算、区间计算、
parse_bool——没有稳定的回归保障。
B. Agent 适配能力不足(中高优先级)
- 当时的 JSON 输出(
HTTPSTAT_METRICS_ONLY)缺少 schema version、状态码语义、错误结构、上下文元数据; - 缺少「可机器判断」的 SLO/阈值能力(例如总耗时超阈值即非 0 退出);
- 输出模式较少,无法直接覆盖 Agent 常见流水线(JSONL、紧凑 JSON、纯错误对象)。
三、Phase 1 核心设计:--format 结构化输出与 JSON v1 schema
Phase 1(本轮实施)的目标是「结构化输出 + SLO」,AGENTS.md 给出了完整方案,源码与测试均已落地。
3.1 输出格式参数
新增 --format(-f)参数,可选值为 pretty | json | jsonl,默认 pretty 以兼容现有行为。参数解析由手写的 pop_arg() 完成(httpstat.py),它会从 sys.argv 列表中原地摘除 flag 及其值,再校验格式合法性(httpstat.py)。
旧环境变量 HTTPSTAT_METRICS_ONLY 保留兼容:当它为 true 且用户未显式指定 --format 时,等价于 --format json(httpstat.py)。两种输出模式的差异:
json:json.dumps(..., indent=2)多行美化输出;jsonl:紧凑单行 JSON,便于进入日志流水线逐行消费(见 httpstat.py)。
3.2 JSON v1 schema(最小集)
AGENTS.md 定义的最小 schema 如下,后续通过 schema_version 扩展:
{
"schema_version": 1,
"url": "...",
"ok": true,
"exit_code": 0,
"response": {
"status_line": "HTTP/2 200",
"status_code": 200,
"remote_ip": "...",
"remote_port": "...",
"headers": {"Content-Type": "application/json", "Server": "nginx", "...": "..."}
},
"timings_ms": {
"dns": 5,
"connect": 10,
"tls": 15,
"server": 50,
"transfer": 20,
"total": 100,
"namelookup": 5,
"initial_connect": 15,
"pretransfer": 30,
"starttransfer": 80
},
"speed": {
"download_kbs": 1234.5,
"upload_kbs": 0.0
},
"slo": {
"pass": true,
"violations": []
}
}
该结构由 build_json_result() 统一构造(httpstat.py),可从源码确认各字段的取值逻辑:
response.status_line/status_code:从-D导出的响应头首行解析,兼容HTTP/2 200与HTTP/1.1 301 Moved Permanently两种格式;response.headers:首行之后的key: value行解析为字典;timings_ms:前五个字段(dns/connect/tls/server/transfer)是区间耗时(range),后五个字段(namelookup/initial_connect/pretransfer/starttransfer/total)是累计耗时(cumulative),单位均为毫秒;speed.download_kbs/upload_kbs:由 curl 的字节/秒速度除以 1024 并保留一位小数;slo:未指定--slo时为null,指定后为{pass, violations}对象。
与之对应的单元测试见 tests/test_httpstat.py 的 TestBuildJsonResult(含 schema_version、响应字段、timings 映射、速度换算、HTTP/1.1 状态行、JSON 可序列化等用例)。
四、SLO 阈值检查:--slo、退出码 4 与违规输出
SLO(Service Level Objective)能力是 Phase 1 的另一根支柱,它让 httpstat 从「给人看」的工具升级为「可被脚本和 Agent 判定」的探针。
4.1 语法与支持的 key
单一参数 --slo key=value,...,例如 --slo total=500,connect=100,ttfb=200。支持的 key 及其到 curl 指标的映射,定义在 SLO_KEY_MAP(httpstat.py):
| SLO key | 映射的 curl 指标 | 衡量内容 |
|---|---|---|
dns |
time_namelookup |
DNS 解析耗时 |
connect |
time_connect |
DNS + TCP 建连 |
tls |
time_pretransfer |
DNS + TCP + TLS |
ttfb |
time_starttransfer |
首字节时间(TTFB) |
total |
time_total |
完整请求总耗时 |
所有阈值单位均为毫秒。
4.2 解析与校验
parse_slo()(httpstat.py)负责把 "total=500,connect=100" 解析为 {'total': 500, 'connect': 100},并在以下非法输入下以退出码 1 报错:
- 空字符串或空的分段(
Error: empty SLO spec); - 分段缺少
=(Error: invalid SLO spec ...); - key 不在
SLO_KEY_MAP中(会列出合法 key); - value 不是整数或不是正整数。
对应测试 TestParseSlo 覆盖了全部这些非法分支,以及带空格输入 ' total = 500 , connect = 100 ' 会被 trim 后正确解析。
4.3 判定与退出码
check_slo()(httpstat.py)将每个 key 的实测毫秒值与阈值比较,actual > threshold 即记一次违规;恰好等于阈值不算违规(测试 test_exactly_at_threshold_passes 明确锁定该边界语义)。返回值是 (pass, violations),每个 violation 形如 {'key': ..., 'threshold_ms': ..., 'actual_ms': ...}。
在 main() 中,一旦 slo.pass 为 false,进程退出码变为 4。这一退出码语义在 httpstat_test.sh 中用 --slo total=1(1ms 阈值必然超标)断言 assert_exit 4 进行了 E2E 验证。
4.4 两种模式下的违规呈现
- pretty 模式:在计时图输出末尾,用红色逐行标注
SLO VIOLATION: {key} = {actual}ms (threshold: {threshold}ms)(httpstat.py); - JSON 模式:违规出现在
slo字段中,例如:
{
"slo": {
"pass": false,
"violations": [
{ "key": "total", "threshold_ms": 500, "actual_ms": 823 }
]
}
}
五、颜色控制:遵循 NO_COLOR 约定
Phase 1 明确了颜色控制策略:遵循 NO_COLOR 环境变量约定,只要该变量被设置(无论值是什么)即禁用所有 ANSI 颜色;同时不新增 --no-color 命令行参数,避免 flag 膨胀。
源码层面,模块级判定为 ISATTY = sys.stdout.isatty() and 'NO_COLOR' not in os.environ(httpstat.py),make_color() 在非 TTY 或设置了 NO_COLOR 时原样返回文本(httpstat.py)。E2E 测试「NO_COLOR disables ANSI escapes」验证输出中不存在 \x1b[ 转义序列;单元测试 TestNoColor 则同时覆盖了 NO_COLOR 设置与 ISATTY 开关两种路径。
六、Agent 友好细节:--save 与不设 --quiet 的取舍
--save <path>:将结果写入文件(httpstat.py、httpstat.py),适合多步 Agent 工作流复用结果;它不依赖--format,pretty 模式下也会写出同结构的 JSON 文件(此时使用indent=2)。E2E 测试会验证保存的文件可被json.load且schema_version == 1。- 不另设
--quiet:因为--format json已天然抑制装饰文本,无需再引入一个功能重叠的 flag。
这两个决策体现了 AGENTS.md 反复强调的原则:保持命令行接口精简,避免 flag 膨胀。
七、源码级原理:从 curl 输出到结构化数据
7.1 时间单位换算
curl 通过 -w 格式串输出 JSON(httpstat.py)。curl 版本差异导致时间字段有两种表示方式:7.61.0 之前是秒(float),7.61.0 起是微秒(int)。main() 中据此换算为毫秒整数(httpstat.py):
if isinstance(v, float):
d[k] = int(v * 1000) # 秒 → 毫秒
elif isinstance(v, int):
d[k] = int(v / 1000) # 微秒 → 毫秒
7.2 区间(range)计算
五个累计时间戳经过差分得到各阶段独立耗时(httpstat.py):
range_dns = time_namelookup
range_connection= time_connect - time_namelookup
range_ssl = time_pretransfer - time_connect
range_server = time_starttransfer - time_pretransfer
range_transfer = time_total - time_starttransfer
这正是 pretty 模式计时图(https_template/http_template,httpstat.py)与 JSON timings_ms 前五个字段的数据来源。
7.3 curl 参数约束与语言环境
- httpstat 内部已占用
-w、-D、-o、-s、-S,用户在 URL 后追加 curl 参数时这些选项会被拒绝(httpstat.py); - 子进程强制
LC_ALL=C(httpstat.py),确保时间戳解析不受区域设置影响——E2E 测试专门用LC_ALL=ru_RU验证过这一点; HTTPSTAT_CURL_BIN可指定 curl 路径(如 brew 版 curl 以启用 HTTP/2)。
八、测试与完成标准(Definition of Done)
8.1 三层测试体系
改造后的测试体系分三层:
- 单元测试 tests/test_httpstat.py(pytest):覆盖
parse_bool、pop_arg、parse_slo、check_slo、build_json_result、NO_COLOR六大逻辑块,把 AGENTS.md 点名的「指标换算、区间计算、parse_bool」全部纳入稳定回归。开发依赖在 pyproject.toml 的[dependency-groups] dev中声明为pytest>=8.4.2,可用uv run pytest tests/ -v运行; - 端到端测试 httpstat_test.sh:新增用例包括
--format json输出合法 JSON 且含schema_version、--format jsonl单行输出、--slo total=1触发退出码 4、--save写文件、NO_COLOR=1无 ANSI 转义、HTTPSTAT_METRICS_ONLY向后兼容。注意:该脚本依赖外网站点可达性,与 AGENTS.md 记载的技术债一致; - 手工冒烟:
python httpstat.py https://example.com --format json --slo total=100等组合验证。
8.2 Definition of Done 对照
AGENTS.md 定义的完成标准与当前实现逐一对应:
--format json输出具备schema_version=1的稳定结构,有单元测试锁定 →TestBuildJsonResult.test_schema_version;--slo阈值判定正确,退出码4有测试覆盖 →TestCheckSlo全部用例 +httpstat_test.sh的assert_exit 4;NO_COLOR正确禁用颜色输出 →TestNoColor+ E2E 无 ANSI 断言;- 不破坏现有
pretty模式的默认行为 →--format默认值即pretty,且「基本用法」与「https 站点」等原有 E2E 用例继续通过。
九、Phase 2:Skill 层与 Agent 评估
9.1 诊断 Skill
Phase 2(进行中)在 skills/httpstat/SKILL.md 实现了面向 AI Agent 的 HTTP 性能诊断技能,覆盖:
- 自动安装:
which httpstat || pip install httpstat(或uv pip install/pipx/ brew),不假设环境已装; - 结构化运行:优先
httpstat <URL> --format json [curl options]获取机器可读结果; - 瓶颈识别:把
timings_ms中的 5 个区间字段分别对应 DNS/TCP/TLS/Server/Transfer 五类瓶颈,每类给出典型健康区间、可能原因与修复建议(如 DNS 慢建议--resolve绕过解析、TLS 慢建议核对证书链与 OCSP stapling); - SLO 阈值:
--slo total=500,ttfb=300用于持续监控; - curl 命令转换:将已有 curl 命令转换为 httpstat(去掉
-w/-o/-s/-S,保留 headers、method、data 等)。
9.2 评估用例
skills/httpstat/evals/evals.json 包含 3 个评估用例:慢 API 诊断(httpbin.org/delay/2,期望识别 server 阶段为瓶颈)、curl 命令耗时拆解、TLS 开销对比(http vs https)。根据 kb/sessions/2026-04-08-create-httpstat-diagnostics-skill.md 的 session 记录,该 Skill 经过两轮迭代评估:第二轮在干净目录中运行,with-skill 通过率 91.7% 对比 baseline(仅用 raw curl -w)的 78.3%,验证了 Skill 引导 Agent 自动安装并使用结构化诊断的价值。session 记录同时指出了两个后续优化点:评估环境隔离(避免全局 pip install 造成测试污染)与「是否重定向到 HTTPS」这一非区分性断言的处理。
9.3 待补充项
AGENTS.md 明确记录:诊断推理输出结构(bottleneck_stage、next_actions)尚未结构化为 JSON,目前仍以自然语言分析为主,这是 Phase 2 的后续工作方向。
十、总结:一条清晰的 Agent 友好化路线
从 AGENTS.md 的规划到 httpstat.py、tests/test_httpstat.py、httpstat_test.sh、skills/httpstat/SKILL.md 的落地实现,httpstat 的 2.0 时代完成了从「纯人类可读」到「机器可判定、Agent 可消费」的跃迁:--format json 提供带 schema version 的稳定结构,--slo 给出可脚本判定的退出码语义,NO_COLOR 与 --save 补全了流水线集成细节,Skill 层则把「如何诊断瓶颈」本身也变成了可复用的结构化能力。如果你正在为自己的诊断工具设计 Agent 友好接口,这套「单文件 CLI + 结构化输出 + 阈值退出码 + 文档化 Skill」的组合是一个值得参考的最小实现范本。