Kylin Agent：面向国产化环境的多 Agent 智能运维平台

- 面向龙芯与麒麟国产化环境，通过逐动作人工审批、RCA、Trace回放与质量评测闭环，有效降低高危操作风险并提升排障效率。 - 基于 Spring Boot + Sa-Token + H2 构建统一认证与授权服务，支撑中心控制面、面板与受管节点间的安全会话、角色绑定及持久化。 - 采用 LangGraph 状态图编排多 Agent，集成 BM25/FAISS 混合检索与 Cross-Encoder 重排实现可审计的知识链，并通过纯 ONNX Runtime 在龙芯平台完成模型推理与语义安全判断。 - 真机六服务全健康部署；注册 87 项结构化工具；累计专项与回归测试超 500 passed，RAG 与端到端 Agent 评测得分达 0.9814，交付流水线支持可复现与可回滚。

## 项目概览在龙芯 3A5000 处理器与银河麒麟 V11 操作系统的国产化真机环境中，我们构建了一个以安全可控、可恢复、可审计为核心的多 Agent 智能运维平台。系统通过逐动作人工审批、自动根因分析（RCA）、Trace 回放与质量评测闭环，将高危操作风险降至最低，同时显著提升了排障效率与交付可信度。整体方案已实现六服务全健康部署，注册 87 项结构化运维工具，累计专项与回归测试超过 500 passed，RAG 与端到端 Agent 评测得分达到 0.9814，并具备可复现、可回滚的 CI/CD 交付流水线。 ## 从单体到中心化多 Agent 架构早期系统为单体 Agent，聊天、监控、执行等逻辑耦合在 API 与脚本中，ReAct 过程无法可靠恢复，高风险操作缺少统一的人工确认入口。我们将架构重构为“中心控制面 + 受管 Agent + 运维面板”三层角色：控制面基于 LangGraph 状态图驱动 ReAct 循环，通过 SQLite checkpoint 持久化每一步状态，崩溃后可精确恢复；受管 Agent 退化为无状态执行器，仅接收结构化任务快照；运维面板则提供高风险操作的人工介入界面。同时引入最大迭代上限与工具重试策略，防止模型无限思考，并通过流式事件实时推送推理过程，实现白盒化干预。首轮专项回归 55 项全部通过，并成功适配远端节点、Docker、文件、数据库等典型运维入口。 ## 安全闭环：复合意图、结构化工具与逐动作审批自然语言指令常复合检查、删除、重启等多类意图，传统关键词黑名单易误判且可被绕过。我们设计了一套“意图解构→结构化工具契约→逐动作审批→语义安全兜底”的闭环方案。首先将复合指令按分句拆分，为每个原子运维意图分配稳定的 `action_id` 以全链路追溯；然后为 87 项工具（60 项只读、27 项变更）生成基于 Pydantic/JSON Schema 的“数字契约”，明确参数、目标节点、风险等级与影响范围；执行时对每个动作进行**逐动作人工审批**，审批凭据绑定操作者、计划版本、节点与 `action_id`，从根本上杜绝“批一项、执行多项”的绕过风险。语义层面的恶意识别则交由独立轻量模型负责，它不具备自我批准能力，仅作为辅助参考；同时以硬编码规则直接阻断 `rm -rf /`、格式化已挂载盘等无歧义的灾难操作。该方案通过 105 项工具候选与规划专项测试，以及 60 项子测试验证。 ## 可量化的知识引擎：混合 RAG 与多层评测检索增强生成（RAG）采用关键词召回（SQLite FTS5/BM25）+ 语义召回（FAISS）+ 独立 Cross-Encoder 重排的三段式架构，保证了专有名词与意图相近的查询都能精确命中。文档加工引入父子分块、结构化经验卡（症状-原因-解决方案-验证步骤）与多层去重，使知识可过滤、可组合且去冗。所有离线评测均显式绑定数据版本与 SHA-256 校验，采用 Precision、Recall、F1、NDCG、MRR 等标准指标，并结合端到端 Agent 任务评测，自动化衡量工具选择准确率、审批链路完整性。每一次运行保留 Trace 证据，可一键回放定位召回缺失、重排偏差或工具选择错误。最终形成静态检查、RAG、端到端 Agent、Trace 回放与 Future AGI 兼容导出五层评测体系，历史版本得分 0.9814。 ## 龙芯与麒麟国产化环境真机适配在龙芯 3A5000 + 银河麒麟 V11 真机部署过程中，我们遇到 Nginx ABI 不兼容、ONNX 与 CPython ABI 冲突、sqlite-jdbc JNI 加载失败、RabbitMQ OTP 依赖竞态等一系列问题。通过构建四个独立 `linux/loong64` 镜像，为控制面与 Agent 分别锁定 CPython 3.12 + ONNX Runtime 1.21 及 CPython 3.10 运行环境，纯 ONNX Runtime 完成模型推理与语义安全判断，完全脱离 x86 依赖。最终六服务稳定运行，RabbitMQ ACK/DLQ/重启恢复、H2 会话持久化及各类文档解析校验全部通过。 ## 可靠多 Agent：证据契约、幂等与完成裁判在多 Agent 异步协作环境中，消息重投或 checkpoint 回放可能导致副作用重复执行或结果失真。我们建立了以“证据契约”为核心的可靠性体系：为每个原子操作配置持久化 `action_id` 账本与资源租约，实现严格幂等；通过结构化 `SubAgentTask` / `SubAgentResult` 及 `plan_digest` 将任务绑定到具体计划节点、阶段、工具白名单，使每一份返回结果都可验证其来源；设计分层证据裁判，先由系统门禁确定性校验动作覆盖率与契约匹配，再由轻量 LLM 判断语义缺口，并严格限定 `failed`、`blocked` 等非成功状态绝不允许被模型篡改为成功，终止判定与目标达成彻底解耦。多 Agent 协作专项累计 158 passed，复合规划与流式终态真实性等测试均通过。 ## 运维体验与可观测性为降低排障认知负荷，我们摒弃了原始 JSON 堆砌，将 Trace 回放改造为北京时间轴的中文时间线，巡检结果逐项列出失败对象、节点与原因并给出操作建议。子 Agent 仅输出结构化观察，主 Agent 据此拼装出可解释、有来源的专业自然语言总结，直接回答“下一步做什么”。历史会话、指令及审批信息集中收纳至运维指令卡，按需展开，界面清爽且信息完整。 ## 可复现、可回滚的 CI/CD 交付交付阶段，CI/CD 流水线强制校验 Git revision、基础镜像 digest、模型 manifest、文件哈希等不可变身份标识，杜绝制品漂移。交付包固化五类镜像 + ONNX 模型，部署后自动执行严格就绪检查，任何服务未达预期即自动将镜像标签回滚至上一稳定版本，数据卷保留。真机部署 V0.6.186 一次成功，六服务全部 healthy，全部门禁与持久化测试通过，真正实现“一键部署、失败即回滚、全链路可追溯”的交付闭环。

中心化多 Agent 与结构化结果契约
复合意图与 87 项工具能力
轻量模型语义安全、灾难命令硬边界与逐动作人工审批
action_id 幂等账本、资源租约和任务凭据
BM25/FAISS/Rerank/Docling 混合 RAG
RabbitMQ manual ACK、DLX/DLQ 与重启恢复
龙芯/银河麒麟 ONNX-only 原生部署
可验证、可回滚 CI/CD

开发记录

架构起点：从单体 Agent 到中心控制面：背景早期系统为单体 Agent 架构，聊天、监控分析、节点执行与记忆等逻辑分散在 API 与各类脚本中，缺乏统一的执行骨架与角色边界。问题 1. ReAct 过程无法可靠恢复，状态在请求间丢失，中断后难以续接或回溯。 2. 控制面与执行节点职责不清，编排、决策和实际操作混杂在同一入口。 3. 高风险操作（如删除、重启、权限变更）缺少统一的人工确认入口，存在误操作风险。根因执行逻辑直接耦合于请求入口，缺少统一的状态图、持久化检查点以及清晰的部署角色边界，导致流程不可控、不可恢复，且无法施加集中管控。影响 - 任务执行缺乏可恢复性与审计能力，异常中断后无从追溯。 - 高风险操作可被直接触发，安全与稳定性风险上升。 - 功能扩展和维护成本高，模型能力因缺乏稳定运行载体而难以可靠落地。
安全闭环：复合意图、结构化工具与逐动作审批：背景在自然语言驱动的运维场景中，单条指令常复合检查、创建、删除、重启等多类意图，原有安全机制难以应对这种复杂性。问题旧规则易错误裁剪正常动作，或将“删除”“重启”等常规运维表述直接判为恶意；工具参数、目标节点与审批范围未绑定，导致审批通过一项操作即可能执行多项未授权动作。根因缺少对复合意图的结构化拆解与可执行动作的精确契约定义，依赖粗糙的关键词黑名单及模糊的动作裁剪逻辑，审批对象停留在自然语言整体而非绑定了参数、节点与范围的原子动作。影响存在审批绕过风险（批一项、执行多项），安全控制可靠性下降；误判干扰正常运维，可能导致关键操作被阻断或延迟，影响业务连续性。
可量化质量：RAG 真值与端到端评测：**背景** RAG 系统及端到端 Agent 需要可量化、可追溯的质量评估手段，以验证知识召回、工具选择及审批链路的真实表现。 **问题** 1. 旧评测依赖固定 fixture，无法反映真实场景下的知识召回、工具选择与审批链路质量。 2. 运行态的相关度评分与离线 Recall、F1 混用，产出表面好看但无法追溯的指标。 3. 工具调用结果直接暴露原始 JSON，不适合运维人员阅读和判断。 **根因** - 评测数据与流程脱离真实运行环境，fixture 未覆盖实际动态输入。 - 指标计算口径不一致，缺少明确的标准答案与样本身份绑定，导致离线指标与在线行为混为一谈。 - 结果输出未经过业务语义包装，原始数据直接暴露给非研发角色。 **影响** 评测结论可信度低，无法为模型迭代、检索方案选择与工具链路优化提供可靠依据；同时增加了运维和审计的沟通成本，看似达标的分数掩盖了线上真实质量风险。
真机适配：龙芯 3A5000 与银河麒麟 V11：**背景** 在龙芯 3A5000 处理器 + 银河麒麟 V11 操作系统的国产化真机环境中，将原本仅在 x86 平台验证过的服务构建与部署方案进行移植适配。 **问题** 直接沿用 x86 构建方式导致多项运行时异常，包括：Nginx 的 sigaction 调用与 ABI 不兼容、ONNX wheel 与 CPython ABI 冲突、Maven/JDK 版本不适配、sqlite-jdbc 原生库（JNI）加载失败、RabbitMQ 的 OTP/eldap 依赖及启动竞态等；调试期间容器日志曾膨胀至约 59 GB。 **根因** 前期仅将适配视为架构标签替换，未针对 LoongArch 平台的发行版特性、glibc 版本、Python/C++ ABI、JDK 实现以及中间件运行时进行系统性校验。关键依赖项在未经验证的情况下直接复用 x86 组合，造成接口与底层运行时不一致。 **影响** 多项核心服务无法正常启动或运行不稳定，甚至因日志失控消耗存储资源，严重阻碍国产化平台上的交付与验证进度。
可靠多 Agent：证据契约、幂等与完成裁判：**背景** 系统采用多 Agent 协作架构，通过 RabbitMQ 进行异步通信，并依赖 checkpoint 进行状态恢复。在此类分布式环境中，消息重投、网络超时及恢复重放等场景不可避免，对执行一致性与结果可信性提出更高要求。 **问题** 消息重投或恢复导致包含副作用的操作被重复执行；子 Agent 返回的结果可能缺少动作、在错误节点执行、使用过期缓存；达到迭代上限时容易将未完成的任务误判为成功，致使主 Agent 的决策与真实执行证据严重脱节。 **根因** 缺少持久化的幂等控制账本（action_id）、资源租约、一次性任务凭据和消费 receipt，无法防止重复执行。子任务与结果的定义松散，未通过 plan_digest 严格绑定节点、阶段、工具白名单和返回动作。完成判定未区分“流程结束”与“目标达成”，缺少基于原始执行证据的语义门禁，导致失败、阻塞或结果未知的状态被错误改写为成功，并在副作用结果不明时仍自动重试。 **影响** 主 Agent 基于不可靠或不一致的结果推进流程，无法保证最终产出确实属于当前计划、当前节点和当前动作，整体系统的可靠性与可验证性严重下降。
运维体验：Trace、巡检、审计与专业总结：**背景** 运维人员需通过 Trace、巡检、审计及历史会话等功能进行日常排障与复盘，对系统可观测性提出直观、高效的信息呈现要求。 **问题** - Trace 事件回放点击后缺少直观反馈，更偏向开发者日志查看模式。 - 巡检结果仅展示失败数量，未说明具体对象、失败节点与原因。 - 子 Agent 原始字段直接拼入最终回复，运维人员难以快速判断结果。 - 历史会话、指令及审批信息分散在多个区域，缺乏统一视图。 **根因** 早期设计直接暴露内部 JSON 和原始字段，缺少面向运维角色的信息归约与分层展示；前端未按时序、对象和证据链将关键结果结构化传递，也未对长任务超时做合理处理。 **影响** 运维人员定位问题耗时增加，无法从页面直接获知“发生了什么、影响什么、证据在哪、下一步如何操作”；操作反馈弱，易误判任务最终状态，降低排障与协作效率。
交付收口：语义安全与可复现 CI/CD：**背景** 在“语义安全与可复现 CI/CD”的交付收口阶段，需要确保任意全新服务器上可一键完成可信部署，同时安全策略必须精准有效。 **问题** 1. 同版本下旧 revision 的制品可能被部署脚本误复用，环境文件仍指向历史镜像包，导致部署不符合预期。 2. 新服务器一键部署因绝对路径、基础镜像漂移以及缺少 CI runner 而失败。 3. 基于自然语言关键词的硬拦截策略将 `/home` 等正常路径误判为受保护对象。 **根因** - 部署脚本和环境文件未与目标 revision 唯一绑定，缺少制品完整身份校验。 - 构建与运行链路未固化基础镜像 digest、平台架构及必要的 runner 组件，产生镜像漂移与依赖缺失。 - 安全控制直接由命令层关键词硬匹配实现，缺乏语义理解能力，导致误判。 **影响** - 全新服务器无法一次部署成功，交付不可复现。 - 安全拦截误报干扰正常的业务操作，降低可用性。 - 部署回滚和验收责任不清，制品的交付可信度下降。