From 7fed960029e9a31596f812b2ffcc475734239036 Mon Sep 17 00:00:00 2001
From: x15904151985 <15904151985@163.com>
Date: Fri, 10 Apr 2026 15:30:12 +0800
Subject: [PATCH] 20260410-153006

---
 README.md     |  56 +++++++++-
 py-cpuinfo.md | 276 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 329 insertions(+), 3 deletions(-)
 create mode 100644 py-cpuinfo.md

diff --git a/README.md b/README.md
index 83e1b6f..e8276a1 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,19 @@
 # Python-Learning-Resources
 本项目用于整理和记录 Python 学习过程中的重要资料与工具文档，方便查阅与系统学习。
+
 # 目录结构
-Python-Learning-Resources/  
-├── [README.md](README.md)       # 项目主说明文件  
-└── [psutil](psutil.md)       # psutil 库详细功能文档
+
+| 类型 | 名称 | 说明 |
+| :---: | --- | --- |
+| 库 |  |  |
+|| [psutil](#psutil-快速概览) | 平台系统监控库，涵盖 CPU、内存、磁盘、网络、进程管理等核心功能。 |
+|| [py-cpuinfo](#py-cpuinfo-快速概览) | 用于跨平台获取 CPU 型号、核心数、频率、缓存、指令集等信息。 |
 
 ---
+
 当前包含：
 - [psutil 详细功能文档](psutil.md)：跨平台系统监控库 `psutil` 的完整使用指南，涵盖 CPU、内存、磁盘、网络、进程管理等核心功能。
+- [py-cpuinfo 详细使用文档](py-cpuinfo.md)：轻量级 Python 库 `py-cpuinfo` 的完整使用指南，用于跨平台获取 CPU 型号、核心数、频率、缓存、指令集等信息。
 
 ---
 
@@ -46,14 +52,58 @@ print(psutil.pids())    # 查看所有进程 PID
 ```
 
 详细用法请参考 [psutil.md](psutil.md)。
+
+---
+
+## py-cpuinfo 快速概览
+
+`py-cpuinfo` 是一个轻量级的 Python 库，用于**跨平台获取 CPU 信息**，无需安装系统级依赖，适用于 Linux / Windows / macOS / BSD 等系统。它常用于性能分析、环境检测、硬件审计、自动化运维等场景。
+
+### 核心功能
+
+- **基础信息**：CPU 型号、厂商、架构、家族编号
+- **核心与线程**：物理核心数、逻辑 CPU 数量、每核线程数
+- **频率信息**：标称主频、当前实际主频
+- **缓存信息**：L1/L2/L3 缓存大小
+- **指令集支持**：AVX、SSE、AES 等指令集检测
+
+### 安装
+
+```bash
+pip install py-cpuinfo
+```
+
+### 快速开始
+
+```python
+from cpuinfo import get_cpu_info
+
+info = get_cpu_info()
+print(info['brand_raw'])  # 输出 CPU 型号
+print(f"物理核心: {info['cores']}, 逻辑核心: {info['count']}")
+print(f"标称频率: {info['hz_advertised_friendly']}")
+```
+
+详细用法请参考 [py-cpuinfo.md](py-cpuinfo.md)。
+
+---
+
 ### 适用场景
 
+**psutil 适用场景：**
 - 系统资源实时监控
 - 服务器性能分析
 - 进程级资源审计
 - 自动化运维脚本
 - 安全/异常进程检测
 
+**py-cpuinfo 适用场景：**
+- 性能调优与环境检测
+- 软件兼容性判断
+- 硬件审计与资产盘点
+- 自动化运维脚本
+- CPU 特性检测（如 AVX、AES 支持）
+
 ---
 
 > 更多 Python 学习资源将持续更新到此仓库。
\ No newline at end of file
diff --git a/py-cpuinfo.md b/py-cpuinfo.md
new file mode 100644
index 0000000..d790023
--- /dev/null
+++ b/py-cpuinfo.md
@@ -0,0 +1,276 @@
+# py-cpuinfo 详细使用文档
+
+**py-cpuinfo** 是一个轻量级的 Python 库，用于**跨平台获取 CPU 信息**，无需安装系统级依赖，适用于 Linux / Windows / macOS / BSD 等系统。它常用于性能分析、环境检测、硬件审计、自动化运维等场景。
+
+---
+
+## 一、简介
+
+- **项目名称**：py-cpuinfo  
+- **GitHub**：https://github.com/workhorsy/py-cpuinfo  
+- **主要功能**：  
+  - 获取 CPU 型号、厂商、架构  
+  - 获取 CPU 核心数（物理 / 逻辑）  
+  - 获取 CPU 频率、缓存大小  
+  - 获取 CPU 支持的指令集（如 AVX、SSE、AES）  
+- **特点**：  
+  - 纯 Python 实现  
+  - 无外部依赖  
+  - 跨平台兼容性好  
+
+---
+
+## 二、安装方法
+
+### 1. 使用 pip 安装（推荐）
+
+```bash
+pip install py-cpuinfo
+```
+
+### 2. 验证安装是否成功
+
+```bash
+python -c "import cpuinfo; print(cpuinfo.get_cpu_info()['brand_raw'])"
+```
+
+如果输出了 CPU 型号名称，说明安装成功。
+
+---
+
+## 三、快速入门示例
+
+```python
+from cpuinfo import get_cpu_info
+
+info = get_cpu_info()
+print(info)
+```
+
+该代码会返回一个包含 CPU 所有信息的字典对象。
+
+---
+
+## 四、核心 API 说明
+
+### 1. `cpuinfo.get_cpu_info()`
+
+**功能**：获取完整的 CPU 信息  
+**返回值类型**：`dict`
+
+```python
+from cpuinfo import get_cpu_info
+
+cpu = get_cpu_info()
+```
+
+---
+
+## 五、常用字段详解
+
+以下是 `get_cpu_info()` 返回字典中**最常用、最重要的字段说明**。不同平台字段可能略有差异，但核心字段基本一致。
+
+### 1. 基础信息
+
+| 字段名 | 含义 | 示例 |
+|------|------|------|
+| `brand_raw` | CPU 原始品牌字符串 | `"Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz"` |
+| `vendor_id_raw` | CPU 厂商 ID | `"GenuineIntel"` |
+| `arch` | 架构 | `"X86_64"` |
+| `family` | CPU 家族编号 | `6` |
+| `model` | 型号编号 | `158` |
+| `stepping` | 步进 | `13` |
+
+---
+
+### 2. 核心与线程信息
+
+| 字段名 | 含义 | 示例 |
+|------|------|------|
+| `count` | 逻辑 CPU 数量 | `8` |
+| `cores` | 物理核心数 | `4` |
+| `threads_per_core` | 每核线程数 | `2` |
+
+> ✅ 常见关系：  
+> `逻辑 CPU 数 = 物理核心数 × threads_per_core`
+
+---
+
+### 3. 频率信息（单位：MHz）
+
+| 字段名 | 含义 | 示例 |
+|------|------|------|
+| `hz_advertised_friendly` | 标称主频 | `"3.6000 GHz"` |
+| `hz_actual_friendly` | 当前实际主频 | `"4.9000 GHz"` |
+| `hz_advertised` | 标称主频（数值） | `[3600000000, 0]` |
+| `hz_actual` | 实际主频（数值） | `[4900000000, 0]` |
+
+---
+
+### 4. 缓存信息（单位：字节）
+
+| 字段名 | 含义 | 示例 |
+|------|------|------|
+| `l1_data_cache_size` | L1 数据缓存 | `32768` |
+| `l1_instruction_cache_size` | L1 指令缓存 | `32768` |
+| `l2_cache_size` | L2 缓存 | `262144` |
+| `l3_cache_size` | L3 缓存 | `8388608` |
+
+---
+
+### 5. 指令集支持
+
+| 字段名 | 含义 |
+|------|------|
+| `flags` | CPU 支持的所有指令集标志（列表） |
+
+示例：
+
+```python
+cpu['flags']
+# ['avx', 'avx2', 'sse', 'sse2', 'sse3', 'ssse3', 'aes', ...]
+```
+
+可用于判断 CPU 是否支持某些优化指令，如：
+
+```python
+if 'avx2' in cpu['flags']:
+    print("CPU 支持 AVX2")
+```
+
+---
+
+## 六、常见使用示例
+
+### 1. 获取 CPU 型号
+
+```python
+from cpuinfo import get_cpu_info
+
+cpu = get_cpu_info()
+print(cpu['brand_raw'])
+```
+
+---
+
+### 2. 判断 CPU 厂商
+
+```python
+vendor = cpu['vendor_id_raw']
+if vendor == "GenuineIntel":
+    print("Intel CPU")
+elif vendor == "AuthenticAMD":
+    print("AMD CPU")
+```
+
+---
+
+### 3. 判断 CPU 架构
+
+```python
+arch = cpu['arch']
+print(arch)  # X86_32 / X86_64 / ARM_7 / ARM_8
+```
+
+---
+
+### 4. 判断是否为服务器 CPU（辅助判断）
+
+```python
+if cpu['cores'] >= 16:
+    print("可能是服务器 CPU")
+```
+
+---
+
+### 5. 判断是否支持 AES / AVX2
+
+```python
+if 'aes' in cpu['flags'] and 'avx2' in cpu['flags']:
+    print("适合加密和并行计算")
+```
+
+---
+
+### 6. 获取 CPU 缓存大小（MB）
+
+```python
+l3_mb = cpu['l3_cache_size'] / (1024 * 1024)
+print(f"L3 Cache: {l3_mb:.1f} MB")
+```
+
+---
+
+## 七、命令行用法（CLI）
+
+py-cpuinfo 也提供了简单的命令行工具。
+
+### 1. 查看所有 CPU 信息
+
+```bash
+python -m cpuinfo
+```
+
+### 2. 只查看 CPU 型号
+
+```bash
+python -m cpuinfo | grep brand_raw
+```
+
+---
+
+## 八、平台兼容性说明
+
+| 操作系统 | 支持情况 |
+|--------|--------|
+| Linux | ✅ 完全支持 |
+| Windows | ✅ 完全支持 |
+| macOS | ✅ 支持 |
+| FreeBSD / OpenBSD | ✅ 基本支持 |
+| ARM / x86 | ✅ 均支持 |
+
+⚠️ 注意：
+- 部分字段在某些平台可能为空或不完整  
+- ARM 架构下字段数量通常少于 x86
+
+---
+
+## 九、常见问题（FAQ）
+
+### Q1：为什么 `hz_actual` 为 0？
+A：在某些虚拟化环境或受限系统中，无法读取实时频率，此时通常回退为标称频率。
+
+### Q2：为什么 `cores` 和 `count` 一样？
+A：说明 CPU 不支持超线程（Hyper-Threading）。
+
+### Q3：能否用于生产环境？
+A：可以。py-cpuinfo 是只读、无副作用的库，适合生产环境使用。
+
+---
+
+## 十、最佳实践建议
+
+- ✅ 只读取所需字段，避免一次性解析全部信息  
+- ✅ 在程序启动时缓存结果，避免频繁调用  
+- ✅ 结合 `platform`、`os` 模块一起使用，增强环境判断能力  
+
+示例：
+
+```python
+import platform
+from cpuinfo import get_cpu_info
+
+print(platform.system(), platform.release())
+print(get_cpu_info()['brand_raw'])
+```
+
+---
+
+## 十一、总结
+
+py-cpuinfo 是一个**简单、可靠、跨平台**的 CPU 信息获取工具，非常适合用于：
+
+- 性能调优  
+- 环境检测  
+- 软件兼容性判断  
+- 自动化运维与硬件审计