253 lines
9.5 KiB
Markdown
253 lines
9.5 KiB
Markdown
# GoodBuddy 龙芯（LoongArch）预览版构建
|
||
|
||
本文档是 GoodBuddy 龙芯预览版的权威构建与功能状态说明。当前目标是
|
||
Debian `loong64` 桌面，不代表 GoodBuddy 已将龙芯纳入正式发布支持矩阵。
|
||
|
||
## 当前状态
|
||
|
||
当前流程可以在 AMD64 Linux 主机上交叉构建一个独立的
|
||
`goodbuddy-loongarch-preview` DEB，并校验包内 Electron、node-pty 和 Koffi
|
||
均为 LoongArch ELF。
|
||
|
||
预览版使用社区维护的 Electron 42.3.0 LoongArch 构建。GoodBuddy 正式版本
|
||
当前使用 Electron 44.5.1，因此该预览包只用于移植和真机验证，不能作为正式
|
||
发布基线。Electron 官方目前也不提供 Linux LoongArch 预编译包。
|
||
|
||
已完成的实际构建结果：
|
||
|
||
| 项目 | 结果 |
|
||
| --- | --- |
|
||
| GoodBuddy 源版本 | `0.11.0` |
|
||
| 预览版本 | `0.11.0-loong64-preview.1` |
|
||
| Debian 架构 | `loong64` |
|
||
| Electron | 社区版 `42.3.0` |
|
||
| DEB 包名 | `goodbuddy-loongarch-preview` |
|
||
| 构建产物 | `GoodBuddy-0.11.0-linux-loong64-preview.deb` |
|
||
| 已验证构建时间（UTC） | `20260825T102937Z` |
|
||
| 已验证产物大小 | `187053208` bytes |
|
||
| 已验证产物 SHA-256 | `461ade49f10a20ef7b28163077a2ecd6afd2c5b1b0befc673c6d174fd58497b3` |
|
||
| DEB 解包、架构和动态库解析 | 已通过 |
|
||
| QEMU Electron 初始化 | 共享库解析通过；Chromium 多线程初始化在 QEMU 下异常退出 |
|
||
| 龙芯真机启动 | 尚未验证 |
|
||
|
||
版本号和产物名会跟随当前 `package.json` 版本变化，上表只记录首次成功构建。
|
||
|
||
## 功能列表
|
||
|
||
“已打包”只表示所需代码或组件进入 DEB，不等同于已在龙芯桌面完成运行验证。
|
||
|
||
| 功能 | 预览包状态 | 当前验证 |
|
||
| --- | --- | --- |
|
||
| GoodBuddy Electron 桌面主体 | 已打包 | Electron 可执行文件为 LoongArch ELF；尚未完成真机 GUI 启动 |
|
||
| React 界面和主进程业务代码 | 已打包 | 生产 bundle 构建、测试、类型检查和 lint 已通过 |
|
||
| 直接模型调用路径 | 已打包 | JavaScript 代码与生产依赖已包含；待龙芯真机端到端验证 |
|
||
| Continue Runtime | 已打包 | CLI JavaScript 入口及 npm Runtime 已包含；待真机执行验证 |
|
||
| 本地终端能力 | 已打包 | 输入锁文件固定的 node-pty（当前为 1.2.0-beta.15）已针对 Electron 42.3.0 交叉编译并验证为 LoongArch ELF；待真机 PTY 验证 |
|
||
| Koffi glibc 原生绑定 | 已打包 | Koffi 3.1.4 LoongArch glibc binding 已校验为 LoongArch ELF |
|
||
| 内置 Skills | 已打包 | 静态资源已进入 DEB |
|
||
| GoodBuddy Agent | **不包含** | 当前 Agent 的正式构建和双 glibc/musl 产物契约不支持 LoongArch |
|
||
| Remote Runtime | **不包含** | 当前没有 LoongArch Remote Runtime 产物 |
|
||
| OpenCode Runtime | **不包含** | OpenCode 所需 Bun Runtime 当前不支持 LoongArch |
|
||
| 原生 Canvas 图像解码 | **不包含** | npm 当前没有 `@napi-rs/canvas-linux-loong64-gnu` 包 |
|
||
| Koffi musl binding | **不包含** | Koffi 3.1.4 只发布了 `linux_loong64` glibc binding |
|
||
| 正式自动更新和发布索引 | **不支持** | 预览包不加入正式 CI、安装包矩阵或更新索引 |
|
||
|
||
在真机验证完成前，不应把“已打包”功能描述为正式可用。尤其是窗口显示、GPU、
|
||
音频、系统托盘、桌面集成、PTY 交互和模型调用都必须在真实 LoongArch 桌面上
|
||
重新验证。
|
||
|
||
## 与正式 GoodBuddy 隔离
|
||
|
||
预览版有意使用单独身份，避免覆盖正式安装：
|
||
|
||
- Debian 包名：`goodbuddy-loongarch-preview`
|
||
- 产品名：`GoodBuddy LoongArch Preview`
|
||
- 可执行文件：`goodbuddy-loongarch-preview`
|
||
- 安装目录：`/opt/GoodBuddy-LoongArch-Preview`
|
||
- Electron 应用身份与正式 GoodBuddy 不同，因此使用单独的用户数据目录
|
||
|
||
该流程不会修改 `.github/workflows/packages.yml`，也不会把 `loong64` 加入
|
||
正式 release manifest 或下载索引。
|
||
|
||
## 构建前提
|
||
|
||
### 本地源码主机
|
||
|
||
- 已完成 `npm ci`
|
||
- Node.js 和 npm 版本满足仓库要求
|
||
- 可以成功执行 `npm run build:bundle`
|
||
|
||
### AMD64 交叉构建主机
|
||
|
||
- Linux AMD64
|
||
- Docker
|
||
- 建议至少 30 GiB 内存和 50 GiB 可用磁盘
|
||
- 可访问 Ubuntu、npm、Electron headers 和社区 Electron Release
|
||
|
||
### Electron LoongArch shell
|
||
|
||
从
|
||
[`darkyzhou/electron-loong64`](https://github.com/darkyzhou/electron-loong64)
|
||
的 Releases 下载：
|
||
|
||
```text
|
||
electron-v42.3.0-linux-loong64.zip
|
||
```
|
||
|
||
构建脚本固定校验以下 SHA-256，摘要不匹配时必须停止：
|
||
|
||
```text
|
||
92b0ca0c9c18ed90166918a4ac1970266c4fa967aee9277031b3b250b905526e
|
||
```
|
||
|
||
这是社区产物，不是 Electron 官方发布的 Linux LoongArch 二进制。
|
||
|
||
## 第一步：生成架构无关输入
|
||
|
||
在 GoodBuddy 仓库根目录执行：
|
||
|
||
```sh
|
||
npm ci
|
||
npm run build:bundle
|
||
node build/loongarch-cross/prepare-input.cjs
|
||
```
|
||
|
||
默认输出：
|
||
|
||
```text
|
||
dist/loongarch-cross/goodbuddy-loongarch-cross-input.tgz
|
||
```
|
||
|
||
输入归档包含生产 `out`、锁文件、Skills、Continue Runtime、npm Runtime、
|
||
图标和发布元数据。它不包含 Agent、Remote Runtime 或 OpenCode 二进制。
|
||
|
||
可通过 `--output` 指定其他输出位置：
|
||
|
||
```sh
|
||
node build/loongarch-cross/prepare-input.cjs \
|
||
--output /path/to/goodbuddy-loongarch-cross-input.tgz
|
||
```
|
||
|
||
## 第二步：构建交叉工具链镜像
|
||
|
||
将 `build/loongarch-cross`、输入归档和 Electron zip 放到 AMD64 Docker
|
||
主机，然后执行：
|
||
|
||
```sh
|
||
docker build \
|
||
--tag goodbuddy-loongarch-cross:ubuntu-26.04 \
|
||
build/loongarch-cross
|
||
```
|
||
|
||
工具链镜像包括：
|
||
|
||
- `loongarch64-linux-gnu-gcc` 和 G++
|
||
- LoongArch glibc 开发 sysroot
|
||
- QEMU user mode
|
||
- CMake 和 Ninja
|
||
- Rust `loongarch64-unknown-linux-gnu` target
|
||
- Node.js、npm 和上游 node-gyp
|
||
|
||
可先运行基础探针：
|
||
|
||
```sh
|
||
mkdir -p build/loongarch-cross/results
|
||
docker run --rm \
|
||
--volume "$PWD/build/loongarch-cross/results:/results" \
|
||
goodbuddy-loongarch-cross:ubuntu-26.04
|
||
```
|
||
|
||
探针必须通过 C、C++、CMake、Rust、NAPI-RS、QEMU、DEB、Koffi 和
|
||
node-pty 检查。Canvas 和 Koffi musl 显示为 unavailable 是当前已知限制，
|
||
不是 Debian 桌面主体 DEB 的构建失败。
|
||
|
||
## 第三步：生成预览 DEB
|
||
|
||
假设交叉构建主机上的文件布局如下：
|
||
|
||
```text
|
||
input/goodbuddy-loongarch-cross-input.tgz
|
||
electron/electron-v42.3.0-linux-loong64.zip
|
||
preview-output/
|
||
```
|
||
|
||
运行：
|
||
|
||
```sh
|
||
docker run --rm \
|
||
--entrypoint /usr/local/bin/goodbuddy-loongarch-preview-deb \
|
||
--volume "$PWD/input:/input:ro" \
|
||
--volume "$PWD/electron:/electron:ro" \
|
||
--volume "$PWD/preview-output:/preview-output" \
|
||
goodbuddy-loongarch-cross:ubuntu-26.04 \
|
||
/input/goodbuddy-loongarch-cross-input.tgz \
|
||
/electron/electron-v42.3.0-linux-loong64.zip \
|
||
/preview-output
|
||
```
|
||
|
||
每次构建创建一个 UTC 时间戳目录，包含：
|
||
|
||
```text
|
||
GoodBuddy-<version>-linux-loong64-preview.deb
|
||
preview-manifest.json
|
||
SHA256SUMS
|
||
```
|
||
|
||
脚本会执行以下强制检查：
|
||
|
||
1. 校验 Electron zip 的固定 SHA-256。
|
||
2. 删除 npm 错误解析出的宿主架构可选原生包。
|
||
3. 按 lockfile integrity 校验并安装 Koffi LoongArch glibc binding。
|
||
4. 读取输入 lockfile 固定的 node-pty 版本，并使用上游 node-gyp 11.4.2
|
||
和 Electron 42.3.0 headers 交叉编译。
|
||
5. 拒绝 `node_modules` 中任何不是 LoongArch ELF 的 `.node` 文件。
|
||
6. 拒绝意外进入包内的 Agent、Remote Runtime 或 OpenCode 目录。
|
||
7. 生成 `Architecture: loong64` 的 DEB，解包后再次校验关键 ELF。
|
||
|
||
Ubuntu 发行版自带的 node-gyp 会在 Linux addon 链接阶段无条件添加
|
||
`-lnode`，不适合此 Electron 交叉编译；不要用它替换脚本固定的上游
|
||
node-gyp。
|
||
|
||
## 验证边界
|
||
|
||
### 已由交叉构建验证
|
||
|
||
- C、C++、CMake 和 Rust 生成 LoongArch ELF
|
||
- C、C++ 和 Rust 程序通过 QEMU user mode 执行
|
||
- 最小 NAPI-RS addon 交叉编译
|
||
- node-pty 针对 Electron headers 交叉编译
|
||
- Koffi LoongArch glibc binding 架构
|
||
- Electron、node-pty、Koffi 和 DEB `loong64` 元数据
|
||
- DEB 完整解包
|
||
- Debian Forky rootfs 中 Electron 全部共享库解析；该检查发现并补充了
|
||
`libpulse0` DEB 依赖
|
||
|
||
### 仍需真实龙芯桌面验证
|
||
|
||
1. 安装 DEB 并从桌面入口启动。
|
||
2. 验证窗口、渲染、GPU 回退、输入法、系统托盘和通知。
|
||
3. 配置模型并执行一次真实的直接模型对话。
|
||
4. 验证 Continue Runtime 启动、取消和退出清理。
|
||
5. 打开本地终端，验证 node-pty 输入、输出、窗口缩放和进程回收。
|
||
6. 验证 Koffi 使用路径。
|
||
7. 验证音频、文件选择器、剪贴板和外部链接。
|
||
8. 确认 Agent、Remote Runtime、OpenCode 和 Canvas 相关入口不会被误认为
|
||
预览版已支持。
|
||
|
||
QEMU 可以补充动态链接器和缺库检查，但不能替代上述 GUI、PTY、GPU、音频和
|
||
桌面集成真机测试。当前 Electron 在 QEMU user mode 下可以完成全部共享库
|
||
解析；继续进入 Chromium 多线程初始化后，QEMU 出现 target `SIGSEGV`，因此
|
||
不能用该结果判断真机 Electron 是否可以启动。
|
||
|
||
## 已知依赖问题
|
||
|
||
- npm 的 `--cpu=loong64 --os=linux` 仍可能安装宿主 x64 的 Koffi 可选包。
|
||
打包脚本会删除所有该作用域的已解析原生包，并按 lockfile integrity 手工
|
||
安装 LoongArch 包。
|
||
- `@napi-rs/canvas` 没有发布 LoongArch 原生包。基础 NAPI-RS 探针通过只说明
|
||
Rust addon 工具链可用，不代表 Skia/Canvas 已完成移植。
|
||
- Koffi 没有 LoongArch musl binding，因此当前不能满足 GoodBuddy Agent 的
|
||
双 glibc/musl 产物契约。
|
||
- 预览 Electron 比正式 GoodBuddy 低一个主版本。正式支持必须先获得与当前
|
||
Electron 基线一致、可重复构建并完成安全维护的 LoongArch shell。
|