【Agent Harness】Gliding Horse 根因分析引擎：从“头痛医头”到“三维会诊”

Gliding Horse 根因分析引擎从“头痛医头”到“三维会诊”摘要本文深入解析 Gliding Horse 根因分析引擎的设计哲学与架构演进展示如何通过 GraphBackend 抽象层统一图遍历、快照与特征提取能力构建跨越执行面、结构面与语义面的三维融合诊断系统。文章涵盖从模块重构到系统集成的完整实践适合关注 AI 可观测性、多 Agent 系统稳定性与智能运维的开发者阅读。关键词根因分析、GraphBackend、三维诊断、多 Agent 系统、知识图谱、贝叶斯网络、故障定位、可观测性、AI 运维、系统稳定性在多 Agent 协作的复杂系统中定位一个故障的根因有多难Agent 报了一个“文件写入失败”。是权限问题是依赖的数据库连接超时还是上游任务变更了目录结构传统做法要么靠人类翻日志要么让 LLM 做一次性事后分析效果堪忧。Gliding Horse 给出的答案是把根因分析变成一个持续运行的三维诊断引擎让系统自己回答“为什么会出错”以及“还会有什么会出错”。本文将拆解这套根因分析体系的设计哲学、架构演进和最终成果。它不再是单一的规则匹配或贝叶斯模型而是一个跨越执行面、结构面和语义面的融合诊断系统依托我们全新引入的GraphBackend 抽象层统一了图遍历、快照和特征提取能力使得根因分析可以同时审视代码调用链、技能依赖图和实体关系网。一、从“三座孤岛”到“一片大陆”在优化之前Gliding Horse 的根因分析能力其实已经相当丰富但它们各自为政执行层 RootCauseEngine通过 HookManager 捕获错误执行 5-why 模式匹配生成证据链和防御建议。结构层 CausalEngine基于贝叶斯网络利用 petgraph 构建的技能依赖图计算错误传播概率。语义层 KnowledgeGraphStore存储所有实体的 RDF 关系支持 SPARQL 查询和 BFS 邻居遍历。问题是CausalEngine 紧紧绑定着SkillGraphStore只看得见技能图谱里的依赖边语义层有丰富的代码调用、实体归属等关系却从未被根因分析使用。三套系统共享同一个id命名空间却无法联合“会诊”。我们需要一个桥梁。于是GraphBackend 抽象层诞生了。二、GraphBackend 抽象层让根因分析“有统一的图”«interface»GraphBackendlist_all_nodes() : VecStringget_outgoing_edges(iri) : Vecoutget_incoming_edges(iri) : Vecinbfs(seeds, depth, filter) : VecStringnode_count() : usize«interface»SnapshotBackendsnapshot() : VecNodeapply_snapshot(nodes) : Result«interface»FeatureGraphneighbors(iri, dir) : VecStringdegree(iri, dir) : usizeall_nodes() : VecStringPetgraphBackend-graph: DiGraphSparqlBackend-store: KnowledgeGraphStorePetgraphFeatureGraphSparqlFeatureGraphPetgraphBackend包装了SkillGraphStore的内部 petgraph为 CausalEngine 提供轻量内存图遍历。SparqlBackend包装了KnowledgeGraphStore通过 SPARQL 查询将 Oxigraph 中任意命名图的边关系暴露为统一的图遍历接口。这意味着代码 ASTgraph:code、工具调用结果graph:tool-result、甚至 PDCA 执行记录system:plan/exec/review/decision都能被同一个bfs方法探索。同时SnapshotBackend让版本快照不再只针对技能图谱可以对任意命名图创建快照和 diffFeatureGraph让 GNN 特征提取器能够从不同数据源抽取结构特征。这三个 trait 将高级特性从“技能图谱”的孤岛中彻底解耦变为系统级的通用能力。三、三维修正根因分析引擎有了统一的图接口我们的FusedRootCause引擎就可以同时从三个维度审视一个故障FusedRootCause 引擎“谁调了谁”“谁依赖谁”“谁相关于谁”执行面RootCauseEngine 5-why 追溯结构面CausalEngine 依赖传播推断语义面SparqlBackend RDF 语义遍历三维加权融合诊断TraceChainCausalInferencesRdfContext加权融合FusedRootCauseResult执行面当 HookManager 捕获到TaskErrorRootCauseEngine立即执行传统的 5-why 回溯沿着调用链向上追踪生成TraceChain和证据链置信度基于证据完整性计算。结构面CausalEngine以故障实体为种子在GraphBackend可以是技能图或 RDF 全图上运行 BFS利用贝叶斯后验概率计算每个关联节点的因果贡献输出CausalInference列表。语义面SparqlBackend对故障 IRI 进行深度为 3 的语义邻居探索获取它在知识图谱中的所有上下文——属于哪个任务、操作了哪些实体、受哪些规则约束等生成RdfSemanticContext。最终三个维度的结果通过加权融合执行面 0.4结构面 0.35语义面 0.25生成最终根因报告FusedRootCauseResult包含主要故障 IRI、总体置信度、各维度的贡献因子以及针对性行动建议。这种“三维会诊”远比任何单一维度的分析更可靠。四、模块改造从硬绑定到依赖注入为了让这套融合引擎落地我们对相关模块进行了低侵入性的重构CausalEngine构造函数从接受ArcSkillGraphStore改为接受Arcdyn GraphBackend。在技能故障场景注入PetgraphBackend在跨领域分析时注入SparqlBackend无需改动引擎内部逻辑。TimelineStore原本绑死技能快照现在create_snapshot改为接收dyn SnapshotBackend参数可以对任意图存储生成时间线快照用于跨版本对比。FeatureExtractor同样改为依赖Arcdyn FeatureGraph使得提取节点度、中心性等图特征时可以从不同存储后端读取。旧版skill_graph/types.rs中的CausalEvent和CausalChain被标记为弃用统一迁移到causal/types.rs消除类型冗余。整个重构保持向后兼容原有测试全部通过。下面是一个具体的 Rust 代码示例展示CausalEngine如何通过依赖注入GraphBackend来灵活切换后端usestd::sync::Arc;// 1. 定义 GraphBackend trait抽象层pubtraitGraphBackend:SendSync{fnbfs(self,seeds:[String],depth:usize)-VecString;fnget_outgoing_edges(self,iri:str)-VecString;// ... 其他图操作方法}// 2. 两个具体实现pubstructPetgraphBackend{// 包装 SkillGraphStore 内部的 petgraphgraph:petgraph::GraphString,(),}implGraphBackendforPetgraphBackend{fnbfs(self,seeds:[String],depth:usize)-VecString{// 在内存 petgraph 上执行 BFS 遍历// 适用于技能依赖图的快速分析vec![]// 简化示意}fnget_outgoing_edges(self,iri:str)-VecString{vec![]}}pubstructSparqlBackend{store:ArcKnowledgeGraphStore,}implGraphBackendforSparqlBackend{fnbfs(self,seeds:[String],depth:usize)-VecString{// 通过 SPARQL 查询在 Oxigraph 上执行 BFS// 可遍历代码 AST、工具调用结果等任意命名图vec![]// 简化示意}fnget_outgoing_edges(self,iri:str)-VecString{vec![]}}// 3. CausalEngine 通过依赖注入接收 GraphBackendpubstructCausalEngine{backend:ArcdynGraphBackend,}implCausalEngine{/// 构造函数接受任意实现了 GraphBackend 的后端pubfnnew(backend:ArcdynGraphBackend)-Self{Self{backend}}/// 根因推断利用注入的后端执行 BFS 与贝叶斯后验计算pubfninfer_root_cause(self,fault_iri:str)-VecCausalInference{letneighborsself.backend.bfs([fault_iri.to_string()],3);// 对邻居节点计算贝叶斯后验概率...vec![]}}// 4. 使用示例根据场景注入不同的后端fnmain(){// 场景 A技能依赖故障 → 使用轻量内存图letpetgraph_backendArc::new(PetgraphBackend{/* ... */});letengine_for_skillsCausalEngine::new(petgraph_backend);// 场景 B跨领域分析 → 使用 RDF 知识图谱letsparql_backendArc::new(SparqlBackend{store:Arc::new(KnowledgeGraphStore::new()),});letengine_for_cross_domainCausalEngine::new(sparql_backend);// 两种场景共用同一套 infer_root_cause 逻辑无需修改引擎内部代码letresult_aengine_for_skills.infer_root_cause(task:file-write-error);letresult_bengine_for_cross_domain.infer_root_cause(task:file-write-error);}关键点CausalEngine不再关心具体是哪种图存储只依赖Arcdyn GraphBackend接口。注入PetgraphBackend时获得轻量内存遍历性能注入SparqlBackend时获得全量 RDF 语义探索能力——一行构造函数调用即可切换后端引擎内部逻辑完全不变。五、系统集成从被动记录到主动诊断融合引擎完全嵌入 Hook 系统形成闭环L0KnowledgeGraphStoreCausalEngineRootCauseEngineHookManagerL0KnowledgeGraphStoreCausalEngineRootCauseEngineHookManagerTaskError 事件trace_backward() [5-why]infer_root_cause(fault_iri)GraphBackend.bfs() posteriorVecCausalInferenceget_neighbors(fault_iri, depth3)RDF 语义子图fuse_confidence()FusedRootCause写入诊断报告 (JSON-LD)诊断报告以 JSON-LD 节点存入 L0关联原任务 IRI后续 SA 进行相似任务编排时会参考历史根因Batch Agent “失败模式挖掘” 也会消费这些报告提炼出通用失败模式并挂载到技能图谱。这实现了根因分析的“一次诊断全局受益”。六、带来的提升与平台效果准确率提升融合三维证据后根因定位的置信度显著高于单维度避免了“只看调用链以为是参数错误实际是上游数据源变更”的片面判断。跨领域通用无论是技能依赖错误、代码缺陷、还是环境资源冲突都能在统一框架内分析因为图遍历后端可灵活切换。可解释性强每份诊断报告都附带三个维度的证据分项人类审计时可以清晰回溯 AI 的推理过程。系统自愈基础根因引擎输出的recommended_actions已经可以直接喂给 AA决策 Agent进行自动修复或回滚。在流马内部这套根因分析系统已经从“特定模块的附属工具”升级为系统级的诊断服务为多 Agent 复杂任务的长稳运行提供了坚实保障。它让我们从“记录错误”迈向了“理解错误”最终走向“预防错误”。Gliding Horse 已在 GitHub 开源https://github.com/doiito/gliding_horse