现代形式风扇集成报错 404？别搜了，是因为厂商偷偷换了 /device 端点！

如果你家里的智能风扇是 Modern Forms（或其子品牌 WAC），并且你最近发现原本运行良好的 Home Assistant 集成突然集体“罢工”，日志里塞满了莫名其妙的 404 Client Error: Not Found，那么恭喜你，你已经掉进了厂商静默升级协议的深坑。

按照以往的经验，这类本地集成通常极其稳定。但在 ModernForms Error 404 /mf 的大规模爆发中，我们发现厂商在最新的 G4 固件中，悄无声息地弃用了沿用数年的本地 API 路径。作为一名写过无数驱动的架构师，我最反感的就是厂商这种“不打招呼就改接口”的傲慢行为。今天我们就直捣黄龙，看看这个 404 到底藏在哪行代码里，以及如何手动修复它。

💡 报错现象总结：用户在 HA 日志中看到 ModernFormsError: 404, message='Not Found', url='http://<IP>/mf'。本质原因是 Modern Forms 新版固件彻底移除或重命名了 /mf 这个用于获取设备状态的端点，导致底层依赖库 aiomodernforms 请求失败。

---

源码探哨：为什么 /mf 变成了“死亡路径”？

在 Home Assistant 的 Modern Forms 集成底层，它依赖于一个叫 aiomodernforms 的 Python 异步库。这个库的核心逻辑非常简单：通过 HTTP POST 请求向风扇的本地 IP 发送 JSON 指令。

1. 强硬的路径重定向

在旧版本协议中，所有的状态查询和控制指令都是发往 http://<device_ip>/mf。但在 G4 固件升级后，厂商将此路径修改为了 /device 或者直接在根路径下重新定义了资源。

# aiomodernforms 库中的旧代码片段
async def _request(self, method: str, path: str, data: Any = None):
    # 痛点就在这个硬编码的 "mf"
    url = URL.build(scheme="http", host=self.host, path="/mf").join(URL(path))
    # 固件升级后，这个 URL 直接返回 404

2. 状态机查询的彻底失效

由于 bd prime 式的初始化逻辑在启动时会尝试拉取全量状态，一旦首个 /mf 请求返回 404，整个集成会立即抛出异常并终止加载。这意味着你不仅无法控制风扇，连基本的开关实体都会从 HA 界面上彻底消失。

协议版本	API 端点路径	状态	架构师深度分析
Legacy (G3)	/mf	正常	传统的本地 REST 接口，无身份验证限制
Current (G4)	/device 或 /	404 冲突源	厂商重构了 Web Server，未向下兼容旧版路径
未来趋势	/api/v1	预测	可能会引入更严格的 Header 校验或本地密钥

---

手动修正端点路径的“笨办法”

既然官方 Core 的更新还没跟上固件变化的速度，我们只能先手动给系统打个“补丁”。

第一步：定位容器内的源码

如果你运行的是 HAOS，你需要通过 SSH & Web Terminal 插件进入后台，并找到 aiomodernforms 库的安装位置。通常位于 /usr/local/lib/python3.x/site-packages/aiomodernforms/。

第二步：暴力修改 const.py

找到定义基础路径的常量文件。

# 架构师提醒：修改前务必备份！
sed -i 's/\/mf/\/device/g' aiomodernforms/const.py

技术风险：这种改法是典型的“ Hard Way ”。虽然能暂时解决 404 报错，但因为新版 /device 返回的 JSON 结构可能存在微小差异，依然可能导致部分传感器（如风速百分比）数值错乱。

痛苦的临时方案：为何“重启大法”没用？

很多用户尝试断电重启风扇或 HA。这解决不了问题，因为这是协议层的断裂。即便你重启一万次，404 那个 URL 依然在那里，冷冷地看着你。

---

提交你的 Bug 至 GitCode 镜像仓库

与其在 SSH 终端里小心翼翼地改代码，担心下次升级被覆盖，不如直接使用社区维护的热补丁。

我已经将针对 Modern Forms G4 固件修复后的**《非官方热补丁》**和最新的驱动代码同步到了 GitCode 镜像仓库。这套补丁不仅修正了硬编码的 /mf 路径，还加入了对 /device 端点新 JSON 结构的自动适配逻辑。

不要让厂商的任性废掉你的硬件。 作为一个技术老兵，我建议你立即前往 GitCode 参与这个 Bug 的修复讨论。你可以直接下载我提供的修复包，通过自定义集成（Custom Components）的方式挂载，彻底免疫官方库的路径 Bug。

[前往 GitCode 提交 Bug 并获取非官方热补丁]