MindSpeed-Agent

📖 架构设计 · 贡献指南 · 开发规范

---

📢 项目概述

MindSpeed-Agent 是面向 MindSpeed 大模型开发套件的 Claude Code 插件，提供覆盖 模型迁移调优、算子开发优化、推理部署 等场景的 Agent Skills 集合。

面向用户：MindSpeed / Ascend NPU 平台的大模型开发者（训练、推理、模型迁移、算子调优等），同时欢迎社区开发者共建 Skills 和 Agents。

🚀 快速开始

前置条件

• 安装 Claude Code

安装

# 在线安装
claude plugins install https://github.com/Ascend/MindSpeed-Agent.git

或本地安装：

git clone https://github.com/Ascend/MindSpeed-Agent.git
claude plugin marketplace add ./MindSpeed-Agent
claude plugin install mindspeed-agent@MindSpeed-Agent

安装后使用

启动 Claude Code，直接用自然语言描述需求，Claude 会根据上下文自动匹配对应 skill：

"帮我搭建 MindSpeed 训练环境"
"检查当前 CANN 环境配置"
"把这个模型从 GPU 迁移到 NPU 上跑"

也可显式调用：/mindspeed-agent:<skill-name>

📐 开发路径与核心能力

领域 / 路径	适用场景	目标用户
LLM 模型迁移调优	大语言模型（GPT/LLaMA/Qwen 等）在 NPU 上的训练迁移、性能调优、精度对齐	LLM 训练工程师
多模态模型迁移调优	多模态大模型（视觉-语言、音频-语言）的 NPU 适配与优化	多模态模型开发者
强化学习模型迁移调优	RL 模型（PPO/GRPO 等）的训练迁移与调优	RL 训练工程师
推理模型部署优化	推理模型的端到端部署、性能剖析、量化压缩、服务化	推理部署工程师
算子开发调优	Ascend C / Triton / TileLang 算子开发、优化与精度调试	算子开发者
通用工具	环境检查、模型下载、日志分析等公共能力	所有开发者

🔍 项目架构

目录结构

MindSpeed-Agent/
├── .claude-plugin/
│   └── plugin.json                   # 插件清单
│   ├── inference-model-skills/       # 推理模型部署优化 Skills            
│   │   ├── deployment/               #   部署类（vLLM 安装、服务化部署）
│   │   │   ├── 环境一键部署
│   │   │   └── vllm/vllm-ascend安装
│   │   ├── model-analysis/           #   模型分析类
│   │   │   ├── 模型结构分析
│   │   │   ├── kvcache占用计算    
│   │   │   ├── 制定配置下并行策略计算    
│   │   ├── model-adaptation/         #   模型适配类
│   │   │   ├── 模型脚本开发
│   │   │   └── 并行策略开发
│   │   │   └── 低精权重转换开发
│   │   ├── alignment/                #   精度对齐类
│   │   │   ├── 数据集自动评测
│   │   │   └── 模块级精度比对与分析
│   │   ├── performance-optimization/ #   性能优化类
│   │   │   ├── 参数、并行策略寻优
│   │   │   └── 性能特性开发
│   │   │   └── profiling采集与分析
│   │   ├── community-operations/     #   社区运营类
│   │   │   ├── issue自动回复
│   │   └── common_tools/             #   工具类
│   │   │   ├── 依赖组件二分定位
│   ├── rl-skills/                   # RL部署优化 Skills
│   │   ├── deployment/              #   自动部署，根据具体结果自动修改对应配置
│   │   │   ├── 环境一键安装部署默认配置
│   │   │   └── 自动拉起脚本，oom配置修改，根据反馈bug修复
│   │   ├── npu_adapter/              #   RL框架中GPU特性自动迁移NPU
│   │   │   ├── 新模型适配
│   │   │   └── GPU特性自动迁移NPU
│   │   ├── train_rollout_precision/  #   rl训推精度对齐
│   │   │   └── 模型训练推理精度对齐
│   │   ├── performance/              #   性能调优
│   │   │   ├── 自动搜索并行配置
│   │   │   └── 发现性能瓶颈并给出解决方案（算子、训练 no overlap通信）
│   │   ├── cicd/                     #   RL框架看护自动升级
│   ├── mindspeed-mm-skills/          # 多模态模型部署优化调优 Skills
│   │   ├── 模型迁移/   
│   │   │   ├── 模型迁移
│   │   │   └── 理解模型迁移
│   │   │   └── 生成模型迁移
│   │   ├── 性能开箱/
│   │   │   ├── mfu计算
│   │   │   └── 融合算子替换
│   │   ├── 并行策略适配/  
│   │   │   └── EP开发
│   │   │   └── CP开发
│   │   ├── 性能分析以及优化/  
│   │   │   ├── xx
│   │   │   └── xx
│   ├── ops-skills/                   # 算子开发调优 Skills
│   │   ├── ascendc/                  #   Ascend C 算子（生成/优化/精度）
│   │   ├── triton/                   #   Triton 算子（生成/优化/精度）
│   │   └── tilelang/                 #   TileLang 算子（生成/优化/精度）
│   └── common/                       # 跨领域通用 Skills（环境检查、日志解析等）
│   │   ├── 权重、数据集下载
│   │   └── 服务器连接
├── plugins/                           # Agent 定义（主控 Agent + 子 Agent）
│   ├── inference-model-adpator/       #   推理模型迁移plugin
│   │   |.claude-plugin
│   │   |──agent
│   │   │   ├── 方案设计
│   │   │   ├── 代码开发
│   │   │   └── 代码检视
│   │   │   └── 代码测试 
│   ├── inference-model-optimize/      #   推理模型优化plugin
│   │   |.claude-plugin
│   │   |──agent
│   │   │   ├── 方案设计
│   │   │   ├── 代码开发
│   │   │   └── 代码检视
│   │   │   └── 代码测试
│   ├── inference-model-alignment/    #   推理模型精度plugin
│   │   |.claude-plugin
│   │   |──agent
│   │   │   ├── 方案设计
│   │   │   ├── 代码开发
│   │   │   └── 代码检视
│   │   │   └── 代码测试
├── tools/                            # 工具类
├── docs/
│   └── skill-template/
│       └── SKILL.md                   # 带注释的 skill 模板参考
├── .github/
│   └── PULL_REQUEST_TEMPLATE.md
├── CLAUDE.md                          # AI Agent 工作指南（Schema / 评审清单 / 规范）
├── CONTRIBUTING.md                    # 贡献者指南
├── LICENSE
└── README.md

三层架构

三层架构设计：Plugin 编排 Agents，Agents 绑定 Skills。

┌─────────────────────────────────────────────────────────────────────────────────┐
│                         PLUGIN — 应用编排层                                       │
│                                                                                 │
│  入口：.claude-plugin/plugin.json（主插件 mindspeed-agent）                       │
│                              │                                                  │
│              ┌───────────────┼───────────────┐                                  │
│              ▼               ▼               ▼                                  │
│  ┌───────────────────┐ ┌──────────────┐ ┌──────────────┐                        │
│  │inference-model-   │ │inference-    │ │inference-    │  …  plugins/           │
│  │adpator            │ │model-optimize│ │model-alignment│      （子插件）         │
│  │（推理模型迁移）    │  │（优化）      │ │（精度）       │                        │
│  └────────┬──────────┘ └──────┬───────┘ └──────┬───────┘                        │
│           │                   │                │                                 │
├───────────┼───────────────────┼────────────────┼─────────────────────────────────┤
│           ▼                   ▼                ▼                                 │
│                         AGENT — 角色执行层                                       │
│                                                                                 │
│           每个子插件均包含 4 个标准 Agent 角色：                                   │
│                                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  architect   │  │  developer   │  │  reviewer    │  │  tester      │         │
│  │   方案设计    │  │   代码开发    │  │   代码检视    │  │   代码测试    │         │
│  │              │  │              │  │              │  │              │         │
│  │ 主控 Agent    │  │ 调优 Agent   │  │ 精度 Agent   │  │ 迁移 Agent   │         │
│  │ 决定调用链    │  │ 选技能+定参数 │  │ 选技能+定参数 │  │ 选技能+定参数 │         │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘         │
│         │                 │                 │                 │                  │
├─────────┼─────────────────┼─────────────────┼─────────────────┼──────────────────┤
│         ▼                 ▼                 ▼                 ▼                  │
│                         SKILL — 知识能力层                                       │
│                                                                                 │
│  位置：skills/ 目录，按 领域/功能/skill名 三级组织                                │
│                                                                                 │
│  ┌─────────────────────── 推理模型 Skills ───────────────────────────────────┐  │
│  │                                                                           │  │
│  │  skills/inference-model-skills/                                          │  │
│  │  ├── deployment/              部署类                                      │  │
│  │  │   ├── vllm-ascend-serving/      vLLM 推理服务一键部署                  │  │
│  │  │   ├── kvcache-calculator/       KV Cache 显存占用计算                  │  │
│  │  │   └── vllm-memory-calculator/   vLLM 服务显存与并行策略计算            │  │
│  │  ├── model-analysis/          模型分析类                                  │  │
│  │  ├── model-adaptation/        模型适配类（脚本开发、并行策略、权重转换）    │  │
│  │  ├── alignment/               精度对齐类（数据集评测、模块级精度比对）      │  │
│  │  ├── performance-optimization/ 性能优化类                                 │  │
│  │  │   ├── ascend-profiling-collection/  Profiling 数据采集                 │  │
│  │  │   ├── ascend-msprof-analyze-cli/   msprof 命令行分析                   │  │
│  │  │   └── vllm-ascend-benchmark/       vLLM 推理性能基准测试               │  │
│  │  ├── community-operations/    社区运营类（issue 自动回复等）               │  │
│  │  └── common_tools/            工具类（依赖二分定位等）                     │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ┌─────────────────────── 多模态模型 Skills ──────────────────────────────────┐  │
│  │  skills/mindspeed-mm-skills/                                              │  │
│  │  ├── 模型迁移/        模型迁移、理解模型迁移、生成模型迁移                   │  │
│  │  ├── 性能开箱/        MFU 计算、融合算子替换                                │  │
│  │  ├── 并行策略适配/    EP 开发、CP 开发                                     │  │
│  │  └── 性能分析以及优化/                                                     │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ┌─────────────────────── RL 模型 Skills ─────────────────────────────────────┐  │
│  │  skills/rl-skills/                                                        │  │
│  │  ├── deployment/              自动部署、OOM 配置修改、Bug 修复              │  │
│  │  ├── npu_adapter/             新模型适配、GPU 特性自动迁移 NPU              │  │
│  │  ├── train_rollout_precision/ 训推精度对齐                                  │  │
│  │  ├── performance/             并行配置自动搜索、性能瓶颈分析                 │  │
│  │  └── cicd/                    框架看护自动升级                              │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ┌─────────────────────── 算子开发 Skills ────────────────────────────────────┐  │
│  │  skills/ops-skills/                                                       │  │
│  │  ├── ascendc/    Ascend C 算子（生成 / 优化 / 精度调试）                    │  │
│  │  ├── triton/     Triton 算子（生成 / 优化 / 精度调试）                      │  │
│  │  └── tilelang/   TileLang 算子（生成 / 优化 / 精度调试）                    │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ┌─────────────────────── 通用 Skills ────────────────────────────────────────┐  │
│  │  skills/common/                                                           │  │
│  │  ├── 权重、数据集下载                                                      │  │
│  │  └── 服务器连接                                                            │  │
│  └───────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  每个 Skill = SKILL.md（YAML frontmatter + Markdown 正文）                       │
│            + references/（按需加载知识） + scripts/（可执行脚本）                 │
│            + assets/（模板等静态资源）                                            │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

详细的 Skill 规范（Schema、分类、评审清单、i18n）见 CLAUDE.md。

Skill 功能分类

在每个领域内部，Skill 按功能定位划分：

功能类别	定位	说明
deployment	部署类	环境搭建、服务部署、配置管理
model-analysis	模型分析类	性能采集、瓶颈分析、资源监控、模型结构分析
model-adaptation	模型适配类	GPU→NPU 模型迁移适配、格式转换、算子映射
alignment	精度对齐类	GPU→NPU 精度对比、数值校验、精度调试
performance-optimization	性能优化类	训练/推理性能优化、量化压缩、算子融合、混合精度
community-operations	社区运营类	使用案例分享、最佳实践沉淀、社区协作
common	通用类	跨领域的公共能力（环境检查、日志解析等）

开发

快速开始

1. 在 skills/<domain>/<function>/ 下创建新目录（kebab-case 命名）
2. 添加 SKILL.md 文件，包含 YAML frontmatter
3. 提交 PR，参考 贡献指南

SKILL.md 模板

---
name: my-skill
description: "This skill should be used when the user asks to...（英文，第三人称）"
version: 1.0.0
category: optimization
tags:
  - mindspeed
  - ascend
---

# Skill 标题

详细的 skill 内容（简体中文）...

完整模板参考：SKILL.md（Anthropic 官方）和 docs/skill-template/SKILL.md（本项目带注释版本）。

质量标准

所有合入的 skill 需满足：

• ✅ 包含完整的必填 frontmatter（name、description）
• ✅ 描述为英文，以 "This skill should be used when..." 开头
• ✅ 正文使用简体中文，语言统一
• ✅ 目录命名符合 kebab-case 规范
• ✅ 提供清晰、可操作的指令
• ✅ 无重复功能、无危险指令

详见 CLAUDE.md（评审清单 + Schema 规范）和 CONTRIBUTING.md（贡献流程）。

相关信息

• CLAUDE.md — AI Agent 工作指南（Skill Schema、分类体系、评审清单）
• CONTRIBUTING.md — 贡献指南（开发流程、提交规范、分类指南）
• Skill 模板
• Agent Skills 开放标准 — 跨平台 Skill 规范
• Claude Code 官方 Skills 文档

许可

MIT License