Phase 1: 硬件探针与能力分级 - 参考文档

模块状态: 待开始 完成度: 0% 更新日期: 2026-03-05 说明: 硬件检测模块尚未实现，依赖基础 CPU/内存检测模块

---

一、模块概述

硬件探针模块是 CFDesktop 项目的能力分级核心，负责在启动时自动检测系统硬件能力，根据检测结果计算硬件档位 (HWTier)，并为上层模块提供对应的能力策略配置。

核心职责

1. 硬件检测 - CPU、GPU、内存、网络自动检测
2. 能力分级 - 根据检测结果计算 Low/Mid/High 三档
3. 策略引擎 - 为各模块提供对应档位的能力配置
4. 配置覆盖 - 支持手动配置和自定义检测脚本

档位定义

档位	典型硬件	动画	渲染	视频解码	内存限制
Low	IMX6ULL (528MHz Cortex-A7)	禁用	linuxfb	软件	< 64MB
Mid	RK3568 (4xCortex-A55, Mali-G52)	部分启用	eglfs可选	H.264/H.265 部分	< 256MB
High	RK3588 (8xCortex-A76/A55, Mali-G610)	全部启用	eglfs+OpenGL ES 3.2+	全格式硬件解码	< 1GB

---

二、当前实现状态

总体完成度: 0%

模块	完成度	实现位置	备注
CPUDetector	80%	base/system/cpu/	核心功能已实现
GPUDetector	0%	-	未实现
MemoryDetector	80%	base/system/memory/	核心功能已实现
NetworkDetector	0%	-	未实现
HWTier 枚举	0%	-	未定义
HardwareProbe 主类	0%	-	未实现
CapabilityPolicy	0%	-	未实现
DeviceConfig	0%	-	未实现

现有相关模块

项目中已存在基础的 CPU 和内存检测模块，可作为硬件探针的基础：

CPU 检测 (base/system/cpu/): - cfcpu.h - CPU 信息查询接口 - cfcpu_bonus.h - CPU 扩展信息 - cfcpu_profile.h - CPU 性能分析 - Linux 实现: private/linux_impl/ - Windows 实现: private/win_impl/

内存检测 (base/system/memory/): - memory_info.h - 内存信息接口 - Linux 实现: private/linux_impl/ - Windows 实现: private/win_impl/

---

三、已完成项清单

3.1 基础系统检测 (部分完成)

CPU 检测模块 (base/system/cpu/)

已完成功能: - CPU 基本信息查询 (型号、核心数、频率) - CPU 特性检测 (NEON, SSE 等) - Linux 平台 /proc/cpuinfo 解析 - Windows 平台 WMI 查询 - CPU 性能分析接口

内存检测模块 (base/system/memory/)

已完成功能: - 物理内存查询 - 可用内存查询 - Swap 内存查询 - DIMM 信息查询 - 进程内存查询 - Linux 平台 /proc/meminfo 解析 - Windows 平台 API 查询

---

四、待完成项清单

4.1 HWTier 枚举定义 (0%)

需求描述: - 定义 Low/Mid/High 三档枚举 - 每档对应硬件配置说明 - 档位字符串转换函数

建议文件路径: base/hardware/HWTier.h

接口设计:

namespace CFDesktop::Base {

enum class HWTier {
    Low,   // IMX6ULL 级别
    Mid,   // RK3568 级别
    High   // RK3588 级别
};

QString tierToString(HWTier tier);
HWTier tierFromString(const QString& str);

} // namespace CFDesktop::Base

4.2 GPU 检测器 (0%)

需求描述: - DRM 设备检测 (/dev/dri/card*) - OpenGL 上下文创建 - GPU 信息查询 (供应商、渲染器、版本) - 扩展列表获取 - 硬件加速能力判断

建议文件路径: - base/hardware/detectors/GPUDetector.h - base/hardware/detectors/GPUDetector.cpp

接口设计:

namespace CFDesktop::Base {

struct GPUInfo {
    QString renderer;
    QString vendor;
    QString version;
    bool hasHardwareAcceleration = false;
    QString driverPath;
    int maxTextureSize = 0;
    QStringList extensions;
};

class GPUDetector {
public:
    static GPUInfo detect();
};

} // namespace CFDesktop::Base

4.3 网络检测器 (0%)

需求描述: - 网络接口枚举 (/sys/class/net/*) - 接口状态检测 - 无线接口识别 - MAC 地址获取 - IP 地址查询

建议文件路径: - base/hardware/detectors/NetworkDetector.h - base/hardware/detectors/NetworkDetector.cpp

接口设计:

namespace CFDesktop::Base {

struct NetworkInterface {
    QString name;
    bool isUp = false;
    bool isWireless = false;
    QString macAddress;
    QStringList ipAddresses;
};

class NetworkDetector {
public:
    static QList<NetworkInterface> detect();
};

} // namespace CFDesktop::Base

4.4 HardwareProbe 主类 (0%)

需求描述: - 整合所有检测器 - 实现档位计算逻辑 - 单例模式 - Mock 数据支持

建议文件路径: - base/hardware/HardwareProbe.h - base/hardware/HardwareProbe.cpp

接口设计:

namespace CFDesktop::Base {

struct HardwareInfo {
    HWTier tier = HWTier::Low;
    CPUInfo cpu;
    GPUInfo gpu;
    MemoryInfo memory;
    QList<NetworkInterface> networkInterfaces;
    QString deviceTreeCompatible;
    bool isUserOverridden = false;
};

class HardwareProbe : public QObject {
    Q_OBJECT

public:
    static HardwareProbe* instance();
    HardwareInfo probe();
    HardwareInfo forceRedetect();
    HWTier currentTier() const;
    const HardwareInfo& hardwareInfo() const;
    void setMockData(const HardwareInfo& mockInfo);

signals:
    void probeCompleted(const HardwareInfo& info);
    void tierChanged(HWTier newTier);

private:
    HardwareProbe(QObject* parent = nullptr);
    void calculateTier(HardwareInfo& info);
};

} // namespace CFDesktop::Base

4.5 CapabilityPolicy 策略引擎 (0%)

需求描述: - 定义各策略结构体 - 实现档位特定策略配置 - 策略查询接口

建议文件路径: - base/hardware/CapabilityPolicy.h - base/hardware/CapabilityPolicy.cpp

接口设计:

namespace CFDesktop::Base {

struct AnimationPolicy {
    bool enabled = false;
    int defaultDurationMs = 0;
    int maxConcurrentAnimations = 0;
    bool allowComplexEffects = false;
};

struct RenderingPolicy {
    QString qtPlatform;
    bool useOpenGL = false;
    QString openGLVersion;
    bool useVSync = false;
    int maxFPS = 60;
};

struct VideoDecoderPolicy {
    bool useHardwareDecoder = false;
    QStringList supportedCodecs;
    int maxResolution = 0;
    int maxBitrate = 0;
};

struct MemoryPolicy {
    int maxImageCacheBytes = 0;
    int maxFontCacheBytes = 0;
    bool enableTextureCompression = false;
    int maxWindowSurfaces = 0;
};

class CapabilityPolicy : public QObject {
    Q_OBJECT

public:
    static CapabilityPolicy* instance();
    AnimationPolicy getAnimationPolicy() const;
    RenderingPolicy getRenderingPolicy() const;
    VideoDecoderPolicy getVideoDecoderPolicy() const;
    MemoryPolicy getMemoryPolicy() const;
    HWTier currentTier() const;
    void overrideTier(HWTier tier);

signals:
    void policyChanged(HWTier newTier);
};

} // namespace CFDesktop::Base

4.6 DeviceConfig 配置文件 (0%)

需求描述: - INI 格式配置文件解析 - 支持档位手动覆盖 - 自定义检测脚本执行

建议文件路径: - base/hardware/DeviceConfig.h - base/hardware/DeviceConfig.cpp

配置文件格式 (/etc/CFDesktop/device.conf):

[Device]
Tier=auto|low|mid|high
CustomScript=/opt/cfdesktop/detect-hardware.sh
BoardName=Generic-Board

[Overrides]
EnableAnimations=true
AnimationDuration=200
RenderingBackend=auto
ForceOpenGL=false
VideoDecoder=auto

[Logging]
LogLevel=Info

---

五、Mock 数据集设计

5.1 测试数据目录结构

tests/mock/
└── proc/
    ├── cpuinfo_imx6ull          # IMX6ULL CPU 信息
    ├── cpuinfo_rk3568           # RK3568 CPU 信息
    ├── cpuinfo_rk3588           # RK3588 CPU 信息
    ├── meminfo_512mb            # 512MB 内存
    ├── meminfo_1gb              # 1GB 内存
    ├── meminfo_4gb              # 4GB 内存
    └── devices/
        └── dri/
            └── card0            # 模拟 GPU 设备

5.2 Mock 数据示例

IMX6ULL CPU 信息 (cpuinfo_imx6ull):

processor       : 0
model name      : ARMv7 Processor rev 5 (v7l)
BogoMIPS        : 26.00
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva idivt vfpd32 lpae evtstrm crc32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0xc07
CPU revision    : 5

Hardware        : Freescale i.MX6 UltraLite (Device Tree)
Revision        : 0000
Serial          : 0000000000000000

512MB 内存信息 (meminfo_512mb):

MemTotal:         524288 kB
MemFree:          262144 kB
MemAvailable:     393216 kB
Buffers:           16384 kB
Cached:           131072 kB
SwapTotal:             0 kB
SwapFree:              0 kB

---

六、单元测试设计

6.1 测试用例清单

文件: test/hardware/test_hardware_probe.cpp

class TestHardwareProbe : public QObject {
    Q_OBJECT

private slots:
    // CPU 检测测试
    void testDetectCPU_IMX6ULL();
    void testDetectCPU_RK3568();
    void testDetectCPU_RK3588();

    // GPU 检测测试
    void testDetectGPU_WithDRM();
    void testDetectGPU_NoDRM();
    void testDetectGPU_OpenGLContext();

    // 内存检测测试
    void testDetectMemory_512MB();
    void testDetectMemory_1GB();
    void testDetectMemory_4GB();

    // 档位计算测试
    void testCalculateTier_IMX6ULL_returnsLow();
    void testCalculateTier_RK3568_returnsMid();
    void testCalculateTier_RK3588_returnsHigh();

    // 配置文件测试
    void testDeviceConfig_LoadDefault();
    void testDeviceConfig_OverrideTier();
    void testDeviceConfig_CustomScript();

    // 策略引擎测试
    void testCapabilityPolicy_LowTier();
    void testCapabilityPolicy_MidTier();
    void testCapabilityPolicy_HighTier();
    void testCapabilityPolicy_AnimationDisabledOnLow();

    // 边界情况
    void testEmptyProcFiles();
    void testMalformedConfig();
    void testTierOverride();
};

6.2 评分算法设计

void HardwareProbe::calculateTier(HardwareInfo& info) {
    HWTier calculatedTier = HWTier::Low;
    int score = 0;

    // CPU 评分
    score += std::min(info.cpu.cores, 8) * 10;  // 最多 80 分
    if (info.cpu.frequencyMHz > 1000) score += 20;
    if (info.cpu.features.contains("neon")) score += 10;

    // GPU 评分
    if (info.gpu.hasHardwareAcceleration) score += 50;
    if (!info.gpu.driverPath.isEmpty()) score += 20;

    // 内存评分
    int memoryMB = info.memory.totalBytes / (1024 * 1024);
    if (memoryMB >= 512) score += 20;
    if (memoryMB >= 1024) score += 20;
    if (memoryMB >= 2048) score += 10;

    // 档位判定
    // Low: 0-60, Mid: 61-120, High: 121+
    if (score >= 121) {
        calculatedTier = HWTier::High;
    } else if (score >= 61) {
        calculatedTier = HWTier::Mid;
    } else {
        calculatedTier = HWTier::Low;
    }

    info.tier = calculatedTier;
}

---

七、完成度百分比

模块	原计划需求	已实现	完成度
HWTier 枚举	100%	0%	0%
CPU 检测器	100%	80%	80%
GPU 检测器	100%	0%	0%
内存检测器	100%	80%	80%
网络检测器	100%	0%	0%
HardwareProbe 主类	100%	0%	0%
CapabilityPolicy	100%	0%	0%
DeviceConfig	100%	0%	0%
Mock 数据集	100%	0%	0%
单元测试	100%	0%	0%
总体	100%	18%	18%

---

八、关键文件路径

已实现文件

base/
├── system/
│   ├── cpu/
│   │   ├── cfcpu.h                    # CPU 检测接口
│   │   ├── cfcpu_bonus.h              # CPU 扩展信息
│   │   ├── cfcpu_profile.h            # CPU 性能分析
│   │   └── private/
│   │       ├── linux_impl/            # Linux 实现
│   │       └── win_impl/              # Windows 实现
│   └── memory/
│       ├── memory_info.h              # 内存检测接口
│       └── private/
│           ├── linux_impl/            # Linux 实现
│           └── win_impl/              # Windows 实现
└── include/
    ├── system/cpu/                    # CPU 公共头文件
    └── system/memory/                 # 内存公共头文件

待创建文件

base/
├── hardware/
│   ├── HWTier.h                       # 档位枚举
│   ├── HardwareInfo.h                 # 硬件信息结构体
│   ├── HardwareProbe.h                # 探针主类
│   ├── CapabilityPolicy.h             # 策略引擎
│   ├── DeviceConfig.h                 # 配置文件
│   ├── detectors/
│   │   ├── GPUDetector.h              # GPU 检测器
│   │   └── NetworkDetector.h          # 网络检测器
│   └── platform/
│       ├── LinuxDetector.cpp          # Linux 平台实现
│       └── WindowsDetector.cpp        # Windows 平台实现

测试文件

tests/
├── hardware/
│   ├── test_hardware_probe.cpp        # 主测试
│   ├── test_capability_policy.cpp     # 策略测试
│   └── mock/
│       └── proc/                      # Mock 数据

---

九、下一步行动建议

优先级1 (高)

1. 定义 HWTier 枚举
2. 优先级: 最高
3. 理由: 其他模块依赖此定义

4. 预计工作量: 0.5天

5. 实现 GPUDetector

6. 优先级: 高
7. 理由: 档位判定的关键因素

8. 预计工作量: 2-3天

9. 实现 NetworkDetector

10. 优先级: 中
11. 理由: 网络能力检测
12. 预计工作量: 1-2天

优先级2 (中)

1. 实现 HardwareProbe 主类
2. 优先级: 中
3. 理由: 整合所有检测器

4. 预计工作量: 2-3天

5. 实现 CapabilityPolicy

6. 优先级: 中
7. 理由: 为上层提供策略配置

8. 预计工作量: 2-3天

9. 实现 DeviceConfig

10. 优先级: 中
11. 理由: 支持手动配置覆盖
12. 预计工作量: 1-2天

优先级3 (低)

1. 创建 Mock 数据集
2. 优先级: 低
3. 理由: 单元测试需要

4. 预计工作量: 1天

5. 编写单元测试

6. 优先级: 低
7. 理由: 确保代码质量
8. 预计工作量: 3-4天

---

十、相关文档

• 原始TODO: ../01_hardware_probe.md
• 设计文档: ../../design_stage/01_phase1_hardware_probe.md
• CPU 实现: ../../HandBook/api/system/cpu/overview.md
• 内存实现: ../../HandBook/api/system/memory/memory_info.md

---

最后更新: 2026-03-05