aiops/docs/agent/00-README.md

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	项目概述与设计哲学	Agent CLI 的定位、四大设计哲学、与 opsxcli 的关系
02	整体架构设计	引擎五层结构（controller / model / pkg / frontend / evolver）与执行流程
03	Harness 工程化与反馈回路	Harness Engineering 理论在 aiops Agent CLI 中的落地（前馈 + 反馈 + Steering）
04	插件架构设计	Tool 接口 + Registry 工具注册中心，Web 版精简为 2 个工具
05	Builtin 内置工具	ssh_execute 与 analyze_output 两个内置工具的设计
06	Agent 核心引擎设计	ReAct 16 轮主循环、自适应检查点、循环检测、Evolver 集成
07	Prompt 构建与记忆注入	五层 System Prompt 与动态记忆注入
08	Evolver 自进化引擎	四层记忆 + 精简进化循环（OBSERVE→…→PREDICT）
09	安全系统与工具注册	三级安全模式、五级风险、黑名单、WebSocket 确认
10	会话管理	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