# 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)。本文保留平台智能化长文；挂点索引为增量入口。