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,54 @@
+# N7Cockpit Android
+
+原生 Android 车舱应用。功能模式页从服务器 A 的 Cognitive_Agent 获取预设模式，
+提交模式任务，并每秒同步 Web/Android 共用的执行事件与最终车端状态。
+
+跨服务器迁移请优先阅读 [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)。可迁移 ZIP
+通过 `scripts\create-portable-package.ps1` 生成，包内不包含设备令牌、构建缓存、
+历史 APK 或本机测试产物。
+
+## 服务器 B 构建
+
+工程使用 Android Gradle Plugin 8.7.3、Gradle 8.9、JDK 17+ 和 Android SDK 35。
+工程已包含 Gradle Wrapper，服务器安装 JDK 17 或更高版本和 Android SDK 35 后可直接构建。
+
+服务器 A 地址和设备令牌通过 Gradle 属性或环境变量注入。真实设备不能填写
+`127.0.0.1`；该地址会指向 Android 设备自身。`10.0.2.2` 只适用于 Android
+模拟器访问宿主机。
+
+```powershell
+$env:COGNITIVE_AGENT_BASE_URL = 'http://192.168.1.10:8000'
+$env:COGNITIVE_AGENT_DEVICE_API_TOKEN = '<与服务器A相同的长随机令牌>'
+./gradlew.bat assembleRelease
+```
+
+也可使用 `-PorchestratorBaseUrl=...`、`-PorchestratorApiToken=...`、
+`-PorchestratorVehicleId=denza_n7`、`-PorchestratorHardwareClientId=hwc-n7cockpit-001`
+和 `-PorchestratorExecutionTarget=hardware`。APK 输出位于
+`app/build/outputs/apk/release/`。
+
+未传 `orchestratorExecutionTarget` 时默认使用 `dry_run`。真实 CAN 构建必须显式
+传入 `-PorchestratorExecutionTarget=hardware`，避免普通调试构建误入硬件执行。
+
+开发环境允许局域网 HTTP；生产跨服务器部署应在服务器 A 前配置 HTTPS，并关闭
+Manifest 的明文流量许可。令牌会进入 APK 的 BuildConfig，因此它只用于受控车机，
+如 APK 会公开分发，应改为设备注册后下发短期凭据。
+
+## 模拟器远程联调
+
+启动已安装的远程联调应用时，不要解析 `resolve-activity` 输出后直接拼接命令；
+部分 Android 版本会先输出匹配优先级元数据。使用固定、完整组件名启动，并验证
+Activity 确实处于前台：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-remote-app.ps1
+```
+
+自动联调脚本会校验模式目录、启动 Android、点击“宝宝午睡模式”，并检查
+`queued -> executing -> succeeded` 事件、相同的 `execution_id` 和车端状态回显。
+脚本只允许 `10.0.2.2:8000` 且强制要求 APK 的执行目标为 `dry_run`；不申请硬件
+控制权限，也不会执行真实 CAN：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-remote-link.ps1
+```