msagent-profiler-breakdown —— 场景化拆解（一步到位）

定位：合并原 stage-decompose / step-decompose / breakdown-report 三份 skill，一份搞定 阶段归因（level=阶段）→ 单次执行边界（level=单次执行）→ 报告。 场景差异（推理 / 训练 / RL，vllm / sglang / verl / slime…）下沉到场景资源文件 resources/scenarios/<scenario>/<framework>.json，主 skill 不做框架分支。 用户只与本文档交互；scripts/decompose.py 一步产出 breakdown.json（统一拆解树）/ HTML 报告 / findings。

触发与元信息

维度	内容
触发关键词	模型按层拆解、完整性能分析、一键分析、端到端到层内拆解、框架/并行自动识别、多卡 TP/EP/PP 分析
外部依赖	昇腾 Profiling DB（sqlite）与 analysis.db；Python 3 标准库；场景资源 resources/scenarios/；拆解树契约 references/breakdown-schema.md；报告模板 references/report-template.md
权限要求	只读打开 Profiling DB（mode=ro，保留 WAL 恢复）；在工作区读写中间产物与报告
预期输出	breakdown.json（统一拆解树：端到端 → 阶段 + 单次执行分支）+ stage.json（同内容别名，场景信息供 layer-decompose 继承）+ HTML 报告 + findings（8 字段）+ 明细 CSV

一句话调用

python scripts/decompose.py --db <ascend_pytorch_profiler_{rank_id}.db> \
    [--framework vllm|sglang|verl|slime|megatron|mindspeed|fsdp] \
    [--task-type inference|train|rl] [--anchor "forward"] [--inspect-index 0]

最少必给只有 --db；framework / task-type 可省，走自动探测 / 兜底默认 / 由编排层询问用户。

三步流程

第 1 步：场景确认（framework / task-type 判定）

判定优先级（framework 与 task-type 同构）：

1. CLI / 编排层显式指定（--framework / --task-type）→ high。用户可直接说 「请帮我分析下这个 vllm 的 profiling 数据」，此时 framework 由上层输入。
2. 自动探测（从 profiling 数据分析）：STRING_IDS.value 含 vllm% 前缀 → vllm； 存在 verl worker 侧 MSTX 打点名（actor_update / actor_compute_log_prob / ref_compute_log_prob / train_batch）→ verl。框架映射任务类型： vllm/sglang→inference、megatron/mindspeed/fsdp→train、verl/slime→rl。→ high
3. 识别不了 → 询问用户（编排层用 AskUserQuestion 回显候选 + 依据让用户确认/修正）； 仍缺则默认 vllm/inference + 显式告警（task_type_source=default），报告低置信度清单列出。

探测工具：scripts/db_query.py（子命令 string / mstx / pytorch / cann / api）， 先查打点再定规则。判定结果（framework / framework_source / task_type / task_type_source）写入 stage.json，供下游 layer-decompose 经 --framework 继承， 无需重新探测。

第 2 步：执行拆解（按场景资源规则）

引擎 decompose.py 框架无关，按场景资源文件声明式规则执行，主 skill 不过多呈现框架分支：

• 阶段归因：读取 resources/scenarios/<scenario>/<framework>.json 的 stage_decompose.stages（name + scopes + backing），直连 DB 统计每个 stage 的 count / 累计 / 均值 / 最大 / 最小 / 首个。

• 单次执行边界：读取 step_decompose.anchor（默认 forward），锚点 scope 每次出现 记一个 step，按位置（前 2 步 graph_capture/compile）+ 阈值（wall_time > factor×median） 判热身并写 warmup_reason；--skip-first-step 另标首个 step 为疑似 prefill； 剔除后算稳态统计（count/mean/P50/P99/min/max/variance/CV）。

• 锚点优先级：CLI --anchor 显式覆盖 > 场景资源 step_decompose.anchor；锚点为空 （如 RL/训练待核验）→ 跳过 step 拆解并告警。

新增框架 = 在场景目录放一个 <framework>.json（支持 extends 继承父规则），不改引擎， 详见 references/frameworks/README.md。

第 3 步：生成报告（模板即资源，无独立 report skill）

按 references/report-template.md 组织结论先行 HTML（自包含、无 JS 依赖）： 一句话结论 → 逐级耗时（仅列出现过的级别）→ 阶段统计表 → TOP-N 下钻链 → per-step 明细 → 稳态统计 → 异常/漂移 → 低置信度清单 → 建议下一步 → findings（8 字段）。 场景信息（框架/任务类型，用户已知）与守恒自检不做独立章节，守恒缺口告警保留在 findings 中。 同时落盘 findings JSON 与明细 CSV；多 run A/B 对比用 scripts/compare_runs.py。

输入

输入	必填	来源
昇腾 Profiling DB	是	用户给定路径（ascend_pytorch_profiler_{rank}.db / analysis.db）
framework	否	场景确认（CLI > 自动探测 > 询问 > 默认 vllm + 告警）
task-type	否	场景确认（CLI > 框架映射 > 默认 inference + 告警）
anchor	否	覆盖 step 边界锚点（默认取场景资源 step_decompose.anchor）

输出（workspace 落盘）

产物	内容
breakdown.json	统一拆解树：端到端（会话）→ children（阶段... + 单次执行分支含 per-step 序列与稳态统计）+ 框架/任务类型来源 + 守恒自检
stage.json	与 breakdown.json 同内容别名；场景信息供 layer-decompose --framework 继承
<prefix>.html	结论先行报告（模板见 references/report-template.md）
<prefix>_findings.json	结构化结论（8 字段：问题/证据/影响/根因/优化动作/预期收益/验证路径/置信度）
<prefix>_detail.csv / <prefix>_handoff.csv	per-step 明细 / 层拆解交接清单（暂缓期间为占位）

涉及的 skill

skill	职责	状态
msagent-profiler-breakdown	场景确认 + 阶段/单次执行拆解 + 报告，一步到位	在链路内
layer-decompose	单层归属 + 层内归因 + 结构校验（直连 DB）	暂缓保留（经 --framework 继承场景）