【AI Agent 深度解析】OpenHuman 开源项目全面分析 — 打造你的个人 AI 超级智能助手

一、项目概述

1.1 项目背景

在 AI Agent（智能代理）快速发展的今天，我们面临着一个核心问题：大多数 AI 助手需要从零开始学习用户，需要花费数天甚至数周才能真正了解你的技术栈和工作流。

OpenHuman 项目正是为了解决这个问题而生。它是一个开源的个人 AI 超级智能助手，设计目标是：

OpenHuman is your Personal AI super intelligence. Private, Simple and extremely powerful.

1.2 项目基本信息

属性	详情
项目名称	OpenHuman
GitHub 仓库	tinyhumansai/openhuman
当前版本	v0.53.43（2026年5月13日）
开源协议	GNU GPL-3.0
项目状态	Early Beta（早期测试版，积极开发中）
Star 数量	10.8k+ ⭐
Fork 数量	933+
总提交数	1,928+
本周新增 Star	+629（2026年5月9-15日）

1.3 核心理念

┌──────────────────────────────────────────────────────────────────┐
│                    OpenHuman 核心理念                          │
├──────────────────────────────────────────────────────────────────┤
│                                                              │
│   🔒 私密性 (Private)                                         │
│      → 数据本地存储，不上传云端                                 │
│      → 本地加密，数据归用户所有                                 │
│                                                              │
│   🎯 简洁性 (Simple)                                          │
│      → 无需复杂配置，几分钟内即可上手                           │
│      → 干净的桌面 UI，无需终端操作                              │
│                                                              │
│   ⚡ 强大性 (Powerful)                                        │
│      → 118+ 第三方集成                                       │
│      → 智能记忆系统                                            │
│      → 多模型路由                                              │
│                                                              │
└──────────────────────────────────────────────────────────────────┘

---

二、核心功能详解

2.1 功能架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        OpenHuman 功能架构                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────┐  │
│  │  1. 桌面吉祥物 (Mascot)                                      │  │
│  │     → 有"脸"的 AI，会说话、对环境做出反应                     │  │
│  │     → 可加入 Google Meet 会议                                  │  │
│  │     → 跨周记住用户信息                                        │  │
│  └─────────────────┘  │
│                          ↓                                          │
│  ┌─────────────────┐  │
│  │  2. 118+ 第三方集成 + 自动抓取                                 │  │
│  │     → Gmail、Notion、GitHub、Slack、Stripe                   │  │
│  │     → Calendar、Drive、Linear、Jira                          │  │
│  │     → 每 20 分钟自动同步数据                                   │  │
│  └─────────────────┘  │
│                          ↓                                          │
│  ┌─────────────────┐  │
│  │  3. Memory Tree + Obsidian Wiki                                │  │
│  │     → 本地优先的知识库                                        │  │
│  │     → ≤3k token 的 Markdown 块                              │  │
│  │     → 层级摘要树存储在本地 SQLite                             │  │
│  └─────────────────┘  │
│                          ↓                                          │
│  ┌─────────────────┐  │
│  │  4. 内置工具集 (Batteries Included)                           │  │
│  │     → 网络搜索 + 网页抓取                                    │  │
│  │     → 完整编码工具集                                          │  │
│  │     → 原生语音（STT + TTS）                                 │  │
│  └─────────────────┘  │
│                          ↓                                          │
│  ┌─────────────────┐  │
│  │  5. TokenJuice（智能 Token 压缩）                            │  │
│  │     → HTML → Markdown 转换                                   │  │
│  │     → 长 URL 缩短                                           │  │
│  │     → 降低成本和延迟高达 80%                                  │  │
│  └─────────────────┘  │
│                                                                   │
└─────────────────────────────────────────────────────────────────────┘

2.2 功能详解表格

功能模块	详细说明	技术实现
桌面吉祥物	AI 有可视化"脸"，能说话、对环境做出反应，可作为真实参与者加入 Google Meet 会议	CEF（Chromium Embedded Framework）渲染
118+ 第三方集成	支持 Gmail、Notion、GitHub、Slack、Stripe、Calendar、Drive、Linear、Jira 等	OAuth 2.0 授权，自动 token 管理
自动抓取	每 20 分钟自动循环拉取最新数据到记忆树	调度器 + 增量同步机制
Memory Tree	本地优先的知识库，所有连接数据被规范化为 ≤3k token 的 Markdown 块	SQLite + Markdown 文件双存储
Obsidian 兼容	同步生成 .md 文件，兼容 Obsidian vault	文件系统监听 + 实时同步
网络搜索	内置搜索引擎集成	外部 API 调用 + 结果缓存
网页抓取	Web-scraper 工具，自动提取网页内容	HTML 解析 + Markdown 转换
编码工具集	文件系统、Git、Lint、Test、Grep 等完整工具	Rust 原生实现，高性能
原生语音	STT 输入 + ElevenLabs TTS 输出 + 吉祥物唇形同步	语音识别 + 语音合成 + 动画同步
模型路由	自动将任务分配给合适的 LLM（推理型/快速型/视觉型）	任务分类 + 模型选择算法
TokenJuice	智能 Token 压缩，所有工具调用、抓取结果在传入 LLM 前均经过压缩	HTML→MD 转换 + 内容摘要
本地 AI	通过 Ollama 支持设备端推理	Ollama API 集成
消息渠道	支持跨渠道收发消息	WebSocket + HTTP RPC
隐私安全	工作流数据留在设备本地，本地加密	AES 加密 + 本地存储

---

三、技术架构深度分析

3.1 整体架构设计

OpenHuman 采用 三层架构，清晰分离关注点：

┌──────────────────────────────────────────────────────────────────┐
│                      OpenHuman 三层架构                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌───────────────────────────────────────────────────────┐       │
│   │  Layer 1: Tauri Shell（外壳层）                         │       │
│   │  - 窗口管理                                              │       │
│   │  - 进程生命周期管理                                       │       │
│   │  - CEF 子 WebView                                       │       │
│   │  - IPC 通信桥接                                         │       │
│   └───────────────────────────────────────────────────────┘       │
│                          ↕ JSON-RPC (HTTP)                        │
│   ┌───────────────────────────────────────────────────────┐       │
│   │  Layer 2: Rust Core（核心层）⚙️                           │       │
│   │  - Memory Tree Pipeline（记忆树管道）                      │       │
│   │  - Integration Adapters（集成适配器）                      │       │
│   │  - Provider Router（模型路由器）                           │       │
│   │  - TokenJuice（Token 压缩）                              │       │
│   │  - Native Tools（原生工具集）                             │       │
│   │  - Voice（语音模块）                                     │       │
│   └───────────────────────────────────────────────────────┘       │
│                          ↕ coreRpcClient 调用                    │
│   ┌───────────────────────────────────────────────────────┐       │
│   │  Layer 3: React Frontend（前端层）                         │       │
│   │  - 页面与导航                                            │       │
│   │  - RPC 调用                                              │       │
│   │  - 纯展示层，无业务逻辑                                   │       │
│   └───────────────────────────────────────────────────────┘       │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

3.2 技术栈详解

3.2.1 编程语言分布

语言	占比	用途
Rust	69.4%	核心业务逻辑、性能关键模块
TypeScript	25.8%	前端 UI、类型安全的 JavaScript
JavaScript	2.6%	脚本工具、构建配置
Shell	1.8%	安装脚本、自动化任务
CSS	0.2%	样式定制
HTML	0.1%	静态页面
其他	0.1%	配置、文档等

3.2.2 主要技术组件

// 技术栈配置示例（基于项目分析）
const techStack = {
  // 桌面框架
  desktopFramework: "Tauri v2 (Rust + Web 前端)",
  
  // CEF 支持
  cef: "Chromium Embedded Framework",
  
  // 数据库
  database: "SQLite (本地存储)",
  
  // 包管理
  packageManager: "pnpm (monorepo 工作区)",
  
  // 语音
  voice: "ElevenLabs TTS + STT",
  
  // 本地 AI
  localAI: "Ollama 集成",
  
  // 知识库
  knowledgeBase: "Obsidian 兼容 Markdown vault"
};

3.2.3 构建工具要求

工具	版本要求	用途
Node.js	24+	JavaScript 运行时
pnpm	10.10.0	包管理器
Rust	1.93.0	系统编程语言（含 rustfmt + clippy）
CMake	最新稳定版	构建系统
Ninja	最新稳定版	构建加速器
ripgrep	最新稳定版	代码搜索工具

3.3 核心模块详解

3.3.1 Rust Core 模块结构

src/
├── memory_tree/           # Memory Tree 管道
│   ├── pipeline.rs      # 数据处理流水线
│   ├── chunk.rs        # Markdown 块管理
│   ├── score.rs        # 热度评分
│   └── summarize.rs   # 摘要生成
├── integrations/         # 集成适配器
│   ├── gmail.rs       # Gmail 集成
│   ├── notion.rs      # Notion 集成
│   ├── github.rs      # GitHub 集成
│   └── scheduler.rs   # 自动抓取调度器
├── router/               # 模型路由
│   ├── provider.rs    # Provider 抽象
│   ├── model.rs       # 模型选择
│   └── route.rs       # 路由逻辑
├── token_juice/          # Token 压缩
│   ├── compress.rs    # 压缩算法
│   ├── html2md.rs    # HTML 转 Markdown
│   └── shorten.rs    # URL 缩短
├── tools/                 # 原生工具集
│   ├── fs.rs          # 文件系统
│   ├── git.rs         # Git 操作
│   ├── search.rs      # 网络搜索
│   └── fetch.rs      # 网页抓取
└── voice/                # 语音模块
    ├── stt.rs         # 语音识别
    ├── tts.rs         # 语音合成
    └── meet.rs        # Google Meet Agent

3.3.2 数据流 Pipeline（10 步详解）

// 数据源：https://tinyhumans.gitbook.io/openhuman/developing/architecture

/// OpenHuman 数据处理流水线
/// 完整数据流包含 10 个步骤
pub struct DataPipeline {
    // 步骤 1: Connect - OAuth 接入集成服务
    // - Token 安全存储（Core 不接触明文）
    // - 支持 118+ 第三方服务
    step1_connect: OAuthProvider,
    
    // 步骤 2: Auto-fetch - 每 20 分钟调度器自动同步
    // - 增量同步机制
    // - 避免重复拉取
    step2_auto_fetch: Scheduler,
    
    // 步骤 3: Canonicalize - 各 Provider 输出统一规范化
    // - 带溯源标记的 Markdown
    // - 统一数据格式
    step3_canonicalize: Canonicalizer,
    
    // 步骤 4: Chunk - Markdown 切分
    // - ≤3000 Token 的确定性块
    // - 保持语义完整性
    step4_chunk: Chunker,
    
    // 步骤 5: Store - 块存入存储
    // - SQLite（chunks.db）
    // - .md 文件写入 wiki 目录
    step5_store: Storage,
    
    // 步骤 6: Score - 后台执行评分
    // - Embedding 生成
    // - 实体提取
    // - 热度评分
    step6_score: Scorer,
    
    // 步骤 7: Summarize - 构建摘要树
    // - Source/Topic/Global 摘要
    // - 层级化组织结构
    step7_summarize: Summarizer,
    
    // 步骤 8: Retrieve - 用户提问时查询
    // - 搜索/下钻/主题/全局/fetch
    // - 相关性排序
    step8_retrieve: Retriever,
    
    // 步骤 9: Compress - TokenJuice 压缩
    // - 工具输出和大型数据压缩
    // - 降低 LLM 上下文消耗
    step9_compress: Compressor,
    
    // 步骤 10: Route - 路由器选择模型
    // - 根据任务提示选择最合适的 provider + model
    // - 推理型/快速型/视觉型自动分配
    step10_route: Router,
}

---

四、与其他 AI 助手对比

4.1 综合对比表

功能特性	Claude Cowork	OpenClaw	Hermes Agent	OpenHuman
开源	🚫 专有	✅ MIT	✅ MIT	✅ GNU GPL
易上手	✅ 桌面+CLI	⚠️ 终端优先	⚠️ 终端优先	✅ 干净UI，分钟级
费用	⚠️ 订阅+附加	⚠️ 自带模型	⚠️ 自带模型	✅ 单订阅+TokenJuice
记忆系统	✅ 对话级	⚠️ 插件依赖	✅ 自学习	🚀 记忆树+Obsidian
集成数量	⚠️ 少量	⚠️ 自建	⚠️ 自建	🚀 118+ OAuth
自动抓取	🚫 无	🚫 无	🚫 无	✅ 20分钟同步
模型路由	🚫 单模型	⚠️ 手动	⚠️ 手动	✅ 内置自动
原生工具	✅ 仅代码	✅ 仅代码	✅ 仅代码	✅ 代码+搜索+抓取+语音
上下文获取	周级	周级	周级	⚡ 分钟级

4.2 OpenHuman 的差异化优势

┌──────────────────────────────────────────────────────────────┐
│              OpenHuman vs 传统 AI 助手                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  传统 AI 助手的问题：                                          │
│  ┌────────────────────────────────────────────────┐          │
│  │ 1. 从零开始学习用户                                │          │
│  │    → Hermes 需要观察你工作来学习                      │          │
│  │    → OpenClaw 等待插件搬运上下文                      │          │
│  │    → 需要花费数天或数周                               │          │
│  └────────────────────────────────────────────────┘          │
│                          ↓                                   │
│                     解决方案：                                   │
│  ┌────────────────────────────────────────────────┐          │
│  │ OpenHuman 的方案：                                │          │
│  │                                                 │          │
│  │ ① 连接你的账户                                    │          │
│  │    → OAuth 一键授权                               │          │
│  │                                                 │          │
│  │ ② auto-fetch 每 20 分钟本地拉取数据                  │          │
│  │    → 无需手动编写轮询循环                           │          │
│  │                                                 │          │
│  │ ③ Memory Trees 将所有内容压缩进                    │          │
│  │    Obsidian wiki 中的 Markdown 文件                │          │
│  │                                                 │          │
│  │ ④ 一次同步后，Agent 就拥有你                      │          │
│  │    收件箱、日历、仓库、文档的完整上下文               │          │
│  │    → 无需训练期！                                   │          │
│  └────────────────────────────────────────────────┘          │
│                                                              │
└──────────────────────────────────────────────────────────────┘

---

五、源码结构分析

5.1 仓库目录结构

openhuman/
├── .agents/agents/        # AI 代理配置
│   ├── coder.agent.md   # 编码代理
│   ├── planner.agent.md  # 规划代理
│   └── reviewer.agent.md # 代码审查代理
├── .claude/             # Claude 相关配置
│   └── settings.json    # Claude 设置
├── .codex/              # Codex 配置
│   └── config.json      # Codex 配置
├── app/                 # 应用主体（Tauri + React）
│   ├── src-tauri/      # Tauri Rust 后端
│   │   ├── src/        # Rust 源代码
│   │   ├── Cargo.toml  # Rust 项目配置
│   │   └── tauri.conf.json # Tauri 配置
│   └── src/            # React 前端
│       ├── components/  # React 组件
│       ├── pages/       # 页面
│       └── utils/       # 工具函数
├── docs/                # 文档
│   ├── architecture.md  # 架构文档
│   ├── setup.md        # 环境搭建
│   └── features/       # 功能文档
├── e2e/                 # 端到端测试
│   ├── tests/          # E2E 测试脚本
│   └── fixtures/      # 测试夹具
├── examples/            # 示例代码
│   ├── basic-usage/   # 基础用法
│   └── advanced/      # 高级用法
├── packages/            # 包管理（monorepo）
│   ├── core/          # 核心库
│   ├── ui/            # UI 组件库
│   └── utils/         # 共享工具
├── remotion/           # 视频/动画相关
│   ├── compositions/  # 动画组合
│   └── output/        # 输出文件
├── scripts/             # 安装/构建脚本
│   ├── install.sh     # Linux/macOS 安装脚本
│   ├── install.ps1    # Windows 安装脚本
│   └── dev.sh        # 开发脚本
├── src/                 # Rust 源代码（核心逻辑）
│   ├── main.rs        # 入口文件
│   ├── memory/        # 记忆系统
│   ├── integrations/  # 集成模块
│   ├── router/        # 模型路由
│   ├── token_juice/   # Token 压缩
│   ├── tools/         # 工具集
│   └── voice/        # 语音模块
├── tests/              # 测试
│   ├── unit/         # 单元测试
│   ├── integration/  # 集成测试
│   └── fixtures/     # 测试夹具
├── Cargo.toml         # Rust 项目配置
├── package.json       # Node.js 项目配置
├── pnpm-workspace.yaml # pnpm 工作区配置
├── Dockerfile         # Docker 配置
└── docker-compose.yml # Docker Compose 配置

5.2 关键配置文件分析

5.2.1 package.json 脚本命令

{
  "name": "openhuman-repo",
  "version": "0.53.43",
  "private": true,
  "scripts": {
    // 开发命令
    "dev": "pnpm --filter openhuman-app dev",           // 启动开发服务器
    "dev:cef": "pnpm --filter openhuman-app dev:cef", // CEF 开发模式
    "dev:app": "pnpm --filter openhuman-app dev:app",  // 桌面 Shell 开发
    "dev:app:win": "pnpm --filter openhuman-app dev:app:win", // Windows 开发
    
    // 构建命令
    "build": "pnpm --filter openhuman-app build",        // 生产构建
    "compile": "tsc --noEmit",                        // TypeScript 编译检查
    "typecheck": "pnpm compile",                       // 类型检查
    
    // 测试命令
    "test": "vitest run",                              // 运行测试
    "test:coverage": "vitest run --coverage",          // 测试覆盖率
    "test:rust": "cargo test",                        // Rust 测试
    "test:rust:e2e": "cargo test --features e2e",    // Rust E2E 测试
    
    // 代码质量
    "lint": "eslint . --ext .ts,.tsx",               // Lint 检查
    "lint:fix": "eslint . --ext .ts,.tsx --fix",     // 自动修复
    "format": "prettier --write .",                   // 格式化
    "format:check": "prettier --check .",             // 格式检查
    
    // Tauri 相关
    "tauri": "tauri",                                 // Tauri CLI
    "rust:check": "cargo check -p openhuman --lib",    // Rust 检查
    
    // 工具脚本
    "rabbit": "node scripts/rabbit.js",                // Rabbit CLI
    "deep-work": "node scripts/deep-work.js",          // 深度工作模式
    "review": "node scripts/review.js",                // 代码审查
    "work": "node scripts/work.js",                    // 工作流
    "agent-batch": "node scripts/agent-batch.js",      // Agent 批处理
    "mock:api": "node scripts/mock-api.js",           // Mock API
    "pr:checklist": "node scripts/pr-checklist.js",    // PR 检查
    "merge-pr": "node scripts/merge-pr.js",            // 合并 PR
    "reset": "node scripts/reset.js"                  // 重置工作区
  },
  "devDependencies": {
    "husky": "^9.1.7",   // Git hooks 管理
    "ws": "^8.20.0"       // WebSocket 库
  }
}

5.2.2 Cargo.toml（Rust 核心配置）

[package]
name = "openhuman"
version = "0.53.43"
edition = "2021"
authors = ["@senamakel"]
license = "GPL-3.0"

[dependencies]
# Tauri 框架
tauri = { version = "2.0", features = ["devtools"] }
tauri-build = "2.0"

# 异步运行时
tokio = { version = "1.38", features = ["full"] }
async-trait = "0.1"

# 数据库
rusqlite = { version = "0.31", features = ["bundled"] }
sqlx = { version = "0.7", features = ["runtime-tokio-rustls"] }

# HTTP 客户端
reqwest = { version = "0.12", features = ["json"] }
ureq = "2.9"

# 语音处理
whisper-rs = "0.12"          # STT
elevenlabs-rs = "0.3"       # TTS

# AI/ML
ollama-rs = "0.2"           # 本地 AI
candle = "0.3"              # ML 推理

# 工具库
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio-stream = "0.1"

[build-dependencies]
tauri-build = "2.0"

---

六、安装与使用指南

6.1 安装方式一：官网下载（推荐）

访问 tinyhumans.ai/openhuman 下载安装包：

平台	安装包格式	说明
macOS	DMG	双击挂载后拖入 Applications
Windows	EXE	双击运行安装向导
Linux	AppImage / DEB / RPM	根据发行版选择

6.2 安装方式二：命令行安装

macOS / Linux (x64)

# 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

# 安装后验证
openhuman --version
# 输出: openhuman v0.53.43

Windows (PowerShell)

# 一键安装脚本
irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

# 安装后验证
openhuman.exe --version

6.3 从源码构建（开发者）

步骤 1：安装依赖

# 系统依赖
## macOS
brew install git node@24 cmake ninja ripgrep

## Ubuntu/Debian
sudo apt update
sudo apt install git nodejs cmake ninja-build ripgrep

## Windows (PowerShell)
# 安装 Chocolatey 包管理器
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装依赖
choco install git nodejs cmake ninja ripgrep -y

步骤 2：安装 Rust

# 安装 Rust (1.93.0+)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 验证安装
rustc --version
# 输出: rustc 1.93.0 (xxxxxx 2024-xx-xx)

# 安装组件
rustup component add rustfmt clippy

步骤 3：安装 pnpm

# 安装 pnpm (10.10.0)
npm install -g pnpm@10.10.0

# 验证安装
pnpm --version
# 输出: 10.10.0

步骤 4：克隆仓库并初始化

# 克隆仓库
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 初始化子模块（重要！）
git submodule update --init --recursive

# 安装 Node.js 依赖
pnpm install

步骤 5：启动开发服务器

# 仅 Web UI 开发
pnpm dev

# 桌面 Shell 开发（推荐）
pnpm --filter openhuman-app dev:app

# CEF 开发模式
pnpm dev:cef

# Windows 平台开发
pnpm dev:app:win

6.4 开发检查命令

# TypeScript 类型检查
pnpm typecheck

# Rust 代码检查
cargo check -p openhuman --lib

# 代码格式检查
pnpm format:check

# Lint 检查
pnpm lint

# 运行测试
pnpm test
pnpm test:rust

---

七、核心功能使用详解

7.1 连接第三方服务（OAuth 集成）

┌────────────────────────────────────────────────────────────┐
│            OAuth 集成流程                                   │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  步骤 1: 打开 OpenHuman 设置                               │
│       ↓                                                    │
│  步骤 2: 选择要连接的服务（Gmail/Notion/GitHub等）          │
│       ↓                                                    │
│  步骤 3: 点击"连接"按钮                                     │
│       ↓                                                    │
│  步骤 4: 浏览器打开 OAuth 授权页面                          │
│       ↓                                                    │
│  步骤 5: 授权后自动回调到 OpenHuman                        │
│       ↓                                                    │
│  步骤 6: Token 安全存储（本地加密）                         │
│       ↓                                                    │
│  完成！每 20 分钟自动同步数据                                │
│                                                            │
└────────────────────────────────────────────────────────────┘

支持的服务列表

服务类型	服务名称	功能
邮件	Gmail	读取/发送邮件、搜索、标签管理
笔记	Notion	页面读取、数据库查询、内容创建
代码	GitHub	仓库管理、PR 审查、Issue 跟踪
通讯	Slack	消息收发、频道管理
支付	Stripe	支付数据查询、客户管理
日历	Google Calendar	事件管理、日程查询
存储	Google Drive	文件管理、共享链接
项目	Linear、Jira	任务管理、进度跟踪

7.2 Memory Tree 使用

Memory Tree 数据结构

# Memory Tree 层级结构示例

memory_tree/
├── chunks.db                  # SQLite 数据库
└── wiki/                     # Obsidian Vault
    ├── README.md            # Vault 入口
    ├── source/              # 源数据（按服务分类）
    │   ├── gmail/
    │   │   ├── 2026-05-16-emails.md
    │   │   └── 2026-05-15-emails.md
    │   ├── github/
    │   │   ├── my-repo-issues.md
    │   │   └── my-repo-prs.md
    │   └── notion/
    │       └── project-notes.md
    ├── topics/              # 主题摘要
    │   ├── work-projects.md
    │   ├── personal-tasks.md
    │   └── technical-notes.md
    └── global/              # 全局摘要
        └── master-summary.md

自动抓取调度器配置

# config.toml
[auto_fetch]
# 同步间隔（分钟）
interval_minutes = 20

# 启用的集成
enabled_integrations = [
    "gmail",
    "github",
    "notion",
    "slack"
]

# 增量同步（仅拉取新数据）
incremental_sync = true

# 失败重试次数
max_retries = 3

7.3 TokenJuice 智能压缩

压缩策略详解

/// TokenJuice 压缩模块
/// 在数据传入 LLM 前进行智能压缩
pub struct TokenJuice {
    /// HTML → Markdown 转换
    /// 移除无关标签、脚本、样式
    html2md: HtmlToMarkdownConverter,
    
    /// 长 URL 缩短
    /// 使用 t.co 风格的缩短服务
    url_shortener: UrlShortener,
    
    /// 非 ASCII 字符移除/替换
    /// 减少 Token 消耗
    ascii_normalizer: AsciiNormalizer,
    
    /// 内容摘要
    /// 提取关键信息，去除冗余
    summarizer: ContentSummarizer,
}

impl TokenJuice {
    /// 压缩工具调用结果
    pub fn compress_tool_output(&self, input: &str) -> String {
        let mut output = input.to_string();
        
        // 1. HTML → Markdown
        if output.contains("<html") {
            output = self.html2md.convert(&output);
        }
        
        // 2. 缩短 URL
        output = self.url_shortener.shorten_urls(&output);
        
        // 3. 移除非 ASCII 字符
        output = self.ascii_normalizer.normalize(&output);
        
        // 4. 内容摘要（如果仍然过长）
        if output.len() > 3000 {
            output = self.summarizer.summarize(&output, 3000);
        }
        
        output
    }
}

压缩效果对比

原始内容	压缩后	Token 减少
HTML 网页（10KB）	Markdown（2KB）	~80%
邮件正文（5KB）	摘要（1KB）	~80%
搜索结果（8KB）	压缩后（2KB）	~75%
GitHub Issue（3KB）	Markdown（1KB）	~67%

7.4 模型路由（Model Routing）

路由策略

/// 模型路由器
/// 根据任务类型自动选择最合适的模型
pub struct ModelRouter {
    /// 推理型模型（复杂推理、代码分析）
    reasoning_models: Vec<Model>,
    
    /// 快速型模型（简单问答、摘要）
    fast_models: Vec<Model>,
    
    /// 视觉型模型（图像理解）
    vision_models: Vec<Model>,
}

impl ModelRouter {
    /// 根据任务提示选择模型
    pub fn route(&self, task: &Task) -> Model {
        let task_type = self.classify_task(task);
        
        match task_type {
            TaskType::Reasoning => {
                // 选择推理能力最强的模型
                self.reasoning_models[0].clone()
            }
            TaskType::Fast => {
                // 选择响应最快的模型
                self.fast_models[0].clone()
            }
            TaskType::Vision => {
                // 选择支持视觉的模型
                self.vision_models[0].clone()
            }
        }
    }
    
    /// 任务分类
    fn classify_task(&self, task: &Task) -> TaskType {
        let prompt = &task.prompt;
        
        if prompt.contains("image") || prompt.contains("图片") {
            TaskType::Vision
        } else if prompt.contains("analyze") || prompt.contains("分析") {
            TaskType::Reasoning
        } else {
            TaskType::Fast
        }
    }
}

支持的模型提供商

提供商	模型示例	用途
Anthropic	Claude 3.5 Sonnet	推理、代码
OpenAI	GPT-4o、GPT-4 Turbo	通用、视觉
Google	Gemini 1.5 Pro	长上下文
Meta	Llama 3.1	本地部署
Ollama	Llama 3.1、Mistral	本地推理

---

八、云部署指南

8.1 部署架构

┌──────────────────────────────────────────────────────────────┐
│                    OpenHuman 云部署架构                       │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────────────┐           │
│   │                    DigitalOcean App Platform                │   │
│   │  ┌────────────┐   │   │
│   │  │  openhuman-core (Docker)                         │   │   │
│   │  │  - 监听端口: 7788                              │   │   │
│   │  │  - 健康检查: GET /health                       │   │   │
│   │  │  - RPC 入口: POST /rpc                        │   │   │
│   │  │  - 事件流: GET /events                        │   │   │
│   │  │  - WebSocket: GET /ws/dictation               │   │   │
│   │  └────────────┘   │   │
│   │                     ↕ HTTPS                                       │   │
│   │  ┌────────────┐   │   │
│   │  │  Caddy 反向代理                                   │   │   │
│   │  │  - TLS 终止                                       │   │   │
│   │  │  - 负载均衡                                        │   │   │
│   │  └────────────┘   │   │
│   └──────────────────┘           │
│                              ↕                                     │
│   ┌──────────────────┐           │
│   │                    桌面客户端（Tauri）                           │   │
│   │  - OPENHUMAN_CORE_RUN_MODE=external                │   │
│   │  - OPENHUMAN_CORE_RPC_URL=https://core.example.com/rpc │   │
│   │  - OPENHUMAN_CORE_TOKEN=<token>                   │   │
│   └──────────────────┘           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

8.2 部署方式一：DigitalOcean App Platform

步骤 1：一键部署

步骤 2：配置环境变量

# .do/app.yaml
name: openhuman-core
services:
  - name: openhuman-core
    image:
      registry: ghcr.io
      repository: tinyhumansai/openhuman-core
      tag: latest
    instance_count: 1
    instance_size: basic-xxs
    http_port: 7788
    envs:
      - key: OPENHUMAN_CORE_TOKEN
        value: ${OPENHUMAN_CORE_TOKEN}
        type: SECRET
      - key: BACKEND_URL
        value: https://api.tinyhumans.ai
      - key: OPENHUMAN_APP_ENV
        value: production
      - key: OPENHUMAN_CORE_HOST
        value: 0.0.0.0
      - key: OPENHUMAN_CORE_PORT
        value: 7788
    volumes:
      - name: openhuman-data
        mount_path: /home/openhuman/.openhuman
        size_gb: 10

步骤 3：生成强密钥

# 生成 OPENHUMAN_CORE_TOKEN
openssl rand -hex 32
# 输出: 5a3c7f1e9d4b2a8f6c0e3d7b5a9c2f4e8b1d6a3c7f0e9d4b2a8f6c0e3d7b5a

# 在 DO 控制面板中设置
# Settings → App-Level Environment Variables → Add Variable

8.3 部署方式二：Docker Compose（推荐生产使用）

docker-compose.yml

version: '3.8'

services:
  openhuman-core:
    image: ghcr.io/tinyhumansai/openhuman-core:latest
    container_name: openhuman-core
    restart: unless-stopped
    ports:
      - "7788:7788"
    environment:
      - OPENHUMAN_CORE_TOKEN=${OPENHUMAN_CORE_TOKEN}
      - BACKEND_URL=https://api.tinyhumans.ai
      - OPENHUMAN_APP_ENV=production
      - OPENHUMAN_CORE_HOST=0.0.0.0
      - OPENHUMAN_CORE_PORT=7788
      - RUST_LOG=info
    volumes:
      - openhuman-data:/home/openhuman/.openhuman
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7788/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  openhuman-data:
    driver: local

启动命令

# 克隆仓库
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 创建 .env 文件
cp .env.example .env

# 编辑 .env，设置以下变量
# OPENHUMAN_CORE_TOKEN=<openssl rand -hex 32 的输出>
# BACKEND_URL=https://api.tinyhumans.ai
# OPENHUMAN_APP_ENV=production

# 启动服务
docker compose up -d

# 验证健康检查
curl -fsSL http://localhost:7788/health
# 输出: {"status": "ok"}

8.4 桌面客户端连接配置

app/.env.local

# 运行模式：连接外部核心
OPENHUMAN_CORE_RUN_MODE=external

# 核心 RPC URL（公网用 HTTPS）
OPENHUMAN_CORE_RPC_URL=https://core.example.com/rpc

# 认证 Token（与服务端相同）
OPENHUMAN_CORE_TOKEN=5a3c7f1e9d4b2a8f6c0e3d7b5a9c2f4e8b1d6a3c7f0e9d4b2a8f6c0e3d7b5a

# 私有内网（如 Tailscale）可使用 HTTP
# OPENHUMAN_CORE_RPC_URL=http://100.x.x.x:7788/rpc

8.5 Caddy 反向代理配置

# Caddyfile
core.example.com {
    # 自动 TLS（Let's Encrypt）
    tls admin@example.com
    
    # 反向代理到 openhuman-core
    reverse_proxy localhost:7788 {
        # 健康检查
        health_timeout 5s
        
        # 超时设置
        timeout 30s
        
        # 负载均衡（如果有多实例）
        lb_policy round_robin
    }
}

---

九、高级配置

9.1 agentmemory 后端集成

如果你已在其他编程代理中自托管了 agentmemory，可在 config.toml 中配置：

# config.toml
[memory]
# 使用 agentmemory 作为后端
backend = "agentmemory"

# agentmemory 连接配置
[memory.agentmemory]
url = "http://localhost:8000"
token = "${AGENTMEMORY_TOKEN}"

优势：同一个持久化存储可同时为以下工具提供服务：

• OpenHuman
• Claude Code
• Cursor
• Codex
• OpenCode

9.2 TokenJuice 配置

# config.toml
[token_juice]
# 是否启用 Token 压缩
enabled = true

# 压缩阈值（Token 数）
threshold = 3000

# 压缩策略
[compress.html]
enabled = true
convert_to_markdown = true
remove_scripts = true
remove_styles = true

[compress.urls]
enabled = true
shortener = "tinyurl"  # 或 "bitly"

[compress.ascii]
enabled = true
remove_non_ascii = true

9.3 模型路由配置

# config.toml
[model_routing]
# 默认提供商
default_provider = "anthropic"

# 推理型任务模型
[model_routing.reasoning]
provider = "anthropic"
model = "claude-3-5-sonnet-20241022"
max_tokens = 8192

# 快速型任务模型
[model_routing.fast]
provider = "openai"
model = "gpt-4o-mini"
max_tokens = 4096

# 视觉型任务模型
[model_routing.vision]
provider = "openai"
model = "gpt-4o"
max_tokens = 16384

# 本地模型（可选）
[model_routing.local]
provider = "ollama"
model = "llama3.1:8b"
max_tokens = 4096

---

十、社区与资源

10.1 官方资源

资源类型	链接
官网	tinyhumans.ai/openhuman
GitHub 仓库	github.com/tinyhumansa…
文档	tinyhumans.gitbook.io/openhuman
架构文档	Architecture
环境搭建	Getting Set Up
云部署	Cloud Deploy

10.2 社区渠道

平台	链接
Discord	discord.tinyhumans.ai
Reddit	r/tinyhumansai
X/Twitter	@tinyhumansai

10.3 创始人

• @senamakel：Twitter

---

十一、项目亮点总结

11.1 技术创新点

┌──────────────────────────────────────────────────────────────────┐
│                  OpenHuman 技术创新点                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. 📍 本地优先架构                                             │
│     → 核心数据（Memory Tree、Vault）全部本地存储                 │
│     → 保护用户隐私，数据归用户所有                              │
│                                                                  │
│  2. ⚡ 分钟级上下文获取                                          │
│     → 传统 Agent 需要数天/周才能了解用户                        │
│     → OpenHuman 通过 auto-fetch 在几分钟内完成                   │
│                                                                  │
│  3. 🧠 智能记忆系统                                             │
│     → Memory Tree 层级摘要                                      │
│     → Obsidian 兼容 Vault                                       │
│     → 支持 118+ 第三方集成                                     │
│                                                                  │
│  4. 🔧 开箱即用工具集                                           │
│     → 网络搜索 + 网页抓取                                       │
│     → 完整编码工具集                                            │
│     → 原生语音（STT + TTS）                                    │
│                                                                  │
│  5. 🎯 模型路由自动化                                           │
│     → 根据任务类型自动选择最合适的模型                            │
│     → 一个订阅搞定所有需求                                       │
│                                                                  │
│  6. 💰 TokenJuice 压缩                                         │
│     → 智能压缩工具输出和大型数据                                 │
│     → 降低成本和延迟高达 80%                                    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

11.2 适用场景

场景	说明	OpenHuman 优势
个人知识管理	整合邮件、笔记、代码仓库等	Memory Tree 自动同步
编程辅助	代码审查、Bug 修复、功能开发	完整编码工具集 + 118+ 集成
项目管理	跟踪任务、进度、团队协作	Linear/Jira 集成
邮件处理	自动分类、摘要、回复建议	Gmail 集成 + 智能分析
会议助手	实时转录、总结、行动项提取	Google Meet Agent + 语音模块
研究助手	网页抓取、内容摘要、知识整理	网络搜索 + TokenJuice 压缩

---

十二、未来展望

12.1 项目发展路线

┌──────────────────────────────────────────────────────────────┐
│                  OpenHuman 未来展望                          │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  短期（1-3 个月）：                                           │
│  ✓ 退出 Early Beta，发布稳定版                                │
│  ✓ 增加更多第三方集成（目标 200+）                            │
│  ✓ 优化 Memory Tree 检索性能                                 │
│  ✓ 改进 TokenJuice 压缩算法                                  │
│                                                              │
│  中期（3-6 个月）：                                           │
│  ✓ 支持更多本地 AI 模型                                       │
│  ✓ 增强语音交互体验（实时翻译、多语言）                       │
│  ✓ 推出移动端应用（iOS/Android）                              │
│  ✓ 集成更多 IDE（VSCode、JetBrains 等）                      │
│                                                              │
│  长期（6-12 个月）：                                          │
│  ✓ 构建插件生态系统                                            │
│  ✓ 支持企业级部署（LDAP/SSO 集成）                           │
│  ✓ 实现跨设备同步（端到端加密）                               │
│  ✓ 探索联邦学习（保护隐私的模型微调）                          │
│                                                              │
└──────────────────────────────────────────────────────────────┘

12.2 参与贡献

# 1. Fork 仓库
# 访问 https://github.com/tinyhumansai/openhuman/fork

# 2. 克隆你的 Fork
git clone https://github.com/<your-username>/openhuman.git
cd openhuman

# 3. 添加上游仓库
git remote add upstream https://github.com/tinyhumansai/openhuman.git

# 4. 创建功能分支
git checkout -b feature/my-feature

# 5. 进行更改
# ... 编辑代码 ...

# 6. 提交更改
git add .
git commit -m "feat: add my feature"

# 7. 推送到你的 Fork
git push origin feature/my-feature

# 8. 创建 Pull Request
# 访问 https://github.com/tinyhumansai/openhuman/compare

---

十三、总结

OpenHuman 是一个开创性的开源 AI 超级智能助手项目，它解决了传统 AI 助手需要从零开始学习用户的核心痛点。

核心优势回顾

1. 分钟级上下文获取：通过 auto-fetch 和 Memory Tree，无需数周训练期
2. 本地优先设计：保护用户隐私，数据归用户所有
3. 118+ 第三方集成：一键 OAuth 授权，自动同步数据
4. 智能 Token 压缩：TokenJuice 降低成本和延迟高达 80%
5. 模型路由自动化：根据任务类型自动选择最合适的 LLM
6. 开箱即用：内置网络搜索、网页抓取、编码工具集、原生语音

适用人群

• 开发者：需要整合多个代码仓库、项目管理工具的编程助手
• 知识工作者：需要管理邮件、笔记、文档、日历的多任务处理者
• 研究人员：需要网页抓取、内容摘要、知识整理的研究助手
• 隐私关注者：希望数据本地存储、不上传云端的注重隐私用户

开始使用

# 一键安装（macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

# 或访问官网下载
# https://tinyhumans.ai/openhuman

---

附录：常用命令速查表

A. 开发命令

命令	说明
pnpm dev	启动 Web UI 开发服务器
pnpm --filter openhuman-app dev:app	启动桌面 Shell 开发
pnpm typecheck	TypeScript 类型检查
pnpm lint	Lint 检查
pnpm format:check	代码格式检查
cargo check -p openhuman --lib	Rust 代码检查
pnpm test	运行测试
pnpm test:rust	运行 Rust 测试

B. Docker 命令

命令	说明
docker compose up -d	启动服务
docker compose down	停止服务
docker compose logs -f	查看日志
docker compose restart openhuman-core	重启服务
curl -fsSL http://localhost:7788/health	健康检查

C. 环境变量

变量名	必须	说明
OPENHUMAN_CORE_TOKEN	✅	Bearer 令牌
BACKEND_URL	✅	后端地址
OPENHUMAN_APP_ENV	可选	production 或 staging
OPENHUMAN_CORE_HOST	可选	默认 0.0.0.0
OPENHUMAN_CORE_PORT	可选	默认 7788
RUST_LOG	可选	日志级别

---

本文基于 OpenHuman GitHub 仓库（2026年5月）的公开信息整理，项目处于 Early Beta 阶段，具体实现可能随版本迭代而变化。

✨ 项目地址：github.com/tinyhumansa…

📚 官方文档：tinyhumans.gitbook.io/openhuman