merge: integrate remote MQTT routing with seat-scoped dynamic modes

2026-09-12 15:10:16 +08:00
parent d8dad22ec0 7eed11b774
commit 3eeca2ea75
43 changed files with 5726 additions and 492 deletions
@@ -5,7 +5,7 @@
 Web 控制台与同源 API 由同一个 Python 服务提供。本地启动：

 ```bash
-make dev
+.\.venv\Scripts\python.exe .\tools\start_n7web.py
 ```

 Windows PowerShell 未安装 `make` 时可直接运行：
@@ -172,6 +172,31 @@ config/gesture/default.yaml

 同一局域网的其他电脑需要体验时，使用 `make dev-lan` 监听全部网络接口。服务启动日志会打印实际 LAN 地址，例如 `http://172.20.10.5:8000`。前端和 API 使用同源访问，不需要 CORS，也不会把 `OPENAI_API_KEY` 发送到浏览器。若没有启用 `.env.auth`，任何可达设备都能触发服务端 GPT 请求，因此未认证的 LAN 模式只应在可信网络内临时演示。

+### N7 模式卡片局域网目录
+
+服务正常启动时，会把当前车型可见的工程预设模式和用户自定义模式原子同步到相邻目录 `../scenses/demo-scenes.json`，并提供无需登录、只读的 `GET /n7/scenes`。YAML 模式库仍是唯一真源；创建、更新、删除、恢复模式都会刷新 JSON，原有模式执行和安全校验链路不变。JSON 保留 `n7-scenes` v1 的 `id/label/background_time/description/actions` 字段，同时在动作中保留完整的 `domain/capability/target_scope/operation/parameters`，因此座椅、空调、天幕和氛围灯配置不会在导出时丢失。可用 `N7_SCENE_CATALOG_PATH` 或启动参数 `--scene-catalog` 覆盖输出路径。
+
+分阶段动态模式额外保留完整 `schedule` 和用于展示单轮阶段起点的 `preview_actions`，并标记 `execution.kind=server_schedule`。此类模式的旧版 `actions` 列表为空，避免不认识时间轴的 v1 客户端把多个阶段同时下发；必须通过主工程已认证、受控的模式执行链运行。静态模式和已有 `timeline` 格式不变。
+
+主项目和客户端只读目录服务可以用一个监督脚本同时启动：
+
+```powershell
+.\.venv\Scripts\python.exe tools\start_n7web.py
+```
+
+脚本自动设置 `PYTHONPATH`，主页面默认仅监听 `127.0.0.1:8000`，模式卡片 HTTP/UDP 服务监听 `0.0.0.0:8090`。需要让可信局域网内的设备同时访问主页面时，使用 `--host 0.0.0.0`；可通过 `--port`、`--scene-port`、`--catalog` 和 `--server-id` 覆盖其他参数。任一子服务异常退出或按一次 `Ctrl+C` 时，脚本会停止另一个服务。
+
+同步由模式注册表的创建、更新、删除、恢复和显式重载事件触发，不会持续扫描目录。每次变更只重新生成并原子替换一份小型 JSON；独立目录服务在收到 HTTP 请求时才读取它。因此空闲时的额外开销主要是一个等待请求的 Python 进程和一个 UDP 发现线程，而不是持续的 CPU 或磁盘轮询。
+
+如果只需单独启动 UDP 发现和只读目录服务，也可以在另一个 PowerShell 终端运行：
+
+```powershell
+$env:PYTHONPATH = "src;domains/seat/src"
+.\.venv\Scripts\python.exe -m cognitive_agent.lan_scene_server --bind 0.0.0.0 --port 8090
+```
+
+客户端向 UDP `8090` 发送 `N7_SCENES_DISCOVER_V1`，收到 `N7_SCENES_V1` 后访问 `http://<服务端IP>:8090/n7/scenes`。独立服务每次请求都读取最新的 JSON，并为只读接口开放 CORS；它不提供模式创建、修改、删除或执行能力。
+
 Linux 上使用 USBCANFD-200U 被动同步 CH1 车辆状态时，使用
 `zlgcan-linux` 后端。USB 权限、60 MHz/500k/2M 位时序、只读配置和状态接口
 验证见 [Linux ZLG 车辆状态接入](docs/workflows/linux-zlg-vehicle-state.md)。