Skip to content

README.md

Latest commit

 

History

History
314 lines (220 loc) · 11.4 KB

README.md

File metadata and controls

314 lines (220 loc) · 11.4 KB

🚀 MindStudio-Agent

面向 Ascend NPU 场景的一站式调试调优 Agent

msAgent

📢 最新消息

  • 2026-04-27： v26.1.0.alpha1发布：新增Accuracy / Zephyr Agent，辅助精度调优、模型量化。
  • 2026-04-08：v0.1.3 发布，完成 DeepAgents 重构更快更好用，并增强 ，新增 msagent web 能力。
  • 2026-03-19：mindstudio-agent 已发布到 PyPI，推荐优先使用 pip install -U mindstudio-agent 安装

🤖 内置 Agent 与能力分工

形象 名称 领域定位 说明
Hermes Hermes 性能调优：聚焦 Ascend Profiling 分析，覆盖单卡、多卡、集群等场景，擅长快慢卡、慢节点、MFU、通信瓶颈、算子热点、下发调度等性能问题定位与优化建议。 Hermes说明
Accuracy Accuracy 精度调优：聚焦Ascend精度分析与优化，覆盖单卡，多卡，集群等场景，可处理RL训推一致性分析，loss/gnorm NaN分析等常见精度问题。 Accuracy说明
Minos Zephyr 模型量化：聚焦 msModelSlim 量化与压缩场景，协助完成模型适配可行性与结构风险评估，辅助完成基础适配器开发。 Zephyr说明
Minos Minos 文档体验与代码审查辅助：聚焦 README 走查、安装流程验证、Quick Start 体验、新手 onboarding、文档可用性评估，以及 GitCode PR 审查与评审意见整理。 Minos说明
Minos Icarus 算子调优：聚焦Ascend NPU 算子性能调优，包括算子性能深度分析、端到端算子性能优化，辅助提升算子性能优化效率，降低开发难度 Icarus说明

⚡ 快速上手

1) 🧰 准备环境

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

2) 📦 安装

推荐优先使用 PyPI 安装。如果你需要跟踪最新源码、参与开发，或同步最新内置 Skills，再使用 源码运行 方式。

说明：

  • 下文中的 msagent 默认指已安装的命令行入口
  • 如果采用源码运行，请将示例中的 msagent 替换为 uv run msagent

方式一：PyPI 安装

pip install -U mindstudio-agent

方式二：源码运行（开发 / 跟踪最新代码）

拉取源码并进入目录：

git clone https://gitcode.com/Ascend/msagent.git
cd msagent

源码仓库已直接包含内置 Skills，无需额外同步子模块。

如果你只需要使用当前仓库锁定的 Skills 版本，可以跳过这一步。

安装依赖并启动：

uv sync
uv run msagent

常用命令

检查版本：

msagent --version

开启详细日志：

msagent -v

启用后日志会写入当前工作目录下的 ./.msagent/logs/app.log，同时终端会提示日志文件位置。

日志级别环境变量

通过 MSAGENT_LOG_LEVEL 环境变量可调整日志详细程度（默认 INFO）：

# 调试模式，记录最详细日志
export MSAGENT_LOG_LEVEL=DEBUG
msagent -v

支持的级别（从低到高）：DEBUG < INFO < WARNING < ERROR < CRITICAL

3) 🔐 配置 LLM

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

选型建议：

  • OpenAI 兼容接口：使用 openai
  • Anthropic 兼容接口：使用 anthropic
  • Google / Gemini 接口：使用 google

对于用户自部署或经由网关转发的服务，不再单独区分 custom provider；请根据接口协议兼容性复用上述三种 provider，并通过 --llm-base-url 指定自定义服务地址。

下面命令使用 Linux / macOS 的环境变量写法；Windows CMD 请改成 set KEY=value，PowerShell 请改成 $env:KEY = "value"。

OpenAI 兼容接口

以 DeepSeek deepseek-chat 为例：

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

本地 OpenAI 兼容服务

如果是本地部署的 OpenAI 兼容服务，例如 vLLM 暴露的 OpenAI-compatible API，即使服务端不校验 API Key，也可以继续使用 openai provider：

export OPENAI_API_KEY="dummy"
msagent config --llm-provider openai --llm-base-url "http://127.0.0.1:8000/v1" --llm-model "your-model"
  • OPENAI_API_KEY 只需任意非空字符串，不需要是真实密钥
  • --llm-base-url 对于 vLLM 一般填写服务根路径，例如 http://127.0.0.1:8000/v1

自定义服务地址示例

如果你使用的是自部署服务、企业网关或代理层，请按协议兼容性选择 provider，并通过 --llm-base-url 指向你的服务地址。

Anthropic 兼容服务

例如自部署或代理后的 Claude / Anthropic 兼容接口：

export ANTHROPIC_API_KEY="your-key"
msagent config --llm-provider anthropic --llm-base-url "https://example.com/anthropic" --llm-model "claude-sonnet-4-20250514"

Google / Gemini 服务

例如 Google AI Studio、Vertex AI 网关，或兼容 Gemini 协议的服务：

export GOOGLE_API_KEY="your-key"
msagent config --llm-provider google --llm-base-url "https://example.com/google" --llm-model "gemini-2.5-pro"

说明：

  • 自部署服务请选择与其协议兼容的 provider，而不是使用不存在的 custom provider
  • --llm-base-url 用于覆盖默认官方地址，指向你自己的服务入口或代理网关
  • 对于不校验 API Key 的兼容服务，通常仍建议设置一个非空占位值，例如 dummy
  • 历史配置里的 gemini 会被兼容处理为 google，但新配置建议统一使用 google

查看当前配置

msagent config --show

4) 🖥️ 启动会话

进入交互式会话：

msagent

手动指定启动 agent：

msagent --agent Hermes
msagent --agent Minos
msagent --agent Accuracy
msagent --agent Zephyr
msagent --agent Icarus
4.1) 🌐 启动 Web UI（可选，Beta功能）

前置依赖：

  • 本机需要已安装 node（wheel 安装后的 Web UI 运行时依赖）

启动：

msagent web

打开：

http://127.0.0.1:3000

说明：

  • 通过 pip install -U mindstudio-agent 安装后，也可以直接使用 msagent web
  • wheel 安装默认内置预编译 Web UI，运行时只需要本机有 node，不再要求额外执行 npm install 或单独安装 next
  • msagent web 默认会同时启动：
    • API：http://127.0.0.1:2024
    • UI：http://127.0.0.1:3000
  • 启动成功后会自动打开默认浏览器进入 UI
  • 浏览器访问 UI 地址，不是 API 地址
  • 首次打开时会自动预填：
    • Deployment URL = http://127.0.0.1:2024
    • Assistant ID = msagent
  • 如果端口冲突，改端口启动即可
  • 如果本地残留了旧的 Web 进程，可先手动清理：
pkill -f "next dev --turbopack" || true
pkill -f "langgraph dev" || true

常用命令：

msagent web --host 127.0.0.1 --port 2024 --ui-port 3000
msagent web --port 2025 --ui-port 3001
msagent web --no-open
msagent web --no-ui

5) 📚 按 Agent 查看说明与示例

不同能力的说明与示例已经按 Agent 拆分：

🛠️ 参考文档

后续的配置、扩展、构建和版本说明已经拆分到独立文档，避免首页信息过载，也方便按代码演进单独维护：

  • 配置与扩展 项目本地配置目录、MCP 配置、Skills 扩展与加载顺序。
  • 编译与打包 wheel 构建流程、构建脚本行为、常用构建参数与手动构建方式。
  • 版本与兼容性 当前版本、Python 要求、内置 MCP 版本与 Provider 支持情况。

⌨️ 会话常见操作

进入交互式会话后，可以直接输入问题，也可以配合 / 命令和快捷键提升效率。

/ 命令

当前交互式会话支持以下 slash commands：

命令 说明
/help 查看当前支持的命令列表。
/hotkeys 查看键盘快捷键说明。
/agents 打开 Agent 选择器。
/model 打开模型选择器。
/threads 浏览并恢复历史会话线程。
/tools 查看当前可用工具。
/skills 浏览当前可用 Skills。
/mcp 管理 MCP 服务启用状态。
/offload 压缩并卸载较早的会话消息。
/tool-output 打开最近一次可展开的工具输出。
/clear 清屏并开启新线程。
/exit 退出当前会话。

输入区快捷键

快捷键 说明
Ctrl+C 有输入时清空输入框；连续按两次退出会话。
Ctrl+J 插入换行，便于多行输入。
Shift+Tab 循环切换审批模式。
Ctrl+B 切换 bash mode。
Ctrl+K 直接打开快捷键说明。
Ctrl+O 打开最近一次可展开的工具输出。
Tab 应用第一个补全项。
Enter 提交输入；如果当前选中了补全项，则先应用补全。

工具输出查看器

当某次工具调用支持展开查看时，可用 Ctrl+O 或 /tool-output 打开工具输出查看器。查看器内支持：

快捷键 说明
Ctrl+O / Enter 展开或折叠当前工具输出。
Left / Right 在不同 tool call 之间切换。
Up / Down 按行滚动。
PageUp / PageDown 按页滚动。
Home / End 跳到顶部或底部。
Esc / Ctrl+C 关闭查看器。

联系我们

欢迎加入飞书群交流：

Feishu Group