vllm-ascend-workspace: Skill for Claude Code

Ascend Profiling Analysis

Status: experimental / beta. 当前 PR 主要提供：远端 pipeline、evidence-chained report、HTML 三级聚焦视图、stage selector。Knowledge 已分层：kernel 分类规则（kernel_signatures.yaml:match_rules）、attention 家族判定（attention_families.yaml:cheat_sheet.resolver）、diagnosis 阈值与文案（diagnosis_rules.yaml）、segment 层锚点先验（segmentation_rules.yaml）均为运行时加载的 YAML；仍在 Python 内的是 segment.py 切分策略、classify.py block 拆分、以及 finding 的触发条件（见 Knowledge map）。新模型 / 新算子族碰到问题时，优先改 knowledge YAML；改 Python 前请把 counterexample 落到 knowledge/known_counterexamples.md。

Remote substrate rule: use .remote-dev remote tools for ad hoc remote read/edit/bash/search/patch work around profiling roots and generated reports. Use this skill for the domain analysis workflow and keep its scripts as the compatibility backend for managed VAWS sessions.

读取 Ascend NPU torch profiler 的产物 (kernel_details.csv, trace_view.json, op_summary, communication.json 等)，做 normalize → segment → summarize → cross-rank → diagnostics → report 的端到端分析，产物全部可追溯到原始 row range。

本 skill 只消费已经采集好的 profiling root，不负责采集，不负责服务生命周期，不负责 benchmark。

Use this skill when

• 用户提供一个 profiling root 路径（远端或工作区路径），或者 ascend-profiling-collection 写出的 manifest.json，要求分析。
• 用户问 step / layer / operator 统计、跨 rank 对齐、bubble、AICPU、wait anchor。
• 用户怀疑通信慢、EP 负载不均、快慢卡、陪跑/dummy rank、workload 非对称。
• 用户需要带 evidence 链的 report.md / report.xlsx / report.html（HTML 报告是单文件零依赖，含交互式 Single-step Inspector、bubble tracing axis、可缩放多流时间轴、46 字段算子卡）。
• 用户要在多个 profiling root 之间扫一遍 (sweep) 并对比。

Do not use this skill when

• 任务是 HBM / 显存归因 → 用 ascend-memory-profiling。
• 任务是启停服务 → 用 vllm-ascend-serving。
• 任务是吞吐/性能 benchmark → 用 vllm-ascend-benchmark。
• 任务是采集新的 torch profiler 数据（起服务、控 profile 窗口、跑 workload、analyse） → 用 ascend-profiling-collection。
• profiling root 还没采到 kernel_details.csv（采集阶段失败） → 先回到 collection skill 排查；本 skill 不做补救。

Critical rules

• 准确性优先于覆盖率：宁可报错或留 low confidence，也不输出无法追溯的结论。
• 远端解析：profiling root 通常几十 GB，禁止全量拉回本地解析。本地只做静态检查、schema 校验、产物 manifest 阅读。真实 analyze 在远端容器里跑，必要时把 report/ 目录拉回本地。
• 入口稳定：agent 调用 profile_analyze.py / profile_sweep.py，不要绕过去手写 python3 -m ascend_profile.analyze 命令。
• manifest-aware：当 ascend-profiling-collection 产物可用时，优先把 --manifest <run_dir>/manifest.json 喂给 profile_analyze.py，让本 skill 自己从 manifest 里读 remote_profile_root / analysis_status。analysis_status != "ok" 直接拒绝，不要静默跳过。
• 进度协议：进度走 stderr，前缀 __VAWS_PROFILE_ANALYSIS_PROGRESS__=<json>。最终结果走 stdout，单个 JSON 对象。
• 本地状态：本 skill 的本地状态全部放在 .vaws-local/profiling-analysis/runs/<timestamp>_<tag>/（untracked）。远端工作目录默认 /tmp/ascend_profile_framework。
• 不在算法里硬编码层数 / 模型语义：层数不能写成 Python 规则。已知模型的结构字段必须来自 config.json（显式提供、Hugging Face、ModelScope 或已登记本地 catalog）或已验证的 profile-visible hint；模糊族名（如 dsv4 / qwen3.5）必须枚举具体 variants 后逐个匹配，不能直接猜层数。量化和数据格式只影响权重大小、dtype 和效率解释，不作为层数/结构变体。