Gliding Horse 给 Agent OS 装上双曲空间引擎与默克尔树边云同步

摘要：本文深入探讨如何将双曲面空间向量检索（HyperspaceEngine）与默克尔树边‑云差分同步协议集成到 Gliding Horse（流马）Agent OS 中。通过双曲几何（Poincaré/Lorentz）实现技能图谱的层次化低维嵌入，将向量维度从 768 降至 64，内存占用减少 90%+；利用 256 桶默克尔树实现边端与云端的高效增量同步，仅传输变更部分；结合锁无关架构与 L0 热缓存，将热点检索延迟降至亚微秒级。方案为多 Agent、多阶段、联邦化工程平台提供了统一的空间记忆引擎，显著提升层次感知检索精度、边端离线能力与联邦一致性。

关键词：Gliding Horse；Agent OS；双曲空间向量检索；默克尔树；边云同步；技能图谱；Poincaré嵌入；联邦架构

构建 Gliding Horse（流马）的过程中，我一直在寻找一种能完美匹配其 Agent OS 架构的向量存储与检索方案。传统向量数据库如 Qdrant 虽能胜任语义搜索，但在层次化知识表征、边端离线同步以及实时写入加速方面，难以满足一个多 Agent、多阶段、联邦化工程平台的全部需求。

直到我发现了双曲面空间向量检索的优势——为自主智能体和机器人打造的 空间 AI 引擎。双曲几何（Poincaré、Lorentz），拥有锁无关架构带来的极致性能，并且内置了基于默克尔树（Merkle Tree）的边‑云差分同步协议。与 Gliding Horse 的技能图谱层次化组织、分层联邦架构以及边缘端部署场景高度契合。

本文将介绍如何将双曲面空间向量检索的核心能力移植到 Gliding Horse 中，形成一个统一、高效且具备离线同步能力的空间记忆引擎。

一、双曲面空间向量检索的核心技术优势

双曲面空间向量检索+默克尔树特性简直就是面向自主智能体的空间记忆基础设施。其关键特性包括：

1. 双曲几何： Poincaré Ball 和 Lorentz Hyperboloid 度量，能以极低维度（如 64 维）高效嵌入大规模层次结构（代码 AST、分类体系等），内存占用仅为欧氏空间的 1/50，同时保持语义结构。
2. 锁无关架构与 L0 热缓存：基于 ArcSwap 的无锁读取路径，配合 L1 DashMap 精确缓存（~1 µs）和 L2 HNSW 近似缓存（~100 µs），实现超高吞吐和低延迟。
3. 实时写入缓冲：插入即搜索，后台异步构建 HNSW 图，保证写入延迟接近零。
4. 默克尔树 Delta Sync：采用 256 桶的默克尔树进行数据分片，通过比对桶哈希实现差分同步，仅传输变更部分，极大节省带宽，尤其适合边‑云或 WASM 离线场景。
5. 量化与压缩：各向异性标量量化（SQ8）等可在 8 倍压缩下保持高召回率。

这些特性解决了 Gliding Horse 的几个核心挑战：技能图谱的层次化存储、大规模知识库的低延迟检索、以及联邦架构下边端与云端的知识同步。

二、Gliding Horse 的契合点

Gliding Horse 是一个用 Rust 编写的 AI Agent 操作系统，具备以下鲜明特点：

• JSON‑LD 统一数据总线：所有知识以图节点形式存储，具有全局唯一 IRI。
• 四层记忆体系：L0 持久化图，L2 共享黑板，L3 按需投影，L1 上下文窗口。
• 技能图谱（Skill Graph）：基于 JSON‑LD 的技能网络，包含 MOC 导航、语义链接，天然形成树状或层次结构。
• 分层联邦架构：不同工程阶段（需求、设计、编码等）可部署为独立 Agent OS 实例，通过 IRI 传递契约，共享底层 L0 图存储。
• 边端与云端协同：编码 Agent 可能运行在开发机或云容器中，需要离线工作并在联网时同步产物。

双曲面空间向量检索+默克尔树可以带来以下增强：

• 用双曲嵌入压缩技能图谱：将技能树（MOC → 子分类 → 具体技能）嵌入 Poincaré 空间，保留层次距离，大幅降低内存占用，提高语义相似性搜索准确度。
• 替代或增强现有 Qdrant 向量存储：在需要层次感知检索（如根据领域树查找相关技能）时使用双曲度量，在普通语义搜索时沿用欧氏度量，双栈并存。
• 实现边‑云知识同步：利用默克尔树差分同步，让运行在开发机上的 Agent OS 实例能够离线记录变更，联网后仅传输增量部分，与中心知识库保持一致。
• 加速记忆检索：将双曲面向量 的 L0 热缓存和锁无关架构用于 L2 黑板或 L3 投影，降低 SPARQL 查询的延迟，提升上下文组装速度。

三、整体架构

方案的核心思想是：将双曲面空间向量检索作为 Gliding Horse 的嵌入式向量引擎，与原生的 Oxigraph 图数据库并存，共享底层部分存储，并通过适配层融入 SemanticCore。

graph TB subgraph SemanticCore["Gliding Horse SemanticCore"] Blackboard["L2 黑板 (Oxigraph)"] L3["L3 投影引擎"] Ontology["本体论引擎"] HS["HyperspaceEngine (新增)"] end subgraph Storage["存储层"] Store["共享 Oxigraph Store (Arc<Store>)"] HSStore["双曲面空间向量检索引擎 内存/磁盘存储"] end subgraph Sync["同步层"] Merkle["默克尔树同步引擎"] DeltaPush["Push/Pull Delta Sync"] end Blackboard <-->|"图数据 (JSON-LD)"| Store HS <-->|"向量数据 (嵌入)"| HSStore HS <-->|"混合检索"| Store L3 -->|"语义增强投影"| HS Ontology -->|"层次嵌入"| HS Merkle --> HS Merkle <-->|"边-云差分"| Cloud[云中心实例]

• HyperspaceEngine：封装双曲面空间向量检索的核心库，提供双曲/欧氏索引、实时写入、混合搜索（BM25+RRF）等 API。
• 混合检索桥：当 L3 投影需要语义召回时，可同时查询 SPARQL（精确）和 混合向量检索（模糊），通过可配置权重合并结果。
• 默克尔树同步引擎：监听 L2 或知识图谱的变更事件，周期性地计算 Merkle 桶哈希，与云端实例握手，完成增量同步。适合联邦架构下各阶段 Agent OS 实例之间的知识共享。

四、关键实现设计

4.1 双曲嵌入：技能图谱的层次化压缩

技能图谱本身是一个以 MOC 为根的树状结构。传统欧氏空间需要较高维度（如 768）才能较好保留层次关系，而 Poincaré 球在低维（如 64 维）即可高效嵌入。

实现步骤：

1. 技能树编码：将每个技能节点与其在 MOC 中的路径（如 moc:data-science/moc:statistics/skill:python-analysis）转换为文本描述。
2. 生成 Poincaré 嵌入：调用 HyperspaceEngine的嵌入服务（支持 YAR v5 等双曲模型），为技能描述生成 64 维 Poincaré 向量。
3. 存入集合：在 HyperspaceEngine中为技能图谱创建集合，配置 metric: "poincare"。
4. 语义检索：当 SA 根据任务 5W2H 发现技能时，可执行双曲空间搜索，天然偏好层次相近的技能（如兄弟技能、父子技能）。

优势：

• 存储节省：技能向量占用仅为欧氏的 1/12（64 vs 768 维）。
• 检索精度：层次化感知的相似度更符合人类直觉，比如“数据清洗”和“数据可视化”会因同属“数据科学”分支而获得更高分数。
• 渐进式披露：MOC 导航结合双曲嵌入，SA 可先从高层快速定位领域，再逐步深入。

Rust 集成示例：以下代码展示如何在 Gliding Horse 的 SemanticCore 中初始化 HyperspaceEngine 并完成技能嵌入与检索。

use hyperspace_engine::prelude::*;
use std::sync::Arc;

/// 在 SemanticCore 初始化时创建 HyperspaceEngine 实例
fn init_skill_embedding_engine() -> Arc<HyperspaceEngine> {
    let engine = HyperspaceEngine::builder()
        .dimension(64)               // Poincaré 低维嵌入
        .metric(Metric::Poincare)    // 双曲度量
        .build()
        .expect("HyperspaceEngine 初始化失败");

    Arc::new(engine)
}

/// 将技能节点嵌入并存入集合
fn embed_skill_node(
    engine: &HyperspaceEngine,
    skill_iri: &str,
    skill_description: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    // 1. 生成 Poincaré 嵌入向量
    let embedding = engine.embed(skill_description)?;  // 返回 64 维向量

    // 2. 构造向量记录（可附加元数据）
    let record = VectorRecord::builder()
        .id(skill_iri)
        .vector(embedding)
        .metadata(json!({
            "type": "skill",
            "description": skill_description,
        }))
        .build();

    // 3. 写入集合（实时写入缓冲，插入即搜索）
    engine.insert("skill_graph", record)?;

    Ok(())
}

/// 在 SA 发现技能时执行双曲空间检索
fn search_related_skills(
    engine: &HyperspaceEngine,
    query: &str,
    top_k: usize,
) -> Vec<ScoredPoint> {
    let query_vec = engine.embed(query).expect("查询嵌入失败");
    engine
        .search("skill_graph")
        .query(query_vec)
        .top_k(top_k)
        .run()
        .expect("双曲空间检索失败")
}

4.2 默克尔树边‑云差分同步

Gliding Horse 的联邦架构允许多个 Agent OS 实例分布在不同位置：云端服务器、开发机、甚至 CI/CD 容器。每个实例都维护一份本地知识图谱（技能、记忆、经验碎片）。为了在联网时高效同步，我们采用 HyperspaceEngine的 256 桶默克尔树协议。

同步流程：

sequenceDiagram participant Edge as 边端 Agent OS participant Cloud as 云端 Agent OS Edge->>Edge: 本地变更（新技能、失败模式） Edge->>Edge: 计算当前 256 桶哈希 Edge->>Cloud: SyncHandshake(本地桶哈希表) Cloud->>Cloud: 对比云端桶哈希，识别差异桶 Cloud-->>Edge: 返回差异桶 ID 列表 Edge->>Cloud: SyncPull(差异桶) → 拉取云端更新 Edge->>Cloud: SyncPush(本地差异桶数据) → 推送本地更新 Cloud->>Cloud: 合并更新，重新计算全局哈希

Gliding Horse 特有的同步数据：

• 技能图谱更新：新技能、技能合并、废弃标记。
• 知识碎片：AA 提炼的经验教训、失败模式。
• 5W2H 任务模板：经过验证的调度策略。
• 行为准则更新：方法论、SHACL 形状的版本迭代。

集成方式：在 BatchAgent 中新增一个“同步 Agent”，定时或在网络就绪时触发同步。同步基于 L0 持久化图的命名图进行，每个命名图对应一个同步集合。利用 Merkle 树的特性，即使边端长期离线，也能在重连时快速定位变更，只传输差异部分。

Rust 集成示例：以下代码展示如何在边端 Agent OS 中触发默克尔树差分同步。

use hyperspace_engine::sync::MerkleSync;
use std::time::Duration;

/// 边端 Agent OS 的同步 Agent 核心逻辑
async fn run_edge_sync_agent(
    local_engine: &HyperspaceEngine,
    cloud_endpoint: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    // 1. 创建默克尔树同步引擎（256 桶）
    let sync_engine = MerkleSync::builder()
        .bucket_count(256)
        .collection("skill_graph")
        .build();

    // 2. 定时触发同步（例如每 30 秒检查一次网络状态）
    loop {
        tokio::time::sleep(Duration::from_secs(30)).await;

        if !is_network_available() {
            continue; // 离线时跳过，变更累积在本地
        }

        // 3. 计算本地 256 桶哈希
        let local_buckets = sync_engine
            .compute_bucket_hashes(local_engine)
            .await?;

        // 4. 与云端握手：发送本地桶哈希表
        let cloud_client = CloudSyncClient::new(cloud_endpoint);
        let diff_buckets = cloud_client
            .handshake(local_buckets)
            .await?; // 云端返回差异桶 ID 列表

        if diff_buckets.is_empty() {
            continue; // 无差异，跳过
        }

        // 5. 拉取云端差异桶数据并合并到本地
        for bucket_id in &diff_buckets {
            let cloud_data = cloud_client
                .pull_bucket(*bucket_id)
                .await?;
            sync_engine
                .merge_bucket(local_engine, *bucket_id, cloud_data)
                .await?;
        }

        // 6. 推送本地差异桶数据到云端
        for bucket_id in &diff_buckets {
            let local_data = sync_engine
                .export_bucket(local_engine, *bucket_id)
                .await?;
            cloud_client
                .push_bucket(*bucket_id, local_data)
                .await?;
        }

        // 7. 同步完成，云端重新计算全局哈希
        cloud_client.finalize_sync().await?;
    }
}

fn is_network_available() -> bool {
    // 简化的网络状态检测（实际项目中可结合 Connectivity API）
    true
}

4.3 实时写入缓冲与 L0 缓存：加速上下文组装

Gliding Horse 的 L2 黑板在多个 Agent 并行工作时，需要承受高频的 SPARQL 写入和读取。HyperspaceEngine 的实时写入缓冲（WriteBuffer）和 L0 热缓存可以显著提升这一层的响应速度。

• 写入路径：当 Agent 向 L2 写入 JSON‑LD 节点时，同步调用 HyperspaceEngine 的插入接口（异步索引）。新写入的向量即时出现在 WriteBuffer 中，可被搜索。
• 读取路径：L3 投影在进行语义增强时，先从 L1 DashMap 缓存查找热点向量（如常用技能向量），未命中则走 L2 HNSW 图。整个流程延迟可控制在微秒级。
• 自适应缓存：利用 TTL 机制自动淘汰冷数据，保证内存占用可控。

4.4 安全与多租户隔离

Gliding Horse 可能需要同时服务多个项目或用户（多租户）。HyperspaceEngine 的原生多租户支持（通过 x-hyperspace-user-id 头或 API 密钥）可以直接用于隔离不同任务线的技能和记忆向量，确保数据不泄露。

五、带给 Gliding Horse 的提升

这些提升使得 Gliding Horse 在面对长时间、多阶段、分布式软件工程任务时，能够以更低的资源消耗、更高的响应速度和更强的数据同步能力支撑各个 Agent 的协同工作。

六、结语

将 HyperspaceEngine 增加到 Gliding Horse，并不是简单地替换一个向量数据库，而是为整个 Agent OS 注入一套层次化感知、边云协同、极致性能的记忆与同步基础设施。它让技能图谱真正“长”在双曲空间里，让分布式的 Agent 实例能够像生物体一样同步自己的“大脑”，也让每一次上下文检索都快如闪电。

这种融合完美体现了 Gliding Horse 的设计哲学：不重新发明轮子，而是将最好的轮子组装成一辆能征服任何地形的越野车。如果你也在探索 Agent OS 或空间记忆的边界，欢迎来 GitHub 交流：https://github.com/doiito/gliding_horse。