> 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/developing.md). # 概览 从源代码构建、运行、测试并发布 OpenHuman。 OpenHuman 在 GPLv3 许可下开源，地址为 [github.com/tinyhumansai/openhuman](https://github.com/tinyhumansai/openhuman)。本节面向贡献者以及任何从源码运行 OpenHuman 的人。 如果你只是想使用这个应用，请从 [入门指南](/openhuman/zh/gai-lan/getting-started.md)开始。如果你想阅读架构、构建一个功能或提交一个 PR，那么你来对地方了。 *** ## 为什么这个框架很轻量 核心是一个 Rust 库，而不是一组通过套接字通信的服务。代理在进程内运行，因此一次轮次消耗的是一次函数调用，而不是进程边界或一次 RPC 往返。我们测得在一个进程中同时存活 500 个代理时，每个代理的边际内存大约为 1.77 MiB。一个冷启动代理轮次大约需要 100 ms，而只包含你所需领域的精简构建最小可达 51 MiB。 [性能](/openhuman/zh/kai-fa/performance.md) 中有这些数据以及我们如何得到它们。生成这些数据的测试装置公开在 [tinyhumansai/openhuman-benchmarks](https://github.com/tinyhumansai/openhuman-benchmarks). 在该基础之上的一切都是模块化的。Cargo 功能开关决定编译进来哪些内容，可加载的原生模块承载更重的引擎，而配置则选择具体引擎：模型提供方、嵌入、记忆和搜索。 [可插拔引擎](/openhuman/zh/kai-fa/engines.md), [可加载模块](/openhuman/zh/kai-fa/loadable-modules.md) 和 [Jev](/openhuman/zh/kai-fa/jev.md) 涵盖这些内容。 ## 各部分所在位置 | 路径 | 内容 | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `app/` | pnpm 工作区 `openhuman-app`：Vite 和 React 前端（[`app/src/`](https://github.com/tinyhumansai/openhuman/tree/main/app/src/README.md)）以及 Tauri 桌面宿主（[`crates/openhuman-app/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-app/README.md)). | | `crates/` | Rust crate（[概览](https://github.com/tinyhumansai/openhuman/blob/main/crates/README.md)）。其中有六个是工作区成员。 `openhuman-core` （包 `openhuman`）是核心库，其领域模块位于 `src//` ，控制器契约和进程内分发位于 `src/core/`。它没有二进制文件，也没有 JSON-RPC 服务器。 `openhuman-rpc` 是在核心之上的 JSON-RPC 2.0：信封、HTTP 客户端和服务器。 `openhuman-embed` 是类型化的库门面。 `openhuman-tinyhumans` 是唯一可以依赖 `tinyhumans-sdk`的 crate，并包含后端传输、托管 RPC 代理以及宿主侧会话所有者。每个宿主都会先安装它。 `openhuman-cli` 是 `openhuman-core` 二进制文件以及所有根目录下的 `tests/` 和 `examples/` target。 `openhuman-tui` 是终端前端。Tauri 宿主 `openhuman-app`，不包含在根工作区中，并从自己的清单构建。 | | `docs/gitbooks/en/` | 本网站、公开文档（[源代码](https://github.com/tinyhumansai/openhuman/tree/main/docs/gitbooks/README.md)). | | `docs/` | 内部维护者文档：测试覆盖矩阵、发布冒烟检查清单、库基准测试和最小示例说明、已翻译的 README，以及 `community/` ([`docs/`](https://github.com/tinyhumansai/openhuman/tree/main/docs/README.md)). | [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md) 位于仓库根目录，是在代码库上工作的 AI 代理的事实来源。 [`CLAUDE.md`](https://github.com/tinyhumansai/openhuman/blob/main/CLAUDE.md) 指向它。相同的规则也适用于人类。 *** ## 从这里开始 如果这是你第一次接触此仓库： 1. [环境设置](/openhuman/zh/kai-fa/getting-set-up.md)：工具链、依赖项、Tauri CLI 以及 `pnpm dev` 所需的一切。 2. [构建 Rust 核心](/openhuman/zh/kai-fa/building-rust-core.md)：仅针对 Rust 工作区的设置，包含固定的工具链、操作系统包以及精确的 `cargo` 命令。 3. [架构](/openhuman/zh/kai-fa/architecture/architecture.md) 及其 [概览](/openhuman/zh/kai-fa/architecture.md)：桌面应用、进程内 Rust 核心、JSON-RPC 桥接以及双套接字如何协同工作。在进行非平凡更改之前先阅读这里。 4. [前端](/openhuman/zh/kai-fa/architecture/frontend.md) 和 [Tauri 外壳](/openhuman/zh/kai-fa/architecture/tauri-shell.md)：React 应用以及包裹它的桌面宿主。 5. [MCP 服务器](/openhuman/zh/kai-fa/mcp-server.md)：可选的 stdio MCP 模式，将 OpenHuman 搜索、记忆和子代理工具暴露给本地客户端。 *** ## 核心深度解析 * [性能](/openhuman/zh/kai-fa/performance.md)：每个代理的内存、冷启动时间、二进制大小以及基准测试如何运行。原始测试装置和结果位于公开的 [openhuman-benchmarks](https://github.com/tinyhumansai/openhuman-benchmarks) 仓库中。 * [可插拔引擎](/openhuman/zh/kai-fa/engines.md)：配置如何选择 LLM、嵌入、记忆和网页搜索层，以及每一层可用的内容。 * [Jev](/openhuman/zh/kai-fa/jev.md)：位于工具选择和常规浏览器决策背后的快速概率模型。 * [将 OpenHuman 嵌入](https://github.com/tinyhumansai/openhuman/tree/main/docs/gitbooks/en/developing/embedding.md) （另见 [`crates/openhuman-embed`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-embed/README.md)）：在另一个 Rust 产品中使用 `openhuman-embed` 来运行核心，以及其上的任意数量代理。 [Rust 快速入门](/openhuman/zh/kai-fa/quickstart.md) 会一步步讲解。 * [SaaS 配置文件](/openhuman/zh/kai-fa/saas-profiles.md)：在网关后面将核心作为多用户服务运行，每个用户一个配置文件，可以在单节点上运行，也可以在带有租用配置文件的集群中运行。 * [一个 TinyHumans API 密钥](/openhuman/zh/kai-fa/tinyhumans-api-key.md)：单个密钥能解锁什么，包括托管推理、嵌入、网页搜索、媒体、集成、语音和 Jev。 *** ## 测试 OpenHuman 有三层测试。要知道你的更改属于哪一层。Rust 集成目标在 [`tests/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/tests/README.md) 中描述，辅助脚本在 [`scripts/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/README.md). * [测试策略](/openhuman/zh/kai-fa/testing-strategy.md)：何时编写 Vitest、cargo 或 WDIO 测试。 * [端到端测试](/openhuman/zh/kai-fa/e2e-testing.md)：WDIO 和 Appium 规范、Linux 和 macOS 配置，以及如何在本地运行单个规范。 * [代理可观测性](/openhuman/zh/kai-fa/agent-observability.md)：使 E2E 和代理运行在事后可调试的工件捕获。 PR 对已更改行的覆盖率必须至少达到 80%。为新行为添加测试，而不只是快乐路径。 *** ## 发布 * [发布策略](/openhuman/zh/kai-fa/release-policy.md)：版本管理、发布节奏、OAuth 和安装程序规则。 * [云端部署](/openhuman/zh/gong-neng/cloud-deploy.md)：当更改跨越桌面边界时的部署。 *** ## 更深入了解 * [代理框架](/openhuman/zh/kai-fa/architecture/agent-harness.md)：tinyagents 的轮次循环（检查点、熔断器、子代理交接、日志和回放）以及如何扩展工具面。 * [工作流](/openhuman/zh/gong-neng/workflows.md)：由 tinyflows 支持的 `flows` 领域，包含触发器、信任来源、审批门控运行以及 `flows_*` RPC 接口。 * [可加载模块](/openhuman/zh/kai-fa/loadable-modules.md)：原生 `cdylib` 模块，核心在运行时加载它们，以及它们如何被接纳。 * [钩子](/openhuman/zh/kai-fa/hooks.md)：由你维护的脚本，在工具执行前、文件编辑后或轮次结束时运行。 * [Chromium 嵌入式框架](/openhuman/zh/kai-fa/cef.md)：来自 CEF 时代的设计说明。如今外壳运行在原生 Tauri（Wry）上。 *** ## 贡献 * 在以下位置查看开放的问题和 PR： [tinyhumansai/openhuman](https://github.com/tinyhumansai/openhuman)。 [`vendor/`](https://github.com/tinyhumansai/openhuman/tree/main/vendor/README.md) 子模块（tinyagents、tinymemory 等）各自有自己的仓库，位于 [tinyhumansai](https://github.com/tinyhumansai). * PR 目标分支是 `main`。请推送到你的 fork，而不是上游仓库。 * 遵循 [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md) 以及问题和 PR 模板。 * 保持更改聚焦。一个 bug 修复不需要顺带清理周边代码。 朝着 AGI 前进并不一定意味着要交付一个内核。Bug 修复、文档、集成和测试都在推动上限。