{"owner":"reorx","repo":"httpstat","hasSkills":true,"totalSkillsCount":3,"totalTokensCount":3960,"categories":["anthropic-skill","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["skills/httpstat/evals/evals.json","AGENTS.md","skills/httpstat/SKILL.md"],"skills":{"skills/httpstat/evals/evals.json":"{\n  \"skill_name\": \"httpstat\",\n  \"evals\": [\n    {\n      \"id\": 0,\n      \"prompt\": \"Our /api/v2/search endpoint at https://httpbin.org/delay/2 is taking forever, can you figure out what's going on?\",\n      \"expected_output\": \"Should run httpstat with --format json, identify server processing as the dominant bottleneck (~2s), and explain that the delay is server-side, not network.\",\n      \"files\": []\n    },\n    {\n      \"id\": 1,\n      \"prompt\": \"I have this curl command: curl -X GET https://httpbin.org/get -H 'Accept: application/json' — can you show me where the time is being spent?\",\n      \"expected_output\": \"Should convert the curl command to httpstat, run it, break down timings by phase, and explain the results.\",\n      \"files\": []\n    },\n    {\n      \"id\": 2,\n      \"prompt\": \"Can you check if there's a noticeable TLS overhead when hitting https://www.google.com vs http://www.google.com?\",\n      \"expected_output\": \"Should run httpstat on both URLs, compare TLS timing, and quantify the overhead. Should note that http may redirect to https.\",\n      \"files\": []\n    }\n  ]\n}\n","AGENTS.md":"# httpstat 项目规划\n\n## 1) 项目现状\n\n- 单文件 CLI (`httpstat.py`, ~370 行)，Python >=3.9，版本 2.0.0。\n- 打包完全由 `pyproject.toml` 驱动（setuptools），`setup.py` 已删除。\n- 构建/发布使用 `uv build` / `uv publish`。\n- 测试为 `httpstat_test.sh`（端到端 shell 脚本，依赖外网站点）。\n\n### 已完成的现代化工作\n- 去除所有 Python 2 兼容代码，shebang 改为 `#!/usr/bin/env python`。\n- 全量 f-string，新式 class 语法，类型标注（`Env` 类 overload、`NoReturn`）。\n- 严格布尔解析 `parse_bool()`，替代 `'true' in value.lower()`。\n- 临时文件 `try/finally` 统一清理，不再泄漏。\n- `quit()` 重命名为 `_exit()` 并标注 `NoReturn`。\n\n\n## 2) 剩余技术债\n\n### A. 测试可靠性不足（高优先级）\n- 仅有 shell E2E，强依赖公网与第三方站点行为，CI/本地结果不稳定。\n- 缺少单元测试，核心逻辑（指标换算、区间计算、`parse_bool`）没有稳定回归保障。\n\n### B. Agent 适配能力不足（中高优先级）\n- 当前 JSON 输出缺少 schema version、状态码语义、错误结构、上下文元数据。\n- 缺少\"可机器判断\"的 SLO/阈值能力（例如总耗时超阈值即非 0 退出）。\n- 输出模式较少，无法直接覆盖 Agent 常见流水线（JSONL、紧凑 JSON、纯错误对象）。\n\n\n## 3) 下一阶段推进方案\n\n### Phase 1：结构化输出 + SLO（本轮实施）\n\n#### 输出格式\n- 新增 `--format`（`-f`）：`pretty | json | jsonl`（默认 `pretty`，兼容现有行为）。\n- `HTTPSTAT_METRICS_ONLY` 环境变量保留兼容，等价于 `--format json`。\n- JSON v1 schema（最小集，后续通过 schema_version 扩展）：\n  ```json\n  {\n    \"schema_version\": 1,\n    \"url\": \"...\",\n    \"ok\": true,\n    \"exit_code\": 0,\n    \"response\": {\n      \"status_line\": \"HTTP/2 200\",\n      \"status_code\": 200,\n      \"remote_ip\": \"...\",\n      \"remote_port\": \"...\",\n      \"headers\": {\"Content-Type\": \"application/json\", \"Server\": \"nginx\", \"...\": \"...\"}\n    },\n    \"timings_ms\": {\n      \"dns\": 5,\n      \"connect\": 10,\n      \"tls\": 15,\n      \"server\": 50,\n      \"transfer\": 20,\n      \"total\": 100,\n      \"namelookup\": 5,\n      \"initial_connect\": 15,\n      \"pretransfer\": 30,\n      \"starttransfer\": 80\n    },\n    \"speed\": {\n      \"download_kbs\": 1234.5,\n      \"upload_kbs\": 0.0\n    },\n    \"slo\": {\n      \"pass\": true,\n      \"violations\": []\n    }\n  }\n  ```\n\n#### SLO 阈值\n- 单一参数 `--slo key=value,...`，例如 `--slo total=500,connect=100,ttfb=200`。\n- 支持的 key：`total`、`connect`、`ttfb`（starttransfer）、`dns`、`tls`。\n- 超阈值时退出码为 `4`，JSON 中 `slo.pass=false`，`slo.violations` 列出超标项。\n- pretty 模式下在输出末尾用红色标注超标指标。\n\n#### 颜色控制\n- 遵循 `NO_COLOR` 环境变量（https://no-color.org）。设置后禁用所有 ANSI 颜色。\n- 不新增 `--no-color` 命令行参数，减少 flag 膨胀。\n\n#### 其他 Agent 友好改进\n- 新增 `--save <path>` 将结果写入文件（适合多步 Agent 工作流复用）。\n- `--format json` 已天然抑制装饰文本，不另设 `--quiet`。\n\n### Phase 2：Skill 层（进行中）\n- `skills/httpstat/SKILL.md`：已完成初版诊断 skill，覆盖自动安装、瓶颈识别、SLO 阈值、curl 转换。\n- `skills/httpstat/evals/evals.json`：3 个评估用例，经过两轮迭代验证。\n- 待补充：诊断推理输出结构（bottleneck_stage、next_actions）尚未结构化为 JSON，目前以自然语言分析为主。\n\n\n## 4) 完成标准（Definition of Done）\n- `--format json` 输出具备 schema_version=1 的稳定结构，有单元测试锁定。\n- `--slo` 阈值判定正确，退出码 `4` 有测试覆盖。\n- `NO_COLOR` 正确禁用颜色输出。\n- 不破坏现有 `pretty` 模式的默认行为。\n","skills/httpstat/SKILL.md":"---\nname: httpstat\ndescription: >\n  Diagnose website and API performance using httpstat — a curl wrapper that visualizes\n  HTTP timing breakdowns (DNS, TCP, TLS, server processing, content transfer).\n  Use this skill whenever the user wants to debug slow websites, analyze HTTP/HTTPS\n  latency, profile API response times, understand curl timing output, find network\n  bottlenecks, check TLS handshake speed, measure Time to First Byte (TTFB), or\n  troubleshoot any connection performance issue. Also trigger when the user has a\n  curl command and wants to understand where time is being spent, or when they paste\n  httpstat output and want help interpreting it. Even if the user doesn't mention\n  \"httpstat\" by name — if they're asking \"why is this endpoint slow?\" or \"what's\n  taking so long?\" for an HTTP request, this skill applies.\n---\n\n# httpstat: HTTP Performance Diagnostics\n\nUse `httpstat` — a curl wrapper that breaks down HTTP request timing into discrete\nphases — to diagnose where latency lives and what to do about it.\n\n## When to use httpstat\n\n- User says a website or API is slow\n- User wants to profile an HTTP endpoint\n- User has a curl command and wants timing visibility\n- User asks about DNS, TLS, TTFB, or connection performance\n- User pastes httpstat output and wants interpretation\n- User wants to compare performance before/after a change\n\n## Setup (do this first)\n\nBefore running any diagnostics, ensure httpstat is available:\n\n```bash\nwhich httpstat || pip install httpstat\n```\n\nIf `pip` is not appropriate for the environment, try `uv pip install httpstat`,\n`pipx install httpstat`, or `brew install httpstat` (macOS). The goal is to get\nthe `httpstat` command on PATH. Do not assume it is already installed — always\ncheck first.\n\n## Running httpstat\n\n### Basic usage\n\n```bash\nhttpstat <URL> [curl options]\n```\n\n### Get structured JSON output (preferred for analysis)\n\n```bash\nhttpstat <URL> --format json [curl options]\n```\n\n### With SLO thresholds (exit code 4 if any threshold exceeded)\n\n```bash\nhttpstat <URL> --format json --slo total=500,connect=100,ttfb=200\n```\n\n### Save results to file for later comparison\n\n```bash\nhttpstat <URL> --format json --save results.json\n```\n\n### Supported curl options\n\nAny curl flag works EXCEPT `-w`, `-D`, `-o`, `-s`, `-S` (reserved by httpstat).\nCommon useful ones:\n\n- `-X POST --data '{\"key\":\"val\"}'` — test POST endpoints\n- `-H \"Authorization: Bearer TOKEN\"` — authenticated requests\n- `-L` — follow redirects\n- `-k` — skip TLS verification (useful for self-signed certs)\n- `--connect-timeout 10` — cap connection time\n- `-6` or `-4` — force IPv6 or IPv4\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `HTTPSTAT_SHOW_BODY=true` | false | Show response body (truncated to 1023 bytes) |\n| `HTTPSTAT_SHOW_SPEED=true` | false | Show download/upload speed |\n| `NO_COLOR=1` | unset | Disable colored output |\n\n## Understanding the JSON output\n\nThe `--format json` output has this structure:\n\n```\ntimings_ms:\n  dns         — DNS resolution time\n  connect     — TCP handshake duration (after DNS)\n  tls         — TLS handshake duration (after TCP connect)\n  server      — Server processing time (after TLS, before first byte)\n  transfer    — Content download time (after first byte)\n  total       — End-to-end total\n\n  namelookup    — Cumulative: DNS done\n  initial_connect — Cumulative: TCP done\n  pretransfer   — Cumulative: TLS done, ready to send\n  starttransfer — Cumulative: first byte received (TTFB)\n```\n\nThe \"range\" fields (dns, connect, tls, server, transfer) show how long each\nphase took independently. The cumulative fields show elapsed time since request\nstart. Both are in milliseconds.\n\n## Bottleneck diagnosis\n\nAfter running httpstat, identify the bottleneck by finding the phase that\nconsumes the most time relative to total. Then apply the appropriate diagnosis.\n\n### DNS is slow (dns > 50ms)\n\nTypical healthy: 1-20ms (cached) or 20-80ms (cold lookup).\n\n**Likely causes:**\n- DNS resolver is far away or overloaded\n- Domain has complex CNAME chains\n- DNSSEC validation overhead\n- No local DNS cache\n\n**Suggestions:**\n- Try a faster public resolver: `--resolve host:port:ip` to bypass DNS\n- Check if DNS caching is enabled on the machine (`systemd-resolved`, `dnsmasq`)\n- Run `dig +trace <domain>` to see the full resolution path\n- Compare with `dig @8.8.8.8 <domain>` vs `dig @1.1.1.1 <domain>`\n\n### TCP connect is slow (connect > 100ms)\n\nTypical healthy: 5-50ms (same region), 100-200ms (cross-continent).\n\n**Likely causes:**\n- Server is geographically distant\n- Network congestion or packet loss\n- Server TCP backlog is full (SYN queue saturation)\n- Firewall or security group adding latency\n\n**Suggestions:**\n- Check server location vs client: `curl -s ipinfo.io/<server-ip>`\n- Run from a closer region if possible\n- Check for packet loss: `mtr <host>` or `traceroute <host>`\n- Compare IPv4 vs IPv6: run httpstat with `-4` and `-6`\n\n### TLS handshake is slow (tls > 200ms)\n\nTypical healthy: 30-100ms (TLS 1.3), 100-250ms (TLS 1.2).\n\n**Likely causes:**\n- TLS 1.2 with full handshake (no session resumption)\n- OCSP stapling not configured (client does online revocation check)\n- Large certificate chain\n- Server doing expensive key exchange (RSA vs ECDHE)\n\n**Suggestions:**\n- Check TLS version: `curl -v <url> 2>&1 | grep 'SSL connection'`\n- Check cert chain size: `openssl s_client -connect host:443 -showcerts`\n- Verify OCSP stapling: `openssl s_client -connect host:443 -status`\n- TLS 1.3 reduces round trips — check if server supports it\n\n### Server processing is slow (server > 500ms)\n\nThis is TTFB minus connection overhead. It reflects backend work.\n\n**Likely causes:**\n- Slow database queries\n- Missing cache (hitting origin every time)\n- Cold start (serverless/lambda functions)\n- Upstream dependency latency\n- Heavy computation in request handler\n\n**Suggestions:**\n- This is an application-level issue, not a network issue\n- Check server-side logs and APM tools\n- Compare with a simpler endpoint on the same host to isolate\n- Run multiple times — if first request is slow but subsequent are fast, it's a cold start\n- Add `--slo server=200` to set a threshold and monitor\n\n### Content transfer is slow (transfer > 500ms for small responses)\n\n**Likely causes:**\n- Large response body without compression\n- Server sending data in small chunks with delays (streaming/SSE)\n- Bandwidth limitation between client and server\n- Transfer-Encoding: chunked with slow chunk generation\n\n**Suggestions:**\n- Check response size: look at Content-Length or `HTTPSTAT_SHOW_BODY=true`\n- Verify compression: `-H \"Accept-Encoding: gzip\"` and check response headers\n- If response is large, this may be expected — calculate effective bandwidth\n- Compare `HTTPSTAT_SHOW_SPEED=true` output against expected bandwidth\n\n## Diagnostic workflow\n\nFollow this sequence when a user reports a slow endpoint:\n\n1. **Run httpstat with JSON output** to get structured timings\n2. **Identify the dominant phase** — which timing is the largest portion of total?\n3. **Run 3-5 times** to check for variance (one slow DNS lookup doesn't mean DNS is the problem)\n4. **Compare against baselines** — is this endpoint unusually slow, or is the server always like this?\n5. **Drill into the bottleneck** using the phase-specific diagnostics above\n6. **Set SLO thresholds** if the user wants ongoing monitoring: `--slo total=500,ttfb=300`\n\n### Multiple-run comparison\n\nRun httpstat several times and compare JSON output to distinguish consistent\nbottlenecks from transient issues:\n\n```bash\nfor i in 1 2 3; do\n  httpstat <URL> --format json --save \"run_$i.json\"\ndone\n```\n\nThen compare the `timings_ms` across runs. High variance in one phase suggests\ntransient issues (DNS cache miss on first run, TLS session resumption on\nsubsequent runs, etc.).\n\n## Converting curl commands\n\nWhen a user has an existing curl command, convert it to httpstat by:\n\n1. Replace `curl` with `httpstat`\n2. Remove any `-w` (write-out format) flag — httpstat provides its own\n3. Remove `-o /dev/null` or `-o <file>` — httpstat handles output\n4. Remove `-s` and `-S` — httpstat sets these internally\n5. Keep everything else (headers, method, data, auth, etc.)\n\nExample:\n```\n# Original curl\ncurl -X POST https://api.example.com/v1/users \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  -w \"time_total: %{time_total}\\n\" -o /dev/null -s\n\n# Converted to httpstat\nhttpstat https://api.example.com/v1/users \\\n  -X POST \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  --format json\n```\n\n## SLO key reference\n\n| SLO key | Maps to | What it measures |\n|---------|---------|------------------|\n| `dns` | time_namelookup | DNS resolution |\n| `connect` | time_connect | DNS + TCP connect |\n| `tls` | time_pretransfer | DNS + TCP + TLS |\n| `ttfb` | time_starttransfer | Time to first byte |\n| `total` | time_total | Complete request |\n\nAll values in milliseconds. Exit code is `4` when any threshold is exceeded.\n"},"files":{"skills/httpstat/evals/evals.json":"{\n  \"skill_name\": \"httpstat\",\n  \"evals\": [\n    {\n      \"id\": 0,\n      \"prompt\": \"Our /api/v2/search endpoint at https://httpbin.org/delay/2 is taking forever, can you figure out what's going on?\",\n      \"expected_output\": \"Should run httpstat with --format json, identify server processing as the dominant bottleneck (~2s), and explain that the delay is server-side, not network.\",\n      \"files\": []\n    },\n    {\n      \"id\": 1,\n      \"prompt\": \"I have this curl command: curl -X GET https://httpbin.org/get -H 'Accept: application/json' — can you show me where the time is being spent?\",\n      \"expected_output\": \"Should convert the curl command to httpstat, run it, break down timings by phase, and explain the results.\",\n      \"files\": []\n    },\n    {\n      \"id\": 2,\n      \"prompt\": \"Can you check if there's a noticeable TLS overhead when hitting https://www.google.com vs http://www.google.com?\",\n      \"expected_output\": \"Should run httpstat on both URLs, compare TLS timing, and quantify the overhead. Should note that http may redirect to https.\",\n      \"files\": []\n    }\n  ]\n}\n","AGENTS.md":"# httpstat 项目规划\n\n## 1) 项目现状\n\n- 单文件 CLI (`httpstat.py`, ~370 行)，Python >=3.9，版本 2.0.0。\n- 打包完全由 `pyproject.toml` 驱动（setuptools），`setup.py` 已删除。\n- 构建/发布使用 `uv build` / `uv publish`。\n- 测试为 `httpstat_test.sh`（端到端 shell 脚本，依赖外网站点）。\n\n### 已完成的现代化工作\n- 去除所有 Python 2 兼容代码，shebang 改为 `#!/usr/bin/env python`。\n- 全量 f-string，新式 class 语法，类型标注（`Env` 类 overload、`NoReturn`）。\n- 严格布尔解析 `parse_bool()`，替代 `'true' in value.lower()`。\n- 临时文件 `try/finally` 统一清理，不再泄漏。\n- `quit()` 重命名为 `_exit()` 并标注 `NoReturn`。\n\n\n## 2) 剩余技术债\n\n### A. 测试可靠性不足（高优先级）\n- 仅有 shell E2E，强依赖公网与第三方站点行为，CI/本地结果不稳定。\n- 缺少单元测试，核心逻辑（指标换算、区间计算、`parse_bool`）没有稳定回归保障。\n\n### B. Agent 适配能力不足（中高优先级）\n- 当前 JSON 输出缺少 schema version、状态码语义、错误结构、上下文元数据。\n- 缺少\"可机器判断\"的 SLO/阈值能力（例如总耗时超阈值即非 0 退出）。\n- 输出模式较少，无法直接覆盖 Agent 常见流水线（JSONL、紧凑 JSON、纯错误对象）。\n\n\n## 3) 下一阶段推进方案\n\n### Phase 1：结构化输出 + SLO（本轮实施）\n\n#### 输出格式\n- 新增 `--format`（`-f`）：`pretty | json | jsonl`（默认 `pretty`，兼容现有行为）。\n- `HTTPSTAT_METRICS_ONLY` 环境变量保留兼容，等价于 `--format json`。\n- JSON v1 schema（最小集，后续通过 schema_version 扩展）：\n  ```json\n  {\n    \"schema_version\": 1,\n    \"url\": \"...\",\n    \"ok\": true,\n    \"exit_code\": 0,\n    \"response\": {\n      \"status_line\": \"HTTP/2 200\",\n      \"status_code\": 200,\n      \"remote_ip\": \"...\",\n      \"remote_port\": \"...\",\n      \"headers\": {\"Content-Type\": \"application/json\", \"Server\": \"nginx\", \"...\": \"...\"}\n    },\n    \"timings_ms\": {\n      \"dns\": 5,\n      \"connect\": 10,\n      \"tls\": 15,\n      \"server\": 50,\n      \"transfer\": 20,\n      \"total\": 100,\n      \"namelookup\": 5,\n      \"initial_connect\": 15,\n      \"pretransfer\": 30,\n      \"starttransfer\": 80\n    },\n    \"speed\": {\n      \"download_kbs\": 1234.5,\n      \"upload_kbs\": 0.0\n    },\n    \"slo\": {\n      \"pass\": true,\n      \"violations\": []\n    }\n  }\n  ```\n\n#### SLO 阈值\n- 单一参数 `--slo key=value,...`，例如 `--slo total=500,connect=100,ttfb=200`。\n- 支持的 key：`total`、`connect`、`ttfb`（starttransfer）、`dns`、`tls`。\n- 超阈值时退出码为 `4`，JSON 中 `slo.pass=false`，`slo.violations` 列出超标项。\n- pretty 模式下在输出末尾用红色标注超标指标。\n\n#### 颜色控制\n- 遵循 `NO_COLOR` 环境变量（https://no-color.org）。设置后禁用所有 ANSI 颜色。\n- 不新增 `--no-color` 命令行参数，减少 flag 膨胀。\n\n#### 其他 Agent 友好改进\n- 新增 `--save <path>` 将结果写入文件（适合多步 Agent 工作流复用）。\n- `--format json` 已天然抑制装饰文本，不另设 `--quiet`。\n\n### Phase 2：Skill 层（进行中）\n- `skills/httpstat/SKILL.md`：已完成初版诊断 skill，覆盖自动安装、瓶颈识别、SLO 阈值、curl 转换。\n- `skills/httpstat/evals/evals.json`：3 个评估用例，经过两轮迭代验证。\n- 待补充：诊断推理输出结构（bottleneck_stage、next_actions）尚未结构化为 JSON，目前以自然语言分析为主。\n\n\n## 4) 完成标准（Definition of Done）\n- `--format json` 输出具备 schema_version=1 的稳定结构，有单元测试锁定。\n- `--slo` 阈值判定正确，退出码 `4` 有测试覆盖。\n- `NO_COLOR` 正确禁用颜色输出。\n- 不破坏现有 `pretty` 模式的默认行为。\n","skills/httpstat/SKILL.md":"---\nname: httpstat\ndescription: >\n  Diagnose website and API performance using httpstat — a curl wrapper that visualizes\n  HTTP timing breakdowns (DNS, TCP, TLS, server processing, content transfer).\n  Use this skill whenever the user wants to debug slow websites, analyze HTTP/HTTPS\n  latency, profile API response times, understand curl timing output, find network\n  bottlenecks, check TLS handshake speed, measure Time to First Byte (TTFB), or\n  troubleshoot any connection performance issue. Also trigger when the user has a\n  curl command and wants to understand where time is being spent, or when they paste\n  httpstat output and want help interpreting it. Even if the user doesn't mention\n  \"httpstat\" by name — if they're asking \"why is this endpoint slow?\" or \"what's\n  taking so long?\" for an HTTP request, this skill applies.\n---\n\n# httpstat: HTTP Performance Diagnostics\n\nUse `httpstat` — a curl wrapper that breaks down HTTP request timing into discrete\nphases — to diagnose where latency lives and what to do about it.\n\n## When to use httpstat\n\n- User says a website or API is slow\n- User wants to profile an HTTP endpoint\n- User has a curl command and wants timing visibility\n- User asks about DNS, TLS, TTFB, or connection performance\n- User pastes httpstat output and wants interpretation\n- User wants to compare performance before/after a change\n\n## Setup (do this first)\n\nBefore running any diagnostics, ensure httpstat is available:\n\n```bash\nwhich httpstat || pip install httpstat\n```\n\nIf `pip` is not appropriate for the environment, try `uv pip install httpstat`,\n`pipx install httpstat`, or `brew install httpstat` (macOS). The goal is to get\nthe `httpstat` command on PATH. Do not assume it is already installed — always\ncheck first.\n\n## Running httpstat\n\n### Basic usage\n\n```bash\nhttpstat <URL> [curl options]\n```\n\n### Get structured JSON output (preferred for analysis)\n\n```bash\nhttpstat <URL> --format json [curl options]\n```\n\n### With SLO thresholds (exit code 4 if any threshold exceeded)\n\n```bash\nhttpstat <URL> --format json --slo total=500,connect=100,ttfb=200\n```\n\n### Save results to file for later comparison\n\n```bash\nhttpstat <URL> --format json --save results.json\n```\n\n### Supported curl options\n\nAny curl flag works EXCEPT `-w`, `-D`, `-o`, `-s`, `-S` (reserved by httpstat).\nCommon useful ones:\n\n- `-X POST --data '{\"key\":\"val\"}'` — test POST endpoints\n- `-H \"Authorization: Bearer TOKEN\"` — authenticated requests\n- `-L` — follow redirects\n- `-k` — skip TLS verification (useful for self-signed certs)\n- `--connect-timeout 10` — cap connection time\n- `-6` or `-4` — force IPv6 or IPv4\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `HTTPSTAT_SHOW_BODY=true` | false | Show response body (truncated to 1023 bytes) |\n| `HTTPSTAT_SHOW_SPEED=true` | false | Show download/upload speed |\n| `NO_COLOR=1` | unset | Disable colored output |\n\n## Understanding the JSON output\n\nThe `--format json` output has this structure:\n\n```\ntimings_ms:\n  dns         — DNS resolution time\n  connect     — TCP handshake duration (after DNS)\n  tls         — TLS handshake duration (after TCP connect)\n  server      — Server processing time (after TLS, before first byte)\n  transfer    — Content download time (after first byte)\n  total       — End-to-end total\n\n  namelookup    — Cumulative: DNS done\n  initial_connect — Cumulative: TCP done\n  pretransfer   — Cumulative: TLS done, ready to send\n  starttransfer — Cumulative: first byte received (TTFB)\n```\n\nThe \"range\" fields (dns, connect, tls, server, transfer) show how long each\nphase took independently. The cumulative fields show elapsed time since request\nstart. Both are in milliseconds.\n\n## Bottleneck diagnosis\n\nAfter running httpstat, identify the bottleneck by finding the phase that\nconsumes the most time relative to total. Then apply the appropriate diagnosis.\n\n### DNS is slow (dns > 50ms)\n\nTypical healthy: 1-20ms (cached) or 20-80ms (cold lookup).\n\n**Likely causes:**\n- DNS resolver is far away or overloaded\n- Domain has complex CNAME chains\n- DNSSEC validation overhead\n- No local DNS cache\n\n**Suggestions:**\n- Try a faster public resolver: `--resolve host:port:ip` to bypass DNS\n- Check if DNS caching is enabled on the machine (`systemd-resolved`, `dnsmasq`)\n- Run `dig +trace <domain>` to see the full resolution path\n- Compare with `dig @8.8.8.8 <domain>` vs `dig @1.1.1.1 <domain>`\n\n### TCP connect is slow (connect > 100ms)\n\nTypical healthy: 5-50ms (same region), 100-200ms (cross-continent).\n\n**Likely causes:**\n- Server is geographically distant\n- Network congestion or packet loss\n- Server TCP backlog is full (SYN queue saturation)\n- Firewall or security group adding latency\n\n**Suggestions:**\n- Check server location vs client: `curl -s ipinfo.io/<server-ip>`\n- Run from a closer region if possible\n- Check for packet loss: `mtr <host>` or `traceroute <host>`\n- Compare IPv4 vs IPv6: run httpstat with `-4` and `-6`\n\n### TLS handshake is slow (tls > 200ms)\n\nTypical healthy: 30-100ms (TLS 1.3), 100-250ms (TLS 1.2).\n\n**Likely causes:**\n- TLS 1.2 with full handshake (no session resumption)\n- OCSP stapling not configured (client does online revocation check)\n- Large certificate chain\n- Server doing expensive key exchange (RSA vs ECDHE)\n\n**Suggestions:**\n- Check TLS version: `curl -v <url> 2>&1 | grep 'SSL connection'`\n- Check cert chain size: `openssl s_client -connect host:443 -showcerts`\n- Verify OCSP stapling: `openssl s_client -connect host:443 -status`\n- TLS 1.3 reduces round trips — check if server supports it\n\n### Server processing is slow (server > 500ms)\n\nThis is TTFB minus connection overhead. It reflects backend work.\n\n**Likely causes:**\n- Slow database queries\n- Missing cache (hitting origin every time)\n- Cold start (serverless/lambda functions)\n- Upstream dependency latency\n- Heavy computation in request handler\n\n**Suggestions:**\n- This is an application-level issue, not a network issue\n- Check server-side logs and APM tools\n- Compare with a simpler endpoint on the same host to isolate\n- Run multiple times — if first request is slow but subsequent are fast, it's a cold start\n- Add `--slo server=200` to set a threshold and monitor\n\n### Content transfer is slow (transfer > 500ms for small responses)\n\n**Likely causes:**\n- Large response body without compression\n- Server sending data in small chunks with delays (streaming/SSE)\n- Bandwidth limitation between client and server\n- Transfer-Encoding: chunked with slow chunk generation\n\n**Suggestions:**\n- Check response size: look at Content-Length or `HTTPSTAT_SHOW_BODY=true`\n- Verify compression: `-H \"Accept-Encoding: gzip\"` and check response headers\n- If response is large, this may be expected — calculate effective bandwidth\n- Compare `HTTPSTAT_SHOW_SPEED=true` output against expected bandwidth\n\n## Diagnostic workflow\n\nFollow this sequence when a user reports a slow endpoint:\n\n1. **Run httpstat with JSON output** to get structured timings\n2. **Identify the dominant phase** — which timing is the largest portion of total?\n3. **Run 3-5 times** to check for variance (one slow DNS lookup doesn't mean DNS is the problem)\n4. **Compare against baselines** — is this endpoint unusually slow, or is the server always like this?\n5. **Drill into the bottleneck** using the phase-specific diagnostics above\n6. **Set SLO thresholds** if the user wants ongoing monitoring: `--slo total=500,ttfb=300`\n\n### Multiple-run comparison\n\nRun httpstat several times and compare JSON output to distinguish consistent\nbottlenecks from transient issues:\n\n```bash\nfor i in 1 2 3; do\n  httpstat <URL> --format json --save \"run_$i.json\"\ndone\n```\n\nThen compare the `timings_ms` across runs. High variance in one phase suggests\ntransient issues (DNS cache miss on first run, TLS session resumption on\nsubsequent runs, etc.).\n\n## Converting curl commands\n\nWhen a user has an existing curl command, convert it to httpstat by:\n\n1. Replace `curl` with `httpstat`\n2. Remove any `-w` (write-out format) flag — httpstat provides its own\n3. Remove `-o /dev/null` or `-o <file>` — httpstat handles output\n4. Remove `-s` and `-S` — httpstat sets these internally\n5. Keep everything else (headers, method, data, auth, etc.)\n\nExample:\n```\n# Original curl\ncurl -X POST https://api.example.com/v1/users \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  -w \"time_total: %{time_total}\\n\" -o /dev/null -s\n\n# Converted to httpstat\nhttpstat https://api.example.com/v1/users \\\n  -X POST \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  --format json\n```\n\n## SLO key reference\n\n| SLO key | Maps to | What it measures |\n|---------|---------|------------------|\n| `dns` | time_namelookup | DNS resolution |\n| `connect` | time_connect | DNS + TCP connect |\n| `tls` | time_pretransfer | DNS + TCP + TLS |\n| `ttfb` | time_starttransfer | Time to first byte |\n| `total` | time_total | Complete request |\n\nAll values in milliseconds. Exit code is `4` when any threshold is exceeded.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/reorx/httpstat/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# httpstat 项目规划\n\n## 1) 项目现状\n\n- 单文件 CLI (`httpstat.py`, ~370 行)，Python >=3.9，版本 2.0.0。\n- 打包完全由 `pyproject.toml` 驱动（setuptools），`setup.py` 已删除。\n- 构建/发布使用 `uv build` / `uv publish`。\n- 测试为 `httpstat_test.sh`（端到端 shell 脚本，依赖外网站点）。\n\n### 已完成的现代化工作\n- 去除所有 Python 2 兼容代码，shebang 改为 `#!/usr/bin/env python`。\n- 全量 f-string，新式 class 语法，类型标注（`Env` 类 overload、`NoReturn`）。\n- 严格布尔解析 `parse_bool()`，替代 `'true' in value.lower()`。\n- 临时文件 `try/finally` 统一清理，不再泄漏。\n- `quit()` 重命名为 `_exit()` 并标注 `NoReturn`。\n\n\n## 2) 剩余技术债\n\n### A. 测试可靠性不足（高优先级）\n- 仅有 shell E2E，强依赖公网与第三方站点行为，CI/本地结果不稳定。\n- 缺少单元测试，核心逻辑（指标换算、区间计算、`parse_bool`）没有稳定回归保障。\n\n### B. Agent 适配能力不足（中高优先级）\n- 当前 JSON 输出缺少 schema version、状态码语义、错误结构、上下文元数据。\n- 缺少\"可机器判断\"的 SLO/阈值能力（例如总耗时超阈值即非 0 退出）。\n- 输出模式较少，无法直接覆盖 Agent 常见流水线（JSONL、紧凑 JSON、纯错误对象）。\n\n\n## 3) 下一阶段推进方案\n\n### Phase 1：结构化输出 + SLO（本轮实施）\n\n#### 输出格式\n- 新增 `--format`（`-f`）：`pretty | json | jsonl`（默认 `pretty`，兼容现有行为）。\n- `HTTPSTAT_METRICS_ONLY` 环境变量保留兼容，等价于 `--format json`。\n- JSON v1 schema（最小集，后续通过 schema_version 扩展）：\n  ```json\n  {\n    \"schema_version\": 1,\n    \"url\": \"...\",\n    \"ok\": true,\n    \"exit_code\": 0,\n    \"response\": {\n      \"status_line\": \"HTTP/2 200\",\n      \"status_code\": 200,\n      \"remote_ip\": \"...\",\n      \"remote_port\": \"...\",\n      \"headers\": {\"Content-Type\": \"application/json\", \"Server\": \"nginx\", \"...\": \"...\"}\n    },\n    \"timings_ms\": {\n      \"dns\": 5,\n      \"connect\": 10,\n      \"tls\": 15,\n      \"server\": 50,\n      \"transfer\": 20,\n      \"total\": 100,\n      \"namelookup\": 5,\n      \"initial_connect\": 15,\n      \"pretransfer\": 30,\n      \"starttransfer\": 80\n    },\n    \"speed\": {\n      \"download_kbs\": 1234.5,\n      \"upload_kbs\": 0.0\n    },\n    \"slo\": {\n      \"pass\": true,\n      \"violations\": []\n    }\n  }\n  ```\n\n#### SLO 阈值\n- 单一参数 `--slo key=value,...`，例如 `--slo total=500,connect=100,ttfb=200`。\n- 支持的 key：`total`、`connect`、`ttfb`（starttransfer）、`dns`、`tls`。\n- 超阈值时退出码为 `4`，JSON 中 `slo.pass=false`，`slo.violations` 列出超标项。\n- pretty 模式下在输出末尾用红色标注超标指标。\n\n#### 颜色控制\n- 遵循 `NO_COLOR` 环境变量（https://no-color.org）。设置后禁用所有 ANSI 颜色。\n- 不新增 `--no-color` 命令行参数，减少 flag 膨胀。\n\n#### 其他 Agent 友好改进\n- 新增 `--save <path>` 将结果写入文件（适合多步 Agent 工作流复用）。\n- `--format json` 已天然抑制装饰文本，不另设 `--quiet`。\n\n### Phase 2：Skill 层（进行中）\n- `skills/httpstat/SKILL.md`：已完成初版诊断 skill，覆盖自动安装、瓶颈识别、SLO 阈值、curl 转换。\n- `skills/httpstat/evals/evals.json`：3 个评估用例，经过两轮迭代验证。\n- 待补充：诊断推理输出结构（bottleneck_stage、next_actions）尚未结构化为 JSON，目前以自然语言分析为主。\n\n\n## 4) 完成标准（Definition of Done）\n- `--format json` 输出具备 schema_version=1 的稳定结构，有单元测试锁定。\n- `--slo` 阈值判定正确，退出码 `4` 有测试覆盖。\n- `NO_COLOR` 正确禁用颜色输出。\n- 不破坏现有 `pretty` 模式的默认行为。\n","isInternal":false,"tokens":1384,"sizeBytes":3855},{"name":"evals.json","path":"skills/httpstat/evals/evals.json","rawUrl":"https://raw.githubusercontent.com/reorx/httpstat/HEAD/skills/httpstat/evals/evals.json","title":"Evals Skill","category":"anthropic-skill","format":"json","content":"{\n  \"skill_name\": \"httpstat\",\n  \"evals\": [\n    {\n      \"id\": 0,\n      \"prompt\": \"Our /api/v2/search endpoint at https://httpbin.org/delay/2 is taking forever, can you figure out what's going on?\",\n      \"expected_output\": \"Should run httpstat with --format json, identify server processing as the dominant bottleneck (~2s), and explain that the delay is server-side, not network.\",\n      \"files\": []\n    },\n    {\n      \"id\": 1,\n      \"prompt\": \"I have this curl command: curl -X GET https://httpbin.org/get -H 'Accept: application/json' — can you show me where the time is being spent?\",\n      \"expected_output\": \"Should convert the curl command to httpstat, run it, break down timings by phase, and explain the results.\",\n      \"files\": []\n    },\n    {\n      \"id\": 2,\n      \"prompt\": \"Can you check if there's a noticeable TLS overhead when hitting https://www.google.com vs http://www.google.com?\",\n      \"expected_output\": \"Should run httpstat on both URLs, compare TLS timing, and quantify the overhead. Should note that http may redirect to https.\",\n      \"files\": []\n    }\n  ]\n}\n","frontmatter":{"skill_name":"httpstat","evals":[{"id":0,"prompt":"Our /api/v2/search endpoint at https://httpbin.org/delay/2 is taking forever, can you figure out what's going on?","expected_output":"Should run httpstat with --format json, identify server processing as the dominant bottleneck (~2s), and explain that the delay is server-side, not network.","files":[]},{"id":1,"prompt":"I have this curl command: curl -X GET https://httpbin.org/get -H 'Accept: application/json' — can you show me where the time is being spent?","expected_output":"Should convert the curl command to httpstat, run it, break down timings by phase, and explain the results.","files":[]},{"id":2,"prompt":"Can you check if there's a noticeable TLS overhead when hitting https://www.google.com vs http://www.google.com?","expected_output":"Should run httpstat on both URLs, compare TLS timing, and quantify the overhead. Should note that http may redirect to https.","files":[]}]},"isInternal":false,"tokens":271,"sizeBytes":1087},{"name":"SKILL.md","path":"skills/httpstat/SKILL.md","rawUrl":"https://raw.githubusercontent.com/reorx/httpstat/HEAD/skills/httpstat/SKILL.md","title":"httpstat","category":"anthropic-skill","format":"markdown","content":"---\nname: httpstat\ndescription: >\n  Diagnose website and API performance using httpstat — a curl wrapper that visualizes\n  HTTP timing breakdowns (DNS, TCP, TLS, server processing, content transfer).\n  Use this skill whenever the user wants to debug slow websites, analyze HTTP/HTTPS\n  latency, profile API response times, understand curl timing output, find network\n  bottlenecks, check TLS handshake speed, measure Time to First Byte (TTFB), or\n  troubleshoot any connection performance issue. Also trigger when the user has a\n  curl command and wants to understand where time is being spent, or when they paste\n  httpstat output and want help interpreting it. Even if the user doesn't mention\n  \"httpstat\" by name — if they're asking \"why is this endpoint slow?\" or \"what's\n  taking so long?\" for an HTTP request, this skill applies.\n---\n\n# httpstat: HTTP Performance Diagnostics\n\nUse `httpstat` — a curl wrapper that breaks down HTTP request timing into discrete\nphases — to diagnose where latency lives and what to do about it.\n\n## When to use httpstat\n\n- User says a website or API is slow\n- User wants to profile an HTTP endpoint\n- User has a curl command and wants timing visibility\n- User asks about DNS, TLS, TTFB, or connection performance\n- User pastes httpstat output and wants interpretation\n- User wants to compare performance before/after a change\n\n## Setup (do this first)\n\nBefore running any diagnostics, ensure httpstat is available:\n\n```bash\nwhich httpstat || pip install httpstat\n```\n\nIf `pip` is not appropriate for the environment, try `uv pip install httpstat`,\n`pipx install httpstat`, or `brew install httpstat` (macOS). The goal is to get\nthe `httpstat` command on PATH. Do not assume it is already installed — always\ncheck first.\n\n## Running httpstat\n\n### Basic usage\n\n```bash\nhttpstat <URL> [curl options]\n```\n\n### Get structured JSON output (preferred for analysis)\n\n```bash\nhttpstat <URL> --format json [curl options]\n```\n\n### With SLO thresholds (exit code 4 if any threshold exceeded)\n\n```bash\nhttpstat <URL> --format json --slo total=500,connect=100,ttfb=200\n```\n\n### Save results to file for later comparison\n\n```bash\nhttpstat <URL> --format json --save results.json\n```\n\n### Supported curl options\n\nAny curl flag works EXCEPT `-w`, `-D`, `-o`, `-s`, `-S` (reserved by httpstat).\nCommon useful ones:\n\n- `-X POST --data '{\"key\":\"val\"}'` — test POST endpoints\n- `-H \"Authorization: Bearer TOKEN\"` — authenticated requests\n- `-L` — follow redirects\n- `-k` — skip TLS verification (useful for self-signed certs)\n- `--connect-timeout 10` — cap connection time\n- `-6` or `-4` — force IPv6 or IPv4\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `HTTPSTAT_SHOW_BODY=true` | false | Show response body (truncated to 1023 bytes) |\n| `HTTPSTAT_SHOW_SPEED=true` | false | Show download/upload speed |\n| `NO_COLOR=1` | unset | Disable colored output |\n\n## Understanding the JSON output\n\nThe `--format json` output has this structure:\n\n```\ntimings_ms:\n  dns         — DNS resolution time\n  connect     — TCP handshake duration (after DNS)\n  tls         — TLS handshake duration (after TCP connect)\n  server      — Server processing time (after TLS, before first byte)\n  transfer    — Content download time (after first byte)\n  total       — End-to-end total\n\n  namelookup    — Cumulative: DNS done\n  initial_connect — Cumulative: TCP done\n  pretransfer   — Cumulative: TLS done, ready to send\n  starttransfer — Cumulative: first byte received (TTFB)\n```\n\nThe \"range\" fields (dns, connect, tls, server, transfer) show how long each\nphase took independently. The cumulative fields show elapsed time since request\nstart. Both are in milliseconds.\n\n## Bottleneck diagnosis\n\nAfter running httpstat, identify the bottleneck by finding the phase that\nconsumes the most time relative to total. Then apply the appropriate diagnosis.\n\n### DNS is slow (dns > 50ms)\n\nTypical healthy: 1-20ms (cached) or 20-80ms (cold lookup).\n\n**Likely causes:**\n- DNS resolver is far away or overloaded\n- Domain has complex CNAME chains\n- DNSSEC validation overhead\n- No local DNS cache\n\n**Suggestions:**\n- Try a faster public resolver: `--resolve host:port:ip` to bypass DNS\n- Check if DNS caching is enabled on the machine (`systemd-resolved`, `dnsmasq`)\n- Run `dig +trace <domain>` to see the full resolution path\n- Compare with `dig @8.8.8.8 <domain>` vs `dig @1.1.1.1 <domain>`\n\n### TCP connect is slow (connect > 100ms)\n\nTypical healthy: 5-50ms (same region), 100-200ms (cross-continent).\n\n**Likely causes:**\n- Server is geographically distant\n- Network congestion or packet loss\n- Server TCP backlog is full (SYN queue saturation)\n- Firewall or security group adding latency\n\n**Suggestions:**\n- Check server location vs client: `curl -s ipinfo.io/<server-ip>`\n- Run from a closer region if possible\n- Check for packet loss: `mtr <host>` or `traceroute <host>`\n- Compare IPv4 vs IPv6: run httpstat with `-4` and `-6`\n\n### TLS handshake is slow (tls > 200ms)\n\nTypical healthy: 30-100ms (TLS 1.3), 100-250ms (TLS 1.2).\n\n**Likely causes:**\n- TLS 1.2 with full handshake (no session resumption)\n- OCSP stapling not configured (client does online revocation check)\n- Large certificate chain\n- Server doing expensive key exchange (RSA vs ECDHE)\n\n**Suggestions:**\n- Check TLS version: `curl -v <url> 2>&1 | grep 'SSL connection'`\n- Check cert chain size: `openssl s_client -connect host:443 -showcerts`\n- Verify OCSP stapling: `openssl s_client -connect host:443 -status`\n- TLS 1.3 reduces round trips — check if server supports it\n\n### Server processing is slow (server > 500ms)\n\nThis is TTFB minus connection overhead. It reflects backend work.\n\n**Likely causes:**\n- Slow database queries\n- Missing cache (hitting origin every time)\n- Cold start (serverless/lambda functions)\n- Upstream dependency latency\n- Heavy computation in request handler\n\n**Suggestions:**\n- This is an application-level issue, not a network issue\n- Check server-side logs and APM tools\n- Compare with a simpler endpoint on the same host to isolate\n- Run multiple times — if first request is slow but subsequent are fast, it's a cold start\n- Add `--slo server=200` to set a threshold and monitor\n\n### Content transfer is slow (transfer > 500ms for small responses)\n\n**Likely causes:**\n- Large response body without compression\n- Server sending data in small chunks with delays (streaming/SSE)\n- Bandwidth limitation between client and server\n- Transfer-Encoding: chunked with slow chunk generation\n\n**Suggestions:**\n- Check response size: look at Content-Length or `HTTPSTAT_SHOW_BODY=true`\n- Verify compression: `-H \"Accept-Encoding: gzip\"` and check response headers\n- If response is large, this may be expected — calculate effective bandwidth\n- Compare `HTTPSTAT_SHOW_SPEED=true` output against expected bandwidth\n\n## Diagnostic workflow\n\nFollow this sequence when a user reports a slow endpoint:\n\n1. **Run httpstat with JSON output** to get structured timings\n2. **Identify the dominant phase** — which timing is the largest portion of total?\n3. **Run 3-5 times** to check for variance (one slow DNS lookup doesn't mean DNS is the problem)\n4. **Compare against baselines** — is this endpoint unusually slow, or is the server always like this?\n5. **Drill into the bottleneck** using the phase-specific diagnostics above\n6. **Set SLO thresholds** if the user wants ongoing monitoring: `--slo total=500,ttfb=300`\n\n### Multiple-run comparison\n\nRun httpstat several times and compare JSON output to distinguish consistent\nbottlenecks from transient issues:\n\n```bash\nfor i in 1 2 3; do\n  httpstat <URL> --format json --save \"run_$i.json\"\ndone\n```\n\nThen compare the `timings_ms` across runs. High variance in one phase suggests\ntransient issues (DNS cache miss on first run, TLS session resumption on\nsubsequent runs, etc.).\n\n## Converting curl commands\n\nWhen a user has an existing curl command, convert it to httpstat by:\n\n1. Replace `curl` with `httpstat`\n2. Remove any `-w` (write-out format) flag — httpstat provides its own\n3. Remove `-o /dev/null` or `-o <file>` — httpstat handles output\n4. Remove `-s` and `-S` — httpstat sets these internally\n5. Keep everything else (headers, method, data, auth, etc.)\n\nExample:\n```\n# Original curl\ncurl -X POST https://api.example.com/v1/users \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  -w \"time_total: %{time_total}\\n\" -o /dev/null -s\n\n# Converted to httpstat\nhttpstat https://api.example.com/v1/users \\\n  -X POST \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  --format json\n```\n\n## SLO key reference\n\n| SLO key | Maps to | What it measures |\n|---------|---------|------------------|\n| `dns` | time_namelookup | DNS resolution |\n| `connect` | time_connect | DNS + TCP connect |\n| `tls` | time_pretransfer | DNS + TCP + TLS |\n| `ttfb` | time_starttransfer | Time to first byte |\n| `total` | time_total | Complete request |\n\nAll values in milliseconds. Exit code is `4` when any threshold is exceeded.\n","frontmatter":{"name":"httpstat","description":"Diagnose website and API performance using httpstat — a curl wrapper that visualizes HTTP timing breakdowns (DNS, TCP, TLS, server processing, content transfer). Use this skill whenever the user wants to debug slow websites, analyze HTTP/HTTPS latency, profile API response times, understand curl timing output, find network bottlenecks, check TLS handshake speed, measure Time to First Byte (TTFB), or troubleshoot any connection performance issue. Also trigger when the user has a curl command and wants to understand where time is being spent, or when they paste httpstat output and want help interpreting it. Even if the user doesn't mention \"httpstat\" by name — if they're asking \"why is this endpoint slow?\" or \"what's taking so long?\" for an HTTP request, this skill applies.\n"},"isInternal":false,"tokens":2305,"sizeBytes":9143}],"systemPromptSnippet":"<yakaai_skills repo=\"reorx/httpstat\">\n<!-- File: AGENTS.md (Tokens: ~1384 | Category: root-instruction) -->\n# httpstat 项目规划\n\n## 1) 项目现状\n\n- 单文件 CLI (`httpstat.py`, ~370 行)，Python >=3.9，版本 2.0.0。\n- 打包完全由 `pyproject.toml` 驱动（setuptools），`setup.py` 已删除。\n- 构建/发布使用 `uv build` / `uv publish`。\n- 测试为 `httpstat_test.sh`（端到端 shell 脚本，依赖外网站点）。\n\n### 已完成的现代化工作\n- 去除所有 Python 2 兼容代码，shebang 改为 `#!/usr/bin/env python`。\n- 全量 f-string，新式 class 语法，类型标注（`Env` 类 overload、`NoReturn`）。\n- 严格布尔解析 `parse_bool()`，替代 `'true' in value.lower()`。\n- 临时文件 `try/finally` 统一清理，不再泄漏。\n- `quit()` 重命名为 `_exit()` 并标注 `NoReturn`。\n\n\n## 2) 剩余技术债\n\n### A. 测试可靠性不足（高优先级）\n- 仅有 shell E2E，强依赖公网与第三方站点行为，CI/本地结果不稳定。\n- 缺少单元测试，核心逻辑（指标换算、区间计算、`parse_bool`）没有稳定回归保障。\n\n### B. Agent 适配能力不足（中高优先级）\n- 当前 JSON 输出缺少 schema version、状态码语义、错误结构、上下文元数据。\n- 缺少\"可机器判断\"的 SLO/阈值能力（例如总耗时超阈值即非 0 退出）。\n- 输出模式较少，无法直接覆盖 Agent 常见流水线（JSONL、紧凑 JSON、纯错误对象）。\n\n\n## 3) 下一阶段推进方案\n\n### Phase 1：结构化输出 + SLO（本轮实施）\n\n#### 输出格式\n- 新增 `--format`（`-f`）：`pretty | json | jsonl`（默认 `pretty`，兼容现有行为）。\n- `HTTPSTAT_METRICS_ONLY` 环境变量保留兼容，等价于 `--format json`。\n- JSON v1 schema（最小集，后续通过 schema_version 扩展）：\n  ```json\n  {\n    \"schema_version\": 1,\n    \"url\": \"...\",\n    \"ok\": true,\n    \"exit_code\": 0,\n    \"response\": {\n      \"status_line\": \"HTTP/2 200\",\n      \"status_code\": 200,\n      \"remote_ip\": \"...\",\n      \"remote_port\": \"...\",\n      \"headers\": {\"Content-Type\": \"application/json\", \"Server\": \"nginx\", \"...\": \"...\"}\n    },\n    \"timings_ms\": {\n      \"dns\": 5,\n      \"connect\": 10,\n      \"tls\": 15,\n      \"server\": 50,\n      \"transfer\": 20,\n      \"total\": 100,\n      \"namelookup\": 5,\n      \"initial_connect\": 15,\n      \"pretransfer\": 30,\n      \"starttransfer\": 80\n    },\n    \"speed\": {\n      \"download_kbs\": 1234.5,\n      \"upload_kbs\": 0.0\n    },\n    \"slo\": {\n      \"pass\": true,\n      \"violations\": []\n    }\n  }\n  ```\n\n#### SLO 阈值\n- 单一参数 `--slo key=value,...`，例如 `--slo total=500,connect=100,ttfb=200`。\n- 支持的 key：`total`、`connect`、`ttfb`（starttransfer）、`dns`、`tls`。\n- 超阈值时退出码为 `4`，JSON 中 `slo.pass=false`，`slo.violations` 列出超标项。\n- pretty 模式下在输出末尾用红色标注超标指标。\n\n#### 颜色控制\n- 遵循 `NO_COLOR` 环境变量（https://no-color.org）。设置后禁用所有 ANSI 颜色。\n- 不新增 `--no-color` 命令行参数，减少 flag 膨胀。\n\n#### 其他 Agent 友好改进\n- 新增 `--save <path>` 将结果写入文件（适合多步 Agent 工作流复用）。\n- `--format json` 已天然抑制装饰文本，不另设 `--quiet`。\n\n### Phase 2：Skill 层（进行中）\n- `skills/httpstat/SKILL.md`：已完成初版诊断 skill，覆盖自动安装、瓶颈识别、SLO 阈值、curl 转换。\n- `skills/httpstat/evals/evals.json`：3 个评估用例，经过两轮迭代验证。\n- 待补充：诊断推理输出结构（bottleneck_stage、next_actions）尚未结构化为 JSON，目前以自然语言分析为主。\n\n\n## 4) 完成标准（Definition of Done）\n- `--format json` 输出具备 schema_version=1 的稳定结构，有单元测试锁定。\n- `--slo` 阈值判定正确，退出码 `4` 有测试覆盖。\n- `NO_COLOR` 正确禁用颜色输出。\n- 不破坏现有 `pretty` 模式的默认行为。\n\n<!-- File: skills/httpstat/evals/evals.json (Tokens: ~271 | Category: anthropic-skill) -->\n{\n  \"skill_name\": \"httpstat\",\n  \"evals\": [\n    {\n      \"id\": 0,\n      \"prompt\": \"Our /api/v2/search endpoint at https://httpbin.org/delay/2 is taking forever, can you figure out what's going on?\",\n      \"expected_output\": \"Should run httpstat with --format json, identify server processing as the dominant bottleneck (~2s), and explain that the delay is server-side, not network.\",\n      \"files\": []\n    },\n    {\n      \"id\": 1,\n      \"prompt\": \"I have this curl command: curl -X GET https://httpbin.org/get -H 'Accept: application/json' — can you show me where the time is being spent?\",\n      \"expected_output\": \"Should convert the curl command to httpstat, run it, break down timings by phase, and explain the results.\",\n      \"files\": []\n    },\n    {\n      \"id\": 2,\n      \"prompt\": \"Can you check if there's a noticeable TLS overhead when hitting https://www.google.com vs http://www.google.com?\",\n      \"expected_output\": \"Should run httpstat on both URLs, compare TLS timing, and quantify the overhead. Should note that http may redirect to https.\",\n      \"files\": []\n    }\n  ]\n}\n\n<!-- File: skills/httpstat/SKILL.md (Tokens: ~2305 | Category: anthropic-skill) -->\n---\nname: httpstat\ndescription: >\n  Diagnose website and API performance using httpstat — a curl wrapper that visualizes\n  HTTP timing breakdowns (DNS, TCP, TLS, server processing, content transfer).\n  Use this skill whenever the user wants to debug slow websites, analyze HTTP/HTTPS\n  latency, profile API response times, understand curl timing output, find network\n  bottlenecks, check TLS handshake speed, measure Time to First Byte (TTFB), or\n  troubleshoot any connection performance issue. Also trigger when the user has a\n  curl command and wants to understand where time is being spent, or when they paste\n  httpstat output and want help interpreting it. Even if the user doesn't mention\n  \"httpstat\" by name — if they're asking \"why is this endpoint slow?\" or \"what's\n  taking so long?\" for an HTTP request, this skill applies.\n---\n\n# httpstat: HTTP Performance Diagnostics\n\nUse `httpstat` — a curl wrapper that breaks down HTTP request timing into discrete\nphases — to diagnose where latency lives and what to do about it.\n\n## When to use httpstat\n\n- User says a website or API is slow\n- User wants to profile an HTTP endpoint\n- User has a curl command and wants timing visibility\n- User asks about DNS, TLS, TTFB, or connection performance\n- User pastes httpstat output and wants interpretation\n- User wants to compare performance before/after a change\n\n## Setup (do this first)\n\nBefore running any diagnostics, ensure httpstat is available:\n\n```bash\nwhich httpstat || pip install httpstat\n```\n\nIf `pip` is not appropriate for the environment, try `uv pip install httpstat`,\n`pipx install httpstat`, or `brew install httpstat` (macOS). The goal is to get\nthe `httpstat` command on PATH. Do not assume it is already installed — always\ncheck first.\n\n## Running httpstat\n\n### Basic usage\n\n```bash\nhttpstat <URL> [curl options]\n```\n\n### Get structured JSON output (preferred for analysis)\n\n```bash\nhttpstat <URL> --format json [curl options]\n```\n\n### With SLO thresholds (exit code 4 if any threshold exceeded)\n\n```bash\nhttpstat <URL> --format json --slo total=500,connect=100,ttfb=200\n```\n\n### Save results to file for later comparison\n\n```bash\nhttpstat <URL> --format json --save results.json\n```\n\n### Supported curl options\n\nAny curl flag works EXCEPT `-w`, `-D`, `-o`, `-s`, `-S` (reserved by httpstat).\nCommon useful ones:\n\n- `-X POST --data '{\"key\":\"val\"}'` — test POST endpoints\n- `-H \"Authorization: Bearer TOKEN\"` — authenticated requests\n- `-L` — follow redirects\n- `-k` — skip TLS verification (useful for self-signed certs)\n- `--connect-timeout 10` — cap connection time\n- `-6` or `-4` — force IPv6 or IPv4\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `HTTPSTAT_SHOW_BODY=true` | false | Show response body (truncated to 1023 bytes) |\n| `HTTPSTAT_SHOW_SPEED=true` | false | Show download/upload speed |\n| `NO_COLOR=1` | unset | Disable colored output |\n\n## Understanding the JSON output\n\nThe `--format json` output has this structure:\n\n```\ntimings_ms:\n  dns         — DNS resolution time\n  connect     — TCP handshake duration (after DNS)\n  tls         — TLS handshake duration (after TCP connect)\n  server      — Server processing time (after TLS, before first byte)\n  transfer    — Content download time (after first byte)\n  total       — End-to-end total\n\n  namelookup    — Cumulative: DNS done\n  initial_connect — Cumulative: TCP done\n  pretransfer   — Cumulative: TLS done, ready to send\n  starttransfer — Cumulative: first byte received (TTFB)\n```\n\nThe \"range\" fields (dns, connect, tls, server, transfer) show how long each\nphase took independently. The cumulative fields show elapsed time since request\nstart. Both are in milliseconds.\n\n## Bottleneck diagnosis\n\nAfter running httpstat, identify the bottleneck by finding the phase that\nconsumes the most time relative to total. Then apply the appropriate diagnosis.\n\n### DNS is slow (dns > 50ms)\n\nTypical healthy: 1-20ms (cached) or 20-80ms (cold lookup).\n\n**Likely causes:**\n- DNS resolver is far away or overloaded\n- Domain has complex CNAME chains\n- DNSSEC validation overhead\n- No local DNS cache\n\n**Suggestions:**\n- Try a faster public resolver: `--resolve host:port:ip` to bypass DNS\n- Check if DNS caching is enabled on the machine (`systemd-resolved`, `dnsmasq`)\n- Run `dig +trace <domain>` to see the full resolution path\n- Compare with `dig @8.8.8.8 <domain>` vs `dig @1.1.1.1 <domain>`\n\n### TCP connect is slow (connect > 100ms)\n\nTypical healthy: 5-50ms (same region), 100-200ms (cross-continent).\n\n**Likely causes:**\n- Server is geographically distant\n- Network congestion or packet loss\n- Server TCP backlog is full (SYN queue saturation)\n- Firewall or security group adding latency\n\n**Suggestions:**\n- Check server location vs client: `curl -s ipinfo.io/<server-ip>`\n- Run from a closer region if possible\n- Check for packet loss: `mtr <host>` or `traceroute <host>`\n- Compare IPv4 vs IPv6: run httpstat with `-4` and `-6`\n\n### TLS handshake is slow (tls > 200ms)\n\nTypical healthy: 30-100ms (TLS 1.3), 100-250ms (TLS 1.2).\n\n**Likely causes:**\n- TLS 1.2 with full handshake (no session resumption)\n- OCSP stapling not configured (client does online revocation check)\n- Large certificate chain\n- Server doing expensive key exchange (RSA vs ECDHE)\n\n**Suggestions:**\n- Check TLS version: `curl -v <url> 2>&1 | grep 'SSL connection'`\n- Check cert chain size: `openssl s_client -connect host:443 -showcerts`\n- Verify OCSP stapling: `openssl s_client -connect host:443 -status`\n- TLS 1.3 reduces round trips — check if server supports it\n\n### Server processing is slow (server > 500ms)\n\nThis is TTFB minus connection overhead. It reflects backend work.\n\n**Likely causes:**\n- Slow database queries\n- Missing cache (hitting origin every time)\n- Cold start (serverless/lambda functions)\n- Upstream dependency latency\n- Heavy computation in request handler\n\n**Suggestions:**\n- This is an application-level issue, not a network issue\n- Check server-side logs and APM tools\n- Compare with a simpler endpoint on the same host to isolate\n- Run multiple times — if first request is slow but subsequent are fast, it's a cold start\n- Add `--slo server=200` to set a threshold and monitor\n\n### Content transfer is slow (transfer > 500ms for small responses)\n\n**Likely causes:**\n- Large response body without compression\n- Server sending data in small chunks with delays (streaming/SSE)\n- Bandwidth limitation between client and server\n- Transfer-Encoding: chunked with slow chunk generation\n\n**Suggestions:**\n- Check response size: look at Content-Length or `HTTPSTAT_SHOW_BODY=true`\n- Verify compression: `-H \"Accept-Encoding: gzip\"` and check response headers\n- If response is large, this may be expected — calculate effective bandwidth\n- Compare `HTTPSTAT_SHOW_SPEED=true` output against expected bandwidth\n\n## Diagnostic workflow\n\nFollow this sequence when a user reports a slow endpoint:\n\n1. **Run httpstat with JSON output** to get structured timings\n2. **Identify the dominant phase** — which timing is the largest portion of total?\n3. **Run 3-5 times** to check for variance (one slow DNS lookup doesn't mean DNS is the problem)\n4. **Compare against baselines** — is this endpoint unusually slow, or is the server always like this?\n5. **Drill into the bottleneck** using the phase-specific diagnostics above\n6. **Set SLO thresholds** if the user wants ongoing monitoring: `--slo total=500,ttfb=300`\n\n### Multiple-run comparison\n\nRun httpstat several times and compare JSON output to distinguish consistent\nbottlenecks from transient issues:\n\n```bash\nfor i in 1 2 3; do\n  httpstat <URL> --format json --save \"run_$i.json\"\ndone\n```\n\nThen compare the `timings_ms` across runs. High variance in one phase suggests\ntransient issues (DNS cache miss on first run, TLS session resumption on\nsubsequent runs, etc.).\n\n## Converting curl commands\n\nWhen a user has an existing curl command, convert it to httpstat by:\n\n1. Replace `curl` with `httpstat`\n2. Remove any `-w` (write-out format) flag — httpstat provides its own\n3. Remove `-o /dev/null` or `-o <file>` — httpstat handles output\n4. Remove `-s` and `-S` — httpstat sets these internally\n5. Keep everything else (headers, method, data, auth, etc.)\n\nExample:\n```\n# Original curl\ncurl -X POST https://api.example.com/v1/users \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  -w \"time_total: %{time_total}\\n\" -o /dev/null -s\n\n# Converted to httpstat\nhttpstat https://api.example.com/v1/users \\\n  -X POST \\\n  -H \"Authorization: Bearer tok_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"test\"}' \\\n  --format json\n```\n\n## SLO key reference\n\n| SLO key | Maps to | What it measures |\n|---------|---------|------------------|\n| `dns` | time_namelookup | DNS resolution |\n| `connect` | time_connect | DNS + TCP connect |\n| `tls` | time_pretransfer | DNS + TCP + TLS |\n| `ttfb` | time_starttransfer | Time to first byte |\n| `total` | time_total | Complete request |\n\nAll values in milliseconds. Exit code is `4` when any threshold is exceeded.\n</yakaai_skills>"}