【Agent Harness】Gliding Horse 整体架构拼图：当 AI Agent 有了自己的操作系统

doiito
0 阅读10分钟

Gliding Horse 整体架构拼图：当 AI Agent 有了自己的操作系统

摘要：本文深入解析 Gliding Horse（流马）——一个用 Rust 构建的 AI Agent 操作系统的七层架构。从 PDCA 调度状态机、JSON-LD 语义总线到四级分层记忆，全面拆解其如何将 LLM 从“聪明但散漫”转变为“可靠且可依赖”。适合对 AI Agent 架构、Rust 系统设计、Agent 编排感兴趣的开发者阅读。

关键词：AI Agent 操作系统、Gliding Horse、Rust、PDCA 调度、分层架构、JSON-LD、知识图谱、Agent 编排、LLM 工程化、系统设计

去年我写了一系列文章，拆解 Gliding Horse 的每一个子系统——记忆、技能、工具、门禁、事件总线、知识图谱……有朋友说：能不能用一篇文章把整张拼图摊开，让我们一眼看清这个“AI Agent 操作系统”到底是怎么运转的？

今天这篇，就是这张拼图。

Gliding Horse（流马）是用 Rust 从零构建的 AI Agent 操作系统。它不只是一个编排框架，而是一套完整的内核：有进程调度、有虚拟内存、有文件系统、有权限管理，还有与 CPU 缓存体系对标的四层记忆。它的核心哲学非常简单：把 LLM 当成 CPU，给它配上操作系统。

一、分层架构：从应用到底座，每一层都职责分明

Gliding Horse 采用严格的七层架构，上层调用下层，下层不感知上层。

graph TB
    subgraph "应用层"
        APP1[&#34;gliding_code<br/>Rust CLI — 编码智能体&#34;]
        APP2[&#34;software_engineering_single<br/>Go — 单机软件工程&#34;]
        APP3[&#34;software_engineering_team<br/>Go — 团队协作<br/>center + edge daemon&#34;]
    end

    subgraph &#34;API 层&#34;
        GRPC[&#34;gRPC Server<br/>tonic + proto&#34;]
        HTTP[&#34;HTTP/SSE Server<br/>axum&#34;]
    end

    subgraph &#34;核心编排层&#34;
        SA[&#34;SupervisorAgent<br/>PDCA 调度 + 7 级复杂度&#34;]
        AR[&#34;AgentRunner<br/>PA/DA/CA/AA 执行循环&#34;]
        WF[&#34;Workflow Engine<br/>DAG + 拓扑排序&#34;]
        BATCH[&#34;BatchAgentManager<br/>后台维护智能体&#34;]
    end

    subgraph &#34;能力层&#34;
        TOOLS[&#34;ToolExecutor<br/>15+ 内置工具&#34;]
        MEM[&#34;Memory Manager<br/>L0/L1/L2/L3 四级&#34;]
        GW[&#34;UnifiedGateway<br/>LLM 调用 + 重试 + 缓存&#34;]
        PERC[&#34;ProactiveEngine<br/>主动感知 + 干预&#34;]
    end

    subgraph &#34;治理层&#34;
        CON[&#34;Constitution<br/>行为宪法&#34;]
        METH[&#34;MethodologyGate<br/>方法论门控&#34;]
        SG[&#34;SyscallGate<br/>系统调用门&#34;]
        TG[&#34;ToolGuard<br/>工具守卫&#34;]
        RC[&#34;RootCauseEngine<br/>根因分析&#34;]
    end

    subgraph &#34;语义层&#34;
        JSONLD[&#34;JSON-LD 上下文<br/>+ Framing + TypeRouter&#34;]
        KG[&#34;KnowledgeGraph<br/>Oxigraph SPARQL&#34;]
        SKILL[&#34;SkillGraph<br/>技能图 + 图算法&#34;]
    end

    subgraph &#34;高级分析层&#34;
        CAUSAL[&#34;CausalEngine<br/>贝叶斯因果推断&#34;]
        FEAT[&#34;FeatureExtractor<br/>图拓扑特征&#34;]
        SNAP[&#34;TimelineStore<br/>版本快照&#34;]
        FUSED[&#34;FusedRootCauseEngine<br/>三维融合根因&#34;]
    end

    APP1 --> GRPC & HTTP
    APP2 --> GRPC
    APP3 --> GRPC
    GRPC & HTTP --> SA
    SA --> AR & WF & BATCH
    AR --> TOOLS & MEM & GW & PERC
    SA --> CON & METH & SG & TG & RC
    AR --> JSONLD & KG & SKILL
    RC --> CAUSAL & FUSED
    SKILL --> FEAT & SNAP

各层职责速览：

  • 应用层：针对不同场景的具体应用程序，如编码助手、单机软件工程、分布式团队协作。
  • API 层：通过 gRPC 和 HTTP 暴露服务，支持流式响应（SSE）。
  • 核心编排层：系统的“大脑”。SA 根据任务复杂度动态决定执行 PDCA 的哪一阶段、是否并行、是否递归。AgentRunner 是统一的执行器，PA/DA/CA/AA 只是注入不同提示词的同一套引擎。Workflow Engine 负责将任务拆解为 DAG 并拓扑排序。BatchAgentManager 管理 8 个后台保洁 Agent。
  • 能力层：提供工具调用、记忆管理、LLM 通信和主动感知能力。
  • 治理层：系统的“免疫系统”。行为宪法是不可绕过的基线，方法论门控是条件触发的纪律，系统调用门是代码级硬拦截，ToolGuard 做运行时前置注入和后置校验，根因引擎自动分析错误。
  • 语义层：以 JSON-LD 为统一总线，所有数据都有 @id、@type、@context。知识图谱存实体关系，技能图谱存能力网络。
  • 高级分析层：贝叶斯因果推断、图拓扑特征提取、版本快照、三维融合根因分析——这些是系统持续自优化的高级工具箱。

二、核心运行时数据流：一次完整任务的生命周期

下面这张时序图展示了一个典型任务（例如“重构认证系统为 JWT”）在 Gliding Horse 内部的完整流转过程。

sequenceDiagram
    participant U as 用户/gRPC
    participant SA as SupervisorAgent
    participant AR as AgentRunner
    participant GW as UnifiedGateway
    participant TE as ToolExecutor
    participant L0 as L0 Store
    participant L2 as L2 Blackboard
    participant KG as KnowledgeGraph

    U->>SA: process_task(prompt)
    SA->>SA: classify_with_llm() → TaskComplexity
    SA->>SA: build_execution_plan() → ExecutionPlan
    
    loop PDCA Steps (PA → DA → CA → AA)
        SA->>AR: dispatch_agent(role, ctx)
        AR->>AR: build_system_prompt(role, 5W2H, methodology)
        AR->>GW: chat_with_params(model, messages, tools)
        GW-->>AR: LLM response (content + tool_calls)
        
        alt has tool_calls
            AR->>TE: execute_tool(name, input)
            TE->>TE: ToolGuard pre-check
            TE->>TE: Permission check
            TE->>TE: execute builtin
            TE->>TE: ResultRouter (graphify/truncate/summary)
            TE-->>AR: tool result (IRI-referenced)
            AR->>L0: store(tool_result_iri, full_content)
        end
        
        AR->>L2: write_node(task_iri, jsonld_output)
        L2->>KG: sync_to_oxigraph(sparql_insert)
        AR->>L0: checkpoint(task_iri, messages, state)
        AR-->>SA: TaskResult(status, summary, output)
    end
    
    SA->>SA: 5W2H freeze (on last AA success)
    SA->>L0: archive(task_iri, frozen_5w2h)
    SA-->>U: TaskResult

关键路径解读：

  1. SA 收到任务后，通过 LLM 分类确定复杂度等级（L0~L6），并构建执行计划——可能是单次 DA 直行，也可能是多轮 PDCA 循环。
  2. dispatch_agent 根据当前角色（PA/DA/CA/AA）动态生成系统提示词，注入该角色的行为宪法、激活的方法论、可用工具清单和 5W2H 上下文。
  3. AgentRunner 通过 UnifiedGateway 调用 LLM。如果 LLM 返回工具调用，ToolExecutor 会经过 ToolGuard 校验、权限检查后执行，结果通过 ResultRouter 压缩（大结果存档 L0 并替换为 IRI 引用）。
  4. 每一轮产出都写入 L2 黑板（Oxigraph 图数据库），并同步到知识图谱，同时做 L0 检查点。
  5. PDCA 循环结束时，AA 冻结 5W2H 元数据，归档到 L0，形成可追溯的任务档案。

整个流程中，LLM 只看到高度压缩的上下文（摘要 + IRI 引用），完整数据全在图数据库里，按需检索——这正是 Gliding Horse 维持长周期运行而不爆 Token 的核心秘密。

三、PDCA 调度状态机：不是固定的“计划—执行—检查—行动”

Gliding Horse 的 PDCA 不是死流程。SA 会根据 5W2H 元数据动态决定执行拓扑。

stateDiagram-v2
    [*] --> Analyzing: process_task()
    Analyzing --> Planning: classify_with_llm()
    
    Planning --> Executing: build_execution_plan()
    Executing --> Checking: DA completed
    Checking --> Acting: CA completed
    Acting --> Completed: AA success
    Acting --> Planning: AA fail (retry, max_pdca_cycles)
    
    state Executing {
        [*] --> DA_Running
        DA_Running --> DA_Recursive: Complex/Recursive
        DA_Recursive --> DA_Running: sub-task complete
        DA_Running --> [*]: DA done
    }
    
    Completed --> [*]
  • 简单任务（例如“现在几点”）：直接走 DA 直行，不启动 PA/CA/AA。
  • 标准任务：PA → DA → CA → AA，单次 PDCA 循环。
  • 复杂项目：PA → 多个 DA 并行 → CA 汇总 → AA 拍板。
  • 探索性任务：DA ↔ CA 循环，直到收敛。
  • 递归分解：DA 内部可以启动一个完整的微观 PDCA 子循环。

这种动态拓扑让 Gliding Horse 能够适配从一次简单查询到多阶段软件工程的各种任务，不错配资源。

四、架构的五大核心优势

1. 动态编排：任务自己决定怎么被做

SA 不是静态 DAG 引擎。它分析 5W2H 后实时推理该用什么角色、多少轮次、是否并行。没有两个完全一样的任务，也就没有两个完全一样的流程。

2. 分层记忆：永远不丢上下文

L0 持久化全量数据，L1 仅保留摘要和 IRI 引用，L2 是共享工作区，L3 按需投影子图。聊 50 轮，上下文窗口只装 50 条摘要，但任何历史细节都能通过 IRI 秒级调取。Token 消耗从 O(n) 降为 O(1)。

3. 硬约束安全：不靠 LLM 的“自觉”

系统调用门做三层硬拦截（Schema 校验 + 签名验证 + 角色白名单），ToolGuard 做前置注入和后置校验，阶段门禁用 SHACL 契约强制验收。LLM 想删文件？白名单里没有，直接拒绝。这不是“建议”，这是“物理定律”。

4. JSON-LD 语义总线：让数据变成图

系统中没有任何“字符串数据”——所有任务、技能、记忆、设计文档、审计日志全是带 @id 的 JSON-LD 节点。鸭子类型消除命名冲突，图合并自动去重，Token 捏合随心所欲。

5. 知识自进化：越用越聪明

技能图谱基于成功率自动进化，Batch Agent 定时合并相似技能、挖掘失败模式、压缩陈旧记忆。根因引擎从执行面、结构面、语义面三维诊断故障。系统不依赖 LLM 变强，而是靠知识沉淀持续优化。

五、实际效果：从“能用”到“可信赖”

在内部测试中，Gliding Horse 完成一个“重构认证系统为 JWT”的完整需求，从需求分析到编码实现，SA 自动选择了 PA → DA → CA → AA 流程，DA 并行启动了三个编码子 Agent，CA 发现其中一个缺少 token 刷新逻辑后打回重做，最终 AA 归档冻结了 5W2H。

整个过程中，人工只给了最初的一句话需求。规划、执行、检查、修正、归档全是系统自动完成的。上下文 Token 消耗比传统方案降低了 47%，关键信息可追溯率达到 100%。

七、实战代码示例

下面通过三个 Rust 代码片段，展示 Gliding Horse 核心 API 的调用方式。这些示例基于 gliding_horse crate 的公开接口，帮助你快速上手。

1. 通过 SupervisorAgent 提交一个任务

use gliding_horse::prelude::*;
use gliding_horse::agent::SupervisorAgent;
use gliding_horse::config::RuntimeConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化运行时配置（模型、记忆后端、治理策略等）
    let config = RuntimeConfig::builder()
        .llm_endpoint("http://localhost:11434/v1")
        .llm_model("qwen2.5:32b")
        .memory_backend("oxigraph")  // 使用 Oxigraph 图数据库作为 L2 黑板
        .build()?;

    // 创建 SupervisorAgent 实例
    let mut supervisor = SupervisorAgent::new(config);

    // 提交一个任务——只需一句话需求，SA 会自动规划执行
    let task = supervisor
        .process_task("分析项目 src/ 目录下的代码，找出所有未处理的 Result 类型并生成修复建议")
        .await?;

    // 输出任务结果
    println!("任务状态: {:?}", task.status);
    println!("任务摘要: {}", task.summary);
    println!("输出: {}", task.output);

    Ok(())
}

说明：SupervisorAgent::process_task() 是最高层入口。SA 内部自动调用 classify_with_llm() 确定复杂度等级，构建执行计划，调度 AgentRunner 执行 PDCA 循环，最终返回 TaskResult。开发者只需提供自然语言需求，无需手动编排流程。

2. 定义一个自定义工具并注册

use gliding_horse::tool::{Tool, ToolContext, ToolResult};
use gliding_horse::tool::ToolGuard;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};

// 1. 定义工具的输入/输出结构
#[derive(Debug, Deserialize)]
struct CodeReviewInput {
    file_path: String,
    language: String,
}

#[derive(Debug, Serialize)]
struct CodeReviewOutput {
    issues: Vec<String>,
    suggestions: Vec<String>,
    score: u8,
}

// 2. 实现 Tool trait
struct CodeReviewTool;

#[async_trait]
impl Tool for CodeReviewTool {
    fn name(&self) -> &str {
        "code_review"
    }

    fn description(&self) -> &str {
        "对指定代码文件进行静态审查，返回问题列表和改进建议"
    }

    async fn execute(&self, input: &str, ctx: &ToolContext) -> ToolResult {
        // 解析输入（JSON-LD 格式自动反序列化）
        let parsed: CodeReviewInput = serde_json::from_str(input)?;

        // 模拟代码审查逻辑
        let output = CodeReviewOutput {
            issues: vec![
                format!("{}:{} 存在未处理的 unwrap()", parsed.file_path, 42),
                format!("{}:{} 函数过长（>100行）", parsed.file_path, 15),
            ],
            suggestions: vec![
                "使用 ? 运算符替代 unwrap()".to_string(),
                "将第15行的函数拆分为多个小函数".to_string(),
            ],
            score: 72,
        };

        // 返回结果（自动转为 JSON-LD 节点）
        Ok(serde_json::to_value(output)?)
    }
}

// 3. 注册到 ToolExecutor
fn register_custom_tools() -> ToolExecutor {
    let mut executor = ToolExecutor::new();
    executor.register(Box::new(CodeReviewTool));
    // 注册后，AgentRunner 在 PDCA 循环中即可自动调用该工具
    executor
}

说明：自定义工具只需实现 Tool trait 的 name()、description() 和 execute() 三个方法。注册后，LLM 在 PDCA 循环中会自动识别何时调用该工具。ToolGuard 会在执行前自动做权限校验和 Schema 验证，无需开发者额外处理安全逻辑。

3. 从 L2 黑板（知识图谱）中查询任务历史

use gliding_horse::memory::L2Blackboard;
use gliding_horse::knowledge::KnowledgeGraph;
use gliding_horse::jsonld::JsonLdNode;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 连接 L2 黑板（底层是 Oxigraph 图数据库）
    let blackboard = L2Blackboard::connect("http://localhost:7878")?;
    let kg = KnowledgeGraph::new(blackboard.clone());

    // 查询所有已完成的任务（SPARQL 查询）
    let query = r#"
        PREFIX gh: <https://gliding.horse/ontology/>
        SELECT ?task ?summary ?status ?created_at WHERE {
            ?task a gh:Task ;
                  gh:summary ?summary ;
                  gh:status ?status ;
                  gh:createdAt ?created_at .
            FILTER(?status = "completed")
        }
        ORDER BY DESC(?created_at)
        LIMIT 10
    "#;

    let results: Vec<JsonLdNode> = kg.sparql_query(query).await?;

    for node in results {
        println!("任务 IRI: {}", node.id());
        println!("摘要: {}", node.get_string("summary").unwrap_or_default());
        println!("状态: {}", node.get_string("status").unwrap_or_default());
        println!("---");
    }

    // 按 IRI 精确检索某个任务的完整上下文
    let task_iri = "https://gliding.horse/tasks/abc-123-def";
    if let Some(task_node) = kg.get_node(task_iri).await? {
        // 获取该任务的所有关联数据（包括子步骤、工具调用记录、检查点）
        let full_context = kg.expand_node(&task_node, 2).await?; // 深度 2 的图展开
        println!("完整上下文: {:#?}", full_context);
    }

    Ok(())
}

说明：Gliding Horse 的所有任务数据都以 JSON-LD 节点形式存储在 L2 黑板中。通过 KnowledgeGraph 可以执行 SPARQL 查询、按 IRI 检索节点、以及按深度展开关联子图。这正是系统实现“Token 消耗 O(1) 但历史可追溯”的关键机制——LLM 只看到摘要和 IRI 引用，完整数据按需从图数据库中拉取。

六、总结

Gliding Horse 不是要替代 Claude Code、Codex CLI 或 Cursor。它是一个可以运行这些工具的底层平台——把它们的聪明才智装进一套有记忆、有约束、有质量保障的工程体系里。

这张架构拼图摊开后，你会发现它的每一个模块都在回答同一个问题：如何让 AI Agent 从“聪明但散漫”变成“可靠且可依赖”。

LLM 是伟大的发明，但它只是一个零件。它需要操作系统、需要文件系统、需要权限管理、需要质量保障——就像 CPU 很强大，但没有主板、内存、操作系统，它就是个发热的硅片。

LLM 是天才，Harness 是纪律。天才需要纪律，才能创造价值。

Gliding Horse 已在 GitHub 开源：github.com/doiito/glid…

avatar
文章
阅读
粉丝