OpenHuman 开发者指南：从源码构建、测试到发布的完整工作流-酒店常州论坛

OpenHuman 开发者指南：从源码构建、测试到发布的完整工作流

【免费下载链接】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 是一个面向 Mac、Windows、Linux 的开源个人 AI 桌面应用（React + Tauri v2 前端 + Rust 核心，GPLv3 协议）。本篇技术指南以仓库中的开发者文档 gitbooks/developing/README.md 为主线，系统梳理从零开始克隆仓库、搭建工具链、构建桌面应用与 Rust 核心、分层编写测试，到走完发布流程的完整开发闭环。读完本文，你将掌握 OpenHuman 仓库的目录组织、精确的构建命令、测试分层决策方法，以及main/release双分支发布模型下的实际发布操作。

仓库布局：四块核心区域

OpenHuman 是一个 monorepo，所有代码按职责集中在四个顶层目录中。理解这张表是阅读任何源码的前提：

路径	内容
app/	pnpm workspace`openhuman-app`：Vite + React 前端（app/src/）与 Tauri 桌面宿主（app/src-tauri/）
src/	Rust crate`openhuman_core`与`openhuman-core`CLI 二进制：领域逻辑、JSON-RPC、MCP 路由
gitbooks/	面向公众的文档站（本文所在目录）
docs/	尚未迁移到 GitBook 的深度参考文档（记忆管线图、Agent 流程等）

根目录的 CLAUDE.md 是 AI Agent 在该代码库上工作的"事实来源"（source of truth），同样的规则也适用于人类贡献者。它明确指出了逻辑所在的分界：Rust 核心（src/）承载全部业务逻辑、执行、领域、RPC、持久化与 CLI；Tauri + React（app/）只负责 UX、界面、导航与桥接，是"展示与编排层"而非特性所在层。

值得注意的细节：CLAUDE.md 说明核心以 in-process 方式运行——Tauri 宿主通过core_process::CoreProcessHandle将 Rust 核心作为 tokio 任务内嵌（sidecar 模式已在 PR #1061 移除），前端 RPC 走http://127.0.0.1:<port>/rpc，携带每次启动随机生成的 hex bearer token。OPENHUMAN_CORE_TOKEN对 CLI / docker / cloud 场景仍然生效。

从哪里开始：推荐的阅读路线

文档为首次拉取仓库的开发者规划了明确的阅读顺序，依次覆盖"能跑起来 → 能编译核心 → 能理解架构 → 能写测试"：

构建与安装（Getting Set Up）：工具链、依赖、vendor 的 Tauri CLI、sidecar staging——让pnpm dev真正启动起来所需的一切；
构建 Rust 核心（Building the Rust Core）：仅针对仓库根 Rust crate 的全新机器搭建：固定的工具链版本、操作系统包、精确的cargo命令；
架构（Architecture）：桌面应用、Rust 核心 sidecar、JSON-RPC 桥接、双 socket 如何拼合——做任何非平凡修改前先读它；
前端（Frontend）与 Tauri Shell：React 应用与其外的桌面宿主；
MCP Server：可选的 stdio MCP 模式，用于向本地客户端暴露只读的 OpenHuman 记忆工具。

从仓库根 package.json 可以看到 workspace 的管理方式：根包是私有包openhuman-repo，packageManager固定为pnpm@10.10.0+sha512...，并通过patchedDependencies对@assistant-ui/react-lexical@0.2.10应用了 app/patches/ 下的补丁。这种"根仓库只做编排、openhuman-app承载应用"的结构贯穿所有 npm script。

环境准备与工具链

必需的软件版本

依赖	版本要求	依据
Node.js	24 或更新	app/package.json
pnpm	10.10.0	根 package.json 的`packageManager`字段
Rust	1.93.0（rustup 安装，含`rustfmt`、`clippy`）	rust-toolchain.toml
CMake	最新稳定版	原生 Rust 依赖编译所需
Git 子模块	`app/src-tauri/vendor/`	vendor 的 CEF-aware Tauri CLI 需要
平台构建工具	macOS：Xcode Command Line Tools；Linux：Tauri 的 GTK/WebKit/AppIndicator 包组	见下文

macOS（Homebrew）快速开始：

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

Arch Linux 快速开始：

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

子模块与 vendor 体系

OpenHuman 的核心子系统大量运行在发布为独立 crate 的tiny*家族上（tinyagents、tinyflows、tinychannels、tinymemory、tinybus等），它们以 git 子模块形式 vendor 在vendor/下，以便在发布前于本仓库内直接测试 crate 变更。从根 Cargo.toml 的依赖注释可以看出这套体系的分工原则，例如：

Agent 引擎基于tinyagents：每一轮 agent turn 都经由src/openhuman/agent/tinyagents/的适配接缝穿过 harness；
记忆引擎基于tinycortex（通过tinymemory的 vendor 副本访问），OpenHuman 保留 RPC、工具、调度、凭据、安全策略等宿主侧逻辑；
推理基于 crate 原生的ModelRouter/OpenAiModel做工作负载分层路由。

克隆仓库后务必执行git submodule update --init --recursive（构建桌面壳时需要），而纯核心开发则不需要子模块。相关依赖声明（如tinyhumans-sdk、tinymcp）都在注释里标注了对应的初始化命令，例如git submodule update --init vendor/tinymcp。

构建桌面应用（本地编译）

从仓库根执行以下命令即可完成一次完整的源码构建：

# 1) 克隆并进入仓库 git clone https://github.com/tinyhumansai/openhuman.git cd openhuman # 2) 拉取 vendor 的 Tauri/CEF 源码 git submodule update --init --recursive # 3) 安装 JS 依赖（workspace 级） pnpm install # 4) 构建桌面应用产物 pnpm build

本地开发而非生产构建时：

# 仅 Web UI 开发（Vite dev server） pnpm dev # 桌面应用开发：使用 vendor 的 Tauri/CEF CLI，须在 workspace 根执行 pnpm --filter openhuman-app dev:app

根 package.json 提供了配套的完整脚本矩阵：pnpm typecheck（即tsc --noEmit/compile）、pnpm lint（ESLint --cache）、pnpm format:check（Prettier + cargo fmt --check）、pnpm test:rust（调用 scripts/test-rust-with-mock.sh）等，均可从仓库根直接运行。

通过官方安装脚本安装稳定版

macOS / Linux x64 的常规安装：

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

安装脚本行为：解析当前平台的最新稳定版、在可用时校验产物摘要、默认本地安装（无需 sudo）；macOS 安装OpenHuman.app到~/Applications，Linux x64 将 AppImage 安装为~/.local/bin/openhuman并写入桌面条目。可用--dry-run预览动作而不落盘：

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash -s -- --dry-run

Windows 使用 PowerShell：

irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

仓库还附带 packages/arch/openhuman-bin/ 的 AUR 配方：以官方 x86_64 AppImage 为二进制源，makepkg时解包应用树、安装桌面条目并暴露/usr/bin/openhuman。发布前可本地构建：cd packages/arch/openhuman-bin && makepkg --syncdeps --install。

ARM Linux（aarch64）构建

ARM 构建因 CEF 与 GTK 依赖需要特殊处理。先安装 Xvfb 用于无头构建/测试，然后：

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

运行 ARM 二进制需要设置 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::init().ok()）。若出现 "GTK has not been initialized" 说明该修复未就位，需重新构建。

常见故障排查

macOS：pnpm dev:app报 "CEF cache is held by another OpenHuman instance"

CEF 通过~/Library/Caches/com.openhuman.app/cef下的SingletonLock符号链接独占其用户数据目录。安装版.app与开发二进制共用同一 bundle id（com.openhuman.app），无法并行运行。退出另一实例后重跑：

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

若锁由崩溃进程残留（PID 已不存在），preflight 会自动清理过期SingletonLock并继续启动。已知限制：dev 与 release 构建仍共享com.openhuman.app缓存标识，隔离需要修改 vendor 的tauri-runtime-cef（跟踪自 #864）。

核心端口上的陈旧openhumanRPC 进程

core_process::ensure_running会在启动时探测OPENHUMAN_CORE_PORT（默认 7788）：若GET /识别出是 OpenHuman core（JSON 响应含"name": "openhuman"），判定为陈旧进程并主动终止（Unix 下 SIGTERM 后 750ms SIGKILL，Windows 下taskkill /F /T /PID），随后宿主拉起全新内嵌核心；若端口被其他服务占用则大声报错而非静默挂接。设置OPENHUMAN_CORE_REUSE_EXISTING=1可回到旧的"挂接任意进程"行为（用于手动调试 harness）。手动清理依然有效：

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

仅构建 Rust 核心（core-only 工作流）

如果你只关心仓库根 Rust crate，不需要桌面壳，使用 Building the Rust Core 的流程：

Cargo 包名：openhuman；
可运行二进制：openhuman-core（入口 src/main.rs）；
库：openhuman_core（Cargo.toml 的[lib]段，crate-type = ["rlib"]）。

# 快速依赖 + 类型检查 cargo check --manifest-path Cargo.toml # 调试构建 CLI / RPC 二进制 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。若偏好面向包的命令（如打包脚本），用-p openhuman。

加速本地链接（可选）

openhuman核心 crate 链接的是单个巨型 rlib，编辑 →cargo check/cargo test的内循环经常受链接瓶颈约束。用 mold（Linux）或 lld（macOS）可显著缩短增量重链时间。仓库提供幂等的配置脚本，它把检测结果写入$CARGO_HOME/config.toml（绝不改动仓库内跟踪的.cargo/config.toml，属于每台机器的可选开启）：

scripts/dev-setup-linker.sh # 安装 mold/lld 检测 scripts/dev-setup-linker.sh --dry-run # 先预览变更

需先安装链接器（apt install mold/brew install llvm），脚本检测不到会打印指引并退出。CI 的 Linux Rust 任务直接通过RUSTFLAGS启用同一标志。

各平台系统包前置条件

macOS：xcode-select --install。whisper-rs在构建期间编译原生代码，macOS 上该 crate 以metalfeature 构建，需要 Apple 工具链与 SDK 头文件。
Ubuntu / Debian（core-only 最小集）：

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（core-only）：

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

Windows：rustup + Visual Studio Build Tools 2022（"Desktop development with C++" 工作负载），MSVC 目标x86_64-pc-windows-msvc。注意用 MSVC 而非 MinGW——仓库给whisper-rs-sys打了补丁以强制静态 MSVC CRT，规避LNK2038/LNK1169错误。

一个典型的坑：whisper-rs-sys在 clang 下可能报fatal error: 'array' file not found，这正是文档点名libstdc++-14-dev的原因（clang 可能选中 Ubuntu runner 上的 GCC 14 C++ 头文件）。若仍无法解析libstdc++.so，可用 AGENTS.md 中记录的软链方案（按实际 GCC 版本调整）。

构建桌面壳（而非 core-only）时，需使用更宽的依赖集（GTK/WebKit/AppIndicator 等），详见 building-rust-core.md 第 5 节，两套清单都镜像自 .github/workflows/build-desktop.yml。

三层测试体系：你的改动该写在哪里

OpenHuman 对测试分层有非常明确的约定。核心原则：把测试压到尽可能低的层级（Rust unit > Rust integration > Vitest > WDIO），低层更快、更确定、更便宜；WDIO 只用于真正跨越 UI ⇄ Tauri ⇄ sidecar ⇄ JSON-RPC 的行为。

五个测试层级总览

层级	位置	测试内容	驱动方式
Rust 单元	`#[cfg(test)] mod tests`（同文件或`tests.rs`，或领域下`tests/`子目录，如`src/openhuman/channels/tests/`）	纯领域逻辑、schema、RPC handler 形状、内存状态机	`cargo test`
Rust 集成	仓库根`tests/*.rs`	真实 Tokio 运行时下的完整领域接线、mock 外部服务、JSON-RPC 端到端（如 tests/json_rpc_e2e.rs）、领域 × 领域交互	`pnpm test:rust`（即`bash scripts/test-rust-with-mock.sh`）
Vitest 单元	`app/src/*`下与源码同目录的`.test.ts(x)`，或`app/src/**/__tests__/`	React 组件、hooks、store slices、纯工具、服务层适配器	`pnpm test:unit`
WDIO E2E	app/test/e2e/specs/*.spec.ts	完整桌面流：UI → Tauri → in-process 核心 → JSON-RPC；用户可见行为	全平台走 Appium Chromium driver（端口 4723，面向 CEF 运行时）
手动冒烟	docs/RELEASE-MANUAL-SMOKE.md	驱动无法断言的 OS 级表面：TCC 权限弹窗、Gatekeeper、代码签名、DMG 安装、OS 原生 toast	发布切版时人工执行并在 release PR 签署

决策树：测试放哪层

改动在 JSON-RPC 边界之后（src/ 内）？ ├─ YES - 跨领域或与外部队话？ │ ├─ YES → Rust 集成（tests/*.rs） │ └─ NO → Rust 单元（源码旁） └─ NO - 改动在 app/ 内 ├─ 是纯函数 / hook / slice / 独立组件？ │ └─ YES → Vitest 单元（*.test.tsx 同目录） └─ 用户可见 且 跨越 UI ⇄ Tauri ⇄ sidecar ⇄ JSON-RPC？ ├─ YES → WDIO E2E（app/test/e2e/specs/*.spec.ts） └─ 属于 OS 级（TCC、Gatekeeper、安装、OS toast）？ └─ YES → 手动冒烟清单

如果一个改动涉及多个层级，每一层都要写对应的测试，不能用一层替代另一层。

关键质量门槛

失败路径要求：覆盖矩阵中每个特性叶子除 happy path 外必须有至少一条失败/边界断言。例如文件写入工具：happy = 写入了字节；failure = 路径限制拒绝。只断言 happy path 的 spec 是不完整的。
覆盖率门槛：PR 必须通过改动行 ≥ 80% 覆盖率的PR CI Gate检查。为新增行为补测试，而不只是 happy path。Cargo.toml 中还专门用build.rs把 tests/raw_coverage/ 下约 76 个独立tests/*.rs目标折叠进单一raw_coverage_all集成目标，省去约 75 次整 crate 重链。
Mock 策略：单元/集成/E2E 一律不得访问真实网络。统一使用共享 mock 后端（scripts/mock-api-core.mjs、scripts/mock-api-server.mjs、app/test/e2e/mock-server.ts），管理端点包括GET /__admin/health、POST /__admin/reset、POST /__admin/behavior、GET /__admin/requests。Telegram、Slack、Gmail、Notion、Ollama、OpenAI 等外部服务都在 mock 层打桩，测试通过getRequestLog()断言请求形状。
确定性规则：不用墙钟等待（用waitForApp/waitForWebView等辅助）；每个 E2E spec 运行在隔离的OPENHUMAN_WORKSPACE中；spec 不得依赖执行顺序；避免绝对坐标与动画时序；优先用browser.execute(...)合成键盘输入。

合并前的本地检查清单

# Rust core cargo fmt --check cargo check --manifest-path Cargo.toml cargo clippy --manifest-path Cargo.toml -- -D warnings cargo test --manifest-path Cargo.toml # Tauri shell cargo check --manifest-path app/src-tauri/Cargo.toml # Frontend pnpm typecheck pnpm lint pnpm format:check pnpm test:unit # Rust integration with mock backend pnpm test:rust # E2E（慢，仅当行为有用户可见变化时） pnpm test:e2e:build bash app/scripts/e2e-run-spec.sh test/e2e/specs/<your-spec>.spec.ts <id>

E2E 快速上手

桌面 E2E 用 WebDriverIO 通过 Appium 驱动 Tauri 应用：Linux 与 macOS 均使用Appium Chromium driver（端口 4723，CEF 运行时，CSS/DOM 选择器）。

# 一次性安装 Appium + Chromium driver npm install -g appium@3 appium driver install --source=npm appium-chromium-driver # 构建 E2E 应用 pnpm --filter openhuman-app test:e2e:build # 运行全部 flows pnpm --filter openhuman-app test:e2e:all:flows # 运行单个 spec bash app/scripts/e2e-run-spec.sh test/e2e/specs/smoke.spec.ts smoke

无头 Linux 下 harness 跑在 Xvfb 虚拟显示上；macOS 用户可通过 Docker 复用同一 Linux harness：docker compose -f e2e/docker-compose.yml run --rm e2e（要求 Docker Desktop 或 Colima，仓库以 bind mount 方式挂载，构建产物在多次运行间保留）。

E2E 仓库中已有大量现成 spec 可作范式参考（app/test/e2e/specs/ 下共 90+ 个.spec.ts，如chat-harness-send-stream.spec.ts、auth-access-control.spec.ts、notifications.spec.ts）。编写跨平台 spec 的要点：一律使用 element-helpers.ts 的辅助函数（clickNativeButton、hasAppChrome、waitForWebView等），绝不裸用XCUIElementType*选择器；优先使用稳定的data-testid钩子（命名规范<surface>-<element>-<id?>，如cron-job-toggle-<jobId>、thread-row-<threadId>），文本选择器只用于用户可见文案断言。

失败时wdio.conf.ts的afterTest钩子会把failure-*.png与failure-*.source.xml写入运行目录；若要完整的可审计运行（截图 + 页面源码 + mock 请求日志落盘），运行bash app/scripts/e2e-agent-review.sh，产物落在app/test/e2e/artifacts/<timestamp>-agent-review/。

Agent 可观测性

Agent Observability 描述的是 artifact-capture 层：它让 E2E 与 Agent 运行在事后可调试。这是测试体系的横向能力，配合测试矩阵作为契约使用——docs/TEST-COVERAGE-MATRIX.md 中每个特性叶子要么映射到测试路径，要么给出带理由的🚫加手动冒烟条目；增删改特性时必须在同一 PR 内更新矩阵行。

发布流程与 OAuth 版本门槛

分发渠道

GitHub Releases 是桌面构建的主分发源；
Tauri updater 端点（见 scripts/prepareTauriConfig.js）应指向当前发布产物；
退役旧稳定版时需同步清理：移除/隐藏 GitHub Release 上的过时安装器、更新网站/CDN 下载链接、刷新 updater manifest（如 scripts/fixtures/latest.json），并抽查旧直链是否已重定向/404/410。

最小应用版本门槛（OAuth 防护）

生产 Web 构建在构建期内嵌一个最低支持应用 semver，使 OAuth 深链无法在过时二进制上完成——这尤其保护 Gmail 等 OAuth 流程。相关变量：

变量	作用
`VITE_MINIMUM_SUPPORTED_APP_VERSION`	例如`0.51.0`——桌面应用必须 ≥ 该版本才能完成`openhuman://oauth/success`
`VITE_LATEST_APP_DOWNLOAD_URL`	可选；默认指向`releases/latest`。门槛拦截 OAuth 时打开

二者配置为 GitHub Actions variables，且必须同时出现在 .github/workflows/build-desktop.yml 的独立pnpm build步骤与tauri-apps/tauri-action步骤 env 中（该复用矩阵由release-production.yml/release-staging.yml调用），确保随安装包分发的 Vite bundle 包含该门槛。本地开发请保持VITE_MINIMUM_SUPPORTED_APP_VERSION未设置（门槛禁用）。实现位于 app/src/utils/oauthAppVersionGate.ts 与desktopDeepLinkListener.ts。

分支模型与 CI 车道

两条长期分支、两条 CI 车道：

main——所有特性/修复 PR 的落点。每个 PR（及对 main 的 push）运行CI Lite（.github/workflows/ci-lite.yml）：按变更区域做质量检查 + 限定到变更文件的单元测试，由PR CI Gate把关 ≥ 80% diff 覆盖率。
release——维护者从main提升的快照，发布从它切出。面向release的 PR 与每次 push 运行CI Full（.github/workflows/ci-full.yml）：完整单元套件、Rust mock-backend E2E、Playwright web E2E，以及 Linux/macOS/Windows 全量桌面 E2E 矩阵。CI Full Gate聚合除 Playwright spec 运行外的所有车道（Playwright 因 CI 争用下的不稳定性暂为continue-on-error的非阻塞信号，切版前需人工查看该车道结果）。

循环过程：promote-main-to-release.yml把 main 以 merge commit 推入 release（无 PR）→ CI Full 在提升 push 上运行 → 通过后以release-production.yml切生产。从release切出的版本会通过 scripts/release/merge-release-into-main.sh 把 release 回并到 main（尽可能 fast-forward，否则生成chore(release): merge release vX.Y.Z back into main这样的版本化合并提交）。版本号 bump 提交携带[skip ci]。

staging 与 production 两套工作流

工作流	分支	版本号	打的 tag	并发组	何时使用
release-staging.yml	`main`或`release`	仅`patch`	`v<version>-staging`	`release-staging`	为 QA 从所选分支切 staging 构建
release-production.yml	`release`	`patch`/`minor`/`major`（`release_type`输入）	`v<version>`	`release-production`	从验证过的 release HEAD（或固定`commit_sha`）发布生产版本

没有独立的staging分支——staging 切版与生产发布都活在release上，仅以 tag 后缀（-staging与否）和工作流来源区分。staging tag 用 SemVer 预发布后缀-staging（如v1.2.4-staging），在排序上先于匹配的生产 tag。失败自动回滚：构建矩阵失败会删除 draft Release 与对应 tag（生产）/ 仅删除-stagingtag（staging，bump 提交保留，下次从新 patch 号继续）。

发布 App token 的审批门与季度轮换

release-production.yml用 GitHub App token（XGITHUB_APP_ID/XGITHUB_APP_PRIVATE_KEY）完成 bump、向release提交、回并main并推送提交 + tag——该 token绕过分支保护，因此泄露风险被两道控制约束：

人工审批门：review-approvaljob 在prepare-build之前运行，将每个生产 run 停在Release-ApprovalGitHub environment 上，必须先有人工审批才会发生任何 push。
季度密钥轮换：每季度（3/6/9/12 月末）及任何疑似泄露时立即轮换XGITHUB_APP_PRIVATE_KEY——在 App settings 生成新私钥 → 更新仓库 secret → 用低风险的Release (Staging)验证 token 步骤 → 删除旧私钥 → 记录轮换日期。

深入理解核心子系统

Agent Harness（tinyagents 驱动）

Agent Harness 讲解基于 tinyagents 的 turn loop：检查点（checkpointing）、熔断器（circuit breakers）、子 Agent 交还（sub-agent handback）、journals/replay，以及如何扩展工具表面。如根 Cargo.toml 所述，tinyagents 已被拆分为一组聚焦 crate，OpenHuman 直接依赖tinyagents-harness（agent loop / tools / middleware）、tinyagents-graph（持久状态图）、tinyagents-language（.rag）、tinyagents-registry与tinyagents-session——26+ 个领域消费 tinyagents，是 agent 引擎与编排的地基。

Workflows（tinyflows 支撑）

Workflows 介绍flows领域：触发器、信任源（trust origins）、审批门控运行（approval-gated runs）与flows_*RPC 表面。tinyflows 是宿主无关的工作流引擎（类型化节点图 → 校验 → 编译 → 在 tinyagents 上运行），其mockfeature 提供的确定性内存能力包让dry_run_workflowagent 工具可以在零副作用下自校验草稿图。

Chromium Embedded Framework（CEF）

cef.md 说明内嵌 provider webview 的工作方式：为什么它们不运行注入的 JS，以及 per-provider scanner 取而代之做什么。这也是为什么 Tauri shell 使用 vendor 的tauri-runtime-cef，以及为什么 macOS 会出现 CEF 缓存锁冲突。

对于仍在构建中的特性，Subconscious Loop 页面覆盖后台任务评估系统的端到端设计。

贡献规范

在 upstream（tinyhumansai/openhuman）开 issue 与 PR；
PR 目标是main。推送到自己的 fork，而非 upstream；
遵循 CONTRIBUTING.md 与 issue/PR 模板；
保持改动聚焦：修 bug 不需要附带周边清理；一次性操作不需要抽 helper。

仓库还有 AGENTS.md、CONTRIBUTING-BEGINNERS.md 等面向不同读者的协作文档。正如 README 末尾所说：向构建 AGI 迈进不一定意味着提交内核——bug 修复、文档、集成与测试同样在推动进度条。

一句话总结本文的技术闭环：先按 getting-set-up.md 搭好 pnpm + Rust 1.93.0 + vendor 子模块环境，用pnpm dev/cargo build --bin openhuman-core跑起桌面应用或纯核心；写代码时按 testing-strategy.md 的决策树把测试放进 Rust unit / Rust integration / Vitest / WDIO 四层之一，保证改动行 ≥ 80% 覆盖率并通过PR CI Gate；合并进main后由维护者经 promote-main-to-release.yml 提升到release，CI Full 全绿后走 release-production.yml 完成带 OAuth 版本门槛的正式发布。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析