# 02 - 整体架构设计

> 本文描述 AIOps 当前 Agent CLI 的真实工程分层、端到端链路和模块职责。// Logan.Li

---

## 架构定位

Agent CLI 是 AIOps 平台内置的智能运维执行器，整体由四层组成：

| 层级 | 代码位置 | 职责 |
|------|----------|------|
| 前端工作台 | `frontend/src/components/aiops/AgentCLI.tsx` | 目标选择、任务输入、事件流展示、确认弹框、历史侧栏 |
| WebSocket / REST Controller | `backend/controller/agent_cli*.go` | 鉴权、目标加载、会话入库、WS 控制协议、安全确认桥接 |
| Agent 引擎库 | `backend/pkg/agentcli/` | LLM、Prompt、ReAct、工具注册、安全控制、Evolver |
| 平台底座 | `model.Server`、`LLMConfig`、K8s Client、凭证、DB | 资产、凭据、集群、模型配置、会话存储 |

核心边界：`backend/pkg/agentcli/` 不依赖 `controller` 或 `model`，只接收配置和回调；平台业务全部在 controller 层完成。

---

## 端到端调用链路

```text
浏览器 AgentCLI 页面
  │
  ├─ host 模式: /ws/agent-cli?mode=host&id=<serverID>&token=<jwt>
  └─ kubernetes 模式: /ws/agent-cli?mode=kubernetes&cluster=<code>&namespace=<ns>&pod=<pod>&container=<container>&token=<jwt>
        │
        ▼
AgentCLIHandler.Run()
  ├─ JWTAuth 解析当前用户
  ├─ 加载 Server / KubernetesCluster
  ├─ 构造 SSHConfig 或 KubernetesTarget
  ├─ 读取启用的 LLMConfig
  ├─ 创建 / 续接 AgentCLISession
  └─ agentcli.NewEngine()
        │
        ▼
core.Agent.Run()
  ├─ BuildSystemPrompt()
  ├─ LLM function calling
  ├─ tools.Registry 查找工具
  ├─ safety.Controller 执行前检查
  ├─ EventCallback 推送事件并落库
  └─ Evolver 异步学习经验
```

---

## 前端层

前端页面负责把 Agent 的执行过程做成可操作的工作台：

| 模块 | 职责 |
|------|------|
| `AgentCLI.tsx` | 页面主体、模式切换、目标选择、WebSocket 生命周期 |
| `AgentCLIMessages.tsx` | 渲染思考、工具调用、工具结果、最终答案 |
| `AgentCLIHistory.tsx` | 会话列表、回放、删除、继续追问 |
| `frontend/src/api/aiops/agent-cli.ts` | REST 会话 API 和 WebSocket URL 构建 |

前端通过 WebSocket 发送控制消息：

| type | 含义 |
|------|------|
| `start` | 开始新任务 |
| `continue` | 基于当前会话继续追问 |
| `resume` | 加载历史会话上下文 |
| `confirm` | 批准高危工具调用 |
| `reject` | 拒绝高危工具调用 |

---

## Controller 层

Controller 是平台上下文和通用 Agent 引擎之间的适配层。

### 主机模式

`runHostWS()` 完成：

1. 从 `id` 查询 `model.Server`。
2. 通过资产和凭据构造 `remoteexec.SSHConfig`。
3. 读取启用的 `model.LLMConfig`。
4. 建立 WebSocket 连接。
5. 组装 `agentcli.EngineConfig{Mode: host, SSH: ...}`。

### Kubernetes 模式

`runKubernetesWS()` 完成：

1. 从 `cluster`、`namespace`、`pod`、`container` 解析目标。
2. 加载 Kubernetes 集群配置。
3. 构造轻量 K8s Client。
4. 组装 `agentcli.EngineConfig{Mode: kubernetes, Kubernetes: ...}`。

### 会话与事件

Controller 负责将事件写入数据库：

| 表 | 内容 |
|----|------|
| `agent_cli_sessions` | 一次 AI 任务的用户、目标、模型、状态、轮次、耗时、token |
| `agent_cli_messages` | 用户输入、思考、工具调用、工具输出、最终答案、错误 |

---

## 引擎层

`agentcli.NewEngine()` 组装以下组件：

| 组件 | 代码位置 | 说明 |
|------|----------|------|
| LLM Client | `pkg/agentcli/llm/` | 支持 OpenAI 兼容接口和 Anthropic Messages |
| Registry | `pkg/agentcli/tools/registry.go` | 线程安全工具注册中心 |
| Safety Controller | `pkg/agentcli/safety/safety.go` | 高危确认、危险命令硬拒 |
| Core Agent | `pkg/agentcli/core/agent.go` | 16 轮 ReAct 主循环 |
| Evolver | `pkg/agentcli/evolver/` | 经验、事实、流程记忆 |

引擎接收两个关键回调：

| 回调 | 说明 |
|------|------|
| `EventCallback` | 推送 `progress/thought/tool_call/tool_result/done/error` 并落库 |
| `ConfirmFn` | 高危工具调用时由 controller 推送确认事件，等待前端响应 |

---

## 工具集

工具按运行模式注册，避免模型看到不该用的工具。

| 模式 | 工具 |
|------|------|
| host | `ssh_execute`、`analyze_output` |
| kubernetes | `kubernetes_get`、`pod_logs`、`pod_execute`、`kubernetes_action`、`analyze_output` |

`ssh_execute` 和 `pod_execute` 支持动态风险评估，会根据实际命令计算风险等级。

---

## 数据流

```text
用户输入 query
  → 写入 agent_cli_messages(type=session, role=user)
  → BuildSystemPrompt(mode, targetInfo, toolDescs, evolveContext)
  → LLM Complete(function calling)
  → tool_call event
  → safety.Check()
  → tool.Execute()
  → tool_result event
  → LLM 观察工具输出继续推理
  → done / error event
  → 更新 agent_cli_sessions 状态
  → Evolver 后台学习
```

---

## 当前架构优点

1. **平台权限可控**：WebSocket 入口走 JWT，目标资产由后端加载。
2. **引擎可复用**：`pkg/agentcli` 是纯库，后续可接自动化任务或告警处置。
3. **过程可审计**：每一步工具调用和输出都有数据库记录。
4. **工具面收敛**：主机和 K8s 模式互斥注册工具，减少误调用。
5. **失败可降级**：Evolver 初始化失败不影响主流程。

---

## 待演进点

| 方向 | 建议 |
|------|------|
| 权限剪枝 | 按用户权限动态注册工具，例如无 K8s 变更权限则不注册 `kubernetes_action` |
| 审计统一 | 工具调用同步写入安全审计中心，关联审批、资产、用户 |
| 记忆 DB 化 | 将 `data/agentcli` 文件记忆迁移到数据库，支持查看和清理 |
| 输出脱敏 | 对密钥、Token、Cookie、连接串做落库前脱敏 |
| 审批接入 | 高危动作不只弹确认，支持企业审批流 |