| name | model-infer-perf-breakdown |
| description | NPU 性能数据拆解技能。把 kernel_details.csv 按用户描述的模型结构切成 component
实例（每层 attn / ffn / moe…），再按用户给的 cluster 规则把 component 内部算子
分桶，生成 wall_ms / bubble_ms 中位数 + 异常 layer 的单页 HTML。
触发场景：分析 NPU prof / 拆解大模型性能 / 找抖动 layer。
|
NPU 性能数据拆解技能
输入一份 prof（kernel_details.csv + trace_view.json），结合用户对模型结构的口头描述，先把 op 序列切成 component 实例，再按 cluster 规则统计每类计算的 wall_ms + bubble_ms 中位数 / 抖动 / 异常 layer，输出一页可读的 HTML。内部指标字段用 *_ms，HTML 展示按量级自动使用 µs 或 ms。
工作流
Step 0: 收齐 prof 路径 + 模型脚本路径 (硬约束) → <run_dir>/inputs.json
Step 1: kernel_details.csv → raw_ops.json (单 step 提取)
Step 1.5: (可选,默认不开) 调用 operator-theoretical-perf → operator_analysis.csv → 合并理论列到 raw_ops_details.json
Step 2: Phase 0a 用户描述模型 → structure_spec.json
Phase 0b 敲定每个 component 的 stream sample 范围 (必须用户 ack)
→ sample_ack.json
Phase 1 跑 detect_structure → structure_draft.json (component 实例表)
Phase 1.5 复读 warnings 让用户 ack
Step 3: 用户和 agent 对话定 cluster 规则 → network_spec.json
→ index.html（含 theory median 列）
Step 4: 按 component 切 csv / trace → splits/ (单层下钻)
Step 5: 洞察归纳（agent 语义判断 + 脚本统计） → insights/
每个 Step 各自的脚本 docstring 里有完整 schema 与算法描述；本文档只列契约与 CLI。
工作目录约定
跑本 skill 的 agent 第一步（早于 Step 1）必须先和用户敲定一个 <run_dir>——本次 skill 所有产物的落盘根，下文 CLI 里出现的 <run_dir>/ 都指这个目录。默认建议 ./perf_breakdown/<label>/，<label> 由用户给（如 <network>_baseline / <network>_variant）；用户也可以直接指定绝对路径。不存在就 mkdir -p。
进 <run_dir> 先查历史产物，再判档复用：每次跑 skill，agent 在做新的对话 / 脚本调用前，必须先列 <run_dir> 已有文件 + 读 HISTORY.md（如果有），然后跑 Step 1 出新 raw_ops.json（落到 raw_ops.next.json 以免覆盖），和上一 run 做自动 diff，判出 小改 / 中改 / 大改 三档之一，再按对应档位复用产物：
| 档 | 触发信号 | 复用范围 |
|---|
| 小改 | kernel 集合完全相同；anchor count 偏差 = 0；上一 sample 的 stream anchors 在相近位置命中 | structure_spec / structure_draft（sample 平移） / <network>_spec 全复用；跳过所有对话 |
| 中改 | 出现新 normalized_name；anchor count 偏差 ≤ 10%；sample 偏移 > 5 row；shape 分布漂移 | structure_spec 复用 + 回显问；重走 Phase 0b 重出 sample；<network>_spec 增量补 rule |
| 大改 | anchor count 偏差 > 10%；总 op 数偏差 > 30%；关键 anchor 消失 | 重走 Phase 0a / 0b；<network>_spec 当参考但逐条审 |
判档后 agent 复述一句结论给用户 ack（如"prof 相对 <prev_label> 是中改：MoE 新增 AddRmsNormCast，sample 偏移约 80 行。打算 B 档复用，对吗？"），用户不同意直接按用户给的档位走。
首次跑（<run_dir> 空）跳过 diff 走全量流程。完整信号定义与判档规则见 references/reuse_policy.md。
反模式
禁止修改用户提供的任何原始文件（prof / modeling 源码 / config 等）；产物只写到 <run_dir>/。
前置物料 checklist（Step 1 之前必走）
跑本 skill 在做任何 prof 解析之前，agent 必须和用户敲齐下列物料；任一缺失或未确认即 abort，不要带着空缺/默认值往下走。
| 物料 | 强度 | 缺失/未确认行为 |
|---|
prof 路径（kernel_details.csv + trace_view.json） | 硬约束 | 文件不存在直接 abort |
模型脚本路径（modeling*.py + 相关 module 文件） | 硬约束 | 用户说"没有/不方便"也 abort——stream sample ack 流程依赖它；用户应当先去拿到再回来 |
<run_dir> 目录 | 硬约束 | 不存在则 mkdir -p |
| phase + device 选择（多卡 / 多采集会话时） | 硬约束 | 必须列出可选项让用户挑；不允许 agent 自作主张默认选第一个 |
Ascend prof 有两种主流目录布局（A 类 torch_npu.profiler / B 类原生 msprof），各自的 csv / json 落在哪、多卡怎么分目录见 references/prof_layouts.md。agent 看到 prof 目录后先识别是哪一类，再按对应位置取 kernel_csv / trace_json；多卡 / 多采集 / 多 phase 任一维度组合数 > 1 时枚举所有 (phase, rank/device) 让用户挑，每个组合各起一个 sub <run_dir> 独立跑。
每个子 run 的 inputs.json（agent 写）：
{
"prof_dir": "/abs/path/to/<prof 根目录>",
"kernel_csv": "/abs/path/to/.../kernel_details.csv 或 op_summary_*.csv",
"trace_json": "/abs/path/to/.../trace_view.json 或 msprof_*.json",
"model_script_paths": ["/abs/path/to/modeling_xxx.py", "/abs/path/to/moe_module.py"],
"phase": "decode",
"rank": 0
}
rank 一般 = device_id（每 process 绑一张卡时），分布式训练 rank ≠ device 时由用户给。
后续 detect_structure.py 启动时会校验 inputs.json 存在、model_script_paths 非空且文件存在、phase / rank 字段已填，否则 exit 1。
历史记录（<run_dir>/HISTORY.md）
agent 维护的人类可读运行日志，用途：
- 下一个 agent / 用户进
<run_dir> 时，一眼看清"这个模型之前是怎么拆的、为什么这么拆"
- 跨 run 归因：某次性能变化是因为换了 sample？改了 cluster 规则？还是模型本身改了？（与
compare_runs.py 输出的 history.html 定量对比互补）
契约：
- 进
<run_dir> 时若文件存在 → 必读
- 每次完成
render.py（Step 3 Phase 2 出 runs/<label>/）后 → 必 append 一条
- append-only，按时间从老到新；禁止回头改旧条目
条目字段、写法、撤回规则见 references/history_template.md。
Step 1 — 单 step 提取
python scripts/analyze_kernels.py -f kernel_details.csv -s 2 \
-o <run_dir>/raw_ops.json -d <run_dir>/raw_ops_details.json
作用：从 csv 抽一个稳定 step（默认跳过 step 0 warmup），后续所有分析以单 step 为单位。
输入：kernel_details.csv（同目录通常还有 trace_view.json，Step 4 用，Step 1 不消费）。
输出：
raw_ops.json — 单 step operators[]，每条含 index / org_index（csv 0-based 数据行号）/ normalized_name / duration_us / start_time_us / stream_id / input_shapes / output_shapes。Step 2、3 消费。raw_ops_details.json — 单 step 详情，含 csv 全部字段。Step 4 切片时用。
行号 domain（Excel / org_index / index，三者各自的语义和换算关系）+ AI_CPU drift 注意事项见 references/phase0b_workflow.md 末尾的"行号 domain 速查"。
Fallback 行为：accelerator_core ∈ {AI_CPU, AICPU} 默认剔除；sample 模式严禁加 --keep-ai-cpu（破坏 row-order）。若 profiler 同时记录 HCCL/COMMUNICATION 的 collective summary 行和 Name == AivKernel 的 task fragment 行，Step 1 只保留 summary 行、丢弃可匹配 summary 的 fragment；没有 summary 证据的通信 fragment 必须保留，不能静默丢失。AI_VECTOR_CORE 中的 Gather/Scatter/Reduce/Slice 等仍按普通算子保留。
Step 1.5 — 理论性能注入（可选，默认不启用）
可选步骤——依赖外部 operator-theoretical-perf skill。不启用时 render.py 的 theory median 列自动留空（—）、不阻塞；Step 5 的理论偏离 insight 也自动跳过（输出空 JSON + data_limits 说明）。仅当用户要理论对比、且外部 skill 可用时才启用。
启用时：chip 配置提问可并入 Step 0 前置物料，或推迟到 Step 2 之后、render.py 之前（Phase 0a 的「不要先于此发问」只约束结构类提问，chip 不受限）；理论列合并必须在 render.py 之前完成。
调用外部 operator-theoretical-perf skill（或直接跑其 analyze_operators.py --chip-config <chip>.json），用原始 kernel_details.csv + 用户确认的 chip 生成 <run_dir>/operator_analysis.csv，再把理论列按原 CSV 行序 / org_index 合并回 <run_dir>/raw_ops_details.json：
python scripts/merge_theoretical_columns.py \
--raw-ops-details <run_dir>/raw_ops_details.json \
--operator-analysis-csv <run_dir>/operator_analysis.csv \
-o <run_dir>/raw_ops_details.json
理论列不参与 Step 2 结构拆解；sub-item / TOTAL 粒度理论耗时在 Step 3 渲染时从合并后的 raw_ops_details.json 计算。调用契约、多流选择口径见 references/theoretical_perf_workflow.md。
Step 2 — sample-driven 层检测
Phase 0a：问用户模型结构（必走）
agent 逐字把 references/phase0a_prompt.md 里的 prompt 发给用户，解析答案后自动起 phase 名（①→main、②→mtp_head、③→用户类别名），写 <run_dir>/structure_spec.json 并回显 JSON 让用户确认。schema：
{
"model_hint": "<自然语言>",
"phases": [
{"name": "main", "layers": 6,
"layer_compositions": [
{"layer_range": [0, 2], "components": ["mla", "dense"]},
{"layer_range": [3, 5], "components": ["mla", "moe"]}
]},
{"name": "mtp_head", "layers": 3,
"layer_compositions": [{"layer_range": [0, 2], "components": ["mtp", "moe"]}]}
],
"expected_components": ["mla", "dense", "moe", "mtp"],
"expected_layer_count": 9
}
每个 composition 的层用 layer_range（连续区间，闭区间）或 layer_indices（显式枚举层号）二选一表达，层号均为 phase 内 0-based。当相邻层使用不同 composition、连续区间表达不了时（逐层交替 / 交错结构），用 layer_indices 显式枚举各 composition 占用的层号。下例示意两种 composition 按奇偶层交替（attn_a / attn_b 为占位名，实际填该模型的 component 名）：
"layer_compositions": [
{"layer_indices": [0, 2, 4], "components": ["attn_a", "moe"]},
{"layer_indices": [1, 3, 5], "components": ["attn_b", "moe"]}
]
同一 phase 内各 composition 的层集合不得重叠——重叠（同一层被多个 composition 覆盖）会被 _expand_schedule 判为 hard error 并中止，而非静默取最后一个。
Phase 0b：定 stream sample 范围（必走，必须用户 ack）
核心契约：按 expected_components 去重列表逐项敲定每个 component 的 sample 范围。脚本会把 sample 转成 per-stream stream_samples；每个 component 必须有且只有一个 primary stream，其他确认属于该 component 的流标 auxiliary。归属看语义、不看时间是否重叠：语义上属于该 component 的流，即使与本层时间脱节也写 auxiliary——detect_structure 会发 hard warning auxiliary_stream_temporally_displaced，render 自动把它从 cluster/bubble/TOTAL 剔除并标注、op 仍 matched 保留在 component（op_indices 全集不破、Step 4 split 照切），判定是流级全有全无；只有不属于任何 component 的流（全局通信/采样/IO 等）才留 unmatched。用户 ack 后写 <run_dir>/sample_ack.json；agent 不能跳过 ack 自己往下推。pre / post / inter 不需要给。
两条路径（sample 范围是硬需求，二选一）：
- A 档：用户直接给 row 区间或算子名，agent 对照
raw_ops.json 校验后回贴 ack
- B 档：用户给不出 → agent 读 Step 0 收齐的
model_script_paths 推典型 sample 范围，标注来源后让用户核对
详细步骤、回贴格式、sample_ack.json schema 见 references/phase0b_workflow.md。expected_components 中任一缺失即 ack 未完成，detect_structure.py 启动时 exit 1。
Phase 1：跑 detect_structure
python scripts/detect_structure.py \
-r <run_dir>/raw_ops.json \
--structure-spec <run_dir>/structure_spec.json \
--inputs <run_dir>/inputs.json \
--sample-ack <run_dir>/sample_ack.json \
-o <run_dir>/structure_draft.json
--inputs 和 --sample-ack 在 sample 模式下必传：
--inputs <run_dir>/inputs.json：校验 model_script_paths 非空（Step 0 物料）--sample-ack <run_dir>/sample_ack.json：使用 schema_version: "stream_sample_ack.v1"，校验每个 component 都有 stream_samples[] 且只有一个 primary- 任一校验失败 exit 1，agent 必须回 Phase 0b 补齐
新写入的 sample_ack.json 必须保存为 stream sample schema；Step 2 输入须为此 schema。
hard / ambiguous warnings（含 auxiliary_stream_temporally_displaced）默认 exit 1；agent 必须先逐条复读给用户，用户明确接受后才可加 --accept-warnings 重跑放行。
输出 structure_draft.json（下游 Step 3 / Step 4 直接消费）：
mode: "stream_sample_driven"schema_version: "structure_draft.stream.v1"structure_spec — 原样回写samples_used[] — 每 sample 的 stream_samples[]components[] — 扁平表，每条 = 一个 component instance（component_id / layer_idx / phase / type / op_indices[] / stream_segments[] / stream-aware scores；某条 aux 流被判时间脱节时还含 displaced_op_indices[]——该流的 op，render 据此从 cluster/bubble/TOTAL 剔除，但仍在 op_indices 全集内、partition 不破）op_to_component — op index 到 component_id 的反查表unmatched_op_indices[] / unmatched_stream_segments[] — 未归属 op，不能静默丢弃warnings[] — primary/auxiliary stream、op membership、composition schedule、count/shape/ambiguity、temporally-displaced aux stream 类问题，每条含 code + messagevalidation — declared vs detected 层数 / missing_samples / ambiguous_matches
warning codes、validation 字段、匹配算法细节见 detect_structure.py / sample_matching.py docstring。
Phase 1.5：复读 warnings 等用户 ack（必走）
逐条把 warnings[] 复读给用户，列 layer_idx / component / 期望 vs 实测。用户选项："忽略" / "改 0a 重跑" / "改 0b 重跑"。无 ack 视为 Step 2 未结束。
Step 3 — cluster 规则对话 + 渲染
Phase 1：agent 引导用户给 cluster 规则
structure_draft.json 给出 component 实例边界，但每个 component 内部还要进一步分桶才能看出抖动来源。agent 主动和用户对话产出 <run_dir>/<network>_spec.json——每个 component_type 一个 cluster 列表，每个 cluster 一条或多条匹配规则（op_name / op_name_regex / input_shapes_contains / output_shapes_regex / catch_all 等），逐 component_type 让用户确认。
跑完 render.py 后看 unmatched ops 面板，若有未匹配算子回头细化规则直到 unmatched = 0 或用户明确说"剩下的不关心"。
详细工作步骤、规则字段、network_spec.json schema、outlier 选项、cluster / bubble / TOTAL 数值定义、spec 跨 prof 复用规则见 references/cluster_dialogue.md。
网络 spec 存放位置：<run_dir>/<network>_spec.json。同一模型在不同 prof 上复用——新 run 进入工作目录后优先查同名文件，存在就直接读，不必重跑 cluster 对话。
Phase 2：渲染
启用理论时（Step 1.5 已把逐 kernel 理论列合并进 raw_ops_details.json），渲染脚本在 cluster / TOTAL 粒度按 critical stream 聚合理论耗时；未启用则 theory median 列整列留空（—），本段其余多流口径不适用。多流时默认取 observed timeline union 最大的 stream，未选中流视为被覆盖或旁路，不计入该 sub-item 的理论耗时。若某 sub-item / TOTAL 出现多流，agent 应在 <run_dir>/theory_stream_decisions.json 填 semantic_note 说明这些流的语义；若候选流覆盖范围接近，还要同时判断是否覆盖 selected_stream。没有语义说明的多流项会在理论列标 semantic note required。
python scripts/render.py \
-d <run_dir>/structure_draft.json \
-r <run_dir>/raw_ops.json \
--raw-ops-details <run_dir>/raw_ops_details.json \
-s <run_dir>/<network>_spec.json \
--label <label> \
-o <run_dir>/runs/<label>/index.html
（首次渲染也走 runs/<label>/，与输出文件表 / Step 5 回填 / compare_runs 一致；metrics.json 落到同目录。）
如需填写多流语义或覆盖 critical stream 选择，再追加：
--theory-decisions <run_dir>/theory_stream_decisions.json
HTML 主表在 median 后展示 theory median 列（数据来自 Step 1.5 合并进 raw_ops_details.json 的 theoretical_operator_time_us；未跑 Step 1.5 时整列留空 —）；两列都按量级自动显示 µs 或 ms。bubble 行没有 kernel 理论耗时，显示 —。
主报告最后一列固定为 insight：Step 3 初次渲染时保留为空；Step 5 结束后由 agent 写 <run_dir>/runs/<label>/insights/main_report_insights.json，再用 --insight-annotations 重跑 render.py 回填。该列只显示 confidence = high | medium 的洞察，low 不写入主报告。每条回填必须带 category；若不能精准映射到单个模块，由 agent 选择主要归属 target，用 mapping_type: agent_primary 和 mapping_note 说明依据。TOTAL 只是可选主归属之一，只有洞察确实是整体性的才放到 TOTAL，否则优先放到最相关的具体 cluster / bubble 行。同一主报告 row 可以显示多条 insight。
--raw-ops-details 必传：缺了 chip 退化成静态 <span>，无法下钻 per-op 明细。
unmatched gate：render.py 在 compute-core unmatched 比例 > --unmatched-limit（默认 5%） 时 exit 1（通信类 core 不计入该比例）。报错打印按 accelerator_core 的 unmatched 分解：若主要是通信 / 采样 / embedding / IO，加 --accept-unmatched 放行；若有大段 compute 算子漏匹配，回 Phase 0a/0b 补 sample 或声明 component。--unmatched-limit 可调阈值。
输出：
index.html — 单页报告，按 spec 中 component_type 顺序排，每 component_type 一张 cluster / bubble / TOTAL 抖动表，含 unmatched ops 面板。若 cluster 桶之间存在 timeline overlap 或覆盖率异常，HTML 顶部按下列规则插提示面板：
- cluster 覆盖率红字：Σ cluster_wall.median / TOTAL.median < 80% 时插红字 banner，提示大量算子落进 bubble / 未匹配 / 漏算子，查 unmatched 面板与 cluster 规则。
- overlap 黄字警告：median gap ≥ 5% TOTAL，提示"分桶不能直接反映真实性能分布"，列主要重叠桶对 + 占比。
- overlap 浅蓝 info：median gap 0 < x < 5% TOTAL，列出仍存在跨 stream 并发的桶对（过滤掉 < 1µs 的噪声项，最多 8 对），方便定位并发来源，但不影响主表读数。
- 辅流时间脱节提示（浅蓝）：某 aux 流被判 displaced 时，列其 op_count / median wall / %TOTAL，标注"已从 TOTAL/bubble 排除"、op 仍 matched（逐层明细见 splits/）。
metrics.json — compare_runs.py 消费的指标数据；每个 section 含 overlap: {median_gap_ms, median_gap_pct, max_gap_ms, top_pairs[]}、cluster_sum_pct_of_total、displaced（per-stream 脱节摘要）字段。字段名保持 *_ms，HTML 展示层会把小于 1ms 的值显示成 µs。- render 完成时若
<run_dir>/HISTORY.md 不存在，stdout 打 reminder（不 exit 1）。
cluster / bubble / TOTAL 定义、outlier 检测、overlap 度量、规则求值顺序见 render.py docstring。
Step 4 — 按 component 切 csv / trace_view
必跑。skill 的交付契约要求 op 序列被完整切片：每个 component 实例与每段 unmatched op 集合各占一个文件夹，整体严格覆盖 [0, N-1]、无重无漏。新 draft 以 op_indices 为准，component 可以是非连续 op 集合；op_range 只作为 manifest 里的展示 envelope。脚本会自检 partition，draft 与 raw_ops 不匹配时直接 abort。
python scripts/split_artifacts.py \
-d <run_dir>/structure_draft.json \
-r <run_dir>/raw_ops.json \
-f /path/to/kernel_details.csv \
-t /path/to/trace_view.json \
-o <run_dir>/splits/
文件夹命名（直接对应 layer_id 与 component 类型）：
| kind | 命名 |
|---|
| component 实例 | L<idx:03d>_<phase>_<type> |
| pre/post 头尾 | pre / post |
| 相邻 component 间的 gap | gap_L<prev>_<phase>_<type>_to_L<next>_<phase>_<type> |
| 头尾外侧 gap | gap_before_L<next>_… / gap_after_L<prev>_… |
| 疑似未声明的 component | suspected_…（其余结构同 gap） |
每个文件夹内只放两份产物：
kernels.csv — csv 切片（保留 header，首列 org_index）trace_view.json — trace 证据；传 -t 时是该目标 op 的时间包络上下文窗口，可能包含同时间并行的其他目标 op；不传时从 raw_ops 的 op_indices 精确合成
顶层 manifest.json 是 folder → {kind, op_range, op_indices?, ops_count, files} 索引，给下游 / 用户导航用；当目标 op 非连续时才写 op_indices。files.trace_scope 标明 trace 是 op_membership_exact 还是 time_envelope_context。
-f / -t 在标准 prof 包下必传；缺 csv 跳过 csv 切片，缺 trace 时 trace_view.json 从 raw_ops 合成。--dry-run 只打印目标清单不落盘。
Step 5 — 洞察归纳
Step 5 在 Step 3 / Step 4 之后执行，只做洞察层归纳与展示，不重新定义模型结构、不修改 cluster 规则。事实提取与渲染由 scripts/gen_insights.py（两遍：先产事实候选，agent 写 movement_taxonomy.json + annotations.json 后带 --movement-taxonomy/--annotations 再跑）+ scripts/render_insights.py 完成，agent 不手写提取逻辑；候选可靠性 / 是否展示由 agent 用 confidence（high|medium|low）标注。CLI、脚本/agent 边界、五类 insight、HTML 渲染与落盘契约见 references/insight_workflow.md。
默认输出目录：<run_dir>/runs/<label>/insights/，和该 run 的 index.html / metrics.json 放在同一目录下。只有未使用 runs/<label>/ 的老式单 run 输出，才退回 <run_dir>/insights/。Step 5 最后还要生成 main_report_insights.json，并重跑主报告渲染（render.py --insight-annotations），把 high / medium 洞察连同类别和主映射说明填回 runs/<label>/index.html 最后一列。
增量分析（模型迭代 + 历史对比）
模型局部改动后重新 prof 时，不要从零再走一遍 Step 2 对话。复用规则：
network_spec.json 跨 prof 复用：cluster 规则是 op_name + shape pattern，与 layer 位置 / 数量无关，模型改动只要不引入新算子就直接复用。新增算子时只需补一条 rule。structure_spec.json 通常微调：layer 数 / composition 不变就照搬；改了层数 / 加了 MTP 改 0a 重写。- sample 行号需重出：op 在 csv 中的位置随改动平移，Phase 0b 每次都要给。
每个 run 落盘到独立目录：render.py 的 --label <label> + -o <run_dir>/runs/<label>/index.html（首次起就这样，见 Step 3 Phase 2）让每个 run 独占 runs/<label>/；增量 run 只换 <label> 值。同目录同时产 metrics.json（含 label / model_name / outlier / 每个 (component_type, cluster) 的 wall + bubble 指标 + outlier 列表，compare_runs.py 消费）。
对比表：
python scripts/compare_runs.py \
-r <run_dir>/runs/ \
-o <run_dir>/history.html \
[--metric median_ms]
[--baseline <label>]
-r 给目录时自动扫所有 */metrics.json，按 mtime 升序排（早的当 baseline）。也可以列出多个 metrics.json 路径显式指定顺序。
输出 history.html — 多 run 跨版本对比表（Δ% vs baseline + outlier diff），列布局见 compare_runs.py docstring。
输出文件
| 文件 | 阶段 | 说明 |
|---|
<run_dir>/raw_ops.json | Step 1 | 单 step kernel 概要，下游所有脚本消费 |
<run_dir>/raw_ops_details.json | Step 1；Step 1.5 可加列 | 单 step kernel 详情，Step 4 切片用；启用理论性能时合并理论列 |
<run_dir>/operator_analysis.csv | Step 1.5 | 外部 operator-theoretical-perf skill 对原 CSV 加列后的原生产物 |
<run_dir>/theory_stream_decisions.json | Step 3 / 2 | agent 对多流语义的说明（多流场景必填）；必要时覆盖 critical stream 选择 |
<run_dir>/structure_spec.json | Step 2 / 0a | 用户描述的模型结构 |
<run_dir>/structure_draft.json | Step 2 / 1 | component 实例表，Step 3 / 4 输入 |
<run_dir>/<network>_spec.json | Step 3 / 1 | 用户的 cluster 规则，新 run 优先复用同名文件 |
<run_dir>/runs/<label>/index.html | Step 3 / 2 | 单 run 的单页 cluster 抖动报告 |
<run_dir>/runs/<label>/metrics.json | Step 3 / 2 | 单 run 指标，compare_runs.py 消费 |
<run_dir>/runs/<label>/insights/module_bubble.json | Step 5 | 模块长期 bubble 与具体层/模块 bubble 异常 |
<run_dir>/runs/<label>/insights/operator_jitter.json | Step 5 | 算子 / cluster 性能抖动候选与证据 |
<run_dir>/runs/<label>/insights/theoretical_deviation.json | Step 5 | 逻辑 sub-item / TOTAL / operator slot 与理论性能偏离 Top5 |
<run_dir>/runs/<label>/insights/vector_sequence_candidates.json | Step 5 | 连续 vector 区间融合候选，按 pattern 聚合 |
<run_dir>/runs/<label>/insights/data_movement_ops.json | Step 5 | 冗余 Tensor Movement 消除候选：搬运 / 结构变换算子定位、上下文与消除方向 |
<run_dir>/runs/<label>/insights/final_conclusions.md | Step 5 | agent 基于五类 insight 汇总的最终结论与证据索引 |
<run_dir>/runs/<label>/insights/index.html | Step 5 | 五类 insight 的可视化页面 |
<run_dir>/runs/<label>/insights/main_report_insights.json | Step 5 | agent 选择回填到主报告 insight 列的 high / medium 洞察 |
<run_dir>/history.html | 增量 | 多 run 对比表（Δ% vs baseline） |
<run_dir>/HISTORY.md | 每 run 收尾 | agent append 的运行日志，记录复用 / 变更 / 观察 |
<run_dir>/splits/ | Step 4 | 按 component 切的 csv / trace_view，含 manifest.json |
参考
references/kernel_data_guide.md — kernel_details.csv 字段说明references/prof_layouts.md — Ascend prof 两类目录布局（torch_npu / msprof）+ 多卡识别要点references/phase0a_prompt.md — Step 2 Phase 0a 用户结构描述逐字 promptreferences/phase0b_workflow.md — Step 2 Phase 0b stream sample ack 流程 + sample_ack.json schema + 行号 domainreferences/cluster_dialogue.md — Step 3 cluster 规则对话步骤 + network_spec.json schema + 数值定义references/history_template.md — HISTORY.md 条目字段与模板references/reuse_policy.md — prof 变更检测信号 + 三档复用规则references/theoretical_perf_workflow.md — Step 1.5 理论性能注入：外部 skill 调用、CSV 理论列合并、多流选择口径references/insight_workflow.md — Step 5 洞察归纳：五类 insight、脚本/agent 边界、HTML 渲染references/insight_html_template.html — Step 5 洞察页 HTML/CSS/JS 骨架- 各脚本 docstring — 内部算法、阈值推导、edge case 处理
