mindstudio-agent 0.1.2

AI assistant for Ascend NPU profiling analysis, bottleneck diagnosis, and optimization guidance

🚀 msAgent

面向 Ascend NPU 场景的性能问题定位助手

msAgent 聚焦“发现瓶颈 -> 定位根因 -> 给出建议”的分析闭环。
它结合 LLM 推理能力与可扩展工具链，帮助你把复杂 Profiling 信息快速转化为可执行的优化决策。

📌 文档导航：最新消息 ｜ 版本说明 ｜ 使用效果展示

最新消息

• 2026-03-19：mindstudio-agent 已发布到 PyPI，推荐优先使用 pip install -U mindstudio-agent 安装

🔍 支持的分析场景与扩展能力

• ⚙️ 覆盖单卡、多卡到集群的性能分析
• 🔎 支持算子热点、通信瓶颈、快慢卡、慢节点、下发调度等常见问题定位
• 📊 支持 MFU 计算、快慢卡诊断等典型分析任务
• 🖼️ 具体示例提示词和效果截图可参考下文的 使用效果展示
• 🔌 支持 MCP 扩展，默认随 PyPI 包安装启用 msprof-mcp
• 🧠 支持 Skills 扩展；源码仓库中的内置 Skills 由 mindstudio-skills 子模块提供

---

⚡ 快速上手

1) 🧰 准备环境

• Python 3.11+
• 推荐使用 uv
• 至少准备一个可用的 LLM API Key
• glibc >= 2.34 (msprof-mcp trace_processor binary required)

2) 📦 安装

说明：

• 下文中的 msagent 适用于已安装命令行入口的场景。
• 如果你是源码运行（git clone + uv sync），请把示例里的 msagent 替换成 uv run msagent。
• Windows 示例默认使用 CMD；若使用 PowerShell，请把 set KEY=value 改为 $env:KEY = "value"。

推荐方式：直接从 PyPI 安装

pip install -U mindstudio-agent

检查版本：

msagent --version

如果你希望跟踪最新源码、参与开发，或需要同步最新的内置 Skills，可以使用源码运行方式：

git clone --recurse-submodules https://github.com/kali20gakki/msAgent.git
cd msAgent
git submodule sync --recursive
# 如果要同步 mindstudio-skills 上游最新版本，再执行下一行
git submodule update --init --recursive --remote resources/configs/default/skills
uv sync

3) 🔐 配置默认 LLM

当前 config 子命令直接支持的 Provider 是：openai、anthropic、gemini、google、custom。

对于兼容 OpenAI API 的服务，推荐使用 openai provider，并通过 --llm-base-url 指定服务地址。

OpenAI 兼容 API 示例（以 DeepSeek deepseek-chat 为例）：

Linux / macOS：

export OPENAI_API_KEY="your-key"
msagent config --llm-provider openai --llm-base-url "https://api.deepseek.com/v1" --llm-model "deepseek-chat"

Windows（CMD）：

set OPENAI_API_KEY=your-key
msagent config --llm-provider openai --llm-base-url "https://api.deepseek.com/v1" --llm-model "deepseek-chat"

Windows（PowerShell）：

$env:OPENAI_API_KEY = "your-key"
msagent config --llm-provider openai --llm-base-url "https://api.deepseek.com/v1" --llm-model "deepseek-chat"

Custom 示例（适用于不兼容 OpenAI API、需要直接请求指定 HTTP 接口的场景）：

Linux / macOS：

export CUSTOM_API_KEY="your-key"
msagent config --llm-provider custom --llm-base-url "https://example.com/chat/completions" --llm-model "my-model"

查看当前项目配置：

msagent config --show

4) 🖥️ 启动会话

进入交互式会话：

msagent

5) 📊 与 msAgent 一起性能调优

把 Profiling 目录路径和问题一起发给 msAgent，目前已有能力请参考：使用效果展示

---

使用效果展示

场景	示例提示词	效果展示
MFU 计算	请基于/path/to/kernel_details.csv计算matmul的MFU（910B3），并说明各项计算依据。
快慢卡诊断	请分析 /path/to/cluster_profiling/ 中是否存在快慢卡问题，定位异常 rank，并给出可能原因。
profiling数据检查	请分析 /path/to/xxx_ascend_pt/ 数据是否采集正常。
msprof工具使用类咨询	msprof怎么编译出run包？
db自定义内容转csv	基于ascend_pytorch_profiler_0.db，帮我提取各个算子类型的总耗时并按降序输出到csv。

---

🛠️ 参考：配置与扩展

📁 项目本地配置目录

当前实现使用“项目本地配置”，所有运行时文件都放在：

<working-dir>/.msagent/

首次运行时，msAgent 会把 resources/configs/default/ 里的默认模板复制到该目录。常见文件如下：

文件	作用
.msagent/config.llms.yml	当前项目默认模型配置；msagent config 直接写这里
.msagent/llms/*.yml	附带的模型别名集合
.msagent/agents/*.yml	Agent 定义，例如 general、code-reviewer
.msagent/subagents/*.yml	SubAgent 定义
.msagent/checkpointers/*.yml	Checkpointer 配置
.msagent/sandboxes/*.yml	沙箱配置模板
.msagent/config.mcp.json	MCP 服务器配置
.msagent/config.approval.json	工具审批规则
.msagent/config.checkpoints.db	会话 checkpoint 数据库
.msagent/.history	输入历史
.msagent/memory.md	用户偏好和项目上下文记忆

🔌 MCP 配置

默认模板会启用 msprof-mcp，并直接调用随当前 Python 环境安装的 msprof-mcp 可执行程序启动。

当前代码中的 MCP 使用方式是：

• 用 /mcp 在会话里切换已有服务的启用状态
• 用编辑器直接修改 .msagent/config.mcp.json 来新增、删除或细调服务器定义

配置文件格式示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"],
      "transport": "stdio",
      "env": {},
      "include": [],
      "exclude": [],
      "enabled": true,
      "stateful": false
    }
  }
}

常用字段：

• command / url
• args
• transport
• env
• include / exclude
• enabled
• stateful
• repair_command / repair_timeout
• timeout / sse_read_timeout / invoke_timeout

对于像 msprof-mcp 这类本地 stdio MCP，默认更推荐：

• stateful: true，避免每次工具调用都重新拉起服务进程
• 如果你是通过 pip install mindstudio-agent 或安装已构建的发布包使用，保持默认的 "command": "msprof-mcp" 即可
• 如需把 msprof-mcp 与当前环境解耦，仍可改成 uvx --isolated --from msprof-mcp==0.1.4 msprof-mcp 启动
• 只在需要强制刷新远端版本时才临时使用 uvx --refresh，不要把它作为常驻默认参数

🧠 Skills

Skills 会按以下候选目录自动加载：

• <working-dir>/skills
• 内置 Skills（源码仓库中对应 resources/configs/default/skills/ 子模块）
• <working-dir>/.msagent/skills

源码仓库中的内置 Skills 来源于 mindstudio-skills 子模块：

• 子模块路径：resources/configs/default/skills/
• 上游仓库：https://github.com/kali20gakki/mindstudio-skills

如果你是 git clone 后从源码运行，建议至少执行一次以下命令初始化 Skills：

git submodule sync --recursive
git submodule update --init --recursive resources/configs/default/skills

如果你要同步 mindstudio-skills 的最新上游提交，请执行：

git submodule sync --recursive
git submodule update --init --recursive --remote resources/configs/default/skills

说明：

• 不带 --remote：同步到当前 msAgent 仓库记录的 Skills 版本，适合复现和保持版本一致。
• 带 --remote：同步到 mindstudio-skills 上游默认分支的最新提交。
• 执行 --remote 后，主仓库里的 submodule 指针会变更；如果你希望固定这个版本，记得一起提交该变更。

支持两种目录结构：

skills/
  my-skill/
    SKILL.md

skills/
  profiling/
    my-skill/
      SKILL.md

其中 SKILL.md 需要包含 frontmatter，至少提供：

---
name: my-skill
description: 这个技能做什么
---

当前仓库里已经包含示例技能 op-mfu-calculator，会在无项目自定义 Skill 时作为兜底能力之一被加载。

---

🏗️ 编译与打包

打包 wheel（可直接 pip install）

Linux / macOS：

bash scripts/build_whl.sh

Windows（CMD）：

git submodule sync --recursive
git submodule update --init --recursive --remote --force --depth 1 resources/configs/default/skills
uv build --wheel --out-dir dist .

如果你的 Windows 环境安装了 Git Bash / WSL，也可以直接执行 bash scripts/build_whl.sh。

构建脚本会默认执行 git submodule update --init --recursive --remote --force --depth 1 resources/configs/default/skills，同步 mindstudio-skills 上游最新提交后再打入 wheel 包。 如果你需要按主仓库里固定的 submodule 提交构建，可以临时设置 SYNC_SKILLS_REMOTE=0。

打包完成后会在 dist/ 目录生成 mindstudio_agent-*.whl，可直接安装：

Linux / macOS：

pip install dist/mindstudio_agent-<version>-py3-none-any.whl

Windows（CMD）：

pip install .\dist\mindstudio_agent-<version>-py3-none-any.whl

请将上面的 <version> 替换为实际构建出的 wheel 文件名。

从 TestPyPI 安装时，建议同时添加 PyPI 作为依赖源（部分依赖仅发布在 PyPI）：

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mindstudio-agent==0.1.0

---

---

版本说明

项目	说明
当前版本	0.1.0（首个 PyPI 发布版本）
发布方式	支持通过 pip install -U mindstudio-agent 直接安装
包名	mindstudio-agent
命令行入口	msagent
Python 要求	>=3.11
默认内置扩展	msprof-mcp==0.1.4
版本策略	遵循语义化版本（SemVer），补丁版本以兼容性修复为主，次版本新增功能保持向后兼容，主版本包含不兼容变更。

0.1.0 能力概览

• 支持通过 CLI 直接分析 Profiling 数据，既可进入交互式会话，也可执行单轮问题分析
• 支持单卡、多卡到集群的性能定位，覆盖算子热点、通信瓶颈、快慢卡、慢节点、下发调度等常见问题
• 支持 MFU 计算、快慢卡诊断、Profiling 数据检查等典型任务，具体示例可参考上文的 使用效果展示
• 支持 OpenAI 兼容 API 与 custom HTTP 接口配置，可按项目写入默认模型
• 支持 MCP 扩展，默认随安装启用 msprof-mcp
• 支持 Skills 扩展；源码仓库中的内置 Skills 由 mindstudio-skills 子模块提供

可通过以下命令查看本地安装版本：

msagent --version

---

🙏 引用与致谢

本项目在架构设计与实现思路上参考了 langrepl 项目，在此向其作者与贡献者表示感谢。