> 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/architecture.md). # 架构 OpenHuman 的高层结构：桌面外壳、Rust 核心和前端，以及它们之间的数据流动方式。 OpenHuman 依据 GNU GPL3 开源。本页概述系统的高层结构。完整的开发者参考文档位于 [架构](/openhuman/zh/kai-fa/architecture/architecture.md). ## 结构 OpenHuman 是一款基于 React 和 Tauri v2 的桌面应用。Rust 核心负责繁重工作，并与应用在同一进程中运行，而非作为独立服务。 ``` ┌──────────────────────────────────────────────────────────────────┐ │ Tauri 外壳（crates/openhuman-app/） │ │ • 窗口管理、操作系统集成、嵌入式核心生命周期（tokio 任务） │ │ • 全局热键、PTT/听写浮层、深层链接 │ └──────────────────────────────────────────────────────────────────┘ │ JSON-RPC（回环 HTTP）↕ ┌──────────────────────────────────────────────────────────────────┐ │ Rust 核心（crates/openhuman-core/，进程内，无二进制文件） │ │ • Memory v2（引擎绑定、召回/获取/存储、轮次生命周期） │ │ • 集成适配器 + 记忆源同步 │ │ • 提供商路由器（模型路由） │ │ • TokenJuice 压缩 │ │ • 原生工具（搜索、获取、文件系统、git，…） │ │ • 语音（STT 输入、TTS 输出、实时语音代理） │ └──────────────────────────────────────────────────────────────────┘ │ ┌──────────────────────────────────────────────────────────────────┐ │ React 前端（app/src/） │ │ • 屏幕、导航 │ │ • 通过 `coreRpcClient` 与核心通信 │ │ • 无业务逻辑，仅负责展示 │ └──────────────────────────────────────────────────────────────────┘ ``` 逻辑所在位置： * Rust 核心承载所有业务逻辑：记忆、集成、模型路由、工具和语音。它是权威来源。 * Tauri 外壳处理窗口管理、进程生命周期和 IPC。功能不在其中实现。 * React 前端绘制并编排 UI。它通过 JSON-RPC 调用核心： `coreRpcClient` 发送 `fetch()` 请求直接发送到 `http://127.0.0.1:/rpc`。只有非回环的纯`http://` 运行时才会经过外壳的 `relay_http_rpc` 命令。 核心在进程内运行而非置于套接字之后，也是许多代理可同时低成本运行的原因。没有每代理一个操作系统进程，也没有每代理一个套接字。有关 [性能](/openhuman/zh/kai-fa/performance.md) 的测量结果，以及 [嵌入 OpenHuman](https://github.com/tinyhumansai/openhuman/tree/main/docs/gitbooks/en/developing/embedding.md) 中如何在桌面应用之外将同一核心作为库使用，请参阅。 ## Crate * [`crates/openhuman-app/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-app/README.md) - Tauri v2 桌面宿主；不包含在根工作区中，从自己的清单文件构建。 * [`crates/openhuman-core/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/README.md) - Cargo 包 `openhuman`：业务领域、控制器契约和进程内分发、 `CoreBuilder`/`CoreRuntime`。它是一个库：没有二进制文件、没有 JSON-RPC 服务器，也不依赖于 `tinyhumans-sdk`. * [`crates/openhuman-embed/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-embed/README.md) - 类型化库门面（`openhuman_embed::Runtime` / `Agent`，以及 `Harness` ，后者作为单代理简写），用于将核心嵌入另一个产品。 * [`crates/openhuman-rpc/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-rpc/README.md) - 位于核心之上的 JSON-RPC 2.0：封装格式、浏览器来源允许列表、应用和 TUI 使用的 HTTP 客户端，以及整个服务器（axum 路由器、认证中间件、Socket.IO、 `/dev/connect`、监听器绑定）。契约类型本身（`Outcome`, `ControllerSchema`, `StructuredRpcError`）位于核心中。 * [`crates/openhuman-tinyhumans/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-tinyhumans/README.md) - TinyHumans 层：由 SDK 支持的后端传输、托管 RPC 代理领域、一个 `RuntimeBuilder` ，用于以已连接状态启动，以及宿主端登录和会话所有者。唯一允许依赖于 `tinyhumans-sdk`的 crate，也是每个宿主安装的第一个组件。 * [`crates/openhuman-cli/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-cli/README.md) - `openhuman-core` 二进制文件、开发者和基准测试二进制文件，以及每个根目录 `tests/` 和 `examples/` 目标。 * [`crates/openhuman-tui/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-tui/README.md) - 独立终端前端，在进程内启动核心。 完整表格位于 [架构](/openhuman/zh/kai-fa/architecture/architecture.md)中的“仓库布局”下。各 crate 的说明位于 [`crates/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/crates/README.md). ## 数据流 1. 连接。你通过 OAuth 登录一个 [集成](/openhuman/zh/gong-neng/integrations.md) 。后端存储令牌，核心绝不会以明文形式看到它。 2. 同步。一个 [内存来源](/openhuman/zh/gong-neng/memory.md) （文件夹、文件、链接、GitHub、RSS 或已连接的 Composio 工具包）会按需并根据其自身计划同步。 3. 读取。 `tinymemory-sources` 将源转化为文档，并对链接实施 SSRF 防护。 4. 清理。宿主绑定的每个引擎都被包装在 `memory::guard::ScrubbingEngine`中。它使用 `安全` 功能，来自 `tinymemory-integrations` ，在写入离开进程之前剥离密钥和个人标识符。包装发生在解析引擎的位置，因此覆盖工具、RPC 接口、源同步、回填和导入。持有 `BoundEngine` 并绕过它进行访问的调用方不受保护，因此解析是获取它的唯一受支持方式。 5. 存储。项目会进入选定的引擎，即托管的 TinyHumans 或你的 CortexDB。对话轮次会在发生时记录。代理或你添加学习内容时，学习内容会被存储。 6. 召回和获取。代理的 `记忆` 工具向引擎提问，并获得带引用的答案，或执行原始混合搜索。 7. 打包。每轮之前都会召回一个受令牌预算限制的记忆包。它仅进入该轮的模型请求，绝不会进入对话记录。 8. 遗忘。你可以在 Memory 页面或通过工具按 ID 删除项目。 9. 压缩。工具输出和大型源数据会经过 [TokenJuice](/openhuman/zh/gong-neng/token-compression.md) ，然后才进入 LLM 上下文。 10. 路由。 [路由器](/openhuman/zh/gong-neng/model-routing.md) 会根据任务提示选择提供商和模型。它是多个 [可插拔引擎](/openhuman/zh/kai-fa/engines.md) 之一，由核心在运行时选择。 ## 隐私边界 保留在你的设备上： * 工作区配置和角色文件 * 音频采集缓冲区及任何本地模型状态 经由 OpenHuman 后端传输（一个订阅，以及供嵌入者使用的一个 TinyHumans API 密钥）： * LLM 调用（模型提供商） * 网络搜索代理 * 集成 OAuth 和工具代理 * TTS 流式传输 请参阅 [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md) 了解完整情况，以及 [一个 TinyHumans API 密钥](/openhuman/zh/kai-fa/tinyhumans-api-key.md) 了解该单个密钥涵盖的内容。 ## 开源 代码位于 [github.com/tinyhumansai/openhuman](https://github.com/tinyhumansai/openhuman) ，采用 GNU GPL3 许可。欢迎提交 Issue 和拉取请求。该项目目前处于早期 Beta 阶段。贡献者应从 [架构](/openhuman/zh/kai-fa/architecture/architecture.md). ## 延伸阅读 * [智能体支架](/openhuman/zh/kai-fa/architecture/agent-harness.md), [Memory](/openhuman/zh/kai-fa/architecture/memory.md) 和 [安全性](/openhuman/zh/kai-fa/architecture/security.md) 开始，以深入了解详情。 * [前端](/openhuman/zh/kai-fa/architecture/frontend.md) 和 [Tauri 壳](/openhuman/zh/kai-fa/architecture/tauri-shell.md) 了解两个外层。 * [可加载模块](/openhuman/zh/kai-fa/loadable-modules.md) 和 [可插拔引擎](/openhuman/zh/kai-fa/engines.md) 了解可插入核心的组件。 * [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md) 了解全仓库规则，包括哪个 `vendor/` 子模块负责什么。 ## 可加载组件依赖边界 宿主通过已编译的 TinyBus 模块执行可加载组件行为，并且仅链接组件最小化的 `*-bus` 词汇。契约 crate 包含序列化类型、错误、标识符、版本、模式和工具声明；提供商、解析器、密码学、存储、原生资源和执行算法属于模块内部。OpenHuman 保留策略、凭据、审批、取消和产品编排。有状态资源以不透明句柄的形式跨总线传递，并具有显式清理操作。 此边界仍在迁移中。 [模块边界清单](https://github.com/tinyhumansai/openhuman/tree/main/docs/module-boundary-inventory.md) 列出了现有例外和所需的上游工作。 `pnpm rust:module-boundaries` 检查宿主正常/构建依赖图以及独立解析的契约图。其过渡性检查不证明迁移已完成； `pnpm rust:module-boundaries:complete` 要求例外列表为空且没有待处理契约。兼容的模块构件发布并固定后，宿主适配器才会切换，从而保留延迟加载和缓存解析。