aiops/docs/ai-agent/02-整体架构设计.md

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 层完成。

---

端到端调用链路

浏览器 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 支持动态风险评估，会根据实际命令计算风险等级。

---

数据流

用户输入 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、连接串做落库前脱敏
审批接入	高危动作不只弹确认，支持企业审批流