Recorder Mode 運用ガイド

--recorder-mode フラグで起動した「軽量記録専用モード」の使い方・配布方法・確認方法。

spec: standalone-recorder-app Phase 0 PoC 関連実測値: archive/refactoring/recorder-poc-metrics.md（リポジトリ archive 配下。docs サイトには未収録）

何ができるか

メモリ ~180 MB で常駐 (Viewer フル 1012 MB の 18%)
ログ監視 + DB 保存を UI なしで実行 (auto-start)
OBS ブラウザソース向けのオーバーレイ配信 (http://127.0.0.1:47832/overlay.html)。配信サーバの所有者は Recorder で、Manager はレイアウト編集時だけ起動すればよい。オーバーレイ設定の正本は <userData>/overlay-config.json（Recorder だけが書く）。Manager 不在でも再起動後に同じ見た目で配信し、「起動時 / ゲーム起動検知時に勝敗をリセット」と試合完了での勝敗の自動加算も Recorder が行う（spec: overlay-config-single-source）。 BP で決まった自分の 4 キャラのカスタムエリアへの反映も Recorder が行う（spec: electron-memory-release） (詳細: OBS 連携)
設定ファイル <userData>/user-settings.json を書くのは Recorder だけ。Manager の設定タブで変えた値は Recorder に送られて保存され、ゲーム検知（ON/OFF・対象プロセス名・間隔）は Recorder の再起動なしで反映される。変更は Manager の画面にも通知され、開いたままの設定タブが読み直す（spec: settings-ownership）
アカウント（DB の profiles）のログフォルダは 5 秒ごとに読み直し、追加・変更・削除を Recorder の再起動なしで監視に反映する。変わったフォルダの watcher だけ張り替え、ほかの watcher は止めない。トレイ / WS の watch:stop で止めている間は張らない（spec: settings-ownership-followups）
ブラウザ自動化 (recorderBrowserAutomation.enabled=true のときのみ。未設定は OFF で、戦績サイトにログインすると未設定のときだけ true になる)
トレイアイコン + 30 秒間隔のメトリクスログ + 試合検出時に console 出力

CLI フラグ (一時的な上書き)

UserSettings を変えずに 1 回だけ動作を変えたいとき:

bash

# ブラウザ自動化を強制 ON + 画面付き (--headed) で起動
yarn dev:electron:recorder:browser
# または手動で:
node scripts/dev/run-electron.cjs . --recorder-mode --browser-automation --headed

flag	効果
`--browser-automation`	enabled を強制 ON
`--no-browser-automation`	enabled を強制 OFF
`--headed`	headless=false (画面を出す)
`--headless`	headless=true (default)
`--target-url=<url>`	targetUrl 上書き
`--auto-full-workflow`	autoFullWorkflowOnStart=true

優先順位: CLI > UserSettings > default

--browser-automation / --no-browser-automation は開発・テスト用で、インストール版の起動経路（Run キー・ショートカット・ Manager / Viewer からの起動）は付けない。付けて起動した Recorder は戦績取得の ON/OFF を固定し、設定ファイル（Manager のトグル）の変更を反映しない（ログに「起動オプションで固定中」と出す）。固定中の値は status の battleRecordCliOverride に載り、 Manager のアプリ設定タブ（記録サービス制御）・ライブ監視タブ・トレイと Viewer のトレイは、実際の値を出してトグルを無効にし理由を表示する（spec: settings-ownership-followups）。

トレイ右クリックメニューで設定変更

Recorder 起動中、トレイアイコン右クリックで以下のメニューが開く:

状態: 監視 N 件 / ブラウザ ON  (read-only)
直近10戦 7勝3敗 / 勝率 70.0%  (read-only)
─────
🔑 今すぐログイン（再ログイン）
☐ 🎥 リプレイ自動録画 (OBS)   ← 接続テスト未成功のまま ON にすると準備の案内が出る
📺 OBS 用 URL をコピー (http://127.0.0.1:47832/overlay.html)  ← 配信サーバ停止中は disabled
─────
今すぐ終了して常駐も解除
終了

操作系（ブラウザ自動化の ON/OFF・取得・常駐・ゲーム検知）は Manager / Viewer から WS コマンドで委譲する。自動録画（リプレイ・試合ごと）の接続先・パスワード・接続テスト・スイッチは Manager の設定 →「OBS 連携」から obsRecording:* コマンドで行う（自動録画（OBS 連携））。トレイのチェックはリプレイの録画のスイッチ。

トグル操作は <userData>/user-settings.json の recorderBrowserAutomation を更新し、必要なら BrowserAutomation を即座に再起動する。Viewer を起動せずに Recorder 単独で設定変更できる。

ブラウザ自動化の有効化 (Viewer 経由 / 手動編集)

Recorder mode は Viewer 側 localStorage の設定を読めない ため、UserSettings.json に専用 section を持つ。

<userData>/user-settings.json を編集 (例):

json

{
  "myUid": "1046101022",
  "myPlayerNames": ["MyName"],
  "recorderBrowserAutomation": {
    "enabled": true,
    "headless": true,
    "targetUrl": "https://xzysteam.shengtiangames.com/gamerecords/dist/index.html#/pages/home/index",
    "autoFullWorkflowOnStart": false
  }
}

field	説明
`enabled`	true で Recorder 起動時にブラウザ自動化を開始 (default false)
`targetUrl`	ナビゲート先 URL (空で DEFAULT)
`headless`	true でヘッドレス起動 (画面を出さない、default true)
`autoFullWorkflowOnStart`	true で起動時に `fetchSeasonOnly` を 1 回走らせる

取得方式とバックフィルの設定も Recorder が使う時点で毎回読む（Manager で変えると再起動なしで次の実行から効く。spec: settings-ownership-followups）:

key	説明
`battleRecordFetchMode`	`auto`（既定）: 起動時に取り込んだ未保存の試合があれば、全件同期 + シーズン取得を自動で行う（own-writer の Manager の起動時取得と同じ）。`direct`: 起動時には自動で取得しない
`battleRecordBackfill.autoMerge`	全件取得（バックフィル）でログとマージするか（既定 true）。委譲 Manager の「全件取得」は画面の指定（マージ・全シーズン）を `backfill-all-seasons` の args で渡し、そちらが優先
`battleRecordBackfill.autoOnStartup`	true で Recorder 起動時に全件取得を走らせる（Manager の「今後は確認せず自動取得する」が書く。旧 `recorderBrowserAutomation.autoBackfillOnStart` も読む）

全件取得は指定が無ければ直近シーズンのみ。走っている間に重ねて頼まれたら新しくは始めない（委譲 Manager は走っている分の完了を待つ）。

ログイン状態は Playwright の storageState に依存。Viewer で 1 度ログインを完了すると Cookie が <userData>/playwright/storage-state.json に記録され、Recorder もそれを読み込む。

試す手順 (開発時)

1. 前提

Viewer を 1 度起動して Profile を作成しておく必要があります (Profile に紐付いたログディレクトリを Recorder が読むため)。

bash

# 通常起動して、オーバーレイタブのプロファイル設定で Profile を 1 つ作る
corepack yarn dev:electron

Profile を保存したら一旦終了。

2. Recorder mode で起動

bash

corepack yarn dev:electron:recorder

console に以下が出れば成功:

🎙️ [Recorder mode] UI 抑制で起動 — renderer / overlay / BP ウィンドウは作りません
[Recorder] window 作成をスキップ
[Recorder] BPOpponentWindow をスキップ
[TrayService] 初期化しました
🟢 [Recorder] 監視開始: C:\path\to\log\dir
🎙️ [Recorder] 1 個のディレクトリを監視中
📊 [MetricsLogger] uptime=0s | total: 89.3MB / 0.0%CPU | processes=1
📊 [MetricsLogger] 計測開始 (30s 間隔)

ゲームを起動して 1 戦すると:

📝 [Watcher:C:\...\log\dir] (各種ログ行)
🎬 [Watcher:C:\...\log\dir] phase → BP
🎬 [Watcher:C:\...\log\dir] phase → INGAME
🎬 [Watcher:C:\...\log\dir] phase → RESULT
✅ [Recorder] 試合 #1 検出: type=Rank_2v2 my=Win (W2 L2) → DB 保存済み

3. 終了

トレイアイコンを右クリック → 「終了」 (既存の TrayService 経由)。または console で Ctrl+C。

4. 記録の確認

Viewer (yarn dev:electron) で起動 → DB閲覧タブ → Recorder 動作中に保存された試合が見える
直接 SQLite を覗く: userData/matches.db (DB Browser for SQLite 等)

5. 過去のログを再生する（simulator・CLI トリガ）

ゲームを起動せずに、保存済みのログを 1 行ずつ流して試合を起こせる（勝敗の自動加算・4 キャラ反映・DB 保存の確認用）。 Recorder は <userData>/recorder-cli-trigger.txt を 1 秒ごとに読み、1 行目をコマンド、2 行目以降を引数として実行して消す。ログ監視が動いている必要がある（Profile に log_dir があり、そのフォルダが存在すること）。

text

simulator:start
C:\path\to\Log_2025_12_09.txt
20

行	中身
1	`simulator:start`
2	再生するログファイルの絶対パス
3	1 行ごとの間隔 ms（省略可。既定 200。0〜60000）

既定の 200ms/行だと 7 試合入りのログ（約 7300 行）で約 25 分かかる。確認だけなら 10〜20ms で数分になる。小さくしすぎると、試合完了時の DB 保存などより先に次の試合の行が入ることがあるので、結果がおかしいときは間隔を戻す。ほかに simulator:pause / simulator:resume / simulator:nextPhase / simulator:nextMatch / simulator:playAll / simulator:stop（引数なし）。dev:electron:recorder の CLI では p キーで開始でき、間隔は環境変数 RECORDER_SIM_INTERVAL_MS で渡せる。

本番配布の方法

現状 (Phase 0): ビルド時に自動で 2 つの exe が生成される

electron-builder の afterPack フックで WingStats Manager.exe をコピーして WingStats Recorder.exe を作るので、通常のビルドコマンドで 2 つの exe が同時に出力 されます。

bash

yarn build:electron:win
# → release/win-unpacked/
#     ├ WingStats Manager.exe   (Viewer)
#     ├ WingStats Recorder.exe  (Recorder, 自動生成)
#     └ resources/              (両方が共有)

NSIS インストーラ (*.exe Setup) を実行すると、Program Files 配下に 両方の exe が同時にインストール され、両方のショートカットが自動作成 されます (build/installer.nsh で NSIS をカスタマイズ済):

WingStats Manager (スタートメニュー / デスクトップ) → Viewer 起動 (electron-builder 標準)
WingStats Recorder (スタートメニュー / デスクトップ) → Recorder 起動 (build/installer.nsh の customInstall で追加)
アンインストール時はどちらのショートカットも自動削除される

フラグなしでダブルクリックするだけ で recorder mode に入ります (exe 名に "recorder" を含む自動判定)。

💡 ビルド済み win-unpacked から手動で recorder.exe を作りたいときは yarn make-recorder-exe も使える (afterPack を経由しないケース用)。

GitHub Actions

.github/workflows/release.yml が既存の yarn build:electron を呼んでおり、afterPack フックが自動で走るため、タグ push (v*) の release ビルドにも 2 つの exe が含まれる。追加 workflow 変更は不要。

Phase 0 配布の追加選択肢

リネームコピー以外でも recorder mode に入る方法を併用可能:

方法 A: ショートカット

WingStats Manager.exe のショートカットを作成
プロパティ → リンク先末尾に --recorder-mode を追加
```
"C:\...\WingStats Manager.exe" --recorder-mode
```
ショートカット名を「WingStats Recorder」に rename
必要なら「実行」ドロップダウンで「最小化」を選択 (UI 出ないので無関係だが整合性のため)

方法 B: バッチファイル (.bat)

bat

@echo off
chcp 65001 >nul
start "" "C:\...\WingStats Manager.exe" --recorder-mode

このファイルを保存して、ダブルクリックで起動。chcp 65001 で console を UTF-8 にしてから起動するため、デバッグ時に console を覗いても文字化けしない。

方法 C: Steam 起動オプション (auto-launch spec と組合せ)

Steam で星の翼のプロパティ → 起動オプションに以下を貼る:

cmd /c start "" "C:\...\WingStats Manager.exe" --recorder-mode --launched-by-steam & "%COMMAND%"

Steam Play でゲーム起動と同時に Recorder が常駐起動。

将来 (Phase 1+): 別 exe で配布

WingStats Recorder.exe を電子ビルダー別 target として生成予定 (T05-T06)。インストーラのチェックボックスで opt-in 選択可能に (T09)。

トラブルシュート

Q: 起動したが「監視するログディレクトリが見つかりません」

→ Manager でアカウントを 1 つ作って logDir を設定する。Recorder は 5 秒以内に監視を始める（再起動は不要）。

Q: ゲームを起動しても何も検出されない

Profile の logDir が正しいか確認 (Viewer のプロファイル設定で確認可)
ゲームのログが本当にそのディレクトリに書かれているか確認 (watch/tail で確かめる)
console に 📝 [Watcher:...] のログ行が出ているか確認 — 出ていなければファイル監視が走っていない

Q: 文字化け (cp932)

yarn dev:electron:recorder には chcp 65001 が組み込まれているので通常出ない。手動で WingStats Manager.exe --recorder-mode を直接実行した場合は、cmd で先に chcp 65001 を打ってから起動。

Q: 終了の仕方

トレイ右クリック → 終了。console から Ctrl+C でも可。Task Manager で electron.exe を kill しても DB は WAL なので破損しない。

動作確認テスト (将来)

T03 以降で以下を追加予定:

単体テスト: RecorderAutoStart.start() が Profile が無いとき startedCount=0 を返す (mock DB)
integration test: 実 Electron を --recorder-mode で spawn → ログを fixture から流し込み → DB に試合が保存されるか確認
ベンチマーク回帰: PoC で計測した 182 MB から大幅に増えていないこと

Recorder Mode 運用ガイド ​

何ができるか ​

CLI フラグ (一時的な上書き) ​

トレイ右クリックメニューで設定変更 ​

ブラウザ自動化の有効化 (Viewer 経由 / 手動編集) ​

試す手順 (開発時) ​

1. 前提 ​

2. Recorder mode で起動 ​

3. 終了 ​

4. 記録の確認 ​

5. 過去のログを再生する（simulator・CLI トリガ） ​

本番配布の方法 ​

現状 (Phase 0): ビルド時に自動で 2 つの exe が生成される ​

GitHub Actions ​

Phase 0 配布の追加選択肢 ​

方法 A: ショートカット ​

方法 B: バッチファイル (.bat) ​

方法 C: Steam 起動オプション (auto-launch spec と組合せ) ​

将来 (Phase 1+): 別 exe で配布 ​

トラブルシュート ​

Q: 起動したが 「監視するログディレクトリが見つかりません」 ​

Q: ゲームを起動しても何も検出されない ​

Q: 文字化け (cp932) ​

Q: 終了の仕方 ​

動作確認テスト (将来) ​

Recorder Mode 運用ガイド

何ができるか

CLI フラグ (一時的な上書き)

トレイ右クリックメニューで設定変更

ブラウザ自動化の有効化 (Viewer 経由 / 手動編集)

試す手順 (開発時)

1. 前提

2. Recorder mode で起動

3. 終了

4. 記録の確認

5. 過去のログを再生する（simulator・CLI トリガ）

本番配布の方法

現状 (Phase 0): ビルド時に自動で 2 つの exe が生成される

GitHub Actions

Phase 0 配布の追加選択肢

方法 A: ショートカット

方法 B: バッチファイル (.bat)

方法 C: Steam 起動オプション (auto-launch spec と組合せ)

将来 (Phase 1+): 別 exe で配布

トラブルシュート

Q: 起動したが「監視するログディレクトリが見つかりません」

Q: ゲームを起動しても何も検出されない

Q: 文字化け (cp932)

Q: 終了の仕方

動作確認テスト (将来)