root/goodbuddy

Fork 0

Files

T

mesalogo d773f5e961 chore: upgrade Electron to 44.5.1 and adapt clipboard APIs

2026-10-02 17:53:42 +08:00

9.5 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 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 的 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

脚本会执行以下强制检查：

校验 Electron zip 的固定 SHA-256。
删除 npm 错误解析出的宿主架构可选原生包。
按 lockfile integrity 校验并安装 Koffi LoongArch glibc binding。
读取输入 lockfile 固定的 node-pty 版本，并使用上游 node-gyp 11.4.2 和 Electron 42.3.0 headers 交叉编译。
拒绝 node_modules 中任何不是 LoongArch ELF 的 .node 文件。
拒绝意外进入包内的 Agent、Remote Runtime 或 OpenCode 目录。
生成 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 依赖

仍需真实龙芯桌面验证

安装 DEB 并从桌面入口启动。
验证窗口、渲染、GPU 回退、输入法、系统托盘和通知。
配置模型并执行一次真实的直接模型对话。
验证 Continue Runtime 启动、取消和退出清理。
打开本地终端，验证 node-pty 输入、输出、窗口缩放和进程回收。
验证 Koffi 使用路径。
验证音频、文件选择器、剪贴板和外部链接。
确认 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。

9.5 KiB Raw Blame History Unescape Escape