httpstat AGENTS.md

httpstat 项目规划

1) 项目现状

• 单文件 CLI (httpstat.py, ~370 行)，Python >=3.9，版本 2.0.0。
• 打包完全由 pyproject.toml 驱动（setuptools），setup.py 已删除。
• 构建/发布使用 uv build / uv publish。
• 测试为 httpstat_test.sh（端到端 shell 脚本，依赖外网站点）。

已完成的现代化工作

• 去除所有 Python 2 兼容代码，shebang 改为 #!/usr/bin/env python。
• 全量 f-string，新式 class 语法，类型标注（Env 类 overload、NoReturn）。
• 严格布尔解析 parse_bool()，替代 'true' in value.lower()。
• 临时文件 try/finally 统一清理，不再泄漏。
• quit() 重命名为 _exit() 并标注 NoReturn。

2) 剩余技术债

A. 测试可靠性不足（高优先级）

• 仅有 shell E2E，强依赖公网与第三方站点行为，CI/本地结果不稳定。
• 缺少单元测试，核心逻辑（指标换算、区间计算、parse_bool）没有稳定回归保障。

B. Agent 适配能力不足（中高优先级）

• 当前 JSON 输出缺少 schema version、状态码语义、错误结构、上下文元数据。
• 缺少"可机器判断"的 SLO/阈值能力（例如总耗时超阈值即非 0 退出）。
• 输出模式较少，无法直接覆盖 Agent 常见流水线（JSONL、紧凑 JSON、纯错误对象）。

3) 下一阶段推进方案

Phase 1：结构化输出 + SLO（本轮实施）

输出格式

• 新增 --format（-f）：pretty | json | jsonl（默认 pretty，兼容现有行为）。
• HTTPSTAT_METRICS_ONLY 环境变量保留兼容，等价于 --format json。
• JSON v1 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": []
    }
  }
  

SLO 阈值

• 单一参数 --slo key=value,...，例如 --slo total=500,connect=100,ttfb=200。
• 支持的 key：total、connect、ttfb（starttransfer）、dns、tls。
• 超阈值时退出码为 4，JSON 中 slo.pass=false，slo.violations 列出超标项。
• pretty 模式下在输出末尾用红色标注超标指标。

颜色控制

• 遵循 NO_COLOR 环境变量（https://no-color.org）。设置后禁用所有 ANSI 颜色。
• 不新增 --no-color 命令行参数，减少 flag 膨胀。