add: mqtt 客户端测试 + 文档更新

README.md

@@ -117,7 +117,10 @@ await client.stop()
 
 ## 与 aibox_sophon_adapter 插件的集成
 
-插件在 `[workers.config]` 下分别配置这三个客户端：
+插件在 `[workers.config]` 下分别配置这三个客户端，启动逻辑封装在插件的
+`mqtt_clients.py` 能力组件中（`start_mqtt_forward` / `start_mqtt_subscribe` /
+`start_internal_mqtt`，启动失败自动降级为 `None` 并告警），
+由 `AiboxSophonAdapterPlugin.on_init` 调用：
 
 ```toml
 [workers.config.mqtt_forward]       # -> MQTTForwardClient
@@ -159,6 +162,26 @@ async def _cmd_some_op(payload: dict) -> dict:
 
 ---
 
+## 测试
+
+单元测试位于 `utils/mqtt/test/`，通过注入 `FakeMQTT` 模拟底层连接，**不依赖真实 Broker**，可离线快速运行。
+
+```bash
+uv run pytest utils/mqtt/test -v
+```
+
+覆盖范围：
+
+| 测试文件            | 覆盖内容                                                                                           |
+| ------------------- | -------------------------------------------------------------------------------------------------- |
+| `test_forward.py`   | 凭据解码、默认/指定主题发布、未连接与异常时的行为、stop 断开                                       |
+| `test_subscribe.py` | 主题通配符（`+`/`#`）编译、无效路由跳过、消息分发、`reply_topic` 回复、`None` 不回复、`{1}` 占位符 |
+| `test_internal.py`  | 凭据解码、回显 `request_id` 关联、`{rid}` 模板、超时、FIFO 兜底、并发乱序、订阅去重                |
+
+> 若需对真实 Broker 做端到端验证，可参考项目根目录的 `test_mqtt_e2e.py` 模式，自行启动本地 broker 后联测。
+
+---
+
 ## 构建集成
 
 若通过 PyInstaller/Nuitka 打包，需在 `config.toml` 的 `[pyinstaller_build_import] base` 中加入：