Logan.Li
1c98c25c74
RunResult 增加 Outcome/Reason；触顶标记 incomplete:max_steps； WebSocket finish 区分 incomplete 与 fatal error。补充 ai-agent docs 13 与挂点索引。
334 lines
16 KiB
Markdown
334 lines
16 KiB
Markdown
# Agent CLI 代码审计与平台智能化优化
|
||
|
||
> 更新：2026-07-05
|
||
> 范围：Agent CLI、智能助手、告警分析、预测分析，以及它们如何关联 AIOps 平台资产、告警、指标、日志、Kubernetes 和 CMDB。// Logan.Li
|
||
|
||
---
|
||
|
||
## 结论
|
||
|
||
当前 Agent CLI 的执行底座已经可用：WebSocket 会话、ReAct 主循环、工具调用、安全确认、会话持久化、历史恢复和 Evolver 记忆都已落地。
|
||
|
||
真正需要升级的是“平台上下文能力”。现在模型主要能操作目标主机或 Kubernetes 目标，但它还不能像专业 AIOps Agent 一样主动查询平台内的 CMDB、告警历史、指标趋势、日志片段、发布变更、拓扑依赖和相似事故。
|
||
|
||
一句话：**Agent CLI 已经具备执行能力，但智能助手、告警分析、预测分析要从“页面拼 prompt”升级为“平台上下文工具 + 证据链推理 + 可审计闭环”。**
|
||
|
||
2026-07-05 第一版已落地：
|
||
|
||
| 能力 | 状态 | 代码位置 |
|
||
|------|------|----------|
|
||
| AIOps 上下文服务 | 已完成第一版 | `backend/pkg/aiopscontext/` |
|
||
| 平台总览接口 | 已完成 | `GET /api/v1/aiops/context/summary` |
|
||
| 目标上下文包接口 | 已完成 | `POST /api/v1/aiops/context/pack` |
|
||
| Agent CLI 资产搜索工具 | 已完成 | `aiops_asset_search` |
|
||
| Agent CLI 告警查询工具 | 已完成 | `aiops_alert_list` |
|
||
| Agent CLI 指标摘要工具 | 已完成 | `aiops_metric_summary` |
|
||
| 智能助手总览快捷操作接入 | 已完成第一版 | `AIOpsAssistant.tsx` |
|
||
| 告警 RCA 后端化 | 已完成第一版 | `POST /api/v1/aiops/alert-analysis` |
|
||
| 告警 RCA Trace 与上下文落库 | 已完成第一版 | `ai_analysis_traces` / `GET /api/v1/aiops/analysis-traces/:trace_id` |
|
||
| MCP Server 暴露 | 待增强 | 后续基于 `pkg/aiopscontext` 封装 |
|
||
|
||
---
|
||
|
||
## 当前代码观察
|
||
|
||
### 已完成能力
|
||
|
||
| 能力 | 代码位置 | 说明 |
|
||
|------|----------|------|
|
||
| ReAct 循环 | `backend/pkg/agentcli/core/agent.go` | 16 轮主循环、工具调用、输出裁剪、循环检测 |
|
||
| 工具注册 | `backend/pkg/agentcli/agentcli.go` | 主机模式注册 `ssh_execute`，K8s 模式注册 `kubernetes_get/pod_logs/pod_execute/kubernetes_action` |
|
||
| 安全确认 | `backend/pkg/agentcli/safety/safety.go` | high+ 操作触发 WebSocket 确认，critical 硬拒 |
|
||
| 会话持久化 | `backend/controller/agent_cli.go` | `agent_cli_sessions` / `agent_cli_messages` |
|
||
| 历史追问 | `backend/controller/agent_cli_history.go` | 从历史消息恢复 LLM 上下文 |
|
||
| 智能助手上下文 | `frontend/src/components/aiops/AIOpsAssistant.tsx` | 快捷操作会拉取告警、Agent 指标、仪表盘数据拼进 prompt |
|
||
| 预测分析 | `frontend/src/components/aiops/predictUtils.ts` | 指标趋势、容量预测、成本预测已有本地算法 |
|
||
|
||
### 主要缺口
|
||
|
||
| 优先级 | 缺口 | 影响 |
|
||
|--------|------|------|
|
||
| P0 | 没有 AIOps 平台上下文工具 | Agent 只能查远端现场，不能查 CMDB、告警、指标、日志、变更和相似事故 |
|
||
| P0 | 告警分析缺证据链 | 当前更多是单条告警 + LLM/规则模板，无法解释“为什么是这个根因” |
|
||
| P0 | 智能助手上下文在前端拼接 | 逻辑散在页面，难复用、难审计、难做权限过滤 |
|
||
| P1 | K8s Agent 连接预检仍可能阻塞 | `loadKubernetesAgentContext` 会同步 `ListNamespaces/ListPods`，不可达集群会影响连接体验 |
|
||
| P1 | Agent 工具 trace 不够细 | 告警 RCA 已有 trace/span 和上下文包落库；Agent CLI 工具调用还需要补 parent_span_id、输入脱敏、输出大小、工具耗时分布 |
|
||
| P1 | RBAC 工具裁剪未落地 | 不同角色看到的工具应不同，例如只读用户不能拿到 `ssh_execute` 写操作能力 |
|
||
| P1 | Evolver 记忆仍偏文件化 | 企业版需要 DB 化、可检索、可删除、可按租户/用户/资产隔离 |
|
||
| P2 | 预测分析还在前端计算 | 适合先验证体验，后续应迁到后端任务，支持定时预测、历史留存和告警联动 |
|
||
|
||
---
|
||
|
||
## 外部对标
|
||
|
||
| 参考 | 可借鉴点 | AIOps 落地 |
|
||
|------|----------|------------|
|
||
| [ReAct](https://arxiv.org/abs/2210.03629) | 推理和行动交替，行动从外部系统取证，观察结果反哺下一轮推理 | 保持当前 ReAct 主循环，但工具要扩展到平台数据 |
|
||
| [SWE-agent ACI](https://arxiv.org/abs/2405.15793) | 专门为模型设计 Agent-Computer Interface，工具反馈格式影响智能体表现 | AIOps 工具返回结构化摘要，而不是把页面文本或原始大 JSON 丢给模型 |
|
||
| [HolmesGPT](https://github.com/HolmesGPT/holmesgpt) | SRE Agent 聚焦 incident、Kubernetes、Prometheus、observability | 告警分析应自动拉取指标、日志、事件和资源状态 |
|
||
| [Robusta](https://github.com/robusta-dev/robusta) | Prometheus/Kubernetes 告警增强、分组、AI enrichment、自动修复 | AIOps 告警中心可做告警分组、上下文增强、修复建议 |
|
||
| [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) | Prompt、上下文、工具、暂停恢复、人工确认都应工程化 | 把前端快捷 prompt 升级为后端上下文包和工具层 |
|
||
| [OpenAI Agents Guardrails](https://openai.github.io/openai-agents-python/guardrails/) | 输入、输出、工具调用都要有 guardrail | 告警自动修复脚本、命令执行、K8s action 都做输入/输出校验 |
|
||
| [OpenAI Agents Tracing](https://openai.github.io/openai-agents-python/tracing/) | 记录 Agent、LLM、工具、guardrail、自定义事件 | 在 `agent_cli_messages` 基础上补 `trace_id/span_id/tool_audit` |
|
||
|
||
---
|
||
|
||
## 推荐目标架构
|
||
|
||
```text
|
||
智能助手 / 告警分析 / 预测分析 / Agent CLI
|
||
│
|
||
▼
|
||
AIOps AI Orchestrator
|
||
├─ Context Pack Builder
|
||
├─ Tool Registry
|
||
├─ Guardrail / RBAC / Approval
|
||
├─ Trace / Audit
|
||
└─ LLM Client
|
||
│
|
||
▼
|
||
AIOps Context Graph
|
||
├─ CMDB: 服务器、云资源、K8s 集群、应用、环境、负责人
|
||
├─ Observability: 指标、日志、事件、拨测、SNMP、中间件
|
||
├─ Alerts: 当前告警、历史告警、静默、通知、相似事故
|
||
├─ Changes: 发布、流水线、脚本、定时任务、审批
|
||
└─ Security: 凭证、权限、会话审计、命令审计
|
||
```
|
||
|
||
核心不是马上上复杂图数据库，而是先实现一个轻量的 `Context Pack`：给定 `target/alert_id/cluster/pod/time_range`，后端统一返回可控、脱敏、限长、带来源的数据包。
|
||
|
||
### 为什么先做内部 Tool 层，再做 MCP
|
||
|
||
MCP 适合作为外部协议入口，但 AIOps 平台内置 Agent CLI 已经有自己的权限、确认、审计和会话体系。如果一开始只做 MCP，会绕开一部分现有治理能力。
|
||
|
||
推荐顺序：
|
||
|
||
```text
|
||
pkg/aiopscontext
|
||
├─ 内部工具：注册到 Agent CLI tools.Registry
|
||
├─ REST 接口：智能助手 / 告警分析 / 预测分析复用
|
||
└─ MCP Server：后续对外暴露给 Codex、Claude Desktop、opsxcli 等外部 Agent
|
||
```
|
||
|
||
这样 MCP 不是几组零散接口，而是 AIOps 上下文服务的一个协议外壳。
|
||
|
||
---
|
||
|
||
## 平台上下文工具清单
|
||
|
||
### P0 只读工具
|
||
|
||
| 工具 | 输入 | 输出 | 用途 |
|
||
|------|------|------|------|
|
||
| `aiops_asset_search` | `keyword/ip/hostname/tag` | 资产、负责人、环境、云厂商、凭证状态 | 让模型先识别对象是谁 |
|
||
| `aiops_alert_list` | `target/severity/status/time_range` | 告警列表和统计 | 关联同一目标近期告警 |
|
||
| `aiops_alert_detail` | `alert_id` | 告警详情、规则、阈值、当前值 | 单告警 RCA 起点 |
|
||
| `aiops_metric_summary` | `target/metric/time_range` | min/max/avg/p95、趋势、异常点 | 判断是否趋势性恶化 |
|
||
| `aiops_log_search` | `target/query/time_range` | 日志片段、错误聚类、样例 | RCA 证据 |
|
||
| `aiops_k8s_context` | `cluster/namespace/pod` | Pod、事件、重启、镜像、节点、owner | K8s 排障上下文 |
|
||
| `aiops_change_window` | `target/time_range` | 发布、脚本、审批、定时任务 | 关联变更导致故障 |
|
||
| `aiops_similar_incidents` | `fingerprint` | 相似告警、历史处理结果 | 经验复用 |
|
||
|
||
第一版已实现其中 3 个 P0 工具：
|
||
|
||
| 工具 | 实现状态 | 说明 |
|
||
|------|----------|------|
|
||
| `aiops_asset_search` | 已完成 | 查 `asset_servers`，只返回脱敏资产摘要 |
|
||
| `aiops_alert_list` | 已完成 | 合并 `monitor_alert_events` 和 `monitor_agent_alerts` |
|
||
| `aiops_metric_summary` | 已完成 | 查 `monitor_agent_reports`，返回 latest/min/max/avg/p95/trend |
|
||
|
||
### P1 动作工具
|
||
|
||
| 工具 | 风险 | 说明 |
|
||
|------|------|------|
|
||
| `aiops_create_diagnosis_task` | low | 生成诊断任务，不直接执行 |
|
||
| `aiops_open_terminal_session` | medium | 打开 SSH/RDP/Pod/kubectl 会话，审计关联 |
|
||
| `aiops_run_readonly_playbook` | medium | 执行只读诊断脚本 |
|
||
| `aiops_apply_fix_plan` | high | 修复动作必须审批或二次确认 |
|
||
|
||
---
|
||
|
||
## 智能助手优化
|
||
|
||
当前智能助手的快捷操作已经会拉真实告警和指标，但逻辑在前端：
|
||
|
||
```text
|
||
AIOpsAssistant.tsx
|
||
├─ loadAlertsContext()
|
||
├─ loadMetricsContext()
|
||
└─ loadReportContext()
|
||
```
|
||
|
||
建议升级：
|
||
|
||
1. 后端新增 `GET /api/v1/aiops/context/summary`，统一返回平台概览、活跃告警、高负载主机、近期发布、成本摘要。
|
||
2. 后端新增 `POST /api/v1/aiops/context/pack`，按目标构建上下文包。
|
||
3. 智能助手 prompt 不直接拼页面数据，而是调用上下文接口并带来源字段。
|
||
4. 多轮对话记录关联 `context_pack_id`，后续能回放“当时模型看到了哪些数据”。
|
||
|
||
推荐输出格式：
|
||
|
||
```json
|
||
{
|
||
"scope": "host:10.0.0.1",
|
||
"time_range": "2026-07-05T10:00:00+08:00/2026-07-05T11:00:00+08:00",
|
||
"assets": [],
|
||
"alerts": [],
|
||
"metrics": [],
|
||
"logs": [],
|
||
"changes": [],
|
||
"evidence": [
|
||
{"source": "agent_report", "summary": "CPU p95 92%", "confidence": 0.82}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 告警分析优化
|
||
|
||
当前告警分析流程是：
|
||
|
||
```text
|
||
选择单条告警 → prompt 包含告警字段 → LLM 输出 JSON → 失败回退规则模板
|
||
```
|
||
|
||
建议升级为：
|
||
|
||
```text
|
||
alert_id
|
||
→ Alert Detail
|
||
→ 资产/服务/负责人/环境
|
||
→ 同目标近 2h 告警
|
||
→ 指标窗口: 触发前 30m + 触发后 30m
|
||
→ 日志错误 TopN
|
||
→ K8s 事件/Pod 重启/发布变更
|
||
→ RCA JSON + 证据链 + 修复计划
|
||
```
|
||
|
||
RCA 输出不要只要自然语言，建议固定结构：
|
||
|
||
```json
|
||
{
|
||
"root_cause": "最可能根因",
|
||
"confidence": 0.78,
|
||
"evidence": [
|
||
{"type": "metric", "source": "agent_report", "detail": "CPU 从 35% 升到 96%"},
|
||
{"type": "log", "source": "loki", "detail": "出现 timeout/refused 错误"}
|
||
],
|
||
"impact": "影响范围",
|
||
"next_checks": ["还需要确认的点"],
|
||
"fix_plan": [
|
||
{"step": "只读检查", "risk": "safe"},
|
||
{"step": "重启服务", "risk": "high", "requires_approval": true}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 预测分析优化
|
||
|
||
当前预测分析以页面计算为主，适合展示，但还不是平台能力。
|
||
|
||
建议拆成三层：
|
||
|
||
1. **短期异常预测**：基于最近 1h/24h 指标，发现 CPU、内存、磁盘、网络的趋势性异常。
|
||
2. **容量预测**：基于 7d/30d/90d 时序，预测达到阈值的剩余时间。
|
||
3. **业务风险预测**：关联 CMDB、告警、变更、应用等级，输出“哪个业务风险最高”。
|
||
|
||
预测不应只输出“CPU 会涨到多少”，而应输出：
|
||
|
||
```text
|
||
对象：生产环境 / app=payment / node=xxx
|
||
风险：内存 5 天后可能超过 90%
|
||
证据：过去 7 天日均增长 3.2%，最近 24h 增速加快
|
||
关联：同节点近 24h 有 OOMWarning 2 次，昨日有发布变更
|
||
建议：扩容、限制缓存、检查内存泄漏、安排低峰窗口处理
|
||
```
|
||
|
||
---
|
||
|
||
## 落地阶段
|
||
|
||
### 第 1 阶段：可用智能分析
|
||
|
||
周期：1-3 天。
|
||
|
||
1. 新增 `aiops/context/summary` 和 `aiops/context/pack` 后端接口。（已完成第一版）
|
||
2. Agent CLI 新增只读平台工具：`aiops_asset_search`、`aiops_alert_list`、`aiops_metric_summary`。（已完成第一版）
|
||
3. 智能助手、告警分析、预测分析统一改用后端上下文包。（智能助手总览、告警分析已接入，预测分析待迁移）
|
||
4. 告警分析补充同目标近期告警、指标摘要、资产信息。（已完成第一版）
|
||
|
||
验收标准：
|
||
|
||
- 告警分析结果至少包含 3 条可追溯证据。
|
||
- 智能助手回答能引用平台实际资源和告警。
|
||
- 不可达 K8s/数据源不会阻塞其他页面。
|
||
|
||
### 第 2 阶段：企业级 RCA
|
||
|
||
周期：1-2 周。
|
||
|
||
1. 增加 `trace_id/span_id`，告警 RCA 已完成 root span；后续继续打通 Agent CLI 工具调用、确认、输出。
|
||
2. 工具 RBAC 裁剪，不同角色拥有不同工具集。
|
||
3. 上下文包落库，告警 RCA 已支持回放和审计；预测分析、智能助手、Agent CLI 后续统一接入。
|
||
4. 相似事故检索：按目标、指标、错误关键词、解决方案做 fingerprint。
|
||
5. 修复计划接审批流，避免模型直接执行高危动作。
|
||
|
||
验收标准：
|
||
|
||
- 每次 AI 分析都能回放输入数据、工具调用和最终结论。
|
||
- 高危修复必须进入确认或审批。
|
||
- 相似事故能命中历史会话/告警。
|
||
|
||
### 第 3 阶段：预测与闭环
|
||
|
||
周期：3-6 周。
|
||
|
||
1. 预测任务后端化：定时生成容量、成本、可用性风险。
|
||
2. 预测结果转告警规则或风险事件。
|
||
3. 引入拓扑依赖：主机、应用、K8s、云资源、数据库、中间件。
|
||
4. 建立 AI 评测集：误报率、根因命中率、建议采纳率、平均处理时长。
|
||
|
||
验收标准：
|
||
|
||
- 预测风险能进入告警中心或风险看板。
|
||
- RCA 对高频故障有稳定命中率。
|
||
- 形成“告警 → 分析 → 处置 → 复盘 → 记忆”的闭环。
|
||
|
||
---
|
||
|
||
## 近期代码任务建议
|
||
|
||
| 顺序 | 任务 | 文件方向 |
|
||
|------|------|----------|
|
||
| 1 | 修复告警分析 prompt 和兜底脚本里未展开的 i18n 文本 | `frontend/src/components/aiops/AIAlertAnalyzer.tsx`、`analyzerHelpers.ts` |
|
||
| 2 | 新增后端 `ContextPack` DTO 和 builder | `backend/controller/aiops_context.go` 或 `backend/pkg/aiopscontext/` |
|
||
| 3 | 智能助手快捷操作改为调用 ContextPack | `AIOpsAssistant.tsx`、`frontend/src/api/aiops/` |
|
||
| 4 | Agent CLI 注册只读 AIOps 工具 | `backend/pkg/agentcli/tools/`、`backend/pkg/agentcli/agentcli.go` |
|
||
| 5 | 告警分析后端化，返回 RCA 结构化 JSON | `backend/controller/aiops_alert_analysis.go` |
|
||
| 6 | 告警 RCA 增加 trace_id/span_id 和上下文包落库 | `model.AIAnalysisTrace`、`backend/controller/aiops_alert_analysis.go` |
|
||
| 7 | Agent CLI 增加工具级 span | `model.AgentCLISession`、`model.AgentCLIMessage` 或新增 `agent_tool_traces` |
|
||
|
||
已完成：1、2、4、5、6，以及 3 的智能助手总览和告警分析接入。下一步优先做 Agent CLI 工具级 span 和预测分析后端化。
|
||
|
||
---
|
||
|
||
## 判断标准
|
||
|
||
好的 AIOps 智能分析必须满足四点：
|
||
|
||
1. **有对象**：知道分析的是哪台主机、哪个应用、哪个 Pod、哪个环境。
|
||
2. **有证据**：结论引用告警、指标、日志、事件、变更中的具体事实。
|
||
3. **有边界**：不确定时明确说明，不编造数据。
|
||
4. **可执行**：建议能转成只读检查、修复计划、审批动作或自动化任务。
|
||
|
||
只要沿着这条线做，智能助手、告警分析、预测分析就会从“AI 页面”变成 AIOps 平台真正的智能中枢。
|
||
|
||
---
|
||
|
||
## 挂点速查（2026-09-18）// Logan.Li
|
||
|
||
复杂多步「未跑完就挂」的对照表与修复优先级见：[08-代码审计与挂点索引](08-代码审计与挂点索引.md) 与权威契约 [13-运行结果状态与可续跑契约](13-运行结果状态与可续跑契约.md)。本文保留平台智能化长文；挂点索引为增量入口。
|