根据官方文档操作，远没有想象中简单......

一、 编译环境与底层依赖的标准化准备

在执行任何源码拉取动作之前，操作系统的底层环境配置是决定后续编译链是否稳定的基础。OpenHarmony 庞大的源码树对文件系统与构建工具有着严格的要求。

1. 基础编译工具链配置 推荐使用 Ubuntu 22.04 LTS 版本。必须确保安装完整的编译工具链，特别是 git-lfs（用于拉取音视频等大文件测试用例）以及 ccache（用于缓存编译中间产物，二次编译时可大幅缩减时间）。 同时，针对打包流程，必须手动安装并配置 make_ext4fs 工具，否则在最终生成镜像（Image）阶段，即使源码编译通过，也会因为无法构建 EXT4 文件系统而前功尽弃。

2. 鉴权机制配置（SSH 与 Token） 由于 OpenHarmony 源码托管在如意社区，部分核心组件或特定驱动仓库实施了严格的访问权限控制（ACL）。开发者必须在本地环境中完成双重鉴权配置：

• SSH 公钥：用于基础代码的无密码高速克隆。

• 个人访问令牌（Token）：需要将其写入本地系统的 .git-credentials 中，以应对 HTTPS 协议下的特定仓库访问请求。缺乏此配置将导致同步流程直接被权限错误阻塞。

---

二、 源码同步阶段的存储库解析异常与 Manifest 干预

在执行 repo sync 同步 OpenHarmony 源码树时，终端常常在特定存储库处停滞，并抛出终止错误。

2.1 报错日志分析：fatal: 不是 git 仓库

GitCommandError: 'pack-refs --all --prune' on kernel_liteos_a failed
stderr: fatal: 不是 git 仓库：'/home/xxx/WorkSpace/oh61/.repo/projects/kernel/liteos_a.git'

底层机理与原因定位： 该错误并非表明远程端不存在该仓库，而是由网络传输超时与 repo 工具的本地文件处理机制冲突导致的。kernel_liteos_a 作为一个体积较大的内核组件，在下载过程中若发生网络协议层面的断流，repo 工具的容错机制会在本地文件系统中遗留一个缺失 .git 核心数据结构的空目录。 当同步流程进入尾声，repo 试图遍历所有组件执行常规的 Git 引用压缩（pack-refs 操作以优化存储空间）时，底层的 git 二进制程序无法识别该空目录的文件树结构，从而向上层抛出致命异常（Fatal Error），强制终止整个工作区的同步进程。

此外，从系统硬件架构评估，MUSE Pi V30 开发板基于 RISC-V 架构，其目标系统底层运行的是标准的 Linux 内核（linux-6.6）。LiteOS-A 作为一个主要面向轻量级物联网设备（如智能手表、旧式摄像头）的微内核，在当前 RISC-V 桌面/平板级系统的编译链路中属于绝对的冗余组件。

2.2 解决方案：Local Manifest 清单重写机制

为了避免无意义的网络重试和编译链污染，必须利用 repo 工具的本地清单（local_manifests）机制，在本地 XML 解析层面直接移除该组件的同步节点配置：

# 清除本地文件系统中已损坏的空目录及缓存数据
rm -rf kernel/liteos_a .repo/projects/kernel/liteos_a.git .repo/project-objects/kernel/liteos_a.git .repo/worktrees/kernel/liteos_a.git

# 构建本地清单目录并写入基于 XML 的排除规则
mkdir -p .repo/local_manifests
cat <<EOF > .repo/local_manifests/remove_liteos.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <remove-project name="kernel_liteos_a" />
</manifest>
EOF

# 启用 fail-fast 参数重试同步
repo sync -j4 -c --fail-fast

---

三、 服务器鉴权失败导致的同步拒绝与强制剔除

在清理了失效内核组件后，源码同步进程依然可能在业务组件模块被强制中断。

3.1 报错日志分析：Terminal prompts disabled

fatal: could not read Username for 'https://code.ruyicommunity.cn': terminal prompts disabled
git requires authentication, but repo cannot perform interactive authentication.
Unable to remote fetch project useriam_companion_device_auth

底层机理与原因定位： 此类报错直接指向远端代码托管服务器（如意社区）针对特定组件（如 useriam_companion_device_auth 或 game_controller_framework）实施的读取权限限制。 在自动化批量拉取场景下，repo 工具以非交互式模式运行。一旦服务器端由于权限策略变更或临时的 Token 校验接口故障而拒绝访问请求，Git 客户端会尝试回退至终端交互式密码输入。但由于非交互模式（terminal prompts disabled）的限制，进程无法获取输入，最终抛出 authentication required 错误并终止整个工程树的拉取。

3.2 解决方案：强制跳过非关键路径组件

针对当前处于评估和移植阶段的开发板，上述权限受限模块（游戏手柄框架、外围设备认证鉴权等）并不属于系统启动（Boot）的核心关键路径。必须通过扩充 local_manifests 清单，使用 <remove-project> 标签批量剔除这些由于服务器鉴权失败而阻塞进程的组件。

注意：在此步骤解压或应用清单补丁文件（如 skip_inaccessible.xml）时，必须确保 .xml 文件物理存储于 .repo/local_manifests/ 绝对路径下，而非 .repo/ 根目录，否则 repo 清单解析器将忽略该规则文件。

---

四、 构建系统架构深度解析：级联失败与 SDK 依赖冲突

源码拉取完成且执行预编译工具链下载脚本后，进入实质性的代码编译阶段。执行标准的构建命令： ./build.sh --product-name pico --ccache --prebuilt-sdk

4.1 报错日志分析：[LOAD] Exception

[OHOS ERROR] [LOAD] Exception: find component game_controller_framework failed, please check it in .../parts.json.
...
[OHOS ERROR] exceptions.ohos_exception.OHOSException: product pico@None not found

底层机理与原因定位（构建流程解析）： 理解此报错需要深入 OpenHarmony 构建工具 hb 的运行架构。OpenHarmony 的编译流程严格划分为四个阶段：Preloader -> Loader -> GN -> Ninja。

1. Preloader 阶段：解析全局编译配置并生成系统级的构建属性文件。

2. Loader 阶段：读取各个子系统的依赖树配置（如 parts.json），对各个代码模块的依赖关系进行合法性与完整性校验。

本次执行的构建指令中包含了 --prebuilt-sdk 参数。该参数强制 hb 系统优先唤起 OpenHarmony 官方 SDK 的全量构建流程。官方 SDK 作为一个通用开发套件，其构建清单中硬编码了对 game_controller_framework 等组件的依赖。 由于在第三阶段的源码同步中，我们通过 Manifest 排除了该框架仓库，导致 Loader 阶段的依赖树扫描在此处断裂。系统立即抛出 Exception 并终止主线程执行。 由于进程非正常退出，其后续负责解析 --product-name pico 参数及生成产品特定配置的代码段被直接跳过，从而产生了一个存在严重误导性的空指针异常衍生日志：product pico@None not found。

4.2 解决方案：解耦构建目标

为了打破这一死锁，必须明确当前的工程目标为“构建底层硬件固件镜像”而非“编译上层应用开发 SDK”。通过调整参数，跳过前置的 SDK 编译及其依赖校验阶段，直接驱动 GN 进入特定产品线的图纸生成阶段：

./build.sh --product-name pico --ccache --no-prebuilt-sdk

---

五、 板级支持包（BSP）隔离机制与私有化构建适配

排除了 SDK 干扰后，终端的唯一报错精简为： product pico@None not found。检查 out 目录发现其仅包含极少数初始化日志文件，证明构建流程未能真正开始。

5.1 底层机理与原因定位：

此问题暴露了 AOSP 及 OpenHarmony 生态中典型的主线代码与私有板级支持包（BSP）的代码隔离策略。 官方维护的 Manifest 清单（如 OpenHarmony-v6.1-Release）中，通常仅包含公版参考设计或标准评估板（如 deb1, musepaper）的配置信息。MUSE Pi V30（代号 pico）作为一个特定的定制硬件，其硬件抽象层驱动（Vendor 目录）和具体的板卡硬件引脚及设备树配置（Device 目录）通常存放于芯片原厂或主板厂商维护的私有 Git 仓库中。 因为常规的 repo sync 无法拉取未在主线清单中声明的私有仓库，导致本地文件系统 vendor/spacemit/ 路径下缺乏目标开发板的目录结构与 config.json 产品配置文件。hb 工具在扫描 vendor 目录进行产品名称匹配时返回空集，抛出目标不存在异常。

5.2 解决方案：闭环私有代码树

1. 参数核实：与硬件移植团队核对确认该设备确切的终端编译代号（确保 --product-name 参数的值准确无误）。

2. 获取源码地址：获取板级支持包私有库的 Git 访问 URL，并手动将其克隆并映射至工程结构的指定层级中：

   git clone <私有仓库地址_vendor> vendor/spacemit/<board_name>
   git clone <私有仓库地址_device> device/board/spacemit/<board_name>
   

---

六、 全流程标准化验证与后续操作

在彻底解决了内核仓库空置、权限组件剔除、构建依赖解耦以及私有 BSP 代码注入等一系列问题后，RISC-V 开发板的标准化编译工作流应如下执行：

# 1. 环境准备与私有代码就位 (假定 repo sync 主线已通过清单干预完成)
repo forall -c 'git lfs pull'
bash build/prebuilts_download.sh

# 2. 覆盖并修复架构特定的交叉编译工具链
repo sync toolchains_llvm_riscv
repo sync spacemit-riscv-gcc

# 3. 启动闭环系统的全量编译 (禁用 SDK 预编译以加快速度并规避依赖冲突)
./build.sh --product-name <board_name> --ccache --no-prebuilt-sdk

当 Ninja 编译器的并发任务全部完成，终端将输出 =====build <board_name> successful=====。此时，系统镜像文件将被打包至 out/<board_name>/packages/phone/images/ 目录下。随后，开发者即可通过 TitanFlasher 专用烧录工具，或通过组合键进入 Fastboot 模式结合 HDC 命令完成固件烧录。

深入理解错误日志背后的构建系统运行逻辑，区分公有库与私有库的代码分布界限，是提升底层操作系统移植效率的关键所在。