pyperformance Stat Report

负责把已存在的 pyperformance JSON 结果整理成适合人工阅读和汇报的统计产物。此 skill 只读结果，不负责跑 benchmark，也不能替代 pyperformance-result-compare 对 baseline source、CPU affinity、worker env、噪声和可信度的判断。

CinderX/JIT 性能结论必须先确认结果满足 ../using-cpython-optimize/references/pyperformance-env-contract.md；get_stat.py 只格式化已有数据。

输入

• 两个或更多 run.json / pyperformance JSON 文件，按对比顺序传入。
• 第一个 JSON 是 ratio 计算的 baseline。
• 可选 benchmark 名称，用于只输出指定用例。

脚本

从已加载 skill 的目录解析 bundled helper 绝对路径，不要假设当前目录是插件根目录。保持报告输出目录为 working directory：

SKILL_DIR="/absolute/path/from-loaded-skill/pyperformance-stat-report"
SCRIPT="$SKILL_DIR/scripts/get_stat.py"
cd <report-output-directory>
python "$SCRIPT" [-c] [-b <benchmark>]... <baseline.json> <candidate.json> [more.json ...]

JSON 可以使用绝对路径，也可以使用相对报告目录的路径。未传 JSON 时脚本会扫描当前目录 *.json；正式报告中优先写显式路径。

模式

• -c / --console-only：只打印对比表，不生成文件，不需要 openpyxl 或 matplotlib。
• 默认模式：打印表格，在临时目录生成完整报告后统一发布 benchmark_comparison.xlsx 和 benchmark_trends_part<N>.png；生成失败时保留上一套完整报告。
• -b / --benchmarks：只保留指定的公共 benchmark；每个 benchmark 单独写一个 -b，例如 -b 2to3 -b chaos，并保持用户给定顺序。

默认产物模式需要：

python -m pip install openpyxl matplotlib

语义

• 只比较所有有效 JSON 共有的 benchmark。
• 第一个 JSON 必须成功加载且包含 benchmark；除 baseline 外还必须至少有一个有效 candidate。
• 拒绝通过等价路径、符号链接或硬链接重复传入同一物理 JSON，避免自比较报告。
• 单项 ratio 和几何平均都使用 baseline_time / current_time。
• ratio 大于 1.0 表示快于第一个 JSON；小于 1.0 表示慢于第一个 JSON。
• 显示单位按 baseline 文件中该 benchmark 的耗时量级选择。

输出要求

使用此 skill 时必须输出：

• 真实命令和 working directory；
• JSON 顺序，以及哪个文件是 baseline；
• benchmark filter（如使用）；
• 公共 benchmark 数量；
• 生成的 benchmark_comparison.xlsx / benchmark_trends_part<N>.png 路径，或说明使用了 --console-only；
• 被跳过的 JSON 或未命中的指定 benchmark。