@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: msopprof-visualization
+description: 面向算子的 msOpProf 数据采集与可视化技能。用于执行环境检查、最小非重复采集、已有采集结果重绘，以及生成包含 Details、Roofline、Timeline、Cache、Source、片上内存、Warp Stall、指令时间线和原始数据页面的独立 HTML 报告。当用户要求将上板采集的算子性能数据生成可视化报告、查看某个性能模块页面、或基于已有采集目录重建报告时触发。
+---
+
+# msOpProf 采集与可视化
+
+## 职责
+
+将算子工程或已有 msOpProf 采集目录转换为可验证的独立 HTML 性能报告。
+
+本技能负责：
+
+1. 识别 CANN、msprof、设备、可执行文件和应用工作目录；
+2. 按请求模块规划最少且不重复的 profiler replay；
+3. 对命令结果和产物进行语义校验，安全复用已完成采集；
+4. 构造统一报告载荷；
+5. 生成交互式 HTML，并明确区分“可用、缺失、不可支持”；
+6. 输出机器可读的验证结果和性能计时。
+
+不得推测或伪造 profiler 未提供的指标。缺少证据时，必须显示不可用原因，或在非定向报告中明确省略。
+
+## 输入模式
+
+### 1. 完整采集并生成报告
+
+需要：
+
+- `--operator-path`：算子工程根目录；
+- `--output`：采集和报告输出目录；
+- 可自动发现或显式指定的 `--app`；
+- 应用必需参数，使用可重复的 `--app-arg`；
+- 可选的 `--kernel-name`。
+
+```bash
+python scripts/run_pipeline.py \
+  --operator-path /path/to/operator \
+  --output /path/to/output \
+  --preset complete
+```
+
+### 2. 只使用已有采集结果生成报告
+
+已有目录必须包含 `collection_manifest.json`。
+
+```bash
+python scripts/run_pipeline.py \
+  --mode visualize \
+  --output /path/to/collection \
+  --preset complete
+```
+
+也可直接运行：
+
+```bash
+python scripts/visualize.py \
+  --input /path/to/collection \
+  --output /path/to/report \
+  --preset complete
+```
+
+### 3. 定向生成模块
+
+```bash
+python scripts/visualize.py \
+  --input /path/to/collection \
+  --output /path/to/report \
+  --feature roofline \
+  --feature timeline \
+  --feature cache
+```
+
+查看可用特性：
+
+```bash
+python scripts/visualize.py --list-features
+python scripts/visualize.py --explain source
+```
+
+不得自行创造特性名称。
+
+## 标准工作流
+
+### 步骤 1：判断执行模式
+
+- 用户提供算子工程：默认 `full`；
+- 用户只需要采集：使用 `collect`；
+- 用户已有 `collection_manifest.json`：优先 `visualize`，不得重复采集；
+- 只需要检查命令规划：先使用 `--dry-run`。
+
+### 步骤 2：解析环境
+
+稳定主机可建立可复用环境档案：
+
+```bash
+python scripts/environment_context.py init \
+  --profile /stable/path/msopprof_environment.json \
+  --base-dir /path/to/operator \
+  --source 'source /usr/local/Ascend/ascend-toolkit/set_env.sh'
+```
+
+环境档案只允许复用稳定的 CANN 环境变量、`msprof` 路径和 CLI 能力信息。它不得跳过算子相关的可执行文件、Kernel、调试符号、插桩和产物校验。
+
+涉及环境复用或失效时，读取 `references/environment-and-failure.md`。
+
+### 步骤 3：执行短时预检
+
+正式采集前默认执行一次 `BasicInfo` canary：
+
+- `--launch-count=1`；
+- 使用解析出的应用工作目录；
+- 使用短时超时；
+- 校验返回码和实际产物。
+
+超时、非零返回或语义空产物均视为基础设施失败。立即中止，不得继续执行 Occupancy、Roofline、Timeline、Source 等昂贵采集。
+
+所有 profiler 命令必须在独立进程组中运行。超时后先终止、再强制清理完整进程树，并保存日志和诊断信息。
+
+### 步骤 4：选择最小采集计划
+
+根据请求页面反推采集块，并执行语义去重：
+
+- `Roofline` 已包含标准 Default 指标时，不额外执行相同 Default replay；
+- `MemoryDetail` 缺失时，可在 Roofline 产物通过内存模块语义校验后复用；
+- Raw Data 优先复用 MemoryDetail，其次复用 Roofline；
+- 单次精确 Kernel、单次 launch 的成功 preflight 可复用为 Discovery；
+- Timeline、Source、Occupancy 等语义独立模块不得仅因 CLI 支持逗号组合而合并。
+
+详细规则读取 `references/collection-workflow.md`。
+
+### 步骤 5：语义校验产物
+
+命令返回码为 0 不等于采集成功。必须校验：
+
+- profiler 输出目录存在；
+- 必需文件存在；
+- 产物中包含可解析、非空且符合模块语义的数据；
+- alias/reuse 的来源和原因已写入 manifest；
+- 顶层 `_internal/run_state.json` 为 `completed`，才允许后续复用。
+
+Source 需要精确构建树中的 `.debug_line`。`-g` 是编译参数，不是 msprof 参数。不得把二进制 printable strings 当作完整源码映射。
+
+### 步骤 6：独立构建报告模块
+
+支持页面：
+
+- `details`：基本信息、核占用率、计算、内存和建议；
+- `roofline`：实测点、带宽线、算力上限和交互坐标；
+- `timeline`：原生事件、lane、范围选择和切片详情；
+- `cache`：Hit/Miss、Block、Cache family 和统计；
+- `onchip-memory`：仅使用编译器 `memory_info.json`；
+- `source`：源码文件、行、地址、指令和显式关联；
+- `warp-stall`：仅使用 SIMT/PCSampling 证据；
+- `instruction-timeline`：仅使用受支持的指令时间线产物；
+- `raw-data`：原始 CSV 表格。
+
+模块数据合同读取 `references/visualization-contract.md`。
+
+### 步骤 7：生成完整特性报告
+
+要在同一报告中展示所有支持页面，并对缺失模块保留诊断页，使用：
+
+```bash
+python scripts/visualize.py \
+  --input /path/to/collection \
+  --output /path/to/report \
+  --feature details \
+  --feature roofline \
+  --feature timeline \
+  --feature cache \
+  --feature onchip-memory \
+  --feature source \
+  --feature warp-stall \
+  --feature instruction-timeline \
+  --feature raw-data \
+  --unavailable-policy explain \
+  --report-name msopprof_complete_report.html
+```
+
+报告较大时可用 `--compress-payload on` 将载荷以 gzip 内嵌（体积约降低一个数量级，需现代浏览器解压）；默认 `off` 为纯 JSON 内嵌，兼容性最好。两种模式渲染内容一致。
+
+需要预估各 preset 的采集耗时（不重跑 profiler）时：
+
+```bash
+python scripts/estimate_runtime.py \
+  --timing /path/to/output/_internal/timing_summary.json
+```
+
+### 步骤 8：验证与交付
+
+运行结构和真实数据验证：
+
+```bash
+python scripts/self_check.py \
+  --collection /path/to/collection \
+  --output /path/to/validation-output
+```
+
+交付时至少说明：
+
+- HTML 报告路径；
+- `report_index.json`；
+- 可用模块；
+- 不可用模块及原因；
+- 运行耗时和峰值内存；
+- 验证是否通过。
+
+不得让用户打开 `templates/report_template.html`。应打开由 `--report-name` 指定的最终报告，并返回其绝对路径。
+
+## 输出合同
+
+默认输出包括：
+
+```text
+OUTPUT/
+├── collection_manifest.json
+├── feature_catalog.json
+├── 00_discovery/
+├── 01_details/
+├── 02_roofline/
+├── 03_timeline/
+├── 04_source/
+├── 05_warp_stall/
+├── 06_instruction_timeline/
+├── 07_memory_detail/
+├── 08_raw_data/
+├── 09_timeline_detail/
+├── 10_kernel_scale/
+├── 11_onchip_memory/
+├── _internal/
+├── report_payload.json
+├── report_index.json
+└── report.html
+```
+
+`report_index.json` 是机器可读交付回执。`collection_manifest.json` 是采集真源。
+
+## 强制规则
+
+1. 不得伪造缺失指标或从不等价数据推导模块。
+2. `memory_info.json` 缺失时，不得用 MemoryDetail 计数伪造片上内存分配寿命和地址。
+3. 不得复用 `running`、`aborted`、超时、非零返回或语义空的采集结果。
+4. 采集目录不得具有 group/other write 权限；发现后应修正并记录。
+5. `--app` 一旦指定即为权威；未指定时必须记录候选排序和选择理由。
+6. 应用工作目录默认是 `--operator-path`，不是调用命令时的 shell 目录。
+7. Timeline 和 Source 成本较高；只有请求其独有证据时才执行。
+8. 报告页面必须使用同一 canonical payload，不得为不同页面重复解析并产生不一致数据。
+9. 完整报告允许模块不可用，但必须提供证据和下一步动作。
+10. 所有正式提交不得包含 `.pytest_cache`、`__pycache__`、`*.pyc`、运行日志或历史验证结果。
+
+## 参考资料
+
+按需读取，避免一次性加载全部内容：
+
+- `references/collection-workflow.md`：采集计划、参数和 replay 去重；
+- `references/environment-and-failure.md`：环境档案、预检、超时和诊断；
+- `references/data-contract.md`：manifest、alias、可用性和输出真源；
+- `references/visualization-contract.md`：各可视化模块的数据与交互合同；
+- `references/validation-and-performance.md`：验证、浏览器检查和性能门禁。

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/VERSION

@@ -0,0 +1,10 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+3.4.0

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "msopprof-visualization",
+  "evals": [
+    {
+      "id": 1,
+      "config": {"ascend_platforms": ["A2"], "timeout": 900},
+      "prompt": "我有一个算子工程，准备采集完整的 msOpProf 数据并生成中文 HTML 可视化报告。请说明应该使用哪套流程与脚本、执行顺序，以及会产出哪些交付文件。",
+      "expected_output": "1. 回复应说明使用统一的 run_pipeline.py 流程（而不是散装脚本拼凑），先执行 BasicInfo/preflight 预检\n2. 回复应说明按最小非重复计划采集，最终交付 HTML 报告与 report_index.json 交付回执",
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "config": {"ascend_platforms": ["A2"], "timeout": 900},
+      "prompt": "我已经有 collection_manifest.json，只想重新生成 Roofline、Timeline 和 Cache，不要重新采集。请给出应该执行的模式与参数，不需要真的执行。",
+      "expected_output": "1. 回复应选择 visualize 模式（不重新采集），并对 roofline、timeline、cache 各传入一次 --feature\n2. 回复应说明该模式下不会触发新的 msprof 采集/replay",
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "config": {"ascend_platforms": ["A2"], "timeout": 900},
+      "prompt": "数据里没有 memory_info.json。有同事建议直接用 MemoryDetail 计数画片上内存分配图。这样可以吗？请说明理由和处理方式。",
+      "expected_output": "1. 回复应拒绝在缺少 memory_info.json 时伪造 allocation 地址、lifetime、bank 等片上内存数据\n2. 回复应说明应输出该模块不可用的诊断（按 unavailable 策略说明原因），而不是用 MemoryDetail 计数硬凑",
+      "expectations": []
+    },
+    {
+      "id": 4,
+      "config": {"ascend_platforms": ["A2"], "timeout": 900},
+      "prompt": "请用已有采集数据生成包含全部模块的报告，即使某些模块没有数据也要说明原因。请说明需要显式请求哪些页面、以及用什么策略解释缺失数据。",
+      "expected_output": "1. 回复应说明要显式请求全部九个页面（含 onchip-memory、instruction-timeline 等）\n2. 回复应使用 --unavailable-policy explain，对缺数据的模块说明原因而不是静默略过",
+      "expectations": []
+    }
+  ]
+}

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/references/collection-workflow.md

@@ -0,0 +1,91 @@
+# 采集工作流与命令规划
+
+## 目标
+
+用最少的 profiler replay 覆盖用户请求的模块，同时保证不同模块使用的数据语义一致。
+
+## 能力优先
+
+没有有效环境档案时，先执行并保存：
+
+```bash
+msprof op --help
+```
+
+只使用当前安装版本实际暴露的选项和指标名称。必须保留原始大小写，例如 `PCSampling` 与 `PcSampling`。
+
+## 特性与采集块
+
+| 报告能力 | 主要采集块 | 首选指标或产物 | 说明 |
+|---|---|---|---|
+| Details/Occupancy | `details` | `Occupancy` | 核与子核占用率 |
+| Compute/Memory/Advice/Cache | `memory_detail` | `MemoryDetail` | 缺失时可校验 Roofline 产物后复用 |
+| Roofline | `roofline` | `Roofline` | 同时可能提供标准 CSV 指标族 |
+| Timeline | `timeline` | `PipeTimeline` | 独立 replay，不与普通计数器合并 |
+| Source | `source` | `Source` | 精确构建树必须包含 `.debug_line` |
+| Warp Stall | `warp_stall` | `PCSampling`/`PcSampling` | 需要 SIMT 证据或显式请求 |
+| Instruction Timeline | `instruction_timeline` | `instrTimeLine` > `TimelineDetail,Default` > `TimelineDetail` | 按当前 CLI 能力选择 |
+| Raw Data | `raw_data` | 标准 CSV | 优先 alias MemoryDetail/Roofline |
+| On-Chip Memory | `onchip_memory` | `memory_info.json` | 不执行 msprof replay |
+| KernelScale | `kernel_scale` | `KernelScale` | 目前主要作为定向采集数据 |
+
+## 去重规则
+
+1. 精确 Kernel 且 `launch-count=1` 时，成功的 BasicInfo canary 可作为 Discovery。
+2. `Roofline` 已包含完整标准 CSV 时，不再执行独立 Default。
+3. `MemoryDetail` 不可用时，只有 Roofline 产物通过计算、内存、缓存和建议合同后，才可 alias。
+4. Raw Data 依次尝试复用 MemoryDetail、Roofline、Details。
+5. 如果 `Default` 不存在，可用一个命令采集当前 CLI 暴露的标准计数器：
+
+```text
+ArithmeticUtilization,L2Cache,Memory,MemoryL0,MemoryUB,PipeUtilization,ResourceConflictRatio
+```
+
+6. `--independent-default` 只用于有意研究跨 replay 方差。
+7. 不得复用超时、非零、partial、empty 或顶层状态非 `completed` 的结果。
+
+## Source
+
+- `-g` 必须加入实际 Kernel/可执行文件的构建命令；
+- `Source` 是 msprof 指标，`-g` 不是 msprof 参数；
+- 调试符号检查必须限制在所选可执行文件的所属构建树；
+- sibling build 中的符号不能满足当前 Source 门禁；
+- 可使用用户提供的 `--debug-rebuild-command` 条件重建，不得硬编码工程命令。
+
+## 可执行文件与工作目录
+
+- 显式 `--app` 优先级最高；
+- 自动发现时，NPU 构建目录（如 `build_npu`）优先于普通 host build；
+- 记录全部候选、评分、歧义和最终选择；
+- `--app-cwd` 默认等于算子根目录，以确保相对输入文件可解析。
+
+## 常用命令
+
+完整采集：
+
+```bash
+python scripts/run_pipeline.py \
+  --operator-path OP \
+  --output OUT \
+  --preset complete
+```
+
+定向采集 Source：
+
+```bash
+python scripts/run_pipeline.py \
+  --operator-path OP \
+  --output OUT \
+  --mode collect \
+  --feature source \
+  --debug-rebuild-command '用户现有的带 -g 构建命令'
+```
+
+只重绘已有数据：
+
+```bash
+python scripts/run_pipeline.py \
+  --mode visualize \
+  --output OUT \
+  --preset complete
+```

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/references/data-contract.md

@@ -0,0 +1,63 @@
+# 数据合同与真源规则
+
+## 真源
+
+- `collection_manifest.json`：采集块、命令、状态、alias 和 artifact 的唯一真源；
+- `feature_catalog.json`：请求特性到采集能力的映射；
+- `report_payload.json`：报告页面使用的 canonical payload；
+- `report_index.json`：交付回执、请求页面、渲染页面和不可用模块；
+- `_internal/run_state.json`：顶层复用门禁。
+
+## 采集块状态
+
+建议使用：
+
+- `ok`：命令和语义校验通过；
+- `aliased`：复用另一个语义完整的采集块；
+- `partial`：存在部分产物但不能满足完整合同；
+- `empty`：返回成功但没有可用语义数据；
+- `unavailable`：当前 CLI、架构或输入不支持；
+- `failed`：命令失败；
+- `skipped`：因依赖、circuit breaker 或用户选择跳过。
+
+alias 必须记录来源块和复用原因。
+
+## 路径
+
+manifest 内 artifact 路径使用相对 manifest 的 POSIX 路径。不得写入仅在采集机器有效的临时绝对路径作为唯一定位信息。
+
+## 可用性
+
+报告中每个请求页面必须具有明确状态：
+
+- 有语义数据：渲染模块；
+- 定向请求但缺失：渲染诊断页；
+- preset 请求且策略允许省略：写入 `omitted_modules`；
+- 不得使用空白图表冒充成功。
+
+## 不可替代的数据
+
+- On-Chip Memory 必须使用 `memory_info.json`；
+- Source 必须使用真实源码快照、行映射、指令映射和关系；
+- Warp Stall 必须使用 SIMT/PCSampling 证据；
+- 指令时间线必须使用受支持的指令级 timeline 数据；
+- MemoryDetail 计数器不能替代 allocation address、lifetime 或 bank/group 信息。
+
+## 调试导出
+
+Memory topology 每个 Block 导出：
+
+```text
+_debug/memory_edges/block_{ID}_edges.csv
+_debug/memory_edges/block_{ID}_bandwidth.csv
+_debug/memory_edges/block_{ID}_requests.csv
+```
+
+Source 导出：
+
+```text
+_debug/source/source_files.csv
+_debug/source/source_lines.csv
+_debug/source/instructions.csv
+_debug/source/source_instruction_relations.csv
+```

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/references/environment-and-failure.md

@@ -0,0 +1,82 @@
+# 环境、预检与失败处理
+
+## 环境档案
+
+环境档案用于复用稳定主机上的：
+
+- 经过筛选的 CANN 环境变量；
+- `msprof` 绝对路径和文件身份；
+- `msprof op --help` 的完整能力清单；
+- 主机和来源脚本元数据。
+
+以下变化使档案失效：
+
+- 主机身份变化；
+- 来源脚本路径、时间戳或内容变化；
+- `msprof` 文件身份变化；
+- 档案缺少必需字段。
+
+档案不得缓存算子相关检查。
+
+## BasicInfo canary
+
+正式采集前执行短时 canary：
+
+- 独立输出目录；
+- `--launch-count=1`；
+- 解析后的 `--app-cwd`；
+- 默认短时超时；
+- 校验 OpBasicInfo 或可用 visualize payload。
+
+以下任一情况立即中止：
+
+- 超时；
+- 返回码非零；
+- 返回码为 0 但没有可用产物；
+- 设备或目录权限错误。
+
+## 进程隔离
+
+每个 msprof 命令必须在新 session/进程组中执行。超时处理顺序：
+
+1. 标记命令超时；
+2. 向完整进程组发送终止信号；
+3. 等待短暂清理窗口；
+4. 强制清理仍存活的后代进程；
+5. 写入 stdout、stderr、heartbeat 和进程诊断；
+6. 默认触发 circuit breaker，跳过后续昂贵模块。
+
+## 输出目录权限
+
+msprof 可能在输出目录对 group/other 可写时返回 0 但不生成产物。创建输出目录后，应移除 group/other write 位，并将修正写入：
+
+```text
+_internal/output_permission_fixes.json
+```
+
+## 诊断内容
+
+共享设备或锁问题发生时，尽可能收集：
+
+- `npu-smi info`；
+- `/proc/locks`；
+- Ascend `sink_file_mutex_*` 文件身份；
+- holder/waiter PID、状态、wchan、命令行、父 PID、工作目录；
+- 进程快照；
+- 当前命令、工作目录和完整日志片段。
+
+诊断保存到：
+
+```text
+_internal/diagnostics/{stage}/
+```
+
+## 状态与复用
+
+顶层 `_internal/run_state.json` 仅允许：
+
+- `running`；
+- `completed`；
+- `aborted`。
+
+只有 `completed` 可作为复用来源。发现上次状态为 `running` 或 `aborted` 时，即使 per-block state 文件存在，也不得自动复用。

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/references/validation-and-performance.md

@@ -0,0 +1,63 @@
+# 验证与性能门禁
+
+## 提交前结构检查
+
+- 目录名与 frontmatter `name` 一致；
+- 目录名为 `{domain}-{name}`、kebab-case；
+- 主入口为 `SKILL.md`；
+- 参考文档位于 `references/`；
+- 模板位于 `templates/`；
+- 脚本位于 `scripts/`；
+- 评测位于 `evals/evals.json`；
+- 不包含缓存、编译产物、运行报告、日志、历史验证结果。
+
+## 代码检查
+
+```bash
+python scripts/self_check.py
+```
+
+检查 Python AST、模板占位符、YAML frontmatter、JSON 格式、路径引用和禁用文件。
+
+## 真实数据集成测试
+
+```bash
+python scripts/self_check.py \
+  --collection COLLECTION \
+  --output VALIDATION_OUT
+```
+
+必须验证：
+
+- 所有 9 个报告页面均被请求；
+- 有数据模块正常渲染；
+- 无数据模块生成诊断页而不是伪造图；
+- HTML 内嵌 JSON 可解析；
+- 内嵌 JavaScript 通过 `node --check`（Node 可用时）；
+- 页面在 Chromium 中无 page error 和 console error；
+- 每个 tab 可激活；
+- Source、Timeline 和 Raw Data 页面具有实际内容；
+- 输出 `validation_result.json`。
+
+## 性能门禁
+
+默认建议：
+
+- 真实数据完整重绘：不超过 12 秒；
+- 峰值常驻内存：不超过 512 MiB；
+- 报告能够离线打开；
+- compact payload 默认开启。
+
+大型 Source/Timeline 数据可通过：
+
+- `--max-trace-events`；
+- `--max-raw-rows`；
+- `--compact-payload`；
+- 避免 `--pretty-payload`。
+
+计时回执：
+
+```text
+_internal/visualization_timing.json
+_internal/pipeline_timing.json
+```

package/assets/ops-direct-invoke/skills/ops-profiling/msopprof-visualization/references/visualization-contract.md

@@ -0,0 +1,86 @@
+# 可视化模块合同
+
+## 通用规则
+
+1. 所有页面使用同一个 `report_payload.json`；
+2. 数据解析与页面渲染分离；
+3. `0` 是有效数据，`NA` 表示缺失；
+4. 不得通过视觉插值补齐不存在的数据；
+5. 页面宽度自适应，不依赖固定大屏宽度；
+6. 报告必须离线可打开，不依赖远程资源。
+
+## Details
+
+包含：
+
+- 基本信息和各 Block duration；
+- Core/Subcore Occupancy；
+- Compute pipeline、breakdown、wait/conflict 和 counters；
+- Memory workload topology、带宽、请求数和原生表；
+- profiler advice。
+
+Occupancy 的异常值颜色表示统计偏离，不表示性能结论。必须保留原始 core/subcore 映射。
+
+## Memory topology
+
+执行绑定优先级：
+
+```text
+table_per_block[i] <-> core_memory_map[i]
+```
+
+`core_no` 是物理核元数据，可能在 dispatch 中重复，不能作为 Block ID 选择键。
+
+每条边必须包含方向、数值、Block 和 dispatch 绑定。相反方向是两条独立边。边的 label 必须绑定到固定 `edge_id`，不得使用“最近连线”推断。
+
+## Roofline
+
+必须保留：
+
+- 所有有效 chart group；
+- 所有实测 point；
+- 带宽、算力上限、ridge point；
+- 算术强度和实测性能；
+- pointer crosshair、point hover 和 curve hover。
+
+不得过滤未知但合法的图表名称。
+
+## Timeline
+
+必须保留原始事件开始时间、持续时间、PID/TID/lane 和 args。交互包含：
+
+- 缩放、适配、重置；
+- 范围选择；
+- Slice Detail；
+- Slice List；
+- event count 与 payload 一致。
+
+## Cache
+
+必须展示真实 Hit/Miss 计数或比率、Block 和 cache family。没有 cache event cell 时显示明确空状态，不能复制同一 Block 数据填满热力图。
+
+## Source
+
+必须建立：
+
+- file；
+- line；
+- instruction；
+- address/opcode/pipe；
+- line-to-instruction 与 instruction-to-line 关系；
+- 可用时的 stall/GPR 状态。
+
+Source 页面不得只显示头文件，也不得只提取二进制 printable strings。
+
+## On-Chip Memory
+
+仅使用 `memory_info.json`，展示 allocation、地址、lifetime、bank/group 和执行顺序。缺失时输出诊断页。
+
+## 不可用页面
+
+诊断页至少包含：
+
+- 模块名称；
+- 不可用原因；
+- 当前证据；
+- 需要补充的 artifact 或采集动作。