[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83808":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":9,"totalLinesOfCode":9,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":9,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":9,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":9,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":25,"discoverSource":26},83808,"SmartPerfetto","Gracker\u002FSmartPerfetto","Gracker","use ai analysis Performance issue with perfetto",null,"https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto","JavaScript",508,91,3,2,0,15,17,45,9.89,false,"main","2026-06-12 02:04:35","# SmartPerfetto\n\n[English](README.md) | [中文](README.zh-CN.md)\n\n[![License: AGPL-3.0-or-later](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FGracker\u002FSmartPerfetto)](LICENSE)\n[![Backend Regression Gate](https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto\u002Factions\u002Fworkflows\u002Fbackend-agent-regression-gate.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto\u002Factions\u002Fworkflows\u002Fbackend-agent-regression-gate.yml)\n[![Node.js 24 LTS](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode.js-24%20LTS-brightgreen)](package.json)\n[![TypeScript strict](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-strict-3178c6)](backend\u002Ftsconfig.json)\n[![Docker Compose](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocker-Compose-2496ed)](docker-compose.yml)\n[![Perfetto UI fork](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPerfetto-UI%20fork-4285f4)](https:\u002F\u002Fperfetto.dev\u002F)\n[![Sponsor](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSponsor-WeChat%20553000664-f66f6f)](docs\u002Fsponsor.en.md)\n\n> AI-powered Android performance analysis built on [Perfetto](https:\u002F\u002Fperfetto.dev\u002F).\n\nSmartPerfetto adds an AI analysis layer on top of Perfetto traces. Load a trace, ask a natural-language question, and get an evidence-backed answer with SQL results, skill outputs, root-cause reasoning, and optimization suggestions.\n\nConfigure a provider before running AI analysis. This README keeps the startup flow and one provider configuration example only; the complete provider\u002Fmodel list lives in [docs\u002Fgetting-started\u002Fconfiguration.en.md](docs\u002Fgetting-started\u002Fconfiguration.en.md), [backend\u002F.env.example](backend\u002F.env.example), and the root [.env.example](.env.example).\n\nProvider Base URL notice: the prefilled Claude\u002FAnthropic-compatible and OpenAI-compatible Base URLs are based on public provider information. They are not guaranteed to be correct for every account, region, plan, or future provider change. If a preset fails, verify the Base URL, model ID, and protocol in your provider console first; then open an issue or PR if the public preset should be updated.\n\nThe project is open source and in active development. The UI, backend runtime, and skill system are usable today, but public APIs and internal contracts may still change.\n\n## Configure Your AI Provider First\n\nSmartPerfetto uses exactly one active model-provider source at runtime. Pick one path and avoid mixing them during first setup:\n\n- You do not need to configure Claude Code, OpenAI Agents SDK, Pi Agent Core, and OpenCode all at once. Claude Code is the local-auth \u002F Claude-compatible runtime path; OpenAI Agents SDK is the OpenAI \u002F OpenAI-compatible runtime path; Pi Agent Core and OpenCode are custom-provider runtime paths. Pick one for first setup.\n- UI Provider Manager: easiest for portable packages, Docker, and new users. Start SmartPerfetto, open **AI Assistant Settings → Providers**, add a provider, paste the **Provider API Key**, verify the Base URL\u002Fruntime, save it, test it, then activate it. Saving a provider is not enough; the active provider is what takes effect.\n- Env file: best for scripted or server deployments. Local source runs read `backend\u002F.env`; Docker reads the repository-root `.env`.\n- Local Claude Code config: best for source runs when `claude` already works in the same terminal. No SmartPerfetto `.env` is required.\n\nThe `Connection` tab normally only needs the backend URL. Its advanced backend auth token is optional and is only used when the backend was started with `SMARTPERFETTO_API_KEY`; it is not a model-provider key field. An active Provider Manager profile overrides `.env`; choose `System Default` in the provider switcher or deactivate providers to return to `.env` \u002F local Claude Code config. See [docs\u002Fgetting-started\u002Fconfiguration.en.md](docs\u002Fgetting-started\u002Fconfiguration.en.md) for the full provider guide.\n\nStep 1: Choose your run mode and credential file.\n\n| Run mode | Credential file | Notes |\n|----------|-----------------|-------|\n| Local source checkout where Claude Code already works in the same terminal | No `.env` required | Verify with `claude`; then run `.\u002Fstart.sh`, which starts both backend and the pre-built frontend |\n| Local source checkout with explicit API key or compatible proxy | `backend\u002F.env` | Create it with `cp backend\u002F.env.example backend\u002F.env` |\n| Docker Hub image | Provider Manager UI or repository-root `.env` | Docker cannot see the host Claude Code login; use `.env` only for scripted setup |\n| Source Docker build | Provider Manager UI or repository-root `.env` | `docker-compose.yml` reads root `.env`; same credential file as the Docker Hub path |\n| Portable package | Provider Manager UI first | Use the package UI at `http:\u002F\u002Flocalhost:10000`; only use the package env file if you need scripted setup |\n\nStep 2: Choose the runtime and provider settings. Claude Agent SDK is for Claude Code \u002F Anthropic-compatible providers; OpenAI Agents SDK is for OpenAI \u002F OpenAI-compatible providers. Pi Agent Core and OpenCode are optional custom-provider runtimes that reuse the same SmartPerfetto analysis contract. For first setup, keep only one credential family enabled. In advanced deployments where multiple credential families are present, `SMARTPERFETTO_AGENT_RUNTIME` or the active UI provider decides; otherwise the default is Claude Agent SDK.\n\nFor direct Anthropic API access, set:\n\n```env\nANTHROPIC_API_KEY=sk-ant-your-key\n```\n\nFor providers that expose Claude Code \u002F Anthropic-compatible endpoints, uncomment the provider block in [backend\u002F.env.example](backend\u002F.env.example), replace the API key\u002Ftoken, and keep `CLAUDE_MODEL` \u002F `CLAUDE_LIGHT_MODEL` as the SmartPerfetto model fields. Example for DeepSeek:\n\n```env\nANTHROPIC_BASE_URL=https:\u002F\u002Fapi.deepseek.com\u002Fanthropic\nANTHROPIC_AUTH_TOKEN=sk-your-deepseek-key\nCLAUDE_MODEL=deepseek-v4-pro\nCLAUDE_LIGHT_MODEL=deepseek-v4-flash\n```\n\nOpenAI \u002F OpenAI-compatible providers use the OpenAI Agents SDK runtime; Ollama and other OpenAI-compatible endpoints use `OPENAI_AGENTS_PROTOCOL=chat_completions`. In Provider Manager, dual-surface providers such as DeepSeek, Qwen, Kimi, MiMo, and TokenHub show both Claude-compatible and OpenAI-compatible Base URLs. The selected SDK runtime decides which side is used. Pi Agent Core and OpenCode are exposed only through custom providers or explicit env configuration; neither path reads local `.pi` \u002F OpenCode project config or CLI login state. Full provider-specific fields, known regional URL variants, model IDs, and troubleshooting notes are in [docs\u002Fgetting-started\u002Fconfiguration.en.md](docs\u002Fgetting-started\u002Fconfiguration.en.md) and the env templates.\n\nStep 3 (optional): Set the output language. SmartPerfetto defaults to Simplified Chinese for AI answers, streamed progress, and generated reports. Set this if the primary users prefer English:\n\n```env\nSMARTPERFETTO_OUTPUT_LANGUAGE=en\n```\n\nStep 4: Start or restart services. For Docker, run `docker compose -f docker-compose.hub.yml up -d` or `docker compose -f docker-compose.hub.yml restart`. For local source runs, use `.\u002Fstart.sh`; if you only changed `.env` while the backend is already running, use `.\u002Fscripts\u002Frestart-backend.sh`. Verify the active source with [http:\u002F\u002Flocalhost:3000\u002Fhealth](http:\u002F\u002Flocalhost:3000\u002Fhealth): `aiEngine.credentialSource=provider-manager` means the UI provider overrides env, while `env-or-default` means SmartPerfetto is using `.env` or local Claude Code fallback. For the local Claude Code path, verify by running a normal `claude` request in the same terminal.\n\n## Perfetto Resources\n\n| Resource | English | Chinese |\n|----------|---------|---------|\n| Android Performance Blog | [androidperformance.com\u002Fen](https:\u002F\u002Fwww.androidperformance.com\u002Fen) | [androidperformance.com](https:\u002F\u002Fwww.androidperformance.com\u002F) |\n| Perfetto official docs | [perfetto.dev\u002Fdocs](https:\u002F\u002Fperfetto.dev\u002Fdocs\u002F) | [gugu-perf.github.io\u002Fperfetto-docs-zh-cn](https:\u002F\u002Fgugu-perf.github.io\u002Fperfetto-docs-zh-cn\u002F) |\n\n## What It Does\n\n- Analyzes Android Perfetto traces for scrolling jank, startup, ANR, interaction latency, memory, game, and rendering-pipeline issues.\n- Keeps Perfetto's timeline and SQL power, then adds an AI assistant panel inside the Perfetto UI.\n- Reconstructs mixed-action traces in Smart mode before deep analysis, so users can inspect the scene timeline and choose all scenes or only startup, scrolling, click, navigation, device-state, or ANR ranges.\n- Compares completed analysis results across multiple traces, windows, or workspace users without requiring both Perfetto UI windows to stay open.\n- Uses a TypeScript backend to run agent workflows, query `trace_processor_shell`, invoke YAML analysis skills, and stream results to the browser.\n- Supports Anthropic directly, Claude\u002FAnthropic-compatible providers, OpenAI\u002FOpenAI-compatible providers, Pi Agent Core custom models, and OpenCode custom models through the matching backend runtime.\n- Ships with registry-discovered YAML skill\u002Fconfig files and scene strategies for Android performance investigation.\n\n## Feature Overview\n\n- [Feature Overview](docs\u002Fgetting-started\u002Ffeatures.en.md): AI Assistant workflows, Smart scene inventory and selected deep dives, performance scenarios, selection-aware analysis, reports, live trace comparison, multi-trace result comparison, code-aware local-source analysis, provider management, API\u002FCLI automation, and runtime options.\n\n## Tech Stack\n\n| Area | Technology |\n|------|------------|\n| Frontend | Forked Perfetto UI with the `com.smartperfetto.AIAssistant` plugin |\n| Backend | Node.js 24 LTS, TypeScript strict mode, Express |\n| Agent runtime | Runtime selector, Claude Agent SDK, OpenAI Agents SDK, Pi Agent Core, OpenCode, MCP tools, scene strategies, verifier, SSE streaming |\n| Trace engine | Perfetto `trace_processor_shell` over HTTP RPC |\n| Analysis logic | YAML skills under `backend\u002Fskills\u002F` plus Markdown strategies under `backend\u002Fstrategies\u002F` |\n| Storage | Local uploads, session logs, reports, and runtime learning files |\n| Testing | Jest, skill validation, strategy validation, 6-trace scene regression gate |\n| Deployment | Docker Compose, GitHub portable packages, npm CLI package, or local scripts |\n\n## Public Release Channels\n\n| Channel | Install \u002F run | Node requirement | Includes |\n|---------|---------------|------------------|----------|\n| Docker Hub | `docker compose -f docker-compose.hub.yml up -d` | No host Node.js required | Backend, committed pre-built UI, pinned `trace_processor_shell` |\n| GitHub portable | Download `smartperfetto-v\u003Cversion>-*.zip` \u002F `.tar.gz` | Bundled Node.js 24 | Launcher, backend, pre-built UI, native dependencies, pinned `trace_processor_shell` |\n| npm CLI | `npm install -g @gracker\u002Fsmartperfetto` | Host Node.js `>=24 \u003C25` | `smp` \u002F `smartperfetto` CLI, Skills, Strategies, SQL, trace-processor prebuilts |\n| Source checkout | `.\u002Fstart.sh` | Host Node.js 24 LTS | Backend source, committed pre-built UI, optional `perfetto\u002F` submodule for UI work |\n\nMaintainer release rules are in [Release Runbook](docs\u002Freference\u002Frelease.en.md)\nand [`.claude\u002Frules\u002Frelease.md`](.claude\u002Frules\u002Frelease.md). Feature and bug\nwork should also check [`.claude\u002Frules\u002Fproduct-surface.md`](.claude\u002Frules\u002Fproduct-surface.md)\nso Web UI, CLI, API, reports, Docker, portable packages, runtime\u002Fprovider,\npre-built content, and Node boundaries stay aligned.\n\n## For Users\n\n### Docker (Recommended)\n\nUse this path if you only want to run SmartPerfetto. You need Docker Desktop\u002FEngine; configure the AI provider in the UI Provider Manager after startup, or use the repository-root `.env` when you need scripted deployment. You do not need Node.js, a C++ toolchain, or the `perfetto\u002F` submodule. The Docker Hub image is published nightly from `main` and includes the backend, the pre-built Perfetto UI, and the pinned `trace_processor_shell`, so it also avoids first-run access to Google's artifact bucket on the host.\n\nBoth the Docker Hub image and source Docker builds serve the committed pre-built UI from `frontend\u002F`; Docker users never build the Perfetto submodule frontend locally.\n\nThe container starts without a local `.env` file for health\u002FUI smoke checks. Real AI analysis needs one explicit provider source: either a UI Provider Manager profile, or one env provider block such as `ANTHROPIC_API_KEY` for Anthropic direct, `ANTHROPIC_BASE_URL` plus `ANTHROPIC_AUTH_TOKEN` \u002F `ANTHROPIC_API_KEY` for a Claude-compatible provider, `SMARTPERFETTO_AGENT_RUNTIME=openai-agents-sdk` plus `OPENAI_*` fields for an OpenAI-compatible provider, or a custom Pi Agent Core \u002F OpenCode block.\n\nProvider profiles created in the UI are stored in the `provider-data` Docker volume. They survive container restarts and normal `docker compose down`; they are removed by `docker compose down -v`.\n\nAn active Provider Manager profile has priority over Docker `.env` credentials. The container startup log and [http:\u002F\u002Flocalhost:3000\u002Fhealth](http:\u002F\u002Flocalhost:3000\u002Fhealth) show whether the current credential source is `provider-manager` or `env-or-default`. To force Docker `.env` fallback, deactivate the active provider in AI Assistant settings.\n\nWindows users should use Docker Desktop with the WSL2 backend. The published image is a Linux container image and runs through Docker Desktop; no separate Windows build is required.\n\nStep 1: Download the source. Run `git clone https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto.git`, then run `cd SmartPerfetto`.\n\nStep 2 (optional): Create the Docker env file. Run `cp .env.example .env`, edit `.env`, uncomment one provider block, and start by replacing the API key\u002Ftoken. If your provider console shows a different Base URL or model ID, use the console value. Skip this step if you will configure the provider in the UI; real AI analysis requires one provider source.\n\nStep 3: Pull the Docker Hub image. Run `docker compose -f docker-compose.hub.yml pull`.\n\nStep 4: Start the container. Run `docker compose -f docker-compose.hub.yml up -d`.\n\nStep 5: Open the service URLs.\n\n- Frontend: [http:\u002F\u002Flocalhost:10000](http:\u002F\u002Flocalhost:10000)\n- Backend health: [http:\u002F\u002Flocalhost:3000\u002Fhealth](http:\u002F\u002Flocalhost:3000\u002Fhealth)\n\nTo use non-default service ports, set `SMARTPERFETTO_BACKEND_PORT` and\n`SMARTPERFETTO_FRONTEND_PORT` before running Compose. If the browser-visible\nbackend address differs from the container listen port, set\n`SMARTPERFETTO_BACKEND_PUBLIC_URL`.\n\nStop the container with `docker compose -f docker-compose.hub.yml down`.\n\nUploads, logs, and Provider Manager profiles are stored in Docker volumes, so they survive container restarts.\n\nIf analysis fails with `Claude Code native binary not found at ...\u002Fclaude-agent-sdk-linux-x64-musl\u002Fclaude` (or the glibc variant), this is the SDK's per-platform native binary auto-selection misfiring inside the container — it is unrelated to your AI provider configuration. The backend will normally auto-fall-back to an installed sibling variant; if it still mispicks, set `CLAUDE_BINARY_PATH` in `.env` to the actual installed binary. See `.env.example` for details.\n\n### Portable Packages\n\nUsers who do not want Docker can use maintainer-built portable packages for Windows, macOS, and Linux. Each package includes the Node.js 24 runtime, target-native `node_modules`, the pre-built Perfetto UI, backend runtime files, and the pinned `trace_processor_shell`.\n\nAssets:\n\n- `smartperfetto-v\u003Cversion>-windows-x64.zip`: extract and double-click `SmartPerfetto.exe`.\n- `smartperfetto-v\u003Cversion>-macos-arm64.zip`: extract and double-click `SmartPerfetto.app`.\n- `smartperfetto-v\u003Cversion>-linux-x64.tar.gz`: extract and run `.\u002FSmartPerfetto`.\n\nAll launchers start the backend and pre-built Perfetto UI, then open [http:\u002F\u002Flocalhost:10000](http:\u002F\u002Flocalhost:10000). Override ports with `SMARTPERFETTO_BACKEND_PORT` and `SMARTPERFETTO_FRONTEND_PORT`. AI analysis needs a Provider profile configured in the UI, or env credentials in the package's user data env file.\n\nMaintainer build command:\n\n```bash\nnpm run package:portable\n```\n\nThe root `package.json` is the project version source and is synchronized to `backend\u002Fpackage.json` and lockfiles. A normal public release publishes npm first, then GitHub portable assets:\n\n```bash\nnpm run version:set -- \u003Cversion>\nnpm run version:sync -- --check\ngit add package.json package-lock.json backend\u002Fpackage.json backend\u002Fpackage-lock.json\ngit commit -m \"chore: release v\u003Cversion>\"\ngit push origin main\nnpm --prefix backend run cli:pack-check\nnpm --prefix backend publish --access public\nnpm run package:portable\nnpm run release:portable -- \u003Cversion> --skip-build --no-draft\n```\n\nCross-platform assets are written to `dist\u002Fportable\u002F`; the Windows-compatible command still writes to `dist\u002Fwindows-exe\u002F`. See [Release Runbook](docs\u002Freference\u002Frelease.en.md) and [Portable Packaging](docs\u002Freference\u002Fportable-packaging.en.md) for npm smoke tests, GitHub release verification, and signing notes.\n\n### Local Script\n\nUse this path if you prefer running from a source checkout on macOS or Linux. Prerequisites: **Node.js 24 LTS**, `curl`, `lsof`, `pkill`, and either Claude Code login or LLM provider credentials. For Windows source development, use [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall), not native Windows shell.\n\nThe repository includes `.nvmrc`, `.node-version`, and Volta pins in `package.json` plus `backend\u002Fpackage.json`; npm is configured with `engine-strict=true`. `.\u002Fstart.sh`, `.\u002Fscripts\u002Fstart-dev.sh`, and `.\u002Fscripts\u002Frestart-backend.sh` will try to activate Node 24 through Volta, nvm, or fnm. If backend dependencies were installed under another Node ABI, the scripts reinstall `backend\u002Fnode_modules` automatically before starting the server. This prevents native modules such as `better-sqlite3` from being reused across Node 20\u002F24\u002F25.\n\nOn macOS, if `trace_processor_shell` fails the `--version` smoke test, macOS says the developer cannot be verified, or the terminal only prints `killed`, Gatekeeper may have blocked the downloaded binary. Open **System Settings → Privacy & Security → Security**, click **Allow Anyway** for `trace_processor_shell`, then re-run `.\u002Fstart.sh` and choose **Open** if macOS asks again. For a binary you trust, you can also run `xattr -dr com.apple.quarantine \u002Fabsolute\u002Fpath\u002Fto\u002Ftrace_processor_shell` and then `chmod +x \u002Fabsolute\u002Fpath\u002Fto\u002Ftrace_processor_shell`.\n\nStep 1: Download the source. Run `git clone https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto.git`, then run `cd SmartPerfetto`.\n\nStep 2: Choose the model credential source. If Claude Code already works in the same terminal, run `claude` to verify it and do not create `.env`. If you want an explicit API key or compatible proxy, run `cp backend\u002F.env.example backend\u002F.env`, then edit `backend\u002F.env`: uncomment `ANTHROPIC_API_KEY` for direct Anthropic, uncomment one Claude Code \u002F Anthropic-compatible provider block for compatible providers, use the OpenAI Agents SDK fields for OpenAI \u002F OpenAI-compatible providers, or use the custom Pi Agent Core \u002F OpenCode sections.\n\nStep 3: Start services. Run `.\u002Fstart.sh`. This script starts both the backend at `http:\u002F\u002Flocalhost:3000` and the repository's pre-built Perfetto UI at `http:\u002F\u002Flocalhost:10000`; regular use does not require initializing the `perfetto\u002F` submodule or compiling Perfetto UI from source. Use `SMARTPERFETTO_BACKEND_PORT` and `SMARTPERFETTO_FRONTEND_PORT` when those defaults conflict with other local services.\n\n## For Developers\n\n### Runtime Scripts\n\nFor regular use, backend changes, strategy changes, and skill changes, prefer `.\u002Fstart.sh`. It starts the backend and serves the repository's pre-built Perfetto UI as the frontend. Use `.\u002Fscripts\u002Fstart-dev.sh` only when editing the AI Assistant plugin UI, debugging Perfetto UI source, or explicitly needing the `perfetto\u002F` submodule watch build. Do not only run `cd backend && npm run dev`: that starts Express, but it does not bring up the frontend or validate the trace-processor path.\n\nOn Linux, if analysis fails with `Claude Code native binary not found at ...\u002Fnode_modules\u002F@anthropic-ai\u002Fclaude-agent-sdk-...\u002Fclaude`, the backend dependencies were installed without the Claude Agent SDK optional native package for this platform. Fix it in three steps: Step 1, run `rm -rf backend\u002Fnode_modules`; Step 2, run `cd backend && npm ci --include=optional`; Step 3, run `cd .. && .\u002Fscripts\u002Fstart-dev.sh`.\n\n| Script | Use when |\n|--------|----------|\n| `.\u002Fstart.sh` | ✅ Default — regular use, backend changes, strategy\u002Fskill edits; starts both backend and pre-built frontend |\n| `.\u002Fscripts\u002Fstart-dev.sh` | AI plugin UI edits (`ai_panel.ts`, `styles.scss` etc.) or Perfetto UI source debugging — requires `perfetto\u002F` submodule |\n\n### Source Docker Build\n\nUse this only when testing Docker changes or building an unreleased local checkout. Step 1: run `cp .env.example .env` and edit the provider if needed. Step 2: run `docker compose up --build`.\n\nThe source build uses the committed `frontend\u002F` bundle and does not rebuild the `perfetto\u002F` submodule.\n\n### Frontend Development (modifying AI plugin code)\n\nWhen you need to edit the AI Assistant plugin UI, Step 1 (first time): run `git submodule update --init --recursive` to initialize the `perfetto\u002F` submodule. Step 2: run `.\u002Fscripts\u002Fstart-dev.sh`; it rebuilds on save.\n\nAfter verifying your changes in the browser, Step 1: run `.\u002Fscripts\u002Fupdate-frontend.sh` to update the pre-built frontend. Step 2: run `git add frontend\u002F`. Step 3: run `git commit -m \"chore(frontend): update prebuilt\"`.\n\n## Runtime Settings\n\nThe quick setup above covers where credentials live. Detailed provider setup, model IDs, regional Base URL variants, OpenAI-compatible runtime fields, Anthropic-compatible presets, Pi Agent Core\u002FOpenCode custom runtime fields, proxy guidance, and troubleshooting live in [docs\u002Fgetting-started\u002Fconfiguration.en.md](docs\u002Fgetting-started\u002Fconfiguration.en.md). Use `GET \u002Fhealth` to confirm `aiEngine.runtime`, `aiEngine.credentialSource`, `aiEngine.providerMode`, and `aiEngine.diagnostics` after changing provider settings.\n\nClaude Code local auth\u002Fconfig is only available to local source runs, not Docker. Separate tools such as Codex CLI, Gemini CLI, and OpenCode manage their own configuration files and login state; SmartPerfetto does not automatically read those credentials. Even the `opencode` runtime uses explicit Provider Manager\u002Fenv model configuration and an isolated server\u002Fproject boundary. The frontend settings dialog's `Connection` tab stores the backend URL and an optional advanced `SMARTPERFETTO_API_KEY` access token only when the backend is protected; the `Providers` tab can write model-provider profiles to the backend Provider Manager.\n\n### Output Language\n\nUser-facing output defaults to Simplified Chinese. To make AI answers, streamed progress text, and generated Agent-Driven reports English, set:\n\n```bash\nSMARTPERFETTO_OUTPUT_LANGUAGE=en\n```\n\nAccepted values include `zh-CN` and `en`. Restart the backend after changing `.env`.\n\n### Turn Budgets\n\nSmartPerfetto has separate turn budgets for fast and full analysis. Claude runtime uses `CLAUDE_*`; OpenAI runtime uses `OPENAI_*` with the same meanings:\n\n```bash\nCLAUDE_QUICK_MAX_TURNS=10  # fast mode default\nCLAUDE_MAX_TURNS=60        # full mode default\nOPENAI_QUICK_MAX_TURNS=10  # optional OpenAI runtime override\nOPENAI_MAX_TURNS=60        # optional OpenAI runtime override\n```\n\nRaise these values for slower models or traces that need more tool iterations. The total safety timeout scales with the turn budget: full mode uses `CLAUDE_FULL_PER_TURN_MS` \u002F `OPENAI_FULL_PER_TURN_MS` per turn, and fast mode uses `CLAUDE_QUICK_PER_TURN_MS` \u002F `OPENAI_QUICK_PER_TURN_MS` per turn. Restart the backend after changing `.env`.\n\n## Basic Usage\n\n1. Open [http:\u002F\u002Flocalhost:10000](http:\u002F\u002Flocalhost:10000).\n2. Load a Perfetto trace file (`.pftrace` or `.perfetto-trace`).\n3. Open the AI Assistant panel.\n4. Ask a question, for example:\n   - `分析滑动卡顿`\n   - `Why is startup slow?`\n   - `CPU 调度有没有问题？`\n   - `Analyze the ANR in this trace`\n\nSmartPerfetto works best with Android 12+ traces that include FrameTimeline data. Recommended atrace categories:\n\n| Scene | Minimum categories | Useful extras |\n|-------|--------------------|---------------|\n| Scrolling | `gfx`, `view`, `input`, `sched` | `binder_driver`, `freq`, `disk` |\n| Startup | `am`, `dalvik`, `wm`, `sched` | `binder_driver`, `freq`, `disk` |\n| ANR | `am`, `wm`, `sched`, `binder_driver` | `dalvik`, `disk` |\n\n## CLI Usage\n\nSmartPerfetto also ships a terminal CLI for trace analysis without opening the browser UI. It uses the same runtime selection, tools, skills, and report pipeline as the web experience and writes local sessions, transcripts, and reports under `~\u002F.smartperfetto\u002F`.\n\n```bash\n# Requires Node.js 24 LTS\nnpm install -g @gracker\u002Fsmartperfetto\n\n# Analyze a trace, then continue the conversation or open the report.\nsmp doctor\nsmp run trace.pftrace \"Analyze scrolling jank\"\nsmp ask \u003CsessionId> \"Why is RenderThread slow?\"\nsmp list\nsmp report \u003CsessionId> --open\n\n# Record an Android trace from a connected device, then analyze it.\nsmp capture presets\nsmp capture android --preset startup --app com.example.app --duration 10 --out launch.perfetto-trace\nsmp capture android --preset cpu --app '*' --duration 30 --categories dalvikviktime my_custom_tag --out cpu-custom.perfetto-trace\nsmp capture android --preset power --app com.example.app --duration 60 --out power.perfetto-trace\nsmp capture android --config ~\u002Ftools\u002Fperfetto_shell\u002Fperfetto.config --out ~\u002Ftools\u002Fperfetto_shell\u002Ftrace\u002Fdut-game-launch.ptrace --analyze --query \"Analyze app launch\"\n\n# Or run the interactive SmartPerfetto REPL.\nsmp repl\n```\n\nThe npm CLI package is the supported standalone terminal product. It does not start or bundle the Web UI launcher; use Docker or a GitHub portable package when you need the browser experience. The first analysis uses the bundled pinned `trace_processor_shell` binary when available, and can download the pinned binary automatically on unsupported targets. Android capture itself never downloads tools at runtime: `adb` is resolved from `ADB_PATH`, an approved bundled slot, then `PATH`; pre-Android Q or `--sideload` tracebox capture requires an approved bundled `tracebox` or `--tracebox \u002Fpath\u002Fto\u002Ftracebox`. If your network cannot reach Google's artifact bucket, set `TRACE_PROCESSOR_PATH=\u002Fpath\u002Fto\u002Ftrace_processor_shell` to use a local binary, or set `TRACE_PROCESSOR_DOWNLOAD_BASE` \u002F `TRACE_PROCESSOR_DOWNLOAD_URL` to a trusted mirror; downloaded binaries are still checked against the pinned SHA256. `smartperfetto` remains available as the long command name; source checkout scripts are only for maintainers debugging the CLI. See [CLI Reference](docs\u002Freference\u002Fcli.en.md) for all commands, capture presets, REPL slash commands, storage layout, and resume behavior.\n\n## API Integration\n\nThe browser UI talks to the backend through REST and SSE. If you want to build your own UI or automation, start with these endpoints:\n\n| Method | Path | Purpose |\n|--------|------|---------|\n| `POST` | `\u002Fapi\u002Fagent\u002Fv1\u002Fanalyze` | Start an analysis |\n| `GET` | `\u002Fapi\u002Fagent\u002Fv1\u002F:sessionId\u002Fstream` | Subscribe to SSE progress and answer tokens |\n| `GET` | `\u002Fapi\u002Fagent\u002Fv1\u002F:sessionId\u002Fstatus` | Poll analysis status |\n| `POST` | `\u002Fapi\u002Fagent\u002Fv1\u002F:sessionId\u002Frespond` | Continue a multi-turn session |\n| `POST` | `\u002Fapi\u002Fagent\u002Fv1\u002Fresume` | Resume SDK context for an existing session |\n| `POST` | `\u002Fapi\u002Fagent\u002Fv1\u002Fscene-reconstruct` | Start scene reconstruction |\n| `GET` | `\u002Fapi\u002Fagent\u002Fv1\u002F:sessionId\u002Freport` | Fetch the generated report |\n\nLeave `SMARTPERFETTO_API_KEY` unset for local single-user runs. Set it in `backend\u002F.env` only if you expose the backend beyond your local machine. Protected APIs then require `Authorization: Bearer \u003Ctoken>`.\n\n## Architecture\n\n```text\nFrontend (Perfetto UI @ :10000)\n  └─ SmartPerfetto AI Assistant plugin\n       └─ SSE \u002F HTTP\nBackend (Express @ :3000)\n  ├─ Runtime selector: Claude Agent SDK, OpenAI Agents SDK, Pi Agent Core, or OpenCode\n  ├─ Agent orchestration: scene routing, prompts, MCP tools, verifier\n  ├─ Shared comparison evidence\u002Freport contracts for Web UI and CLI\n  ├─ Skill engine: YAML analysis pipelines\n  ├─ Session\u002Freport\u002Flog services\n  └─ trace_processor_shell pool (HTTP RPC, 9100-9900)\n```\n\nRepository layout:\n\n```text\nSmartPerfetto\u002F\n├── backend\u002F\n│   ├── src\u002FagentRuntime\u002F   # SDK\u002Fserver runtime selection, registry, Pi\u002FOpenCode adapters\n│   ├── src\u002Fagentv3\u002F        # Claude Agent SDK orchestration\n│   ├── src\u002FagentOpenAI\u002F    # OpenAI Agents SDK orchestration\n│   ├── src\u002Fservices\u002F       # Trace processor, skills, reports, sessions\n│   ├── skills\u002F             # YAML analysis skills and configs\n│   ├── strategies\u002F         # Scene strategies and prompt templates\n│   └── tests\u002F              # Skill-eval and regression tests\n├── docs\u002F                   # Architecture, MCP, skills, rendering references\n├── scripts\u002F                # Development and restart scripts\n└── perfetto\u002F               # Forked Perfetto UI submodule\n```\n\n## Development\n\nCommon commands:\n\n```bash\n.\u002Fscripts\u002Fstart-dev.sh\n.\u002Fscripts\u002Frestart-backend.sh\n\n# Before opening a PR: runs quality, build\u002Ftype checks, skill\u002Fstrategy\n# validation, core tests, and the 6 canonical trace regression.\nnpm run verify:pr\n\ncd backend\nnpm run build\nnpm run cli:build-run -- --help\nnpm run test:scene-trace-regression\nnpm run validate:skills\nnpm run validate:strategies\nnpm run test:core\n```\n\nRequired checks:\n\n- Before opening a PR: `npm run verify:pr` from the repository root\n- Code change by category:\n  - Contract \u002F type-only (`backend\u002Fsrc\u002Ftypes\u002FsparkContracts.ts` etc.): `cd backend && npx tsc --noEmit` + relevant `__tests__\u002FsparkContracts.test.ts`\n  - CRUD-only service (file IO, no agent path touched): that service's unit tests\n  - Touches mcp \u002F memory \u002F report \u002F agent runtime: `cd backend && npm run test:scene-trace-regression`\n- Skill YAML change: `npm run validate:skills` plus scene regression\n- Strategy\u002Ftemplate Markdown change: `npm run validate:strategies` plus scene regression\n- Type\u002Fbuild fix: `cd backend && npm run typecheck`\n\nDo not hardcode prompt content in TypeScript. Put scene logic in `backend\u002Fstrategies\u002F*.strategy.md` or reusable `*.template.md` files.\n\n## Documentation\n\n- [Documentation Center](docs\u002FREADME.en.md)\n- [Quick Start](docs\u002Fgetting-started\u002Fquick-start.en.md)\n- [Code-Aware Analysis](docs\u002Fgetting-started\u002Fcode-aware-analysis.en.md)\n- [Architecture Overview](docs\u002Farchitecture\u002Foverview.en.md)\n- [API Reference](docs\u002Freference\u002Fapi.en.md)\n- [CLI Reference](docs\u002Freference\u002Fcli.en.md)\n- [MCP Tools Reference](docs\u002Freference\u002Fmcp-tools.en.md)\n- [Skill System Guide](docs\u002Freference\u002Fskill-system.en.md)\n- [Data Contract](backend\u002Fdocs\u002FDATA_CONTRACT_DESIGN.en.md)\n- [Rendering Pipeline References](docs\u002Frendering_pipelines\u002Findex.en.md)\n- [Security Policy](SECURITY.md)\n\n## Contributing\n\nContributions are welcome. Good first contributions include:\n\n- Reproducing a performance case with a small trace and clear question\n- Adding or improving YAML skills\n- Improving scene strategies and output templates\n- Fixing UI issues in the Perfetto plugin\n- Adding regression coverage for known trace scenarios\n\nBefore opening a PR:\n\n1. Read [CONTRIBUTING.md](CONTRIBUTING.md).\n2. Fork the repo and create a branch from `main`.\n3. Keep changes scoped and include a clear test plan.\n4. Run the required checks listed above.\n5. Follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Contact\n\n- Bugs and feature requests: [GitHub Issues](https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto\u002Fissues)\n- Security reports: [GitHub private advisory](https:\u002F\u002Fgithub.com\u002FGracker\u002FSmartPerfetto\u002Fsecurity\u002Fadvisories\u002Fnew) or `smartperfetto@gracker.dev`\n- Collaboration, commercial support, and sponsorship: WeChat `553000664`\n\n## Sponsor\n\nSmartPerfetto accepts personal donations, AI credits \u002F token sponsorship, commercial support, and commercial licensing inquiries.\n\n- Sponsor page: [docs\u002Fsponsor.en.md](docs\u002Fsponsor.en.md)\n- WeChat \u002F Alipay QR codes: [docs\u002Fsponsor.en.md#personal-donations](docs\u002Fsponsor.en.md#personal-donations)\n- AI credits \u002F token sponsorship: [docs\u002Fsponsor.en.md#ai-credits-token-sponsorship](docs\u002Fsponsor.en.md#ai-credits-token-sponsorship)\n- Commercial support and licensing: WeChat `553000664`\n\n## License\n\n[AGPL-3.0-or-later](LICENSE) for SmartPerfetto core code.\n\nThe `perfetto\u002F` submodule is a fork of [Google Perfetto](https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fperfetto) and remains under [Apache-2.0](perfetto\u002FLICENSE).\n\nFor commercial licensing without AGPL obligations, contact the maintainer on WeChat: `553000664`.\n","2026-06-11 04:11:31","trending"]