configure-memory-profiling

/configure:memory-profiling

使用 pytest-memray 检查并配置 Python 项目的内存分析基础设施。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方法……
从头开始为 Python 项目设置内存分析	项目不是 Python 项目——memray/pytest-memray 仅适用于 Python
为 CI 集成 pytest-memray，以检测内存回归	分析 CPU 性能——改用 cProfile 或 py-spy
在测试套件中配置内存泄漏检测	运行负载/压力测试——使用 /configure:load-tests
为 CI 设置内存阈值和分配基准	快速进行一次性内存检查——直接运行 uv run pytest --memray
启用原生 C 扩展堆栈跟踪，进行深度分析	实时分析生产系统——使用独立版 memray 或 Grafana

上下文

• 项目根目录：!pwd
• Python 项目：!find . -maxdepth 1 \( -name 'pyproject.toml' -o -name 'setup.py' \)
• 已安装 pytest-memray：!grep -r 'pytest-memray' pyproject.toml requirements*.txt
• 已安装 memray：!grep -r 'memray' pyproject.toml requirements*.txt
• Conftest 固件：!grep -l 'memray' tests/conftest.py
• 内存测试文件：!find tests -maxdepth 2 -name '*memory*' -o -name '*memray*'
• 基准测试：!find tests -maxdepth 2 -type d -name 'benchmarks'
• CI 工作流：!find .github/workflows -maxdepth 1 -name '*memory*'
• 内存报告目录：!find . -maxdepth 1 -type d -name 'memory-reports'

参数

从 $ARGUMENTS 解析：

• --check-only：报告内存分析合规状态，不做任何修改
• --fix：自动应用所有修复，无需提示
• --threshold <mb>：设置默认内存阈值，单位为 MB（默认值：100）
• --native：为 C 扩展启用原生堆栈跟踪

支持的工具：

工具	最适用于
pytest-memray（推荐）	集成到测试中的分析、CI/CD 内存限制、泄漏检测
独立版 memray	深度分析、火焰图、生产环境分析
tracemalloc	快速调试、无需依赖、轻量级分析

执行

执行此内存分析配置检查：

步骤 1：确认这是 Python 项目

读取上下文值。如果未找到 pyproject.toml 或 setup.py，报告“不是 Python 项目”并停止。

步骤 2：检查最新工具版本

使用 WebSearch 或 WebFetch 核实当前版本：

1. pytest-memray：查看 PyPI
2. memray：查看 PyPI

步骤 3：分析当前的内存分析配置

检查配置是否完整：

• pytest-memray 已作为开发依赖安装
• memray 后端已安装
• pyproject.toml 中已配置 pytest（标记、addopts）
• 使用 @pytest.mark.limit_memory 的内存限制测试
• 已启用泄漏检测（--memray-leak-detection）
• 已配置原生跟踪（如果设置了 --native 标志）
• 已配置 CI/CD 集成
• 报告目录已存在

步骤 4：生成合规报告

打印合规报告，涵盖以下内容：

• 安装状态（pytest-memray、memray、pytest 版本）
• 配置（pytest 集成、标记、泄漏检测、原生跟踪）
• 测试覆盖范围（内存限制测试、分配基准）
• CI/CD 集成（工作流、阈值、制品上传、趋势跟踪）

最后列出问题总数和建议。

如果设置了 --check-only，则在此处停止。

步骤 5：安装并配置 pytest-memray（如果设置了 --fix 或用户确认）

1. 安装 pytest-memray：uv add --group dev pytest-memray
2. 如果设置了 --native，则安装原生支持：uv add --group dev pytest-memray[native]
3. 更新 pyproject.toml 中的 pytest 配置（标记、filterwarnings）
4. 创建 memory-reports/ 目录
5. 使用 REFERENCE.md 中的配置模板

步骤 6：创建内存分析测试文件

1. 在 tests/conftest.py 中添加内存测试夹具（设置报告目录、阈值夹具、数据生成器）
2. 创建 tests/test_memory_example.py，添加内存限制测试示例
3. 创建 tests/benchmarks/test_memory_benchmarks.py，用于趋势跟踪
4. 使用 REFERENCE.md 中的测试模板

步骤 7：添加包脚本

在 Makefile 或 pyproject.toml 中添加内存分析命令：

• test-memory：uv run pytest --memray
• test-memory-report：运行测试并输出 bin 文件，然后生成火焰图
• test-memory-leaks：uv run pytest --memray --memray-leak-detection
• test-memory-native：uv run pytest --memray --native

步骤 8：配置 CI/CD 集成

创建 .github/workflows/memory-profiling.yml，包含：

• 在 PR 上进行内存分析（检测回归）
• 按周定期运行基准测试以跟踪趋势
• 生成火焰图
• 在 PR 中评论结果
• 使用 REFERENCE.md 中的工作流模板

步骤 9：更新标准跟踪

更新 .project-standards.yaml：

components:
  memory_profiling: "2025.1"
  memory_profiling_tool: "pytest-memray"
  memory_profiling_threshold_mb: 100
  memory_profiling_leak_detection: true
  memory_profiling_ci: true
  memory_profiling_native: false

步骤 10：打印最终合规报告

打印已安装的软件包、已应用的配置、已创建的测试文件、可用命令、已配置的 CI/CD，以及给用户的后续步骤摘要。

有关详细的测试模板、CI 工作流和独立的 memray 命令，请参阅 REFERENCE.md。

Agentic 优化

上下文	命令
快速合规检查	/configure:memory-profiling --check-only
自动修复所有问题	/configure:memory-profiling --fix
运行内存测试	uv run pytest --memray
检测内存泄漏	uv run pytest --memray --memray-leak-detection
使用原生跟踪运行	uv run pytest --memray --native
生成火焰图	uv run memray flamegraph output.bin -o flamegraph.html

标志

标志	说明
--check-only	报告状态，不提供修复选项
--fix	无需提示，自动应用所有修复
--threshold <mb>	设置默认内存阈值，单位为 MB（默认值：100）
--native	为 C 扩展启用原生堆栈跟踪

示例

# Check compliance and offer fixes
/configure:memory-profiling

# Check only, no modifications
/configure:memory-profiling --check-only

# Auto-fix with custom threshold
/configure:memory-profiling --fix --threshold 200

# Enable native tracking for C extensions
/configure:memory-profiling --fix --native

错误处理

• 不是 Python 项目：跳过并显示消息，建议手动设置
• 未安装 pytest：先提供安装 pytest 的选项
• 不支持 memray：说明平台限制（仅支持 Linux/macOS）
• 原生跟踪不可用：警告缺少调试符号
• CI 工作流已存在：提供更新或跳过的选项

另请参阅

• /configure:tests - 配置测试框架
• /configure:coverage - 配置代码覆盖率
• /configure:load-tests - 负载和性能测试
• /configure:all - 运行所有合规检查
• pytest-memray 文档：https://pytest-memray.readthedocs.io
• memray 文档：https://bloomberg.github.io/memray