rodrigogs/avell-sucks

为什么开发  ·  功能  ·  安装  ·  工作原理  ·  安全性  ·  构建

## 为什么开发 我在 2018 年买了一台顶配的 Avell 游戏笔记本。当 Windows 11 迎来它的首次重大更新（22H2 版本，发布于 **2022 年 9 月 20 日**，随后 Microsoft 对其提供了长达 **24 个月**的支持）时，OEM 的“Gaming Center”—— 这个掌控着风扇曲线、性能模式、键盘灯效以及整台机器散热与功耗特性的应用，已经 **被停止开发和废弃**了：它过时、臃肿、不再维护，却仍然是 驱动这台笔记本自带硬件的唯一官方途径。入手大约四年，运行我这台机器的软件已经死了。 所以，我要么忍受夹在我和我的硅片之间被废弃的臃肿软件，要么 替换掉它。这就是那个替代品。这个名字故意起得很直白：它点明了这个项目不得不存在的原因。 **AvellSucks 做了 OEM 应用做过的事，而且做得更好、更诚实：**它读写 厂商使用过的相同 Embedded Controller (EC) 寄存器，切换相同的 Windows 电源方案，并且从不对硬件写入是否真正成功而撒谎。 ## 键盘（为什么 RGB 未经验证） 这台笔记本让我心里有些不爽还有第二个原因，这也是为什么 RGB 选项卡 处于未完成和未经验证的状态。 在用了大概两年之后，我打开机器进行清理。在里面，键盘的 排线连接器破裂了，用一块胶带固定着。 不是我弄的。出厂就是这样。它发货时就是这样。 那时键盘已经出现故障，而且没有真正的办法修复它。我 去找了 Avell。他们无能为力，保修期已经过了，而且 这个缺陷从一开始就是他们的责任，但这毫无意义。 所以，这台机器的自带键盘已经坏了。RGB 灯效代码 （ITE HID）已经写好并接入了 UI，但我无法在一个 已经坏掉的键盘上测试它。在有硬件可以验证之前，它将保持 诚实的“不可用”状态。 ## 功能 - **风扇**：模式（auto、boost、custom、L1-L5）以及自定义的温度→PWM 曲线。编辑时实时生效；无需 Apply 按钮。 - **性能**：四种模式（Gaming / High / Balanced / Saving），可切换 激活的 **Windows 电源计划**并写入 CPU 功耗限制字节（PL1/PL2/PL4）。 - **设备**：经过验证的 Wi-Fi + Bluetooth、I2C 触摸板、网络摄像头、 内置面板亮度和关闭显示屏的控制。EC 无线写入受型号限制； 触摸板/摄像头/亮度使用 Windows PnP/WMI API 并带回读验证。 - **RGB**：键盘灯效层（ITE HID）。UI 和契约已就绪， 但后端未完成且未经验证（见[上文](#the-keyboard-why-rgb-is-untested)）。 - **仪表板**：实时 CPU/GPU 负载、温度、频率、内存、硬盘、网络以及 激活的散热配置，以约 1 Hz 频率流式传输 —— 并在主卡片中嵌入了 60 秒的 CPU/GPU 趋势 图表。 - **响应式**：在应用之外所做的更改（旧的 OEM 工具、物理 Fn 风扇键、其他电源计划切换器）会在几秒钟内显示在这里。 它反映设备状态；绝不假设自己最后一次写入仍然有效。 - **设置**：语言、开机启动、启动时最小化以及 最小化时隐藏到托盘。首选项持久化保存至 `%AppData%\AvellSucks\settings.json`。 - **语言**：支持英语和葡萄牙语，可在设置中实时切换，无需 重启。默认语言遵循你的 Windows 显示语言：在 pt/pt-BR 系统上为葡萄牙语，否则为英语。更改后，选择将被记住。 _{**品牌：**一款赛博朋克风格的性能仪表盘，*充满能量、精准、生动*。深紫黑色背景上的霓虹品红→青色。} ## 安装 1. 从 [**Releases**](https://github.com/rodrigogs/avell-sucks/releases/latest) 页面下载最新的 **`AvellSucks-Setup.exe`**。 2. 运行它。它会按机器安装到 `Program Files` 中，添加一个开始菜单 快捷方式，并在*添加或删除程序*中注册一个卸载程序。 3. 启动 **AvellSucks** 并批准 UAC 提示。 该应用会检查 GitHub 上的新版本，并可以从 **Settings → Updates** 进行自我更新（它会下载新的安装程序并静默重新启动）。 ### 开机启动 **Start with Windows** 开关会注册一个具有*最高权限*的 Scheduled Task，而不是 Run-key 条目，这是在登录时启动提权应用且每次开机**无需** UAC 提示的受支持方式。 ## 工作原理 一切都是通过逆向工程从反编译的 OEM 应用以及实时的硬件 探测中得出的。 ### EC 访问：WMI ACPI 测试接口 OEM 从未使用过自定义驱动。所有的风扇/电源状态都存在于 **Embedded Controller RAM** 中，通过 `root\WMI` 上的 WMI ACPI 方法访问： `AcpiTest_MULong.GetSetULong`（实例 `ACPI\PNP0C14\1_1`）。 - **读取：** `Data = 0x100_0000_0000 | addr` (2^40 + addr)；返回值为该字节。 - **写入：** `Data = (value << 16) | addr` ，**没有读取标志**（包含它会导致 EC 静默忽略写入；这耗费了一次调试才发现原因）。 ### 已确认的寄存器 | 地址 | 含义 | |---|---| | `0x751` (1873) | 风扇控制字节，0 auto，0x40 boost，0xA0 custom，0x81-0x85 L1-L5 | | `0x743`-`0x747` (1859-1863) | 自定义 PWM 级别 | | `0x783`/`0x784`/`0x785` (1923-1925) | PL1/PL2/PL4 调整字节 (瓦) | | `0x47B` / `0x7A1` | 无线状态 / 固件触发 (`0x80` Wi-Fi，`0x20` 蓝牙)，仅限 Avell 1555 | | `0x730`-`0x732` / `0x734`-`0x736` | Gaming / Office PL 默认值 (只读) | 在这块主板上，PL 寄存器读取为 `0`：真实的 CPU 限制由 **Intel XTU / MSR** 管理，而不是 EC，因此性能选项卡显示标称的预设 瓦数，而该模式的主要杠杆是 Windows 电源计划。 ### 电源计划 四种性能模式与机器自带的专用 Windows 方案一一对应 （`MyGamingMode` / `MyHighPerformance` / `MyBalanced` / `MyPowerSaving`），通过 `powercfg /setactive` 切换。 ### 安全写入流水线 每次 EC 写入都会经过 `SafeEcWriter`： **门控 → 允许列表 → 写入前快照 → 写入 → 读回验证 → 不匹配时回滚 → JSONL 审计。**被阻止或失败的写入在 UI 中显示为阻止/失败状态，绝不造假。控制寄存器的读回操作容忍固件的瞬时 状态位，并使用退避策略重试（EC 在转换过程中会吞掉写入，尤其是在 离开 Boost 状态时）。 ### 架构 .NET 10 解决方案 (`app/AvellSucks.Replacement.slnx`)： - `AvellSucks.Core`：硬件契约、安全写入流水线、模型 (可移植)。 - `AvellSucks.Core.Windows`：WMI EC、PnP、亮度和显示器电源后端。 - `AvellSucks.Api` / `AvellSucks.Server`：可选的本地 ASP.NET 控制制 API ，公开 `/api/fan/*`、`/api/power/*`、`/api/devices/*`、`/api/system/snapshot`、`/events` (SSE)。 - `AvellSucks.UI`：WPF 应用 (深色、赛博朋克风)，通过 LibreHardwareMonitor 进行遥测，每个选项卡配备响应式协调器。运行时本地化 (`.resx` + `Loc` 提供程序和 `{loc:Tr}` 标记扩展) 可实时切换语言；首选项以 JSON 格式持久化在 `%AppData%` 下，日志和 EC 写入审计位于 `%ProgramData%\AvellSucks` 下。 ## 安全性 该软件会写入底层硬件寄存器。允许列表限制了允许写入*哪些* (地址, 值) 对；每次写入都会通过读回进行验证，在不匹配时回滚，并 记录到 JSONL 审计中。电源限制和 EC 写入是最危险的地方，UI 会清晰地显示它们的门控/阻止/失败状态，绝不掩盖。 默认开启写入；如果你不在目标型号上，请在 **Settings → Hardware writes** 中切换到只读预览（或使用 `GAMINGCENTER_ALLOW_EC_WRITES=0` 强制开启）。 ## 远程访问与 MCP 控制 API 和 MCP 服务器可以暴露在你的网络中，以便其他设备 （或 AI agent）可以读取遥测数据，并且在你允许的情况下更改风扇/电源/设备。它 **默认是安全的**：仅限 localhost、无身份验证、无远程写入、MCP 关闭。全部 配置均可从 **Settings → Remote access** 进行 —— 该应用将热重载的配置 写入 `%ProgramData%\AvellSucks\service.json`，服务会自动获取它。 典型设置： 1. **作为后台服务运行** —— 安装一个 Windows 服务，使其在应用关闭时仍保持 API/MCP 可用。 2. **在网络上公开** —— 选择你的 **Tailscale** IP（推荐）或局域网 地址。保留在 `127.0.0.1` 则仅限 localhost。 3. **生成访问令牌** —— 仅显示**一次**；请立即复制。只存储其 SHA-256 哈希值。远程调用者将其作为 `Authorization: Bearer ` 发送。 可选要求客户端证书。 4. **启用 MCP** —— 在相同的身份验证下，于 `/mcp` 提供流式 HTTP MCP 服务器。 5. **允许远程硬件写入** —— 默认关闭。经过身份验证的远程客户端 可以自由读取；只有在你开启此功能后，它们才能控制风扇/电源/设备。 如果你保持 **firewall auto-open** 关闭，请手动添加入站规则 (提权运行)： ``` netsh advfirewall firewall add rule name="AvellSucks Control Service" dir=in action=allow protocol=TCP localport=5055 ``` 有关完整的身份验证模型、`/mcp` 端点和已验证的请求示例，请参见 [`docs/api.md`](docs/api.md)。 ## 从源码构建 **要求：** Avell 机器上的 Windows，.NET 10 SDK，以 **管理员身份**运行 （ring-0 传感器访问 + WMI EC 写入需要它）。WPF → 仅限 Windows。 ``` # 从 app 目录 dotnet build AvellSucks.Replacement.slnx # 运行 WPF app（提权） dotnet run --project src/AvellSucks.UI # 或本地控制服务器 + API dotnet run --project src/AvellSucks.Server -- 5055 # 测试（233: safe-write pipeline, allowlist, write gate, fan map, audit log, # machine-control orchestrator, wireless boot-restore policy） dotnet test AvellSucks.Replacement.slnx ``` **发布版本：** 推送一个版本标签 (`git tag v1.2.3 && git push origin v1.2.3`)。[发布工作流](.github/workflows/release.yml)将发布一个 独立的 win-x64 版本，编译 Inno Setup 安装程序，并将`AvellSucks-Setup.exe` 附加到 GitHub Release 中。 **写入门控：** 硬件写入**默认开启**（这是为其构建的机器的控制 中心）。在 **Settings → Hardware writes** 中将其关闭 （持久化保存）以进行只读预览。环境变量 `GAMINGCENTER_ALLOW_EC_WRITES` 强制覆盖并锁定该开关（`0`/`false` 关闭 —— 预览/演示；`1`/`true` 开启 —— 也允许非提权的开发进程或服务器流水线进行写入）。*(环境 变量保留其原始名称是为了与服务器流水线兼容。)* 请注意 **上方的安全警告**：寄存器是特定于型号的 —— 如果你不在目标硬件上，请不要让写入保持开启状态。 **性能提示：** 请从**本地磁盘**副本运行，而不是 WSL UNC 路径，通过 `\\wsl.localhost\...` 加载程序集会使启动时间增加约 9 秒。 ## 文档 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)：应用的构建方式 (按发布版本)。 - [`docs/reverse-engineering.md`](docs/reverse-engineering.md)：**经过验证的**硬件知识 —— EC 协议、已确认的寄存器、风扇映射、电源计划以及被证伪的内容。 - [`docs/api.md`](docs/api.md)：可选的环回 HTTP API。 - [`docs/design/`](docs/design/)：视觉系统 + 仪表板规范。[`docs/adr/`](docs/adr/)：决策记录。[`docs/runbooks/`](docs/runbooks/)：EC 写入批准检查清单。 - [`docs/evidence/`](docs/evidence/)：原始 RE 工件 (清单、EC 探测、OEM 字符串转储)。[`docs/archive/`](docs/archive/)：原始 RE 日志 + 研究档案。 - `scripts/*.ps1`：可复现的 Windows 清单/探测脚本。 ## 许可证 基于 [Apache License 2.0](LICENSE) 授权 —— 可免费使用、修改和 重新分发，包含明确的**无担保/责任限制**条款 （参见上文的安全提示；使用本软件操作硬件的风险由您自行承担）。 个人非官方项目。**不附属于 Avell。**“Avell”和“Gaming Center”是其各自所有者的财产；此处使用它们仅用于描述 本软件兼容的对象。

标签：RGB灯效, WPF, 游戏本, 电源管理, 硬件控制, 系统工具, 风扇控制