MooTool F25 系统信息硬件模块:Electron vitest 与 Compose HardwareEngine 的测试对照与实现解析
MooTool F25 系统信息硬件模块:Electron vitest 与 Compose HardwareEngine 的测试对照与实现解析
本篇指南围绕 MooTool(开发者工具箱)中的 F25「系统信息」硬件模块,以 next-compose/docs/fixtures/electron-next-hardwareTools-vitest.md 这份测试对照登记表为骨架,梳理 Electron(Vitest)与 Compose(Kotlin)两端在序列号遮蔽、容量格式化、运行时长格式化与 OSHI 采集快照四个维度上的行为对齐关系,并结合两端源码与测试用例说明其底层实现。读完你可以掌握:两端的格式化与脱敏规则如何保持一致、OSHI 采集快照的完整字段结构、Electron systeminformation 与 Compose OSHI 两条采集链路的差异,以及如何用 HardwareEngineTest 验证这些行为。
一、登记文档背景:F25 硬件模块的 fixture 对照表
docs/fixtures/electron-next-hardwareTools-vitest.md 是 Compose 版 MooTool 与 Electron 版(next/ 目录)做功能对齐时的 F25 fixture 登记文件。它用一张四行对照表,把 Electron 侧 hardwareTools.test.ts 的测试场景逐一映射到 Compose 侧的 HardwareEngineTest:
| caseId | Electron vitest | Compose |
|---|---|---|
| mask-serial | 序列号默认遮蔽 | HardwareEngineTest mask / displayValue |
| format-bytes | 存储容量展示 | HardwareEngineTest.formatBytes_* |
| format-duration | 运行时长 | HardwareEngineTest.formatDuration_* |
| collect-sample | OSHI 采集快照结构 | HardwareEngineTest.collect_* |
该登记源自 DIFF-531「工具默认值即时同步 + Vault Git 命令盘关键词 + F-tool fixture 登记」(docs/diff/531-tools-defaults-live-git-keywords-slice.md),其中明确说明:docs/fixtures/electron-next-timeTools-vitest.md、electron-next-hardwareTools-vitest.md 用于登记 Compose TimeEngineTest / HardwareEngineTest 对照项,配套验证命令为 ./gradlew :composeApp:desktopTest --offline(JDK 21)。
也就是说,这份登记表不是孤立文档,而是 Compose 版 逐条对齐 Electron 硬件工具行为的工程证据链的一部分:Electron 的每一个 vitest 测试用例,在 Compose 侧都有同名语义的 Kotlin 测试与之对应。
二、Compose 侧实现:HardwareEngine 的四个核心能力
2.1 序列号遮蔽 mask / displayValue
Compose 侧脱敏逻辑位于 HardwareEngine.mask()(HardwareEngine.kt):
fun mask(value: String?): String {
val trimmed = value?.trim().orEmpty()
if (trimmed.isEmpty() || trimmed.equals("unknown", ignoreCase = true) || trimmed == "n/a") return "-"
return if (trimmed.length <= 4) trimmed else "${trimmed.take(2)}****${trimmed.takeLast(2)}"
}
规则要点:
- 空串、
unknown(忽略大小写)、n/a一律归一为-; - 长度 ≤ 4 时原样展示(太短没有遮蔽意义);
- 长度 > 4 时保留前 2 位与后 2 位,中间以
****填充,如ABCDEF→AB****EF。
与 mask 配套的是 HardwareEngine.displayValue():
fun displayValue(item: HardwareItem, revealSensitive: Boolean): String =
if (item.sensitive && !revealSensitive) mask(item.value) else item.value.ifBlank { "-" }
HardwareItem 携带 sensitive 标记(序列号字段构造为 sensitive = true),只有 UI 勾选「显示序列号」(revealSensitive = true)时才输出明文,否则一律走 mask。这一「默认遮蔽、显式揭示」的语义在 Electron 侧同样存在(见下文 3.1)。
2.2 存储容量格式化 formatBytes
fun formatBytes(bytes: Long): String {
if (bytes < 0) return "-"
val units = arrayOf("B", "KB", "MB", "GB", "TB", "PB")
var value = bytes.toDouble()
var index = 0
while (value >= 1024 && index < units.lastIndex) {
value /= 1024
index += 1
}
return String.format(Locale.US, "%.2f %s", value, units[index])
}
规则要点:
- 负数归一为
-; - 采用 1024 进制(KiB 语义但沿用 B/KB/MB/GB/TB/PB 标签);
- 固定保留两位小数,且使用
Locale.US强制.小数点,避免不同系统 locale 下出现,分隔符; - 上限到 PB,超出后保持最高单位。
2.3 运行时长格式化 formatDuration
fun formatDuration(seconds: Long): String {
if (seconds < 0) return "-"
val days = seconds / 86_400
val hours = (seconds % 86_400) / 3_600
val minutes = (seconds % 3_600) / 60
return "${days}d ${hours}h ${minutes}m"
}
将秒数折算为 Xd Yh Zm(天/时/分),负数归一为 -;不展示秒级,粒度到分钟。Electron 侧有完全一致的语义(见 3.3)。
此外引擎还提供 formatGHz(hertz),把 Hz 折算为两位小数的 GHz(2_000_000_000 → 2.00 GHz),用于 CPU 主频展示。
2.4 OSHI 采集快照 collect
HardwareEngine.collect() 使用 OSHI 6.8.2(JNA 路线,与 Java 产品一致)读取本机 HAL/OS 信息,返回带时间戳的 HardwareSnapshot:
data class HardwareSnapshot(
val collectedAt: Instant,
val sections: Map<HardwareTab, List<HardwareGroup>>
)
HardwareTab 枚举定义了五个分区:System、Cpu、Memory、Storage、Network(HardwareEngine.kt)。
采集的字段结构(以 collect 源码为准,见 HardwareEngine.kt):
System 分区包含两组:
operatingSystem组:Platform、Distribution、Kernel、Architecture、Host name、Serial(敏感)、Manufacturer、Model、Uptime(formatDuration(os.systemUptime))、Time zone;application组:Product(ProductIdentity.DISPLAY_NAME)、Version、Java version、JVM、Java home——这是 DIFF-014 强调的「本产品运行时」组,避免把 JVM/java.home误写成操作系统字段。
Cpu 分区:Manufacturer、Brand、Vendor、Family、Model、Physical cores、Logical cores、Performance cores、Efficiency cores(通过物理处理器 efficiency 字段区分 P/E 核,不可用时显示 -)、Base speed、Maximum speed、Current load。
Memory 分区:Total、Used、Available、Active(OSHI 无对应计数时显示 -,不填 0)、Usage、Swap total、Swap used。
Storage 分区:先按磁盘列 Device/Model/Serial(敏感)/Capacity,再按文件系统列 Filesystem/Type/Total/Used/Available/Usage;磁盘与文件系统均无可读信息时降级为 - 状态组。
Network 分区:每个网卡一组,含 Interface、Type、IPv4、IPv6、MAC、MTU、Speed(Mbps)、Status、Received/Sent(formatBytes(nic.bytesRecv)/formatBytes(nic.bytesSent))。
采集还包含两个工程细节:
- CPU 负载采样默认
loadSampleMs = 200,通过systemCpuLoadTicks前后两次采样差值计算,采样窗口被coerceIn(50, 2_000)限制; - 所有组均通过
group()过滤空值与"undefined",item()将空值归一为-,保证快照里不出现空洞。
三、Electron 侧实现:systeminformation 采集与同规则格式化
Electron 端(next/ 目录)的系统信息由主进程 SystemService.getSystemInfo() 提供,底层依赖 Node 库 systeminformation(systemService.ts),一次并发拉取 osInfo/system/cpu/currentLoad/mem/time/diskLayout/fsSize/networkInterfaces/networkStats。
3.1 序列号遮蔽
function mask(value: string): string {
if (!value || value.toLowerCase() === 'unknown') return '-'
return value.length <= 4 ? value : `${value.slice(0, 2)}****${value.slice(-2)}`
}
与 Compose HardwareEngine.mask 完全同规则:长度 ≤ 4 原样、否则前 2 + **** + 后 2、unknown/空值归一为 -。系统主序列号(system.serial)与磁盘序列号(disk.serialNum)在采集时都经过 mask 后才进入快照。
3.2 存储容量与运行时长
Electron 的 formatBytes 同样以 1024 进制、两位小数、单位数组 <a href="https://link.gitcode.com/i/bbc70003f40a45bc5e7adaabe434e7cc" target="_blank">'B','KB','MB','GB','TB','PB'] 输出,非有限值或负数归一为 -([systemService.ts);formatDuration 同样按 d/h/m 折算(systemService.ts),与 Compose 侧一一对应。此外 Electron 侧对 CPU 主频输出 ${cpu.speed} GHz,当前负载用 currentLoad.toFixed(1)%,即 DIFF-014 所述「瞬时值」而非 Compose 的采样均值。
3.3 前端展示:HardwareTool.tsx
渲染侧(HardwareTool.tsx)通过 window.mootool.getSystemInfo() 获取快照,以 system/cpu/memory/storage/network 五个 tab 展示,并提供「复制当前 Tab 纯文本」「手动刷新」操作。注意 Electron 侧采集到的字段已经是明文(Serial 在主进程被 mask),而 Compose 侧是在渲染层用 displayValue(item, revealSensitive) 按会话的「显示序列号」开关决定是否解密——这是两条链路在脱敏时机的差异。
四、测试对照:HardwareEngineTest 如何验证四个 caseId
Compose 侧对应 docs/fixtures/electron-next-hardwareTools-vitest.md 的测试文件是 HardwareEngineTest(HardwareEngineTest.kt),两个测试方法覆盖了登记表全部四个 caseId:
@Test
fun masksSerialsAndFormatsUnits() {
assertEquals("-", HardwareEngine.mask(""))
assertEquals("-", HardwareEngine.mask("unknown"))
assertEquals("AB12", HardwareEngine.mask("AB12"))
assertEquals("AB****EF", HardwareEngine.mask("ABCDEF"))
assertEquals("1.00 KB", HardwareEngine.formatBytes(1024))
assertEquals("0.00 B", HardwareEngine.formatBytes(0))
assertEquals("-", HardwareEngine.formatBytes(-1))
assertEquals("1d 2h 3m", HardwareEngine.formatDuration(93780))
assertEquals("2.00 GHz", HardwareEngine.formatGHz(2_000_000_000))
val item = HardwareItem("hardware.label.serial", "ABCDEF", sensitive = true)
assertEquals("AB****EF", HardwareEngine.displayValue(item, revealSensitive = false))
assertEquals("ABCDEF", HardwareEngine.displayValue(item, revealSensitive = true))
}
- mask-serial:空串/
unknown→-;短值原样;长值遮蔽;displayValue在revealSensitive = false时输出遮蔽值、true时输出明文。 - format-bytes:1024 →
1.00 KB;0 →0.00 B;负值 →-。 - format-duration:93780 秒(1 天 2 小时 3 分钟)→
1d 2h 3m;附带formatGHz覆盖。
@Test
fun collectsLiveOsCpuAndMemoryWithoutFillingZeros() {
val snapshot = HardwareEngine.collect(loadSampleMs = 80)
// System 分区:主机名非空且不为 "0";序列号字段 sensitive 且默认遮蔽
val host = os.items.first { it.labelKey == "hardware.label.hostName" }.value
assertTrue(host.isNotBlank() && host != "0")
val serial = os.items.first { it.labelKey == "hardware.label.serial" }
assertTrue(serial.sensitive)
assertEquals(HardwareEngine.mask(serial.value), HardwareEngine.displayValue(serial, false))
// application 组:产品名包含 "Compose"
// CPU:逻辑核心数 ≥ 1
// 内存:总量非 "0.00 B",且不存在 total = "0" 的占位项
// Storage / Network 分区非空
val text = HardwareEngine.plainText(snapshot, HardwareTab.System, revealSensitive = false) { it }
assertTrue(!text.contains(serial.value) || serial.value.length <= 4 || serial.value == "-")
}
- collect-sample:在真实本机执行
HardwareEngine.collect(),验证:- 主机名真实非空(不为
"0"占位); - 序列号字段
sensitive = true,且默认渲染结果与mask一致; - application 组携带
Compose产品标识; - CPU 逻辑核心 ≥ 1、内存总量非
0.00 B、存储/网络分区非空; plainText生成的纯文本报告不会泄漏超过 4 位的序列号明文。
- 主机名真实非空(不为
该测试的运行记录见 docs/evidence/2026-09-09-f25/results.md:./gradlew :composeApp:desktopTest 92/92 全绿(含 HardwareEngineTest 2 项),配套依赖 OSHI 6.8.2、JDK 21。
五、会话层对齐:Compose 的 HardwareSession 与离页取消
除引擎单测外,Compose 侧还有会话级测试 HardwareSessionRestoreTest(HardwareSessionRestoreTest.kt)与 HardwareScreen(HardwareScreen.kt)协同,体现 DIFF-014 强调的「无通用历史」语义:
- 会话只持久化当前 tab 与 revealSensitive(是否显示序列号),由
HardwareSessionMetadata.normalizeTab将非法 tab 值归一为system(HardwareSessionMetadata.kt); - 恢复会话时
snapshot置空、loading复位、error清空,保证重新进入工具必须重新采集; HardwareScreen通过OnToolLeaveUnlessDetached在切走页面时collectJob?.cancel()取消进行中的采集(采样协程运行在Dispatchers.Default),与 Electron 侧「切走页面取消进行中的采集」的行为对齐;- UI 提供「显示序列号」复选框、刷新按钮与复制当前 Tab 文本操作(
HardwareEngine.plainText按revealSensitive决定是否输出明文)。
六、两端差异速览(DIFF-014 决策要点)
DIFF-014(docs/diff/014-oshi-system-info.md)记录了 Compose 版替换 Electron 采集方案的决策:
| 维度 | Electron(原行为) | Compose(本产品) |
|---|---|---|
| 采集库 | Node systeminformation |
OSHI 6.8.2(JNA,与 Java 产品同路线) |
| 拉取方式 | 一次并发拉取多个指标 | SystemInfo 读取本机 HAL/OS |
| 序列号 | mask 遮蔽 |
mask + 渲染层 displayValue(需勾选才显示明文) |
| CPU 负载 | currentLoad 瞬时值 |
前后 ticks 采样约 200 ms 均值 |
| 内存 Active | 直接展示 | OSHI 无对应计数时显示 -,不填 0 |
| 系统分区 | 仅有操作系统字段 | 额外增加「本产品运行时」组(JVM/Java 版本等) |
| 历史 | 无通用历史 | 无通用历史(仅持久化 tab 与 revealSensitive) |
| 离页行为 | 取消进行中的采集 | OnToolLeaveUnlessDetached 取消采集协程 |
Electron 端参考实现为 HardwareTool.tsx 与 systemService.ts(getSystemInfo / mask / formatBytes / formatDuration)。
七、如何在仓库中验证与扩展
- 运行 Compose 侧单测:在
next-compose/目录执行./gradlew :composeApp:desktopTest --offline(JDK 21),观察HardwareEngineTest与HardwareSessionRestoreTest的执行结果;离线证据显示此前为 92/92 全绿。 - 对照 Electron 行为:在
next/端跑hardwareTools.test.ts对应的 vitest 用例,两端应就 mask/format-bytes/format-duration/collect-sample 四个维度保持一致断言。 - 扩展新字段:若需新增硬件字段,应同时改 HardwareEngine.kt 的
collect()分组、HardwareTool.tsx 的字段 key 映射,并在HardwareEngineTest中补充断言,保持两端语义同步。
总结
F25 系统信息模块通过 docs/fixtures/electron-next-hardwareTools-vitest.md 这份登记表,把 Electron 与 Compose 两端的测试行为锁定在四个维度:序列号遮蔽(mask/displayValue)、容量格式化(formatBytes)、运行时长(formatDuration)与采集快照结构(collect)。Compose 侧以 OSHI 6.8.2 为采集底座,在保持字段标签、脱敏规则与 Electron 对齐的前提下,通过「序列号默认遮蔽」「本产品运行时独立分组」「内存 Active 空缺显示 -」「离页取消采集」等设计,形成了与 Electron systeminformation 链路行为等价、但更严谨的系统信息工具。