> 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/building-rust-core.md).

# 构建 Rust 核心

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

本页面说明如何在一台全新的机器上编译 Rust 核心。它涵盖核心工作区及其兄弟 crate：

* Cargo 包： `openhuman`
* 二进制： `openhuman-core` （构建自 `openhuman-cli`)
* 库： `openhuman_core`

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

如果你想要完整的桌面应用（`pnpm dev`、Tauri、前端工具链），请使用 [准备环境](/openhuman/zh/kai-fa/getting-set-up.md)。该路径需要额外的 JavaScript、子模块和桌面运行时工具，而仅核心的 `cargo` 工作流并不需要这些。

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

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

* 通道： `1.99.1`
* 组件： `rustfmt`, `clippy`

之所以固定版本，是因为 `rusqlite` 0.40 和 `libsqlite3-sys` 0.38 使用了 `cfg_select!` 宏，而该宏在 1.96 中变为稳定。

推荐安装：

```bash
rustup toolchain install 1.99.1 --component rustfmt --component clippy
rustup default 1.99.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/` 是终端前端。
* `crates/openhuman-cli/` 保存 `openhuman-core` 二进制、开发和基准测试二进制，以及根目录 `tests/*.rs` 和 `examples/*.rs` 目标。它依赖 `crates/openhuman-tinyhumans/` 提供由 SDK 支持的后端传输，而核心并不包含这一部分。
* `crates/openhuman-rpc/` 保存 Tauri 外壳和 TUI 使用的 JSON-RPC 契约和 HTTP 客户端。

仓库根目录下的递归子模块 `vendor/` 也是核心构建所必需的，不仅仅是桌面外壳。 `crates/openhuman-core/Cargo.toml` 以路径依赖方式依赖 `vendor/tinyagents`, `vendor/tinymemory`, `vendor/tinymcp`，以及其余的 `tiny*` 家族，根目录 `Cargo.toml` `[patch]` 表指向 `vendor/tinymemory`, `vendor/tinyflows`, `vendor/tinychannels`，以及 `tinyinference` 嵌套在 `vendor/tinyagents/`.

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

桌面和 Tauri 工作有额外要求。请按照 [准备环境](/openhuman/zh/kai-fa/getting-set-up.md) 来处理这些。

## 3. 构建命令

在仓库根目录下：

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

# CLI 和 RPC 二进制的调试构建
cargo build --manifest-path Cargo.toml -p openhuman-cli --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 世界，拥有自己的清单和锁文件）
cargo check --manifest-path crates/openhuman-app/Cargo.toml

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

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

说明：

* 核心库的包名是 `openhuman` （crate `openhuman_core`）。可运行的二进制 `openhuman-core`，是从 `openhuman-cli` 包（`crates/openhuman-cli/src/main.rs`）构建出来的，这就是上面的命令为何传入 `-p openhuman-cli`.
* 构建后的二进制位于 `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/blob/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` 运行带来同样的加速。

### 特性开关与二进制大小

`crates/openhuman-core/Cargo.toml` 通过 Cargo 特性构建其大部分领域。一个裸露的 `cargo check` 会编译贡献者默认集合（`media`, `skills`, `flows`, `mcp`, `channels`, `http-server`, `scheduler-gate`, `file-logging`, `modules`），这并不是桌面应用实际发布的内容。 `scripts/ci/product-features.txt` 是已发布产品的开关列表的唯一事实来源，而 `scripts/ci/check-feature-forwarding.mjs` 检查 `crates/openhuman-app/Cargo.toml` 是否正好转发了该集合。关闭某个开关会移除真实代码，并且对某些开关而言，还会移除整个原生依赖。有关若干特性组合下测得的二进制大小和 RSS，请参见 [性能](/openhuman/zh/kai-fa/performance.md).

## 本地模块开发

可加载模块（`文档`, `voice`, `mcp`，等等）默认来自固定且经过摘要校验的 GitHub 发布版本。这是 CI 和发布构建使用的唯一来源。若要在 `vendor/<submodule>` 中迭代某个模块而不发布它，请在本地切换来源：

```bash
# 从其 gitlink 构建模块并打印其环境变量
eval "$(node scripts/modules/build.mjs tinydocs --print-env)"
OPENHUMAN_MODULE_SOURCE=source ./target/debug/openhuman-core serve

# 或将其链接到 CLI（非产品特性）
OPENHUMAN_MODULE_SOURCE=linked cargo run -p openhuman-cli --features linked-modules -- serve

# 推送前：gitlink 是否领先于注册表固定版本？
node scripts/modules/pin-status.mjs

# 发布模块并重新固定注册表（发布前会询问）
node scripts/modules/release-and-repin.mjs tinydocs --bump patch
```

`linked-modules` 链接全部 11 个注册表模块（`crates/openhuman-modules-linked`，每个模块一个特性，再加上 `all`），因此 `OPENHUMAN_MODULE_SOURCE=linked` 可以从可执行文件中提供任何一个模块。它们共享一个 `tinybus`、一个 TinyAgents 和一个 `tinystoragedrivers` ，都通过根目录 `[patch]` 表共享，因此模块仓库会按版本范围命名这些内容，而不会按 `=` 固定版本或嵌套路径命名。可通过以下方式检查： `cargo build -p openhuman-modules-linked --features all`.

`OPENHUMAN_MODULE_SOURCE_<ID>` 会覆盖一个模块。如果某个 `链接的` 或 `来源` 模块不可用，核心会回退到发布版本并记录警告； `modules.list` 显示每个模块是从哪个来源提供的。详细信息： [可加载模块](/openhuman/zh/kai-fa/loadable-modules.md).

## 4. macOS 前置条件

安装：

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

原因：原生依赖在构建期间会编译 C 和 Objective-C 代码，它们需要 Apple 工具链和 SDK 头文件。这些包括 `cpal` 用于音频采集（位于 `inference` 特性之后， `voice` 需要）以及由供应商提供的 `objc2` Contacts crate，编译自 `tinymemory` crate。

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

## 5. Linux 前置条件

### 仅核心包集合

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

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`基于 -driven 的构建在 Ubuntu 运行器上可能会选择 GCC 14 的 C++ 头文件；这可确保这些原生 crate 的 `libstdc++.so` 仍可解析。

### Linux 桌面/Tauri 包集合

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

Ubuntu 或 Debian（镜像自 [`.github/workflows/build-desktop.yml`](https://github.com/tinyhumansai/openhuman/blob/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 安装 Rust
* CI 和发布构建使用的 MSVC 目标： `x86_64-pc-windows-msvc`

安装好 Microsoft 工具链后，推荐的命令：

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

使用 MSVC 工具链，而不是 MinGW，以与 CI 和发布构建保持一致。

## 7. 相关路径

* [准备环境](/openhuman/zh/kai-fa/getting-set-up.md)：包含 `pnpm`、Tauri 和子模块。核心在桌面壳进程内运行（参见 [Tauri 壳](/openhuman/zh/kai-fa/architecture/tauri-shell.md)），因此不需要侧车暂存步骤。
* [架构概览](/openhuman/zh/kai-fa/architecture.md)：核心在桌面应用和 RPC 流程中的位置。
* [架构](/openhuman/zh/kai-fa/architecture/architecture.md)：完整的 crate 映射和仓库布局。
* [嵌入](https://github.com/tinyhumansai/openhuman/tree/main/docs/gitbooks/en/developing/embedding.md)：使用 `crates/openhuman-embed` 将核心作为库在其他产品中运行。
* [引擎](/openhuman/zh/kai-fa/engines.md)：核心可运行于其上的可插拔 LLM、嵌入、记忆和搜索后端。
* [性能](/openhuman/zh/kai-fa/performance.md)：不同功能组合下的二进制大小、冷启动和内存数据。