每个智能体步骤都带有一个工具调用的 tools[] 列表，每次调用都有一个测得的延迟。本实验 从四个角度刻画这种逐调用延迟：一个按工具/按提供商的箱线图视图，一个在粗粒度延迟分箱上 的计数-vs-延迟质量分解，以及两条累积 CDF（按调用计数和按延迟求和）随逐调用延迟阈值变化。

方法与假设：

• 有效工具延迟 = tool_internal_latency_ms（若存在），否则 tool_wall_latency_ms （= result_at − emitted_at；共享的 trace_db.EFFECTIVE_TOOL_LATENCY_MS_SQL 优先级—— 遗留的 latency_ms 字段不在归一化数据中）。内部计时是 runner 上报的 时长（Codex wrapper 的 Wall time、Claude 的 durationMs）。
• 只有严格为正的延迟才进入分布。 没有有效延迟的调用被计为 missing_latency； 有效延迟为非正的调用计为 nonpositive_latency ——两者都不进入箱线图、分箱、分位数或 CDF（与旧的 ToolStats 一致）。
• MCP 工具被合并（仅图）。 任何名称以 mcp_ 开头的工具都被别名归入 单个 mcp 桶；那些冗长的带服务器限定名的名称单独看都很罕见。CSV 汇总保留 原始、未别名化的名称。
• 罕见工具被折叠（仅图）。 单个提供商内部调用次数少于 --min-tool-calls-for-plot （默认 20）的工具被并入一个 Other (<N calls/tool) 箱。CSV 汇总保留 完整的逐工具明细。
• CDF 在调用上可加。 延迟总量按调用求和——并行工具不会被折叠 为墙钟时间，因此总延迟 CDF 度量的是归因到的工作量，而非已逝的会话墙钟时间。
• 精确，而非采样。 箱线的四分位、whisker、分位数和 CDF 都是在从 SQL 拉取的每一个 正有效延迟上计算的。旧的每工具 50k 蓄水池采样器已移除，因此 汇总 CSV 对每个工具都报告 sampled=False，且 sample_count = 完整的 latency_count （此前两个最高频工具 exec_command 和 Bash 是被蓄水池采样的）。

plot.py 是一个基于共享 trace DuckDB 的轻量级 query→shape→plot 流水线：

• _per_tool_query(plot_name_expr, *, by_provider)——共享的逐工具聚合：归一化 工具名（blank/NULL → <unknown-tool>），应用有效延迟优先级，并为每个 桶发出 call/latency_count/missing_latency/nonpositive_latency/error_calls 计数、 latency_sum/min/max、正延迟的精确 list(eff)，以及一个首次出现的 first_seen 序号。plot_name_expr 选择原始名（CSV）或 mcp_*→mcp 别名 （图）；by_provider 按 rounds.provider 拆分。
• load_tool_stats(con)——用于汇总 CSV 的全局 {tool_name: ToolStats}（原始名，不折叠）， 按首次出现顺序插入，使得稳定的 sort(key=calls) 能复现旧的 dict 顺序的平局判定。
• load_tool_stats_by_provider(con, *, min_calls)——用于箱线图的按提供商统计，MCP 合并在 SQL 中完成，随后在 Python 中执行罕见工具折叠；真实工具按字母 plot-name 顺序插入（旧的合并-dict 顺序），Other 追加在最后，固定相等调用数的平局。
• load_tool_latency_values_by_provider(con)——{provider: [positive latency, …]}，喂给两条 CDF（精确，无蓄水池）。
• load_tool_latency_bins(con, *, by_provider)——8 个粗粒度 TOOL_LATENCY_BINS_MS 半开分箱 （call/error 计数 + 延迟求和），全局与按提供商。
• plot_* / write_*——四张图和四个 CSV。
• main()——接入标准 trace_db CLI（--db | -i/--input | -o/--output-dir），并嵌入 自包含的 PNG sidecar。

matplotlib 3.9 的 labels→tick_labels 箱线图 kwarg 改名由 _BOXPLOT_LABEL_KW 垫片处理，使该图在 Pyodide（web 端 Analyze 页签）捆绑的 matplotlib 3.8.x 下也能渲染。数据层（解析、代理键、schema）位于 artifacts/utils/trace_db.py；参见 artifacts/utils/DB_SCHEMA.md。

# default merged trace, output next to this README
uv run python artifacts/tool_calls/tool_latency_distribution/plot.py

# a specific trace (materialized to a temp DuckDB cache on first use)
uv run python artifacts/tool_calls/tool_latency_distribution/plot.py -i trace/sample.jsonl

# a prebuilt DB (run_all.py's build-db step passes this), into a chosen dir
uv run python artifacts/tool_calls/tool_latency_distribution/plot.py --db /tmp/trace.duckdb -o /tmp/out

实用参数：--top-tools（每个面板最多箱数，默认 30）、--min-tool-calls-for-plot （罕见工具折叠阈值，默认 20）。

写入 -o（默认本文件夹）：

• tool_latency_by_tool.png——按提供商的箱线/whisker 面板，展示逐调用延迟按工具分布。
• tool_latency_summary.csv——完整的逐工具统计（原始名）：calls、latency_count、 missing_latency、nonpositive_latency、error_calls、mean_ms、min_ms、p50/p90/p99_ms、 max_ms、sample_count、sampled、providers。
• tool_latency_weighted_bins.png / .csv——在 8 个粗粒度延迟分箱上的工具调用计数 vs 延迟求和占比。
• tool_latency_count_cdf_by_provider.png / .csv——累积工具调用计数 ≤ 某延迟 阈值，按提供商。
• tool_total_latency_cdf_by_provider.png / .csv——来自 ≤ 某阈值的调用的累积延迟求和，按提供商。

每张 PNG 都是自包含的——它嵌入了本 README、CSV 以及绘图代码。用 python artifacts/utils/png_sidecar.py extract <png> 解包。