企业官网建设流程全解析

oam-tools PTO 交互式性能报告 UI 契约：架构大图、Layer 导航、Inspector 与 TraceView 的渲染规则详解

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

本篇基于 oam-tools 仓库中 Skill 3（cann-perf-ui-json-report）的 UI 契约文档 ui-contract.md 展开，逐条讲解昇腾 Profiling 交互报告在架构图、重复层导航、Inspector/Operator List、TraceView、HBM 证据与整体样式六个维度的渲染约束，并结合assets/report-template/下的真实模板源码与scripts/下的校验脚本说明这些契约在代码中是如何落地的。读完本篇，你能完整理解"模型架构事实 + 后端性能数据"如何被一套确定性的 UI 规则渲染成可导航、可缩放、可验证的file://独立报告，并能定位到每条规则对应的源码位置。

一、UI 契约在整个报告流水线中的位置

oam-tools 的性能报告生成被拆成三个协同的 Skill，UI 契约是第三个环节的行为规范：

• Skill 1（cann-perf-breakdown）：从模型源码提取结构、拆解性能、产出分析 JSON；
• Skill 2（cann-perf-breakdown-to-ui-json）：把分析结果转换成model_architecture_graph.v1、overlay 映射和 trace bindings 等中间产物；
• Skill 3（本契约所属）：消费 Skill 2 的交接清单与后端数据，渲染出可交互的 HTML 报告。

Skill 3 的职责边界在 SKILL.md 中有明确声明：只渲染后端与源码事实，不得虚构架构、性能、归属关系、诊断结论或优化建议；后端输入一律只读，report/目录视为生成的运行时产物。UI 契约（ui-contract.md）正是这条原则在"呈现层"上的具体展开——它规定了每个视图（架构图、Inspector、TraceView、HBM）允许显示什么、禁止显示什么、缺失数据时如何降级。

与之配套的>rtk node <skill-dir>/scripts/generate-report.mjs \ --repo <report-repo> \ --handoff <ui-report-handoff.json> \ --refresh-template

带 Trace 与 HBM 的完整生成：

rtk node <skill-dir>/scripts/generate-report.mjs \ --repo <report-repo> \ --trace <trace_view.json> \ --hbm-dir <aligned-hbm-dir> \ --refresh-template

关键规则：

• --refresh-template替换可复用运行时 UI 文件，但保留（或重建）模型专属配置与 Skill 2 输出；
• 报告必须事务性整体生成，任何一步失败都要把上一份报告和 Trace 按字节恢复；
• 所有模型家族统一要求skill3_adapter: generic，消费cann-perf-breakdown-to-ui-json产出的 graph/overlay/bindings，拒绝模型专属适配器；
• report-embedded-data.js由生成器重建，用于file://协议下内嵌数据，手动编辑无效；
• 可选输入缺失降级为空类型数据；必需输入缺失则报字段级错误。

只读检查与确定性校验

# 严格只读检查，不能与 --refresh-template / --trace / --hbm-dir 组合 rtk node <skill-dir>/scripts/generate-report.mjs --repo <report-repo> --check # 生成器改动后的安全回归 rtk node <skill-dir>/scripts/test-generation-safety.mjs --repo <known-good-report-repo>

每次生成必须通过的确定性检查：

rtk node <skill-dir>/scripts/validate-architecture-graph.mjs \ <repo>/report/outputs/model_architecture_graph.json \ --source-root section/source_architecture \ --require-semantic-port-policy rtk node <skill-dir>/scripts/validate-report.mjs --repo <repo> rtk node <skill-dir>/scripts/test-layer-report-metrics.mjs --repo <repo> rtk node <skill-dir>/scripts/test-projected-fanout.mjs --repo <repo>

Layer、专家、HBM 与预期图特征断言仅在交接清单声明了相应能力时运行；声明了能力却缺证据是失败，真正不适用则记为not_applicable，不产生假通过。模板漂移默认拒绝，评审过的偏差只能经ReportRuntimeConfig.templateOverrides/交接清单template_overrides显式声明。

浏览器终验与失败路由

确定性检查通过后，在 1440 × 1000 视口做一次冒烟测试（独立交付时额外做一次file://冒烟），至少覆盖：无 console/资源错误；架构、Inspector、Trace 加载当前数据；mapped/source-only/aggregate/runtime 选择各自守住事实边界；三个不相邻 Layer 的切换能更新作用域徽章、Inspector 指标、Sequence 事件与 Flow 且不改变算子身份；声明分支、残差与选层桥接保持连通；热图图例、本地化标签、tooltip、HBM 缺失态与可选专家投影符合 UI 契约；空画布选择复位与 Trace focus/zoom/pan 可用。浏览器与视觉结果写入校验清单（model_skill_validation_manifest.v2）后，整体状态才能从pending_manual_validation置为 passed。

当验证失败时，SKILL.md 给出按层归因的路由表，防止"在错误的层打补丁"：

• 身份/节点覆盖/Timeline owner/trace 绑定不匹配 → 回到 Skill 1/2 提数据要求，不得修补后端 JSON；
• 边/tensor/provenance 缺失、重复层成员非法、fan-out/fan-in/残差不达标 → 回到 Skill 2 图要求；
• 源码锁不匹配 → 停下重新提取/评审架构，绝不盲目更新哈希；
• 布局、样式、本地化、交互、选择或运行时传输问题 → 修 Skill 3 模板并重新生成。

九、小结：一份"防虚构"的 UI 规范

回看 ui-contract.md 全文，会发现它的措辞几乎全是"preserve / do not / never / only when"：保留所有边身份、绝不合成缺失边、不伪造 per-expert 时序、不把聚合指标复制到各层、不用粗采样声明地址热图、不把常数频率画成时间序列。这套契约的本质是把"性能报告"当作证据呈现系统而非可视化秀场——每一个像素背后的数字都必须能回溯到 analysis、performance、Timeline、原始 Trace 或架构图中被授权的字段。配合 input-files.md 的输入清单与 validation-matrix.md 的验收矩阵，开发者在改动报告 UI 前只需按 SKILL.md 的"先读契约、再改模板、后跑校验"流程操作，就能在昇腾模型 Profiling 数据的呈现上做到可复现、可审计、可独立引用。

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools