# Agent CLI 设计文档（aiops）

> 本文由 opsxcli 同名设计文档集适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。

本系列文档是 **aiops Agent CLI**（Web 版 AI 运维 Agent）的设计文档集。Agent CLI 把 opsxcli 项目的 AI Agent 能力（ReAct 推理、工具调用、自进化、安全审批）移植到 aiops 的 Gin 后端，剥离 CLI/TUI 外壳，改造成一个由 WebSocket 驱动、与 React 前端对话的「类似 Claude Code / Codex」的运维 Agent 库。

一句话定位：**用户在 Agent CLI 页面选择目标主机，用自然语言描述任务，后端 ReAct 引擎自主通过 SSH 在远程服务器上排障、修复，并通过 WebSocket 把思考、命令、输出实时回传给前端。**

---

## 文档目录

| 编号 | 文档 | 一句话简介 |
|------|------|-----------|
| 01 | [项目概述与设计哲学](01-项目概述与设计哲学.md) | Agent CLI 的定位、四大设计哲学、与 opsxcli 的关系 |
| 02 | [整体架构设计](02-整体架构设计.md) | 引擎五层结构（controller / model / pkg / frontend / evolver）与执行流程 |
| 03 | [Harness 工程化与反馈回路](03-Harness工程化与反馈回路.md) | Harness Engineering 理论在 aiops Agent CLI 中的落地（前馈 + 反馈 + Steering） |
| 04 | [插件架构设计](04-插件架构设计.md) | Tool 接口 + Registry 工具注册中心，Web 版精简为 2 个工具 |
| 05 | [Builtin 内置工具](05-Builtin内置命令.md) | ssh_execute 与 analyze_output 两个内置工具的设计 |
| 06 | [Agent 核心引擎设计](06-Agent核心引擎设计.md) | ReAct 16 轮主循环、自适应检查点、循环检测、Evolver 集成 |
| 07 | [Prompt 构建与记忆注入](07-Prompt构建与记忆注入.md) | 五层 System Prompt 与动态记忆注入 |
| 08 | [Evolver 自进化引擎](08-Evolver自进化引擎.md) | 四层记忆 + 精简进化循环（OBSERVE→…→PREDICT） |
| 09 | [安全系统与工具注册](09-安全系统与工具注册.md) | 三级安全模式、五级风险、黑名单、WebSocket 确认 |
| 10 | [会话管理](10-会话管理.md) | GORM 数据库表持久化会话与消息（多用户隔离） |

---

## opsxcli → aiops 映射总览

| opsxcli 模块 | opsxcli 路径 | aiops 对应 | 处理方式 |
|--------------|-------------|-----------|----------|
| Agent ReAct 核心 | `internal/agent/core/` | `backend/pkg/agentcli/core/agent.go` | **适配**：剥离 TUI，改 EventCallback 推 WebSocket；保留 16 轮循环 / 检查点 / 循环检测 |
| 工具注册中心 | `internal/agent/tools/registry.go` | `backend/pkg/agentcli/tools/registry.go` | **原样移植**：Tool 接口（5 方法）+ DynamicRiskTool + Registry（线程安全） |
| 内置工具集 | `local_bash / ssh_execute / scp_transfer / file_read / file_search / analyze_output`（6 个） | `ssh_execute` + `analyze_output`（2 个） | **精简剥离**：去掉 local_bash（不在后端服务器本地执行）、scp、file_read、file_search |
| 安全系统 | `internal/agent/safety/` | `backend/pkg/agentcli/safety/safety.go` + `tools/risk.go` | **适配**：三级模式 / 五级风险 / 黑名单保留；确认机制由 CLI 终端交互改为 WebSocket confirm 事件 + 前端弹框 |
| Prompt 构建 | `internal/agent/prompt/` | `backend/pkg/agentcli/prompt/prompt.go` | **适配**：保留五层架构，角色改写为「aiops Agent CLI 智能运维 Agent」 |
| 自进化引擎 | `internal/agent/evolver/`（13 步 + 3300 行） | `backend/pkg/agentcli/evolver/engine.go` + `memory.go`（~400 行） | **精简适配**：保留四层记忆 + 进化循环思想；步骤从 13 步精简为核心 6 步（OBSERVE→CLASSIFY→LEARN→STORE→MEMORIZE→PREDICT） |
| LLM 客户端 | `internal/llm/`（多 Provider 配置向导 + claude.go/gemini.go 等 15 Provider） | `backend/pkg/agentcli/llm/openai.go` + `types.go` | **精简剥离**：剥离 wizard 配置向导和多 Provider，统一走 OpenAI 兼容接口；配置来自 DB 表 `ai_llm_configs`（model.LLMConfig） |
| 会话管理 | `internal/agent/session/`（JSONL 文件存储） | `backend/model/agent_cli.go` + `controller/agent_cli.go`（GORM DB） | **改造**：多用户 Web 场景下从本地文件改为数据库表 `agent_cli_sessions` / `agent_cli_messages`，按 user_id 隔离 |
| 记忆存储 | `~/.opsxcli/agent/*.jsonl` | `data/agentcli/*.jsonl`（工作目录） | **适配**：从用户主目录改为应用工作目录 |
| LLM 配置 | `~/.opsxcli/providers/*.json` | DB 表 `ai_llm_configs` + 「大模型设置」页面 | **改造**：从本地文件改为 DB 表 + Web 配置页 |
| CLI 命令层 | `cmd/`（Cobra） | `backend/controller/agent_cli.go`（Gin WebSocket handler） | **改造**：从 Cobra 命令改为 WebSocket 控制器 |
| TUI 终端界面 | `internal/agent/tui/`（Bubble Tea） | `frontend/src/components/aiops/AgentCLI.tsx`（React） | **改造**：从 Bubble Tea TUI 改为 React 对话流组件 |
| 远程执行 | `internal/agent/tools/` 内 SSH 实现 | `pkg/remoteexec/`（Go-native SSH，aiops 既有） | **复用**：直接复用 aiops 已有的远程执行包 |

---

## 移植决策

### 剥离了什么

1. **CLI 外壳**：去掉 Cobra 命令定义、参数解析、帮助文本 —— 由 WebSocket 控制器替代。
2. **TUI 终端界面**：去掉 Bubble Tea + 全套终端渲染 —— 由 React 对话流组件替代。
3. **LLM 多 Provider 配置向导**：去掉 `wizard.go` 交互式向导、`claude.go` / `gemini.go` 等专有 Provider —— 统一走 OpenAI 兼容 `/chat/completions`，覆盖 deepseek / qwen / moonshot / ollama / openai / custom。
4. **本地执行类工具**：去掉 `local_bash`（Web 后端不在服务器本地执行命令）、`scp_transfer`、`file_read`、`file_search` —— Web 版聚焦远程运维。
5. **Evolver 复杂分析**：去掉 opsxcli 13 步循环中的反射评分、经验整合去重、Skill 自动提炼等重型子流程 —— 精简为核心学习链路。

### 适配了什么

1. **会话持久化**：从本地 JSONL 文件改为 GORM 数据库表，支持多用户并发与按用户隔离。
2. **记忆路径**：从 `~/.opsxcli/agent/` 改为应用工作目录 `data/agentcli/`，便于容器化部署。
3. **LLM 配置来源**：从 `~/.opsxcli/providers/*.json` 改为 DB 表 `ai_llm_configs`，通过「大模型设置」页面配置。
4. **确认机制**：从 CLI 终端 `bufio.Reader` 改为 WebSocket `confirm` 事件 + 前端 `useConfirm()` 弹框。
5. **SSH 凭据**：从 `~/.ssh/config` 解析改为关联 `model.Server` 凭据（凭证系统 v2），由 controller 注入引擎。
6. **角色定位**：从「opsxcli 智能运维超级助手」改写为「aiops Agent CLI 智能运维 Agent（Web 版，类似 Claude Code）」。

### 精简了什么

1. **工具集**：6 个 → 2 个（`ssh_execute` + `analyze_output`）。
2. **Evolver 步骤**：13 步 → 6 步（保留学习与注入能力，剥离重型分析）。
3. **LLM 层**：15 个 Provider 文件 → 1 个 OpenAI 兼容客户端。
4. **记忆层级**：保留四层（经验 / 环境 / 事实 / 程序），但程序层仅保留接口位、未实现自动 Skill 提炼。

> 作者：Logan.Li