# AI Agent / Agent CLI 设计文档

> 更新：2026-09-03
> 范围：AIOps 平台内置的 AI 运维 Agent、Agent CLI WebSocket 执行页、主机 AI 任务、Kubernetes AI 排障。// Logan.Li

---

## 定位

AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选择目标主机或 Kubernetes 目标，用自然语言描述任务，后端 Agent 引擎通过 LLM 推理、工具调用、安全检查和会话持久化完成排障或操作建议。

一句话：**AIOps Agent CLI 是运行在 AIOps 后端的 Web 版智能运维 Agent，不是本地命令行工具，也不是客户端采集 Agent。**

| 名称 | 含义 |
|------|------|
| AI Agent / Agent CLI | AIOps 后端内置的 ReAct 智能执行引擎 |
| 客户端 Agent | 部署在被管主机上的指标采集 Agent，见 `docs/client-agent/` |
| AIOps Assistant | 普通对话式智能助手，偏分析和问答 |

---

## 文档目录

当前目录包含 9 篇正文，避免把同一条链路拆得过碎：

| 编号 | 文档 | 说明 |
|------|------|------|
| 01 | [项目概述与设计哲学](01-项目概述与设计哲学.md) | 产品定位、边界、成功标准 |
| 02 | [整体架构设计](02-整体架构设计.md) | 前端、WebSocket、Controller、Engine、DB 的分层 |
| 03 | [执行循环与 Harness](03-Harness工程化与反馈回路.md) | ReAct 主循环、Prompt、事件、上下文裁剪、反馈回路 |
| 04 | [工具与 ACI 设计](04-工具与ACI设计.md) | Tool 接口、工具清单、Agent-Computer Interface 设计原则 |
| 05 | [安全治理与审计](05-安全治理与审计.md) | 风险评估、确认、脱敏、策略中心、审计落点 |
| 06 | [会话记忆与 Evolver](06-会话记忆与Evolver.md) | 会话表、消息表、历史恢复、记忆注入、自进化 |
| 07 | [路线图与评测](07-路线图与评测.md) | 可用堡垒机、企业堡垒机、智能闭环、评测指标 |
| 08 | [代码审计与平台智能化优化](08-代码审计与平台智能化优化.md) | Agent CLI 代码差距、AIOps 上下文工具、告警分析和预测分析升级路线 |
| 09 | [三产品定位与执行边界](09-三产品定位与执行边界.md) | OpsXCLI、OpsXShell、AIOps 的独立目标、凭证、执行和审计边界 |

---

## 当前能力矩阵

| 能力 | 状态 | 代码落点 |
|------|------|----------|
| WebSocket 对话流 | 已完成 | `backend/controller/agent_cli.go`、`AgentCLI.tsx` |
| 主机模式 | 已完成 | `ssh_execute`、`analyze_output` |
| Kubernetes 模式 | 已完成 | `kubernetes_get`、`pod_logs`、`pod_execute`、`kubernetes_action` |
| ReAct 主循环 | 已完成 | `backend/pkg/agentcli/core/agent.go` |
| LLM 双协议 | 已完成 | OpenAI 兼容 + Anthropic Messages |
| Prompt 构建 | 已完成 | `backend/pkg/agentcli/prompt/prompt.go` |
| 安全确认 | 已完成 | `safety.Controller` + WebSocket `confirm` |
| 会话持久化 | 已完成 | `agent_cli_sessions` / `agent_cli_messages` |
| 历史回放 | 已完成 | `AgentCLIHistory.tsx`、`AgentCLIMessages.tsx` |
| Evolver 记忆 | 已完成 | `backend/pkg/agentcli/evolver/` |
| 工具审计统一 | 待增强 | 后续接入 `session_commands` 或专属审计表 |
| 策略中心接入 | 待增强 | 后续接入 `sys_audit_settings` 扩展策略 |

---

## 专业参考基线

这些文档不是孤立设计，主要对齐以下业界和论文里的共识：

| 参考 | AIOps 落点 |
|------|------------|
| [ReAct](https://arxiv.org/abs/2210.03629) | 推理和行动交替，工具输出反哺下一轮判断 |
| [Toolformer](https://arxiv.org/abs/2302.04761) | 工具调用要关注何时调用、传什么参数、如何吸收结果 |
| [Anthropic - Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) | Agent 适合有明确成功标准、反馈回路和人工监督的任务 |
| [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) | 自主管理 Prompt、上下文、工具、暂停/恢复和人工确认 |
| [SWE-agent ACI](https://arxiv.org/abs/2405.15793) | 面向模型设计专门的工具接口和反馈格式，而不是直接暴露人类 UI |
| [OpenAI Agents - Guardrails](https://openai.github.io/openai-agents-python/guardrails/) | 输入、输出、工具调用都需要 guardrail |
| [OpenAI Agents - Tracing](https://openai.github.io/openai-agents-python/tracing/) | Agent 运行要记录 LLM、工具、guardrail、自定义事件 |
| [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/) | Prompt Injection、敏感信息泄露、插件设计、过度自主权是核心风险 |
| [NIST AI RMF GenAI Profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence) | 企业级 AI 需要治理、测量、管理和生命周期风险控制 |

---

## 端到端链路

```text
frontend/src/components/aiops/AgentCLI.tsx
  ├── 选择模式：host / kubernetes
  ├── 选择目标：服务器 / 集群 / Namespace / Pod / Container
  ├── 选择安全模式：strict / balanced / permissive
  └── WebSocket /ws/agent-cli
        │
        ▼
backend/controller/agent_cli.go
  ├── JWT 用户身份
  ├── 加载目标资产 / K8s 上下文
  ├── 加载 LLM 配置
  ├── 创建会话和消息
  ├── 注入 confirmFn 和 event callback
  └── 调用 agentcli.Engine.Run()
        │
        ▼
backend/pkg/agentcli/
  ├── llm.Client
  ├── tools.Registry
  ├── safety.Controller
  ├── evolver.EvolverEngine
  └── core.Agent ReAct loop
```

---

## 设计原则

1. **平台内置**：Agent CLI 是 AIOps 后端能力，不要求用户安装本地 AI 工具。
2. **目标受控**：只对用户有权限的资产、集群、Pod 执行工具。
3. **工具最小化**：工具暴露越少，模型误调用和越权风险越低。
4. **安全前置**：危险命令硬拒，高危操作必须确认，后续接审批。
5. **过程可见**：思考、工具调用、工具输出、确认和最终结果均走 WebSocket 事件流。
6. **审计独立**：会话和消息可按用户需求删除，但远程执行跨度和命令审计不得随聊天历史删除。
7. **历史可追溯**：会话和消息入库，支持回放、删除、继续追问。
8. **记忆可控**：Evolver 记忆按用户隔离，后续增加审核、发布、撤销和保留期治理。
9. **产品不越界**：AIOps 只执行平台授权资产，不复用 OpsXCLI 本机执行器或 OpsXShell 当前连接执行器。

---

## 相关文档

| 文档 | 说明 |
|------|------|
| [客户端 Agent](../client-agent/README.md) | 主机指标采集 Agent |
| [安全审计与堡垒机](../security-bastion/README.md) | 会话、审计、审批统一设计 |
| [终端体系](../terminal/README.md) | WebSSH、Pod exec、kubectl 终端 |
| [Kubernetes 管理](../kubernetes/README.md) | K8s 资源、Pod、YAML、AI 排障 |