msmodeling skills
本目录存放 msmodeling 项目专用的 Claude Code skills，用于把常见性能建模、设备建模和 profiling 辅助任务沉淀为可复用的执行流程。
使用提示：如需在 Claude Code 中启用这些 skills，请将本目录
.agents/skills完整复制到.claude/skills。AI agents 必读：请先阅读项目根目录的 AGENTS.md，了解项目规范和 Skill 体系。
Table of Contents
- msmodeling skills
- msmodeling-env-installer
- model-adaptation
- device_config
- op_mapping
- microbench
- text-generate-executor
- throughput-optimizer-executor
msmodeling-env-installer
msmodeling 环境安装器——将“安装 msmodeling 环境依赖”“创建 myenv”“安装当前仓库 requirements.txt”“配置 PYTHONPATH / HF_ENDPOINT”等明确指向 msmodeling 的请求转换为可执行、可验证、可回溯的环境安装流程。用户只说“安装环境”或“安装依赖”时，需要先确认是否安装 msmodeling 当前仓库的环境依赖。
What it does
引导 AI agent 按 RFC 中定义的流程完成开发环境初始化：
- 仓库根目录校验：确认当前目录包含
README.md和requirements.txt。 - Python 与 uv 检查：要求 Python
3.10+，缺少uv时按镜像安装并解析真实可执行路径。 - 安装路径选择：默认用
uv新建myenv；已有环境 fallback 前检查torch_npu、torch-npu和cudatoolkit。 - 依赖安装与验证：安装
requirements.txt后执行uv pip check --python <venv-python>或python -m pip check。 - 环境变量配置：按需设置当前会话
PYTHONPATH和HF_ENDPOINT=https://hf-mirror.com。
File layout
| File | Purpose |
|---|---|
msmodeling-env-installer/SKILL.md |
Skill 定义、触发场景、安装流程和安全规则 |
msmodeling-env-installer/scripts/install-current-project-deps.ps1 |
Windows PowerShell 自动化安装脚本 |
msmodeling-env-installer/scripts/install-current-project-deps.sh |
Linux/macOS/WSL/Git Bash 自动化安装脚本 |
Quick start
在对话中直接提出明确需求，例如“请帮我安装 msmodeling 环境依赖”“按 README 配置 msmodeling 环境”。如果只说“安装环境”，agent 需要先确认是否安装 msmodeling 当前仓库的环境依赖。
Windows PowerShell 可以从仓库根目录直接运行：
.\.agents\skills\msmodeling-env-installer\scripts\install-current-project-deps.ps1
Linux/macOS/WSL/Git Bash 可以从仓库根目录直接运行：
bash ./.agents/skills/msmodeling-env-installer/scripts/install-current-project-deps.sh
Key constraints
- 不修改
requirements.txt、README 或项目源码。 - 不默认覆盖已有
myenv，也不默认持久化系统级环境变量。 - 网络安装需要用户确认和工具权限授权。
scripts/install-current-project-deps.ps1当前仅适用于 Windows PowerShell；Linux/macOS 使用 README 通用命令。
model-adaptation
TensorCast 新模型接入流程 skill——从仿真命令和 MindStudio Insight raw profiling 出发，引导 agent 运行 model_adapter doctor、审阅 ModelProfile、处理 patch/bug AI task、导出 evidence.yaml 并运行 verify。
What it does
将新模型接入拆成确定性工具和人工 checkpoint：
- 收集两个必需输入：仿真命令和匹配的 raw profiling。
- 运行 doctor，审阅 candidate profile、evidence draft、human questions 和 ai tasks。
- 对需要人工确认的字段生成精确问题，并把确认结果写入
hints.yaml或evidence.yaml。 - 对 patch/bug 场景使用
ai_tasks[].prompt_text驱动用户或用户的 AI 助手生成代码，并要求人工 review。 - 使用
export-evidence导出evidence.yaml，再运行 verify。
File layout
| File | Purpose |
|---|---|
model-adaptation/SKILL.md |
新模型接入的核心工作流、人工 checkpoint 和验证要求 |
Quick start
当用户说“接入新模型”“生成 ModelProfile”“根据 doctor report 继续适配”“处理 patch AI task”“从 doctor report 导出 evidence”时使用该 skill。
Key constraints
- 不凭模型名猜 profile 字段。
- doctor 不生成模型专属 patch 代码，只生成 AI task 和 prompt。
evidence.yaml从doctor_after_profile.json.evidence_draft导出后再人工审阅。- 不提交 raw profiling、本地 walkthrough、私人路径或临时材料。
device_config
设备画像自然语言导入器——通过渐进式对话引导用户将自然语言硬件描述转换为 TensorCast DeviceProfile。
What it does
引导 AI agent 通过渐进式对话流程：
- 渐进收集信息：首轮只问硬件名称、资料来源和粒度偏好，每轮最多 2-3 个问题。
- 维护内部事实表：
confirmed/ambiguous/missing/needs calibration。 - 生成可运行 profile：将用户确认的值、临时估值和兜底默认值全部写入
tensor_cast/device.py。 - 验证 + 输出 CLI 命令：运行导入检查，输出
--device <PROFILE_NAME>可执行命令。
File layout
| File | Purpose |
|---|---|
device_config/SKILL.md |
Skill 定义、约束条件和执行流程 |
Quick start
在 Claude Code 对话中直接提出需求，例如"我要导入新的设备拓扑"，遵循 agent 的渐进式提问，逐步提供硬件规格。
Key constraints
-
DeviceProfile.__post_init__会自动注册 profile，name必须唯一。 -
默认写入
tensor_cast/device.py，只有用户明确要求时才写入tensor_cast/device_profiles/。 -
所有默认值、估值和假设必须对用户可见，列入
needs calibration。
op_mapping
op_mapping.yaml 生成器——将 TensorCast 仿真算子映射到 NPU profiling 内核类型。
What it does
通过并行子 Agent 团队（每个算子一个 Agent）追踪完整的 vLLM→CANN 调用链，生成 op_mapping.yaml。
File layout
| File | Purpose |
|---|---|
op-mapping/SKILL.md |
核心执行流程、六阶段工作流 |
op-mapping/op-mapping-template.yaml |
YAML 模板片段 |
op-mapping/single-op-worker-prompt.md |
单算子 Worker Agent 指令 |
op-mapping/verifier-prompt.md |
验证阶段指令 |
op-mapping/ref/shape_matching_catalog.md |
TC tensor 与 NPU profiling shape 的 10 种差异 |
op-mapping/ref/tc_input_count_rules.md |
tc_input_count 安全使用规则 |
op-mapping/ref/zero_cost_classification.md |
零开销算子分类规则 |
Quick start
收集完所有输入（model、device、profiling CSV、repo 版本）后，agent 自动执行六阶段流程：GATHER → FORWARD MAPPING → REVERSE MAPPING → VERIFY → WRITE → COMMIT。
Key constraints
-
kernel_type必须与 CSV 文件名完全一致（无.csv后缀）。 -
三个映射路径：aten→op-plugin→aclnn、torch_npu.npu_*→op-plugin→aclnn、vllm-ascend 自定义/Triton。
-
alternate_kernel_types必须在同一抽象层级，禁止用融合大 op 作为子 op 的备选。
microbench
Microbench Run Script 生成器——从 profiling CSV 生成可在 NPU 上重放的 <KernelType>_run.py。
What it does
为 profiling 内核 CSV 生成可运行的 tools/perf_data_collection/op_replay/<KernelType>_run.py，用于 NPU 实测重放。
File layout
| File | Purpose |
|---|---|
microbench/SKILL.md |
Skill 定义和 repo 搜索顺序 |
Quick start
用户提供 kernel_type、设备 profile、vllm_ascend 版本和 CSV 路径后，agent 生成可重放的 run script。
Key constraints
-
优先使用本地已克隆的 repos，按指定路径搜索。
-
repo 缺失时按
SKILL.md中提供的 clone 命令获取。 -
生成的 run script 由
run_all_op.py/profile_and_update_db.py调用。
text-generate-executor
text_generate 单点验证执行器。用于把用户关于 python -m cli.inference.text_generate 的验证诉求转换为可确认、可执行的 CLI 命令，并在确认后运行和总结结果。
What it does
面向已有模型、硬件、batch/query length、prefill 或 decode 模式、固定 TP/DP/EP/MOE 策略、profiling database、trace/debug 或 throughput optimizer 最优行复验的场景，生成单点仿真命令。
File layout
| File | Purpose |
|---|---|
text-generate-executor/SKILL.md |
Skill 主说明、默认策略、校验规则和 handoff 规则 |
text-generate-executor/references/dialog-flow.md |
渐进式问参流程 |
text-generate-executor/references/text-generate-params.md |
text_generate 参数速查 |
Quick start
提出“帮我跑 text_generate 验证”“把 throughput_optimizer 最优行转 text_generate 跑一下”“导出 chrome trace”等请求时，agent 会补齐缺失参数，展示命令和假设，并在用户确认后执行。
Key constraints
- 执行前必须展示完整命令和关键假设，并要求显式确认。
- Decode 模式必须确认
--context-length；profiling 模式必须提供--profiling-database。 text_generate只验证固定候选，不执行 TP/EP/MOE-DP 搜索。
throughput-optimizer-executor
throughput_optimizer 部署规划执行器。用于把吞吐规划、硬件对比、并行搜索、PD 聚合/分离/配比优化等自然语言诉求转换为 python -m cli.inference.throughput_optimizer 命令。
What it does
面向搜索和规划场景，收集模型、硬件、设备数、输入/输出长度、SLO、部署模式和搜索空间，生成 optimizer 命令，在确认后运行并总结最佳并行策略、batch、concurrency、throughput、TTFT、TPOT 和 PD ratio 信息。
File layout
| File | Purpose |
|---|---|
throughput-optimizer-executor/SKILL.md |
Skill 主说明、默认策略、校验规则和 handoff 规则 |
throughput-optimizer-executor/references/dialog-flow.md |
部署模式识别和渐进式问参流程 |
throughput-optimizer-executor/references/throughput-optimizer-params.md |
throughput_optimizer 参数速查 |
throughput-optimizer-executor/scripts/extract_throughput_optimizer_result.py |
optimizer stdout 结构化摘要脚本 |
Quick start
提出“比较两种硬件”“搜索 Qwen 32B 最佳 TP”“做 PD 分离能力评估”“算 P/D 实例配比”等请求时，agent 会识别 aggregation、disagg 或 PD ratio 模式，补齐 SLO 和搜索空间，并在确认后执行。
Key constraints
--enable-optimize-prefill-decode-ratio不能与--disagg同时使用。- 多硬件对比共用同一个
--num-devices，需要在执行前说明。 - 执行前需要明确确认是否开启 prefix cache 和 MTP；开启后分别补齐 hit rate、MTP token 数和接受率假设。
- 该 skill 做候选搜索和规划；单点复验应 handoff 到
text-generate-executor。