# 01 - 项目概述与设计哲学

> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。
> opsxcli 原文档把 Agent 描述为 CLI 工具（`opsxcli agent -q "..."`），aiops 改为 Web 页面 + WebSocket 事件流。涉及 CLI 特性的地方已注明 aiops 的对应实现。

> 建议阅读顺序：01 → 02 → 03 → ... → 10

## 项目定位

**aiops Agent CLI** —— aiops 平台内置的 Web 版智能运维 Agent。

类似 Claude Code / Codex，但运行在浏览器里：用户在「Agent CLI」页面选择一台目标主机，用自然语言描述运维任务（如「检查磁盘空间」「nginx 启动失败的原因」），后端 ReAct 引擎自主通过 SSH 在远程服务器上排查、修复，并通过 WebSocket 把每一步思考、执行的命令、输出与最终结果实时回传给前端。

这是把 opsxcli（基于 Cobra 的 CLI 运维 Agent）的 AI 能力，剥离 CLI/TUI 外壳、适配为 aiops 的 Gin 后端库后的产物。

## 设计目标

| 维度 | 目标 |
|------|------|
| 形态 | Web 对话流（WebSocket 双向通信），不是命令行 |
| 部署 | 嵌入 aiops 后端二进制（go:embed），无需独立服务 |
| 安全 | 默认 balanced；高危命令前端确认；危险命令硬拒 |
| 智能 | 16 轮 ReAct 主循环 + 自进化记忆注入 |
| 隔离 | 多用户并发，会话/消息按 user_id 隔离，持久化到 DB |

## 五层引擎结构

aiops Agent CLI 不是单一包，而是分散在 aiops 的标准 Gin 分层中：

```
┌─────────────────────────────────────────────────────┐
│   frontend/ (React 对话流 UI)                         │
│   components/aiops/AgentCLI.tsx                       │
│   - WebSocket 客户端，渲染 thought/tool_call/         │
│     tool_result/done/error 事件流                     │
│   - 高危命令 useConfirm() 弹框确认                     │
├─────────────────────────────────────────────────────┤
│   controller/ (HTTP/WS handler)                      │
│   controller/agent_cli.go                             │
│   - WebSocket 入口 /ws/agent-cli?id=<serverID>        │
│   - 构建 Engine、注入 EventCallback + ConfirmFn        │
│   - 事件落库 + 推 WS                                  │
├─────────────────────────────────────────────────────┤
│   model/ (GORM 模型)                                  │
│   model/agent_cli.go                                  │
│   - AgentCLISession / AgentCLIMessage                 │
│   - LLMConfig (ai_llm_configs)                       │
├─────────────────────────────────────────────────────┤
│   pkg/agentcli/ (引擎库，零业务依赖)                   │
│   ├── agentcli.go    Engine 顶层入口                  │
│   ├── core/          ReAct 主循环                     │
│   ├── tools/         工具注册 + ssh_execute 等        │
│   ├── safety/        安全控制器                       │
│   ├── prompt/        五层 System Prompt               │
│   ├── evolver/       自进化引擎（四层记忆）            │
│   └── llm/           OpenAI 兼容客户端               │
├─────────────────────────────────────────────────────┤
│   pkg/remoteexec/ (复用 aiops 既有 Go-native SSH)     │
└─────────────────────────────────────────────────────┘
```

**关键设计原则**：`pkg/agentcli/` 零业务依赖 —— 不 import `model` / `controller`，所有持久化与 WebSocket 由 controller 层负责。引擎只关心「思考-行动-观察」循环本身。

## Agent 引擎子模块全景

`backend/pkg/agentcli/` 包含 7 个子包：

```
backend/pkg/agentcli/
├── agentcli.go   ── Engine 顶层入口：组装 LLM + 工具 + 安全 + Evolver + ReAct 核心
├── core/         ── ReAct 核心引擎：16 轮主循环 + 自适应检查点 + 循环检测
├── prompt/       ── Prompt 构建：五层 System Prompt + 动态记忆注入
├── evolver/      ── 自进化引擎：四层记忆 + 精简进化循环
├── safety/       ── 安全系统：三级模式 + 阈值确认（ConfirmFn 回调）
├── tools/        ── 工具注册中心 + 2 个内置工具 + 风险评估
└── llm/          ── LLM 抽象层（OpenAI 兼容，剥离多 Provider）
```

> 与 opsxcli 的差异：opsxcli 有 `tui/` 子包（Bubble Tea 终端界面），aiops 把它替换为前端 React 组件 `AgentCLI.tsx`，由 controller 序列化事件推 WS。

## 四大设计哲学

### 1. 安全第一 (Safety First)

> 运维工具的底线是「不搞砸」。

- 所有工具执行前必须通过安全评估（`safety.Controller.Check`）
- 三级安全模式：`strict` / `balanced`（默认）/ `permissive`
- 5 级风险等级：Safe → Low → Medium → High → Critical
- 危险命令黑名单硬拒（不可确认放行）：`rm -rf /`、`mkfs`、`dd if=/dev/zero`、fork bomb 等
- 高危命令经 WebSocket `confirm` 事件 + 前端 `useConfirm()` 弹框由用户确认
- 会话与每条消息落库，事后可审计（`agent_cli_messages` 表）

### 2. 渐进式复杂度 (Progressive Complexity)

> 简单任务零配置，复杂任务有能力。

- 默认配置即可运行（`core.DefaultConfig()`）
- LLM 配置通过「大模型设置」页面填一次即生效（DB 表 `ai_llm_configs`）
- 引擎初始化时优雅降级：Evolver 失败设为 `nil`，不影响主 ReAct 循环
- 安全模式按需升级（balanced 默认 → strict 高敏生产环境）

### 3. 工具化思维 (Tool-Oriented)

> 万物皆 Tool，一切可注册。

- 统一的 `Tool` 接口（5 方法）：`Name` / `Description` / `Parameters` / `RiskLevel` / `Execute`
- `DynamicRiskTool` 扩展接口：依据运行时参数动态评估风险（如 `ssh_execute` 看具体命令）
- `Registry` 线程安全注册中心
- 实现接口即可扩展，无需修改核心代码
- **Web 版内置工具精简为 2 个**（剥离 opsxcli 的 local_bash / scp / file_read / file_search）：
  - `ssh_execute` —— 在目标主机远程执行命令（复用 `pkg/remoteexec`）
  - `analyze_output` —— 对冗长输出做摘要/错误提取，避免 token 爆炸

### 4. 自我进化 (Self-Evolution)

> 用得越多，越懂你。

- Evolver 引擎在任务完成后异步学习（30s 超时 + panic 恢复，绝不阻塞主循环）
- 四层记忆（`data/agentcli/`）：
  - **经验记忆**（`experience.jsonl`）—— 任务类型 → 工具序列 + 提示，按成功率优先注入
  - **环境记忆**（`environment.json`）—— 已知主机列表
  - **事实记忆**（`factual.jsonl`）—— LLM 提炼的持久事实
  - **程序记忆**（`procedural.jsonl`）—— 程序性知识（接口位，未实现自动 Skill 提炼）
- 经验按任务类型分类（磁盘空间 / 网络 / 服务管理 / 软件安装 等 11 类）
- 下次任务开始时，Evolver 通过 `GetContextForPrompt()` 把相关历史经验注入 System Prompt

## Agent 核心工作流

```
用户在 Agent CLI 页面选择主机，输入 "内存使用率"
        │
        ▼
┌──────────────────────┐
│  WebSocket 入口       │ ← controller/agent_cli.go: Run()
│  /ws/agent-cli?id=…  │   校验 JWT、加载 model.Server、解析 SSH 凭据
└────────┬─────────────┘
         │
         ▼
┌──────────────────────┐
│  Engine 组装          │ ← pkg/agentcli/agentcli.go: NewEngine()
│  LLM(OpenAI兼容)     │   注入 EventCallback + ConfirmFn
│  + tools(ssh/analyze)│
│  + safety + Evolver  │
└────────┬─────────────┘
         │
         ▼
┌──────────────────────┐
│  Prompt Builder      │ ← prompt/prompt.go: BuildSystemPrompt()
│  五层 System Prompt   │   Layer 1 角色 / 2 安全 / 3 工具 / 4 工作方式 / 5 记忆
│  + Evolver 记忆注入   │
└────────┬─────────────┘
         │
         ▼
┌──────────────────────┐     ┌──────────────┐
│  LLM 推理             │────▶│  工具调用     │
│  (ReAct 16 轮循环)    │◀────│  ssh_execute │
└────────┬─────────────┘     └──────┬───────┘
         │                          │
         │   ┌──────────────────────┘
         │   │ 每步都 emit Event
         │   ▼
│  自适应检查点         │     ┌──────────────┐
│  (Round 4/8/12)      │     │  安全检查     │
│  循环检测(>3次拒绝)   │     │  (RiskLevel) │
│  连续失败追踪         │     │  高危→confirm│
└────────┬─────────────┘     └──────────────┘
         │ EventCallback → controller
         │   ├─ 推 WS: thought/tool_call/tool_result/done
         │   └─ 落库: agent_cli_messages
         ▼ (16 轮迭代或 LLM 不再返回 tool_calls)
┌──────────────────────┐
│  Evolver 学习         │ ← 后台 goroutine，不影响响应速度
│  (经验 + 主机 + 事实) │
└──────────────────────┘
```

## LLM 客户端策略

> opsxcli 有 15 个 Provider（注册制工厂 + `claude.go` / `gemini.go` 等专有实现 + 配置向导 `wizard.go`）。
> aiops 精简为单一 OpenAI 兼容客户端，覆盖所有 OpenAI 协议兼容后端。

```go
// backend/pkg/agentcli/llm/openai.go
// 唯一客户端实现：走标准 /chat/completions + Bearer 鉴权
// 支持后端：openai / deepseek / qwen / moonshot / ollama / custom
func NewClient(cfg Config) Client
```

配置不再来自 `~/.opsxcli/providers/*.json`，而是 DB 表 `ai_llm_configs`（`model.LLMConfig`），由 controller 在握手阶段加载并注入 Engine。

## 文档阅读指南

| 编号 | 文档 | 核心内容 |
|------|------|----------|
| 01 | 本文档 | 项目概述、设计哲学、引擎全景 |
| 02 | [整体架构设计](02-整体架构设计.md) | 五层结构、执行流程、依赖关系 |
| 03 | [Harness 工程化与反馈回路](03-Harness工程化与反馈回路.md) | Harness 理论、前馈/反馈、Steering Loop |
| 04 | [插件架构设计](04-插件架构设计.md) | Tool 接口、Registry、扩展规范 |
| 05 | [Builtin 内置工具](05-Builtin内置命令.md) | ssh_execute 与 analyze_output 设计 |
| 06 | [Agent 核心引擎设计](06-Agent核心引擎设计.md) | ReAct 主循环、自适应检查点 |
| 07 | [Prompt 构建与记忆注入](07-Prompt构建与记忆注入.md) | 五层 Prompt、动态记忆层 |
| 08 | [Evolver 自进化引擎](08-Evolver自进化引擎.md) | 四层记忆、精简进化循环 |
| 09 | [安全系统与工具注册](09-安全系统与工具注册.md) | 风险评估、安全模式、Tool 接口 |
| 10 | [会话管理](10-会话管理.md) | GORM 持久化、按用户隔离 |

> 注：opsxcli 还有第 11 篇「TUI 终端界面设计」，aiops 已剥离 Bubble Tea TUI，由 React 组件 `AgentCLI.tsx` 替代，故本系列不含该篇。

## 快速开始

```bash
# 1. 在「大模型设置」页面配置 LLM（DB 表 ai_llm_configs，Enabled=true）
# 2. 在「服务器管理」确保目标主机凭据（凭证系统 v2）已配置
# 3. 进入「Agent CLI」页面，选择主机 → 输入任务 → 观察 WebSocket 推送的事件流
```

代码侧调用示例（controller）：

```go
engine, _ := agentcli.NewEngine(agentcli.EngineConfig{
    LLM:        llm.Config{Endpoint: ..., APIKey: ..., Model: ...},
    SSH:        sshCfg,                       // 来自 model.Server 凭据
    SafetyMode: safety.ModeBalanced,
})
engine.SetCallback(onEvent)                   // 推 WS + 落库
engine.SetConfirmFn(confirmFn)                // 高危确认
output, _ := engine.Run(ctx, query, serverInfo)
```

> 作者：Logan.Li