NBFC 贡献指南深度解读：Pull Request、Issue 与配置提交实战

NBFC（NoteBook FanControl）是一个跨平台笔记本风扇控制服务，其核心价值在于强大的配置系统——正是社区的配置贡献让 NBFC 能够适配众多笔记本型号。本文基于仓库根目录的 CONTRIBUTING.md 展开，结合配置系统、CLI 与校验测试的源码实现，系统讲解如何高质量地提交 Pull Request（尤其是配置文件）、如何规范地报告 Issue 与请求新配置，帮助你的贡献更快被接受。

贡献的总体原则

CONTRIBUTING.md 开篇即强调：Pull requests are always welcome（PR 永远欢迎），但遵循一套明确的指南可以显著提高 PR 被合并的概率。NBFC 的贡献形态主要分为两类：代码改进/缺陷修复（Improvements or bug fixes） 与 配置文件（Configs）。前者面向核心代码，后者面向 Configs/ 目录下数百个笔记本型号的 XML 配置——这也是社区贡献最活跃、也最需要规范的领域。

仓库根目录的 README.md 明确将「How to create a NBFC config」（如何创建 NBFC 配置）列为 Wiki 三大入门页面之一，说明配置文件贡献在项目协作中的核心地位。

Pull Request 提交规范

改进或缺陷修复类 PR

对于代码类贡献，CONTRIBUTING.md 给出了三条硬性要求：

1. Describe what changes you've made —— 明确描述改动内容；
2. Describe why the changes are useful —— 说明改动的价值与动机；
3. Include only relevant changes in your pull request —— PR 只包含与主题相关的改动，避免无关修改混入。

这三点看似简单，却是保证 NBFC 这类硬件控制项目（直接读写 EC 寄存器，风险敏感）代码可审查性的关键。从仓库结构看，核心代码分布在 Core/StagWare.FanControl/FanControl.cs、Core/StagWare.FanControl/Fan.cs 等文件中，改动涉及嵌入式控制器访问，审查者需要精确理解每一处变更的动机。

配置文件类 PR

配置文件贡献有更具体的专业要求，这直接对应 NBFC 配置系统中最容易出问题的两个高级特性：

• 基于已有配置时须注明来源：如果你的配置是在某个现有配置基础上修改的，必须在 PR 中说明基于哪一个配置（"please mention on which one"）。这能显著缩短审查时间——审查者可以对照原配置快速判断寄存器读写方式、温度阈值曲线是否合理。这也是合理的：同一厂商、同一系列机型的 EC 寄存器布局往往高度相似（例如仓库中大量 ASUS、HP 机型的配置都围绕相似的 EC 寄存器地址展开）。

• 说明配置的工作机制：尤其当配置包含以下两类高级元素时，必须描述其工作原理：

  • RegisterWriteConfigurations（寄存器写入配置）：用于在初始化或每次写入风扇转速时，额外向 EC 指定寄存器写入特定值，以完成诸如切换 EC 到手动控制模式、选择热区、模拟温度等前置操作；
  • FanSpeedPercentageOverrides（风扇转速百分比覆盖）：用于处理百分比与 EC 原始值之间并非线性对应的硬件，直接指定某一百分比对应的寄存器值。

• 配置必须开箱即用、无需系统改动：配置不得依赖欠压（undervolting）、安装第三方软件、物理改造硬件等条件才能正常工作。这是保证配置对全体用户安全、可复现的前提。

RegisterWriteConfiguration 的源码级解析

在 RegisterWriteConfiguration.cs 中，该类包含以下字段：

字段	取值	含义
WriteMode	Set / And / Or	写入方式：直接赋值、与运算、或运算
WriteOccasion	OnInitialization / OnWriteFanSpeed	写入时机：服务初始化时 / 每次写风扇转速时
Register	整数	目标 EC 寄存器地址
Value	整数	要写入的值
ResetRequired	布尔	停止服务时是否需要恢复寄存器
ResetValue	整数	停止服务时恢复写入的值
ResetWriteMode	Set / And / Or	恢复写入的方式
Description	字符串	对该写入操作的文字说明

其执行逻辑位于 FanControl.cs 的 ApplyRegisterWriteConfigurations 与 ApplyRegisterWriteConfig 方法中：

• 在 Start（非只读模式）与 InitializeRegisterWriteConfigurations 时会应用全部写入配置；
• 之后每次轮询更新 EC 时，OnWriteFanSpeed 类型的配置会被再次写入；
• And / Or 模式会先读取当前寄存器值再做位运算（value &= ec.ReadByte(register) / value |= ec.ReadByte(register)）；
• 停止服务时，ResetRegisterWriteConfigs 会对 ResetRequired 为 true 的配置写入 ResetValue，将 EC 恢复到自动控制状态。

以真实配置 Configs/ASUS Vivobook X580VD.xml 为例，该配置通过两条 OnWriteFanSpeed 的写入配置，在每次写风扇转速前向寄存器 160 与 166 写入值 10，并设置了 ResetRequired=true 与相同的 ResetValue，确保服务停止后寄存器恢复原状。

FanSpeedPercentageOverride 的源码级解析

FanSpeedPercentageOverride.cs 定义了三元组：

• FanSpeedPercentage —— 目标转速百分比；
• FanSpeedValue —— 对应的 EC 寄存器原始值；
• TargetOperation（Read / Write / ReadWrite）—— 该覆盖作用于写入方向、读取方向还是双向。

底层实现位于 Fan.cs：构造函数将配置中的覆盖项分别装入 overriddenPercentages（按百分比索引，作用于 PercentageToFanSpeed 写入方向）和 overriddenValues（按原始值索引，作用于 FanSpeedToPercentage 读取方向）。在 PercentageToFanSpeed 中，如果目标百分比命中了覆盖表，则直接返回对应的 FanSpeedValue，否则才走线性换算 minSpeedValueWrite + ((maxSpeedValueWrite - minSpeedValueWrite) * percentage) / 100.0。

当笔记本的 EC 风扇档位并非均匀分布（例如最低档寄存器值并非线性对应 0%）时，通过 FanSpeedPercentageOverrides 可以精确校正百分比与档位的映射。需要特别提醒：FanSpeedPercentage 必须是精确命中才会触发覆盖（字典键匹配），因此配置值必须与温度阈值中的 FanSpeed 数值完全一致，这在编写配置时是常见的踩坑点。

Issue 提交规范

如果你发现了 Bug 或有改进建议，CONTRIBUTING.md 建议先在 FAQ 中排查常见问题，再创建 Issue。

Bug 报告

一份高质量 Bug 报告应包含：

1. 系统信息：笔记本型号、操作系统版本、已安装的、可能与 NBFC 存在冲突的软件（文档特别提示了与 NBFC 的已知不兼容软件清单）；
2. 日志文件：提供日志文件，但不要直接粘贴日志内容到 Issue 正文，而是以附件形式上传。从仓库的 Linux 部署脚本 Linux/nbfcservice.sh 及服务端 FanControlService.cs 看，NBFC 依赖 NLog 记录运行日志，日志对定位 EC 读写异常至关重要；
3. 问题复现步骤：尽可能精确地描述问题现象与复现路径。

配置请求

这是社区最常见的 Issue 类型，CONTRIBUTING.md 给出了明确的行为引导：

1. 先尝试官方推荐配置：运行 nbfc.exe config --recommend，也许你的机型已有可用的推荐配置，无需再发起请求；
2. 不要请求他人代做配置：文档明确要求先阅读官方「如何创建 NBFC 配置」教程，自己动手尝试；
3. 卡住时提供充分信息：如果已阅读教程仍无法完成，请在 Issue 中提供尽可能详细的笔记本信息——制造商、型号、EC/SuperI/O 芯片名称、感兴趣的 EC 寄存器值等；
4. 善用机型专属论坛：通常笔记本型号专属论坛是寻找愿意协助创建配置的其他用户的最佳去处。

nbfc config --recommend 的底层实现

从 ConfigVerb.cs 看，config 动词支持四个互斥参数：

参数	简写	作用
--list	-l	列出所有可用配置（默认行为）
--set <cfg-name>	-s	设置（选中）一个配置
--apply <cfg-name>	-a	设置配置并立即启用风扇控制
--recommend	-r	列出可能适用于当前设备的配置

CLI 调用链（Program.cs 的 ConfigureService）为：nbfc.exe config --recommend → WCF 服务方法 GetRecommendedConfigs → FanControlConfigManager.RecommendConfigs()。

推荐算法的核心逻辑在 FanControlConfigManager.cs：

1. 通过 BiosInfo.BiosInfo.Create() 读取系统型号（GetDeviceModelName），并做规范化处理：去掉括号内容（正则 [\(\[\{].*?[\)\]\}]）、将 Hewlett-Packard 映射为 HP、必要时在型号前拼接厂商名；
2. 遍历 Configs/ 目录下所有配置名，同样去掉括号后，与设备型号做最长公共子串相似度匹配（GetSimilarityIndex，按空格分词、逐词计算 LCS 长度与词长之比并求和）；
3. 相似度 ≥ 1 的候选配置进入下一步；若多个候选的 ReadRegister+WriteRegister 组合（key 由 {ReadRegister}{WriteRegister} 拼接）相同，则只保留相似度最高的一个（避免同一寄存器方案重复推荐）；
4. 最终按相似度降序返回配置名列表。

也就是说，--recommend 并非保证配置一定可用，而是基于机型名称相似度与 EC 寄存器方案一致性给出的候选排序，最终仍需要用户实测验证。从 FanControlService.cs 可以看到，服务端将配置目录固定为程序目录下的 Configs 子目录，推荐结果直接来自该目录中已有的 XML 配置。

配置文件质量的自动化保障

仓库通过测试与校验规则为配置质量提供双层保障，这对 PR 审查极有价值：

配置校验器 FanControlConfigValidator.cs 通过反射自动加载 IValidationRule<FanControlConfigV2> 的所有实现类，规则位于 Core/StagWare.Configurations/Validation/Rules/ 目录，共 6 条：

规则	校验内容
FanConfigurationsNotEmtpy	配置必须包含至少一个风扇配置
MaxFanSpeedThresholdRequired	必须存在达到最大风扇转速的温度阈值
NoDuplicateTemperatureUpThresholds	同一风扇的 UpThreshold 不得重复
UpThresholdMayNotBeLowerThanDownThreshold	升温阈值不得低于降温阈值（避免滞后逻辑错乱）
UpThresholdsMustBeLowerThanCriticalTemperature	所有 UpThreshold 必须低于临界温度（并警告不得在临界温度 5 度以内）
ZeroFanSpeedThresholdRecommended	建议每个风扇都有 FanSpeed=0 的阈值，否则风扇永远不停转

以 UpThresholdsMustBeLowerThanCriticalTemperature.cs 为例：它逐条检查各风扇的温度阈值，若存在 UpThreshold >= CriticalTemperature 则报 Error，若存在 UpThreshold >= CriticalTemperature - 5 则报 Warning，提示临界温度过于接近。

测试保障：测试项目 ConfigsTests.cs 中的 AreConfigsValid 测试会遍历 Configs/ 目录下每一个 XML 配置，反序列化后用 FanControlConfigValidator 校验，任何配置不合规都会导致测试失败。HaveAllConfigsBeenLoaded 则确保所有配置文件都能被配置管理器正确加载。这意味着：提交配置 PR 前，在本仓库运行配置测试套件，是验证配置格式正确性的最低成本手段。

配置提交的实战建议

结合 CONTRIBUTING.md 与源码，一个容易被合并的配置 PR 应该做到：

1. 信息完整：PR 描述中写清笔记本型号、作者、基于哪个已有配置、配置的工作机制（尤其是涉及 RegisterWriteConfigurations / FanSpeedPercentageOverrides 时）；
2. 格式规范：XML 结构严格遵循 FanControlConfigV2.cs 定义的序列化结构（NotebookModel、EcPollInterval、ReadWriteWords、CriticalTemperature、FanConfigurations、RegisterWriteConfigurations），并让配置通过仓库测试套件的校验；可以参考结构清晰的现有配置，如 Configs/Lenovo ThinkPad T440s.xml（含 RegisterWriteConfigurations 与温度阈值示例）；
3. 阈值曲线合理：温度阈值满足「存在 0% 停转档位」「Up 阈值不重复」「Up 阈值低于临界温度」「存在 100% 满速档位」等校验规则；FanSpeedPercentageOverrides 中的百分比必须与阈值 FanSpeed 值精确一致；
4. 安全无副作用：确认配置不需要欠压、安装第三方软件或物理改造即可工作，且 ResetRequired 的寄存器在服务停止后能正确恢复。

小结

NBFC 的成功高度依赖社区贡献的配置文件生态。CONTRIBUTING.md 看似只是一份简短的协作规范，实则指向了配置系统中最关键的两个高级特性（RegisterWriteConfigurations 与 FanSpeedPercentageOverrides）以及一套完整的质量保障体系（校验规则 + 自动化测试）。无论你是想提交代码修复、报告 Bug、请求新机型配置，还是贡献自己的配置文件，遵循「描述改动动机、注明配置来源、提供完整系统信息、先试 --recommend、自测通过再提交」这条主线，都能让你的贡献更快被维护者接纳，也让 NBFC 的配置生态惠及更多笔记本用户。