coderbusy · Copilot · Nov 14, 2025 · Nov 14, 2025 · Nov 14, 2025 · Nov 14, 2025
diff --git a/docs/MachineInfo-EN.md b/docs/MachineInfo-EN.md
@@ -0,0 +1,181 @@
+# MachineInfo Class Documentation
+
+## Overview
+
+The `MachineInfo` class is used to retrieve and store basic machine hardware and system information. It provides cross-platform functionality for gathering machine information, supporting Windows, Linux, and macOS operating systems.
+
+## Key Features
+
+### System Information
+- **Operating System Info**: OS name and version
+- **Hardware Info**: Processor model, manufacturer, product name
+- **Identification Info**: Computer serial number, motherboard info, disk serial number
+
+## Usage Examples
+
+### Basic Usage
+
+```csharp
+using LuYao.Devices;
+
+// Get machine information instance
+var machineInfo = MachineInfo.Get();
+
+// Access basic information
+Console.WriteLine($"OS: {machineInfo.OSName}");
+Console.WriteLine($"Version: {machineInfo.OSVersion}");
+Console.WriteLine($"Processor: {machineInfo.Processor}");
+Console.WriteLine($"Vendor: {machineInfo.Vendor}");
+Console.WriteLine($"Product: {machineInfo.Product}");
+Console.WriteLine($"Serial: {machineInfo.Serial}");
+Console.WriteLine($"Board: {machineInfo.Board}");
+Console.WriteLine($"Disk ID: {machineInfo.DiskID}");
+```
+
+### Reload Information
+
+```csharp
+var machineInfo = MachineInfo.Get();
+
+// Reload machine information
+machineInfo.Reload();
+
+// Access updated information
+Console.WriteLine($"OS: {machineInfo.OSName}");
+```
+
+### Complete Example: Display System Information
+
+```csharp
+using System;
+using LuYao.Devices;
+
+class Program
+{
+    static void Main()
+    {
+        var machineInfo = MachineInfo.Get();
+
+        Console.WriteLine("=== System Information ===");
+        Console.WriteLine($"OS: {machineInfo.OSName}");
+        Console.WriteLine($"Version: {machineInfo.OSVersion}");
+        Console.WriteLine($"Processor: {machineInfo.Processor}");
+        Console.WriteLine($"Vendor: {machineInfo.Vendor}");
+        Console.WriteLine($"Product: {machineInfo.Product}");
+        Console.WriteLine($"Serial: {machineInfo.Serial}");
+        Console.WriteLine($"Board: {machineInfo.Board}");
+        Console.WriteLine($"Disk ID: {machineInfo.DiskID}");
+    }
+}
+```
+
+## Property Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `OSName` | `string?` | Operating system name (e.g., "Windows 11", "Ubuntu 22.04") |
+| `OSVersion` | `string?` | Operating system version number |
+| `Product` | `string?` | Product name (e.g., "ThinkPad X1 Carbon") |
+| `Vendor` | `string?` | Manufacturer (e.g., "Lenovo", "Dell", "Apple") |
+| `Processor` | `string?` | Processor model (e.g., "Intel Core i7-10750H") |
+| `Serial` | `string?` | Computer serial number, suitable for branded machines |
+| `Board` | `string?` | Motherboard serial number or family information |
+| `DiskID` | `string?` | Disk serial number |
+
+## Method Reference
+
+### Get()
+
+Static method to get and initialize a new `MachineInfo` instance.
+
+```csharp
+var machineInfo = MachineInfo.Get();
+```
+
+### Reload()
+
+Reload machine information.
+
+```csharp
+machineInfo.Reload();
+```
+
+## Platform Support
+
+### Windows
+- Supports .NET Framework 4.5+ and .NET Core 3.0+
+- Gets hardware info via registry and WMIC
+- Retrieves: OSName, OSVersion, Product, Vendor, Processor, Serial, Board, DiskID
+
+### Linux
+- Supports .NET Core 3.0+
+- Reads `/proc/cpuinfo` for processor information
+- Reads DMI information from `/sys/class/dmi/id/`
+- Reads disk information from `/sys/block/`
+- Retrieves: OSName, OSVersion, Product, Vendor, Processor, Serial, Board, DiskID
+
+### macOS
+- Supports .NET Core 3.0+
+- Uses `system_profiler` for hardware information
+- Retrieves: OSName, OSVersion, Product, Processor, Serial
+- Vendor defaults to "Apple"
+
+## Important Notes
+
+1. **Performance Impact**: Some operations (like WMIC queries on Windows) may be time-consuming. Consider caching the `MachineInfo` instance.
+
+2. **Permission Requirements**:
+   - Windows: Some registry keys may require administrator privileges
+   - Linux: Reading some system files may require root permissions
+   - macOS: Some system commands may require appropriate permissions
+
+3. **Cross-platform Compatibility**: Not all properties are available on all platforms. Check for `null` or empty strings before use. For example:
+   - `Serial`, `Board`, `DiskID` may be empty on some VMs or specific hardware
+   - `Board` and `DiskID` may not be available on macOS
+
+## Best Practices
+
+1. **Singleton Pattern**: Use singleton pattern to cache `MachineInfo` instance and avoid repeated initialization.
+
+```csharp
+public class SystemInfo
+{
+    private static readonly Lazy<MachineInfo> _instance = 
+        new Lazy<MachineInfo>(() => MachineInfo.Get());
+
+    public static MachineInfo Instance => _instance.Value;
+}
+```
+
+2. **Exception Handling**: Some operations may fail, handle exceptions appropriately.
+
+```csharp
+try
+{
+    var machineInfo = MachineInfo.Get();
+    Console.WriteLine($"OS: {machineInfo.OSName}");
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"Failed to get machine info: {ex.Message}");
+}
+```
+
+3. **Null Checks**: Some properties may be null, check before use.
+
+```csharp
+var machineInfo = MachineInfo.Get();
+
+if (!string.IsNullOrEmpty(machineInfo.Serial))
+{
+    Console.WriteLine($"Serial: {machineInfo.Serial}");
+}
+else
+{
+    Console.WriteLine("Serial number not available");
+}
+```
+
+## Reference
+
+This implementation is based on the MachineInfo implementation from the [NewLifeX](https://github.com/NewLifeX/X) project.
diff --git a/docs/MachineInfo.md b/docs/MachineInfo.md
@@ -0,0 +1,186 @@
+# MachineInfo 类文档
+
+## 概述
+
+`MachineInfo` 类用于获取和存储机器的基本硬件和系统信息。该类提供了跨平台的机器信息获取功能，支持 Windows、Linux 和 macOS 操作系统。
+
+## 主要功能
+
+### 系统信息
+- **操作系统信息**：操作系统名称和版本
+- **硬件信息**：处理器型号、制造商、产品名称
+- **标识信息**：计算机序列号、主板信息、磁盘序列号
+
+## 使用示例
+
+### 基本使用
+
+```csharp
+using LuYao.Devices;
+
+// 获取机器信息实例
+var machineInfo = MachineInfo.Get();
+
+// 访问基本信息
+Console.WriteLine($"操作系统: {machineInfo.OSName}");
+Console.WriteLine($"系统版本: {machineInfo.OSVersion}");
+Console.WriteLine($"处理器: {machineInfo.Processor}");
+Console.WriteLine($"制造商: {machineInfo.Vendor}");
+Console.WriteLine($"产品名称: {machineInfo.Product}");
+Console.WriteLine($"序列号: {machineInfo.Serial}");
+Console.WriteLine($"主板: {machineInfo.Board}");
+Console.WriteLine($"磁盘ID: {machineInfo.DiskID}");
+```
+
+### 重新加载信息
+
+```csharp
+var machineInfo = MachineInfo.Get();
+
+// 重新加载机器信息
+machineInfo.Reload();
+
+// 访问更新后的信息
+Console.WriteLine($"操作系统: {machineInfo.OSName}");
+```
+
+### 完整示例：显示系统信息
+
+```csharp
+using System;
+using LuYao.Devices;
+
+class Program
+{
+    static void Main()
+    {
+        var machineInfo = MachineInfo.Get();
+
+        Console.WriteLine("=== 系统信息 ===");
+        Console.WriteLine($"操作系统: {machineInfo.OSName}");
+        Console.WriteLine($"系统版本: {machineInfo.OSVersion}");
+        Console.WriteLine($"处理器: {machineInfo.Processor}");
+        Console.WriteLine($"制造商: {machineInfo.Vendor}");
+        Console.WriteLine($"产品: {machineInfo.Product}");
+        Console.WriteLine($"序列号: {machineInfo.Serial}");
+        Console.WriteLine($"主板: {machineInfo.Board}");
+        Console.WriteLine($"磁盘ID: {machineInfo.DiskID}");
+    }
+}
+```
+
+## 属性说明
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `OSName` | `string?` | 操作系统名称（如 "Windows 11", "Ubuntu 22.04"） |
+| `OSVersion` | `string?` | 操作系统版本号 |
+| `Product` | `string?` | 产品名称（如 "ThinkPad X1 Carbon"） |
+| `Vendor` | `string?` | 制造商（如 "Lenovo", "Dell", "Apple"） |
+| `Processor` | `string?` | 处理器型号（如 "Intel Core i7-10750H"） |
+| `Serial` | `string?` | 计算机序列号，适用于品牌机，跟笔记本标签显示一致 |
+| `Board` | `string?` | 主板序列号或家族信息 |
+| `DiskID` | `string?` | 磁盘序列号 |
+
+## 方法说明
+
+### Get()
+
+静态方法，获取并初始化一个新的 `MachineInfo` 实例。
+
+```csharp
+var machineInfo = MachineInfo.Get();
+```
+
+### Reload()
+
+重新加载机器信息。
+
+```csharp
+machineInfo.Reload();
+```
+
+## 平台支持
+
+### Windows
+- 支持 .NET Framework 4.5+ 和 .NET Core 3.0+
+- 通过注册表和 WMIC 获取硬件信息
+- 获取：OSName, OSVersion, Product, Vendor, Processor, Serial, Board, DiskID
+
+### Linux
+- 支持 .NET Core 3.0+
+- 读取 `/proc/cpuinfo` 获取处理器信息
+- 读取 `/sys/class/dmi/id/` 下的 DMI 信息
+- 读取 `/sys/block/` 获取磁盘信息
+- 获取：OSName, OSVersion, Product, Vendor, Processor, Serial, Board, DiskID
+
+### macOS
+- 支持 .NET Core 3.0+
+- 使用 `system_profiler` 获取硬件信息
+- 获取：OSName, OSVersion, Product, Processor, Serial
+- Vendor 默认为 "Apple"
+
+## 注意事项
+
+1. **性能影响**：某些操作（如 Windows 上的 WMIC 查询）可能耗时较长，建议缓存 `MachineInfo` 实例。
+
+2. **权限要求**：
+   - Windows：某些注册表项可能需要管理员权限
+   - Linux：读取某些系统文件可能需要 root 权限
+   - macOS：某些系统命令可能需要适当权限
+
+3. **跨平台兼容性**：并非所有属性在所有平台上都可用。使用前应检查属性是否为 `null` 或空字符串。例如：
+   - `Serial`、`Board`、`DiskID` 在某些虚拟机或特定硬件上可能为空
+   - macOS 上的 `Board` 和 `DiskID` 可能无法获取
+
+## 最佳实践
+
+1. **单例模式**：建议使用单例模式缓存 `MachineInfo` 实例，避免重复初始化。
+
+```csharp
+public class SystemInfo
+{
+    private static readonly Lazy<MachineInfo> _instance = 
+        new Lazy<MachineInfo>(() => MachineInfo.Get());
+
+    public static MachineInfo Instance => _instance.Value;
+}
+```
+
+2. **异常处理**：某些操作可能失败，应适当处理异常。
+
+```csharp
+try
+{
+    var machineInfo = MachineInfo.Get();
+    Console.WriteLine($"系统: {machineInfo.OSName}");
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"获取机器信息失败: {ex.Message}");
+}
+```
+
+3. **空值检查**：某些属性可能为空，使用前应检查。
+
+```csharp
+var machineInfo = MachineInfo.Get();
+
+if (!string.IsNullOrEmpty(machineInfo.Serial))
+{
+    Console.WriteLine($"序列号: {machineInfo.Serial}");
+}
+else
+{
+    Console.WriteLine("无法获取序列号");
+}
+```
+
+## 参考
+
+本实现参考了 [NewLifeX](https://github.com/NewLifeX/X) 项目的 MachineInfo 实现。
+
+## 相关文档
+
+- [SizeHelper 文档](SizeHelper.md) - 用于格式化字节大小
+- [UnitConverter 文档](UnitConverter.md) - 单位转换工具