Eval: Skill for Claude Code

新增評測 Benchmark

CLAUDE.md §6 規定的流程，缺一步就不得合入 main。這份 skill 是那份規範的可執行版本。

動手前先確認

• 這是新的評測方法（新的 Extractor/Scorer 配對），不是既有方法的新資料集。 若只是新資料集且能沿用既有 evaluation_method，走 twinkle_eval/benchmarks.py 的下載註冊表即可，不需要跑本流程。
• 上一個 benchmark 已經完成（含比較報告）。§6.0.1 明訂：先完成再開始下一個。

第 0 步：先開 GitHub，再寫程式

沒有 Milestone 和 Issues 的 benchmark 實作不得開 PR。

gh api repos/ai-twinkle/Eval/milestones -f title="{Benchmark} — {一句話說明}" \
  -f description="來源：{paper/repo}｜目的：{評什麼}｜範圍：{預計實作到哪}"

接著開 6 個 Issue，每個都要掛 type: feature label 與該 Milestone：

#	標題格式	對應
1	feat({name}): prepare example dataset from HuggingFace	§6.1
2	feat({name}): implement Extractor + Scorer (+ Checkers)	§6.2
3	feat({name}): score comparison vs reference framework	§6.3
4	feat({name}): speed benchmark vs reference framework	§6.4
5	feat({name}): write docs/evals/{name}.md	§6.5
6	feat({name}): write tests/test_{name}.py	§6.6

gh issue create --title "feat({name}): ..." --label "type: feature" --milestone "{Milestone 標題}"

第 1 步：example dataset

放在 datasets/example/{name}/，10–20 筆（§6.1 規範；既有資料集實際落在 10–30 筆，如 aime2025 收了全部 30 題），涵蓋主要題型分佈。有子類別的（如 BFCL 的 simple/multiple/parallel）每個子類別至少 2–3 筆。

要求任何人不下載完整資料集就能跑通完整流程。格式必須是可直接執行的完整格式 （含 id、question、答案欄位）。

scripts/ 底下有既有的抽取腳本可以參考（prepare_bbh_example.py、 create_vision_mcq_example.py）。

資料集載入器支援 JSON / JSONL / CSV / TSV / Parquet / Arrow。twinkle_eval/datasets/file.py 的 _normalize_record() 會自動把 {"choices": [...], "answer": 1} 這種 HuggingFace 格式 正規化成 {"A": ..., "B": ..., "answer": "B"}。

第 2 步：實作 Extractor + Scorer

架構是 Extractor（從輸出抽答案）+ Scorer（比對正解） 兩個 ABC，定義在 twinkle_eval/core/abc.py。不要在 evaluators.py / main.py 加 if/elif 分支（原則 A）。

# twinkle_eval/metrics/extractors/{name}.py
from typing import Optional

from twinkle_eval.core.abc import Extractor


class MyExtractor(Extractor):
    def get_name(self) -> str:
        return "{name}"

    def extract(self, llm_output: str) -> Optional[str]:
        """抽不到回傳 None（會被計入 unparsed_count）。"""
        ...