uniprof

Name: uniprof
Author: indragiek

本地服务

github.com/indragiek开发工具40959 周前更新

代码仓库

关于 uniprof

uniprof 是一个通用 CPU 性能分析工具，面向人类开发者和 AI Agent。无需修改代码或添加依赖，即可对多种语言和运行时的应用进行剖析并输出热点分析。

主要功能

01支持 Python、Node.js、JVM、.NET 等多种运行时
02自动识别并调用对应的性能分析器
03将不同分析器的输出统一为单一格式
04基于统计分析识别热点函数
05支持容器模式与宿主机模式切换
06可通过 MCP 服务安装到多种客户端

适用场景

01无需改动代码即可分析 Python 或 Node.js 应用的性能瓶颈
02为原生 Linux 或 macOS 程序生成火焰图
03将性能剖析结果保存为 JSON 以便后续分析

MCP 相关

该项目提供基于 stdio 的 MCP 服务（npx -y uniprof mcp run），使 AI 客户端能够调用性能剖析与分析功能。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "indragiek-uniprof": {
      "command": "npx",
      "args": [
        "-y",
        "uniprof"
      ]
    }
  }
}

启动命令npx -y uniprof

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmuniprof0.3.4stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
cwd	string	是	必填：运行命令的工作目录绝对路径（例如，"/home/user/myproject"）。通常为项目根目录。命令将在此目录下执行。必须是以 /（Linux/Mac）或驱动器号（Windows）开头的绝对路径。
mode	enum	否	可选：性能分析的执行模式。"auto"（推荐）会自动选择最佳选项。"container" 会在 Docker 中运行性能分析，以确保环境一致。"host" 使用本地安装的性能分析器（需要手动设置）。除非有特定需求，否则请使用 "auto"。auto \| container \| host
command	string	是	必填：要进行性能分析的确切命令行。示例："python app.py"、"node server.js"、"java -jar app.jar"、"./my-binary"。必须提供你在终端中输入的完整命令。不要包含 &&、\|\| 或 \| 等 shell 运算符。带参数的命令应全部放在此单个字符串中（例如，"python main.py --port 8080"）。
platform	string	否	可选：强制指定性能分析器平台。有效值：python、nodejs、ruby、php、jvm、dotnet、beam、native。留空则根据命令自动检测。仅在自动检测失败或需要特定性能分析器时指定。
output_path	string	否	可选：保存性能分析 JSON 的文件路径（例如，"/tmp/profile.json" 或 "./my-profile.json"）。若未指定，将自动创建唯一的临时文件。记录后始终会分析性能数据。
extra_profiler_args	string	否	可选：平台专用性能分析器参数，作为单个字符串提供（例如，"-F 999"）。常见示例："--rate 500"（Python/Ruby）、"-F 500"（native/perf）、"--interval 1000000"（JVM）。多个参数："--rate 500 --native"（Python 原生扩展性能分析）。平台专用选项请参阅文档。
enable_host_networking	boolean	否	可选：如果应用需要连接主机上的服务，请设为 true（默认值：false）。例如：连接 localhost 数据库、访问主机 API、进行进程间通信。仅影响容器模式。需要支持主机网络的 Docker Desktop。

详细介绍

`uniprof`

uniprof 让人类和 AI Agent 更轻松地进行 CPU 性能分析。无需修改代码或添加依赖，即可分析任何应用。

# Profile and analyze any app in one step
npx uniprof python script.py

支持的平台

uniprof 为多种专用于不同平台和运行时的性能分析器提供统一接口。它会根据要执行的命令自动检测应使用的性能分析器、运行该分析器、将不同的输出格式转换为统一格式，并对数据进行统计分析以识别热点。

平台	性能分析器	容器	主机	最低版本
Python	py-spy	✅	✅	Python 3.7+
Node.js	0x	✅	✅	Node 14+
Ruby	rbspy	✅	✅	Ruby 2.5+
PHP	Excimer	✅	✅	PHP 7.2+
JVM	async-profiler	✅	✅	Java 8+
.NET	dotnet-trace	✅	✅	.NET 5+
BEAM	perf	✅	✅*	OTP 24+
原生（macOS）	Instruments	❌	✅	Xcode 14.3+
原生（Linux）	perf	✅	✅	Linux 2.6.31+

* 主机模式仅支持 Linux

系统要求

简而言之： 安装了 Docker 的 macOS 或 Linux

uniprof 专为在 macOS 和 Linux 上运行而设计，但主要在 macOS 上开发和测试。如果你在 Linux 上运行时发现任何错误，请报告问题。目前不支持在 Windows 主机上运行，但你可以通过 WSL2 在 Windows 上安装的 Linux 中运行。请注意，通过 WSL2 使用 uniprof 时，不支持对原生 Windows 可执行文件进行性能分析，但仍可使用适用于 Python 和 Node.js 等高级语言运行时的性能分析器。

性能分析工具通常并不容易正确配置，并且可能需要提升权限。为简化配置并更好地隔离被分析的代码，uniprof 默认使用Docker 容器运行各个运行时；这些容器已预先配置为运行特定的性能分析工具。uniprof 会将你的工作区挂载到容器中，并在连接性能分析器的情况下执行程序。uniprof 也支持在容器外进行性能分析，前提是主机系统已安装性能分析工具；运行时传入 --mode host 标志即可。唯一不支持容器化执行的情况是在 macOS 上分析原生 Mach-O 二进制文件，因为 Apple Instruments 无法在容器内运行。

安装

npm install -g uniprof

MCP 服务

# Install uniprof MCP server automatically
uniprof mcp install claudecode
uniprof mcp install cursor
uniprof mcp install vscode

支持自动安装的客户端： amp、claudecode、codex、cursor、gemini、vscode、zed

如果你的客户端不支持自动安装，请使用 stdio 传输方式添加 MCP 服务，并运行命令 npx -y uniprof mcp run。

详细的 MCP 文档请参阅 docs/mcp.md。

快速开始

一步完成性能分析和分析：

# Profile most languages and get immediate analysis
uniprof python app.py
uniprof node server.js
uniprof ruby script.rb
uniprof java -jar myapp.jar
uniprof dotnet MyApp.dll
uniprof ./my-native-app

# Profile and visualize flamegraph in browser
uniprof --visualize python app.py

保存性能分析结果，以便稍后分析和可视化：

# 1. Check environment (optional)
uniprof bootstrap

# 2. Record a profile
uniprof record -o profile.json -- python app.py
uniprof record -o profile.json -- node server.js
uniprof record -o profile.json -- ruby script.rb
uniprof record -o profile.json -- php script.php
uniprof record -o profile.json -- java -jar myapp.jar
uniprof record -o profile.json -- ./gradlew run
uniprof record -o profile.json -- ./mvnw spring-boot:run
uniprof record -o profile.json -- dotnet MyApp.dll
uniprof record -o profile.json -- elixir script.exs
uniprof record -o profile.json -- mix run
uniprof record -o profile.json -- ./my-native-app
uniprof record -o profile.json -- /Applications/MyApp.app

# 3. Analyze profile data to find hotspots
uniprof analyze profile.json

# 4. Visualize flamegraph in the browser
uniprof visualize profile.json

详细的命令行选项文档请参阅 docs/cli.md。

主机模式与容器模式

使用 --mode 选项控制性能分析的运行方式：

auto（默认）：Docker 可用时优先使用容器模式；否则使用主机模式。
- 语言运行时（Python/Node.js/Ruby/PHP/BEAM/JVM/.NET）默认使用容器模式，实现零配置。
- 在 macOS 上，使用 Mach-O 二进制文件的原生程序采用主机模式（Instruments）。macOS 上的 ELF 二进制文件支持容器模式。
- 在 Linux 上，原生程序默认使用容器模式；如果你更倾向于使用本地 perf 配置，也可以使用主机模式。
host：强制使用主机上安装的性能分析器。
container：强制使用 Docker 容器（不支持 macOS Instruments/Mach-O 二进制文件）。

# Auto mode (default)
uniprof record -o profile.json -- python script.py

# Force host profilers
uniprof record --mode host -o profile.json -- python script.py

# Force container mode
uniprof record --mode container -o profile.json -- ./my-linux-app

编译时添加调试信息

原生程序性能分析需要调试信息才能获得有意义的结果。调试符号可让性能分析器将内存地址映射到函数名称，从而生成可读的输出，而非仅显示十六进制地址。此外，帧指针有助于提高调用栈的准确性，尤其是在经过优化的代码中。

编译器	DWARF 调试信息	帧指针	说明
gcc	`gcc -g -o myapp main.c`	`gcc -fno-omit-frame-pointer -o myapp main.c`	使用 `-g3` 获取最多的调试信息，使用 `-ggdb` 获取 GDB 专用扩展
clang	`clang -g -o myapp main.cpp`	`clang -fno-omit-frame-pointer -o myapp main.cpp`	在 macOS 上使用 `-gfull` 获取完整的调试信息
swift	`swiftc -g main.swift`	`swiftc -Xcc -fno-omit-frame-pointer main.swift`	使用 `swift build` 时，调试构建默认包含符号
cargo	`cargo build`（调试模式） `cargo build --release` + `[profile.release]` `debug = true`	`RUSTFLAGS="-C force-frame-pointers=yes" cargo build`	调试构建默认包含 DWARF；对于发布构建，在 Cargo.toml 中添加 `debug = true`
go	`go build -gcflags=all="-N -l"`	内置，始终启用	Go 默认包含调试信息；`-gcflags` 会禁用优化，以便更好地调试
zig	`zig build-exe -O Debug main.zig`	`zig build-exe -fno-omit-frame-pointer main.zig`	对经过优化且包含符号的构建，使用带调试信息的 `-O ReleaseSafe`
ghc	`ghc -g -rtsopts main.hs`	`ghc -fno-omit-frame-pointer main.hs`	性能分析构建使用 `-prof`；`-rtsopts` 可启用运行时性能分析选项

文档

致谢

py-spy（MIT）用于 Python 性能分析，包含在 uniprof-python 镜像中。
0x（MIT）用于 Node.js 性能分析，包含在 uniprof-nodejs 镜像中。
rbspy（MIT）用于 Ruby 性能分析，包含在 uniprof-ruby 镜像中。
Excimer（Apache 2.0）用于 PHP 性能分析，包含在 uniprof-php 镜像中。
async-profiler（Apache 2.0）用于 JVM 性能分析，包含在 uniprof-jvm 镜像中。
dotnet-trace（MIT）用于 .NET 性能分析，包含在 uniprof-dotnet 镜像中。
perf（GPL）用于 Linux 上的原生性能分析，包含在 uniprof-native 和 uniprof-beam 镜像中。
speedscope（MIT）与 uniprof 捆绑，用于火焰图可视化

许可证

本仓库中的所有 uniprof 源代码均根据 MIT License 获得许可。详见 LICENSE。

uniprof 会下载并运行捆绑第三方软件的 Docker 镜像。用于构建这些镜像的 Dockerfile 位于 containers/。这些镜像及其内容不受 MIT 许可证约束，而受各自许可证管辖。uniprof 不授予这些组件的使用权，也不会对其重新授权。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

uniprof

关于 uniprof

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

uniprof

目录

支持的平台

系统要求

安装

MCP 服务

快速开始

主机模式与容器模式

编译时添加调试信息

文档

致谢

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`uniprof`