perf-optimizer

性能优化器

使用 perf-ci 基础设施和 performance-server 工具，系统地诊断和修复 OneKey 移动应用中的性能问题。

概述

此技能提供了一套结构化的迭代方法，用于：

• 根据现有会话建立性能基线
• 运行受控的性能测量（运行 3 次，取中位数汇总）
• 分析会话数据以找出瓶颈
• 针对性地修改代码
• 根据阈值验证改进效果
• 记录所有更改和结果

关键指标：

• tokensStartMs：Home 代币刷新开始的时间（越低越好）
• tokensSpanMs：Home 代币刷新的持续时间（越低越好）
• 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

每次迭代都在子 Agent 中运行：

步骤 2.1：运行性能测试

性能脚本会自动运行 3 次并汇总结果：

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

输出位置：development/perf-ci/output/<jobId>/

• report.json - 在 agg 字段中包含汇总结果
• detox/runs.json - 包含各次运行的会话 ID

从 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 的瓶颈，这些瓶颈应当：

• 耗时显著
• 可能可以优化
• 位于关键路径中（Home 刷新流程）

步骤 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：

• 记录调查结果并停止

步骤 2.4：进行代码更改

根据分析，每轮进行一项有针对性的更改：

更改类型：

1. 优化：移除冗余工作、缓存结果、减少分配
2. 添加 perfMark：添加标记，以便更好地了解不明确的瓶颈
3. 两者兼有：在同一区域添加标记并进行优化

指南：

• 一次只做一项更改（除非分析证明多项更改必须协同进行）
• 更改要小而聚焦
• 只做安全的更改（绝不破坏功能）
• 清楚地记录更改原因

添加 perfMarks：

使用 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）

如果添加 perfMarks 进行调查：

1. 在疑似瓶颈周围添加标记
2. 使用标记运行一轮性能测试
3. 分析显示标记的新数据
4. 然后进行代码优化
5. 再运行一轮性能测试进行验证

步骤 2.5：记录迭代

在会话文档中更新以下内容：

• 分析：作业 ID、会话 ID、中位数指标，以及 derive-session 的关键发现
• 代码更改：文件、位置、更改类型、描述、原因
• 验证结果：新作业 ID、指标、与上次结果／基线的差异、结论、采取的操作

阶段 3：收尾

步骤 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 .

在会话文档中记录分支名称。

步骤 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. 在子 Agent 中运行每个优化循环，避免上下文膨胀
2. 除非达到 SUCCESS 或 MINOR_IMPROVEMENT，否则绝不提交更改
3. 始终记录失败的尝试——有助于避免重复无效的更改
4. 相信数据——如果指标没有改善，即使更改“理应”有帮助，也要回退
5. 保持耐心——每次性能测试都需要较长时间（构建 + 3 次运行）；仓促行事会导致错误
6. 聚焦关键路径——主屏幕令牌刷新是关键指标
7. 留意权衡——有些优化可能会改善一项指标，却使另一项指标变差