root/goodbuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da00a850ec8ef5686f7d2531779d68867e262d54
goodbuddy/docs/development/loongarch-preview-build.md
T
mesalogo 500f7d2735 feat: add experimental LoongArch desktop preview 
GoodBuddy can now be cross-packaged as an isolated Debian loong64 preview with verified Electron, node-pty, and Koffi binaries. The preview remains separate from the standard release matrix and excludes Agent, Remote Runtime, OpenCode, and native Canvas until those dependencies support LoongArch.

The Chinese website identifies GoodBuddy as the first open-source desktop AI assistant with LoongArch support while clearly labeling the independently built package as a preview.

Release note: 新增龙芯 LoongArch 独立编译预览版，并提供完整构建文档；当前预览版不包含 Agent、Remote Runtime、OpenCode 和原生 Canvas。
2026-08-25 18:41:35 +08:00

9.4 KiB
Raw Blame History

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 43.2.0，因此该预览包只用于移植和真机验证，不能作为正式 发布基线。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.1.0 已针对 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 的 Releases 下载：

electron-v42.3.0-linux-loong64.zip

构建脚本固定校验以下 SHA-256，摘要不匹配时必须停止：

92b0ca0c9c18ed90166918a4ac1970266c4fa967aee9277031b3b250b905526e

这是社区产物，不是 Electron 官方发布的 Linux LoongArch 二进制。

第一步：生成架构无关输入

在 GoodBuddy 仓库根目录执行：

npm ci
npm run build:bundle
node build/loongarch-cross/prepare-input.cjs

默认输出：

dist/loongarch-cross/goodbuddy-loongarch-cross-input.tgz

输入归档包含生产 out、锁文件、Skills、Continue Runtime、npm Runtime、 图标和发布元数据。它不包含 Agent、Remote Runtime 或 OpenCode 二进制。

可通过 --output 指定其他输出位置：

node build/loongarch-cross/prepare-input.cjs \
  --output /path/to/goodbuddy-loongarch-cross-input.tgz

第二步：构建交叉工具链镜像

将 build/loongarch-cross、输入归档和 Electron zip 放到 AMD64 Docker 主机，然后执行：

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

可先运行基础探针：

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

假设交叉构建主机上的文件布局如下：

input/goodbuddy-loongarch-cross-input.tgz
electron/electron-v42.3.0-linux-loong64.zip
preview-output/

运行：

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 时间戳目录，包含：

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. 使用上游 node-gyp 11.4.2 和 Electron 42.3.0 headers 交叉编译 node-pty。
  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。
Reference in New Issue View Git Blame Copy Permalink