单个工具名众多且因提供商而异；本实验将它们归入跨 Claude Code 和 Codex 含义相同的粗粒度类别，然后报告调用和有效延迟在这些类别间的分布。

方法与假设：

• 每次调用一行。 我们统计的是 tool_calls（即 UNNEST 后的 tools[]）中的条目，而非智能体步骤。
• 两套固定的工具→类别映射。 一套 5 类别加 other 的映射（Execute command、File write/edit、File read/search、Agent/task、Web/remote/lookup、Other）驱动计数 环图和延迟柱状图；一套 7 桶的展示映射（额外拆分出 Planning） 驱动 dashboard。两套映射都是逐字移植的显式 名称→类别 集合—— tool_category_tool_map.csv 发出已实现的 (category, provider, tool) 分解供 审计。
• 有效工具延迟 = tool_internal_latency_ms（若存在），否则 tool_wall_latency_ms （遗留的 latency_ms 回退不在归一化 schema 中）。只有正延迟 贡献到延迟求和以及分位数/长尾视图；缺失和非正 延迟被单独计数但排除在求和之外。
• 长尾分箱。 正延迟被分桶为 <1s、1–10s、10s–1m、>1m，以 对比每个桶的调用占比与其总延迟占比。

analyze.py 是一个基于共享 trace DuckDB 的 query→fold→plot 流水线：

• load_tool_aggregates(con)——一条对 tool_calls ⋈ rounds 的 GROUP BY (provider, tool_name)， 返回逐工具的 calls、error_calls，有效/缺失/非正延迟类计数， 以及正延迟求和。提供商/工具名归一化（<unknown-provider> / <unknown-tool>）在 SQL 中完成，以匹配旧的 loader。
• load_positive_latency_histogram(con)——正延迟的 (tool_name, latency_ms, count) 行， 在 Python 中展开为分位数所消费的逐类别延迟列表。
• scan_trace / scan_trace_presentation / scan_trace_long_tail_latency——使用逐字的 category_for_tool / presentation_category_for_tool 映射将逐工具 聚合折叠进粗粒度类别（在整数毫秒延迟上求和与顺序无关）。
• category_rows / presentation_rows / long_tail_rows 及其 write_*_csv——塑形并发出 四个 CSV。
• plot_count_ring / plot_latency_bar / plot_dashboard / plot_long_tail_imbalance—— 四张图。main() 接入标准 trace_db CLI，并嵌入 PNG sidecar。

数据层（解析、代理键、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_category_distribution/analyze.py

# a specific trace (materialized to a temp DuckDB cache on first use)
uv run python artifacts/tool_calls/tool_category_distribution/analyze.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_category_distribution/analyze.py --db /tmp/trace.duckdb -o /tmp/out

• tool_category_count_ring.png——6 个粗粒度类别上调用计数的圆环图。
• tool_category_latency_bar.png——每个类别的有效延迟求和（小时），带平均值。
• tool_category_dashboard.png——7 桶展示映射的组合圆环图 + 类别表 + 延迟分位条。
• tool_latency_long_tail_imbalance.png——<1s … >1m 分箱上的调用占比 vs 延迟占比。
• tool_category_summary.csv——每个粗粒度类别：调用数、占比、错误率、延迟类计数、 延迟求和/平均。
• tool_category_tool_map.csv——已实现的 (category, provider, tool_name) 分解。
• tool_category_dashboard_summary.csv——每个展示类别：调用数、占比、p25/p50/p90/p99 秒。
• tool_latency_long_tail_imbalance.csv——每个延迟分箱：调用数、调用占比、延迟、延迟 占比。
• result_analysis.md——生成的运行日志。

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