aiops/docs/agent/01-项目概述与设计哲学.md

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 协议兼容后端。

// 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	整体架构设计	五层结构、执行流程、依赖关系
03	Harness 工程化与反馈回路	Harness 理论、前馈/反馈、Steering Loop
04	插件架构设计	Tool 接口、Registry、扩展规范
05	Builtin 内置工具	ssh_execute 与 analyze_output 设计
06	Agent 核心引擎设计	ReAct 主循环、自适应检查点
07	Prompt 构建与记忆注入	五层 Prompt、动态记忆层
08	Evolver 自进化引擎	四层记忆、精简进化循环
09	安全系统与工具注册	风险评估、安全模式、Tool 接口
10	会话管理	GORM 持久化、按用户隔离

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

快速开始

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

代码侧调用示例（controller）：

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