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

一、分层架构：从应用到底座，每一层都职责分明
Gliding Horse 采用严格的七层架构，上层调用下层，下层不感知上层。

高级分析层

语义层

治理层

能力层

核心编排层

API 层

应用层

gliding_code
Rust CLI — 编码智能体

software_engineering_single
Go — 单机软件工程

software_engineering_team
Go — 团队协作
center + edge daemon

gRPC Server
tonic + proto

HTTP/SSE Server
axum

SupervisorAgent
PDCA 调度 + 7 级复杂度

AgentRunner
PA/DA/CA/AA 执行循环

Workflow Engine
DAG + 拓扑排序

BatchAgentManager
后台维护智能体

ToolExecutor
15+ 内置工具

Memory Manager
L0/L1/L2/L3 四级

UnifiedGateway
LLM 调用 + 重试 + 缓存

ProactiveEngine
主动感知 + 干预

Constitution
行为宪法

MethodologyGate
方法论门控

SyscallGate
系统调用门

ToolGuard
工具守卫

RootCauseEngine
根因分析

JSON-LD 上下文

• Framing + TypeRouter

KnowledgeGraph
Oxigraph SPARQL

SkillGraph
技能图 + 图算法

CausalEngine
贝叶斯因果推断

FeatureExtractor
图拓扑特征

TimelineStore
版本快照

FusedRootCauseEngine
三维融合根因

各层职责速览：

应用层：针对不同场景的具体应用程序，如编码助手、单机软件工程、分布式团队协作。
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 内部的完整流转过程。

KnowledgeGraph
L2 Blackboard
L0 Store
ToolExecutor
UnifiedGateway
AgentRunner
SupervisorAgent
用户/gRPC
KnowledgeGraph
L2 Blackboard
L0 Store
ToolExecutor
UnifiedGateway
AgentRunner
SupervisorAgent
用户/gRPC
alt
[has tool_calls]
loop
[PDCA Steps (PA → DA → CA → AA)]
process_task(prompt)
classify_with_llm() → TaskComplexity
build_execution_plan() → ExecutionPlan
dispatch_agent(role, ctx)
build_system_prompt(role, 5W2H, methodology)
chat_with_params(model, messages, tools)
LLM response (content + tool_calls)
execute_tool(name, input)
ToolGuard pre-check
Permission check
execute builtin
ResultRouter (graphify/truncate/summary)
tool result (IRI-referenced)
store(tool_result_iri, full_content)
write_node(task_iri, jsonld_output)
sync_to_oxigraph(sparql_insert)
checkpoint(task_iri, messages, state)
TaskResult(status, summary, output)
5W2H freeze (on last AA success)
archive(task_iri, frozen_5w2h)
TaskResult
关键路径解读：

SA 收到任务后，通过 LLM 分类确定复杂度等级（L0~L6），并构建执行计划——可能是单次 DA 直行，也可能是多轮 PDCA 循环。
dispatch_agent 根据当前角色（PA/DA/CA/AA）动态生成系统提示词，注入该角色的行为宪法、激活的方法论、可用工具清单和 5W2H 上下文。
AgentRunner 通过 UnifiedGateway 调用 LLM。如果 LLM 返回工具调用，ToolExecutor 会经过 ToolGuard 校验、权限检查后执行，结果通过 ResultRouter 压缩（大结果存档 L0 并替换为 IRI 引用）。
每一轮产出都写入 L2 黑板（Oxigraph 图数据库），并同步到知识图谱，同时做 L0 检查点。
PDCA 循环结束时，AA 冻结 5W2H 元数据，归档到 L0，形成可追溯的任务档案。
整个流程中，LLM 只看到高度压缩的上下文（摘要 + IRI 引用），完整数据全在图数据库里，按需检索——这正是 Gliding Horse 维持长周期运行而不爆 Token 的核心秘密。

三、PDCA 调度状态机：不是固定的“计划—执行—检查—行动”
Gliding Horse 的 PDCA 不是死流程。SA 会根据 5W2H 元数据动态决定执行拓扑。

process_task()

classify_with_llm()

CA completed

AA success

AA fail (retry, max_pdca_cycles)

build_execution_plan()

DA completed

Analyzing

Planning

Executing
Complex/Recursive

sub-task complete

DA done

DA_Running

DA_Recursive

Checking

Acting

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> {
// 初始化运行时配置（模型、记忆后端、治理策略等）
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,
suggestions: Vec,
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> {
// 连接 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 从“聪明但散漫”变成“可靠且可依赖”。