📊 agentprof 可视化指南 · 目录 用法 5 / 14
用法

serve：浏览器实时看板

静态 HTML 报告（上节学的 analyze --export html）是快照；agentprof serve 拉起一个本机端口（默认 127.0.0.1:4329），5 个视图自动每 5 秒轮询刷新，跑 agent 边看 token 趋势 —— 不用每次手动重新导。

📋
/sessions
近 200 sessions × 5 列
🔍
/session/:id
单 session 完整报告
📊
/aggregate
by=model/tool/day
🗑️
/mcp-waste
heuristic 浪费分析
⚙️
工具栏
暂停 / 1-30s / localStorage
🔌 生活类比
从 cron + 邮件升级到 Grafana —— 不用每次手动 analyze --export html 邮件转发给自己，agent 跑着就能看实时数据；浏览器开着一个 tab，token 涨没涨、cache 命中没命中、哪个 tool 一直在调，全在那儿动。

3 个核心视图 — 一眼对照

启动 agentprof serve 后，浏览器自动打开（除非 --no-open）。三个最常用的入口：

视图URL用途
Sessions list/sessions最近 sessions 概览（默认 30 天窗口、最多 200 条）
单 session 详情/session/:id完整火焰图 + 表 + cache（T10 同款 body 复用）
跨 session aggregate/aggregate?by=model跨模型对比（类似 list/aggregate 课的 --by tool / --by day）

👇 五张卡片展开 4 个视图 + 1 个工具栏：① 看到什么 · ② 为什么这么设计 · ③ 怎么用。

1 /sessions 列表视图 — 最近 200 sessions 点击展开
🧪 看到什么
最近 200 个 session 的紧凑表，30 天窗口默认（见 cmd/serve/handlers 里的 DEFAULT_SESSIONS_WINDOW）。5 列：Started（开始时间，倒序）/ Model / Turns / Out-tokens / Cache%。点 session id 直接跳详情页。
dashboard /sessions 视图
sessions 列表 — Started/Model/Turns/Out-tokens/Cache% 5 列
🤔 为什么这么设计
列表是入口页，要快 —— 上来就给一周高频信息，不能等几秒。30 天窗口和 200 条上限保证「正常工作量下永远是亚秒响应」；想看更早的 session 就走 analyze --path 或者改 CLI 参数。不做分页是有意的：一屏看不完说明你应该缩窗口，而不是翻第二页。
✅ 怎么用
浏览器开着这个 tab，agent 跑着，每 5 秒它会自己刷一次 —— 你能直接看到「刚才那次 agent 调用花了 18k token」「cache 这一次只命中了 30%」这种实时反馈，无需手动 reload。
2 /session/:id 详情视图 — 复用 analyze HTML body 点击展开
🧪 看到什么
跟 T10 学的 analyze --export html 长得一模一样：Turn Summary 表 + Tool Rank 火焰图 + Cache 段 + Wasted Tool 提示。技术上是同一段 HTML —— serve handler 调 format::html::render_body_only 把 body 段抽出来，外层换上 serve 自己的 chrome（带工具栏的）。
dashboard /session/:id 详情视图
详情视图 — 与 analyze --export html 同款 body
🤔 为什么这么设计
DRY —— 一份模板渲两个产物（静态文件 + serve 端动态）能保证"看到的东西是同一套"，避免「静态报告漂亮，看板里残缺」这种维护噩梦。每 5 秒重新跑一次 analyze 对单个 session 来说几乎免费（百毫秒级），所以不需要缓存。
✅ 怎么用
从 /sessions 点进来，或者直接 http://127.0.0.1:4329/session/<id>。如果你正盯着某个特定 session（比如刚跑了个长任务），把这个 URL bookmark 起来比 analyze 命令快得多。
3 /aggregate?by=model|tool|day — 跨 session 聚合视图 点击展开
🧪 看到什么
和 CLI aggregate --by ...（上节课）同样的三张表，只是渲染到浏览器：?by=model 出 CacheCr/CacheRd/Hit%/NetSaved；?by=tool 出调用次数 + 总 token；?by=day 出时间桶 + low-utilization 标记。
dashboard /aggregate 视图
aggregate 视图 — 浏览器版的 --by model / tool / day
🤔 为什么这么设计
?by=mcp-server 会返回 400 Bad Request —— 不是 bug，是有意的：mcp-server 维度的浪费分析需要 sidecar（tool 描述 token 量），逻辑比一般 aggregate 复杂，单独走 /mcp-waste 专用视图能给更准确的展示。强行塞进 /aggregate 会让 URL 看起来一致但语义实际是两套，反而坑用户。
✅ 怎么用
三个 URL 各 bookmark 一个：/aggregate?by=model（模型对比）、/aggregate?by=tool（tool 排名）、/aggregate?by=day（趋势 + 空转日）。轮询会自动带上参数，所以刷新后视图不会跳走。
4 /mcp-waste — MCP 浪费分析（list + detail 两层） 点击展开
🧪 看到什么
两层视图：list（每个 mcp-server 一行，浪费分数排序）+ detail（点进去看哪些 tool 加载了但从没被调用 / 调用次数极低）。heuristic-only 模式 —— serve 端不要求 sidecar 在线，给的是基于启发式的估算。
dashboard /mcp-waste 视图
mcp-waste — 浪费分数 + 详情两层
🤔 为什么这么设计
浏览器场景下要的是"低延迟、零外部依赖" —— 启发式（基于调用次数 / sessions 覆盖度推断浪费）足够给你"这个 server 该砍"的方向感。精准数字（"这个 tool 的描述吃了多少 token"）需要拉到 sidecar 跑 tokenizer，那条路径走专门的 CLI agentprof mcp-waste --tool-descriptions，serve 这边不强求。
✅ 怎么用
先在浏览器 /mcp-waste 大致看「哪些 server 嫌疑大」；锁定嫌疑 server 后回到 CLI 跑 agentprof mcp-waste --tool-descriptions --server <name> 拿精准 token 数，决定砍不砍 / 哪些 tool 关掉。serve 是探测雷达，CLI 是精确狙击。
5 工具栏 — 暂停 / 间隔切换 / localStorage 记忆 点击展开
🧪 看到什么
页面顶部固定栏：暂停 / 继续按钮 + 间隔下拉（1s / 2s / 5s / 10s / 30s，默认 5s）。会议中临时不想刷新点暂停；演示火焰图细节调到 30s；正在 debug 一个高频任务调到 1s 看实时。
🤔 为什么这么设计
每次开新 tab 重新配置很烦 —— 所以选择持久化到 localStorage，下次打开浏览器记住上次设置。实现是原生 JS poller（不引入 React / Vue / htmx 等任何前端框架），整个工具栏 + 轮询逻辑就一段 vanilla JS（per ADR-0024 D-2 决策：D-1/D-3/D-4/D-5 都是为了「无构建、无 node_modules、纯 Rust 出 binary 就能跑」）。
✅ 怎么用
不用任何配置 —— 打开页面就有。如果工具栏不在你期望的位置，看 ADR-0024 里 D-2「vanilla JS poller」的具体落点；想换 polling 策略改一处 JS 就好，不用动 Rust 代码。

[serve] config block — 固化默认值

每次敲 --bind 127.0.0.1:4329 --interval-default 5 --no-open 很烦，把它写进 ~/.config/agentprof/config.toml（路径见 config show）：

[serve]
bind = "127.0.0.1:4329"
interval_default = 5
auto_open = true

CLI flags 总是覆盖配置文件：临时换端口直接 --bind 127.0.0.1:9999，不影响默认值。

CLI flags 速查

Flag默认值用途
--bind127.0.0.1:4329监听地址；要从局域网访问改成 0.0.0.0:4329（注意没有 auth）
--storage-pathOS data dir 下的默认 SQLite指向已有的 storage DB（比如 watch 在用的那一份）
--interval-default5（秒）首次打开时的轮询间隔；用户在工具栏改过会被 localStorage 覆盖
--no-open（默认会 open）禁止自动打开浏览器；SSH/容器/CI 里必须加

「serve vs static HTML」决策表

你想做什么用哪个为什么
分享给同事一份快照analyze --export html单个 HTML 文件，可邮件 / 上传 wiki / 截图存档；离线打开也能看
边跑 agent 边看实时数据serve5 秒轮询 + 多视图 + 暂停按钮，配合 watch 写入是「近实时」
团队共看 / 长期归档serve 配反向代理 + authbind 到内网地址，前面挂 nginx / Caddy 加 basic auth 或 OAuth proxy

下一步

会用 serve 之后，下一课会带你看 watch + config：watch 守护进程把新 session 实时灌进 storage（serve 这边自动就能看到），config 把所有命令的默认值固化到一处避免每次敲长串。

📂 相关源码： agentprof-cli/cmd/serve/router.rs  build_router

📂 相关源码： agentprof-cli/cmd/serve/handlers.rs  handlers