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 步，输出评估报告和决策清单。

流程

顺序上最容易出错的地方

下面这些顺序错误代价最大，通常一次就是数天：

1. 先看同类项目再设计。 安装方式、切换方式、调试通道、打包结构，同 SoC 或同类设备的项目往往已经有成熟做法和复盘。
2. 先建调试通道和自动恢复，再做任何实验。 默认启动路径在通道建立前不碰外设寄存器。
3. 先取证，后写设备树。 每个数值来自本机原厂证据，不从参考设备抄。
4. 借用固件画面只用于首次点亮。 原生显示接管从第 4 步就开始并行，亮度、熄屏、休眠、外接显示都依赖它。
5. 桌面在内存里能跑就尽快持久化。 不要等外设做全。持久化之后才能做冷启动验证，迭代也更快。
6. 新功能先单独测，再合并。 不要把多个未经真机验证的改动塞进一个候选。
7. 日常迭代在设备上装包。 只在发布时完整构建根文件系统。
8. 发布前按公开文档完整走一遍全新安装。

工作纪律（必须做到）

细节见 references/discipline.md。

1. 必须写文档，并在固定时刻写。 开始功能前写路线和完成标准；上机前写预期和判据，上机后当天写结果和证据位置；结论变化时更新状态表和工作日志；会话结束前写清唯一的下一步、阻塞和设备状态。下一个接手的人或 agent 只看文档就能继续。
2. 临时做法必须登记技术债。 为了快速点亮或跑通可以先用临时做法，但每一个都要记进统一的一份技术债表：做了什么、放在哪、为什么需要、影响、去掉的条件。链路跑通后回来集中还债。
3. 目录结构固定，一份代码只放一个地方。 内核仓、集成仓公开；私有工作区放记录和内部脚本；本机唯一数据和密码不进任何仓库。
4. 每条结论带版本信息。 源码提交、镜像哈希、场景、证据位置。换内核、换系统、换驱动后旧结论要重验。失败记录不删。
5. 分清"跑起来了"和"能用了"。 驱动加载、服务运行、节点存在、Fastboot OKAY、模拟器通过都只说明某一层没问题。标准见 references/verification.md。
6. 每一步都能退回去。 只读 → 内存启动 → 写分区 → 改 bootloader 状态，风险逐级升高。往上走之前先确认退路可用。A/B 槽状态只用 bootloader 自己的命令改。
7. 一次只改一个变量；同样的失败第二次出现就停下来。 从物理层往上找最早出错的层，写下已排除的假设和下一个能证伪的实验。
8. 不用全局开关掩盖问题。 关资源回收、屏蔽部分模块、固定延时、无条件重试都会把问题推到更难查的时候。
9. 改启动路径必须冷启动验证。 unit、socket、udev、initramfs、启动参数的改动，用冷启动加对照验证，运行中切换不算。
10. 设备同一时刻只有一个操作者。 每条命令带 serial；离开 Android 前读电量；对状态不明的设备不发破坏性命令；正式镜像永远保留一条可打开的调试通道。
11. 测试尽量全自动，用户参与尽量少。 上机、采集、判定、恢复由脚本完成；截图和输入注入走调试通道自动化。用户只做看、听、按、摆放、插拔这类必须由人做的事，合并成一份清单，提前通知时间，一次做完。能用只读手段测量的不用提问代替。
12. 按版本推进。 每个版本先定范围和验收方式，开发、测试、发布、清理之后再继续；不堆积未发布的候选。
13. 效率优先。 超过 5 分钟的步骤要计时、找瓶颈、按输入缓存；长期 OUT 加足够大的 ccache；见 references/build-environment.md。

技术选型原则

每个重要选择用同一组问题判断，并记录理由和重新评估的条件。约 40 个关键选型点的默认做法和"遇到什么情况怎么做"的规则，见 references/decisions.md。

• 离上游越近越好：上游 > 在审补丁 > 同 SoC 社区 > 厂商代码 > 自己写。
• 可逆优先：不改 bootloader 状态、不碰原厂关键分区、失败能自动恢复。
• 有真机证据的优先于"声称支持"的；别人的结论在本机验证前只算线索。
• 能复用就整组复用；复用前先比较两边的"地基"（设备树路线、资源管理、安装方式）。
• 自己维护的部分越少越好；不引入通用框架和常驻"管家"服务。
• 硬件层不绑定发行版和桌面，换发行版只换集成层。
• 临时方案可以先用，但要同时开始长期方案并登记技术债。

需要用户决定的事

评估完成后一次性列出，每项给选项、代价和建议，用提问工具确认，确认后写进 AGENTS.md，不再重复问：

1. 数据能不能清除，备份哪些分区。
2. 单系统还是双系统，是否保留 Android。
3. 分区大小（给 2 到 4 个具体方案；Linux 根分区 60 GiB 通常足够，home 放最后方便扩容）。
4. 发行版和桌面环境。
5. 调试通道默认开还是关，是否预置账户。
6. 发布用的账号、仓库名、许可证，原厂固件是否随仓库分发。
7. 预计工作量、主要风险、还缺哪些前提条件。
8. 用户不在场时可以做哪些操作。

文件索引

维护这份 skill

完成一个项目或解决一个新问题后，把经验写回 experience/ 对应文件（格式见 experience/README.md）。流程或纪律有变化时才改外层。不写设备型号、序列号、个人信息和项目内部代号。

android-mainline-port

把主线 Linux 内核和桌面发行版移植到 Android 手机、平板的操作手册与经验库，以 Agent Skill 的形式组织，Claude Code、Codex、Cursor、Gemini CLI 等 AI 编程助手都能直接使用，人也可以直接阅读。English

经验来自三台高通平板从零到公开发布的完整移植（主线内核 6.17 到 7.2，Ubuntu 26.04 + GNOME）。目标只有一个：从头再移植一台设备时，效率最高、少走弯路。

来自这些移植项目

三个项目都在 Android 设备上原生运行 Ubuntu GNOME 桌面，与 Android 双系统共存，不是容器，也不是远程桌面。这份 skill 把三个项目里共同出现、反复出现、花很久才查清的问题，整理成了通用的流程、决策规则和经验条目。

📮 关注与交流

技术长文、经验分享和进展动态在公众号；交流群在小红书，扫码进群交流。

能帮你做什么

• 评估新设备：能不能移植、走哪条路线、要多久、需要你决定哪些事。
• 按流程推进：从立项、构建环境、取证备份、首次启动、点亮桌面、安装到存储、逐个外设，到发布和维护，每一步写清做什么、做到什么程度算完成。
• 做技术决策：约 40 个关键选型点，每个都写了默认做法、"遇到什么情况怎么做"、背后的原因和不适用的情况。
• 排查故障：九类常见问题模式和通用排查步骤，再按领域查具体的坑；日志里的错误码、函数名、配置项可以直接搜索。
• 中途接手：规定了必须写哪些文档、技术债怎么登记，下一个人或 agent 只看文档就能继续。

几条最省时间的经验：

• fastboot boot 返回 OKAY 却一直停在 Fastboot，先查设备树的 msm-id/board-id 是否和 bootloader 期望一致，而不是镜像大小。
• 借用固件画面（simpledrm）只用于首次点亮，原生显示接管要尽早并行开始，亮度、熄屏、休眠、外接显示都依赖它。
• 高通平台休眠默认用 s2idle：远端处理器的消息会把 deep 睡眠完整唤醒，而且不出现在唤醒记录里。
• 睡眠时长只看墙上时间，dmesg 和 journal 的单调时钟在睡眠中会停。
• ccache 按实测约 0.3 GB 一次完整内核构建来配，10 GB 足够，同时设置 base_dir。
• 为了快速跑通而用的临时做法，全部登记进一份统一的技术债表，链路跑通后集中还债。

安装

推荐：npx skills

一条命令装给你在用的所有 AI 编程助手（Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode 等），需要 Node.js 22 或更高版本：

npx skills add yzddmr6/android-mainline-port -g

• -g 装到用户目录，所有项目都能用；不加则只装到当前项目。
• 运行后会让你选择装给哪些助手；也可以直接指定，例如 -a claude-code -a codex。
• 更新：npx skills update android-mainline-port -g；卸载：npx skills remove android-mainline-port -g。

Claude Code 插件

在 Claude Code 会话里输入：

/plugin marketplace add yzddmr6/android-mainline-port
/plugin install android-mainline-port@android-mainline-port

或者在终端里：

claude plugin marketplace add yzddmr6/android-mainline-port
claude plugin install android-mainline-port@android-mainline-port

更新：在 /plugin 的 Marketplaces 页打开自动更新，或手动执行 claude plugin marketplace update android-mainline-port 后再 claude plugin update android-mainline-port@android-mainline-port。

Gemini CLI

gemini skills install https://github.com/yzddmr6/android-mainline-port.git

手动 git clone

把仓库克隆到助手的 skill 目录，目录名必须是 android-mainline-port：

以 Claude Code 为例：

git clone --depth 1 https://github.com/yzddmr6/android-mainline-port ~/.claude/skills/android-mainline-port

更新时在该目录里执行 git pull。不要用 GitHub 的 "Download ZIP"，解压出来的目录名带 -main，和 skill 名不一致，部分助手会不识别。

claude.ai 网页与桌面 App

1. 从 Releases 下载 android-mainline-port.zip。
2. 在 Settings → Capabilities 打开 "Code execution and file creation"。
3. 打开 Customize → Skills，点 "+"，选择上传 skill，选中这个 zip。

让 AI 帮你装

把下面这段话发给你的 AI 编程助手：

请帮我安装这个 Agent Skill：https://github.com/yzddmr6/android-mainline-port
1. 先判断你自己的用户级 skill 目录：Claude Code 是 ~/.claude/skills，Codex、Gemini CLI、Cursor、GitHub Copilot、OpenCode 可用 ~/.agents/skills，或以你自己文档里写的目录为准。
2. 执行 git clone --depth 1 https://github.com/yzddmr6/android-mainline-port <skill目录>/android-mainline-port；如果目录已存在，改为在里面执行 git pull --ff-only。
3. 目录名必须是 android-mainline-port，和 SKILL.md 里的 name 一致。
4. 确认目录里有 SKILL.md、references/、experience/，且 SKILL.md 开头写着 name: android-mainline-port。
5. 不要改动其他 skill 和设置。最后告诉我装在哪里，是否需要重启或重新加载。

确认装好了

• Claude Code：输入 /android-mainline-port（插件方式是 /android-mainline-port:android-mainline-port），能看到这个 skill 即可。
• 其他助手：直接问一句"我想把主线 Linux 移植到一台安卓平板上，先帮我评估"，助手会读取这份 skill 再回答。

使用示例

装好之后不需要特别的命令，像平常一样描述你的情况即可：

• "我有一台骁龙 8 Gen 3 的平板，BL 能解锁，帮我评估能不能跑主线 Linux + Ubuntu，大概要多久。"
• "fastboot boot 返回 OKAY，但屏幕一直停在 Fastboot 界面，pstore 也是空的，帮我排查。"
• "休眠一两秒就被唤醒，帮我查唤醒源。"
• "接手这个移植项目，先读文档，告诉我现在在哪一步、下一步做什么。"

内容结构

• 外层框架：SKILL.md 和 references/。先做什么后做什么、工作纪律、技术选型、构建环境、怎么判断通过、Ubuntu 集成与解耦。相对稳定。
• 经验库：experience/。按领域记录推荐路线、完成标准和具体的坑（现象、原因、怎么确认、怎么解决、怎么预防），随项目持续追加。

SKILL.md                         流程总览、顺序要点、工作纪律、选型原则、用户决策
references/
  process.md                     每一步的详细动作、产出、完成标准
  discipline.md                  文档要记什么、技术债、目录结构、署名、估算、子 agent
  build-environment.md           主机、工具链、ccache、OUT、根文件系统构建、缓存
  decisions.md                   关键技术决策：默认做法、条件与做法、机制、边界
  verification.md                状态词、证据、冷启动、测试自动化、性能预算
  ubuntu.md                      Ubuntu 分层与解耦、包拆分建议、启动钩子、换发行版
experience/
  README.md                      条目格式和维护规则
  patterns.md                    九类问题模式与通用处理
  bootloader-and-boot.md         ABL、启动格式、首次启动、调试通道、恢复
  kernel-and-resources.md        内建与模块、资源回收、PMIC 电压、设备树数值
  display.md                     simpledrm 与原生接管、DSC、熄屏亮屏、背光
  gpu.md                         Adreno、固件、自编 Mesa、新 GPU 的 Mesa 缺陷
  touch-and-input.md             触控（TDDI）、按键、键盘配件、指纹
  audio.md                       AudioReach、功放、麦克风、UCM、音量
  wireless.md                    Wi-Fi、蓝牙
  power-and-time.md              电量、充电、休眠、系统时间
  sensors-camera-media.md        传感器与旋转、相机、视频硬解
  usb-and-storage.md             USB、外接显示、分区、双系统、刷写、安装
  ubuntu-userspace.md            Ubuntu 打包、dracut、snap、GNOME 默认值
  build-and-release.md           构建流水线、缓存、可复现性、发布
  testing-and-process.md         判断标准、自动化测试、协作、子 agent

移植流程分九步：

适用范围与时效

• 高通平台写得最具体；其他 SoC 的流程和纪律相同，硬件细节需要自己调研。
• Ubuntu 相关部分换发行版时按 references/ubuntu.md 最后一节调整。
• 内容基于 2026 年的上游状态。版本号、接口名、上游进度有时效性，使用前请核对；上游已经解决的问题，直接用更简单的办法。
• 正文是中文，各家 AI 都能正常阅读和使用。

⚠️ 风险提示

• 解锁 bootloader 会清空设备数据，可能影响保修；刷写分区操作不当可能导致设备无法启动。
• 动手前按 skill 里的要求完整备份分区并校验，确认有恢复手段。
• 本仓库只提供方法和经验，不提供刷机工具、镜像或固件。内容按"原样"提供，使用风险自负。

贡献

欢迎通过 Issue 和 Pull Request 补充经验：

• 在 experience/ 对应文件里按 experience/README.md 的格式追加条目。
• 只写确认了根因的问题，写清现象、原因、怎么确认、怎么解决、适用范围。
• 不写设备型号、序列号、地址、校准数据、个人信息；芯片型号、驱动名、错误码可以写，它们是搜索关键字。

许可

MIT