| name | android-mainline-port |
|---|---|
| description | 把主线 Linux 和桌面发行版移植到 Android 手机、平板的操作手册与经验库（高通 + Ubuntu GNOME 实践）。覆盖评估、构建、bootloader、设备树、显示、触控、音频、无线、充电、休眠、双系统、打包、测试与发布。用户想在安卓设备上跑原生 Linux、移植主线内核、fastboot 启动自制内核、排查外设在主线下不工作，或评估设备能否移植时使用。 |
安卓设备移植主线 Linux
这份 skill 怎么组织
- 外层框架（本文件和
references/）：先做什么、后做什么，工作纪律，技术选型，怎么判断通过。相对稳定。 - 经验库（
experience/）：按领域写的推荐路线、完成标准和具体的坑（现象、原因、怎么确认、怎么解决、怎么预防）。随项目不断追加。
经验来自高通平板移植到 Ubuntu 26.04 + GNOME 的过程。硬件和内核部分基本通用；Ubuntu 相关部分换发行版时按 references/ubuntu.md 最后一节调整。版本号和接口名有时效性，使用前核对上游现状；上游已经解决的问题，直接用更简单的办法。
怎么用
- 新项目：按下面的流程从第 0 步开始，每一步先读
references/process.md对应小节，再读相关的experience/文件。 - 中途接手：先读项目自己的 AGENTS.md、状态表和技术债表，再定位到流程中的哪一步。
- 做技术决策：先读
references/decisions.md对应一节的默认做法和规则。 - 排查故障：先按
experience/patterns.md判断问题属于哪一类、按通用步骤排查；再用日志里的错误码、函数名、配置项在experience/里grep找具体案例。 - 只做评估：完成第 0 步，输出评估报告和决策清单。
流程
| 步 | 做什么 | 完成标准 | 主要参考 |
|---|---|---|---|
| 0 立项 | 建工作区；资料池（上游、同 SoC 社区、厂商源码、同类项目）；复用调研；硬件清单；选型；估算；和用户确认决策 | 用户确认决策清单；确认前不碰设备 | references/process.md、references/decisions.md、references/discipline.md |
| 1 构建环境 | 工具链、ccache、长期 OUT、根文件系统构建方式；原样构建一次社区参考内核 | 参考内核可复现，增量构建几分钟 | references/build-environment.md |
| 2 取证与备份 | root；按确认的范围备份并校验；取出运行时设备树、固件、PMIC 电压、显示参数、原厂命令序列；准备恢复 | 备份两侧哈希一致；恢复镜像在手 | references/process.md、experience/usb-and-storage.md |
| 3 首次启动 | 离线搞清 bootloader；最小设备树；时标探针；只读 initramfs + USB 网络 + 超时回退 | 主机能连 shell，超时自动回原系统 | experience/bootloader-and-boot.md、experience/kernel-and-resources.md |
| 4 点亮与内存桌面 | 选显示路线，同时启动原生接管；触控；GPU；RAM 根；GNOME；桌面自动化和验收脚本 | 人眼看到画面、手指能操作，硬件指标通过 | experience/display.md、experience/touch-and-input.md、experience/gpu.md |
| 5 安装到存储 | 维护镜像；分区；tar + 设备上格式化；启动镜像集与活动槽轮换；切换工具；调试通道默认关可打开 | 冷启动预算通过；Linux 与 Android 来回切换真机通过 | experience/usb-and-storage.md、references/ubuntu.md |
| 6 外设 | 按优先级一次一个：查复用 → 对照原厂 → 独立测试镜像 → 真机 → 合并 → 冷启动回归 | 每项有真实结果证据 | experience/ 各领域 |
| 7 发布 | 功能冻结；分层打包；按公开文档从零安装验收；第一小时审计；对外文档审核 | 别人按文档能构建、安装、使用 | references/ubuntu.md、experience/build-and-release.md |
| 8 维护 | 上游合入就删本地实现；按影响还技术债；每次更新冷启动验证 | — | references/discipline.md |
顺序上最容易出错的地方
下面这些顺序错误代价最大，通常一次就是数天：
- 先看同类项目再设计。 安装方式、切换方式、调试通道、打包结构，同 SoC 或同类设备的项目往往已经有成熟做法和复盘。
- 先建调试通道和自动恢复，再做任何实验。 默认启动路径在通道建立前不碰外设寄存器。
- 先取证，后写设备树。 每个数值来自本机原厂证据，不从参考设备抄。
- 借用固件画面只用于首次点亮。 原生显示接管从第 4 步就开始并行，亮度、熄屏、休眠、外接显示都依赖它。
- 桌面在内存里能跑就尽快持久化。 不要等外设做全。持久化之后才能做冷启动验证，迭代也更快。
- 新功能先单独测，再合并。 不要把多个未经真机验证的改动塞进一个候选。
- 日常迭代在设备上装包。 只在发布时完整构建根文件系统。
- 发布前按公开文档完整走一遍全新安装。
工作纪律（必须做到）
细节见 references/discipline.md。
- 必须写文档，并在固定时刻写。 开始功能前写路线和完成标准；上机前写预期和判据，上机后当天写结果和证据位置；结论变化时更新状态表和工作日志；会话结束前写清唯一的下一步、阻塞和设备状态。下一个接手的人或 agent 只看文档就能继续。
- 临时做法必须登记技术债。 为了快速点亮或跑通可以先用临时做法，但每一个都要记进统一的一份技术债表：做了什么、放在哪、为什么需要、影响、去掉的条件。链路跑通后回来集中还债。
- 目录结构固定，一份代码只放一个地方。 内核仓、集成仓公开；私有工作区放记录和内部脚本；本机唯一数据和密码不进任何仓库。
- 每条结论带版本信息。 源码提交、镜像哈希、场景、证据位置。换内核、换系统、换驱动后旧结论要重验。失败记录不删。
- 分清"跑起来了"和"能用了"。 驱动加载、服务运行、节点存在、Fastboot OKAY、模拟器通过都只说明某一层没问题。标准见
references/verification.md。 - 每一步都能退回去。 只读 → 内存启动 → 写分区 → 改 bootloader 状态，风险逐级升高。往上走之前先确认退路可用。A/B 槽状态只用 bootloader 自己的命令改。
- 一次只改一个变量；同样的失败第二次出现就停下来。 从物理层往上找最早出错的层，写下已排除的假设和下一个能证伪的实验。
- 不用全局开关掩盖问题。 关资源回收、屏蔽部分模块、固定延时、无条件重试都会把问题推到更难查的时候。
- 改启动路径必须冷启动验证。 unit、socket、udev、initramfs、启动参数的改动，用冷启动加对照验证，运行中切换不算。
- 设备同一时刻只有一个操作者。 每条命令带 serial；离开 Android 前读电量；对状态不明的设备不发破坏性命令；正式镜像永远保留一条可打开的调试通道。
- 测试尽量全自动，用户参与尽量少。 上机、采集、判定、恢复由脚本完成；截图和输入注入走调试通道自动化。用户只做看、听、按、摆放、插拔这类必须由人做的事，合并成一份清单，提前通知时间，一次做完。能用只读手段测量的不用提问代替。
- 按版本推进。 每个版本先定范围和验收方式，开发、测试、发布、清理之后再继续；不堆积未发布的候选。
- 效率优先。 超过 5 分钟的步骤要计时、找瓶颈、按输入缓存；长期 OUT 加足够大的 ccache；见
references/build-environment.md。
技术选型原则
每个重要选择用同一组问题判断，并记录理由和重新评估的条件。约 40 个关键选型点的默认做法和"遇到什么情况怎么做"的规则，见 references/decisions.md。
- 离上游越近越好：上游 > 在审补丁 > 同 SoC 社区 > 厂商代码 > 自己写。
- 可逆优先：不改 bootloader 状态、不碰原厂关键分区、失败能自动恢复。
- 有真机证据的优先于"声称支持"的；别人的结论在本机验证前只算线索。
- 能复用就整组复用；复用前先比较两边的"地基"（设备树路线、资源管理、安装方式）。
- 自己维护的部分越少越好；不引入通用框架和常驻"管家"服务。
- 硬件层不绑定发行版和桌面，换发行版只换集成层。
- 临时方案可以先用，但要同时开始长期方案并登记技术债。
需要用户决定的事
评估完成后一次性列出，每项给选项、代价和建议，用提问工具确认，确认后写进 AGENTS.md，不再重复问：
- 数据能不能清除，备份哪些分区。
- 单系统还是双系统，是否保留 Android。
- 分区大小（给 2 到 4 个具体方案；Linux 根分区 60 GiB 通常足够，home 放最后方便扩容）。
- 发行版和桌面环境。
- 调试通道默认开还是关，是否预置账户。
- 发布用的账号、仓库名、许可证，原厂固件是否随仓库分发。
- 预计工作量、主要风险、还缺哪些前提条件。
- 用户不在场时可以做哪些操作。
文件索引
| 文件 | 内容 |
|---|---|
references/process.md | 每一步的详细动作、产出、完成标准 |
references/discipline.md | 文档要记什么、技术债、目录结构、署名、估算、子 agent |
references/build-environment.md | 主机、工具链、ccache、OUT、根文件系统构建、缓存、可以省掉的开销 |
references/decisions.md | 约 40 个关键技术决策：默认做法、条件与做法、为什么、不适用的情况 |
references/verification.md | 状态词、证据、冷启动和对照、测试自动化、性能预算 |
references/ubuntu.md | Ubuntu 分层与解耦、包拆分建议、内核包、启动钩子、dracut、snap、GNOME 默认值、换发行版 |
experience/patterns.md | 九类问题模式：怎么认出来、通用处理、常见表现 |
experience/README.md | 经验库的文件列表、条目格式、维护规则 |
experience/*.md | 13 个领域的推荐路线、完成标准和坑 |
维护这份 skill
完成一个项目或解决一个新问题后，把经验写回 experience/ 对应文件（格式见 experience/README.md）。流程或纪律有变化时才改外层。不写设备型号、序列号、个人信息和项目内部代号。