mxready 1.0.0__py3-none-any.whl

mxready/resources/frontend/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="description"
+      content="MXReady：面向 PyTorch CUDA 扩展项目的沐曦 MXMACA 迁移准备度体检工具"
+    />
+    <title>MXReady · 沐曦适配体检</title>
+    <script type="module" crossorigin src="/assets/index-lzTCdWAt.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BxJEwNUm.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

mxready/resources/rules/v1/core.yml

@@ -0,0 +1,634 @@
+- id: MXR-TOOLCHAIN-001
+  version: 2
+  title: 检测直接 nvcc 工具调用
+  category: toolchain
+  severity: blocker
+  # Makefile / *.mk 必须在内：CUDA 侧大量项目（含 cuda-samples）用 Make 构建，
+  # cu-bridge 的官方入口 make_maca 本身就是 make 包装器。此前这里漏掉 Makefile，
+  # 导致 `NVCC = nvcc` 这类最容易命中的写法完全不可见。
+  file_globs:
+    [
+      "**/*.py",
+      "**/*.sh",
+      "**/*.cmake",
+      "**/CMakeLists.txt",
+      "**/Makefile",
+      "**/makefile",
+      "**/GNUmakefile",
+      "**/*.mk",
+    ]
+  patterns:
+    - type: regex
+      expression: '(?:subprocess\.(?:run|Popen|call|check_call|check_output)|os\.system)\s*\([^\n]{0,200}\bnvcc\b'
+      flags: [IGNORECASE]
+    - type: regex
+      expression: '(?m)^\s*(?:NVCC|CMAKE_CUDA_COMPILER)\s*=\s*[^\n]*\bnvcc\b'
+      flags: [IGNORECASE]
+    - type: regex
+      expression: '(?m)^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:\S*/)?nvcc(?!\s*=)(?:\s|$)'
+      flags: [IGNORECASE]
+  message: 项目直接调用或固定指定 nvcc，迁移到 MXMACA/cu-bridge 时工具入口与参数需要复核。
+  recommendation: 请复核调用点，按 cu-bridge 当前版本配置对应工具链，并在沐曦环境验证构建。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-TOOLCHAIN-002
+  version: 1
+  title: 识别 cu-bridge 工具链接入
+  category: toolchain
+  severity: info
+  file_globs:
+    [
+      "**/*.py",
+      "**/*.sh",
+      "**/*.cmake",
+      "**/CMakeLists.txt",
+      "**/Makefile",
+      "**/makefile",
+      "**/GNUmakefile",
+      "**/*.mk",
+      "**/Dockerfile",
+      "**/*.dockerfile",
+    ]
+  patterns:
+    - type: fact
+      name: uses_cu_bridge_toolchain
+      equals: true
+  message: 项目已包含 cu-bridge 工具链入口（make_maca / cmake_maca / cucc / CUCC_* 环境变量），构建层已接入 MXMACA 兼容层。
+  recommendation: 请复核 cu-bridge 版本与 conf.json 的覆盖范围，并在沐曦环境验证构建；若有脚本绕过包装器直接调用 nvcc，仍需单独处理。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+    - title: cu-bridge 使用手册
+      url: https://gitee.com/p4ul/cu-bridge/tree/master
+
+- id: MXR-PATH-001
+  version: 1
+  title: 检测硬编码 CUDA 安装路径
+  category: path
+  severity: warning
+  file_globs:
+    [
+      "**/*.py",
+      "**/*.sh",
+      "**/*.cmake",
+      "**/CMakeLists.txt",
+      "**/*.toml",
+      "**/*.cfg",
+      "**/Makefile",
+      "**/makefile",
+      "**/GNUmakefile",
+      "**/*.mk",
+    ]
+  patterns:
+    - type: regex
+      expression: '/usr/local/cuda(?:/|\b)'
+  message: 项目硬编码了 /usr/local/cuda，可能绕过 MXMACA/cu-bridge 提供的工具链路径。
+  recommendation: 请将路径改为可配置项，复核 cu-bridge 环境变量，并在沐曦服务器验证解析结果。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-PYTORCH-001
+  version: 1
+  title: 识别 PyTorch CUDAExtension
+  category: pytorch-extension
+  severity: info
+  file_globs: ["**/*.py"]
+  patterns:
+    - type: fact
+      name: uses_torch_cuda_extension
+      equals: true
+  message: 项目通过 PyTorch CUDAExtension 构建原生扩展，需要准备与目标工具链匹配的编译环境。
+  recommendation: 请复核扩展源文件、编译参数与依赖库，并在 MXMACA PyTorch 环境完成最小构建验证。
+  references:
+    - title: PyTorch C++/CUDA extensions
+      url: https://docs.pytorch.org/docs/stable/cpp_extension.html
+
+- id: MXR-DEPENDENCY-001
+  version: 1
+  title: 检测 flash-attn 依赖
+  category: dependency
+  severity: warning
+  file_globs: ["**/requirements*.txt", "**/pyproject.toml", "**/setup.cfg", "**/setup.py"]
+  patterns:
+    - type: dependency
+      name: flash-attn
+  message: 项目声明了 flash-attn，其原生扩展、架构参数与版本组合需要在目标平台单独验证。
+  recommendation: 请复核 flash-attn 版本和构建选项，先验证最小导入与算子，再运行项目级测试。
+  references:
+    - title: PyTorch C++/CUDA extensions
+      url: https://docs.pytorch.org/docs/stable/cpp_extension.html
+
+- id: MXR-CMAKE-001
+  version: 1
+  title: 识别 CMake CUDA 语言
+  category: cmake
+  severity: info
+  file_globs: ["**/CMakeLists.txt", "**/*.cmake"]
+  patterns:
+    - type: fact
+      name: uses_cmake_cuda_language
+      equals: true
+  message: CMake 项目启用了 CUDA 语言，目标环境需要提供与工程探测逻辑匹配的编译器。
+  recommendation: 请复核 CMake 工具链选择和语言探测结果，并在 MXMACA/cu-bridge 环境验证配置阶段。
+  references:
+    - title: CMake FindCUDAToolkit
+      url: https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html
+
+- id: MXR-CMAKE-002
+  version: 1
+  title: 检测 CMake FindCUDAToolkit
+  category: cmake
+  severity: warning
+  file_globs: ["**/CMakeLists.txt", "**/*.cmake"]
+  patterns:
+    - type: regex
+      expression: '\bfind_package\s*\(\s*CUDAToolkit\b'
+      flags: [IGNORECASE]
+  message: 工程显式查找 NVIDIA CUDAToolkit，其搜索路径和导入目标带有工具链假设。
+  recommendation: 请复核 CUDAToolkit_ROOT、导入目标和链接库，并在 cu-bridge 环境验证 CMake 配置。
+  references:
+    - title: CMake FindCUDAToolkit
+      url: https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html
+
+- id: MXR-ARCH-001
+  version: 1
+  title: 检测 CUDA gencode 参数
+  category: architecture
+  severity: warning
+  file_globs: ["**/*.py", "**/*.sh", "**/*.cmake", "**/CMakeLists.txt", "**/*.toml", "**/*.cfg"]
+  patterns:
+    - type: regex
+      expression: '(?:-gencode|--generate-code)(?:[=\s]|$)'
+  message: 构建参数显式生成 NVIDIA compute/sm 目标，可能固化了设备架构假设。
+  recommendation: 请复核目标架构参数，依据 MXMACA 工具链要求调整，并在沐曦设备验证生成物。
+  references:
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+
+- id: MXR-ARCH-002
+  version: 1
+  title: 检测硬编码 sm 或 compute 架构
+  category: architecture
+  severity: warning
+  file_globs: ["**/*.py", "**/*.sh", "**/*.cmake", "**/CMakeLists.txt", "**/*.toml", "**/*.cfg"]
+  patterns:
+    - type: regex
+      expression: '\b(?:sm|compute)_[0-9]{2,3}\b'
+      flags: [IGNORECASE]
+  message: 项目硬编码了 NVIDIA sm/compute 架构编号，需要确认目标编译器如何处理该配置。
+  recommendation: 请复核架构列表是否可配置，并在 MXMACA 工具链上验证编译参数和运行结果。
+  references:
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+
+- id: MXR-TOOL-001
+  version: 1
+  title: 检测直接 nvidia-smi 调用
+  category: tool
+  severity: warning
+  file_globs:
+    [
+      "**/*.py",
+      "**/*.sh",
+      "**/Makefile",
+      "**/makefile",
+      "**/GNUmakefile",
+      "**/*.mk",
+    ]
+  patterns:
+    - type: regex
+      expression: '(?:subprocess\.(?:run|Popen|call|check_call|check_output)|os\.system)\s*\([^\n]{0,200}\bnvidia-smi\b'
+      flags: [IGNORECASE]
+    - type: regex
+      expression: '(?m)^\s*(?:\S*/)?nvidia-smi(?:\s|$)'
+      flags: [IGNORECASE]
+  message: 项目直接调用 nvidia-smi，设备发现或诊断流程依赖 NVIDIA 专用工具。
+  recommendation: 请复核诊断逻辑并提供可替换工具入口，再在沐曦服务器验证设备信息采集。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-COMM-001
+  version: 1
+  title: 检测 NCCL 环境变量覆盖
+  category: communication
+  severity: warning
+  file_globs: ["**/*.py", "**/*.sh", "**/*.toml", "**/*.cfg"]
+  patterns:
+    - type: regex
+      expression: '(?m)^\s*os\.environ\[(?=[^\]\n]*NCCL_[A-Z0-9_])[^\]\n]*\]\s*='
+    - type: regex
+      expression: '(?m)^\s*(?:export\s+)?NCCL_[A-Z0-9_]+\s*='
+  message: 项目覆盖了 NVIDIA NCCL 环境变量，多卡通信配置包含平台特定假设。
+  recommendation: 请复核通信后端、环境变量和拓扑配置，并在沐曦多卡环境进行针对性验证。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-DEPENDENCY-002
+  version: 1
+  title: 检测 bitsandbytes 依赖
+  category: dependency
+  severity: warning
+  file_globs: ["**/requirements*.txt", "**/pyproject.toml", "**/setup.cfg", "**/setup.py"]
+  patterns:
+    - type: dependency
+      name: bitsandbytes
+  message: bitsandbytes 包含原生 GPU 组件和设备相关构建逻辑，需要单独确认目标平台版本。
+  recommendation: 请复核依赖版本、预编译包来源和算子覆盖，并在沐曦环境验证导入与核心功能。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-DEPENDENCY-003
+  version: 1
+  title: 检测 xformers 依赖
+  category: dependency
+  severity: warning
+  file_globs: ["**/requirements*.txt", "**/pyproject.toml", "**/setup.cfg", "**/setup.py"]
+  patterns:
+    - type: dependency
+      name: xformers
+  message: xformers 可能构建并选择设备特定的原生算子，需确认版本与工具链组合。
+  recommendation: 请复核 xformers 构建选项和算子回退路径，并在沐曦环境验证项目实际调用链。
+  references:
+    - title: PyTorch C++/CUDA extensions
+      url: https://docs.pytorch.org/docs/stable/cpp_extension.html
+
+- id: MXR-DEPENDENCY-004
+  version: 1
+  title: 检测 TensorRT 依赖或导入
+  category: dependency
+  severity: blocker
+  file_globs: ["**/requirements*.txt", "**/pyproject.toml", "**/setup.cfg", "**/setup.py", "**/*.py"]
+  patterns:
+    - type: dependency
+      name: tensorrt
+    - type: fact
+      name: imports_tensorrt
+      equals: true
+  message: 项目直接依赖或导入 TensorRT，当前执行路径包含 NVIDIA 专用运行时边界。
+  recommendation: 请复核是否存在可替换后端或隔离路径，并先验证沐曦目标栈的等价推理流程。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-HEADER-001
+  version: 1
+  title: 识别 cuda_runtime.h 头文件
+  category: header
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '(?m)^\s*#\s*include\s*[<"]cuda_runtime\.h[>"]'
+  message: 源码直接包含 CUDA Runtime 头文件，需要由目标兼容层和工具链提供相应映射。
+  recommendation: 请复核使用到的 Runtime API，并结合 cu-bridge 当前版本在沐曦环境验证编译与功能。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-HEADER-002
+  version: 1
+  title: 识别 cuda.h 驱动头文件
+  category: header
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '(?m)^\s*#\s*include\s*[<"]cuda\.h[>"]'
+  message: 源码直接包含 CUDA Driver 头文件，需要核对所用 Driver API 的目标映射。
+  recommendation: 请复核 Driver API 调用范围，并结合 cu-bridge 文档在沐曦环境验证编译与行为。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-INTRINSIC-001
+  version: 1
+  title: 检测 CUDA warp 同步内建函数
+  category: intrinsic
+  severity: warning
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\b__(?:shfl(?:_(?:up|down|xor))?_sync|ballot_sync|activemask)\s*\('
+  message: 内核使用 warp 同步内建函数，其掩码、warp 宽度和硬件执行假设需要复核。
+  recommendation: 请复核内建函数语义与 warp 假设，并依据性能指南在沐曦设备验证正确性和性能。
+  references:
+    - title: CUDA Programming Guide
+      url: https://docs.nvidia.com/cuda/cuda-programming-guide/
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+
+- id: MXR-KERNEL-001
+  version: 1
+  title: 检测 __launch_bounds__ 调优假设
+  category: kernel
+  severity: warning
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\b__launch_bounds__\s*\('
+  message: 内核使用 __launch_bounds__ 固化线程和寄存器调优假设，目标架构的最佳配置可能不同。
+  recommendation: 请复核线程块和资源约束，并依据 MXMACA 性能指南在沐曦设备重新验证调优参数。
+  references:
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+    - title: CUDA Programming Guide
+      url: https://docs.nvidia.com/cuda/cuda-programming-guide/
+
+- id: MXR-GRAPH-001
+  version: 1
+  title: 检测 CUDA Graph API
+  category: graph
+  severity: warning
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcudaGraph[A-Za-z0-9_]*\s*\('
+  message: 项目调用 CUDA Graph API，图构建、更新和执行行为需要在目标运行时单独确认。
+  recommendation: 请复核实际使用的 Graph API 与错误处理路径，并在沐曦环境验证功能和收益。
+  references:
+    - title: CUDA Programming Guide
+      url: https://docs.nvidia.com/cuda/cuda-programming-guide/
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-BUILD-001
+  version: 1
+  title: 检测 TORCH_CUDA_ARCH_LIST 覆盖
+  category: build
+  severity: warning
+  file_globs: ["**/*.py", "**/*.sh", "**/*.toml", "**/*.cfg"]
+  patterns:
+    - type: regex
+      expression: '(?m)^\s*os\.environ\[[^\]\n]*TORCH_CUDA_ARCH_LIST[^\]\n]*\]\s*='
+    - type: regex
+      expression: '(?m)^\s*(?:export\s+)?TORCH_CUDA_ARCH_LIST\s*='
+  message: 项目显式覆盖 TORCH_CUDA_ARCH_LIST，构建产物可能绑定 NVIDIA 架构列表。
+  recommendation: 请复核 PyTorch 扩展的架构选择方式，移除不适用假设，并在 MXMACA 环境验证构建。
+  references:
+    - title: PyTorch C++/CUDA extensions
+      url: https://docs.pytorch.org/docs/stable/cpp_extension.html
+
+- id: MXR-PYTORCH-002
+  version: 1
+  title: 识别 PyTorch JIT 原生扩展
+  category: pytorch-extension
+  severity: info
+  file_globs: ["**/*.py"]
+  patterns:
+    - type: fact
+      name: uses_torch_cpp_extension_load
+      equals: true
+  message: 项目使用 torch.utils.cpp_extension.load 在运行时编译扩展，执行环境必须具备完整工具链。
+  recommendation: 请复核 JIT 源码、缓存、编译参数与依赖，并在 MXMACA 环境验证首次和重复加载。
+  references:
+    - title: PyTorch C++/CUDA extensions
+      url: https://docs.pytorch.org/docs/stable/cpp_extension.html
+
+- id: MXR-DOCKER-001
+  version: 1
+  title: 检测 NVIDIA GPU 容器基础镜像与运行时配置
+  category: docker
+  severity: warning
+  file_globs: ["**/Dockerfile", "**/*.dockerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml"]
+  patterns:
+    - type: regex
+      expression: '^\s*FROM\s+(?:nvidia/cuda|nvcr\.io|nvidia/cudagl|nvidia/tensorrt|nvidia/tritonserver)(?:[:/\s]|$)'
+      flags: [IGNORECASE, MULTILINE]
+    - type: regex
+      expression: '(?:nvidia-docker|nvidia-container-runtime|--gpus\s|--runtime\s*=\s*nvidia|gpus:\s*all)'
+      flags: [IGNORECASE]
+  message: 镜像或运行配置基于 NVIDIA GPU 容器体系，迁移到沐曦环境需要更换基础镜像与容器运行时参数。
+  recommendation: 请复核基础镜像来源、--gpus/--runtime 参数与 GPU 设备挂载方式，替换为沐曦环境的等价方案后验证容器内算子。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-MEMORY-001
+  version: 1
+  title: 检测 CUDA 显存管理 Runtime API
+  category: runtime
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcuda(?:Malloc|MallocAsync|MallocManaged|Free|FreeAsync)\s*\('
+      flags: [IGNORECASE]
+  message: 源码调用 CUDA 显存管理 Runtime API，需要确认 cu-bridge 对相应 API 的映射与行为差异。
+  recommendation: 请复核显存分配/释放调用点与错误处理，并结合 cu-bridge 当前版本在沐曦环境验证。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-STREAM-001
+  version: 1
+  title: 检测 CUDA 流（Stream）API
+  category: runtime
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcudaStream[A-Za-z0-9]*\s*\('
+      flags: [IGNORECASE]
+  message: 源码调用 CUDA 流（Stream）API，流创建、同步与事件语义需要结合目标运行时确认。
+  recommendation: 请复核流与事件的使用方式，并在沐曦环境验证并发与同步行为。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-DEVICE-001
+  version: 1
+  title: 检测 CUDA 设备管理 API
+  category: runtime
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcuda(?:SetDevice|GetDevice|GetDeviceCount|DeviceSynchronize|DeviceReset)\s*\('
+      flags: [IGNORECASE]
+  message: 源码调用 CUDA 设备管理 API，多设备枚举与选择逻辑包含平台假设。
+  recommendation: 请复核设备选择与同步逻辑，并在沐曦环境验证设备枚举与上下文行为。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-COMM-002
+  version: 1
+  title: 检测 torch.distributed NCCL 通信后端
+  category: communication
+  severity: warning
+  file_globs: ["**/*.py"]
+  patterns:
+    - type: regex
+      expression: '\b(?:init_process_group|new_group)\s*\(\s*[''"]nccl[''"]'
+    - type: regex
+      expression: '\b(?:init_process_group|new_group)\s*\([^\n]{0,200}\bbackend\s*=\s*[''"]nccl[''"]'
+  message: 项目将分布式通信后端指定为 NCCL，迁移到沐曦环境需要确认通信库与后端的等价映射。
+  recommendation: 请复核通信后端选择、初始化参数与多卡拓扑，并在沐曦多卡环境验证集合通信行为。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-DEPENDENCY-005
+  version: 1
+  title: 检测 apex 依赖或导入
+  category: dependency
+  severity: warning
+  file_globs: ["**/requirements*.txt", "**/pyproject.toml", "**/setup.cfg", "**/setup.py", "**/*.py"]
+  patterns:
+    - type: dependency
+      name: apex
+    - type: dependency
+      name: nvidia-apex
+    - type: fact
+      name: imports_apex
+      equals: true
+  message: 项目依赖或导入 apex，其混合精度与融合算子包含设备相关原生组件，需要单独确认目标平台版本。
+  recommendation: 请复核 apex 版本、算子覆盖与混合精度路径，并在沐曦环境验证导入与核心功能。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-LIBRARY-001
+  version: 1
+  title: 识别 cuBLAS / cuDNN / cuFFT / cuSPARSE / cuSOLVER 头文件
+  category: library
+  severity: warning
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '(?m)^\s*#\s*include\s*[<"](?:cublas|cublasLt|cudnn|cufft|cusparse|cusolver)[A-Za-z0-9_-]*\.h[>"]'
+  message: 源码直接包含 NVIDIA 数学库头文件，目标环境需要由兼容层或等价库提供相应 API 映射。
+  recommendation: 请复核实际使用的库 API 与链接配置，并结合 cu-bridge 当前版本在沐曦环境验证编译与数值行为。
+  references:
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+
+- id: MXR-RUNTIME-001
+  version: 1
+  title: 检测 CUDA 数据拷贝与事件 Runtime API
+  category: runtime
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cc", "**/*.cpp", "**/*.c", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcuda(?:Memcpy|MemcpyAsync|Memcpy2D|Memcpy2DAsync|MemcpyPeer|MemcpyPeerAsync|Memset|MemsetAsync|EventCreate|EventRecord|EventSynchronize|EventQuery|EventElapsedTime|EventDestroy)\s*\('
+      flags: [IGNORECASE]
+  message: 源码调用 CUDA 数据拷贝或事件 API，其同步语义与错误处理需要结合目标运行时确认。
+  recommendation: 请复核拷贝路径、同步点与事件使用方式，并在沐曦环境验证数据一致性与性能。
+  references:
+    - title: CUDA Programming Guide
+      url: https://docs.nvidia.com/cuda/cuda-programming-guide/
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-TEST-001
+  version: 1
+  title: 检测 CUDA 可用性静默跳过测试
+  category: test
+  severity: warning
+  file_globs: ["**/*.py"]
+  patterns:
+    - type: regex
+      expression: 'skipif\s*\([^\n]*\bnot\s+torch\.cuda\.is_available\(\)'
+    - type: regex
+      expression: 'skipUnless\s*\([^\n]*torch\.cuda\.is_available\(\)'
+  message: 测试在 torch.cuda 不可用时静默跳过，迁移到沐曦环境后可能因环境未配置而跳过，造成验证通过的假象。
+  recommendation: 请复核跳过条件，并在真机环境手动运行核心 CUDA 测试以确认实际覆盖。
+  references:
+    - title: pytest skipif documentation
+      url: https://docs.pytest.org/
+    - title: unittest skipUnless documentation
+      url: https://docs.python.org/3/library/unittest.html
+
+- id: MXR-PYTORCH-003
+  version: 1
+  title: 识别 PyTorch 自动混合精度用法
+  category: runtime
+  severity: info
+  file_globs: ["**/*.py"]
+  patterns:
+    - type: regex
+      expression: '\b(?:torch\.cuda\.amp|torch\.amp)\b|\b(?:autocast|GradScaler)\s*\('
+  message: 项目使用 PyTorch 自动混合精度，目标环境的半精度算子支持与缩放行为需要结合 MXMACA 版本验证。
+  recommendation: 请复核混合精度路径与缩放器行为，并依据 MXMACA 性能指南在沐曦设备验证精度与性能。
+  references:
+    - title: MXMACA performance tuning guide
+      url: https://gitee.com/metax-maca/mxmaca-performance-tuning-guide
+    - title: MetaX-MACA cu-bridge
+      url: https://gitee.com/metax-maca/cu-bridge
+
+- id: MXR-PTX-001
+  version: 1
+  title: 检测内联 PTX 汇编
+  category: ptx
+  severity: blocker
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cpp", "**/*.cc", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\b(?:__asm__|asm)\s*(?:(?:__volatile__|volatile)\s*)?\(\s*"'
+  message: 内联汇编块嵌入的是 NVIDIA 虚拟 ISA（PTX）指令，MXMACA 后端不执行 PTX；这类代码可能固化 NVIDIA 指令语义。
+  recommendation: 请逐处复核 asm 块对应的硬件能力，改用目标平台支持的内建函数或等价 C++ 实现，并在沐曦环境验证功能与性能。
+  references:
+    - title: NVIDIA Inline PTX Assembly
+      url: https://docs.nvidia.com/cuda/inline-ptx-assembly/index.html
+    - title: MXMACA runtime API guide
+      url: https://developer.metax-tech.com/api/client/document/preview/567/C500_RuntimeAPIProgrammingGuide_CN.html
+
+- id: MXR-WARP-001
+  version: 1
+  title: 检测硬编码 32 线程束假设
+  category: warp
+  severity: blocker
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cpp", "**/*.cc", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '(?m)^(?!\s*(?://|/\*|\*))[^\n]*threadIdx\.x\s*[%/&]\s*(?:31|32)\b'
+    - type: regex
+      expression: '(?m)^\s*#\s*define\s+(?:WARP_SIZE|WARPSIZE)\s+32\b'
+    - type: regex
+      expression: '(?m)^(?!\s*(?://|/\*|\*))[^\n]*\b(?:WARP_SIZE|warp_size|WARPSIZE)\s*=\s*32\b'
+  message: 代码按 32 线程一组计算 lane 或定义线程束宽度常量；MXMACA 的线程束（wave）宽度为 64，这类算术可能编译通过但结果错位。
+  recommendation: 请复核 lane 计算与掩码宽度，改用运行时查询的线程束宽度，并在沐曦环境用最小用例比对结果。
+  references:
+    - title: MXMACA runtime API guide
+      url: https://developer.metax-tech.com/api/client/document/preview/567/C500_RuntimeAPIProgrammingGuide_CN.html
+
+- id: MXR-THRUST-001
+  version: 1
+  title: 识别 Thrust 用法
+  category: library
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cpp", "**/*.cc", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bthrust::[A-Za-z_]'
+  message: 项目使用 Thrust；MXMACA 提供 mcThrust wrapper 并在编译期自动接入，通常无需改动源码，接口对齐情况需按版本确认。
+  recommendation: 请复核 Thrust 版本与 mcThrust 的对应关系，并在沐曦环境验证编译与结果。
+  references:
+    - title: MXMACA AI training manual
+      url: https://developer.metax-tech.com/api/client/document/preview/587/C500_AITrainningMaunal_CN.html
+
+- id: MXR-CUB-001
+  version: 1
+  title: 识别 CUB 用法
+  category: library
+  severity: info
+  file_globs: ["**/*.cu", "**/*.cuh", "**/*.cpp", "**/*.cc", "**/*.h", "**/*.hpp"]
+  patterns:
+    - type: regex
+      expression: '\bcub::[A-Za-z_]'
+    - type: regex
+      expression: '(?m)^\s*#\s*include\s*[<"]cub/[A-Za-z0-9_./]+[>"]'
+  message: 项目使用 CUB；MXMACA 提供 mcCUB 且对外 API 接口不变，通常无需改动源码。
+  recommendation: 请复核 CUB 版本与 mcCUB 的对应关系，并在沐曦环境验证编译与结果。
+  references:
+    - title: MXMACA AI training manual
+      url: https://developer.metax-tech.com/api/client/document/preview/587/C500_AITrainningMaunal_CN.html

mxready/resources/rules/v1/manifest.yml

@@ -0,0 +1,4 @@
+schema_version: "1.0"
+ruleset_version: "4"
+rule_files:
+  - core.yml