@daimazun/hardware-info 1.0.0

package/README.md

@@ -0,0 +1,907 @@
+# hardware-info
+
+> 作者：高健 <gaojianstyle@163.com>
+
+跨平台硬件信息获取与监控库。当前已实现 Windows 平台，支持 CPU 温度/负载/频率/功耗、系统信息、内存详情、硬盘、网络、电池、显卡、USB、进程、服务、进程操作（杀进程/定位文件）、磁盘插拔监听、进程图标、后端资源占用、公网 IP 等全维度硬件数据。Linux / macOS 支持规划中。
+
+CPU 真实核心温度通过 OpenHardwareMonitor DLL 获取（仅 311KB，零安装，用完即卸载驱动不残留），其他信息通过 Windows WMI/CIM/性能计数器获取，无需管理员。进程枚举通过 koffi 直调 Win32 API（335进程 ~28ms），杀进程使用 fkill（支持 PID/端口/名称）。
+
+## 特性
+
+### CPU 与硬件监控
+- **真实核心温度** — 通过 WinRing0 驱动读 CPU MSR 寄存器（DTS），不是主板热区温度
+- **零安装** — 仅需 `OpenHardwareMonitorLib.dll`（311KB），.NET Framework 4.5（Win10/11 自带）
+- **不残留** — 每次调用后自动卸载 WinRing0 驱动、删除服务
+- **三种模式** — 单次调用 / 常驻进程 / 高频监控器，按需选择
+- **多层降级** — 非管理员时自动降级到性能计数器（ACPI 热区温度）
+
+### 系统信息（无需管理员）
+- **系统** — OS 版本/build、计算机制造商型号、BIOS、主板、CPU 详情、开机时长、电源计划
+- **内存** — 使用率、物理内存条详情（型号/频率/容量/厂商）、虚拟内存、最大支持容量
+- **硬盘** — 物理磁盘（型号/接口/固件/序列号/盘符关联）、分区（文件系统/使用率）、实时读写速度/活跃度
+- **网络** — 网卡列表、IP/MAC/DNS、实时上下行网速、WiFi SSID/信号/频道、活跃网卡过滤
+- **电池** — 电量、健康度、充电状态、设计/满充容量、循环次数、电源计划
+- **显卡/显示器** — 显卡型号/显存/驱动/分辨率/刷新率、虚拟显卡识别、多显示器信息
+- **USB** — USB 控制器、已连接 USB 设备列表
+- **进程** — koffi 直调 Win32 API（335进程 ~28ms），支持实时 CPU%、按名称聚合（含组内实例明细）、父PID/私有内存/安装时间、排序和 Top N
+- **进程操作** — 结束进程（fkill，支持 PID/端口号/进程名/混合数组，含子进程树）、在资源管理器中定位文件
+- **进程查找** — 按端口号查找占用 PID（netstat 解析）、按进程名查找 PID（koffi 匹配）
+- **磁盘插拔监听** — EventEmitter，WMI 事件监听（Win32_VolumeChangeEvent，插拔瞬间触发）+ 5s 低频轮询兜底
+- **进程图标** — 提取 exe 关联图标（base64 PNG，批量提取，按需）
+- **服务** — Windows 服务列表（状态/启动类型/描述/运行账户）
+- **后端资源占用** — Node.js 进程 + 所有子进程的内存/CPU/线程占用，同步 ~5-10ms，高频安全
+- **公网 IP** — DNS 查询为主（OpenDNS 45ms）→ Google DNS → HTTPS 三源兜底，60 秒缓存，零依赖
+- **一键汇总** — `getAllInfo()` 并行获取全部信息，单模块失败不影响其他
+
+## 环境要求
+
+- **操作系统**：Windows 10 / 11（当前）；Linux / macOS 规划中
+- **Node.js**：>= 14.0.0
+- **权限**：CPU 真实核心温度需管理员；其他信息无需管理员
+- **.NET Framework 4.5**：Win10/11 系统自带
+
+## 安装
+
+```bash
+npm install @daimazun/hardware-info
+```
+
+## 项目结构
+
+```
+hardware-info/
+├── index.js                      # 入口，导出全部 30+ API
+├── package.json
+├── README.md
+├── bin/
+│   └── OpenHardwareMonitorLib.dll   # 311KB
+├── lib/
+│   ├── ps.js                     # 通用 PowerShell 执行工具
+│   ├── ohm.js                    # CPU 温度（单次模式）
+│   ├── ohm-daemon.js             # CPU 温度（常驻进程）
+│   ├── monitor.js                # CPU 温度（高频监控器）
+│   ├── perfctr.js                # 性能计数器降级
+│   ├── allhardware.js            # OHM 全硬件传感器
+│   ├── system.js                 # 系统信息
+│   ├── memory.js                 # 内存详情
+│   ├── disk.js                   # 硬盘详情
+│   ├── network.js                # 网络信息
+│   ├── battery.js                # 电池信息
+│   ├── gpu.js                    # 显卡/显示器
+│   ├── usb.js                    # USB 设备
+│   ├── processes.js              # 进程列表（双后端 koffi/wmi）
+│   ├── win32-procs.js            # koffi 直调 Win32 API 进程枚举
+│   ├── services.js               # 服务列表
+│   ├── process-ops.js            # 进程操作（killProcess/showItemInFolder/findPidsByPort/findPidsByName）
+│   ├── process-icon.js           # 进程图标提取
+│   ├── disk-watcher.js           # 磁盘插拔监听（WMI 事件 + 轮询兜底）
+│   ├── public-ip.js              # 公网 IP（DNS 查询 + 缓存）
+│   ├── sysinfo-daemon.js         # 统一常驻进程（所有模块复用一个 PowerShell）
+│   ├── hardware-service.js       # 统一常驻服务（整合所有模块）
+│   └── backend-usage.js          # 后端资源占用（Node.js + 子进程）
+├── scripts/                      # PowerShell 脚本
+│   ├── get-lhm-temp.ps1
+│   ├── ohm-daemon.ps1
+│   ├── get-all-hardware.ps1
+│   └── sysinfo-daemon.ps1
+└── test/                         # 测试文件
+    ├── test.js                   # CPU 温度 + 全硬件基础测试
+    ├── test-daemon.js            # CPU 温度常驻模式性能测试
+    ├── test-monitor.js           # CPU 温度监控器功能测试
+    ├── test-all.js               # 全模块综合测试（11 个模块）
+    ├── test-new-features.js      # 新增功能综合测试
+    ├── test-service.js           # 统一常驻服务测试
+    ├── test-kill-name.js         # 进程名/端口杀进程测试
+    ├── test-sysinfo-daemon.js    # 统一常驻模式性能测试
+    ├── server.js                 # Express 测试服务（端口 3210）
+    └── public/
+        └── index.html            # Vue 3 调试仪表盘
+```
+
+## 快速开始
+
+```js
+const { getCpuTemp, getAllInfo } = require('./index');
+
+// CPU 温度（需管理员拿真实核心温度，非管理员自动降级）
+const cpu = await getCpuTemp();
+console.log(`${cpu.cpuName}: ${cpu.temperature.maxCore}°C`);
+
+// 一键获取全部系统信息
+const all = await getAllInfo();
+console.log(`OS: ${all.system.os.caption}`);
+console.log(`内存: ${all.memory.usedPercent}%`);
+console.log(`电池: ${all.battery.overallChargePercent}%`);
+```
+
+## CPU 温度三种模式
+
+### 1. 单次模式 — `getCpuTemp()`
+
+每次 spawn 新进程，~800ms。偶尔读一次用这个。
+
+```js
+const { getCpuTemp } = require('./index');
+const data = await getCpuTemp();
+```
+
+返回：`temperature`（每核心/封装/最高温/热区）、`load`、`clock`、`power`、`isCoreTemp`、`cpuName`、`source`。
+
+### 2. 常驻模式 — `createCpuTempDaemon()`
+
+进程保持运行，每次 ~60ms。自己控制读取节奏用这个。
+
+```js
+const { createCpuTempDaemon } = require('./index');
+const daemon = await createCpuTempDaemon();
+const data = await daemon.getTemp();  // ~60ms
+await daemon.close();
+```
+
+### 3. 监控器模式 — `createCpuTempMonitor()`
+
+EventEmitter 事件推送，支持暂停/恢复/动态调间隔。持续监控用这个。
+
+```js
+const { createCpuTempMonitor } = require('./index');
+const monitor = await createCpuTempMonitor({ interval: 500 });
+monitor.on('data', data => console.log(`${data.temperature.maxCore}°C`));
+// monitor.setInterval(200); monitor.pause(); monitor.resume();
+await monitor.stop();
+```
+
+## 系统信息 API（无需管理员）
+
+### `getSystemInfo()`
+
+操作系统、计算机、BIOS、主板、CPU、开机时间、电源计划。
+
+```js
+{
+  os: { caption, version, buildNumber, architecture, installDate, lastBootUpTime, uptimeDays, systemDrive },
+  computer: { manufacturer, model, name, domain, totalPhysicalMemoryGB, numberOfCores, numberOfLogicalProcessors, systemType },
+  bios: { manufacturer, version, releaseDate, serialNumber },
+  motherboard: { manufacturer, product, version, serialNumber },
+  cpu: { name, manufacturer, numberOfCores, numberOfLogicalProcessors, maxClockSpeedMHz, l2CacheKB, l3CacheKB, socketDesignation, virtualizationEnabled },
+  powerPlan: "平衡",
+  timezone: "China Standard Time",
+  currentTime: "..."
+}
+```
+
+### `getMemoryInfo()`
+
+内存使用情况 + 物理内存条详情。
+
+```js
+{
+  totalPhysicalGB, usedPhysicalGB, freePhysicalGB, usedPercent,
+  totalVirtualGB, freeVirtualGB,
+  sticks: [
+    { deviceLocator, bankLabel, capacityGB, speedMHz, configuredSpeedMHz, manufacturer, partNumber, serialNumber, dataWidth }
+  ],
+  stickCount,
+  array: { maxCapacityGB, memoryDevices, use }
+}
+```
+
+> 注意：部分笔记本（内存焊死）WMI 可能将每个内存颗粒识别为一条，导致 stickCount 偏多。
+
+### `getDiskInfo()`
+
+物理磁盘 + 逻辑分区 + 实时读写速度。
+
+```js
+{
+  physicalDisks: [
+    { index, model, manufacturer, interfaceType, mediaType, serialNumber, firmwareRevision, sizeGB, partitions, drives, readBytesPerSec, writeBytesPerSec, percentActive }
+  ],
+  logicalDrives: [
+    { drive, volumeName, fileSystem, sizeGB, usedGB, freeGB, usedPercent, volumeSerialNumber }
+  ],
+  diskCount, totalSizeGB
+}
+```
+
+### `getNetworkInfo()`
+
+网卡列表 + IP 配置 + 实时网速 + WiFi。
+
+```js
+{
+  adapters: [
+    { name, connectionName, macAddress, adapterType, speedMbps, status, ipAddresses, ipSubnets, defaultIpGateway, dnsServers, dhcpEnabled, bytesReceivedPerSec, bytesSentPerSec, isPhysical }
+  ],
+  activeAdapters: [/* 同上，仅已连接的物理网卡 */],
+  adapterCount, activeAdapterCount,
+  wifi: { ssId, signalPercent, channel },
+  totalDownloadBytesPerSec, totalUploadBytesPerSec
+}
+```
+
+### `getBatteryInfo()`
+
+电池状态 + 健康度 + 电源计划。台式机返回 `hasBattery: false`。
+
+```js
+{
+  hasBattery: true,
+  batteries: [
+    { name, deviceId, status, batteryStatusValue, batteryStatus, chargePercent, estimatedRunTimeMinutes, voltagemV, designCapacitymWh, fullChargeCapacitymWh, healthPercent, cycleCount, manufacturer, chemistry }
+  ],
+  powerPlan: "平衡",
+  isCharging: false,
+  overallChargePercent: 99
+}
+```
+
+> 部分笔记本 WMI 不暴露设计容量/循环次数，对应字段为 null。
+
+### `getGpuInfo()`
+
+显卡 + 显示器信息。
+
+```js
+{
+  gpus: [
+    { name, isVirtual, displayMode, adapterCompatibility, adapterRAMMB, driverVersion, driverDate, videoProcessor, currentHorizontalResolution, currentVerticalResolution, currentRefreshRate, currentBitsPerPixel }
+  ],
+  monitors: [
+    { name, monitorManufacturer, monitorType, screenHeight, screenWidth }
+  ],
+  gpuCount, monitorCount, primaryResolution
+}
+```
+
+### `getUsbInfo()`
+
+USB 控制器 + 已连接设备。
+
+```js
+{
+  controllers: [{ name, manufacturer, status, deviceId }],
+  controllerCount,
+  devices: [{ name, description, manufacturer, status, service, pnpDeviceId, classGuid }],
+  deviceCount
+}
+```
+
+### `getProcesses(options?)`
+
+进程列表，支持排序、Top N、实时 CPU%、按名称聚合。
+
+```js
+const procs = await getProcesses({
+  top: 10,
+  sortBy: 'cpu',        // 'memory' / 'cpu' / 'name'
+  includeCpu: true,      // 实时 CPU%，默认 false，常驻采样器自动启停
+  groupByName: true,     // 按名称聚合，默认 false
+  includeInstallTime: true, // 安装时间，默认 false
+  backend: 'koffi'       // 'koffi'（默认，~28ms）/ 'wmi'（~115ms）
+});
+```
+
+**koffi 后端返回**：
+
+```js
+{
+  total, returned, backend,
+  processes: [
+    {
+      pid, name, parentPid, threads,
+      memoryMB, memoryPrivateMB,
+      cpuPercent,       // 实时 CPU%（需 includeCpu=true）
+      exePath,
+      installTime,      // 需 includeInstallTime=true
+      // groupByName=true 时额外返回：
+      pids: [],         // 组内所有 PID
+      instances: [],    // 组内实例明细
+      percent           // 占总内存百分比
+    }
+  ]
+}
+```
+
+**高频优化**：`includeCpu=true` 时启动 1s 常驻采样器，自动维护 CPU% 基线，空闲 15s 自动停止。后续 `getProcesses` 读缓存毫秒级返回。
+
+### `getServicesInfo(options?)`
+
+Windows 服务列表。
+
+```js
+const services = await getServicesInfo({ runningOnly: false });
+```
+
+```js
+{
+  total, running, stopped,
+  services: [
+    { name, displayName, state, status, startMode, startName, pathName, description, processId, acceptStop, acceptPause, serviceType }
+  ]
+}
+```
+
+### `getAllHardwareInfo()`
+
+OpenHardwareMonitor 全硬件传感器（CPU/主板/内存/硬盘/GPU 的温度、电压、频率、负载、风扇等）。**需管理员**。
+
+## 一键汇总
+
+### `getAllInfo(options?)`
+
+并行获取全部信息，单个模块失败不影响其他。
+
+```js
+const all = await getAllInfo({
+  includeProcesses: true,    // 是否包含进程列表，默认 false
+  includeServices: true,     // 是否包含服务列表，默认 false
+  includeOhmHardware: false, // 是否包含 OHM 全硬件传感器（需管理员），默认 false
+  processTop: 20             // 进程前 N 个，默认 20
+});
+```
+
+返回字段：`system`、`cpu`、`memory`、`disk`、`network`、`battery`、`gpu`、`usb`，可选 `processes`、`services`、`ohmHardware`，以及 `timestamp` 和 `errors`（失败模块的错误信息）。
+
+```js
+console.log(all.system.os.caption);        // Windows 10 专业版
+console.log(all.cpu.temperature.maxCore);  // 72
+console.log(all.memory.usedPercent);       // 69.09
+console.log(all.battery.overallChargePercent); // 99
+console.log(all.errors);                    // { battery: "..." } 或 null
+```
+
+## 完整 API 列表
+
+| API | 说明 | 需管理员 |
+|---|---|---|
+| `getCpuTemp()` | CPU 温度/负载/频率/功耗（多层降级） | 真实温度需要 |
+| `getAllHardwareInfo()` | OHM 全硬件传感器 | 是 |
+| `createCpuTempDaemon()` | CPU 温度常驻进程 | 是 |
+| `createCpuTempMonitor()` | CPU 温度高频监控器 | 是 |
+| `getSystemInfo()` | 系统/OS/BIOS/主板/CPU | 否 |
+| `getMemoryInfo()` | 内存详情/内存条 | 否 |
+| `getDiskInfo()` | 硬盘/分区/读写速度 | 否 |
+| `getNetworkInfo()` | 网卡/IP/网速/WiFi | 否 |
+| `getBatteryInfo()` | 电池/健康度/电源计划 | 否 |
+| `getGpuInfo()` | 显卡/显示器 | 否 |
+| `getUsbInfo()` | USB 控制器/设备 | 否 |
+| `getProcesses()` | 进程列表（koffi 直调 Win32 API，~28ms，支持 CPU%/按名称聚合/安装时间） | 否 |
+| `getServicesInfo()` | 服务列表 | 否 |
+| `getPublicIp()` | 公网 IP（DNS 查询为主，HTTPS 兜底，60 秒缓存） | 否 |
+| `getBackendUsage()` | 后端资源占用（Node.js + 子进程，同步 ~5-10ms） | 否 |
+| `getAllInfo()` | 一键汇总全部 | 部分需要 |
+| `createSysInfoDaemon()` | 统一常驻进程（所有模块复用一个 PowerShell 进程） | 否 |
+| `createHardwareService()` | **统一常驻服务**（整合所有模块，一个入口调用） | 否 |
+| `killProcess()` | 结束进程（fkill，支持 PID/端口/名称/混合数组，含子进程树） | 否 |
+| `findPidsByPort(port, protocol?)` | 按端口号查找占用 PID（netstat 解析） | 否 |
+| `findPidsByName(name)` | 按进程名查找 PID（koffi 匹配，不区分大小写） | 否 |
+| `showItemInFolder()` | 在资源管理器中定位到文件 | 否 |
+| `createDiskWatcher()` | 磁盘插拔监听（WMI 事件 + 5s 轮询兜底，EventEmitter） | 否 |
+| `listDriveLetters()` | 列出当前所有盘符 | 否 |
+| `getProcessIcon()` / `getProcessIcons()` | 提取 exe 关联图标（base64 PNG，批量提取，按需） | 否 |
+
+## 统一常驻服务（推荐）
+
+一个入口整合所有常驻模块，无需分别创建和管理 SysInfoDaemon / CpuTempMonitor / 进程采样器 / 磁盘监听器。
+
+```js
+const { createHardwareService } = require('hardware-info');
+
+// 创建即启动（CPU 温度异步初始化，不阻塞）
+const service = await createHardwareService({
+  cpuTempInterval: 1000,      // CPU 温度采样间隔 ms，0=不自动采样
+  diskWatchInterval: 2000,    // 磁盘插拔监听间隔 ms
+  systemCacheTtl: 30000,      // system 缓存 TTL ms
+  networkCacheTtl: 30000,     // 网卡配置缓存 TTL ms
+  enableCpuTemp: true,         // 是否启用 CPU 温度，默认 true
+  enableDiskWatcher: true      // 是否启用磁盘监听，默认 true
+});
+
+// 系统信息（代理到 SysInfoDaemon，高频低延迟）
+const mem = await service.getMemory();
+const net = await service.getNetwork();
+const sys = await service.getSystem();
+
+// 进程（自动带 CPU%，采样器自动启停，无需手动管理）
+const topCpu = await service.getProcesses({ top: 10, sortBy: 'cpu' });
+
+// CPU 温度（自动采样，同步返回最新值，无需 await）
+const temp = service.getCpuTemp();
+
+// 公网 IP（带 60s 缓存）
+const ip = await service.getPublicIp();
+
+// 后端资源占用（同步）
+const usage = service.getBackendUsage();
+
+// 进程操作
+await service.killProcess(1234);              // 按 PID
+await service.killProcess({ port: 3000 });    // 按端口
+await service.killProcess({ name: 'chrome' }); // 按名称
+const pids = await service.findPidsByPort(3000);
+const pids2 = service.findPidsByName('chrome');
+
+// 事件
+service.on('cpu-temp', (data) => console.log(data.temperature.maxCore + '°C'));
+service.on('disk-change', ({ added, removed }) => console.log('磁盘变化', added, removed));
+
+// 暂停/恢复/关闭
+service.pause();    // 暂停所有采样
+service.resume();   // 恢复
+await service.close();  // 关闭所有子模块，释放资源
+```
+
+### 统一服务 API 一览
+
+| 类别 | 方法/事件 | 说明 |
+|---|---|---|
+| **系统信息** | `getSystem()` `getMemory()` `getDisk()` `getNetwork()` `getBattery()` `getGpu()` `getUsb()` `getServices()` `getAll()` | 代理到 SysInfoDaemon |
+| **进程** | `getProcesses({top, sortBy, groupByName})` | 默认 `includeCpu=true`，自动管理采样器 |
+| **CPU 温度** | `getCpuTemp()` | 同步返回最新采样值（自动采样模式） |
+| | `fetchCpuTemp()` | 手动拉取一次（`cpuTempInterval=0` 时用） |
+| **公网 IP** | `getPublicIp()` | 带 60s 缓存 |
+| **磁盘** | `getDisks()` | 当前所有盘符 |
+| **后端资源** | `getBackendUsage()` | Node.js + 子进程内存/CPU/线程 |
+| **进程操作** | `killProcess(input)` | PID/端口/名称/混合数组 |
+| | `findPidsByPort(port, protocol?)` | 按端口查 PID |
+| | `findPidsByName(name)` | 按名称查 PID |
+| | `showItemInFolder(path)` | 资源管理器定位文件 |
+| **事件** | `on('cpu-temp', cb)` `on('disk-change', cb)` `on('error', cb)` `on('close', cb)` `on('pause', cb)` `on('resume', cb)` | |
+| **控制** | `pause()` `resume()` `close()` `getStatus()` | |
+
+## 常驻进程模式（SysInfoDaemon）
+
+所有模块复用一个 PowerShell 常驻进程，通过 stdin/stdout 通信，避免每次 spawn 新进程的 ~1500ms 启动开销。内存占用 ~50MB。
+
+```js
+const { createSysInfoDaemon } = require('hardware-info');
+
+const daemon = await createSysInfoDaemon();
+
+const mem = await daemon.getMemory();       // ~85ms
+const net = await daemon.getNetwork();     // ~270ms（含实时网速）
+const procs = await daemon.getProcesses({ top: 10 }); // ~115ms
+const sys = await daemon.getSystem();      // 缓存命中 ~1ms
+
+await daemon.close();
+```
+
+### 可配置缓存 TTL
+
+```js
+const daemon = await createSysInfoDaemon({
+  systemCacheTtl: 10000,   // system 缓存 10 秒（默认 30000ms）
+  networkCacheTtl: 30000,  // network 网卡配置缓存 30 秒（默认 30000ms）
+  maxRestarts: 5,           // 进程意外退出最大重启次数（默认 3）
+  verbose: false            // 是否输出 stderr 调试信息
+});
+```
+
+> 设为 `0` 可禁用对应缓存（每次都实时查询）。网速、内存、进程等动态数据不受缓存影响，始终实时。
+
+### 各模块查询延迟（常驻模式，i5-11300H 实测）
+
+| 模块 | 延迟 | 说明 |
+|---|---|---|
+| `getSystem()` | 首次 ~1200ms / 缓存命中 **1ms** | 30 秒 TTL 缓存 |
+| `getMemory()` | ~85ms | 实时 |
+| `getDisk()` | ~356ms | 实时 |
+| `getNetwork()` | ~270ms | 网卡配置 30 秒缓存，网速实时 |
+| `getBattery()` | ~25ms | 实时 |
+| `getGpu()` | ~43ms | 实时 |
+| `getUsb()` | ~177ms | 实时 |
+| `getProcesses()` | ~115ms | 实时 |
+| `getServices()` | ~332ms | 实时 |
+
+### 缓存策略（重要）
+
+常驻进程为降低高频调用延迟，对**变化不频繁**的数据做了缓存，其余数据每次实时查询：
+
+#### 有缓存的数据
+
+| 模块 | 缓存字段 | TTL | 说明 |
+|---|---|---|---|
+| `getSystem()` | `os`、`computer`、`bios`、`motherboard`、`cpu`、`powerPlan`、`timezone` | **30 秒** | 电源计划可能切换，30 秒内会刷新；OS/CPU/BIOS 等极少变化 |
+| `getNetwork()` | 网卡 `name`、`macAddress`、`ipAddresses`、`speedMbps`、`status`、`dnsServers` | **30 秒** | IP/网卡配置变化不频繁；**网速每次实时查询** |
+
+#### 每次实时查询（无缓存）
+
+- 内存使用率、已用/可用内存
+- 硬盘使用率、实时读写速度
+- 电池电量、充电状态、健康度
+- 显卡当前分辨率/刷新率
+- USB 设备列表
+- 进程列表（CPU/内存占用）
+- 服务列表
+- 网络上下行网速、包速率
+- CPU 温度（独立 OHM 常驻进程，每次读 MSR 寄存器）
+- `getSystem()` 返回中的 `uptimeSeconds`、`uptimeDays`、`currentTime`（每次更新）
+
+#### `os` 字段说明
+
+`getSystem()` 返回的 `os` 对象包含：
+
+| 字段 | 说明 | 示例 |
+|---|---|---|
+| `caption` | 操作系统名称 | `Microsoft Windows 10 专业版` |
+| `version` | 版本号 | `10.0.19045` |
+| `buildNumber` | 构建号 | `19045` |
+| `architecture` | 系统架构 | `64 位` |
+| `installDate` | 安装日期（ISO 格式） | `2021-07-22T...` |
+| `lastBootUpTime` | 上次启动时间（ISO 格式） | `2026-09-05T...` |
+| `systemDrive` | 系统盘 | `C:` |
+
+## API 返回字段详解
+
+### CPU 温度 `getCpuTemp()`
+
+| 字段 | 说明 | 示例值 |
+|---|---|---|
+| `source` | 数据来源 | `openhardwaremonitor` / `performance_counter` |
+| `isCoreTemp` | 是否真实核心温度 | `true` / `false` |
+| `cpuName` | CPU 型号 | `11th Gen Intel Core i5-11300H` |
+| `temperature.cores[]` | 每核心温度 | `[{name:"CPU Core #1", value:57}]` |
+| `temperature.package` | 封装温度 | `65` |
+| `temperature.maxCore` | 最高核心温度 | `65` |
+| `temperature.zones[]` | ACPI 热区（降级时） | `[{zone:"\\_TZ.TZ00", celsius:27.85}]` |
+| `load[]` | 每核心负载 + CPU Total | `[{name:"CPU Total", value:18.75}]` % |
+| `clock[]` | 每核心频率 + Bus Speed | `[{name:"CPU Core #1", value:4013.75}]` MHz |
+| `power[]` | 功耗（Package/Cores/Graphics/DRAM） | `[{name:"CPU Package", value:8.98}]` W |
+| `note` | 说明文字 | |
+| `errors[]` | 各层降级错误 | |
+
+### 系统信息 `getSystemInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `os.caption` / `version` / `buildNumber` | 系统名称 / 版本号 / 构建号 |
+| `os.architecture` / `installDate` / `lastBootUpTime` / `systemDrive` | 架构 / 安装日期 / 上次启动 / 系统盘 |
+| `computer.manufacturer` / `model` / `name` / `domain` | 厂商 / 型号 / 计算机名 / 域 |
+| `computer.totalPhysicalMemoryGB` / `numberOfLogicalProcessors` / `systemType` | 总内存 / 逻辑处理器数 / 系统类型 |
+| `bios.manufacturer` / `version` / `releaseDate` / `serialNumber` | BIOS 厂商 / 版本 / 发布日期 / 序列号 |
+| `motherboard.manufacturer` / `product` / `version` / `serialNumber` | 主板厂商 / 型号 / 版本 / 序列号 |
+| `cpu.name` / `manufacturer` | CPU 名称 / 厂商 |
+| `cpu.numberOfCores` / `numberOfLogicalProcessors` | 核心数 / 线程数 |
+| `cpu.maxClockSpeedMHz` / `l2CacheKB` / `l3CacheKB` | 最大频率 / L2缓存 / L3缓存 |
+| `cpu.socketDesignation` / `virtualizationEnabled` | 插槽 / 虚拟化是否开启 |
+| `powerPlan` / `timezone` | 电源计划 / 时区 |
+| `uptimeSeconds` / `uptimeDays` / `currentTime` | 开机时长（秒/天）/ 当前时间 |
+
+### 内存 `getMemoryInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `totalPhysicalGB` / `usedPhysicalGB` / `freePhysicalGB` / `usedPercent` | 总内存 / 已用 / 可用 / 使用率 |
+| `totalVirtualGB` / `freeVirtualGB` | 虚拟内存总量 / 可用 |
+| `sticks[].deviceLocator` / `bankLabel` | 插槽位置 / 通道标签 |
+| `sticks[].capacityGB` / `speedMHz` / `configuredSpeedMHz` | 容量 / 标称频率 / 实际频率 |
+| `sticks[].manufacturer` / `partNumber` / `serialNumber` / `dataWidth` | 厂商 / 型号 / 序列号 / 位宽 |
+| `stickCount` | 内存条数 |
+| `array.maxCapacityGB` / `array.memoryDevices` | 最大支持容量 / 最大插槽数 |
+
+### 硬盘 `getDiskInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `physicalDisks[].index` / `model` / `interfaceType` / `mediaType` | 索引 / 型号 / 接口类型 / 介质类型 |
+| `physicalDisks[].serialNumber` / `firmwareRevision` / `sizeGB` | 序列号 / 固件版本 / 容量 |
+| `physicalDisks[].drives` | 关联盘符数组，如 `['C:', 'D:']` |
+| `physicalDisks[].readBytesPerSec` / `writeBytesPerSec` / `percentActive` | 实时读速 / 写速 / 活跃时间% |
+| `logicalDrives[].drive` / `volumeName` / `fileSystem` | 盘符 / 卷标 / 文件系统 |
+| `logicalDrives[].sizeGB` / `usedGB` / `freeGB` / `usedPercent` | 总量 / 已用 / 可用 / 使用率 |
+| `diskCount` / `totalSizeGB` | 物理磁盘数 / 总容量 |
+
+### 网络 `getNetworkInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `adapters[]` / `activeAdapters[]` | 所有网卡 / 活跃网卡（已连接的物理网卡） |
+| `adapters[].name` / `connectionName` / `macAddress` | 名称 / 连接名 / MAC |
+| `adapters[].speedMbps` / `status` / `isPhysical` | 速率Mbps / 连接状态(2=已连接) / 是否物理 |
+| `adapters[].ipAddresses[]` / `defaultIpGateway[]` / `dnsServers[]` | IP / 网关 / DNS |
+| `adapters[].bytesReceivedPerSec` / `bytesSentPerSec` | **实时下载 / 上传速度** B/s |
+| `adapters[].packetsReceivedPerSec` / `packetsSentPerSec` | 收包 / 发包速率 |
+| `adapterCount` / `activeAdapterCount` | 总数 / 活跃数 |
+| `wifi.ssId` / `wifi.signalPercent` | WiFi名称 / 信号强度% |
+| `totalDownloadBytesPerSec` / `totalUploadBytesPerSec` | 总下载 / 总上传速度 |
+
+### 电池 `getBatteryInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `hasBattery` | 是否有电池 |
+| `batteries[].name` / `deviceId` / `status` | 名称 / 设备ID / 状态 |
+| `batteries[].batteryStatusValue` / `batteryStatus` | 状态值 / 状态文字 |
+| `batteries[].chargePercent` / `estimatedRunTimeMinutes` | 电量% / 预计续航分钟 |
+| `batteries[].voltagemV` | 电压 mV |
+| `batteries[].designCapacitymWh` / `fullChargeCapacitymWh` | 设计容量 / 满充容量 mWh |
+| `batteries[].healthPercent` / `cycleCount` | 健康度% / 循环次数 |
+| `batteries[].manufacturer` / `chemistry` | 厂商 / 化学类型 |
+| `isCharging` / `overallChargePercent` | 是否充电中 / 总电量% |
+
+### 显卡/显示器 `getGpuInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `gpus[].name` / `isVirtual` / `displayMode` | 名称 / 是否虚拟 / 显示模式(已格式化) |
+| `gpus[].adapterCompatibility` / `adapterRAMMB` | 兼容厂商 / 显存MB |
+| `gpus[].driverVersion` / `driverDate` / `videoProcessor` | 驱动版本 / 驱动日期 / 视频处理器 |
+| `gpus[].currentHorizontalResolution` / `currentVerticalResolution` | 当前水平 / 垂直分辨率 |
+| `gpus[].currentRefreshRate` / `currentBitsPerPixel` | 当前刷新率 / 色深 |
+| `monitors[].name` / `monitorManufacturer` / `monitorType` | 名称 / 厂商 / 类型 |
+| `monitors[].screenWidth` / `screenHeight` | 宽 / 高 |
+| `gpuCount` / `monitorCount` / `primaryResolution` | 显卡数 / 显示器数 / 主分辨率 |
+
+### USB `getUsbInfo()`
+
+| 字段 | 说明 |
+|---|---|
+| `controllers[].name` / `manufacturer` / `status` | 控制器名称 / 厂商 / 状态 |
+| `controllerCount` | 控制器数 |
+| `devices[].name` / `description` / `manufacturer` | 设备名称 / 描述 / 厂商 |
+| `devices[].status` / `service` | 状态 / 服务 |
+| `deviceCount` | 设备数 |
+
+### 进程 `getProcesses({top, sortBy, backend, includeCpu, groupByName, includeInstallTime})`
+
+**双后端**：
+- `koffi`（默认）：直调 Win32 API（Toolhelp32+psapi+GetProcessTimes），335进程 ~28ms，支持实时 CPU%
+- `wmi`：PowerShell Get-Process，~115ms，命令行信息更全
+
+**koffi 后端字段**：
+
+| 字段 | 说明 |
+|---|---|
+| `total` / `returned` / `backend` | 总进程数 / 返回数量 / 后端类型 |
+| `processes[].pid` / `name` | PID / 进程名（已去 .exe） |
+| `processes[].parentPid` | 父进程 PID |
+| `processes[].threads` | 线程数 |
+| `processes[].memoryMB` / `memoryPrivateMB` | 工作集内存 / 私有内存 MB |
+| `processes[].cpuPercent` | 实时 CPU%（需 includeCpu=true，第一次为0，后续正常） |
+| `processes[].exePath` | exe 完整路径 |
+| `processes[].installTime` | 安装时间（需 includeInstallTime=true，YYYY-MM-DD） |
+| `processes[].pids[]` / `instances[]` | 聚合后：所有PID / 组内实例明细（需 groupByName=true） |
+| `processes[].percent` | 聚合后：占总内存百分比 |
+
+**高频优化**：includeCpu=true 时启动 1s 常驻采样器，自动维护 CPU% 基线，空闲 15s 自动停止。getProcesses 读缓存毫秒级返回。
+
+### 进程操作
+
+#### `killProcess(input)`
+
+结束进程（使用 fkill，支持 PID/端口号/进程名/混合数组，含子进程树）。自动拒绝结束当前进程自身和父进程。
+
+```js
+const { killProcess } = require('hardware-info');
+
+// 按 PID
+const result = await killProcess(1234);
+// 批量 PID
+await killProcess([1234, 5678]);
+
+// 按端口号
+await killProcess({ port: 3000 });
+await killProcess({ port: 3000, protocol: 'tcp' }); // 'tcp'/'udp'/'all'(默认)
+
+// 按进程名
+await killProcess({ name: 'chrome' });
+await killProcess({ name: ['chrome', 'firefox'] });
+
+// 混合数组
+await killProcess([1234, { port: 3000 }, { name: 'chrome' }]);
+```
+
+返回 `{ ok, killed, failed, message? }`。
+
+#### `findPidsByPort(port, protocol?)`
+
+查找占用指定端口的进程 PID（netstat -ano 解析，零依赖）。
+
+```js
+const pids = await findPidsByPort(3000);           // 所有协议
+const pids = await findPidsByPort(3000, 'tcp');     // 仅 TCP
+// 返回: [1234, 5678]
+```
+
+#### `findPidsByName(name)`
+
+按进程名查找 PID（koffi 进程枚举匹配，不区分大小写，自动忽略 .exe）。
+
+```js
+const pids = findPidsByName('chrome');
+// 返回: [1234, 5678]
+```
+
+#### `showItemInFolder(filePath)`
+
+在资源管理器中打开并定位到文件（`explorer /select,<path>`）。
+
+```js
+const { ok, message } = showItemInFolder('C:\\path\\to\\app.exe');
+```
+
+### 磁盘插拔监听 `createDiskWatcher({interval})`
+
+WMI 事件监听（Win32_VolumeChangeEvent，插拔瞬间触发）+ 5s 低频轮询兜底。EventEmitter，不占用大量 CPU。
+
+```js
+const { createDiskWatcher } = require('hardware-info');
+
+const watcher = createDiskWatcher({ interval: 5000 });
+watcher.on('change', ({ added, removed, disks }) => {
+  console.log('新增盘符:', added);   // ['E']
+  console.log('移除盘符:', removed); // ['E']
+  console.log('当前所有:', disks);   // ['C','D']
+});
+watcher.start();
+// ...
+watcher.stop();
+```
+
+方法：`start()` / `stop()` / `getDisks()`。
+
+### 进程图标 `getProcessIcon(exePath)` / `getProcessIcons(paths)`
+
+提取 exe 关联图标，输出 base64 PNG。用 PowerShell System.Drawing，按需调用（图标是静态属性，建议调用方缓存），不进高频路径。
+
+```js
+// 单个
+const iconBase64 = await getProcessIcon('C:\\path\\to\\app.exe');
+
+// 批量（路径走 stdin，无命令行长度限制）
+const icons = await getProcessIcons(['C:\\a.exe', 'C:\\b.exe']);
+// icons = { 'C:\\a.exe': 'base64...', 'C:\\b.exe': 'base64...' }
+```
+
+### 后端资源占用 `getBackendUsage()`
+
+获取当前 Node.js 进程 + 所有子进程的内存/CPU/线程占用。同步 ~5-10ms，高频安全。
+
+```js
+const usage = getBackendUsage();
+// {
+//   node: { pid, memory: { workingSetMB, heapUsedMB, heapTotalMB }, cpuPercent, threads },
+//   children: [ { pid, name, memoryMB, cpuPercent, threads } ],
+//   total: { processCount, memoryMB, cpuPercent, threads }
+// }
+```
+
+### 公网 IP `getPublicIp()`
+
+DNS 查询为主（OpenDNS myip.opendns.com，~45ms）→ Google DNS → HTTPS 三源兜底，60 秒缓存，零依赖。
+
+```js
+const ip = await getPublicIp();
+// "112.2.231.35"
+```
+
+### 服务 `getServicesInfo({runningOnly})`
+
+| 字段 | 说明 |
+|---|---|
+| `total` / `running` / `stopped` | 总数 / 运行中 / 已停止 |
+| `services[].name` / `displayName` | 服务名 / 显示名 |
+| `services[].state` / `status` / `startMode` | 状态 / 状态2 / 启动类型 |
+| `services[].startName` / `pathName` / `description` | 运行账户 / 路径 / 描述 |
+| `services[].processId` / `acceptStop` / `serviceType` | 关联PID / 是否可停止 / 服务类型 |
+
+### 其他 API
+
+| API | 返回值 | 说明 |
+|---|---|---|
+| `getAllInfo()` | 上述全部模块汇总对象 | 并行获取，单模块失败不影响其他 |
+| `getAllHardwareInfo()` | 完整硬件传感器树 | OHM 全硬件（主板/CPU/内存/硬盘/风扇等），需管理员 |
+| `createCpuTempDaemon()` | `CpuTempDaemon` | CPU 温度独立常驻进程（~60ms/次），需管理员 |
+| `createCpuTempMonitor()` | `CpuTempMonitor` | CPU 温度高频监控器（EventEmitter） |
+| `createSysInfoDaemon()` | `SysInfoDaemon` | 统一常驻进程（所有模块复用，缓存可配） |
+| `listDriveLetters()` | `string[]` | 列出当前所有盘符，如 `['C:', 'D:']` |
+
+## 原理
+
+### CPU 温度
+
+Windows 没有用户态 API 读 CPU 核心温度。OpenHardwareMonitor 自带 WinRing0 内核驱动，运行时临时加载，通过 `DeviceIoControl` 执行 `RDMSR` 读 MSR 寄存器：
+
+- `IA32_THERM_STATUS` (0x19C) — 每核心 DTS 温度
+- `IA32_PACKAGE_THERM_STATUS` (0x1B1) — 封装温度
+- `IA32_TEMPERATURE_TARGET` (0x1A2) — TjMax
+- RAPL 寄存器 — 功耗
+
+温度 = TjMax - DTS差值，精度 ±1-2°C。用完即卸载驱动不残留。
+
+### 其他系统信息
+
+通过 Windows WMI/CIM（`Get-CimInstance`）和性能计数器获取，无需管理员、无需驱动：
+
+- 系统/硬件信息 → `Win32_OperatingSystem`、`Win32_ComputerSystem`、`Win32_BIOS`、`Win32_BaseBoard`、`Win32_Processor`
+- 内存 → `Win32_PhysicalMemory`、`Win32_PhysicalMemoryArray`
+- 硬盘 → `Win32_DiskDrive`、`Win32_LogicalDisk`、`Win32_PerfFormattedData_PerfDisk_PhysicalDisk`
+- 网络 → `Win32_NetworkAdapter`、`Win32_NetworkAdapterConfiguration`、`Win32_PerfFormattedData_Tcpip_NetworkInterface`、`netsh wlan`
+- 电池 → `Win32_Battery`、`Win32_PortableBattery`、`powercfg`
+- 显卡 → `Win32_VideoController`、`Win32_DesktopMonitor`
+- USB → `Win32_USBController`、`Win32_PnPEntity`
+- 进程 → koffi 直调 Toolhelp32/psapi/GetProcessTimes（默认）或 `Get-Process`/`Win32_Process`（wmi 后端）
+- 服务 → `Win32_Service`
+- 磁盘插拔 → WMI 事件 `Win32_VolumeChangeEvent` + 轮询兜底
+- 公网 IP → DNS 查询（OpenDNS/Google DNS）+ HTTPS 兜底
+
+## 注意事项
+
+- **CPU 真实温度需管理员**，非管理员时 `getCpuTemp()` 自动降级到 ACPI 热区温度（`isCoreTemp: false`）
+- **驱动不残留**，每次 OHM 调用后自动卸载 WinRing0 驱动
+- **OHM 0.9.6 硬件局限**：较新的 GPU/NVMe/笔记本 EC 可能支持有限，需要更新硬件可换 LibreHardwareMonitor
+- **内存焊死的笔记本**：WMI 可能将每个内存颗粒识别为一条，stickCount 偏多
+- **电池健康度**：部分笔记本 WMI 不暴露设计容量，healthPercent 为 null
+- **进程 CPU%**：`includeCpu=true` 时第一次调用返回 0（建立基线），1 秒后正常
+- **杀进程**：`killProcess` 自动拒绝结束当前进程自身和父进程，防止误杀
+- **公网 IP**：DNS 查询可能被防火墙拦截，自动降级到 HTTPS 兜底
+
+## 测试
+
+```bash
+# CPU 温度基础测试（需管理员）
+node test/test.js
+
+# 常驻模式性能测试（需管理员）
+node test/test-daemon.js
+
+# 监控器功能测试（需管理员）
+node test/test-monitor.js
+
+# 全模块综合测试（无需管理员，CPU 温度自动降级）
+node test/test-all.js
+
+# 新增功能综合测试（进程增强/进程操作/磁盘监听/进程图标）
+node test/test-new-features.js
+
+# 统一常驻服务测试
+node test/test-service.js
+
+# 进程名/端口杀进程测试
+node test/test-kill-name.js
+
+# Express 调试服务（端口 3210，Vue 3 仪表盘）
+node test/server.js
+```
+
+或使用 npm scripts：
+
+```bash
+npm test
+npm run test:daemon
+npm run test:monitor
+npm run test:all
+npm run test:new
+npm run test:monitor
+npm run server
+```
+
+## 支持作者
+
+这个项目从"只想读个 CPU 温度"开始，一路踩坑扩展到现在 30+ API 的全维度硬件信息库，全是业余时间一点点堆出来的。
+
+如果你觉得它帮你省了调研时间、避开了那些坑（比如 Windows 真实核心温度要读 MSR 寄存器、koffi 直调 Win32 API 比 WMI 快 4 倍这些），欢迎请作者喝杯咖啡 ☕
+
+你的支持会用来：
+- 持续修复 bug、跟进新硬件兼容
+- 推进 Linux / macOS 跨平台支持
+- 补充更多传感器和系统信息
+- 买咖啡续命（真的需要，开源不容易）
+
+| 微信 | 支付宝 |
+|:---:|:---:|
+| ![微信收款码1](https://cos.gaojianstyle.com/pay/gj/gj.pay.wx.jpg) | ![支付宝收款码1](https://cos.gaojianstyle.com/pay/gj/gj.pay.ali.jpg) |
+| ![微信收款码2](https://cos.gaojianstyle.com/pay/zdl/zdl.pay.wx.jpg) | ![支付宝收款码2](https://cos.gaojianstyle.com/pay/zdl/zdl.pay.ali.jpg) |
+
+一块两块都是鼓励，感谢 🙏
+
+## 致谢
+
+- [OpenHardwareMonitor](https://openhardwaremonitor.org/) — 开源硬件监控库，CPU 温度功能使用其 DLL
+- [koffi](https://koffi.dev/) — 快速 Node.js C FFI 库，进程枚举直调 Win32 API
+- [fkill](https://github.com/sindresorhus/fkill) — 跨平台杀进程库，支持 PID/端口/名称
+- WinRing0 — 内核驱动，允许用户态程序执行特权指令
+
+## License
+
+MIT