oam-tools PTO 交互式性能报告 UI 契约架构大图、Layer 导航、Inspector 与 TraceView 的渲染规则详解【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools本篇基于 oam-tools 仓库中 Skill 3cann-perf-ui-json-report的 UI 契约文档 ui-contract.md 展开逐条讲解昇腾 Profiling 交互报告在架构图、重复层导航、Inspector/Operator List、TraceView、HBM 证据与整体样式六个维度的渲染约束并结合assets/report-template/下的真实模板源码与scripts/下的校验脚本说明这些契约在代码中是如何落地的。读完本篇你能完整理解模型架构事实 后端性能数据如何被一套确定性的 UI 规则渲染成可导航、可缩放、可验证的file://独立报告并能定位到每条规则对应的源码位置。一、UI 契约在整个报告流水线中的位置oam-tools 的性能报告生成被拆成三个协同的 SkillUI 契约是第三个环节的行为规范Skill 1cann-perf-breakdown从模型源码提取结构、拆解性能、产出分析 JSONSkill 2cann-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 repoLayer、专家、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考