Wallezy/mgu-setup-skills / skills/mgu-setup
mgu-setup
VerifiedSet up and maintain an owner-authorized BMW MGU over ENET using SSH and Store tools. Use for environment checks, backup preparation, initial root, Store setup, supported distribution migration, map/HUD setup, live read-only log collection and diagnostic bundles, updates, and supported rollback or removal. Supports Chinese and English.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 34.3 KB |
| NOTICE.md | markdown | 958 B |
| SKILL.md | skill md | 7.7 KB |
| agents/openai.yaml | config | 358 B |
| assets/wechat-code.png | binary | 613.2 KB |
| references/contact.md | markdown | 437 B |
| references/diagnostics.md | markdown | 15.3 KB |
| references/evidence.md | markdown | 14.3 KB |
| references/maintenance-update.md | markdown | 7.9 KB |
| references/network-mirrors.md | markdown | 16.1 KB |
| references/network-sources.json | config | 976 B |
| references/recovery.md | markdown | 23.4 KB |
| references/release-channels.md | markdown | 11.0 KB |
| references/root-tool.json | config | 568 B |
| references/root-tool.md | markdown | 9.8 KB |
| references/session-record.md | markdown | 7.3 KB |
| references/store-distributions.md | markdown | 11.7 KB |
| references/workflow.en.md | markdown | 13.6 KB |
| references/workflow.zh-CN.md | markdown | 12.2 KB |
| scripts/check_environment.py | script | 6.5 KB |
| scripts/collect_diagnostics.py | script | 21.7 KB |
| scripts/diagnose.py | script | 18.8 KB |
| scripts/mirror_resources.py | script | 18.8 KB |
references/workflow.zh-CN.md
View on GitHub# 安装与维护流程
## 1. 范围与电脑环境
确定本次终点:准备资源、首次 root、商店修复/安装、地图/HUD、更新、回滚或卸载。读取所用仓库的要求,保留车主选择和已有改动。
首次安装先按[版本选择](store-distributions.md#choose-edition):大陆推荐国内版,
其他地区推荐官方版,尊重用户选择。第 4–5 节命令针对官方版;国内版使用
[匹配的安装器与可用性检查](store-distributions.md),不执行下方官方安装示例替代。
已有安装切到国内版、其他二开版或切回官方版,先走
[整套发行版切换](store-distributions.md#switch-distribution),包含电脑安装器与车端组件,
不重复首次 root 流程。
用准备运行 SSH 源码工具的 Python 执行 `scripts/check_environment.py`,检查 Python、cryptography、Node 和 OpenSSH。它不判断车辆是否具备刷写条件。
涉及 Root 时,先按 [Root 工具准备](root-tool.md)选择正式版本和独立本地目录,再用
`--profile root --root-repo <已准备的Root源码目录>` 校验运行环境与版本。当前审阅基线为 v1.4.0;
来源选择、离线复用和新版本判断以该参考为准,不重复下载,也不沿用未核验的旧目录。
| 系统 | 检查重点 |
|---|---|
| macOS | 拓展坞网卡、链路本地地址、热点/VPN 与 ENET 路由;接口名不能写死 |
| Windows | OpenSSH、所选 Python 的依赖、上游对 ENET 的管理员要求;使用 PowerShell 语法 |
| Linux | 链路、权限、OpenSSH 和路由,不能照搬 macOS 网卡绑定参数 |
源码解锁需要 Python 3.9+ 和上游 `requirements.txt`;Windows 也可使用预编译程序。直接运行 `mgu-install.js` 需要 Node 18+,当前官方 shell/PowerShell 包装安装器提供另一种运行时准备方式。核对当前最低要求,优先选受维护且兼容的版本。
检查当前 README、正式发布和已知问题,条件允许时固定到已审阅的安装器提交。案例版本不是永久推荐版本。电脑证书异常时不能关闭 TLS 校验来下载。
计划写入前,在选定环境中准备缺失依赖并重新运行对应检查。按第 5 节将所需上游工具、本次安装包及完整依赖下载到本地,记录来源、版本、长度、来源提供的校验值与本地哈希,并检查归档可读。所需资源仍未下载完成时,不能开始首次刷写或安装。
Root 资源必须匹配所选架构并私有保存;为选择资源可提前只读识别车辆。车辆与资源匹配后,在会话模板记录准备结果;目标车辆或版本选择变化时重新判断。
## 2. 识别车辆与准备备份
用已核验为只读的上游状态/发现功能识别网关与 HU,记录架构、固件、接口、IP 和车辆身份。不能复用其他会话的 VIN 或网关。已有连接可用时,不为发现设备而改编码或开启调试。不要仅凭命令名判断只读:deploy 0.8.8 的 `status` 可能修复目录或重启管理器,见 [只读检查与修复](recovery.md#read-only-status-versus-repair--只读检查与修复)。
首次刷写前确认车辆停稳、保持唤醒,有适合编程的稳定电源,并确认刷写前 HU/MGU 编码备份、模块选择、工具和位置。以下资料保存于公共仓库之外:
| 备份 | 范围与验证 |
|---|---|
| 编码 | 兼容编码工具的 HU/MGU 备份;AI 无法操作时由车主完成。不能恢复可执行文件 |
| 访问凭据 | 匹配的 root 密钥、登记信息、连接资料;不能假定每车密钥唯一 |
| 部署 | 操作前状态、版本、注册/入口状态、部署快照;检查归档内容、退出码和保留范围 |
| 补丁原件 | 已验证原件、补丁记录、权限和所有者;不是完整固件镜像 |
编码采集的 `verified=true` 或文件哈希一致,不能代替完整性和可恢复性判断。只有补充 DID 记录时,不能标记“恢复准备完成”或放行首次刷写;核对匹配的 HU/MGU 备份、兼容恢复工具与格式,见 [编码采集边界](root-tool.md#coding-capture-limits)。
当前 root README 记录了刷写导致编码/CAFD 和 Digital Key 配对丢失。编码备份不覆盖数字钥匙,不能保证任意故障都可恢复或承诺固定恢复耗时。
## 3. Root SSH:先判断再写入
先使用现有授权凭据连接已识别的 HU。root 登录正常时跳过首次设置。
对未设置的车机,检查已核验源码的 CLI 帮助和架构参数。v1.4.0 的命令形态:
```text
python <已核验Root目录>/ssh_enable.py status
python <已核验Root目录>/ssh_enable.py flash --arch <已核实变体> --vin <已核对的车辆VIN> --persist
```
这是 agent 流程示例,不是每次连车都执行的命令。变体必须明确为 `id7`、`id8-bdc3` 或 `id8-bcp`;
v1.4.0 GUI 要求选择,但 CLI 仍默认 ID7,因此不得省略 `--arch`,也不能只凭车型/VIN 猜测。
仅在授权且前提齐备的首次设置中执行 flash。GUI 的“Flash + Enable”及 CLI 的 `--persist`
已包含持久化请求,完成后单独核验结果,不再机械追加 enable/persist。
已设置 SSH 却失败时,区分超时、主机密钥变化和公钥拒绝,先检查路由、唤醒状态及凭据。`enable` 修复已有设置,不是日常连接步骤。`fix-key` 会重新刷写,需要单独判断并满足刷写前提。不要默认启用可选的密钥替换。
设置后验证新的 root 登录、持久化及预期调试状态。根据工具流程与实际状态,用适配的编码工具恢复刷写前备份,再检查启动与连接。不能反复刷写来修复编码丢失。
## 4. 官方商店安装与恢复
已选官方版时,使用 `robertnisipeanu/mgu-store` 已审阅的正式安装器。
国内版按对应发行流程执行;是否有中文界面不能决定后续更新源。
已审阅的独立安装器命令形态:
```text
node mgu-install.js first-install --from <准备目录>/mgu-repo/mgu-store --identity <私钥路径>
```
使用第 5 节准备并校验的本地目录。后续应用若选择在线更新路径,应保留已验证的本地资源,并确认车机可访问同一目标发布;不能在准备和安装之间悄悄切换版本。
审阅的安装器支持重复运行并保留已安装的更新版本。`first-install --from` 也可用于兼容的商店组件刷新,通过 ENET 发送本地包,无需实体 U 盘或车机互联网;检查当前健康状态和安装范围后使用。它不会替你更新任意第三方应用。
自动发现选错路径时,使用实际观察的 host/port。需要时复用可用的网卡绑定中继,不能写死案例端口。检查所选安装器 SSH 参数顺序和实际主机密钥校验行为。
安装器使用正式发布资源、目录长度/哈希校验和对应部署工具。保存退出码、日志,核对部分成功情况和实际版本。
入口缺失时,对照真实注册、应用管理器、入口可见状态和部署历史。保留的安装包或陈旧记录不等于已安装。用官方安装/修复流程恢复,不手改注册表或重新刷写 SSH。
## 5. 离线资源与网络
复用已选版本和来源。需要准备官方包时,再按 [网络源流程](network-mirrors.md)
和 [地址配置](network-sources.json)选择下载路径;备用源包含 Gitee 源码和官方包 OSS 缓存。
下方是官方 GitHub 示例,不是国内版目录。不存在 `gitee:` 更新源类型;
回退下载路径须保持同一发行版、版本和 SHA-256。
分别测试电脑和车机更新服务。GitHub API 可用不代表发布资源可下载,须检查所需资源和哈希。热点连通不代表 GitHub 可达。
优先使用官方离线流程,先创建目标目录:
```text
node mgu-install.js usb-repo <已存在目录> github:robertnisipeanu/mgu-store github:robertnisipeanu/idrive-apps
node mgu-install.js first-install --from <已存在目录>/mgu-repo/mgu-store --identity <私钥路径>
```
第二行通过电脑到车机的连接安装商店。后续应用可把准备好的资源放在实体 USB 媒体中,通过商店“USB”页面安装。仅在电脑创建目录,不会使其自动成为车机 USB 源。
也可用商店支持的 HTTP/SOCKS 代理设置,连接车主控制的可达代理。车机上的 loopback 不指向电脑,除非确有转发路径。ENET 隧道仅用于本次任务,记录旧设置并在断开前恢复。不能关闭 HTTPS 检查,也不能在共享日志中暴露代理凭据。
## 6. 地图与 HUD
复用版本选择:国内版使用自带的国内地图目录;官方版按网络选择 GitHub 直连或经过校验的
备用源,保留用户明确指定的偏好,不再询问线路。需要备用源时按
[来源切换流程](network-mirrors.md)处理;地图备用源不会改变商店及基础组件的内置官方源。
保留一份匹配目录和其他作者的独立来源。通过商店或更新器安装 `robertn_waze_cluster`,
由依赖声明选择 `waze-on-cluster` 和 `cluster-render`。
检查补丁状态:安装可能保留此前关闭的 CarPlay 补丁。在兼容且属于请求范围时,通过应用“应用补丁/Patch”控制。Android Auto 状态独立,并受编码/架构约束。
在应用中选择仪表盘、HUD 或两者,先确认“Show on”没有设为 Off。HUD 属上游实验性功能。仪表盘中央区域按说明选择地图视图;必要时重连 CarPlay,开始导航,检查视频流/渲染器并获得实际屏幕结果。0.6.6 的 Off 开关无需重连或重启;0.6.7 的“Keep HUD map over BMW pop-ups”应保留车主偏好,详见 [地图诊断](recovery.md)。
应用 0.6.4 与地图服务 0.9.3 提供“Own settings for this driver”选项:默认共享设置,启用后按驾驶员保存显示目标、HUD 大小和位置。按实际界面翻译识别该选项,不假定所有地图设置都按驾驶员隔离。仅在车主需要时启用;切换驾驶员后验证配置随之变化。驾驶员身份未识别或服务不可用时,控件可能不可用,不应因此重新刷写。配置备份和降级注意事项见 [recovery.md](recovery.md)。
使用提供的正常重启并遵守冷却时间。之后检查启动标识/运行时长、核心服务、文件权限/所有者、启动验证、应用注册和待重启项目。案例构建的 carplay/aapd 预期为 0755;其他构建根据已验证原件和当前上游判断。
无画面时区分补丁关闭、等待重启、手机未输出副屏流、HUD 关闭、渲染器错误和导航应用不兼容。未观察对应组合时,不保证高德/百度效果或固定帧率。
延迟问题可结合地图服务 0.9.2 起的帧组装、解码缓冲及 H.264 诊断判断。日志增强不等于帧率提升;cluster-render 0.4.2 扩大图层容量,也不代表视频带宽增加。
## 7. 更新、降级和移除
已有商店的更新先按 [维护更新路径](maintenance-update.md)复用本地资源与私有记录,核对实际已安装版本,再决定下载差异和传输方式。电脑离线目录、车机 USB 源和 OSS 在线源是三种不同状态,不能下载离线包后又默认改用在线源。
记录当前版本和已知可用资源,刷新正式发布目录,检查依赖,只请求用户选择的更新。由更新服务处理依赖,完成必要重启后再核对版本。不能修改版本号绕过检查。
使用备用源时核对本次所需的实际目录及资源,不能只看 Skill 或 Gitee 是否更新。
按选定发布的实际依赖准备资源。车辆固件更新后出现“Needs setup / Set up”时,
按当前商店提供的设置流程处理,完成提示的重启并验证,不恢复旧固件的系统文件快照。
降级、回滚读取 [recovery.md](recovery.md);撤销补丁、卸载整套商店或关闭/撤销常驻 SSH,
按[卸载范围与顺序](recovery.md#removal)执行。这些操作均不等于恢复原厂固件。
## 8. 验证与交接
使用 [session-record.md](session-record.md)。等待当前版本规定的启动后检查并读取结果,不能仅凭等待时间宣布成功。区分本来无入口的后台工具与应有入口的应用。
恢复临时设置,关闭仅本次使用的隧道。若用户需要永久 SSH 就保留,关闭访问是另一终点。报告实际结果和仍需屏幕或编码工具完成的动作。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |