BreezyWuSTBrainPowerCenter 1.0.40

BreezyWuSTBrainPowerCenter

秉经典美学，道永恒品质。Breezy Wu 科技智囊中心，让阳光照进生命的裂痕里，点靓您的生活。

面向 .NET 应用的通用基础工具库，提供数据转换、字节报文处理、校验、统计与随机分布、公式计算、文本加密，以及 Windows/WPF 辅助功能。应用层可以按场景直接调用，无需统一启动入口或依赖注入容器。

本文依据当前仓库源码说明。项目文件中的包名为 BreezyWuSTBrainPowerCenter，版本为 1.0.39；本地源码中的新增接口不代表已包含在同版本的已发布 NuGet 包中，接入时应以实际引用的程序集为准。

目录

• 解决什么问题
• 框架与平台支持
• 安装与快速开始
• 库分层与组织方式
• 主要模块原理与用法
• 返回值、异常与并发约定
• 源码构建与示例程序
• 常见问题

解决什么问题

库负责通用计算和系统能力封装；业务校验、通信收发、协议分帧规则、日志、重试、密钥管理以及 UI 调度由应用层组织。例如，ByteQueue 可以缓存分批收到的字节，但不会自动识别完整的 Modbus 帧。

框架与平台支持

项目声明了以下目标框架（项目文件中 .NET Framework 的写法为 net4.8）：

多目标框架不等于所有 API 都跨平台。 当前项目仍有 NetFwTypeLib COM 引用，并使用 WMI（System.Management）、注册表以及 user32.dll / Kernel32.dll。计算、字符串和字节处理模块与 Windows 系统管理功能需要分别评估，不能仅凭引用了 .NET Standard 或 .NET 8/10 就认定整个库可以在 Linux/macOS 使用。

在 .NET Standard 2.0、.NET 8.0、.NET 10.0 目标下，项目明确排除了：

• VoicePlayHelper、VisualHelper、BitmapHelper、PrintHelper。
• ResourceHelper、ResourceDictionaryHelper。
• Helper/NETFramework 下的 ComputerInfoHelper、TaskbarHelper。
• SizeUtils、ColorUtils、BrushUtils。
• Utils/NETFramework/CommUtils.cs、IDocRender。

这里排除的是指定路径的文件，例如常规 Helper/ComputerInfoHelper.cs 仍在编译范围内。

主要依赖以项目文件为准：

安装与快速开始

引用 NuGet 包

若所用 NuGet 源提供此包，可在应用项目目录执行：

dotnet add package BreezyWuSTBrainPowerCenter --version 1.0.39

此命令表示按项目声明的版本引用，并非对该版本发布状态的确认。若需要本文描述的最新源码功能，可改用项目引用。

引用源码项目

在 Visual Studio 中把库项目加入应用解决方案，然后添加项目引用。仓库中的库项目路径为：

BreezyWuSTBrainPowerCenter/BreezyWuSTBrainPowerCenter/BreezyWuSTBrainPowerCenter.csproj

本文所用公开类型均位于同一命名空间。目录用于组织源码，不需要写 using BreezyWuSTBrainPowerCenter.Crypto; 等子命名空间：

using BreezyWuSTBrainPowerCenter;

下面是可放入控制台项目的完整入门示例：

using System;
using BreezyWuSTBrainPowerCenter;

internal static class Program
{
    private static void Main()
    {
        byte[] body = "01 03 00 00 00 02".ToByteArray();
        if (body == null)
            throw new InvalidOperationException("报文格式不正确。");

        byte[] frame = body.Combine(CRCCheck.GetCRC16(body));
        Console.WriteLine(frame.ToHexString()); // 01 03 00 00 00 02 C4 0B
        Console.WriteLine(CRCCheck.CompareCRC(frame)); // True
    }
}

后续代码片段放在方法体内使用，并添加片段列出的 using。

库分层与组织方式

当前仓库由一个库项目和一个 WPF Demo 项目组成。以下是按职责归纳的逻辑分层，并非多个独立程序集，也不是强制的单向依赖架构。

应用层（业务、UI、通信收发、配置管理）
  ├─ 场景组件：Formula / Crypto / Generator / Algorithm
  ├─ 基础工具：Extensions / Utils / Helper
  ├─ 数据与契约：Entity / Enum / Const / Interface
  └─ 平台能力：Win32 / WMI / 注册表 / COM / WPF

几个实际的组合关系：ModeA001FileCrypto 调用 AES256CBCCrypto 和 FileUtils；AES 封装使用字节数组拼接与比较扩展；分布随机生成器使用 DistributionBase / TRandom；FormulaParser 通过应用提供的委托取得变量值。

主要模块原理与用法

1. 字节转换、报文组装与校验

StringExtension.ToByteArray() 面向类似 "01 03 00 00" 的两位 HEX 文本，每个字节按三个字符的步长读取。应固定使用单个空格分隔，不要传入连续 HEX、0x 前缀或不规则空白；失败可能返回 null。ToHexString() 默认使用空格输出大写 HEX，适合通信日志。

ByteUtils 是可连续 Add 的字节构建器；ByteConvertUtils 按数组偏移读取数值。两者通过字节重排和 BitConverter 实现转换，以下字节序对照适用于常见的 Windows 小端环境：

库另提供 ByteOrder16Bit（AB/BA）和 ByteOrder32Bit（ABCD/CDAB/BADC/DCBA）枚举，但上述接口通过方法名区分排列，并不接收这些枚举参数。

using BreezyWuSTBrainPowerCenter;

byte[] payload = new ByteUtils()
    .Add((byte)0x01)
    .Add(520.5f)
    .ToArray();

float value = new ByteConvertUtils().ConvertFloat(payload, 1); // 520.5

调用转换方法前，应用应检查偏移与剩余长度；这些底层方法并不统一捕获越界异常。

CRCCheck.GetCRC16 使用初值 0xFFFF、多项式 0xA001 的逐位计算，结果按低字节、高字节返回。CompareCRC 接收的是末尾已经附加两字节 CRC 的完整报文。CRCGB2017 是另一个校验实现；CheckSum 提供累加、补码和异或校验，应按对接协议选择，不能互换。

2. 接收缓存 ByteQueue

ByteQueue 使用数组、头尾索引组成环形缓存，空间不足时按原容量的两倍扩容。默认初始容量为 1024 字节，支持批量入队、查看、搜索和消费。

using BreezyWuSTBrainPowerCenter;

var queue = new ByteQueue();
queue.Enqueue(new byte[] { 0x01, 0x03 });
queue.Enqueue(new byte[] { 0x00, 0x02 });

if (queue.GetSize() >= 4)
{
    byte[] preview = queue.Peek(0, 4); // 不移除
    byte[] frame = new byte[4];
    int read = queue.Dequeue(frame); // 移除，返回实际读取长度
}

• 示例中的 4 是业务已知帧长，实际协议需自行判断帧头、长度和校验。
• IndexOf 找不到时返回 -1；单字节 Peek 在索引超出已有数据时返回 byte.MaxValue，这个值也可能是合法数据，因此应先检查长度。
• 显式设置容量时使用正数。零容量无法通过倍增获得可用空间。
• 队列没有内置同步；多线程访问时应由调用方用同一把锁保护完整操作序列。

3. 统计、概率分布与模拟数据

StatisticHelper 对 List<double> 或满足 struct, IConvertible 的列表计算均值、方差、标准差和相对标准偏差。总体方差除以 n，样本方差除以 n - 1；默认 isPopulation = true。

using System.Collections.Generic;
using BreezyWuSTBrainPowerCenter;

var samples = new List<double> { 1, 2, 3, 4, 5 };
double? mean = StatisticHelper.Mean(samples);                       // 3
double? populationVariance = StatisticHelper.Variance(samples);    // 2
double? sampleVariance = StatisticHelper.Variance(samples, false); // 2.5
double? rsd = StatisticHelper.RelativeStandardDeviation(samples);

空数据返回 null；样本方差至少需要两个值。相对标准偏差返回 标准差 / 平均值 的比值，没有乘以 100，且均值为零时返回 null。

概率模块把“计算分布函数”和“生成随机样本”分开组织：

常见名称含义：PDF 为概率密度，PMF 为离散概率质量，CDF 为累计概率，SF 为右尾概率，PPF 为分位数，Probability 为区间概率，MGF / CF 为矩母函数 / 特征函数。不同分布提供的方法和返回类型并不完全一致，不能假定存在统一接口。

using BreezyWuSTBrainPowerCenter;

double? density = NormalDistribution.PDF(miu: 0, sigma: 1, x: 0);
double? cumulative = NormalDistribution.CDF(miu: 0, sigma: 1, x: 0);
double? threshold = NormalDistribution.PPF(
    miu: 0, sigma: 1, cumulativeProbability: 0.975);

double? uniform = UniformDistributionRandomGenerator.Generate(0, 100);
// 正态采样的当前实现限制见下文；此处使用均匀分布演示采样入口。

分布参数通常放在前面，待计算的 x 或累计概率放在后面；sigma 是标准差，不是方差。许多方法用可空返回值表示无效参数或不适用结果，应用需要区分 null、零以及合法的无穷边界值。数值计算包含近似和迭代实现，不应把示例当作精度保证。

当前随机数实现的使用边界：

• TRandom.GetRandom() 在 .NET 6 及以上编译分支返回 Random.Shared，较旧目标使用 ThreadLocal<Random>。但 DistributionBase 只获取一次随机实例并静态保存，因此旧目标下的分布采样不能据此认定为线程安全。
• 正态采样使用 Box–Muller 变换，一次计算两个值并缓存一个。当前缓存的是已应用 miu / sigma 的结果；交替使用不同参数时，下一次调用可能取到上一组参数的值。缓存也没有同步保护。其他调用正态采样的生成器同样需要考虑这一影响。
• 带 min / max 的正态采样通过重复生成直到落入区间实现，没有尝试次数上限；极窄区间或远尾区间可能耗时很长。
• 这些采样入口使用 System.Random，用途是模拟与统计采样；AES 的 IV 则单独使用 RandomNumberGenerator。

4. 带变量的公式计算

FormulaParser 采用递归下降解析：由加减层进入乘除层，再进入一元正负号和基本表达式层，从而实现四则运算优先级。它直接解析表达式，不编译或执行 C# 代码。

支持 + - * /、圆括号、小数、科学计数法和变量。普通变量以字母或下划线开头，后续可以包含数字；含特殊字符或纯数字的变量用方括号包裹，例如 [001-CH4/01]。当前未提供幂运算、函数调用或条件表达式。

using System;
using System.Collections.Generic;
using BreezyWuSTBrainPowerCenter;

var values = new Dictionary<string, double>
{
    { "CH4", 10 },
    { "C2H6", 6 },
    { "001-CH4/01", 2 }
};

var parser = new FormulaParser(
    "(CH4 + C2H6) / 2 + [001-CH4/01]",
    name => values.TryGetValue(name, out double value)
        ? (double?)value : null);

FormulaParseResult result = parser.Parse();
if (result.Success && result.FormulaResult.HasValue)
    Console.WriteLine(result.FormulaResult.Value); // 10
else
    Console.WriteLine("公式无效，或变量值缺失。");

结果包含 Success、可空的 FormulaResult 和去重后的 VariableIdentifierList。缺失变量、除零、括号不配对或非法字符会导致解析失败；变量列表只表示本次实际解析到的引用，不保证失败时已收集整条公式的所有变量。

即使公式没有变量，也需要传入非空解析委托，例如 _ => null。变量委托抛出的异常会向外传播。解析器持有位置和结果状态，同一实例不应并发调用；重复 Parse() 会重置并复用同一个结果对象，需留存历史结果时应自行复制。

5. 文本写入与加密

FileUtils.WriteAllText 先创建目标目录，再把内容写入目标文件同目录的随机临时文件，成功后移动或替换目标文件；失败返回 false，并尝试清理临时文件。此流程减少直接覆盖造成的半写入风险，但没有提供事务、并发写入协调或断电持久化保证。

AES256CBCCrypto 的数据处理流程为：

明文字节 → AES-256-CBC + PKCS#7 → 密文字节
认证数据 = IV（16 字节）+ 密文字节
输出数据包 = IV + 密文字节 + HMAC-SHA256（32 字节）
字符串接口输出 = Base64（数据包）

每次加密生成随机 IV，解密先验证 HMAC，再执行 AES 解密。byte[] 重载直接处理二进制数据包；string 重载使用 UTF-8 与 Base64。AES 密钥必须是 32 字节，HMAC 密钥至少 32 字节。

using System;
using BreezyWuSTBrainPowerCenter;

// 由应用部署环境提供主密钥，保存密文后解密必须使用相同密钥。
string masterKey = Environment.GetEnvironmentVariable("APP_CRYPTO_MASTER_KEY");
if (string.IsNullOrWhiteSpace(masterKey))
    throw new InvalidOperationException("未配置加密主密钥。");

var keys = AES256CBCCrypto.GetKey(masterKey);
string cipher = AES256CBCCrypto.Encrypt(
    "配置内容", keys.aes256EncryptKey, keys.hmacSHA256Key);
if (cipher == null)
    throw new InvalidOperationException("加密失败。");

string plain = AES256CBCCrypto.Decrypt(
    cipher, keys.aes256EncryptKey, keys.hmacSHA256Key);
if (plain == null)
    throw new InvalidOperationException("解密或完整性验证失败。");

GetKey 将主密钥的 UTF-8 字节做一次 SHA-512，前后各 32 字节分别作为 AES 与 HMAC 密钥；它没有盐或迭代参数，不是口令加固流程。密钥生成、保存、备份和轮换由应用负责。

ModeA001FileCrypto 在字符串密文前加上调用方指定的格式头，并提供文本文件读写：

using System;
using System.IO;
using BreezyWuSTBrainPowerCenter;

string masterKey = Environment.GetEnvironmentVariable("APP_CRYPTO_MASTER_KEY");
if (string.IsNullOrWhiteSpace(masterKey))
    throw new InvalidOperationException("未配置加密主密钥。");

var crypto = new ModeA001FileCrypto("APP:A001:", masterKey);
string file = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "MyApp", "settings.a001");

bool saved = crypto.WriteAllText(file, "{\"enabled\":true}", encrypt: true);
if (!saved)
    throw new IOException("配置保存失败。");

string json = crypto.ReadAllText(file);
if (json == null)
    throw new IOException("配置读取或解密失败。");

其行为需要与业务预期对应：

格式头不包含在 HMAC 认证范围内。若业务要求“只接收加密配置”，需要在应用层拒绝缺少预期格式头的内容，不能把兼容明文的读取接口当成强制加密校验。文件封装会整文件读入内存，面向文本；二进制内容使用基础 AES 的 byte[] 接口。

6. 时间 ID 与原子计数

Time001IDGenerator 通过 ConcurrentDictionary 为每个分类保存时间片和序号，再用 TryAdd / TryUpdate 重试更新，避免同一进程内并发更新丢失。

using BreezyWuSTBrainPowerCenter;

string id = Time001IDGenerator.Generate(
    category: "Order",
    sequenceLength: 4,
    format: "yyMMddHHmmssfff",
    prefix: "ORD-");

var counter = new AtomicOperationCounter();
int first = counter.Increment(); // 1
counter.Exchange(100);
int next = counter.Increment();  // 101

ID 格式为 前缀 + 格式化本地时间 + 序号 + 后缀。同一分类、同一格式化时间片内序号递增，时间片变化后从 1 开始；分类名仅用于管理状态，不会自动写入 ID。

• 不同分类可能生成相同的文本 ID，需要区分时使用不同前缀。
• 状态只存在于当前进程内，不是分布式或持久化 ID。重启、时钟回拨、重复的时间格式均可能影响唯一性。
• 同一分类应保持时间格式和序号规则一致。
• sequenceLength 是最小补零宽度，超出位数不会截断，也不会自动等待下一个时间片。
• AtomicOperationCounter 的增减与设置使用 Interlocked，但“读取后再判断再设置”等多步业务逻辑仍需自行同步。

7. 扩展方法与桌面辅助

常用扩展入口包括字符串切分和列表转换、集合重复项统计、枚举描述、反射属性访问、日期转换，以及数值有效性判断。下面演示数值与重复项处理：

using System.Collections.Generic;
using BreezyWuSTBrainPowerCenter;

double? measurement = double.NaN;
bool usable = measurement.Available(); // False；同时排除 null 和无穷值

var names = new List<string> { "A", "B", "A" };
Dictionary<string, int> duplicates = names.GetDuplicateElementAndCount();

ItemsChangeObservableCollection<T> 在 ObservableCollection<T> 的集合变化通知之外，订阅成员的 INotifyPropertyChanged 并转发 ItemChanged。当前源码在 Add/Remove/Replace 时维护订阅，并在 ClearItems() 中解绑已有成员。使用 IEnumerable<T> 构造函数时，内部会将参数转为 IList，应先把延迟枚举物化为列表。它不会把事件自动调度到 UI 线程。

WPF 的资源切换、视觉树查找、打印和语音等入口位于 Helper，仅在对应桌面目标可用。系统信息、防火墙、IP 设置、自启动等功能涉及具体 Windows 能力和权限，应用应按实际功能调用并处理失败，而不是在所有平台统一初始化。

返回值、异常与并发约定

库由多个独立工具组成，没有全局一致的错误模型。应用层应根据具体接口处理：

基础 AES 的字符串解密捕获异常并返回 null；字节数组重载虽会检查长度与 HMAC，但底层密码操作仍可能抛出异常，两个重载的异常行为不能混为一谈。

线程安全应逐类判断。AtomicOperationCounter 和时间 ID 的状态更新使用并发原语；ByteQueue、公式解析器、集合、字节构建器以及带缓存的随机生成器不能因为属于工具库就视为可安全共享。WPF 对象仍需遵守 UI 线程约束。

源码构建与示例程序

README.md
BreezyWuSTBrainPowerCenter/
├─ BreezyWuSTBrainPowerCenter.sln
├─ BreezyWuSTBrainPowerCenter/          # 多目标库项目
└─ BreezyWuSTBrainPowerCenterDemo/      # .NET Framework 4.8 WPF 演示项目
   ├─ ViewModel/HomeViewModel.cs
   ├─ ViewModel/Window/ListOfStringExtensionViewModel.cs
   └─ Test/Crypto/                     # 加密演示调用

1. 在 Windows 上使用支持所选目标 SDK 的 Visual Studio / MSBuild，安装 .NET Framework 4.8 targeting pack 和所需 .NET SDK；完整构建所有目标需要包括 .NET 10 SDK。
2. 打开 BreezyWuSTBrainPowerCenter/BreezyWuSTBrainPowerCenter.sln，还原 NuGet 依赖。库使用 PackageReference，Demo 使用 packages.config。
3. 构建库和 Demo，设 BreezyWuSTBrainPowerCenterDemo 为启动项目，查看 HomeViewModel 中的调用和对应窗口。

项目包含 COM 引用，源码构建应考虑 Windows 上完整 MSBuild 的 COM 解析能力；不能把单纯运行 dotnet build 当作所有环境都可用的构建保证。项目文件还包含本机绝对路径的 .editorconfig 条目，若构建报告路径问题，应检查开发环境与项目配置。

Demo 依赖 MVVM Light 和 CommonServiceLocator，这些是演示应用依赖，不是应用层调用通用库所必需的依赖。Test/Crypto 中的类由 Demo 调用展示结果，不是独立的自动化单元测试项目；涉及文件的示例应先检查其路径。

库启用了 XML 文档生成及构建时打包，根目录的 README.md 会作为 NuGet 包中的 docs/readme.md 收录。本文示例按源码接口核对，不表示已在所有目标框架执行验证。

常见问题

引用包后找不到本文某个类型？

先检查实际包版本与本地源码是否一致，再检查所选目标是否排除了该文件。WPF 辅助类不会出现在当前 .NET 8/10 目标的编译结果中。

HEX 文本转换为什么返回 null？

按 "01 03 FF" 这样的格式输入：每个字节两位 HEX，中间一个空格。不要把普通文本、连续 HEX 或带 0x 的日志直接传给 ToByteArray()。

公式失败时能得到详细错误位置吗？

当前结果对象只提供成功标志、数值和已发现的变量列表，没有错误位置或错误分类字段；界面提示和输入预检需要应用层补充。

读取加密文件成功，是否说明它一定经过认证？

不一定。ModeA001FileCrypto 兼容没有格式头的普通文本；只有匹配格式头并通过基础解密的内容才执行对应密文认证。需要严格模式时由应用限制输入格式。

这能代替分布式 ID、通信协议栈或完整数值计算平台吗？

不能。这里提供的是可以组合的基础工具。应用仍需负责分布式唯一性、协议收发与分帧，以及目标场景的数值精度和边界验证。