analyze：看懂一次 session

agentprof analyze 是核心子命令 —— 把同一份 session 数据渲染成 5 种 export（md / tui / html / json / speedscope），按你下一步想做什么挑：CI 流水线看 md，浏览器分享 html，本地开发调优 tui。底层都是一份 Analysis 结构体，渲染层只是换了个壳。

🔌 生活类比

像 perf top 看 CPU 热点 —— agentprof analyze 看 token 热点。同一份 perf.data 可以 perf report 看 table、perf script | flamegraph.pl 出火焰图、perf data convert 喂给别的工具； agentprof analyze 的 --export 也是同样的思路：采集只做一次，渲染按需切换，看你下一步要喂给谁（人 / CI / 浏览器 / 第三方 profiler）。

5 种导出格式 — 怎么挑？

下面 3 种是最常用的 主路径；json 与 speedscope 用于工具链集成，在下面卡片里展开：

导出格式	适用场景	命令
`--export md`（默认）	CI 日志 / 控制台 grep 友好 / PR diff	agentprof analyze --agent copilot
`--export html`	浏览器分享 / 单文件自包含 / 邮件 IM 直发	agentprof analyze --export html \ --output report.html
`--export tui`	终端交互 / 火焰图 + ROI 表 + Models view 切视图	agentprof analyze --export tui

👇 三种主路径展开 + json / speedscope 在 html / tui 卡片末尾提及：① 输出长什么样 · ② 为什么这么设计 · ③ agentprof 怎么做。

1 md 导出 — CI 与 grep 友好点击展开

🧪 输出长什么样

标准 Markdown，按段顺序输出：Session header（id / agent / 时间窗口 / 总 token）→ Turn Summary 表（每轮 user/assistant/tool token + cache hit）→ Tool Rank 表（按调用次数 + 平均 token 排序）→ Hook Rank 表（hook 触发次数）→ Cache 段（仅当本 session 有 cache 活动时才出现，命中率 + 节省 token 数）→ Warnings tail（"loaded but never called" 的 tool 列表）。可以用 --section turn-summary,tool-rank 只输出指定段。

🤔 为什么这么设计

纯文本最易 diff：CI 把上一次 main 的 md 报表存成 artifact，PR 跑完直接 diff old.md new.md 就能看到 token 涨跌；不需要专用 viewer。表格列固定 + 排序固定也方便 grep "ToolName" 在大量 session 里定位某次调用。

✅ agentprof 怎么做

用 hand-written markdown renderer（不引 pulldown-cmark 等通用库）—— 输出的是已知形状的固定段落，专用代码反而比通用 AST 短而稳。Cache 段 条件出现是设计取舍：没有 cache 活动时塞一段「Cache hit: 0%」会污染 grep；干脆不写。

2 html 导出 — 浏览器分享 + 自包含点击展开

🧪 输出长什么样

单个 HTML 文件，含 内联 CSS + 内嵌 SVG 火焰图，零外部依赖（无 CDN、无字体请求）。直接邮件 / IM 发给同事，对方双击就能看；离线打开也没问题。

HTML 报告示例 — HTML 报表示例 — 火焰图 + Tool Rank 表（真实截图在 T19 落）

🤔 为什么这么设计

分享场景里「对方不装 agentprof」是常态。如果用 markdown 还得让对方装 viewer + 火焰图渲染不了；如果用 PNG 截图就丢了可点击 / 可复制。单 HTML 文件兼顾「视觉」与「可交互」（hover tooltip / 折叠表）+「可归档」。

✅ agentprof 怎么做

用 askama 模板编译期渲染 HTML 骨架；火焰图走 agentprof-core::flamegraph 生成 SVG 字符串后内嵌；CSS 直接 include_str! 进 binary。整张报表生成后 一次写盘（--output report.html）。想要纯数据喂给别的工具链（grafana / lakera / 自家 dashboard）改 --export json 输出结构化 Analysis；想喂给 speedscope.app 看交互火焰图改 --export speedscope —— 输出的 SVG 长这样：

flamegraph SVG 示例 — speedscope 火焰图示例 — 真实样本在 T19 落

3 tui 导出 — 终端 5 视图（F1..F5）点击展开

🧪 输出长什么样

在当前终端拉起 ratatui 全屏 UI，F1..F5 切 5 个视图：F1 Sessions（session 列表 + 时间窗口过滤）→ F2 TurnDetail（单轮拆解 + token 流向）→ F3 ToolRank（按 ROI 排序的 tool 表）→ F4 HookRank（hook 触发表）→ F5 Models（按模型聚合 token / 成本，M1.6.x + F1.7）。q / Esc 退出。

🤔 为什么这么设计

开发调优场景里你需要的是同一窗口快速切视角：先看 ToolRank 找浪费最多的 tool → 切 TurnDetail 看是哪一轮调的 → 切 Models 看不同模型的占比对比。每切一次 view 就开新 markdown 报表不现实，TUI 是这个场景的天然形态。

✅ agentprof 怎么做

5 视图实现在 agentprof-tui crate，每个 view 是独立 Widget。打 panic-safe lifecycle（ADR-0006）—— main() 装 std::panic::set_hook 先还原 raw mode 再 abort，避免 unwrap panic 让你的 shell 卡死成无回显黑屏。非-TTY 启动 TUI 退出码 3（I/O 错误），用户重定向到管道时立即报错，不会卡在初始化阶段。

下一步

会读单次 session 之后，下一课会带你看 aggregate：把 7 天 / 30 天的 session 聚合在一起，按 mcp-server / tool / 模型分组看趋势 —— 单次 session 看局部，aggregate 看全局。

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

📂 相关源码： agentprof-cli/cmd/format/html.rs render