Panda工单诊断机器人-架构与实现实战指南

前言

想象一个场景:凌晨三点,值班群跳出一个 CD 部署告警。值班工程师爬起来,登上平台、查工单、切集群、看 Pod 事件,发现是一个 ImagePullBackOff。继续查 Kubelet 日志,发现是 Harbor 节点的磁盘满了。整个过程花了 20 分钟——而这个问题上个月其实已经出现过两次,但每次换人值班,排查过程依然是从零开始。

这是运维诊断的核心矛盾:排查经验是团队最宝贵的资产,但它几乎不可复用。

gops-llm 就是为了解决这个问题而生的。它是一个基于 LLM 的运维工单诊断 Agent——接收失败工单,自动调用排查工具,产出结构化诊断结论。

一句话概括:gops-llm 的核心链路是"Skills 主导诊断流程 → Genkit 驱动工具循环 → Run Engine 记录轨迹 → Signal 后验修正"——从工单到诊断结论的全自动闭环。


1. 系统定位

gops-llm 不是通用 AI 聊天机器人,而是一个垂直于 DevOps 工单诊断的专用 Agent。它严格按照不同工单类型预定义的流程来排查,不自己瞎猜。

支持八种工单类型:

工单类型 场景 诊断 Skill
CD 持续部署失败(镜像拉取超时、Rollout 超时、资源不足等) diagnose-cd
BK-CI 蓝盾流水线构建失败(平台封装版) diagnose-bkci
BK-CI Native 原生蓝盾流水线失败(OOM、超时) diagnose-bkci-native
SQL SQL 变更工单执行失败 diagnose-sql
IaC 基础设施即代码资源申请失败 diagnose-iac
SLS 日志分析 日志异常根因诊断 diagnose-sls-log
SLS 日志查询 交互式日志查询辅助 assist-sls-log-query
Free Form 无工单绑定的自由诊断 diagnose-free-form

每种工单类型对应一个独立的诊断 Skill 文件。诊断流程不硬编码在代码里,而是外置成可独立维护、运行时热加载的 Markdown 文件。 这是整个系统最重要的设计决策之一。


2. 技术栈

组件 选型
语言 Go 1.25
HTTP 框架 Gin
基础框架 Sparrow(内部微服务框架,含配置、日志、服务发现)
Agent 运行时 Firebase Genkit(Go SDK)
LLM 协议 OpenAI 兼容 /v1/chat/completions,通过内部 LLM Gateway 路由
默认模型 qwen3.6-plus(支持 Fallback 模型自动切换)
数据库 MySQL(GORM AutoMigrate)
配置中心 Apollo(热更新)
可观测性 OpenTelemetry OTLP/HTTP → Langfuse
Skills 来源 GitLab 仓库(运行时定期同步到本地)

为什么选 Genkit? 早期系统使用自研的 agentic 框架驱动 tool-calling 循环。随着工具数量膨胀到 20+、需要支持子任务委派和工具 ACL 控制,自研框架的维护成本迅速上升。Firebase Genkit 的 Go SDK 提供了开箱即用的 Generate() 循环、中间件机制、流式输出和 OpenTelemetry 集成,迁移后代码量减少约 40%。选 Genkit 而不是 LangChain,是因为 Genkit 是 Go 原生的,和我们的技术栈天然契合,不需要引入多语言维护成本。


3. 架构全景

3.1 项目目录结构

gops-llm/
├── cmd/server/
│   ├── main.go              # 入口:Sparrow Application.Startup() 三阶段启动
│   └── bootstrap.go         # 所有子系统的组装和接线
├── internal/
│   ├── agent/               # Agent 核心
│   │   ├── agent.go         # 主循环(Session → Prompt → Genkit → 后处理)
│   │   ├── session.go       # 会话管理(内存 + MySQL 持久化)
│   │   └── session_store.go # 带 TTL 的内存 SessionStore
│   ├── genkit/              # Genkit 运行时 & 工具
│   │   ├── init.go          # Genkit 实例初始化(模型注册)
│   │   ├── runner.go        # RunDiagnosis:中间件装配 + Generate 循环
│   │   ├── tools.go         # RegisterAllTools:20+ 工具注册
│   │   ├── middleware_skills.go  # SkillsWithACL:Skills 加载 + 工具 ACL
│   │   ├── sse_bridge.go    # SSE 流式事件桥接
│   │   ├── context.go       # 上下文传递(环境变量、ticket 信息)
│   │   └── tool_*.go        # 各类工具实现(20+ 文件)
│   ├── diagnosis/           # 诊断结果
│   │   ├── extractor.go     # 结构化分类提取(LLM 二次调用)
│   │   ├── output.go        # DiagnosisOutput 模型 + Verdict 映射
│   │   ├── model.go         # 数据模型
│   │   └── storage_mysql.go # MySQL 存储
│   ├── run/                 # Run Engine
│   │   ├── engine.go        # 诊断运行生命周期管理
│   │   ├── snapshot.go      # RunSnapshot 不可变快照
│   │   ├── model.go         # DiagnosisRun 数据模型
│   │   └── storage_mysql.go # MySQL 存储
│   ├── signal/              # 反馈信号
│   │   ├── processor.go     # Signal 处理 + Verdict 状态机
│   │   └── model.go         # 信号类型定义
│   ├── skill/               # Skills 同步
│   │   └── syncer.go        # GitLab 多仓库同步
│   ├── gitlab/              # GitLab 客户端
│   │   └── client.go        # API 客户端(文件读取、目录遍历)
│   ├── observe/             # 可观测性
│   │   └── tracer.go        # OpenTelemetry → Langfuse OTLP 导出
│   ├── config/              # 配置
│   │   └── config.go        # Apollo 热更新 + atomic.Pointer
│   ├── api/                 # HTTP 路由
│   │   ├── router.go        # 路由注册
│   │   ├── handler_agent.go # SSE 诊断端点
│   │   ├── handler_run.go   # Run 查询端点
│   │   ├── handler_signal.go # Signal 提交端点
│   │   └── handler_proxy.go # LLM 代理端点
│   └── server/              # HTTP 服务器
│       └── server.go        # Gin + Sparrow 包装
├── skills/                  # 内置 Skill 文件
└── docs/                    # 设计文档

3.2 四层架构图

flowchart TB
    subgraph L1["Layer 1: 入口"]
        API["POST /api/v1/agent/chat
SSE 流式"] end subgraph L2["Layer 2: Agent 核心"] SESSION["Session 管理
内存 + MySQL"] PROMPT["System Prompt 组装
角色 + 工单上下文 + Skill 路由"] GENKIT["Genkit Runtime
Generate() 循环(最多 100 轮)
中间件链:Skills → SSE → Fallback → Retry"] SESSION --> PROMPT --> GENKIT end subgraph L3["Layer 3: 工具层"] SKILL["use_skill / list_skills"] BASH["bash"] DIAG["诊断工具
confirm_diagnosis / query_diagnosis_cache"] GIT["git_inspect"] HTTP["http_fetch / web_search"] LOG["log_grep"] IAC["IaC 工具套件
(8 个专用工具)"] SLS["SLS 工具套件
(4 个专用工具)"] DELEGATE["delegate_task
(并行子 Agent)"] end subgraph L4["Layer 4: 反馈与轨迹"] RUN["Run Engine
轨迹记录 + 快照"] SIGNAL["Signal 处理
Verdict 状态机"] RUN --> SIGNAL end API --> SESSION GENKIT --> SKILL & BASH & DIAG & GIT & HTTP & LOG & IAC & SLS & DELEGATE GENKIT -->|创建 Run| RUN

4. 端到端诊断流程

4.1 请求生命周期

flowchart TB
    A["POST /api/v1/agent/chat (SSE)"] --> B["Session 管理"]
    B -->|恢复已有会话| C["多轮对话继续"]
    B -->|新会话| D["缓存检查"]
    D -->|命中| E["指示 Agent 参考历史诊断"]
    D -->|未命中| F["System Prompt 组装"]
    F --> G["Run Engine 创建 DiagnosisRun"]
    G --> H["构建 RunSnapshot
冻结工单信息"] H --> I["Genkit Generate() 执行
中间件链:Skills → SSE → Fallback → Retry"] I --> J["SSE 流式输出
chunk / tool_call / tool_result"] J --> K["异步后处理"] K --> K1["LLM 提取结构化分类
(ExtractDiagnosisOutput)"] K --> K2["回填 verdict_level / trust_score / error_signature"] K --> K3["双写 diagnosis_results(兼容旧系统)"]

关键设计:SSE 流先结束,分类提取在后台异步执行。 因为用户只想尽快看到排查结论的流式输出,结构化分类(出故障报表用)如果在主链路中做,会让首字响应慢好几秒。

4.2 System Prompt 组装

Agent 的 System Prompt 由三部分拼接:

  1. 角色声明:你是一个专业的 DevOps 诊断 Agent
  2. 工单上下文:ticket_id、ticket_type、相关元数据
  3. Skill 路由指令:根据 ticket_type 映射到对应 Skill(cd → diagnose-cd),指示 Agent 第一步调用 use_skill 加载该 Skill

Skill 路由映射表:

ticket_type Skill
cd diagnose-cd
bkci diagnose-bkci
bkci_native diagnose-bkci-native
sql diagnose-sql
iac diagnose-iac
free_form diagnose-free-form
sls_log_analysis diagnose-sls-log
sls_log_query assist-sls-log-query

此外,系统还支持自动推断:如果 ticket_id 匹配 b-<uuid> 模式,自动识别为 BK-CI 工单。

Agent 的诊断能力可以通过更新 Skill 文件来改进,不需要改一行代码。

4.3 Genkit Runtime

核心循环由 Firebase Genkit 的 Generate() 驱动。RunDiagnosis() 负责装配中间件链和执行:

中间件链:SkillsWithACL → SSEBridge → Fallback → Retry
                ↓
Generate(ctx, model, systemPrompt, history, tools, maxTurns=100, streaming=true)
                ↓
每轮:LLM 返回 tool call → 执行工具 → 把结果喂回 LLM → 重复
                ↓
直到 LLM 输出纯文本(诊断结论)或达到轮次上限

四层中间件各自职责:

中间件 职责
SkillsWithACL Skills 加载、工具 ACL 过滤、References 注入
SSEBridge 拦截工具调用事件,转为 SSE tool_call / tool_result 事件
Fallback 主模型 429 限流时自动切备用模型
Retry 临时错误自动重试

5. Skills 驱动的诊断

5.1 先说人话

如果把 LLM 当作刚入职的实习生,那 Skill 文件就是你扔给他的"新人排查手册"。Skill 是一份纯 Markdown 文件,明确告诉 Agent 第一步查什么命令,第二步怎么分析日志,不能瞎操作哪些危险动作。这不是代码,这是数据。

5.2 Skill 文件结构

每个 Skill 是一个目录,核心是 SKILL.md 文件,可选包含 references/ 子目录:

skills/
├── diagnose-cd/
│   ├── SKILL.md            # 主文件:YAML frontmatter + 诊断指引
│   └── references/         # 可选:补充参考资料
│       └── pod-events.md
├── diagnose-iac/
│   ├── SKILL.md
│   └── references/
│       ├── argo-workflow.md
│       └── terraform-errors.md
└── ...

SKILL.md 的 YAML frontmatter 定义元数据,其中最关键的是 allowed_tools——工具 ACL:

---
name: diagnose-iac
description: IaC 资源申请工单诊断
allowed_tools:
  - iac_order_detail
  - iac_build_detail
  - iac_build_logs
  - iac_argo_status
  - iac_module_variables
  - iac_package_diagnose
  - iac_check_domain_icp
  - iac_check_domain_cdn
  - confirm_diagnosis
  - query_diagnosis_cache
---

当 Agent 加载了这个 Skill,它只能调用列表中声明的工具。为什么要加这个限制? 实测发现,Agent 在没有约束的情况下,IaC 诊断时会"灵机一动"去调用 bash 执行 kubectl 命令——而 IaC 工单根本不涉及 K8s 集群。工具 ACL 给 Agent 划了明确的边界。

5.3 SkillsWithACL 中间件

这是 Skills 系统的核心引擎,扩展了 Genkit 内置的 Skills 中间件,增加了三个能力:

  1. 工具 ACL 过滤:解析 allowed_tools,在 WrapGenerate 中过滤工具定义,让 LLM 看不到不允许的工具
  2. Skill 激活跟踪:WrapTool 跟踪当前活跃的 Skill,在上下文中传递
  3. References 自动注入:当 Agent 调用 use_skill 时,自动追加 references/ 目录下所有 .md 文件的内容

5.4 加载与同步

flowchart LR
    A["GitLab 仓库
(多个 repo)"] -->|定期同步(默认 30m)| B["本地 ./skills 目录"] B -->|Genkit SkillsWithACL| C["use_skill 工具注册"] C -->|Agent 调用| D["Skill 内容 + References 注入上下文"] D -->|ACL 生效| E["工具列表动态过滤"]

skill.Syncer 从 GitLab 定期拉取 Skill 文件,支持多仓库多分支配置。同步时自动将扁平 .md 转换为 Genkit Skill 目录结构(diagnose-cd.md → diagnose-cd/SKILL.md),已结构化的文件保持原样。

这意味着 SRE 团队可以像维护文档一样维护诊断流程——在 GitLab 上编辑 Markdown,不需要发版、不需要重启服务,下次诊断自动生效。


6. 工具系统

6.1 先说人话

Agent 的诊断能力不取决于 LLM 有多聪明,而取决于它手里有什么工具。gops-llm 注册了 20+ 工具,覆盖从通用 Shell 执行到 IaC 资源诊断、SLS 日志分析的全链路。

6.2 通用工具(始终注册)

工具 功能 关键参数
bash Shell 命令执行 默认 30s 超时,最大 300s,输出限制 32KB
confirm_diagnosis 记录用户确认的根因 写入 diagnosis storage
query_diagnosis_cache 查询历史诊断缓存 按 ticket_id + ticket_type 匹配
git_inspect 只读 Git 操作 支持 log / diff / show / blame 等
http_fetch HTTP 请求 自动为内部域名注入认证头
log_grep SLS 日志搜索 通过 poi CLI 执行
web_search 网络搜索 条件注册,需配置搜索端点

bash 工具执行时自动注入环境变量(AUTH_KEY、BKCI_DOMAIN 等),使 Skill 文件中的 CLI 命令能直接使用平台认证。当前通过 bash + Skill 中的 CLI 指令(主要是 poi CLI)直接调用外部排查工具。 简单够用,不需要为每个排查操作单独封装工具。

6.3 IaC 专用工具(8 个)

IaC 诊断是最复杂的场景——一个资源申请失败可能涉及工单系统、CI 流水线、Argo Workflow、Terraform Module、域名备案等多个环节。为此封装了完整的工具链:

工具 功能
iac_order_detail 查工单详情:哪些资源、什么状态
iac_build_detail 查 BK-CI 构建:哪一步失败了
iac_build_logs 看构建日志:自动过滤错误行,支持分页
iac_argo_status 查 Argo Workflow:DAG 哪个节点挂了
iac_module_variables 读 Terraform Module 的 variables.tf
iac_package_diagnose 一站式聚合诊断(工单 + Argo + 失败构建)
iac_check_domain_icp 域名 ICP 备案检查(阿里云 OpenAPI v3)
iac_check_domain_cdn CDN 域名所有权验证(阿里云 OpenAPI v3)

6.4 SLS 日志工具(4 个)

日志分析有两种模式:

模式一:日志异常诊断(sls_log_analysis)——给一条锚点日志,Agent 自动展开上下文分析:

工具 功能
sls_log_diagnosis 获取锚点日志 + 上下文候选列表
sls_log_context_window 按时间窗口和字段过滤获取上下文日志

模式二:日志查询助手(sls_log_query)——帮用户写 SLS 查询语句:

工具 功能
sls_query_context 获取 SLS 索引字段和已保存查询模板
sls_query_verify 验证用户编写的查询语句是否有效

6.5 delegate_task:并行子 Agent

这是系统中最特殊的工具。它接收一组子任务描述,为每个子任务派一个独立的 Genkit Generate() 调用,并行执行:

为什么要并行? IaC 工单诊断时,需要同时查工单详情、Argo 状态、BK-CI 构建日志。串行执行总耗时 3 分钟,用户体感极差。delegate_task 让这些查询并行,总耗时压缩到最慢的那一个。

6.6 工具注册机制

所有工具通过 RegisterAllTools() 统一注册为 Genkit Tool。每个工具是一个泛型函数 genkit.DefineTool[Input, Output](),自带 JSON Schema 参数校验。delegate_task 最后注册——它在注册时接收所有其他工具的引用,这样子 Agent 可以使用完整的工具集。


7. Signal 反馈与 Verdict 状态机

7.1 先说人话

没有人能保证每次诊断都是百分百对的。用户在前端点个"赞"或"踩",甚至工单最终被关闭的事件,都会作为 Signal(信号) 回传给系统,持续修正这条诊断记录的"质量评级"。

7.2 五种信号

信号 来源 含义 Trust Score 增量
accurate 用户 确认诊断正确 +0.15
disputed 用户 否定诊断 -0.40
confirmed 维护者 维护者确认 +0.30
rejected 维护者 维护者拒绝 -0.40
resolved 系统 工单已解决 +0.15

非对称惩罚是刻意设计:一条错误诊断的误导代价远大于缺失一条参考。 否定一次扣 0.40,确认一次才加 0.15——需要至少三次正向反馈才能抵消一次否定。Trust Score 始终 clamp 在 [0, 1] 范围内。

7.3 Verdict 状态转换

stateDiagram-v2
    C --> B : accurate
    C --> D : disputed
    B --> A : confirmed / resolved
    B --> D : disputed / rejected
    A --> B : disputed
Level 含义 默认
A 维护者确认的高质量诊断 -
B 用户确认的可信诊断 -
C 无反馈的初始诊断 是(trust_score=0.5)
D 被否定的诊断 -

当 verdict 降到 D 时,memory_status 自动设为 rejected——该条记录被标记为不可信。


8. 核心数据表

8.1 diagnosis_runs(中枢表)

整个轨迹和反馈体系的中枢。Signal 反馈直接写入该表,verdict_level 和 trust_score 原地更新。

字段 类型 含义
ticket_id varchar(128) 工单 ID
ticket_type varchar(32) cd / bkci / sql / iac / sls_log_analysis 等
service / module / env varchar 关联服务、模块、环境
snapshot_json JSON 创建时冻结的 RunSnapshot
final_result_json JSON 结构化诊断结果(DiagnosisOutput)
verdict_level varchar(8) A / B / C / D
trust_score decimal(3,2) 0.00-1.00
error_signature varchar(256) 归一化错误特征
memory_status varchar(16) active / rejected
signals_json JSON 所有反馈信号数组
status varchar(16) running / completed / failed
source varchar(16) online / shadow
trace_id varchar(64) Langfuse trace ID

8.2 辅助表

表 用途
diagnosis_results 兼容旧系统的缓存表,双写保证存量不受影响
diagnosis_conversations 会话持久化(session_id + messages JSON),支持跨重启恢复多轮对话

9. 可观测性与配置

9.1 Langfuse 追踪

系统通过 OpenTelemetry 将 Trace 数据导出到 Langfuse:

OpenTelemetry TracerProvider(全局注册)
    └── OTLP/HTTP Exporter → Langfuse
        └── Basic Auth(PublicKey:SecretKey)

Genkit 的 Generate() 自动在全局 TracerProvider 上创建 Span。Agent.Run() 额外创建根诊断 Span,注入 Langfuse 属性(trace.name、session.id、ticket.id、ticket.type)。diagnosis_runs.trace_id 关联到 Langfuse,可从诊断记录直接跳转查看完整调用链。

工具调用轨迹由 Langfuse 承接,不需要自建 step 表。

9.2 Apollo 热更新

所有核心配置通过 Apollo 远程管理,使用 atomic.Pointer[Config] 实现无锁热更新:

配置项 作用
RunEngine.Enabled Run Engine 总开关
RunEngine.DualWrite 是否同时写旧 diagnosis_results 表
Agent.MaxTurns 最大工具调用轮次(默认 100)
Agent.SessionTTL 会话过期时间(默认 30 分钟)
SkillsSync.Interval Skills 同步间隔(默认 30 分钟)
Langfuse.Enabled Langfuse 追踪开关

9.3 容错机制

容错机制 场景
Fallback 中间件 LLM 429 限流时自动切换到 fallback 模型
Retry 中间件 临时错误自动重试
双写兼容 新旧两张表同时写入,保证存量系统不受影响
存储降级 MySQL 不可用时自动降级为本地 JSON 文件存储

9.4 API 路由

路由 方法 功能
/api/v1/agent/chat POST 主诊断端点(SSE 流式)
/api/v1/signal POST 提交反馈信号
/api/v1/runs GET 查询诊断记录列表
/api/v1/runs/:id GET 查询单条诊断记录
/api/v1/proxy/*/messages POST LLM 代理(Anthropic / OpenAI 格式)
/health GET 健康检查
/swagger/* GET API 文档

10. 完整数据流:一个 CD 工单的一生

让我们把上面的机制串起来看,假设 Harbor 磁盘满导致 ImagePullBackOff:

1. 破冰(First Encounter)

报警触发,平台调用 POST /api/v1/agent/chat。Agent 创建 Session 和 DiagnosisRun,构建 RunSnapshot 冻结工单信息。System Prompt 组装完成后,Agent 调用 use_skill("diagnose-cd") 加载诊断 Skill,SkillsWithACL 激活工具限制并注入 references 内容。

Agent 按 Skill 指引执行排查:

LLM 结合 Skill 中的排查步骤和通用知识给出根因判断,SSE 流式返回诊断结论。异步后处理提取结构化分类,回填 verdict_level=C、trust_score=0.50。

2. 确认(Feedback)

提单人看了诊断,去清理了磁盘解决了问题,顺手点了个赞。Signal 机制触发:verdict 升为 B,trust_score 上涨到 0.65。

3. 加速(Cache Hit)

第二天,隔壁组也遇到了同样的错。Agent 通过 query_diagnosis_cache 命中上次的诊断结论,参考历史结果,诊断速度大幅提升。

这就是当前的核心闭环——Skills 定义流程,工具执行查询,Signal 修正质量。


11. 设计决策与演进方向

11.1 明确不做的事

不做 原因
长会话上下文治理 工单排查讲究快准狠,以单次诊断为主,不需要复杂的会话压缩
模型微调 先把 Skill + Signal 反馈闭环跑到极致,ROI 更高
Embedding 语义检索 当前通过 Skills + 专用工具直接查询更精准,不需要向量数据库

11.2 演进方向

当前系统已经具备了完善的多领域诊断能力(8 种工单类型、20+ 工具)和质量追踪机制(Signal + Verdict)。下一步的重点方向:

方向 描述
记忆召回 基于 error_signature 和 verdict 的历史案例召回,注入诊断上下文,让 Agent 拥有"团队记忆"
语料沉淀 将反复出现且质量高的诊断自动聚类、提炼为可复用语料,推送到知识库
评测回流 标注数据 + 离线评测 pipeline,量化诊断质量并反向修正门槛

最终目标:从"做诊断"到"沉淀诊断",从"解决一个工单"到"解决一类工单"。


12. 核心参考资料

资料 位置
Agent 核心代码 gops-llm/internal/agent/agent.go
Genkit 运行时 gops-llm/internal/genkit/runner.go
工具注册与实现 gops-llm/internal/genkit/tools.go + tool_*.go
Skills ACL 中间件 gops-llm/internal/genkit/middleware_skills.go
Signal 状态机 gops-llm/internal/signal/processor.go
Run Engine gops-llm/internal/run/engine.go
诊断分类提取 gops-llm/internal/diagnosis/extractor.go