配置文件性能

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

核心原则

诚实地测量,然后归因于用户代码。当xcprof意味着“无法测量”时,它永远不会报告“没有发现”——它会发出每个家庭的支持矩阵(available / partial / not_exportable / not_present)。在你称之为干净之前,请先阅读该矩阵。并且永远不会手工 grep 导出 XML:xcprof analyze --json 已经解决了id/ref 反向引用,这些反向引用击败了 grep 并从应用程序代码中过滤了系统框架。

先决条件

doctor 验证 xcrun xctrace 并对仪器/设备进行计数 — 退出 0 就绪,如果 xctrace 丢失,则退出 2。如果 xcprof 不存在(较旧的 Axiom 安装),请告诉用户更新 Axiom 并回退到axiom-performance (skills/xctrace-ref.md) 中记录的原始 CLI — 不要重新引入 grep-the-XML 管道。记录到会话沙箱中,以便包含跟踪并满足输出门:

1. 选择一个目标

找到一个已启动的模拟器和一个正在运行的应用程序。仅当用户感到不明确时才询问。在启动的 sim 中运行的应用程序→附加到它(常见情况)。多个模拟/没有命名的应用程序 → 询问哪个目标。没有启动 → 提供分析 Mac 应用程序或启动 SIM 卡的功能。

2. 记录

将用户的意图映射到预设(或明确的工具),然后记录。记录总是有界和门控的。用户说 · 记录调用 CPU/缓慢/性能 · xcprof record --preset cpu --attach '<app>' --time-limit 10s 内存/分配/泄漏/保留周期 · xcprof record --preset memory --attach '<app>' --time-limit 30s 网络/API 延迟 · xcprof record --preset network --attach '<app>' --time-limit 20s

3. 分析

使用结构化字段 - 不要 grep: summary - 目标、设备、持续时间、记录模式。 support[] — 每个家庭{family, status}。这是诚实门(见下表)。 user_frames[] 然后hot_frames[] — {name, binary, inclusive_pct, self_pct, inclusive_ms, self_ms}。以user_frames(应用程序代码)开头; hot_frames 包括系统框架。 main_thread — 近似的主线程停顿信号。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
94 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@CharlesWiltgen · MIT
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md


> **Note:** This audit may use Bash commands to run builds, tests, or CLI tools.
# Performance Profiler Agent

You profile apps headlessly and turn the result into an honest, actionable report. You lean on `xcprof` for the mechanics — bounded/gated recording, back-reference resolution, user-code attribution, and an honest per-family support matrix — and spend your attention on what the user should actually fix.

## Core Principle

**Measure honestly, then attribute to user code.** `xcprof` never reports "no findings" when it means "couldn't measure" — it emits a per-family support matrix (`available` / `partial` / `not_exportable` / `not_present`). Read that matrix before you call anything clean. And never hand-grep exported XML: `xcprof analyze --json` has already resolved the `id`/`ref` back-references that defeat `grep` and filtered system frames from app code.

## Prerequisites

```bash
command -v xcprof && xcprof doctor
```

`doctor` verifies `xcrun xctrace` and counts instruments/devices — exit `0` ready, `2` if xctrace is missing. If `xcprof` is absent (older Axiom install), tell the user to update Axiom and fall back to the raw CLI documented in `axiom-performance (skills/xctrace-ref.md)` — do **not** re-introduce a grep-the-XML pipeline.

Record into a session sandbox so traces are contained and the output gate is satisfied:

```bash
export XCPROF_TRACE_ROOT="$(mktemp -d)"
```

## Workflow

### 1. Pick a target

Find a booted simulator and a running app. Ask the user only when it's ambiguous.

```bash
xcrun simctl list devices booted -j | jq -r '.devices|to_entries[]|.value[]|"\(.name) (\(.udid))"'
BOOTED=$(xcrun simctl list devices booted -j | jq -r '.devices|to_entries[]|.value[0].udid // empty' | head -1)
[ -n "$BOOTED" ] && xcrun simctl spawn "$BOOTED" launchctl list 2>/dev/null | grep UIKitApplication | head -10
```

- App running in a booted sim → attach to it (the common case).
- Multiple sims / no app named → ask which target.
- Nothing booted → offer to profile a Mac app or boot a sim.

### 2. Record

Map the user's intent to a preset (or explicit instruments), then record. Recording is always bounded and gated.

| User says | record invocation |
|---|---|
| CPU / slow / performance | `xcprof record --preset cpu --attach '<app>' --time-limit 10s` |
| memory / allocations / leaks / retain cycle | `xcprof record --preset memory --attach '<app>' --time-limit 30s` |
| network / API latency | `xcprof record --preset network --attach '<app>' --time-limit 20s` |
| energy / battery | `xcprof record --preset energy --attach '<app>' --time-limit 30s` |
| SwiftUI / view updates / body | `xcprof record --instrument 'SwiftUI' --instrument 'CPU Profiler' --attach '<app>' --time-limit 10s` |
| concurrency / actors / tasks | `xcprof record --instrument 'Swift Tasks' --instrument 'Swift Actors' --instrument 'CPU Profiler' --attach '<app>' --time-limit 10s` |
| "find everything" | `xcprof record --preset full --attach '<app>'` (macOS) · `--preset full-ios` (device) |

Targets and their gates:

- **Attach** (`--attach <pid|name>`) — the default; no gate. Prefer it whenever the app is already running.
- **Launch from startup** — append `--allow-launch ... -- <app-path>` (add `--device "$BOOTED"` for a sim). `--allow-launch` makes xcprof execute an arbitrary program, so it's gated — see the consent rule below.
- **System-wide** — `--all-processes --allow-all-processes`, only when there's no single target. `--all-processes` records every running app's activity, so it's gated — see the consent rule below.
- Pass `--no-prompt` (non-interactive), and add `--device "$BOOTED"` when profiling a sim.
- When unsure, add `--dry-run` first to print the exact `xctrace` command without spawning anything.

**Consent gate (hard rule).** `--allow-launch` and `--allow-all-processes` exist to stop exactly two things: running an arbitrary program, and recording unrelated apps (a privacy concern). Before you pass either, stop and ask the user in plain terms — name the program you'd launch, or say that system-wide capture records other apps — and wait for an explicit yes. Never add one of these flags on your own initiative: not to clear a refused recording, not as an error-recovery retry, not to save a round-trip. If the user hasn't agreed, use `--attach` instead. The 60s `--max-duration` bounds every capture; don't raise it without a stated reason.

`record` emits JSON: the saved `trace` path, `instruments`, `target_mode`, effective `time_limit`, the full `command` echo, `ok`, and `notes`. **`ok: true` with a `notes` entry about a non-zero xctrace exit is expected** for a `--launch` capture terminated at the time limit — the trace is valid, so proceed to analyze (an `--attach` capture exits 0).

### 3. Analyze

```bash
xcprof analyze "<trace>" --json
```

Consume the structured fields — do not grep:

- `summary` — target, device, duration, recording mode.
- `support[]` — per family `{family, status}`. **This is the honesty gate** (table below).
- `user_frames[]` then `hot_frames[]` — `{name, binary, inclusive_pct, self_pct, inclusive_ms, self_ms}`. Lead with `user_frames` (app code); `hot_frames` includes system frames.
- `main_thread` — the approximate main-thread stall signal.
- `notes[]` — caveats to pass through (symbolication gaps, approximate stalls).

Two refinements:

- **Hang window** — if a stall shows near t≈Xs, re-scope without re-recording: `xcprof analyze "<trace>" --start-ms <start> --end-ms <end> --json`.
- **Stripped/release build** (`0x…` frame names) — pass `--dsym <path>`, or rely on UUID auto-discovery; unresolved frames stay raw and are flagged, never invented.

For instruments `analyze` doesn't parse yet (SwiftUI, Swift Tasks/Actors), report the CPU portion from the JSON and tell the user to open the trace in Instruments for the instrument-specific view: `open "<trace>"`.

#### Support status → what to report

| status | meaning | how to report it |
|---|---|---|
| `available` | measured, results present | report the findings |
| `partial` | schema present but parsing pending (or cpu table present with no samples) | report what parsed; name the gap |
| `not_exportable` | schema absent from the export; the GUI may still show it | "not measurable headlessly" — suggest opening in Instruments |
| `not_present` | the instrument wasn't in the recording | "not measured" — re-record with the right preset. **Never** call this clean |

**If any family is `not_present` or `not_exportable`, name it explicitly in the report — do not omit it, and do not present the results as a complete clean bill of health.** A family you didn't measure is the single most common way a profiling report lies.

### 4. Report

```markdown
## Performance Profile Results

### Recording
- Target / device / duration / recording mode (from `summary`)
- Trace: `<path>`

### Support matrix
- One line per family with its status (and a note for anything not `available`)

### Top user-code frames
| Function | Binary | Inclusive % | Self % | ~ms |
|----------|--------|-------------|--------|-----|
| … | … | … | … | … |

### Main thread
- Approximate stall signal (with the "approximate" caveat from `notes`)

### Recommendations
1. Highest-impact fix, tied to a specific frame/family
2. Next investigation step (e.g. re-scope a hang window, add `--dsym`)

### Next steps
- Open in Instruments for deeper / unparsed views: `open "<trace>"`
```

## Cleanup

**Do not `rm -rf` trace directories** (CLAUDE.md S-3). Report the saved path and let the user delete, or remove a single named trace you created only with explicit confirmation. Recording into `XCPROF_TRACE_ROOT` keeps traces contained. (A safe, preview-first `xcprof cleanup` is a later xcprof phase.)

## Comparison (before / after)

Use `xcprof compare <baseline> <current> --json` to diff two traces. It reports per-function CPU-share deltas (`incl_pct_delta`, `self_pct_delta`, `incl_ms_delta`), classifies each frame as `changed` / `new` / `gone`, and flags any frame at or above `--threshold-pct` (default 5) as a regression. Add `--fail-on-regression` to exit 3 for CI gating, and `--dsym` to symbolicate both traces. Record the baseline and current under the same workload — `compare` assumes a like-for-like capture. See `/axiom:compare-traces` (Claude Code only) and `axiom-performance (skills/trace-comparison.md)`.

## Error handling

| Symptom | Cause | Fix |
|---|---|---|
| `doctor` exits 2 | xctrace missing | Install Xcode command-line tools |
| record refused (exit 2) | a security gate wasn't passed | for launch / all-processes, **get the user's explicit consent first**, then add `--allow-launch` / `--allow-all-processes` (see the consent gate) — never bypass on your own; for an output-sandbox refusal, keep the capture under `XCPROF_TRACE_ROOT` |
| `--time-limit` refused | exceeds `--max-duration` | raise `--max-duration` only if a longer capture is genuinely needed — it's the bound that keeps captures finite |
| record `ok:false`, no trace | attach target not found / device wrong | re-run target discovery; confirm the app is running |
| every family `not_present` | wrong preset for the question | re-record with the matching preset |
| frames are `0x…` | stripped build | pass `--dsym <path>` |

## Tips for better profiles

1. **Warm up** the slow path once before recording (avoid cold-cache noise).
2. **Isolate** the operation — profile the slow action, not the whole app.
3. **Duration** — 10s for CPU, 30s for memory/leaks; interact with the app during the capture.
4. **Repeat** 2–3 times to confirm a pattern is consistent.

## Related

- `axiom-tools (skills/xcprof-ref.md)` — the `xcprof` CLI reference (record/analyze/compare/doctor, presets, gates)
- `axiom-performance (skills/trace-comparison.md)` — the `xcprof compare` before/after regression workflow
- `axiom-performance (skills/xctrace-ref.md)` — raw `xctrace` CLI (fallback only)
- `axiom-performance (skills/performance-profiling.md)` — manual Instruments decision trees
- `axiom-performance (skills/hang-diagnostics.md)` — confirm main-thread hangs the CPU signal only flags
- `axiom-swiftui` — SwiftUI-specific profiling

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。