> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa-zhong/building-rust-core.md).

# 构建 Rust 核心

在一台全新的机器上从零构建 Rust 核心。

此页面是供贡献者在新机器上编译 Rust 核心的参考。

它涵盖了 **核心工作区及其兄弟 crate**:

* Cargo 包： `openhuman`
* 二进制： `openhuman-core`
* 库： `openhuman_core`

根目录下的 `Cargo.toml` 是一个虚拟工作区，其成员包括 `crates/openhuman-core`, `crates/openhuman-embed`, `crates/openhuman-rpc`，以及 `crates/openhuman-tui`. `crates/openhuman-app` （Tauri 桌面外壳）不包含在该工作区中，而是从其自己的清单构建。

如果你想要完整的桌面应用（`pnpm dev`、Tauri、前端工具链），请使用 [开始设置](/openhuman/zh/kai-fa-zhong/getting-set-up.md)。该路径还需要额外的 JavaScript、子模块和桌面运行时依赖，这些 **不是** 仅核心版 `cargo` 工作流所需的。

## 1. 安装固定版本的 Rust 工具链

该仓库在 [`rust-toolchain.toml`](https://github.com/tinyhumansai/openhuman/tree/main/rust-toolchain.toml):

* 中固定了 Rust： `1.96.1`
* 组件： `rustfmt`, `clippy`

之所以存在这个固定版本，是因为 `rusqlite` 0.40 / `libsqlite3-sys` 0.38 使用了 `cfg_select!` 宏，它在 1.96 中稳定（在 1.95 及之前仍是未稳定）。

推荐安装：

```bash
rustup toolchain install 1.96.1 --component rustfmt --component clippy
rustup default 1.96.1
```

你也可以让 `cargo` 在 `rust-toolchain.toml` 之后自动从 `rustup` 本身安装后自动完成。

## 2. 克隆仓库

仅核心工作：

```bash
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
```

这对于 Rust 工作区来说已经足够。核心源代码、包清单以及权威的领域实现位于 `crates/openhuman-core/`。面向宿主的稳定库外观是相邻的 `crates/openhuman-embed/` 包，而终端前端是 `crates/openhuman-tui/`。共享的 JSON-RPC 合约以及供 Tauri 外壳和 TUI 使用的 HTTP 客户端位于 `crates/openhuman-rpc/`.

仓库根目录下的递归子模块 `vendor/` 对于核心构建同样是必需的，不仅仅是桌面外壳： `crates/openhuman-core/Cargo.toml` 路径依赖于 `vendor/tinyagents`, `vendor/tinymemory`, `vendor/tinymcp`，以及其余的 `tiny*` 家族，而根目录的 `Cargo.toml` `[patch]` 表指向 `vendor/tinymemory`, `vendor/tinyflows`, `vendor/tinychannels`, `vendor/motosan-ai-oauth`，以及 `tinyinference` 位于 `vendor/tinyagents/`.

```bash
git submodule update --init --recursive vendor/
```

桌面/Tauri 工作在此基础上还有额外要求——请遵循 [开始设置](/openhuman/zh/kai-fa-zhong/getting-set-up.md) 以获取这些要求。

## 3. 构建命令

在仓库根目录下：

```bash
# 快速依赖 + 类型检查
cargo check --manifest-path Cargo.toml

# 实际 CLI / RPC 二进制的调试构建
cargo build --manifest-path Cargo.toml --bin openhuman-core

# 检查稳定的面向宿主的嵌入式外观
cargo check --manifest-path Cargo.toml -p openhuman-embed

# 检查共享 RPC 合约 + HTTP 客户端 crate
cargo check --manifest-path Cargo.toml -p openhuman-rpc

# 构建终端前端（在进程内嵌入核心）
cargo build --manifest-path Cargo.toml -p openhuman-tui

# 检查桌面外壳（独立的 Cargo 体系，自己的 manifest/lockfile）
cargo check --manifest-path crates/openhuman-app/Cargo.toml

# 发布构建
cargo build --manifest-path Cargo.toml --release --bin openhuman-core

# Rust 测试
cargo test --manifest-path Cargo.toml
```

说明：

* 该 **包** 名称是 `openhuman`，但可运行的二进制是 **`openhuman-core`**.
* 如果你更喜欢面向包的 cargo 命令用于打包脚本，请使用 `-p openhuman`.
* 构建后的二进制位于 `target/debug/openhuman-core` 或 `target/release/openhuman-core`.

### 更快的本地链接（可选）

该 `openhuman` 核心 crate 以一个很大的单一 rlib 链接，因此编辑 → `cargo check`/`cargo test` 的内循环经常受链接速度限制。更快的链接器（Linux 上的 mold，macOS 上的 lld）可以在每次增量重链接时节省大量时间。 [`.cargo/config.toml`](https://github.com/tinyhumansai/openhuman/tree/main/.cargo/config.toml) 记录了手动启用的方法，但最简单的路径是：

```bash
# 将 mold/lld 检测安装到 $CARGO_HOME/config.toml —— 绝不会写入
# 仓库跟踪的 .cargo/config.toml，因此这是按机器启用的可选项
scripts/dev-setup-linker.sh

# 先预览更改
scripts/dev-setup-linker.sh --dry-run
```

先安装链接器（`apt install mold` / `brew install llvm`）——如果缺失，脚本会检测到并给出说明后退出。它是幂等的：在链接器已配置后再次运行不会产生任何作用。CI 通过 `RUSTFLAGS` 在 Linux Rust 任务中直接启用相同的标志；这个脚本存在的目的，是让本地 `cargo` 调用也能获得同样的加速，而不依赖容器。

## 4. macOS 前置条件

安装：

* Xcode 命令行工具： `xcode-select --install`

为什么：

* 本地依赖（`cpal` 用于位于 `inference` 功能后面的音频捕获，该功能由 `voice` 所需； `objc2` Contacts 组件由 vendored 的 `tinymemory` 模块编译）会在构建过程中编译 C/Objective-C 代码，因此需要可用的 Apple 工具链和 SDK 头文件。

安装 Xcode CLT 后，核心应该可以使用上面的 cargo 命令构建。

## 5. Linux 前置条件

### 仅核心版软件包集合

在新 Linux 机器上运行之前，请先安装这些软件包。 `cargo` 在全新的 Linux 机器上。

**Ubuntu / Debian：**

```bash
sudo apt-get update
sudo apt-get install -y \
  build-essential cmake pkg-config clang libssl-dev libclang-dev \
  libasound2-dev libxi-dev libxtst-dev libxdo-dev libudev-dev \
  libstdc++-14-dev
```

**Arch Linux：**

```bash
sudo pacman -S --needed base-devel cmake pkgconf clang openssl \
  alsa-lib libxi libxtst xdotool libevdev
```

> 在 Arch 上， `clang` 包含 `libclang` 和 `base-devel` 包含 `gcc` （提供 `libstdc++`），因此不需要单独的 `-dev` 软件包。

这些为何重要：

* `build-essential` / `base-devel`, `cmake`, `pkg-config` / `pkgconf`：由传递性 Rust 依赖使用的本地构建工具。
* `clang`, `libclang-dev`：bindgen（由诸如 `cpal`的 ALSA 绑定）和 C/C++ 编译路径使用。
* `libssl-dev` / `openssl`：一些网络依赖所需的 OpenSSL 头文件。
* `libasound2-dev` / `alsa-lib`, `libxi-dev` / `libxi`, `libxtst-dev` / `libxtst`, `libxdo-dev` / `xdotool`, `libudev-dev` （在 Arch 的 `systemd-libs`), `libevdev`：音频/输入/设备 crate 所需（`cpal`, `enigo`/X11 输入处理），这些也会被纳入核心构建。
* `libstdc++-14-dev`: `clang`在 Ubuntu 运行环境中，CI 驱动的构建可能会选用 GCC 14 C++ 头文件；这可确保这些本地 crate 的 `libstdc++.so` 仍然可解析。

### Linux 桌面/Tauri 软件包集合

如果你构建的是桌面外壳而不是仅核心 crate，请安装更广泛的依赖集合。

**Ubuntu / Debian** （镜像自 [`.github/workflows/build-desktop.yml`](https://github.com/tinyhumansai/openhuman/tree/main/.github/workflows/build-desktop.yml)):

```bash
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：**

```bash
sudo pacman -S --needed gtk3 webkit2gtk-4.1 libayatana-appindicator \
  librsvg patchelf nss nspr at-spi2-core libcups libdrm \
  libxkbcommon libxcomposite libxdamage libxfixes libxrandr \
  mesa pango cairo libxshmfence
```

只有在你需要时才使用桌面列表 `crates/openhuman-app/`；对于根 crate 工作，上面较小的仅核心列表才是相关基线。

## 6. Windows 前置条件

安装：

* 通过 `rustup`
* Visual Studio Build Tools 2022 或带有 **使用 C++ 的桌面开发** 工作负载的 Visual Studio
* CI 和发布构建使用的 MSVC 目标： `x86_64-pc-windows-msvc`

安装 Microsoft 工具链后建议执行的命令：

```powershell
rustup toolchain install 1.96.1 --component rustfmt --component clippy
rustup target add x86_64-pc-windows-msvc
cargo build --manifest-path Cargo.toml --bin openhuman-core
```

请使用 MSVC 工具链，而不是 MinGW，以匹配 CI 和发布构建。

## 7. 相关路径

* [开始设置](/openhuman/zh/kai-fa-zhong/getting-set-up.md)：完整的桌面贡献者设置，包含 `pnpm`、Tauri 和子模块。核心在桌面外壳内部以内进程方式运行（参见 [Tauri 外壳](/openhuman/zh/kai-fa-zhong/architecture/tauri-shell.md)）；没有 sidecar 分阶段步骤。
* [OpenHuman 架构](/openhuman/zh/kai-fa-zhong/architecture.md)：核心在桌面应用和 RPC 流中的位置。
* [深度架构参考](/openhuman/zh/kai-fa-zhong/architecture/architecture.md)：完整的 crate 地图和仓库布局。