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

graph TB
subgraph “应用层”
APP1[“gliding_code
Rust CLI — 编码智能体”]
APP2[“software_engineering_single
Go — 单机软件工程”]
APP3[“software_engineering_team
Go — 团队协作
center + edge daemon”]
end

subgraph "API 层"
    GRPC["gRPC Server<br/>tonic + proto"]
    HTTP["HTTP/SSE Server<br/>axum"]
end

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

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

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

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

subgraph "高级分析层"
    CAUSAL["CausalEngine<br/>贝叶斯因果推断"]
    FEAT["FeatureExtractor<br/>图拓扑特征"]
    SNAP["TimelineStore<br/>版本快照"]
    FUSED["FusedRootCauseEngine<br/>三维融合根因"]
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

关键路径解读：

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 元数据动态决定执行拓扑。

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> {
// 初始化运行时配置（模型、记忆后端、治理策略等）
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)?)
}

}