企业官网建设流程全解析

如何从源码编译 OpenHuman 桌面应用：配置 Rust 工具链、pnpm 与 Tauri 子模块

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

OpenHuman 的桌面应用由三部分组成：仓库根目录的 Rust crate（包名openhuman，二进制openhuman-core）、app/下的 React 前端，以及app/src-tauri/的 Tauri v2 外壳（Rust 包OpenHuman，进程内嵌入 core 的 JSON-RPC 服务）。如果你要从源码编译出可运行的桌面应用，需要依次完成三件事：装好仓库钉住的 Rust 工具链、安装 pnpm 工作区依赖、初始化仓库的 vendor 子模块。本文的主路径基于 gitbooks/developing/getting-set-up.md，包级依赖和验证命令补充自 gitbooks/developing/building-rust-core.md，最终目标是pnpm build产出桌面应用构建物，或用pnpm dev:app启动开发态桌面壳。

准备条件：工具链与系统包

文档列出的源码构建前置条件：

• git
• Node.js 24 或更新（app/package.json 的engines字段要求>=24.0.0）
• pnpm@10.10.0（由根 package.json 的packageManager字段钉住）
• 通过rustup安装 Rust，并带rustfmt和clippy组件
• CMake，native Rust 依赖编译时需要
• 仓库 vendor 子模块（后文说明）
• 平台桌面构建工具：macOS 为 Xcode Command Line Tools，Linux 为 Tauri 所需的 GTK/WebKit/AppIndicator 包

关于 Rust 版本有一处需要说明的出入：getting-set-up 文档的 quick start 命令写的是1.93.0，而仓库里的 rust-toolchain.toml 当前钉的是channel = "1.96.1"（components = ["rustfmt", "clippy"]，profile = "minimal"），文件内注释解释了原因：rusqlite 0.40 / libsqlite3-sys 0.38的构建脚本使用了 1.96 才稳定的cfg_select!宏。cargo会自动读取rust-toolchain.toml并通过rustup拉取对应工具链，所以以该文件内容为准，文档命令中的版本号按文档原样保留，两者不一致属于文档滞后。

macOS（Homebrew）quick start，来自文档：

brew install node@24 pnpm rustup-init cmake rustup toolchain install 1.93.0 --profile minimal rustup component add rustfmt clippy --toolchain 1.93.0

macOS 上还需要安装 Xcode Command Line Tools（xcode-select --install），因为whisper-rs在构建期编译 native 代码，且该 crate 在 Cargo.toml 中以metalfeature 构建，需要 Apple 工具链和 SDK 头文件。

Linux 桌面壳需要比 core-only 更宽的依赖集（镜像自 CI 的build-desktop.yml，来自 building-rust-core 文档）：

# Ubuntu / Debian sudo apt-get update sudo apt-get install -y \ libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \ patchelf cmake libasound2-dev libxdo-dev libxtst-dev libx11-dev libxi-dev \ libevdev-dev libssl-dev libclang-dev \ libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \ libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \ libgbm1 libpango-1.0-0 libcairo2 libatspi2.0-0 libxshmfence1 libu2f-udev

Arch Linux 的 quick start（同一文档）：

sudo pacman -S --needed nodejs npm rustup cmake base-devel clang openssl \ alsa-lib xdotool libxtst libxi libevdev gtk3 webkit2gtk-4.1 \ libayatana-appindicator librsvg patchelf nss nspr at-spi2-core \ libcups libdrm libxkbcommon libxcomposite libxdamage libxfixes \ libxrandr mesa pango cairo libxshmfence npm install -g pnpm@10.10.0 rustup toolchain install 1.93.0 --profile minimal rustup component add rustfmt clippy --toolchain 1.93.0

Windows 上文档给出的核心 crate 前置是 Visual Studio Build Tools 2022（含 "Desktop development with C++" 工作负载）加rustup target add x86_64-pc-windows-msvc，并且必须用 MSVC 工具链而不是 MinGW（仓库对whisper-rs-sys打了静态 CRT 补丁以避免LNK2038/LNK1169冲突）。文档中桌面源码构建的完整路径以 macOS/Linux 为主，Windows 开发入口是下文的dev:app:win。

拉取代码并初始化子模块

在仓库根目录执行。克隆 openhuman 仓库并进入后：

# 1) 进入 openhuman 仓库根目录（需先克隆仓库） cd openhuman # 2) 拉取 vendored 源码 git submodule update --init --recursive # 3) 安装 JS 依赖（workspace 级别） pnpm install # 4) 构建桌面应用构建物 pnpm build

子模块的作用：getting-set-up 文档说明桌面壳（以及 vendored CEF-aware Tauri CLI）依赖仓库内的 vendor 子模块。本仓库的.gitmodules声明的是一组位于根目录vendor/下的 tiny* 仓库（tinyagents、tinyflows、tinychannels、tinymemory等十余个）。git submodule update --init --recursive会把.gitmodules中声明的目录全部填充到钉住的提交上；只做根 crate 的纯 core 构建时这一步不是必须的，但桌面壳构建必须执行。

安装依赖与构建命令

pnpm install在 workspace 根执行。根 package.json 的packageManager字段把版本钉在pnpm@10.10.0，resolutions固定了@tauri-apps/api到2.11.1；根目录还注册了@assistant-ui/react-lexical@0.2.10的本地 patch（app/patches/@assistant-ui__react-lexical@0.2.10.patch），安装时会自动应用。

构建与开发命令（均在 workspace 根目录运行）：

# 生产构建：根脚本 pnpm build 转发到 openhuman-app 子包， # 子包内执行 scripts/build-parallel.mjs 产出桌面应用构建物 pnpm build # 开发态：仅 Web UI（Vite，dev server 端口 1420） pnpm dev # 开发态：桌面壳（vendored Tauri CLI） pnpm --filter openhuman-app dev:app

几点与脚本定义一致的说明：

• pnpm build对应根脚本"build": "pnpm --filter openhuman-app build"，而 app/package.json 中该子包的build是node scripts/build-parallel.mjs。
• dev:app在 app/package.json 中定义为bash ../scripts/run-dev-macos.sh，即 macOS 桌面开发入口；Windows 对应dev:app:win（"C:/Program Files/Git/bin/bash.exe" ../scripts/run-dev-win.sh），纯 Web 开发用pnpm dev。
• 桌面壳把 core 以进程内 tokio task 方式嵌入，不再需要预置 sidecar：core:stage脚本是有意保留的 no-op（PR #1061），本地构建不需要app/src-tauri/binaries/下的openhuman-core-*。

验证编译结果

Rust 侧（来自 building-rust-core 文档，命令在仓库根目录执行）：

# 快速依赖 + 类型检查 cargo check --manifest-path Cargo.toml # 调试版 openhuman-core 二进制 cargo build --manifest-path Cargo.toml --bin openhuman-core # Release 版 cargo build --manifest-path Cargo.toml --release --bin openhuman-core # Rust 测试 cargo test --manifest-path Cargo.toml

产物位置是固定判断点：构建成功的二进制位于target/debug/openhuman-core或target/release/openhuman-core。注意包名是openhuman，可执行二进制名是openhuman-core，二者不同。

桌面壳侧：pnpm dev启动后 Vite dev server 监听 1420 端口，可在浏览器验证前端；pnpm --filter openhuman-app dev:app应弹出桌面窗口，窗口出现即说明 Tauri 壳与前端加载成功。

ARM Linux（aarch64）构建是文档给出的独立分支，需要额外安装xvfb（sudo apt install xvfb，用于无头构建/测试），然后在app/目录执行：

cd app pnpm tauri build --target aarch64-unknown-linux-gnu

产出的二进制需要手动设置 CEF 库路径才能启动：

REL_DIR=app/src-tauri/target/aarch64-unknown-linux-gnu/release CEF_DIR=$(ls -d "$REL_DIR"/build/cef-dll-sys-*/out/cef_linux_aarch64 2>/dev/null | head -n1) export LD_LIBRARY_PATH="$CEF_DIR:$REL_DIR/deps:$REL_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" "$REL_DIR/OpenHuman" --no-sandbox

若要安装 DEB 包：

DEB_FILE=$(ls app/src-tauri/target/aarch64-unknown-linux-gnu/release/bundle/deb/OpenHuman_*_arm64.deb | head -n1) sudo dpkg -i "$DEB_FILE"

文档同时提醒：ARM 构建要求 GTK 在 Tauri 创建系统托盘前完成初始化，修复位于vendor/tauri-cef/crates/tauri-runtime-cef/src/lib.rs；如果托盘报 "GTK has not been initialized"，确认该修复在位后重新构建。

常见问题排查

macOS 上pnpm dev:app直接退出，提示 "CEF cache is held by another OpenHuman instance"

症状是调试构建在窗口出现前退出，报错指向~/Library/Caches/com.openhuman.app/cef。原因是 CEF 通过SingletonLock对 user-data 目录持有独占锁，已安装的.app和开发二进制共用同一个com.openhuman.app标识符，无法并行运行。文档给出的处理（pkill会终止本机匹配的 OpenHuman 进程，仅在确实需要清理残留进程时使用）：

pkill -f "OpenHuman.app/Contents" pkill -f "openhuman-core" pnpm dev:app

如果锁是崩溃进程留下的（PID 已不存在），preflight 会自动删除过期的SingletonLock，无需手工清理。文档标注的已知限制：dev 与 release 构建仍共享同一个缓存标识符，隔离需要改动 vendoredtauri-runtime-cef。

旧 core 进程占用核心 RPC 端口

之前的 Tauri 构建或openhuman-core run可能留下监听OPENHUMAN_CORE_PORT（默认7788）的进程。当前行为（issue #1130）：core_process::ensure_running启动时探测该端口，如果GET /返回的 JSON 含"name": "openhuman"，判定为上次运行的残留并主动终止（Unix 下SIGTERM，750ms 后升级SIGKILL；Windows 下taskkill /F /T /PID），然后启动新的内嵌 core；如果监听者不是 OpenHuman core，启动会显式失败并在日志中给出冲突，而不是静默挂载。手工清理仍然可用：

pkill -f "OpenHuman.app/Contents" pkill -f "openhuman-core"

设置OPENHUMAN_CORE_REUSE_EXISTING=1可回到"挂载已有监听者"的旧行为，文档说明这对用openhuman-core run做手工调试 harness 时有用。

Linux 上 CEF 启动崩溃时的降级路径

在部分 Linux 桌面（尤其是 NVIDIA 专有驱动 + Wayland/XWayland）上，Tauri/CEF 壳可能在 React 应用可用前就失败，已知症状之一是 CEF 报告主浏览器上下文后出现 X11BadWindow错误。core 本身健康时，文档建议分开发起 core 和前端继续开发：

cargo build --bin openhuman-core ./target/debug/openhuman-core run --port 7788

另一个终端：

cd app pnpm dev

然后浏览器打开 Vite 地址，选 Advanced / remote core 模式，把 RPC URL 设为http://127.0.0.1:7788/rpc，bearer token 用 core 写出的那个。该路径绕过 tray、自动更新、内嵌 provider webview 等 native 功能，但 agent、memory、skills 与 RPC 面保持可用。

可选：加速本地链接

core crate 链接一个大 rlib，cargo check/cargo test内循环经常是链接瓶颈。.cargo/config.toml 中留了注释掉的 mold（Linux）/ lld（macOS）配置供本地手动开启；不改仓库文件的等价做法是先安装 linker（apt install mold/brew install llvm），再运行：

# 预览将写入的内容 scripts/dev-setup-linker.sh --dry-run # 执行：把 mold/lld 检测写入 $CARGO_HOME/config.toml（不修改仓库内受版本管理的 .cargo/config.toml） scripts/dev-setup-linker.sh

该脚本是幂等的，重复执行无副作用；linker 未安装时它会检测并给出指引后退出。

延伸文档

• gitbooks/developing/getting-set-up.md：桌面/源码安装的完整路径，含 stable 版本安装脚本与 ARM Linux 细节
• gitbooks/developing/building-rust-core.md：仅根 crate 的构建参考（无需 JS/子模块依赖）
• gitbooks/developing/architecture/tauri-shell.md：app/src-tauri/外壳的职责、核心进程模型与 IPC 命令
• gitbooks/developing/cef.md：vendored CEF runtime 的来龙去脉与启动排障细节

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman