方式 C：只验证一个独立 profile（不影响正在使用的 GUI）

$env:DSH_HOME = "D:\tmp\.dsh-test"
dsh --profile demo --from-default-profile web --port 3099 --no-open

3. 使用

3.1 打开页面

侧边栏底部新增入口 「Profiler 分析」（浏览器半注册在 sidebar.footer.action 插槽，点击在新标签页打开分析页面）；
或直接访问 http://127.0.0.1: /vllm-ascend-profiler/。

3.2 导入产物

三种方式，任选：

方式	适用场景	说明
拖拽/多选上传	常规 CSV + 中小 trace	多个文件作为一个数据集依次上传，页面显示字节级上传进度
打包上传	`*_ascend_pt` 目录整体	支持 `.zip` / `.tar.gz`（内存内解压，成员大小与数量有上限）
按路径分析	GB 级 `trace_view.json`	服务端流式读取，不占上传带宽；默认限制在会话工作区内

3.3 解析进度

解析是异步任务：页面轮询任务状态并显示「校验 → 解析 → 汇总 → 分析」四段进度与明细日志。大 trace 不会卡死页面：事件按预算做等距采样（通信/拷贝/长耗时算子全量保留），采样情况在页面与报告中明确标注。

3.4 三大模块

页面是一个五步流程（导入产物 → 概览与定位 → 时序取证 → 占比归因 → 优化行动），顶部步骤条显示当前进度并可点击跳转。三个可视化模块共享同一个筛选状态：在泳道图里点选算子、在大类构成条里点选大类、在耗时分布图里点选方块，效果会同步到其它视图（对应条目高亮、其余淡出），筛选条件以可关闭的标签显示，Esc 一键清除。概览页的「查看方案」会把对应优化项直接带到第 5 步的第 ④ 环。

模块一 · Host / Device 算子执行泳道图

两组泳道：Host（CPU） 与 Device（昇腾 NPU），组内每个算子一行（默认按累计耗时降序，可切换调用次数 / 算子名 / 单次最长，行数可调 20/40/80/160）；
X 轴为时间轴（自动按 µs/ms/s 选单位），每根算子条是一次调用：起点=开始时间，宽度=持续时长；
颜色区分通信 / 计算 / 数据拷贝 / 调度 / 其他五类，图例本身就是筛选器（点击即隐藏/显示该类），Host / Device 两组可单独隐藏；
交互：滚轮滚动行、Ctrl/⌘ + 滚轮以光标为中心缩放（缓动过渡）、Shift + 滚轮或拖拽平移、双击重置、Esc 清除筛选、悬停显示算子卡片（算子名、开始时间、耗时、调用次数、累计/均值/p95、输入输出 shape、OP/Task Type、调用栈、rank/stream）、点击算子条筛选该算子并自动滚动到该行；
▶ 播放：时间游标按所选速度（1×/4×/12×）扫过整个窗口，游标扫到的算子条高亮 —— 用来直接回答"设备空闲时主机在做什么"；
视图抽样会明确显示「本行显示 N/M 个算子条」，累计耗时统计不受视图抽样影响。

模块二 · 耗时占比归因（两张图说完全部占比）

大类构成条：一条 100% 构成条按算子大类切分，段内直接标注占比，口径可切「设备侧 / 全部 / Host 侧」；点段或点图例即按该大类聚焦泳道图；
算子耗时分布图（treemap）：每个方块是一个算子，面积 = 耗时占比、颜色 = 大类，方块的排布同时表达"谁最大"（排序）与"属于哪一类"（层级）；点方块即筛选该算子；
维度切换：累计总耗时（找"次数多、总量大"的算子）↔ 单次执行耗时（找"单次就很慢"的算子）；方块数可调 12/20/30；
需要精确数字时展开「数据表」：调用次数、累计、均值、p95、占比与总计来源（trace 聚合 / CANN 统计表）及 cross-check 偏差。

模块三 · 优化行动（推理链即流程，图上只留数字）

第 5 步把固定的五步推理链做成 ①→⑤ 的流程节点 + 一块图：每个节点只带一个关键数字（瓶颈类型与分数、门限通过项数、机理条数、行动优先级分布、保守收益），点节点切换下方那一块图，文字全部收进「依据」折叠项。

瓶颈定位：四类候选（Host 调度 / NPU 计算 / 跨卡通信 / 数据拷贝）分别打分 0–100，柱状对比「全量窗口 / Prefill / Decode」三组判定；
量化证据：每个指标的实测值与其门限画成对比条——达门限=绿、未达门限=红、虚线=门限位置，点击任一指标可回到第 3 步按时序筛选同类算子；
根因推断：每条机理压缩成「触发数据 → 作用机理 → 影响」三段式链条，机理原文与现场确认方法在「依据」里；
优化行动：按高/中/低排序，每条一眼看到收益区间条（竖线=估算值，浅色=经验区间）与置信度，动作、验证方法、风险、关联根因在「依据 / 动作 / 验证」折叠项内；
预期收益：逐项收益条 + 保守/乐观合计，明确标注哪些是本数据集推算、哪些是经验区间，并说明多项优化的收益不可简单相加。

3.5 动效与可访问性

动效都用来说清"数据是怎么来的"，而不是装饰：载入时 KPI 数字滚动、进度条按阶段推进、泳道图从左到右扫出算子条、treemap 方块按名次依次淡入、收益条从 0 生长、进度条与评分条从 0 增长、面板切换淡入。

顶栏 「动效」开关（默认开，选择记在 localStorage）可一键关闭全部动画；
操作系统级 prefers-reduced-motion: reduce 同样会被尊重；
所有交互都有非动画的等价反馈（文字状态、aria-pressed、筛选标签）；
键盘：Esc 清除筛选 / 关闭弹窗，流程节点是 role="tab" 的可聚焦按钮（Enter 切换），treemap 方块与大类段可 Tab 聚焦并用 Enter 选中。

3.5 阶段口径（Prefill / Decode）

页面「阶段口径」可切换 自动推断 / 仅 Prefill / 仅 Decode 并重新分析。由于昇腾产物默认没有阶段标签，推荐做法是：

分别采集 prefill-only 与 decode-only 两个窗口（/start_profile → 只发长 prompt → /stop_profile，再单独采 decode），然后在页面上直接指定阶段；
若无法分开采集，插件会按步长分布推断（log 空间双峰），并在报告中标注置信度与推断依据；step_trace_time.csv 的 Stage 列优先级最高。

3.6 导出报告

Markdown：完整报告（含 ①–⑤ 全链路、门限比对明细、TopN 表、阶段指标、口径与告警）。若已导出过 PDF，图表快照会作为内嵌图片一并写入，文件自包含、可直接分发；
PDF：页面先捕获泳道图（完整采集窗口）、大类构成条与耗时分布图快照提交给服务端，然后打开打印优化版 HTML 并自动弹出打印对话框，选择"另存为 PDF"即可。不引入任何 PDF 库，保留矢量文字与可选中文本。

导出时若图表捕获失败（例如浏览器限制 canvas 导出），报告仍会正常生成，只在图表章节说明原因。

3.7 内置说明文档

页面顶部「说明文档」按钮，包含：指标定义与计算公式、口径注意事项、每个 profiling 产物（含字段表头）的用途与陷阱、快速开始与性能提示。同样的内容以 Markdown 形式保存在 docs/metrics-and-fields.md。

3.9 界面预览

截图由 tools/capture-page.mjs 通过 DevTools 协议驱动无头浏览器生成（等三模块真正渲染、动画结束后再截图）。数据为 test/fixtures/host-schedule-bound 场景：35,713 个事件 / 21 个算子 / 20 个推理步，主导瓶颈 = Host 调度 97 分。

第 1 步 · 导入产物（拖拽上传 / 按路径分析 / 分阶段进度）

导入区