5 分钟上手

装好 agentprof 比装 IDE 插件还快 —— 3 种装法任选其一，最后一句 agentprof analyze --agent copilot 就能看到你第一张火焰图。整个流程不超过 5 分钟，也不需要修改你的 agent 配置。

❓ 你想几分钟内跑起来还是想改源码 / 调试？

🚀 最快路径

→

curl -fsSL https://github.com/verdenmax/agentprof/releases/latest/download/agentprof-cli-installer.sh | sh —— 30 秒拉预编译 binary，不需要 Rust toolchain

📦 想要 sha256 校验

→

去 github.com/verdenmax/agentprof/releases/latest 手工下 .tar.xz + .sha256，校验后解压到 $PATH

🛠️ 想改源码 / 跑测试

→

git clone + cargo install --path crates/agentprof-cli --features full（需要 Rust 1.78+）

🔌 生活类比

把 agentprof 想成 事后回放的 Wireshark：你不需要在 agent 里埋点、不需要改 prompt、不需要重启服务 —— 只要 agent CLI 在本地留下了 events.jsonl / session.jsonl， agentprof 就能事后把每一次对话「抓包回放」成火焰图 + ROI 表。零侵入、零运行时开销、零外发数据。

3 种安装方式怎么选？

按你有没有 Rust toolchain + 是不是开发者分三档，先看一眼对照表再决定：

安装方式	适用人群	命令
One-line installer ⭐	大多数用户（不需要 Rust）	curl -fsSL \ https://github.com/verdenmax/agentprof/releases/latest/download/agentprof-cli-installer.sh \ \| sh
From source	开发者 / 想跑最新 main / 想跑测试	git clone https://github.com/verdenmax/agentprof \ && cd agentprof \ && cargo install --path crates/agentprof-cli \ --features full
`cargo install agentprof-cli`	Rust 用户（暂不可用）	暂未发布到 crates.io，计划随 v0.4 上 publish；当前用上面两种之一

👇 每一种安装方式的细节都在下面的折叠卡片里：① 命令 · ② 为什么 · ③ agentprof 怎么做 · ④ 其他选择。装好以后翻到第 3 张卡片跑第一次 analyze。

1 「One-line installer」最快路径 ⭐ 推荐点击展开

🧪 命令

curl -fsSL https://github.com/verdenmax/agentprof/releases/latest/download/agentprof-cli-installer.sh | sh
# 自动检测 OS/arch，拉对应预编译 binary 到 ~/.cargo/bin/agentprof

🤔 为什么必要

你不需要装 Rust toolchain。脚本走 cargo-dist 发布的 GitHub Release，支持 Linux x86_64 / aarch64、macOS Intel / Apple Silicon 共 4 个 target triple。安装时间 < 10 秒。

✅ agentprof 怎么做

CI 在 tag push 时用 cargo dist build 交叉编译并签名打包，每个 binary 自带 所有默认 feature（含 full）。SHA256 sums 一并发布到 Release assets 里方便手工校验。latest/download/ 会自动跳到含 asset 的最新 release —— 如果当前 tag 还没跑完 release workflow，会回退到上一个有 asset 的版本（详见 ADR-0014）。

🔀 其他选择

离线环境 / 想手动校验 sha256 时，直接到 github.com/verdenmax/agentprof/releases 手工下对应 agentprof-cli-<triple>.tar.xz + .sha256，解压放到 $PATH。

2 「From source」开发者路径点击展开

🧪 命令

git clone https://github.com/verdenmax/agentprof
cd agentprof
cargo install --path crates/agentprof-cli --features full
# 安装位置：~/.cargo/bin/agentprof
# 确认 PATH： echo $PATH | grep -q "$HOME/.cargo/bin" && echo OK

🤔 为什么必要 / MSRV

agentprof 用 Rust 2021 edition + MSRV 1.78 写成。cargo install --path 比 cargo install agentprof-cli 更稳 —— 后者目前还没发布到 crates.io（计划随 v0.4 启动 publish；当前唯一可执行路径是这条）。首次编译 ~2 分钟（带 tiktoken-rs / rusqlite / ratatui 三个稍大依赖），增量编译几秒。

✅ agentprof 怎么做

默认开 full feature，自动带上 anthropic-api（直连官方反查 cache 价格）+ otlp（接 OpenTelemetry receiver）+ web（HTML 报表渲染）+ tui。装完即用，不需要再 --features。

🔀 其他选择

只想要核心 analyzer 不要 OTLP / 网页报表 / TUI，可以 cargo install --path crates/agentprof-cli --no-default-features --features core 减小 binary 体积约 30%。一般用户不需要做这个优化。cargo install agentprof-cli（裸 crates.io 路径）暂时不可用，等 v0.4 ship 后再启用。

3 第一次跑 — analyze --agent copilot 点击展开

🧪 命令

agentprof analyze --agent copilot
# 默认行为：
#   1. 扫描 ~/.copilot/session-state/  找最新一条 session
#   2. 解析 events.jsonl  生成 Episodes
#   3. TUI 打开火焰图 + Turn Summary + Tool Rank 三个 tab

🤔 为什么必要

不需要传任何参数是设计目标：第一次跑就能看到东西，建立"这工具有用"的直觉。指定 session / 时间窗口 / 导出格式都是第二步的事。

✅ agentprof 怎么做

CLI 入口在 agentprof-cli::Cli（clap derive）。--agent copilot 会调用 agentprof-adapters::copilot 解析；想跑 Claude Code 用 --agent claude（默认扫 ~/.claude/projects/），Codex 用 --agent codex（扫 ~/.codex/）。想导出 Markdown 报表加 --export md，HTML 加 --export html。

⚠️ 常见报错对应方案

Error: no session found under ~/.copilot/session-state/
# → 还没用过 Copilot CLI 跑过对话。先跑一句 `copilot "hello"`，
#   产生第一条 session，再回来 analyze。

Error: failed to parse session abc-123 at /home/me/.copilot/.../events.jsonl
# → events.jsonl 损坏（通常是断电中断写入）。跳过这条用
#   `agentprof list --agent copilot --since 7d` 看其他可用 session。

Error: agent 'copilot' not registered
# → adapters 没编进 binary。从 source 装时漏了 default feature，
#   重新 `cargo install agentprof-cli` 即可（默认会带 copilot adapter）。

4 升级 / 卸载 / 切换版本点击展开

⬆️ 升级到最新版

# 路径 1（installer 装的）：再跑一次 installer，覆盖旧 binary
curl -fsSL https://github.com/verdenmax/agentprof/releases/latest/download/agentprof-cli-installer.sh | sh

# 路径 2（from source 装的）：
cd agentprof && git pull
cargo install --path crates/agentprof-cli --features full --force

两种路径都安装到 ~/.cargo/bin/agentprof，覆盖即升级。升级前可 agentprof --version 看现状，升级后再跑一次确认。升级不会动你的 SQLite store（schema migration 是 forward-compatible，新 binary 直读旧 db；详见 ADR-0019）。

⏪ 降到旧版本（troubleshoot 用）

# 装指定版本（替换 v0.3.2 为你想要的 tag）
curl -fsSL https://github.com/verdenmax/agentprof/releases/download/v0.3.2/agentprof-cli-installer.sh | sh

# 或从 source 装某个 tag
git checkout v0.3.2
cargo install --path crates/agentprof-cli --features full --force

🗑️ 卸载

# installer / cargo install 装的都在这里
rm ~/.cargo/bin/agentprof

# 可选：删 SQLite cache / store（如果你不想保留分析数据）
rm -rf ~/.cache/agentprof/   # cache 默认位置 (XDG_CACHE_HOME)
rm -rf ~/.local/share/agentprof/   # store 默认位置 (XDG_DATA_HOME)

# 可选：删配置文件
rm -f ~/.config/agentprof/config.toml

agentprof 不写任何系统级文件（无 launchd / systemd unit / 注册表条目），所以卸载就是删 4 个用户态路径。

🔀 并行多版本（不推荐但可行）

把不同版本 binary 放在不同路径，rename 区分：

cp ~/.cargo/bin/agentprof ~/.local/bin/agentprof-v032
git checkout v0.3.3 && cargo install --path crates/agentprof-cli --features full --force
# 现在 agentprof = v0.3.3, agentprof-v032 = v0.3.2

适合「对比新旧版本输出」debug 场景；正常用户应该只装一个。

下一步

装好工具、看到第一张火焰图后，下一课会带你看懂火焰图：每个矩形块代表什么、宽度怎么算、为什么 system prompt 经常是最长那条。

📂 相关源码： agentprof-cli/main.rs Cli

📂 相关源码： agentprof-cli/cmd/analyze.rs AnalyzeCmd