attackerandClaude
92a2247390
后端引擎 backend/pkg/agentcli/（纯引擎库，零业务依赖，剥离 CLI/TUI 外壳）： - llm: OpenAI 兼容客户端，复用 model.LLMConfig - tools: ssh_execute（复用 pkg/remoteexec）+ analyze_output + 风险评估黑名单 - safety: 三级安全模式 + 五级风险 + WebSocket 异步确认 - prompt: 五层 System Prompt - core: ReAct 16 轮循环 + 自适应检查点 + 循环检测 - evolver: 四层记忆 + 进化循环，data/agentcli/ 文件存储 集成层： - controller/agent_cli.go: WebSocket 控制器（事件流推流 + 高危确认 + 会话持久化） - model/agent_cli.go: agent_cli_sessions/messages 表 + AutoMigrate - 路由 /ws/agent-cli + /api/v1/aiops/agent-cli/sessions - seed 权限 aiops:agent-cli / aiops:llm-config 前端： - AgentCLI.tsx: 对话流 + 工具块 + 高危确认 + 四模块 tips 面板 - LLMConfig.tsx: 大模型设置独立页 - api/agentCli.ts + Sidebar/App 菜单路由 文档： - docs/agent/ 11 篇（opsxcli 同名文档适配改写 + 00-README 映射总览） 其他： - CLAUDE.md 补充 agent-cli 模块说明 - 修正 .gitignore 根级二进制规则（前导 /，避免误伤 frontend/src/components/aiops/） Co-Authored-By: Claude <noreply@anthropic.com>
231 lines
13 KiB
Markdown
231 lines
13 KiB
Markdown
# 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
|