cann-perf-ui-json-report 数据契约详解从 Skill 2 交接清单到跨文件不变量的 UI 报告生成规范【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools本文以 数据契约文档 为核心系统讲解 CANN oam-tools 仓库中cann-perf-ui-json-reportSkill 3在生成交互式性能分析报告时必须遵守的数据契约包括后端事实与展示层的输入所有权划分、ui_report_handoff.v1交接清单格式、report-config.js运行时配置、跨文件不变量以及事务性输出与验证要求。读完本文你将掌握如何正确组织报告输入、判断哪些数据缺失属于上游问题、理解确定性校验与人工验收的分界并能在实际生成与修复报告中做到只呈现、不篡改后端事实。一、数据契约解决什么问题cann-perf-ui-json-report是一个渲染型技能它读取后端Skill 1/2产出的分析、性能、时间线、原始 Trace、架构图与绑定数据把它们渲染为可交互的 HTML 报告。正因为它不产生任何模型事实所以输入所有权Input ownership是整个数据契约的第一原则——每一类输入文件对什么有权威、对什么没有权威必须在生成前明确否则渲染层很容易越权推断。数据契约将参与方划分为三层Skill 1/2上游负责后端事实的采集、分析与架构建模Skill 3本技能负责展示、交互、布局、语言/主题行为、选区同步、本地传输与校验Skill 3 的约束只能呈现输入中已经存在的事实不得修复后端事实It must not repair backend facts。下表完整列出各输入文件的权威边界源自>{ schema_version: ui_report_handoff.v1, model_family: deepseek_v3_2, skill3_adapter: generic, inputs: { analysis: ../model_analysis_config.json, performance: ../model_perf_data.json, timeline: ../model_timeline.json, trace: ../trace_view.json, bindings: ./outputs/trace_bindings.json, architecture: ./outputs/model_architecture_graph.json, overlay: ./outputs/architecture_overlay_map.json }, optional_inputs: { operator_details: ./outputs/operator_details.json, hbm: ./outputs/hbm_series.json, findings: ./outputs/metrics_findings.json, expert_inventory: ./outputs/expert_inventory.json }, capabilities: { repeatedLayers: true, expertInventory: true, expectedGraphFeatures: { fanOutMin: 2, fanInMin: 2, residualEdgesMin: 2, parallelRowsMin: 1 } }, provenance: { skills: [cann-perf-breakdown, cann-perf-breakdown-to-ui-json], modelSource: models/modeling_example.py, extractorModel: model-name } }关于清单格式有三条硬性规定需要特别注意skill3_adapter必须是generic。契约明确规定所有 Skill 2 输出一律使用generic适配器Skill 3 会拒绝模型专用适配器skill3_adapter为其他值时报错模型家族本身绝不授权单独构建一套 builder。这一点在 report-runtime-config.mjs 的validateHandoff中有直接实现schema_version必须是ui_report_handoff.v1inputs七个键缺一不可skill3_adapter非generic直接抛错。capabilities是承诺声明了repeatedLayers、expertInventory、expectedGraphFeatures就等同于承诺报告必须提供对应证据能力缺失时校验不得假通过。provenance是溯源记录流水线所用技能、模型源码路径与提取器模型名Skill 3 不直接读取模型的 Python/配置文件。关于输入文件的权威内容映射input-files.md 给出了更详细的对照analysis对应*_analysis_config.jsonperformance对应*_perf_data.jsontimeline对应*_timeline.jsontrace对应trace_view.jsonbindings/architecture/overlay分别对应report/outputs/下的trace_bindings.json、model_architecture_graph.json、architecture_overlay_map.json。七条路径全部必填缺失必填输入直接导致生成失败。三、运行时配置report-config.js是传输配置而非模型模板数据契约明确将report-config.js定位为generated transport configuration生成的传输配置而不是模型模板。它由 Skill 2 交接清单生成声明了各数据文件的相对路径必填键7 个analysis、performance、timeline、trace、bindings、architecture、overlay可选默认键4 个operatorDetails、hbm、findings、expertInventory均位于report/outputs/下缺省时回退为空数据。在 report-runtime-config.mjs 源码中可以看到这两个集合被直接编码为常量REQUIRED_CONFIG_KEYS与OPTIONAL_CONFIG_DEFAULTS。readRuntimeConfig会在一个window沙箱中执行report-config.js读取window.ReportRuntimeConfig缺必填键时报出missing required key(s)并列出具体键名可选键则自动填充默认路径并返回defaultedOptionalKeys列表供后续校验区分显式提供与回退默认。另一个关键概念是templateOverrides它允许列出经过评审、故意与 Skill 模板不同的运行时文件。未声明的模板漂移undeclared template drift属于校验失败——这是防止报告在长期维护中悄悄偏离技能模板的保护机制。configFromHandoff会从清单的template_overrides或旧配置的templateOverrides中继承该列表而 validate-report.mjs 会对index.html、app.js、architecture-data.js、全部 design-system 模式文件等 23 个文件逐一做 SHA-256 哈希比对哈希一致才算通过不一致时只有声明在templateOverrides中的文件被容忍输出OVERRIDE警告其余一律按STALE计入失败。四、跨文件不变量九条必须成立的事实约束数据契约的Cross-file invariants部分是报告正确性的核心判定标准共九条硬性要求身份一致analysis、performance、Timeline 三份文件中的模型/报告身份model_id、report_id必须完全一致定义唯一后端节点定义与性能记录不得重复节点覆盖精确analysis 与 performance 的节点集合必须完全一致除非 schema 显式声明例外owner 可解析每个非空的 Timeline owner 都必须能在 analysis 中解析到计数自洽事件计数、mapped/unmapped 汇总必须与实际事件吻合事件边界有序有限所有事件边界必须有序且为有限值原始绑定唯一当要求原始绑定raw binding时每个归一化事件必须恰好绑定到一个原始 duration 事件架构边端点有效每条架构边的两个端点都必须可解析并保留语义/张量/溯源字段映射分类唯一每个后端节点必须有且仅有一个经评审的映射分类。契约特别强调一条易混淆的语义Timeline owner 百分比衡量的是事件映射覆盖率event-mapping coverage不是架构覆盖率architecture coverage。二者不能混用。这些不变量在 validate-report.mjs 中被逐条实现为约 180 条断言例如model_id matches across backend files、report_id matches across backend files身份一致analysis and performance node IDs match exactly节点覆盖every mapped timeline owner resolves to a backend nodeowner 可解析timeline event_count matches the event array、timeline mapping summary is backend-authored and internally consistent计数自洽every binding resolves to one distinct raw duration event、TraceView binding coverage is 100 percent原始绑定唯一every backend node has exactly one explicit mapping classification映射分类唯一architecture edges resolve and preserve tensor metadata plus provenance架构边端点有效。五、可选能力声明了就必须兑现数据契约对四个可选能力分别给出了明确的处理策略repeatedLayers必须运行 Layer 成员关系membership、分页器pager、作用域指标scoped-metric与选区保持selection-preservation测试。对应脚本是 test-layer-report-metrics.mjs它从analysis.layer_structure提取解码器模板逐一校验成员索引跨 analysis/graph/performance/Timeline 四处的完全一致、抽样 Layer 的算子数、kernel_sum_ms与time_share百分比与事件逐项对账还验证 Layer 分页器被提升到重复模板之外、无嵌套分页器、全局 Layer 导航索引无重复。expertInventoryMoE 展示只应用于具有显式架构角色或可识别 legacy 别名的条目。校验端要求每个 MoE 都投影为 Router 到 Expert 的直接 fan-out Shared Expert不允许额外 expert-bank 或可见 Dispatch 层并且融合专家执行绝不虚构逐专家后端身份或时序。expectedGraphFeatures强制执行模型特定的最小图证据如fanOutMin、fanInMin、residualEdgesMin、parallelRowsMin当上游声明了这些特性时不允许空的 fan-out/residual 测试通过。对应脚本是 test-projected-fanout.mjs它自动发现图中的 fan-out 源、fan-in 汇与layoutRows行断言每条边在默认折叠后仍投影到可见端点、同层节点之间不存在数据依赖并将实际探测数与清单声明的下限比对。HBMHBM 分区标题必须始终可见数据缺失时折叠内容展开时显示本地化的未采集说明而非假装有数据。能力语义的最后一条铁律是声明了能力却缺少证据 失败确实不适用的能力 not_applicable但not_applicable绝不是缺失预期证据时的替身。repeatedLayers未声明时test-layer-report-metrics会打印SKIP并以状态 0 退出这与声明了却无模板时直接抛错形成鲜明对比。六、输出所有权与事务性生成report/被整体视为generated runtime生成的运行时这一所有权界定带来三条工程要求事务性构建完整生成下一版报告任何一步失败都必须恢复上一版完整报告report.prevTrace 文件trace_view.prev.json同样按字节恢复--check严格只读不得创建占位文件、不得重命名index.html、不得改写清单、不得触碰时间戳且不能与--refresh-template、--trace、--hbm-dir组合使用report-embedded-data.js只是镜像它镜像规范 JSON 以支持file://独立打开永远不是可编辑的事实源。这些要求在 generate-report.mjs 中有非常具体的实现生成前先将旧report重命名为report.prev再拷贝模板与模型配置catch 分支中删除不完整的新目录、把report.prev改名回来并恢复 trace命令行第 56-58 行直接拒绝--check与写操作的非法组合--check is read-only and cannot be combined with ...--refresh-template只替换可复用 UI 文件但通过PRESERVED model-specific report-config.js保留模型特定配置并保留outputs/下 Skill 2 产物新报告无 handoff 时抛出A new report requires ui-report-handoff.json or an explicit --handoff path。生成器内部还内置了一张上游诊断映射表UPSTREAM_DIAGNOSTIC当校验失败时把错误模式对接到应该修复的上游技能例如tensor.name is required指向 Skill 2 的build_architecture_graph.pydataflow cycle detected指向 Skill 1 的analysis_config_v2fan-out minimum/fan-in minimum指向 Skill 2 的边生成。这样谁的数据问题回到谁那里修成为可自动判定的路由规则而不是靠人肉排查。七、验证清单确定性校验与人工验收的分界数据契约的最后一节把验证拆成两类并定义了严格的状态语义validation-matrix.md 有完整展开确定性校验deterministic checks生成安全性、配置、模板一致性、后端身份、架构、绑定、Layer、分支、可选数据、独立运行等十个领域全部由脚本自动执行人工/浏览器校验manual checks在 1440 × 1000 视口下做冒烟测试无 console/资源错误、架构/Inspector/Trace 加载当前数据、三个不相邻 Layer 的选区同步、空画布重置、Trace 缩放平移聚焦、双语言双主题独立交付场景还需以file://打开report/index.html再验一次。状态语义为deterministic_status: passed表示自动校验全过人工条目记为passed/failed/not_run确定性校验通过但人工未跑完时overall_status只能是pending_manual_validation绝不允许直接标记 passed。只有当确定性 全部必需人工校验都通过后overall_status才置为passed。在 generate-report.mjs 末尾可以看到这一语义的落地生成器写出model_skill_validation_manifest.v2清单确定性条目全部置真、人工三项browser_smoke_1440x1000、file_protocol_smoke、visual_review初始化为not_rundeterministic_status: passedoverall_status: pending_manual_validation——最终通过与否交由浏览器冒烟与视觉评审记录后人工翻转。八、实操要点与故障路由速查基于整个数据契约实际操作中的故障可以快速定位归属现象归属处置身份不一致、节点覆盖不齐、Timeline owner 无法解析、Trace 绑定不匹配Skill 1/2 数据问题返回上游补充/修正数据不得修补后端 JSON架构边缺 tensor/provenance、重复成员关系无效、fan-out/fan-in/residual 不足Skill 2 图问题返回 Skill 2 重新构建架构图源码锁不匹配提取问题停止并重新提取/评审架构绝不盲目更新哈希布局、样式、本地化、交互、选区、运行时传输问题Skill 3 模板问题修复模板后重新生成事实缺失一律保留为 unavailable绝不按叶子标签相似度强行映射来凑覆盖率生成与检查的命令源自 SKILL.md# 新报告基于 handoff 清单生成并刷新模板 rtk node skill-dir/scripts/generate-report.mjs \ --repo report-repo \ --handoff ui-report-handoff.json \ --refresh-template # 只读检查不可与写操作组合 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其中 test-generation-safety.mjs 会在临时目录完整复制一个已知良好的报告仓库依次验证四件事--refresh-template不改变模型后端路径、--check前后仓库快照逐字节一致只读、未声明的index.html漂移会被--check拒绝、故意制造生成失败后完整恢复先前报告。九、总结cann-perf-ui-json-report的数据契约用所有权这一单一原则贯穿始终上游文件对后端事实负责Skill 3 对呈现负责二者通过ui_report_handoff.v1交接清单建立唯一连接。report-config.js是这份契约在运行时的投影跨文件不变量是契约的验收标准事务性生成与只读--check是契约的工程保障pending_manual_validation状态语义则确保自动化永远不能替人工验收盖章。理解这份契约是正确使用、扩展与排查本技能报告链路的前提——任何试图在渲染层聪明地修复或推断后端事实的做法都在契约的禁止清单上。参考文档与源码索引数据契约主文档data-contract.md技能使用说明SKILL.md输入文件清单input-files.md验证矩阵与状态语义validation-matrix.md报告生成器事务、--check、上游诊断路由generate-report.mjs运行时配置与 handoff 校验必填/可选键、generic 约束report-runtime-config.mjs报告整体校验模板哈希、跨文件不变量断言validate-report.mjs生成安全性回归测试test-generation-safety.mjsLayer 能力测试test-layer-report-metrics.mjs图证据fan-out/fan-in/layoutRows测试test-projected-fanout.mjs【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考