性能优化技能 lift

---

name: lift description: “全面的性能优化，针对延迟、吞吐量、内存/GC和尾部行为。触发线索/关键词：$lift、优化、加速、降低延迟、改进p95/p99、增加吞吐量/QPS、降低CPU或内存、减少分配/GC暂停、分析热路径、基准回归，以及对JSONL/查询密集型代码的性能改进。”

性能提升

意图

提供激进的、测量驱动的性能改进（延迟/吞吐量/内存/GC/尾部），同时保持正确性并防止回归。

双钻石模型适配

性能提升位于定义 -> 交付阶段：

• 定义：编写性能契约并选择验证工作负载。
• 交付：测量基线、分析、运行精细实验，然后通过防护机制交付。

何时使用

• “优化” / “加速” / “慢”
• “降低延迟” / “p95/p99” / “尾部延迟”
• “增加吞吐量” / “QPS”
• “高CPU” / “GC” / “分配” / “内存膨胀”
• “争用” / “锁” / “热路径”

硬性规则

• 每次优化前后进行测量（数字 + 环境 + 命令）。
• 优化瓶颈，而非最响亮的直觉（需要分析/追踪/计数器）。
• 在算法优势耗尽前避免微优化。
• 保持正确性和安全不变性。
• 优化前后需要正确性信号；绝不接受正确性失败的性能提升。
• 未经用户明确批准，不改变语义。
• 在提升资源/成本上限（CPU核心、内存占用、I/O字节、外部调用）前停止并询问，除非明确请求。
• 当投资回报率为负或风险超过收益时停止。

默认策略（非交互式）

目标：在无需发明SLO的情况下保持自主性。

契约推导

如果用户未提供数字目标：

• 将契约定义为：“在<工作负载>上改进<指标>相对于基线；报告差异；不回归<约束>。”
• 不发明SLO数字；将目标视为"在约束内最大化改进"。

指标默认（选择一个）：

• 类似请求：延迟p95（同时报告p50/p99）。
• 批量/离线：吞吐量（同时报告CPU%和内存）。
• 内存问题：峰值RSS + 分配率 / GC暂停（同时报告延迟）。

工作负载选择（验证信号）

选择第一个可运行的、有代表性的工作负载：

1. 用户提供的重现/命令。
2. 现有仓库基准/工具（README、脚本、Makefile/justfile/taskfile）。
3. 围绕热路径的最小工具（微基准）加上正确性信号。

仅在无法找到或创建任何可运行的验证工作负载且存在产品歧义时停止并询问。

实验卫生

• 一次改变一个变量；保持差异小且可逆。
• 拒绝小于噪声底线的提升；当方差高时重新运行。
• 追踪次要回归（内存、尾部延迟、CPU），即使主要指标改进。

工作流程（有主见）

0. 预检
   • 捕获环境（硬件/OS/运行时标志）。
   • 选择一个正确性信号和一个性能工作负载；各运行一次以验证其工作。
1. 性能契约
   • 指标 + 百分位 + 工作负载 + 环境 + 约束。
2. 基线
   • 预热；收集足够样本以获得稳定的百分位（尽可能保留原始样本）。
3. 定位瓶颈
   • 分析/追踪；分类绑定（CPU/内存/I/O/锁/尾部）。
4. 选择最高杠杆的杠杆
   • 遵循优化阶梯：删除工作 -> 算法 -> 数据/布局 -> 并发 -> I/O -> 微架构 -> 运行时/编译器。
5. 运行精细实验（循环）
   • 假设 -> 补丁 -> 测量 -> 接受/拒绝 -> 记录。
6. 通过防护交付
   • 添加/扩展基准、预算或警报；记录权衡。
7. 报告
   • 呈现基线 vs 变体及证据链。

决策关卡

• 如果基线噪声大或不稳定，先修复测量。
• 如果复杂度类主导，先改变算法。
• 如果尾部延迟主导，将方差减少作为主要目标。
• 如果I/O主导，在CPU调优前减少字节、系统调用或往返次数。
• 如果仅剩的提升需要更高的资源/成本上限，提出权衡并询问。
• 当投资回报率为负或风险超过收益时停止。

交付格式（聊天）

输出以下部分（简短，数字优先）：

性能契约

• 指标 + 百分位：
• 工作负载命令：
• 数据集：
• 环境：
• 约束：

基线

• 样本 + 预热：
• 结果（最小值/p50/p95/p99/最大值）：
• 方差/噪声说明（或估计噪声底线）：

瓶颈证据

• 工具 + 关键发现：
• 热路径 / 争用点：
• 绑定分类：

实验

• <1-3个条目> 假设 -> 更改 -> 测量差异 -> 决策

结果

• 变体结果（最小值/p50/p95/p99/最大值）：
• 相对于基线的差异：
• 置信度（噪声/方差）：
• 权衡 / 已检查的回归：

回归防护

• 添加的基准/预算：
• 阈值（如有）：

验证

• 正确性命令 -> 通过/失败
• 性能命令 -> 数字

残留风险 / 后续步骤

• <要点列表>

核心参考（按需加载）

• 阅读 references/playbook.md 以获取主要流程和优化阶梯。
• 阅读 references/measurement.md 以了解基准测试和统计严谨性。
• 阅读 references/algorithms-and-data-structures.md 以获取算法杠杆。
• 阅读 references/systems-and-architecture.md 以获取CPU、内存和操作系统战术。
• 阅读 references/latency-throughput-tail.md 以了解排队和尾部行为。
• 阅读 references/optimization-tactics.md 以获取按层次划分的战术目录。
• 阅读 references/checklists.md 以获取快速分类和验证清单。
• 阅读 references/anti-patterns.md 以避免常见陷阱。

脚本

• 优先使用这种brew感知的启动器模式用于性能提升CLI：

CODEX_SKILLS_HOME="${CODEX_HOME:-$HOME/.codex}"
CLAUDE_SKILLS_HOME="${CLAUDE_HOME:-$HOME/.claude}"
LIFT_SCRIPTS_DIR="$CODEX_SKILLS_HOME/skills/lift/scripts"
[ -d "$LIFT_SCRIPTS_DIR" ] || LIFT_SCRIPTS_DIR="$CLAUDE_SKILLS_HOME/skills/lift/scripts"

run_lift_tool() {
  local subcommand="${1:-}"
  if [ -z "$subcommand" ]; then
    echo "usage: run_lift_tool <bench-stats|perf-report> [args...]" >&2
    return 2
  fi
  shift || true

  local bin=""
  local marker=""
  local fallback=""
  case "$subcommand" in
    bench-stats)
      bin="bench_stats"
      marker="bench_stats.zig"
      fallback="$LIFT_SCRIPTS_DIR/bench_stats.py"
      ;;
    perf-report)
      bin="perf_report"
      marker="perf_report.zig"
      fallback="$LIFT_SCRIPTS_DIR/perf_report.py"
      ;;
    *)
      echo "unknown lift subcommand: $subcommand" >&2
      return 2
      ;;
  esac

  if command -v "$bin" >/dev/null 2>&1 && "$bin" --help 2>&1 | grep -q "$marker"; then
    "$bin" "$@"
    return
  fi
  if [ "$(uname -s)" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
    if ! brew install tkersey/tap/lift; then
      echo "brew install tkersey/tap/lift failed; refusing silent fallback." >&2
      return 1
    fi
    if command -v "$bin" >/dev/null 2>&1 && "$bin" --help 2>&1 | grep -q "$marker"; then
      "$bin" "$@"
      return
    fi
    echo "brew install tkersey/tap/lift did not produce a compatible $bin binary." >&2
    return 1
  fi
  if [ -f "$fallback" ]; then
    uv run python "$fallback" "$@"
    return
  fi
  echo "lift binary missing and fallback script not found: $fallback" >&2
  return 1
}

run_lift_tool bench-stats --input samples.txt --unit ms
run_lift_tool perf-report --title "Perf pass" --owner "team" --system "service" --output /tmp/perf-report.md

• 等效的仅回退命令仍然有效：
  • uv run python scripts/perf_report.py --title "Perf pass" --owner "team" --system "service" --output /tmp/perf-report.md
  • uv run python scripts/bench_stats.py --input samples.txt --unit ms

资产

• 使用 assets/perf-report-template.md 作为随时可编辑的报告。
• 使用 assets/experiment-log-template.md 以追踪实验和结果。

输出期望

• 交付基线、瓶颈证据、假设、实验计划和测量结果。
• 提供保持正确性并包含回归防护的最小差异。
• 用通俗语言解释权衡并记录测量的差异。