什么是自动抓取？​

自动抓取是 OpenHuman 提供的一种智能数据同步机制。它允许用户配置数据源后，系统会根据预设的调度策略自动拉取最新数据，无需人工干预。

核心特性​

• 定时调度：每 20 分钟自动执行一次数据抓取
• 增量更新：仅获取新增或变更的数据，避免重复处理
• 后台运行：与其他任务并行执行，不影响主流程
• 自动重试：网络异常时自动重试，保证数据完整性

自动抓取的工作原理​

自动抓取采用基于时间窗口的调度机制，确保数据始终保持新鲜。

调度周期​

默认调度周期为 20 分钟，这意味着：

1. 系统每 20 分钟检查一次配置的数据源
2. 发现新数据时自动触发抓取流程
3. 数据经过处理后写入目标存储

数据抓取流程​

数据源 → 调度器（20分钟周期）→ 抓取引擎 → 数据处理 → 写入存储

1. 配置阶段：用户设定需要抓取的数据源 URL 和认证信息
2. 调度阶段：内置调度器按设定周期触发抓取任务
3. 执行阶段：抓取引擎访问数据源，下载最新内容
4. 处理阶段：对数据进行解析、清洗和格式转换
5. 存储阶段：将处理后的数据写入本地知识库

20 分钟调度机制的优势​

20 分钟是一个经过优化的周期，既能保证数据时效性，又不会对数据源造成过大压力。相比实时同步，它更加轻量；相比每日同步，它又能提供足够新鲜的数据。

支持自动抓取的数据源​

OpenHuman 自动抓取功能支持多种主流数据源类型：

网页内容​

• 静态网页：HTML 页面自动解析
• 动态内容：JavaScript 渲染页面支持
• RSS/Atom：博客和新闻订阅源

文档格式​

• Markdown：直接解析并入库
• PDF：文本提取后同步
• Word 文档：docx 格式支持

API 接口​

• REST API：JSON 格式数据自动抓取
• GraphQL：支持自定义查询的数据源

如何配置自动抓取​

基础配置示例​

const fetchConfig = {
  url: 'https://api.example.com/data',
  schedule: '*/20 * * * *',  // 每20分钟
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN
  },
  transform: (data) => {
    return data.items.map(item => ({
      id: item.id,
      content: item.text,
      timestamp: new Date(item.updatedAt)
    }));
  }
};

await client.autoFetch.create(fetchConfig);

调度策略自定义​

如果 20 分钟的默认周期不满足需求，你可以调整调度频率：

// 每小时抓取一次
const hourlyConfig = {
  schedule: '0 * * * *',  // 每小时整点
  // ...
};

// 每日凌晨抓取
const dailyConfig = {
  schedule: '0 2 * * *',   // 每天凌晨2点
  // ...
};

自动抓取的最佳实践​

1. 合理选择调度周期​

根据数据源的更新频率选择合适的调度周期：

• 高频更新源（如新闻、社交媒体）：建议 15-20 分钟
• 低频更新源（如文档、静态内容）：建议 60 分钟或更长

2. 配置增量抓取​

启用增量模式避免重复处理：

const config = {
  // ... 其他配置
  incremental: true,
  lastFetchedAt: await getLastFetchTimestamp()
};

3. 错误处理与重试​

配置自动重试机制保证稳定性：

const config = {
  // ... 其他配置
  retry: {
    maxAttempts: 3,
    backoff: 'exponential'
  }
};

4. 监控抓取状态​

定期检查抓取任务的执行状态：

const status = await client.autoFetch.getStatus(fetchId);
console.log(`上次抓取: ${status.lastRunAt}`);
console.log(`抓取结果: ${status.itemsFetched} 条`);
console.log(`状态: ${status.status}`);

常见问题​

Q: 自动抓取会消耗很多资源吗？​

不会。自动抓取采用轻量级调度机制，每次抓取任务完成后即释放资源。只有在调度周期触发时才会占用少量 CPU 和网络资源。

Q: 如果数据源需要认证怎么办？​

OpenHuman 支持多种认证方式：API Key、Bearer Token、Basic Auth、OAuth 2.0，可根据数据源要求选择合适的认证方式。

Q: 可以同时配置多个数据源吗？​

可以。系统支持并行抓取多个数据源，只需为每个数据源创建独立的抓取配置即可。

Q: 抓取失败了怎么办？​

系统会自动记录失败原因，并在下一个调度周期重试。如果持续失败，会发送通知提醒你检查配置。

总结​

OpenHuman 的自动抓取功能通过智能定时调度，让 AI 数据同步变得简单高效。20 分钟的默认调度周期在数据时效性和系统资源消耗之间取得了良好平衡，配合增量更新和自动重试机制，确保你的知识库始终保持最新状态。

立即配置自动抓取，让 AI 在你睡觉时为你完成数据同步工作。

想了解更多 OpenHuman 使用技巧？查看 OpenHuman Agent 设计模式 深入学习最佳实践。

OpenHuman 给出了不同的答案。作为新一代 AI 个人助手，OpenHuman 采用「本地优先」（Local-First）的架构设计，默认将数据保存在你的设备上，只有在你明确授权时才会进行必要的云端同步。这种设计理念从根本上改变了数据归属权——你的数据，始终是你的。

为什么本地存储比云端更安全​

要理解 OpenHuman 的安全优势，首先需要了解云端 AI 的潜在风险。

传统云端 AI 的数据困境​

当你使用传统云端 AI 服务时，你的数据通常会经历以下过程：

1. 上传至服务器：你的输入内容被传输到第三方服务器
2. 云端处理：数据在远程服务器上进行存储和处理
3. 可能用于训练：部分服务商会将数据用于模型训练
4. 长期留存：数据何时删除、是否彻底删除，你无法确认

这意味着你的私人对话、商业计划、健康信息——都可能留存在他人的服务器上。即便服务商承诺不用于训练，你也无法独立验证。

本地存储的核心优势​

OpenHuman 的本地优先架构从根本上规避了这些风险：

数据不离设备：所有处理都在本地完成，你的敏感信息从不离开你的设备

无云端依赖：核心功能在离线状态下同样可用，不需要时刻保持网络连接

独立验证：你可以通过开源代码自行验证数据处理逻辑，不需要信任服务商承诺

最小化传输：即便需要云端能力，也只传输必要的脱敏数据

OpenHuman 的隐私保护设计​

OpenHuman 从架构设计到功能实现，都将隐私保护作为核心原则，而非后期添加的可选项。

端到端加密通信​

当你使用 OpenHuman 的云端同步功能时，所有数据传输均采用端到端加密。这意味着即便数据在传输过程中被截获，攻击者也无法解读其内容。加密密钥仅存储在你本地设备，其他任何方——包括 OpenHuman 服务端——都无法解密你的数据。

隐私模式：双层保护​

OpenHuman 提供专门的隐私模式，带来了额外的保护层：

• 增强隐私保护：隐私模式开启后，OpenHuman 不会保存任何对话记录
• 临时处理：所有输入在处理完成后立即从内存中清除
• 无日志记录：隐私模式下不产生任何可追溯的操作日志

适合场景：处理敏感财务信息、医疗记录、法律文档，或任何你不希望留下任何痕迹的对话。

细粒度权限控制​

OpenHuman 的集成权限管理允许你精确控制每个第三方服务的访问范围：

• 每次授权都有明确的权限范围说明
• 可以随时在设置中查看和撤销已授权的集成
• 支持设置临时授权，过期后自动失效

数据分类：清楚知道你的数据去哪了​

OpenHuman 将数据分为三类，明确告诉你每类数据的处理方式：

本地数据：完全存储在本地设备，不会上传至任何服务器。包括：本地文档、笔记、任务列表。本地 AI 模型处理的所有数据。

同步数据：经你明确授权后，在加密状态下与你授权的设备同步。包括：跨设备工作进度、配置偏好。云端同步采用零知识加密，服务端无法解读内容。

可选分享数据：当你主动使用特定功能时才会传输的数据。包括：使用云端 AI 模型时的输入内容（仅用于生成回答）。第三方集成的授权数据（可随时撤销）。

这种清晰的分类让你对数据流向一目了然，不再需要对隐私状态感到模糊和焦虑。

企业级安全：适合商业环境使用​

OpenHuman 的隐私设计同样适合对数据安全有高要求的企业环境：

本地部署选项：企业可以选择完整的本地部署方案，所有数据完全在企业内部网络中流转

合规性支持：满足 GDPR、数据本地化等各类数据保护法规要求

审计日志：提供完整的操作审计记录，方便企业进行安全合规审查

团队权限管理：细粒度的团队成员权限控制，确保只有需要访问的人才能接触敏感数据

开始保护你的数据隐私​

OpenHuman 默认启用本地优先模式，你无需进行额外配置即可享受隐私保护。如果你需要更高的隐私保障，可以随时在设置中开启隐私模式。

数据安全是一场持续的战斗，OpenHuman 致力于让隐私保护成为每个用户的默认权利，而非需要昂贵代价才能获得的奢侈品。选择本地优先的 AI，就是选择对自己数据的完全掌控权。

想了解 OpenHuman 的完整安全特性？查看我们的安全白皮书获取详细技术说明。

为什么集成能大幅提升工作效率​

当你需要在多个工具之间来回切换时，每次切换都伴随着注意力损耗。研究表明，频繁切换任务会让工作效率降低高达 40%。OpenHuman 集成通过统一入口，让你可以在一个界面完成所有操作：

• 信息聚合：所有重要通知、邮件、消息聚合在一个地方
• 操作统一：无需离开 OpenHuman 即可完成跨应用操作
• 自动化流程：设置触发条件，自动执行跨应用任务

更重要的是，OpenHuman 的集成采用业界标准的 OAuth 2.0 协议，你在任何时候都可以撤销授权，数据访问权限完全掌握在自己手中。

如何通过 OAuth 一键连接第三方服务​

OAuth（开放授权）是一种安全的授权标准，允许第三方应用在不获取你密码的情况下访问你的数据。OpenHuman 集成正是基于这一标准，确保最高级别的安全性。

连接步骤（以 Gmail 为例）​

1. 进入集成设置：在 OpenHuman 侧边栏点击「设置」→「集成」
2. 选择服务：找到 Gmail，点击「连接」
3. 授权确认：系统会跳转到 Google 授权页面，点击「允许」
4. 完成配置：返回 OpenHuman，开始使用

整个过程不超过 2 分钟，且你随时可以在 Google 账户设置中撤销 OpenHuman 的访问权限。

支持的主要集成服务​

OpenHuman 目前支持以下主流服务的集成：

生产力工具

• Gmail / Google Workspace：邮件管理、日历同步
• Notion：文档查阅、数据库同步
• Slack：消息通知、频道管理
• Microsoft 365：Outlook 邮件、Teams 消息

协作与文档

• Google Docs / Sheets：文档实时协作
• Dropbox：文件存储与分享
• OneDrive：微软生态文件管理

通信与会议

• Zoom：会议安排、入会链接
• Google Meet：视频会议集成

每个集成都遵循最小权限原则，OpenHuman 仅申请实现功能所必需的数据访问权限，绝不超范围收集用户信息。

OpenHuman 集成的独特优势​

安全优先的架构设计​

市面上许多集成工具要求你提供账户密码，这种方式存在严重安全隐患。OpenHuman 所有集成均基于 OAuth 2.0，不存储任何第三方服务的密码，你可以在任何时候检查和撤销已授权的应用。

灵活的触发与自动化​

你可以设置自动化规则，让 OpenHuman 根据特定条件执行操作。例如：

• 新邮件主题包含「报价」时，自动推送到 Slack
• Notion 数据库更新时，发送企业微信通知
• 日历有会议时，提前 5 分钟在系统托盘提醒

统一的用户体验​

无论连接了多少服务，OpenHuman 保持统一的界面设计风格和交互逻辑。你不需要为每个服务学习不同的操作方式，在 OpenHuman 中，一切操作都保持一致。

隐私控制：你的数据你做主​

OpenHuman 集成页面提供了清晰的权限管理视图。你可以：

• 查看当前已连接的所有服务
• 单个撤销不再需要的授权
• 设置哪些数据可以同步，哪些保持本地
• 查看每次数据访问的时间戳记录

这种透明化管理让你对个人信息拥有完全的控制权。

开始使用：3 步搭建你的集成工作流​

第一步：打开 OpenHuman，点击左侧「设置」→「集成管理」

第二步：浏览支持的服务列表，点击你想要连接的服务

第三步：完成 OAuth 授权，配置同步偏好，开始体验无缝工作流

集成是提升工作效率的关键一步。花费 5 分钟配置好你的第一个集成，你会发现每天节省的时间远比这多得多。立即体验 OpenHuman 集成，让工作更专注、更高效。

想了解更多 OpenHuman 功能？欢迎访问我们的官方文档获取完整指南。

为什么选择 Obsidian？​

Obsidian 的核心优势在于其灵活性和可扩展性：

本地优先，数据自主​

所有笔记存储在本地文件夹中，你可以完全掌控自己的数据。不用担心云服务涨价或停运，也不用担心隐私泄露。Markdown 格式确保了数据的长期可读性。

双向链接，知识网络​

Obsidian 的双向链接功能让你可以轻松建立知识点之间的关联。当你在笔记中引用其他笔记时，系统会自动创建反向链接，帮助你发现知识盲区，构建知识网络。

丰富插件生态​

Obsidian 拥有庞大的插件社区，涵盖了知识图谱、日历视图、看板等多种功能。你可以根据自己的需求，打造专属的知识管理系统。

OpenHuman 与 Obsidian 的完美结合​

OpenHuman 提供了强大的 Obsidian 集成功能，实现了人与 AI 知识库的双向同步。

核心功能特性​

• 双向同步：Obsidian 笔记与 AI 知识库实时同步
• 智能标签：自动为笔记添加分类标签
• 知识抽取：AI 自动识别并提取关键信息
• 关联推荐：基于内容智能推荐相关笔记

工作流程示意​

用户笔记 → OpenHuman 解析 → 知识图谱更新
    ↑                              ↓
    ← 智能推荐 ←←←←←←←←←←←←←←←←←←←

快速开始：5 分钟配置集成​

第一步：安装 OpenHuman 插件​

在 Obsidian 的社区插件市场中搜索「OpenHuman」，点击安装并启用。

第二步：连接知识库​

1. 打开 OpenHuman 设置页面
2. 进入「集成」→「Obsidian」选项
3. 点击「连接新保险库」
4. 选择你的 Obsidian 笔记库文件夹

第三步：配置同步选项​

openhuman_sync:
  vault_path: "D:/Obsidian/MyVault"
  auto_sync: true
  sync_interval: 5  # 分钟
  sync_direction: "bidirectional"
  exclude_patterns:
    - "**/Templates/**"
    - "**/.obsidian/**"

第四步：开始使用​

配置完成后，OpenHuman 会自动扫描你的笔记库，建立索引并开始同步。你可以在 AI 对话中直接引用 Obsidian 中的笔记内容。

双向同步如何工作​

同步机制详解​

从 Obsidian 到 OpenHuman​

当你在 Obsidian 中创建或修改笔记时：

1. 变更检测：插件监控笔记文件的修改
2. 格式解析：提取 Markdown 内容、元数据和链接关系
3. 知识入库：更新 OpenHuman 知识图谱
4. 关联更新：重新计算笔记间的关联度

从 OpenHuman 到 Obsidian​

当 AI 生成新知识或建议时：

1. 内容生成：AI 根据上下文生成知识建议
2. 格式转换：将 AI 内容转换为 Markdown 格式
3. 位置推荐：基于现有笔记关系推荐存放位置
4. 用户确认：用户确认后写入 Obsidian

冲突处理​

当同一笔记在两端同时修改时：

• 智能合并：尝试自动合并不冲突的修改
• 冲突提示：无法自动合并时，提示用户手动解决
• 版本历史：保留修改历史，随时可回溯

进阶使用技巧​

利用知识图谱发现关联​

启用知识图谱视图后，你可以直观地看到笔记之间的关联网络。这有助于发现隐藏的知识连接，激发新的思考。

智能模板提升效率​

创建标准化的笔记模板，让 AI 能够更好地理解和处理你的笔记内容：

---
type: concept
tags: [领域标签]
related:
  - [[相关笔记1]]
  - [[相关笔记2]]
created: {{date}}
summary: 一句话描述
---

# 标题

## 定义
## 例子
## 关联

定期整理与 AI 对话​

每隔一段时间，用 AI 帮你梳理近期笔记，发现知识盲点并提出改进建议。这是一种高效的主动学习方法。

实际应用场景​

个人知识库管理​

将你的阅读笔记、学习心得、项目文档统一管理。AI 可以帮你快速检索、总结和关联。

研究与写作​

在撰写论文或博客时，快速调用相关资料。AI 会理解你的写作风格，保持内容一致性。

团队知识共享​

团队成员共享一个 Obsidian 库，OpenHuman 帮助整合每个人的知识贡献，形成团队智慧库。

常见问题​

Q: 同步会影响 Obsidian 性能吗？​

A: OpenHuman 采用增量同步，只处理变更的文件。日常使用中几乎不会影响 Obsidian 的响应速度。

Q: 我的笔记安全吗？​

A: 所有数据存储在本地，OpenHuman 不会上传你的笔记内容到第三方服务器。

Q: 支持同步到多个设备吗？​

A: 支持。请使用 Obsidian 官方同步服务或 Syncthing 等工具同步本地文件，OpenHuman 会自动适配。

总结​

OpenHuman 与 Obsidian 的集成，为知识管理带来了 AI 赋能的可能性。通过双向同步，你可以：

• 充分利用本地优先的隐私优势
• 借助 AI 能力挖掘知识价值
• 构建真正属于你自己的「第二大脑」

立即开始使用，将你的 Obsidian 笔记库与 OpenHuman 连接，开启智能知识管理的新体验！

想了解更多集成方案，请查阅我们的集成文档或加入社区讨论。

什么是 Model Routing？​

Model Routing 是 OpenHuman 的核心特性之一，它允许系统根据输入任务的特征自动分配最适合的 AI 模型。不同于传统的固定模型调用，路由机制会分析任务需求，考虑以下因素：

• 任务复杂度：简单问答 vs 复杂推理
• 响应时间要求：需要快速响应还是允许较长等待
• 成本优化：在保证质量的前提下控制 token 消耗
• 上下文长度：短文本处理 vs 长文档分析

通过智能路由，OpenHuman 可以在保证任务质量的同时，显著降低不必要的成本支出。

hint 指令：精准控制模型选择​

OpenHuman 提供了 hint 指令系统，让开发者可以精确控制模型选择行为。hint 是写在任务描述中的特殊标记，格式为 hint:xxx。

常见的 hint 指令​

hint:reasoning   # 启用深度推理模式，适合复杂逻辑分析
hint:fast        # 启用快速响应模式，适合简单任务
hint:creative    # 启用创意模式，适合写作、创意任务
hint:precise     # 启用精确模式，适合需要高准确率的场景

使用示例​

当你需要模型进行复杂的数学推理时，可以使用：

请帮我解决这道数学题 hint:reasoning

题目：一个完全图 K5 有多少条不同的哈密顿回路？

系统会自动识别 hint:reasoning 指令，分配具备强推理能力的模型进行处理。

Model Routing 的工作原理​

OpenHuman 的模型路由系统包含以下核心组件：

1. 任务分类器​

任务分类器分析输入文本，识别任务类型和特征：

• 分析阶段：解析任务描述，提取关键信息
• 分类阶段：将任务归类到预设的类别（推理、创作、问答等）
• 优先级排序：根据多个维度对任务进行评估

2. 模型池管理​

OpenHuman 维护一个模型池，包含多种不同特性的模型：

3. 动态调度器​

动态调度器根据任务特征和模型状态，做出最优分配决策：

• 实时监控：跟踪各模型的负载和响应时间
• 智能排队：优化任务分配，减少等待时间
• 故障转移：模型不可用时自动切换

如何配置默认路由策略​

在 OpenHuman 配置文件中，你可以设置默认的路由策略：

model_routing:
  default_strategy: "auto"  # auto | fast | balanced | quality
  fallback_enabled: true
  custom_hints:
    enabled: true
    priority: "user"  # user > system > default

策略选项说明​

• auto：系统自动选择最优模型
• fast：优先选择高速模型
• balanced：平衡速度和质量
• quality：优先保证输出质量

实践建议​

充分利用 hint 指令​

对于关键任务，主动使用 hint 指令可以获得更好的结果。例如，在进行代码审查时使用 hint:reasoning 可以获得更深入的分析。

根据场景选择策略​

监控和调优​

定期查看路由统计，了解模型使用分布，根据实际效果调整策略配置。

总结​

Model Routing 是 OpenHuman 提升 AI 应用效率的关键特性。通过合理使用 hint 指令和配置路由策略，开发者可以在保证任务质量的同时，实现成本优化和性能提升。

掌握模型路由的原理和使用技巧，将帮助你构建更加智能、高效的 AI 应用。开始探索 OpenHuman 的模型路由功能，解锁 AI 应用的无限可能！

如果你有任何问题，欢迎在 GitHub 仓库中提交 Issue 或参与社区讨论。

什么是 TokenJuice？​

TokenJuice 是 OpenHuman 自主研发的智能文本压缩技术，专门针对 AI 提示词（Prompt）和上下文内容进行优化。与通用的 gzip 或 zstd 压缩算法不同，TokenJuice 的设计目标是：

• 保持语义完整性：压缩后的文本仍能被 LLM 正确理解
• 保留关键指令：系统提示和约束条件完整保留
• 自适应压缩比：根据内容类型动态调整压缩强度

Token 压缩如何工作​

TokenJuice 采用三层压缩架构：

第一层：结构化压缩​

识别文本中的结构化元素（JSON、Markdown、表格、代码块），对非核心内容进行精简：

原文：The user asked us to "please calculate the total revenue 
      for Q1 2025 which includes January, February, and March"
      
压缩后：Q1 2025 营收总计（含 1-3 月）

第二层：语义压缩​

使用小型专用模型识别并合并语义重复的内容，移除冗余修饰词：

原文：In order to effectively and efficiently process the 
      aforementioned request in a timely manner...
      
压缩后：处理上述请求

第三层：上下文感知压缩​

根据对话历史和任务类型，动态决定哪些信息需要完整保留，哪些可以精简：

• 保留：关键数字、日期、人名、明确的指令
• 精简：重复的解释、显而易见的推导、通用礼貌用语

实际效果测试​

我们在多个场景下进行了基准测试：

关键发现：压缩效果与内容类型高度相关。结构化程度高、重复内容多的文本，压缩效果最好。

适用场景与限制​

最适合的场景​

1. 长文档处理：分析一篇 50 页的 PDF 报告，Token 消耗可降低一半以上
2. 多轮对话：在长程对话中压缩历史消息，保持上下文同时控制成本
3. 批量处理：对大量相似文档进行结构化提取

不适合的场景​

1. 诗歌创作：需要保持原文韵律和风格，压缩会破坏创意表达
2. 精确代码生成：压缩可能影响代码的可读性和安全性
3. 实时口语转写：需要保留原始表达方式和口语特征

节省成本计算​

以 GPT-4o 的定价为基准（$15/1M 输出 Token）：

• 未使用 TokenJuice：每月 100 万次 API 调用，平均每次消耗 500 Token = $7,500/月
• 使用 TokenJuice（55% 压缩率）：相同调用量消耗 225 Token = $3,375/月
• 每月节省：$4,125（约 55%）

对于大型企业用户，这意味着每年可节省超过 50 万美元的 AI 成本。

如何集成到项目​

TokenJuice 提供多种集成方式：

Node.js SDK​

import { TokenJuice } from '@openhuman/tokenjuice';

const compressor = new TokenJuice({
  level: 'balanced', // 'aggressive' | 'balanced' | 'conservative'
  preserveStructure: true,
});

const compressed = await compressor.compress(longPrompt);
const response = await openai.chat.completions.create({
  messages: [{ role: 'user', content: compressed }],
});

OpenAI 兼容 API 代理​

对于已有代码不想大规模修改的团队，可以部署 TokenJuice API 代理：

npm install @openhuman/tokenjuice-proxy

# 启动代理
tokenjuice-proxy --port 8080 --api-key $OPENAI_API_KEY

然后将所有 API 请求发送到 http://localhost:8080，代理会自动进行压缩和解压。

最佳实践​

1. 分层压缩策略​

不要对所有内容采用同一压缩级别：

const messages = [
  { role: 'system', content: systemPrompt, compress: false },
  { role: 'user', content: userQuery, compress: 'conservative' },
  { role: 'assistant', content: historyMessages, compress: 'aggressive' },
];

2. 保持关键约束​

确保系统提示中的安全约束和核心指令不被压缩：

const config = {
  preservePatterns: [
    /never|always|必须|禁止/i,
    /privacy|safety|安全|隐私/i,
  ],
};

3. 监控压缩质量​

定期检查压缩后的输出质量：

const quality = await compressor.evaluate(original, compressed);
if (quality.semantic_similarity < 0.85) {
  console.warn('压缩质量下降，建议降低压缩级别');
}

常见问题​

Q: 压缩会不会影响 AI 的回答质量？

A: 在我们的测试中，使用 balanced 级别压缩时，回答质量几乎不受影响（语义相似度 > 95%）。但对于需要精确记忆的场景，建议使用 conservative 级别。

Q: 压缩会增加延迟吗？

A: TokenJuice 的压缩和解压总延迟约为 5-15ms，对于大多数应用来说可以忽略不计。

Q: 支持中文压缩吗？

A: 完全支持。TokenJuice 专门优化了中文语义压缩，效果与英文相当。

总结​

TokenJuice 为 AI 应用开发者提供了一种实用的成本优化工具。通过智能的三层压缩架构，可以在保持核心语义的同时大幅减少 Token 消耗。结合合理的集成策略，大多数应用都能实现 50% 以上的成本节省。

立即开始使用 TokenJuice，您可以在 OpenHuman Dashboard 中申请试用，或查看我们的 开源实现 自行部署。

什么是记忆树？​

记忆树是 OpenHuman 设计的层次化知识存储结构。它不像传统向量数据库那样将所有内容扁平化存储，而是将信息组织成树状层级：

• 根节点：存储核心身份信息和通用知识
• 分支节点：按主题或领域分类的知识点
• 叶节点：具体的对话片段、事实和引用

这种层级结构使得记忆的检索和更新更加精确，也更符合人类组织知识的方式。

为什么选择 SQLite 而不是向量数据库？​

很多 AI 系统依赖向量数据库（如 Pinecone、Milvus）来存储记忆，但这种方案存在明显缺陷：

SQLite 的引入让记忆树实现了真正的本地化部署，数据永远不会离开您的服务器。对于需要处理敏感数据的企业来说，这一点至关重要。

语义搜索的工作原理​

记忆树的语义搜索结合了两种技术：

1. 嵌入向量相似度搜索 每个记忆片段都会被编码成向量，当您查询「上次讨论的 Python 性能优化方案」时，系统会找到语义最相关的记忆节点。

2. SQLite FTS5 全文搜索 对于需要精确关键词匹配的场景（如搜索特定函数名、日期、人名），FTS5 提供了毫秒级的全文检索能力。

两者结合，确保既能量化语义相似度，又能在需要时精确定位。

与 Obsidian 的深度集成​

对于习惯使用 Obsidian 进行知识管理的用户，OpenHuman 提供了双向同步功能：

• 导入：将 Obsidian 笔记库同步到记忆树作为背景知识
• 导出：将 AI 生成的内容自动写回 Obsidian 笔记
• 实时同步：双向同步确保两边数据一致

# obsidian-sync 配置示例
memory-tree:
  obsidian:
    vault-path: ~/Obsidian/my-knowledge-base
    sync-direction: bidirectional
    sync-interval: 5m
    included-folders:
      - 工作笔记
      - 项目文档

这种集成让您可以在 Obsidian 中用熟悉的 Markdown 语法管理知识，同时让 AI 能够访问和增强这些内容。

实际应用场景​

1. 个人数字分身​

将您的笔记、邮件、日程整合到记忆树中，AI 助手就能了解您的偏好、习惯和工作背景，提供真正个性化的服务。

2. 企业知识库​

将产品文档、客服记录、内部流程导入记忆树，构建一个永不遗忘的企业大脑。新员工可以随时向 AI 咨询公司规范和历史决策。

3. 研究助手​

论文、实验数据、文献笔记全部纳入记忆树，AI 可以帮您发现跨论文的联系，追踪研究脉络。

性能与限制​

单节点 SQLite 适合个人和小型团队使用。经过测试：

• 10 万条记忆条目：查询时间 < 10ms
• 100 万条记忆条目：查询时间 < 50ms
• 最大存储容量：受磁盘空间限制，理论无上限

对于需要处理千万级记忆的企业场景，OpenHuman 正在开发分布式记忆树方案。

快速开始​

在 OpenHuman 项目中启用记忆树只需几步：

import { MemoryTree } from '@openhuman/core';

const memory = new MemoryTree({
  storage: './data/memory.db',
  maxAge: '90d', // 自动清理 90 天前的记忆
  embeddingModel: 'text-embedding-3-small',
});

await memory.initialize();

总结​

记忆树代表了 AI 知识管理的新方向——本地化、层次化、可解释。相比向量数据库，它提供了更好的隐私保护、更低的延迟和更低的成本。结合 Obsidian 的双向同步，它能够融入您现有的知识管理工作流，成为真正的第二大脑。

下一步，您可以阅读我们的 API 参考文档 了解更多配置选项，或在 GitHub 上查看 开源实现 参与社区贡献。

1. 单一职责模式​

每个 Agent 应该只负责一个明确的职责。

const translator = await client.agents.create({
  name: '翻译助手',
  instructions: '你是一个专业的翻译，将中文翻译成英文。',
});

const summarizer = await client.agents.create({
  name: '摘要助手',
  instructions: '你是一个专业的摘要生成器，总结文章要点。',
});

2. 链式调用模式​

将复杂任务分解为多个步骤：

const chain = await client.chains.create({
  name: '研究链',
  steps: [
    { type: 'agent', agentId: searchAgent.id },
    { type: 'agent', agentId: analyzeAgent.id },
    { type: 'agent', agentId: reportAgent.id },
  ],
});

const result = await client.chains.run(chain.id, {
  input: 'AI Agent 发展趋势',
});

3. 并行处理模式​

多个独立任务并行执行：

const results = await Promise.all([
  client.agents.run(agent1.id, { message: '任务1' }),
  client.agents.run(agent2.id, { message: '任务2' }),
  client.agents.run(agent3.id, { message: '任务3' }),
]);

避坑指南​

不要让 Agent 做太多事​

const agent = await client.agents.create({
  instructions: `
    你是一个代码审查助手。
    你的职责：检查代码质量、发现潜在 bug、提出改进建议。
    限制：只做代码审查，不做其他事。
  `,
});

不要忽略错误处理​

try {
  const response = await client.agents.run(agent.id, {
    message: '用户输入',
  });
} catch (error) {
  if (error.code === 'rate_limit') {
    await sleep(60000);
    return retry();
  }
  console.error('Agent 执行失败:', error);
  return { error: '服务暂时不可用，请稍后重试' };
}

性能优化​

1. 缓存常用响应​

const cache = new Map();

async function getCachedResponse(key, factory) {
  if (cache.has(key)) {
    return cache.get(key);
  }
  const result = await factory();
  cache.set(key, result);
  return result;
}

2. 批量处理​

async function processBatch(items, batchSize = 10) {
  const results = [];
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(item => processItem(item))
    );
    results.push(...batchResults);
  }
  return results;
}

安全实践​

输入验证​

function sanitizeInput(input) {
  if (typeof input !== 'string') {
    throw new Error('输入必须是字符串');
  }
  return input.slice(0, 10000).replace(/[<>]/g, '');
}

速率限制​

const rateLimiter = new Map();

function checkRateLimit(userId) {
  const now = Date.now();
  const window = 60000;
  const maxRequests = 10;

  const record = rateLimiter.get(userId) || { count: 0, resetAt: now + window };

  if (now > record.resetAt) {
    record.count = 0;
    record.resetAt = now + window;
  }

  record.count++;
  rateLimiter.set(userId, record);

  return record.count <= maxRequests;
}

总结​

好的 Agent 设计应该：单一职责、错误处理、上下文管理、性能优化、安全第一。希望这些设计模式对您有帮助！

在开始之前，请确保您具备以下条件：Node.js 18+ 已安装、OpenHuman 账号和 API 密钥、基础的 JavaScript 知识。

第一步：安装 SDK​

打开终端，运行以下命令安装 OpenHuman SDK：

npm install openhuman-sdk

第二步：获取 API 密钥​

1. 访问 OpenHuman Dashboard
2. 注册账号并登录
3. 进入「设置」「API 密钥」
4. 点击「创建新密钥」并复制

第三步：创建项目​

创建一个新目录并初始化项目：

mkdir my-openhuman-agent
cd my-openhuman-agent
npm init -y
npm install openhuman-sdk dotenv

创建 .env 文件存储密钥：

OPENHUMAN_API_KEY=your_api_key_here

第四步：编写代码​

创建 index.js 文件：

import 'dotenv/config';
import { OpenHuman } from 'openhuman-sdk';

const client = new OpenHuman({
  apiKey: process.env.OPENHUMAN_API_KEY,
});

async function main() {
  const agent = await client.agents.create({
    name: '我的第一个助手',
    description: '一个友好的问答助手',
    instructions: '你是一个友好的助手，用简洁的语言回答用户问题。',
  });

  console.log('Agent 创建成功');
  console.log('Agent ID:', agent.id);

  const response = await client.agents.run(agent.id, {
    message: '你好，请介绍一下你自己',
  });

  console.log('Agent 响应:', response.message);
}

main().catch(console.error);

第五步：运行​

node index.js

常用操作​

给 Agent 添加工具​

const agent = await client.agents.create({
  name: '研究助手',
  instructions: '你是一个研究助手，帮助用户查找和分析信息。',
  tools: ['web-search', 'calculator'],
});

管理会话​

const session = await client.sessions.create({
  agentId: agent.id,
});

await client.sessions.sendMessage(session.id, {
  content: '你好',
});

const messages = await client.sessions.getMessages(session.id);

下一步​

• 阅读配置指南了解更多配置选项
• 学习基本使用掌握更多功能
• 探索高级功能

祝您开发愉快！

我们提供什么​

• 完整的中文文档：涵盖从入门到高级的所有内容
• 实用的教程：来自实战经验的详细指南
• 最新的资讯：同步官方更新，及时发布相关内容
• 活跃的社区：开发者交流和问题解答

文档结构​

• 快速开始：安装配置、快速开始、配置指南
• 核心概念：架构概述、核心组件、数据流
• 功能教程：基本使用、高级功能、系统集成
• API 文档：API 概述、端点列表、认证机制
• 部署指南：Cloudflare Pages、Docker、Vercel
• 常见问题：故障排除、最佳实践

未来计划​

• 英文版本开发
• 更多语言支持（日语、韩语等）
• 视频教程
• 交互式示例

参与贡献​

我们欢迎任何人参与贡献！访问 GitHub 仓库 开始贡献。

感谢您的支持！