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

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\)" 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 的提升

维度	移植前（仅 Qdrant + SPARQL）	移植后（ + HyperspaceEngine）
技能检索	欧氏语义搜索，忽略层次结构	双曲搜索, 欧氏语义搜索, 混合搜索, 层次感知，召回率提高
存储效率	技能向量 768 维	64 维 Poincaré，内存/磁盘占用减少 90%+
边端同步	无原生差分同步，需全量传输	默克尔树 Delta Sync，仅传输变更桶
写入延迟	同步插入 Qdrant 有一定延迟	实时写入缓冲，插入即搜索
读取延迟	完全依赖外部服务延迟	内嵌 L0 热缓存，热点数据亚微秒级响应
离线能力	依赖 Qdrant 常驻服务	HyperspaceEngine 可嵌入式运行，边端完全离线工作
联邦一致性	IRI 传递，需额外机制保证状态	默克尔树同步提供可验证的最终一致性

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

六、结语

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

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