戦績レポート for TETR.IO
tetr.io の Tetra League 戦績を TETRA CHANNEL API から取得し、11章＋付録構成のHTML分析レポートを生成するツールです（英語表記: League Report for TETR.IO）。
本ツールには2つの版があります。
| 版 | 場所 | 状態 |
|---|
| Web版（現行） | web/ | 開発中。今後の機能追加はこちらに行います |
| Python版（旧版） | python/ | 旧版。更新停止予定（保守のみ） |
本ツールは非公式です。TETR.IO / osk とは関係ありません。"TETR.IO" は権利者の商標です。
Webアプリ
インストール不要で、ブラウザーからそのまま使えます。
https://league-report.61bi.workers.dev/
サンプルレポート
実際の出力イメージを以下で確認できます。
| レポート種別 | リンク |
|---|
| Web版 戦績レポート（300試合・匿名化版） | サンプルを見る |
Web版（現行）
Cloudflare Workers 上で動くWebアプリです（公開URL: https://league-report.61bi.workers.dev/）。ブラウザーでユーザー名と取得マッチ数を入力すると、11章＋付録構成の戦績分析レポート（グラフはChart.js）を1ページのHTMLとして生成します。
- Workerは TETRA CHANNEL API への軽量プロキシ（
/api/league-page）として動作し、レポートの集計・描画はブラウザー側（public/report.js）で行います。Workers無料プランでも動かせる構成です。
- OSを問わず利用できます。
- 入力したユーザー名の公開Tetra Leagueデータのみを使用します。
- 戦績・能力値集計はDQ（不戦勝・不戦敗）を含む公式勝敗マッチ全体を対象にします。通常勝率のみDQ除外の参考指標として残しています。
- マッチ単位のAPM/PPS/VSなどの能力値は、APIの試合集計値（
leaderboard.stats）を優先し、欠損時のみラウンド平均で補います。
開発・ローカル実行
Node.js 22 以降が必要です。
cd web
npm install
npm run dev
wrangler dev が起動したら、表示されたURL（既定は http://localhost:8787）をブラウザーで開きます。
検証
cd web
npm run check
型チェック、クライアントバンドルのビルド、vitest によるテストをまとめて実行します。CI（.github/workflows/web.yml）でも同じ内容を検証しています。
デプロイ
自分のCloudflareアカウントへデプロイする場合は次を実行します。
cd web
npx wrangler deploy
Python版（旧版・更新停止予定）
Windows向けのGUI/コマンドライン版です。旧版として今後の機能追加は行わず、更新停止予定です。 新規に使う場合はWeb版を推奨します。
Python版では、ツールが作る**①戦績レポート（本体）に加えて、外部AIに素材を渡して作る②AI考察レポート（別紙）**を作成できます（②はPython版のみの機能です）。
旧版サンプルレポート
旧Python版のサンプルHTMLは配布していません。Python版には対戦相手の匿名化機能がなく、生成物に相手の実ハンドルがそのまま残るためです。出力イメージは匿名化済みのWeb版サンプルで確認してください。章立てはWeb版とおおむね共通です。
Python版を自分で動かして生成したレポートを共有する場合は、対戦相手のハンドルが本文・表・グラフ画像に含まれる点に注意してください。
| ① 戦績レポート（本体） | ② AI考察レポート（別紙） |
|---|
| 作る主体 | ツールが作る | 外部AIチャット、または連携AIエージェントCLI |
| AIの要否 | 不要 | 必要（AIチャット貼り付け、またはCodex CLI / Claude Code CLI） |
| 主な内容 | 指標の計算・表・グラフ・章立ての解説 | 数値を踏まえた深掘りの考察・言語化 |
| 形式 | 自己完結HTML（1ファイル） | 自己完結HTML（別紙・1ファイル） |
動作条件
- Windows 10 / 11
- Python 3.10 以降（
py -3 または python で起動できること）
- PowerShell 5.1 以降
- インターネット接続
実行ポリシーで PowerShell スクリプトが止まる場合は、現在のユーザーだけ許可します。
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
GUIで使う
python\レポート作成GUI.bat をダブルクリックします。- プレイヤーIDと取得試合数を入力します。
- 必要な実行内容をチェックし、
実行 をクリックします。
標準設定では、TETR.IOから戦績データを取得し、HTMLレポートを作成して、完了後にブラウザーと保存先フォルダーを開きます。GUI初回実行時に、レポート生成用の仮想環境と依存パッケージを自動で準備します。
②AI考察レポートは、GUIの「② AI考察レポートを作る」から、作成方法（AIチャット用素材の保存 / AIエージェントCLIで自動作成）・推論レベル・連携AIエージェントCLI（Codex CLI / Claude Code CLI）を選んで実行します。
コマンドで使う
先にレポートビルダー用の仮想環境を準備します。
py -3 -m venv "python\src\report_builder\.venv"
& "python\src\report_builder\.venv\Scripts\python.exe" -m pip install -r "python\src\report_builder\requirements.txt"
APIから直近100試合を取得します（GUIと同じ data\raw|csv|parquet 構成にする場合は --output-layout typed を付けます）。
& "python\src\report_builder\.venv\Scripts\python.exe" `
"python\src\api_export\tetrio_league_export.py" `
--source api --username your_username --max-matches 100 `
--outputs all --output-dir "python\data" --output-layout typed
取得済みデータから①戦績レポート（本体・HTML）を生成します。
& "python\src\report_builder\make_report.ps1" `
-DataFile "python\data\parquet\your_username_tetra_league_rounds_with_params.parquet" `
-MatchesFile "python\data\parquet\your_username_tetra_league_matches_with_params.parquet" `
-Player "your_username" -Open
②AI考察レポート関連の主なスイッチ:
-PrepareAI: AIチャット貼り付け用の素材（AI用JSON ai_appendix_data.json・プロンプト prompt_chat.md）を python/src/report_builder/cache/ai に書き出します。-GenerateAIReport: 連携AIエージェントCLIで②を自動作成します。-AIAgent codex|claude でCLIを、-AIReasoningLevel standard|high|low で推論レベルを選びます。CLI実行が失敗しても①本体HTMLは保持され、cache/ai の素材でAIチャット貼り付け手順へ切り替えられます。
出力
- GUIのAPI取得データ:
python\data\raw, python\data\parquet, python\data\csv
- GUIの成果物:
python\reports\<player>_report_<yyyy_mm_dd_HHmm>.html、python\reports\<player>_ai_report_<yyyy_mm_dd_HHmm>.html
- コマンドの成果物:
python/src/report_builder/output（①・②HTML）、python/src/report_builder/cache/ai（AI用JSON・プロンプト）
- 実行情報:
python\src\report_builder\cache\latest_run_manifest.json
個人データの取り扱い
取得データとレポートには、対戦相手のユーザー名、ID、成績が含まれます。共有前に内容を確認してください。
指標について
APP、DS/S、DS/P、GbE、Area、VS/APM などは取得した試合・ラウンドデータから計算します。
Est. TR、Opener / Stride / Inf DS / Plonk、Cheese Index、Weighted APP などの派生指標は、TetraStats に由来する計算式として扱います。
これらは公式TETR.IO計算ではありません。
ライセンスと帰属
このリポジトリのコードは MIT License です。詳細は LICENSE を参照してください。
直接依存パッケージのライセンス概要は THIRD_PARTY_NOTICES.md を参照してください。
