一、项目概述
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 主要技术组件
typescript
复制代码
// 技术栈配置示例（基于项目分析）
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 步详解）
rust
复制代码
// 数据源：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 脚本命令
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 核心配置）
toml
复制代码
[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)
bash
复制代码
# 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash
# 安装后验证
openhuman --version
# 输出: openhuman v0.53.43
Windows (PowerShell)
powershell
复制代码
# 一键安装脚本
irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex
# 安装后验证
openhuman.exe --version
6.3 从源码构建（开发者）
步骤 1：安装依赖
bash
复制代码
# 系统依赖
## 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
bash
复制代码
# 安装 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
bash
复制代码
# 安装 pnpm (10.10.0)
npm install -g pnpm@10.10.0
# 验证安装
pnpm --version
# 输出: 10.10.0
步骤 4：克隆仓库并初始化
bash
复制代码
# 克隆仓库
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
# 初始化子模块（重要！）
git submodule update --init --recursive
# 安装 Node.js 依赖
pnpm install
步骤 5：启动开发服务器
bash
复制代码
# 仅 Web UI 开发
pnpm dev
# 桌面 Shell 开发（推荐）
pnpm --filter openhuman-app dev:app
# CEF 开发模式
pnpm dev:cef
# Windows 平台开发
pnpm dev:app:win
6.4 开发检查命令
bash
复制代码
# 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 数据结构
markdown
复制代码
# 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
自动抓取调度器配置
toml
复制代码
# config.toml
[auto_fetch]
# 同步间隔（分钟）
interval_minutes = 20
# 启用的集成
enabled_integrations = [
"gmail",
"github",
"notion",
"slack"
]
# 增量同步（仅拉取新数据）
incremental_sync = true
# 失败重试次数
max_retries = 3
7.3 TokenJuice 智能压缩
压缩策略详解
rust
复制代码
/// 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）
路由策略
rust
复制代码
/// 模型路由器
/// 根据任务类型自动选择最合适的模型
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> │ │
│ └──────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
步骤 1：一键部署
步骤 2：配置环境变量
yaml
复制代码
# .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：生成强密钥
bash
复制代码
# 生成 OPENHUMAN_CORE_TOKEN
openssl rand -hex 32
# 输出: 5a3c7f1e9d4b2a8f6c0e3d7b5a9c2f4e8b1d6a3c7f0e9d4b2a8f6c0e3d7b5a
# 在 DO 控制面板中设置
# Settings → App-Level Environment Variables → Add Variable
8.3 部署方式二：Docker Compose（推荐生产使用）
docker-compose.yml
yaml
复制代码
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
启动命令
bash
复制代码
# 克隆仓库
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
bash
复制代码
# 运行模式：连接外部核心
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 反向代理配置
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 中配置：
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 配置
toml
复制代码
# 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 模型路由配置
toml
复制代码
# 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 官方资源
10.2 社区渠道
10.3 创始人
十一、项目亮点总结
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 参与贡献
bash
复制代码
# 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 助手需要从零开始学习用户的核心痛点。
核心优势回顾
- 分钟级上下文获取：通过 auto-fetch 和 Memory Tree，无需数周训练期
- 本地优先设计：保护用户隐私，数据归用户所有
- 118+ 第三方集成：一键 OAuth 授权，自动同步数据
- 智能 Token 压缩：TokenJuice 降低成本和延迟高达 80%
- 模型路由自动化：根据任务类型自动选择最合适的 LLM
- 开箱即用：内置网络搜索、网页抓取、编码工具集、原生语音
适用人群
- 开发者：需要整合多个代码仓库、项目管理工具的编程助手
- 知识工作者：需要管理邮件、笔记、文档、日历的多任务处理者
- 研究人员：需要网页抓取、内容摘要、知识整理的研究助手
- 隐私关注者：希望数据本地存储、不上传云端的注重隐私用户
开始使用
bash
复制代码
# 一键安装（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 阶段，具体实现可能随版本迭代而变化。
✨ 项目地址：https://github.com/tinyhumansai/openhuman
📚 官方文档：https://tinyhumans.gitbook.io/openhuman