feat: integrate N7Cockpit remote mode control

2026-08-13 10:36:24 +08:00
parent fd3c219c39
commit 78d758d3fb
108 changed files with 23150 additions and 16 deletions
@@ -0,0 +1,70 @@
+# N7Cockpit 远程功能模式接入
+
+服务器 A 运行 Cognitive_Agent 并独占 CAN 盒；服务器 B 只构建、分发 N7Cockpit
+Android APK。Android 和 Web 不互相调用，也不模拟页面点击，而是调用服务器 A
+上的同一个模式执行资源：
+
+```text
+N7Cockpit ─┐
+           ├─ POST /api/v1/vehicles/denza_n7/mode-executions
+Web Console┘                 │
+                             ▼
+                    Cognitive_Agent → 安全校验 → CAN → 车端回读
+                             │
+           GET /api/v1/vehicles/denza_n7/events?after=<sequence>
+                             ▼
+                       Web 与 Android 同步
+```
+
+Android 只提交仓库模式目录中的 `mode_id`。服务器再次按车型解析 YAML 预设，
+模式展开、参数校验、CAN 编译、硬件门禁和回读仍全部留在服务器 A。
+
+## 服务器 A
+
+生成至少 32 字节的随机设备令牌，将同一个值配置给服务器 A 和服务器 B 的
+Android 构建环境。不要提交令牌到源码：
+
+```powershell
+$env:COGNITIVE_AGENT_DEVICE_API_TOKEN = '<长随机令牌>'
+$env:PYTHONPATH = 'src;domains/seat/src'
+python -m cognitive_agent.server --host 0.0.0.0 --port 8000
+```
+
+开放防火墙时只允许服务器 B、车机所在网段访问 TCP 8000。跨不可信网络应在服务
+前使用 HTTPS 反向代理；Android 配置的地址必须是服务器 A 的可路由 IP 或域名，
+不能是 `http://127.0.0.1:8000`。
+
+设备令牌可访问以下受限接口：
+
+- `GET /api/v1/vehicles/{vehicle_id}/modes`
+- `POST /api/v1/vehicles/{vehicle_id}/mode-executions`
+- `GET /api/v1/mode-executions/{execution_id}`
+- `GET /api/v1/vehicles/{vehicle_id}/events?after={sequence}`
+- 硬件使用权的申请、状态与释放接口
+
+真实硬件仍采用本机审批租约。Android 首次点击“申请真实硬件控制”后，服务器 A
+操作员访问 `http://127.0.0.1:8000/hardware-control`，批准
+`hwc-n7cockpit-001`。审批 API 只允许服务器 A 的无代理回环请求，设备令牌不能批准
+自己。
+
+## 服务器 B / Android
+
+在 N7Cockpit 根目录构建：
+
+```powershell
+$env:COGNITIVE_AGENT_BASE_URL = 'http://<服务器A局域网IP>:8000'
+$env:COGNITIVE_AGENT_DEVICE_API_TOKEN = '<与服务器A相同的令牌>'
+./gradlew.bat assembleRelease
+```
+
+安装 APK 后进入“模式”页。目录只显示 Cognitive_Agent 的 `origin=preset` 模式；
+执行目标默认是 `hardware`。queued/executing/terminal 事件每秒同步到 Web 和 Android，
+任务终态后两端再读取完整执行结果并显示车端状态。
+
+## 联调顺序
+
+1. 先把 Android 构建参数 `orchestratorExecutionTarget` 设为 `dry_run`，验证模式目录、
+   Android 点击、Web 状态和最终孪生状态。
+2. 再切换为 `hardware`，由服务器 A 本机批准 Android 终端。
+3. 在空载且可急停条件下依次验收零重力、小憩、轻松进出；核对 Web 和 Android 的
+   execution_id、终态、CAN 回读一致。