python-vibeperf

Python 工程系统级性能分析与优化工具集。

项目概述

python-vibeperf 是一套面向复杂 Python 多模块项目的性能优化技能（Skill）体系。它提供结构化的性能分析流程，帮助你建立性能基线、定位热点瓶颈、拆解优化需求、迭代验证方案，并输出可对比的优化报告。

本项目包含示例程序 examples/lidar_rasterization.py（LiDAR 点云栅格化渲染），可用于练习性能分析与优化方法。

核心价值

• 系统性分析：不依赖直觉，通过 viztracer 等工具建立真实数据支撑的性能基线
• 结构化流程：从基线、瓶颈分析、需求拆解到迭代优化与报告，提供完整的五步闭环（详见 skills/python-vibeperf/SKILL.md）
• 产物可复用：推荐在目标工程下使用 docs/perf/ 沉淀 CODEBASE_CONTEXT.md、各阶段 Markdown 与追踪数据，便于跨轮次延续与交接
• 与 Superpowers 配合：技能执行时会按需调用 brainstorming、writing-plans、test-driven-development 等子流程（需安装 superpowers）

安装方法

前提条件

• 已安装支持 Agent Skills 的 AI Agent 环境（如 Opencode, Cursor, Trae IDE 等）
• Python 3.8+（用于运行性能分析工具）
• 建议同时安装 superpowers（本技能在流程中依赖其部分子技能）

安装步骤

1. 克隆仓库

   git clone https://gitee.com/giteeziming/python-vibeperf.git
   cd python-vibeperf

   若你使用其他托管地址（如 GitHub 镜像），请将上述 URL 换为实际远程地址。

2. 安装 Skill 到 Agent 系统

   将 skills/python-vibeperf/ 目录复制或软链接到你的 Agent Skills 安装路径，例如：

   • Cursor：复制到用户 skills 目录或项目约定的 skills 路径（以你当前环境的技能加载方式为准）
   • Trae IDE：复制到 .trae/skills/ 目录
   • 其他 Agent：按各产品的技能安装说明配置

3. 安装 Python 依赖

   pip install -r requirements.txt

   当前 requirements.txt 以 viztracer 为主（性能追踪与可视化）。

4. 验证安装

   在 Agent 对话中可使用类似提示词，验证技能是否被正确加载：

   使用 python-vibeperf 技能帮我分析性能
   

   若技能已安装，Agent 应按 SKILL.md 中的流程引导分析。

使用方法

示例：优化 LiDAR 点云栅格化脚本

在 Agent 对话中可使用：

帮我分析 examples/lidar_rasterization.py 这个脚本的性能瓶颈，并进行优化。这是一个 LiDAR 点云栅格化程序，我需要提升它的执行效率。

Agent 会按 python-vibeperf 技能执行，典型环节包括：建立基线、瓶颈分析、需求拆解、迭代优化与最终报告（各阶段需用户确认后再进入下一阶段，详见 SKILL.md 中的约束）。

其他常用提示词

用 viztracer 分析整个项目的性能，看看哪里是瓶颈

这个 Python 项目在高并发场景下响应太慢，帮我做系统级的性能调优

帮我建立性能基线，然后分析 examples/lidar_rasterization.py 的热点函数

性能优化工作流（与 SKILL 对齐）

技能主文档将流程定义为 5 个步骤（与 skills/python-vibeperf/references/ 下文档一一对应）：

步骤	名称	目标	参考文档
1	建立性能基线	使用 viztracer 等建立基线、收集数据	01-performance-profiling.md
2	性能瓶颈分析	结合代码理解，定位热点与瓶颈	02-bottleneck-analysis.md
3	优化需求拆解	将目标拆解为可执行的优化方向与任务	03-requirements-breakdown.md
4	子需求迭代优化	实验设计、修改、验证、提交的闭环	04-iterative-optimization.md
5	输出优化报告	汇总前后指标与结论	05-final-report.md

viztracer 的具体用法以 references/viztracer-guide.md 为准；运行参数需与用户确认后再执行。

详细约束、产物目录结构（docs/perf/）及 Superpowers 子技能映射，请以 skills/python-vibeperf/SKILL.md 为准。

目录结构

python-vibeperf/
├── examples/
│   └── lidar_rasterization.py     # 示例：LiDAR 点云栅格化
├── skills/
│   └── python-vibeperf/
│       ├── SKILL.md                # 技能主文档（流程、约束、产物说明）
│       ├── scripts/
│       │   └── analyze_viztracer.py  # viztracer 相关辅助脚本
│       └── references/             # 各阶段执行参考
│           ├── 01-performance-profiling.md
│           ├── 02-bottleneck-analysis.md
│           ├── 03-requirements-breakdown.md
│           ├── 04-iterative-optimization.md
│           ├── 05-final-report.md
│           └── viztracer-guide.md
├── tests/
│   └── create_mock.py             # 测试辅助脚本
├── requirements.txt
├── LICENSE
└── README.md

依赖说明

依赖	用途
viztracer	Python 性能追踪与火焰图可视化
superpowers	本技能在流程中按需调用的规划、TDD、评审等子技能（见 SKILL.md）

许可证

本项目基于 MIT License 开源，详见 LICENSE。

相关资源

• viztracer 官方文档
• superpowers
• longtaskforagent（可选：与其他长任务编排工具配合时使用）