perf-optimizer

パフォーマンスオプティマイザー

perf-ci インフラストラクチャと performance-server ツールを使用して、OneKey モバイルアプリのパフォーマンス問題を診断し、修正するための体系的なワークフローです。

概要

このスキルでは、次の作業を行うための構造化された反復的なアプローチを提供します。

• 既存のセッションからパフォーマンスのベースラインを確立する
• 制御された perf 測定を実行する（3 回実行し、中央値を集計）
• セッションデータを分析してボトルネックを特定する
• 対象を絞ったコード変更を行う
• しきい値に照らして改善を検証する
• すべての変更と結果を記録する

主な指標：

• tokensStartMs：ホームのトークン更新が開始する時刻（短いほど良好）
• tokensSpanMs：ホームのトークン更新にかかる時間（短いほど良好）
• functionCallCount：セッション中の関数呼び出し総数（少ないほど良好）

成功基準：

• ✅ SUCCESS：時間の指標が 10％以上改善
• 🌟 MINOR_IMPROVEMENT：時間は変わらないが、関数呼び出しが 20％以上減少（安全で、小規模な変更）
• ❌ NO_IMPROVEMENT：どちらのしきい値も満たさない → 変更を元に戻す

ワークフロー

フェーズ 1：セットアップとベースライン

ステップ 1.1：ベースラインセッションを選択する

ベースラインセッションを選ぶようユーザーに依頼するか、選択を支援します。

# List recent sessions with key metrics
cat ~/perf-sessions/sessions.overview.jsonl | \
  jq -r '[.sessionId, .createdAt, .marks["Home:refresh:done:tokens"]] | @tsv' | \
  tail -20

ユーザーは次のいずれかを指定できます。

• 既知の良好なセッション（リグレッションの修正用）
• 最近のセッション（改善作業用）
• 代表的なセッションをこちらで選択する

ステップ 1.2：ベースラインを分析する

セッションからベースラインの指標を抽出します。

# Get detailed analysis
node development/performance-server/cli/derive-session.js <baseline-sessionId> \
  --pretty \
  --output /tmp/perf-baseline-derived.json

~/perf-sessions/<sessionId>/mark.log からベースライン指標を読み込みます。

# Extract tokensStartMs (timestamp of Home:refresh:start:tokens)
grep "Home:refresh:start:tokens" ~/perf-sessions/<sessionId>/mark.log | jq '.timestamp'

# Extract tokensSpanMs (done - start)
grep "Home:refresh:done:tokens" ~/perf-sessions/<sessionId>/mark.log | jq '.timestamp'

# Count function calls
wc -l < ~/perf-sessions/<sessionId>/function_call.log

比較用のベースライン指標 JSON を作成します。

echo '{"tokensStartMs": <start>, "tokensSpanMs": <span>, "functionCallCount": <count>}' > /tmp/baseline-metrics.json

ステップ 1.3：ドキュメントを初期化する

references/template.md のテンプレートを使用して、development/output/perf-optimization-<timestamp>.md にセッションドキュメントを作成します。次の項目を記入します。

• 現在の日付と時刻
• ベースラインセッション ID
• ベースライン指標
• 現在のブランチ名
• 目標（リグレッションの修正または改善）

フェーズ 2：反復的な最適化ループ

最大反復回数：10

各反復では、サブエージェント内で次の作業を実行します。

ステップ 2.1：パフォーマンステストを実行する

perf スクリプトは自動で 3 回実行し、結果を集計します。

node development/perf-ci/run-ios-perf-detox-release.js

出力先：development/perf-ci/output/<jobId>/

• report.json - agg フィールドに集計結果が含まれます
• detox/runs.json - 個々の実行の sessionId が含まれます

report.json から現在の指標を抽出します。

# Read aggregated metrics directly
cat development/perf-ci/output/<jobId>/report.json | jq '{
  tokensStartMs: .agg.tokensStartMs,
  tokensSpanMs: .agg.tokensSpanMs,
  functionCallCount: .agg.functionCallCount
}' > /tmp/current-metrics.json

ステップ 2.2：現在のパフォーマンスを分析する

より詳細な分析を行うには、個々のセッションに対して derive-session を実行します。

# Get sessionIds from the run
SESSIONS=$(cat development/perf-ci/output/<jobId>/detox/runs.json | jq -r '.runs[].sessionId')

# Analyze each session
for sid in $SESSIONS; do
  node development/performance-server/cli/derive-session.js $sid \
    --pretty \
    --output /tmp/perf-derived-$sid.json
done

派生出力の次のセクションを重点的に確認します。

• slowFunctions：累積時間が最も長い関数
• homeRefreshTokens：重要な更新時間内で時間を消費している処理
• jsblock：遅延の原因となるメインスレッドのブロック
• repeatedCalls：過剰な処理や再レンダリングのパターン
• keyMarks：重要なマイルストーンのタイミング

次の条件を満たす、上位 1～3 件のボトルネックを特定します。

• 大きな時間を消費している
• 最適化できる可能性がある
• クリティカルパス（ホームの更新フロー）内にある

ステップ 2.3：対応を決定する

現在の指標をベースラインと比較します。

# Quick comparison
cat /tmp/baseline-metrics.json
cat /tmp/current-metrics.json

# Calculate deltas manually or use script in skill directory

判断フロー：

現在の指標がベースラインより改善している場合：

• ✅ SUCCESS（時間が 10％以上改善）→ 停止し、成功を記録する
• 🌟 MINOR_IMPROVEMENT（関数呼び出しが 20％以上減少し、時間は安定）→ ブランチを作成し、コミットしてメインブランチに戻り、続行する

まだ改善が見られない場合：

• ステップ 2.4 に進み、変更を行う

反復回数が 10 回に達した場合：

• 結果を記録して停止する

Step 2.4: コードを変更する

分析に基づき、反復ごとに対象を絞った変更を1つ行います。

変更の種類：

1. 最適化：冗長な処理を削除し、結果をキャッシュし、割り当てを削減します
2. perfMark の追加：不明瞭なボトルネックをより適切に把握するためにマークを追加します
3. 両方：同じ領域にマークを追加し、最適化します

ガイドライン：

• 一度に1つ変更します（分析によって複数の変更が連携して機能する必要があると判明した場合を除きます）
• 変更は小さく、対象を絞ります
• 安全な変更のみ行います（機能を壊さないでください）
• 変更の理由を明確に記録します

perfMark の追加：

packages/shared/src/performance/ にあるパフォーマンスユーティリティを使用します。

import { perfMark } from '@onekeyhq/shared/src/performance/perfMark';

// Add mark at a specific point
perfMark('MyComponent:operation:start');
// ... operation ...
perfMark('MyComponent:operation:done');

命名規則：<Component>:<action>:<phase>（例：Home:refresh:start:tokens）

調査のために perfMark を追加する場合：

1. ボトルネックと思われる箇所の前後にマークを追加します
2. マークを付けてパフォーマンスサイクルを1回実行します
3. マークを表示して新しいデータを分析します
4. その後、コードを最適化します
5. もう一度パフォーマンスサイクルを実行して検証します

Step 2.5: 反復を記録する

セッションドキュメントを更新し、以下を記載します。

• 分析：ジョブ ID、セッション ID、中央値のメトリクス、derive-session から得られた主な知見
• コード変更：ファイル、場所、変更の種類、説明、理由
• 検証結果：新しいジョブ ID、メトリクス、前回／ベースラインとの差分、判定、実施した対応

Phase 3: 最終処理

Step 3.1: MINOR_IMPROVEMENT ブランチを処理する

いずれかの反復で MINOR_IMPROVEMENT になった場合：

git checkout -b perf/minor-<description>
git add <changed-files>
git commit -m "perf: <description>

Reduces function call count by X% while maintaining time metrics.

Reason: <brief explanation>
"
git checkout <original-branch>
git restore .

ブランチ名をセッションドキュメントに記録します。

Step 3.2: ドキュメントを完成させる

Summary セクションに以下を記入します。

• 実行した反復の合計数
• 最終結果（改善率を含む SUCCESS、または調査を継続中）
• 効果のあった変更の一覧
• 効果のなかった変更とその理由の一覧
• 作成したブランチの一覧
• 未完了の場合は次のステップ

主なファイルとパス

パフォーマンス基盤：

• development/perf-ci/run-ios-perf-detox-release.js - メインのパフォーマンスランナー
• development/perf-ci/output/<jobId>/ - ジョブ出力ディレクトリ
• development/performance-server/cli/derive-session.js - セッションアナライザー
• ~/perf-sessions/ - セッションデータの保存場所（デフォルト）
• ~/perf-sessions/sessions.overview.jsonl - セッションインデックス

しきい値：

• development/perf-ci/thresholds/ios.release.json - リリースモードのしきい値

パフォーマンスユーティリティ：

• packages/shared/src/performance/perfMark.ts - パフォーマンスマーク用ユーティリティ

参考資料

• references/template.md：セッションドキュメントのテンプレート
• references/perf_tool_guide.md：derive-session と分析ツールの詳細なガイド

重要な注意事項

1. コンテキストの肥大化を避けるため、最適化ループはそれぞれサブエージェントで実行します
2. SUCCESS または MINOR_IMPROVEMENT にならない限り、変更をコミットしないでください
3. 失敗した試みも必ず記録してください。効果のない変更を繰り返さずに済みます
4. データを信頼してください。メトリクスが改善しない場合は、変更が「役立つはず」だと思えても元に戻します
5. 焦らず進めてください。各パフォーマンス実行にはかなりの時間がかかります（ビルド＋3回の実行）。急ぐとミスにつながります
6. クリティカルパスに集中してください。Home 画面のトークン更新が重要なメトリクスです
7. トレードオフに注意してください。最適化によって、あるメトリクスが改善する一方で、別のメトリクスが悪化することがあります