feat: 新增 Agent CLI — Web 版 AI 运维 Agent（参考 opsxcli 移植）
后端引擎 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>
This commit is contained in:
attackerandClaude committed
1 parent
f2069fe3f0
commit
92a2247390
37 files changed
+6449
-6
No files matched your search
+4
-4
@@ -22,10 +22,10 @@ backend/vendor/
|
||||
*.test
|
||||
*.out
|
||||
|
||||
# Compiled binary
|
||||
aiops
|
||||
aiops-*
|
||||
aiops.bak.*
|
||||
# Compiled binary（前导 / 只匹配仓库根目录的二进制产物，避免误伤子目录同名文件夹如 frontend/src/components/aiops/） // Logan.Li
|
||||
/aiops
|
||||
/aiops-*
|
||||
/aiops.bak.*
|
||||
|
||||
# 前端构建产物（由 run.sh build 自动生成，非源码）
|
||||
backend/static/assets/
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
1. **资产管理** — 服务器管理、云资源（云账号/域名/账单）、K8s 集群
|
||||
2. **监控告警** — Agent 采集指标、告警引擎（资源阈值/离线检测）、告警中心、链路追踪、监控大屏
|
||||
3. **自动化运维 / AIOps** — 流水线 CI/CD、定时任务/脚本库、远程执行（Go-native SSH）、资源申请审批、AI 智能运维（智能助手/告警分析/容量预测）
|
||||
3. **自动化运维 / AIOps** — 流水线 CI/CD、定时任务/脚本库、远程执行（Go-native SSH）、资源申请审批、AI 智能运维（智能助手/告警分析/容量预测/Agent CLI）
|
||||
|
||||
### 核心特性
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
- **凭证系统 v2** — 7 种统一凭证类型（SSH/Docker/TLS/AKSK/DB/API/Generic），加密存储
|
||||
- **CI/CD 流水线** — GitLab CI 风格可视化，阶段色块进度条，实时日志，文件浏览器
|
||||
- **Kubectl 终端** — WebSocket + PTY 交互式 K8s 终端，懒加载 kubectl 二进制
|
||||
- **Agent CLI** — Web 版 AI 运维 Agent（参考 opsxcli 移植），关联主机后自然语言驱动 SSH 排障/部署，ReAct 循环解决错误，WebSocket 实时回传，Evolver 自进化学习
|
||||
|
||||
## 技术栈
|
||||
|
||||
@@ -174,6 +175,7 @@ aiops/
|
||||
│ │ ├── database/ # DB 连接 + AutoMigrate
|
||||
│ │ ├── kubernetesclient/ # 轻量 K8s API 客户端
|
||||
│ │ ├── remoteexec/ # Go-native SSH 远程执行
|
||||
│ │ ├── agentcli/ # AI 运维 Agent 引擎（ReAct + 工具 + 安全 + Evolver，见 docs/agent/）
|
||||
│ │ └── toolinstaller/ # 工具懒加载 + 镜像回退
|
||||
│ └── Dockerfile # 3 阶段构建 (Backend+Agent→Alpine Runtime)
|
||||
│
|
||||
@@ -187,7 +189,7 @@ aiops/
|
||||
│ │ ├── monitor/ # 监控告警
|
||||
│ │ ├── automation/ # 定时任务/脚本库/远程执行
|
||||
│ │ ├── approval/ # 资源申请审批
|
||||
│ │ ├── aiops/ # AI 智能运维（助手/告警分析/容量预测）
|
||||
│ │ ├── aiops/ # AI 智能运维（助手/告警分析/容量预测/Agent CLI/大模型设置）
|
||||
│ │ ├── system/ # 系统管理
|
||||
│ │ └── layout/ # Sidebar/Header
|
||||
│ ├── src/services/
|
||||
@@ -339,3 +341,4 @@ Git 用户: attacker / attacker@gitee.com
|
||||
- **K8s 客户端** — 轻量自研（net/http + crypto/tls），不引入 50MB+ 的 client-go
|
||||
- **BuildKit cache mount** — Docker 构建从 13min 降至 3sec（二次构建）
|
||||
- **健康检查用 `/version`** — K8s 中 `/health` 可能依赖 DB，`/version` 始终 200
|
||||
- **Agent CLI 引擎** — 移植自 opsxcli 的 AI Agent 能力到 `pkg/agentcli/`（纯引擎库，零业务依赖，剥离 CLI/TUI 外壳）：ReAct 16 轮循环 + 自适应检查点 + 循环检测；工具精简为 `ssh_execute`（复用 `pkg/remoteexec`）+ `analyze_output`；Evolver 四层记忆异步学习并注入下次 Prompt；会话用 GORM 表（`agent_cli_sessions/messages`）多用户隔离；高危命令经 WebSocket `confirm` 事件 + 前端 `useConfirm()` 确认；设计文档见 `docs/agent/`
|
||||
@@ -0,0 +1,328 @@
|
||||
// agent_cli.go - Agent CLI WebSocket 控制器 // Logan.Li
|
||||
// 驱动 pkg/agentcli 引擎：关联主机（model.Server 凭据）→ 构建引擎 → ReAct 循环，
|
||||
// 通过 WebSocket 实时推送思考/工具调用/输出/结果，高危命令经前端确认，过程持久化到 DB。
|
||||
package controller
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/gorilla/websocket"
|
||||
"gorm.io/gorm"
|
||||
|
||||
"ezops/middleware"
|
||||
"ezops/model"
|
||||
"ezops/pkg/agentcli"
|
||||
"ezops/pkg/agentcli/core"
|
||||
"ezops/pkg/agentcli/llm"
|
||||
"ezops/pkg/agentcli/safety"
|
||||
"ezops/pkg/agentcli/tools"
|
||||
"ezops/pkg/remoteexec"
|
||||
)
|
||||
|
||||
// AgentCLIHandler Agent CLI 控制器 // Logan.Li
|
||||
type AgentCLIHandler struct {
|
||||
db *gorm.DB
|
||||
}
|
||||
|
||||
// NewAgentCLIHandler 创建控制器 // Logan.Li
|
||||
func NewAgentCLIHandler(db *gorm.DB) *AgentCLIHandler { return &AgentCLIHandler{db: db} }
|
||||
|
||||
// wsEvent WebSocket 事件信封（后端→前端） // Logan.Li
|
||||
type wsEvent struct {
|
||||
Type string `json:"type"`
|
||||
Round int `json:"round,omitempty"`
|
||||
SessionID uint `json:"session_id,omitempty"`
|
||||
Thought string `json:"thought,omitempty"`
|
||||
ToolName string `json:"tool_name,omitempty"`
|
||||
ToolArgs map[string]interface{} `json:"tool_args,omitempty"`
|
||||
Risk string `json:"risk,omitempty"`
|
||||
Output string `json:"output,omitempty"`
|
||||
Success bool `json:"success,omitempty"`
|
||||
Duration string `json:"duration,omitempty"`
|
||||
Tokens int `json:"tokens,omitempty"`
|
||||
Answer string `json:"answer,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
ConfirmID string `json:"confirm_id,omitempty"`
|
||||
Command string `json:"command,omitempty"`
|
||||
}
|
||||
|
||||
// wsControl 前端→后端控制消息 // Logan.Li
|
||||
type wsControl struct {
|
||||
Type string `json:"type"` // start/confirm/deny/abort
|
||||
Query string `json:"query,omitempty"` // start 时任务描述
|
||||
ConfirmID string `json:"confirm_id,omitempty"` // confirm/deny 时
|
||||
}
|
||||
|
||||
// agentConn 单个 WS 连接的运行态 // Logan.Li
|
||||
type agentConn struct {
|
||||
conn *websocket.Conn
|
||||
db *gorm.DB
|
||||
userID uint
|
||||
server model.Server
|
||||
session *model.AgentCLISession
|
||||
cancel context.CancelFunc
|
||||
writeMu sync.Mutex
|
||||
confirms map[string]chan bool
|
||||
cfMu sync.Mutex
|
||||
}
|
||||
|
||||
// Run WebSocket 入口：GET /ws/agent-cli?id=<serverID>&token=<jwt> // Logan.Li
|
||||
func (h *AgentCLIHandler) Run(c *gin.Context) {
|
||||
serverID := c.Query("id")
|
||||
if serverID == "" {
|
||||
c.JSON(http.StatusBadRequest, model.Response{Code: 400, Message: "缺少主机 id"})
|
||||
return
|
||||
}
|
||||
var server model.Server
|
||||
if err := h.db.First(&server, serverID).Error; err != nil {
|
||||
c.JSON(http.StatusNotFound, model.Response{Code: 404, Message: "主机不存在"})
|
||||
return
|
||||
}
|
||||
sshCfg, err := buildSSHConfig(h.db, server)
|
||||
if err != nil {
|
||||
c.JSON(http.StatusBadRequest, model.Response{Code: 400, Message: err.Error()})
|
||||
return
|
||||
}
|
||||
// LLM 配置
|
||||
var llmCfg model.LLMConfig
|
||||
if err := h.db.First(&llmCfg).Error; err != nil || !llmCfg.Enabled {
|
||||
c.JSON(http.StatusBadRequest, model.Response{Code: 400, Message: "LLM 服务未配置或未启用，请先在「大模型设置」中配置"})
|
||||
return
|
||||
}
|
||||
|
||||
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
defer conn.Close()
|
||||
|
||||
ac := &agentConn{
|
||||
conn: conn, db: h.db,
|
||||
userID: middleware.GetUserID(c), server: server,
|
||||
confirms: make(map[string]chan bool),
|
||||
}
|
||||
// 推送主机上下文
|
||||
ac.write(wsEvent{Type: "session", SessionID: 0,
|
||||
Message: fmt.Sprintf("已连接主机 %s（%s），LLM: %s。请描述要执行的任务。", server.Hostname, server.IP, llmCfg.Model)})
|
||||
|
||||
// 读循环：处理前端控制消息
|
||||
for {
|
||||
_, data, err := conn.ReadMessage()
|
||||
if err != nil {
|
||||
ac.abort()
|
||||
return
|
||||
}
|
||||
var ctrl wsControl
|
||||
if json.Unmarshal(data, &ctrl) != nil {
|
||||
continue
|
||||
}
|
||||
switch ctrl.Type {
|
||||
case "start":
|
||||
if ctrl.Query == "" {
|
||||
ac.write(wsEvent{Type: "error", Message: "任务描述不能为空"})
|
||||
continue
|
||||
}
|
||||
ac.startTask(sshCfg, llmCfg, ctrl.Query)
|
||||
case "confirm":
|
||||
ac.resolveConfirm(ctrl.ConfirmID, true)
|
||||
case "deny":
|
||||
ac.resolveConfirm(ctrl.ConfirmID, false)
|
||||
case "abort":
|
||||
ac.abort()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// startTask 启动一次任务（新会话 + 新引擎） // Logan.Li
|
||||
func (ac *agentConn) startTask(sshCfg remoteexec.SSHConfig, llmCfg model.LLMConfig, query string) {
|
||||
ac.abort() // 取消上一次任务
|
||||
|
||||
// 创建 DB 会话
|
||||
title := query
|
||||
if r := []rune(title); len(r) > 60 {
|
||||
title = string(r[:60]) + "..."
|
||||
}
|
||||
sess := &model.AgentCLISession{
|
||||
UserID: ac.userID, ServerID: ac.server.ID,
|
||||
ServerName: ac.server.Hostname, ServerHost: ac.server.IP,
|
||||
Title: title, Status: "running",
|
||||
Provider: llmCfg.Provider, Model: llmCfg.Model,
|
||||
}
|
||||
if err := ac.db.Create(sess).Error; err != nil {
|
||||
ac.write(wsEvent{Type: "error", Message: "创建会话失败: " + err.Error()})
|
||||
return
|
||||
}
|
||||
ac.session = sess
|
||||
|
||||
// 存用户消息
|
||||
ac.persistMsg(sess.ID, 0, "user", "user", query, "", "", "", "", false, "", 0)
|
||||
|
||||
// 构建引擎
|
||||
engine, err := agentcli.NewEngine(agentcli.EngineConfig{
|
||||
LLM: llm.Config{
|
||||
Endpoint: resolveEndpoint(llmCfg.Provider, llmCfg.Endpoint),
|
||||
APIKey: llmCfg.APIKey, Model: llmCfg.Model,
|
||||
Temperature: llmCfg.Temperature, MaxTokens: llmCfg.MaxTokens,
|
||||
},
|
||||
SSH: sshCfg,
|
||||
SafetyMode: safety.ModeBalanced,
|
||||
})
|
||||
if err != nil {
|
||||
ac.finish(sess, "error", "引擎初始化失败: "+err.Error(), 0, time.Duration(0))
|
||||
return
|
||||
}
|
||||
engine.SetCallback(ac.onEvent)
|
||||
engine.SetConfirmFn(ac.confirmFn)
|
||||
|
||||
ctx, cancel := context.WithCancel(context.Background())
|
||||
ac.cancel = cancel
|
||||
serverInfo := fmt.Sprintf("主机名: %s | IP: %s:%d | 用户: %s | OS: %s", ac.server.Hostname, ac.server.IP, ac.server.Port, ac.server.Username, ac.server.OS)
|
||||
|
||||
ac.write(wsEvent{Type: "session", SessionID: sess.ID, Message: "任务已开始"})
|
||||
|
||||
go func() {
|
||||
defer engine.Close()
|
||||
start := time.Now()
|
||||
_, err := engine.Run(ctx, query, serverInfo)
|
||||
dur := time.Since(start)
|
||||
if ctx.Err() != nil {
|
||||
ac.finish(sess, "aborted", "任务已中断", ac.lastRound(), dur)
|
||||
} else if err != nil {
|
||||
ac.finish(sess, "error", err.Error(), ac.lastRound(), dur)
|
||||
} else {
|
||||
ac.finish(sess, "done", "", ac.lastRound(), dur)
|
||||
}
|
||||
}()
|
||||
}
|
||||
|
||||
// onEvent 引擎事件回调：推 WS + 持久化 // Logan.Li
|
||||
func (ac *agentConn) onEvent(e core.Event) {
|
||||
ev := wsEvent{
|
||||
Type: string(e.Type), Round: e.Round, Thought: e.Thought,
|
||||
ToolName: e.ToolName, ToolArgs: e.ToolArgs, Risk: e.Risk,
|
||||
Output: e.Output, Success: e.Success, Duration: e.Duration,
|
||||
Tokens: e.Tokens, Answer: e.Answer, Message: e.Message,
|
||||
}
|
||||
if ac.session != nil {
|
||||
ev.SessionID = ac.session.ID
|
||||
}
|
||||
ac.write(ev)
|
||||
|
||||
// 持久化（progress 太频繁不入库）
|
||||
if ac.session == nil {
|
||||
return
|
||||
}
|
||||
sid := ac.session.ID
|
||||
switch e.Type {
|
||||
case core.EventThought:
|
||||
ac.persistMsg(sid, e.Round, "thought", "assistant", e.Thought, "", "", "", "", false, "", 0)
|
||||
case core.EventToolCall:
|
||||
argsJSON, _ := json.Marshal(e.ToolArgs)
|
||||
ac.persistMsg(sid, e.Round, "tool_call", "tool", "", e.ToolName, string(argsJSON), "", e.Risk, false, "", 0)
|
||||
case core.EventToolResult:
|
||||
ac.persistMsg(sid, e.Round, "tool_result", "tool", e.Output, e.ToolName, "", "", "", e.Success, e.Duration, 0)
|
||||
case core.EventDone:
|
||||
ac.persistMsg(sid, e.Round, "done", "assistant", e.Answer, "", "", "", "", true, "", e.Tokens)
|
||||
case core.EventError:
|
||||
ac.persistMsg(sid, e.Round, "error", "assistant", e.Message, "", "", "", "", false, "", 0)
|
||||
}
|
||||
}
|
||||
|
||||
// confirmFn 高危命令确认回调：推 confirm 事件并阻塞等前端回传 // Logan.Li
|
||||
func (ac *agentConn) confirmFn(toolName string, args map[string]interface{}, risk tools.RiskLevel) (bool, error) {
|
||||
confirmID := fmt.Sprintf("cf-%d", time.Now().UnixNano())
|
||||
cmd, _ := args["command"].(string)
|
||||
ac.write(wsEvent{Type: "confirm", ConfirmID: confirmID, ToolName: toolName, Command: cmd, Risk: risk.Display(), ToolArgs: args})
|
||||
|
||||
ch := make(chan bool, 1)
|
||||
ac.cfMu.Lock()
|
||||
ac.confirms[confirmID] = ch
|
||||
ac.cfMu.Unlock()
|
||||
|
||||
select {
|
||||
case approved := <-ch:
|
||||
return approved, nil
|
||||
case <-time.After(5 * time.Minute):
|
||||
ac.delConfirm(confirmID)
|
||||
return false, fmt.Errorf("确认超时")
|
||||
}
|
||||
}
|
||||
|
||||
// resolveConfirm 前端回传确认结果 // Logan.Li
|
||||
func (ac *agentConn) resolveConfirm(confirmID string, approved bool) {
|
||||
ac.cfMu.Lock()
|
||||
ch, ok := ac.confirms[confirmID]
|
||||
if ok {
|
||||
delete(ac.confirms, confirmID)
|
||||
}
|
||||
ac.cfMu.Unlock()
|
||||
if ok {
|
||||
ch <- approved
|
||||
}
|
||||
}
|
||||
|
||||
func (ac *agentConn) delConfirm(id string) {
|
||||
ac.cfMu.Lock()
|
||||
delete(ac.confirms, id)
|
||||
ac.cfMu.Unlock()
|
||||
}
|
||||
|
||||
// abort 中断当前任务 // Logan.Li
|
||||
func (ac *agentConn) abort() {
|
||||
if ac.cancel != nil {
|
||||
ac.cancel()
|
||||
ac.cancel = nil
|
||||
}
|
||||
}
|
||||
|
||||
// lastRound 估算已完成轮次（从 DB 取该会话最大 round） // Logan.Li
|
||||
func (ac *agentConn) lastRound() int {
|
||||
if ac.session == nil {
|
||||
return 0
|
||||
}
|
||||
var maxRound int
|
||||
ac.db.Model(&model.AgentCLIMessage{}).Where("session_id = ?", ac.session.ID).
|
||||
Select("COALESCE(MAX(round),0)").Scan(&maxRound)
|
||||
return maxRound
|
||||
}
|
||||
|
||||
// finish 结束会话并更新 DB // Logan.Li
|
||||
func (ac *agentConn) finish(sess *model.AgentCLISession, status, errMsg string, rounds int, dur time.Duration) {
|
||||
if status == "done" || status == "aborted" || status == "error" {
|
||||
ac.write(wsEvent{Type: status, SessionID: sess.ID, Message: errMsg, Round: rounds})
|
||||
}
|
||||
updates := map[string]interface{}{
|
||||
"status": status, "rounds": rounds, "duration": dur.Milliseconds(),
|
||||
}
|
||||
if errMsg != "" {
|
||||
updates["error"] = errMsg
|
||||
}
|
||||
ac.db.Model(sess).Updates(updates)
|
||||
}
|
||||
|
||||
// write 线程安全写 WS 消息 // Logan.Li
|
||||
func (ac *agentConn) write(ev wsEvent) {
|
||||
ac.writeMu.Lock()
|
||||
defer ac.writeMu.Unlock()
|
||||
b, _ := json.Marshal(ev)
|
||||
_ = ac.conn.WriteMessage(websocket.TextMessage, b)
|
||||
}
|
||||
|
||||
// persistMsg 持久化一条消息 // Logan.Li
|
||||
func (ac *agentConn) persistMsg(sid uint, round int, typ, role, content, toolName, args, output, risk string, success bool, dur string, tokens int) {
|
||||
msg := &model.AgentCLIMessage{
|
||||
SessionID: sid, Round: round, Type: typ, Role: role, Content: content,
|
||||
ToolName: toolName, ToolArgs: args, ToolOutput: output, Risk: risk,
|
||||
Success: success, Duration: dur, Tokens: tokens,
|
||||
}
|
||||
if err := ac.db.Create(msg).Error; err != nil {
|
||||
// 持久化失败不阻断主流程
|
||||
_ = err
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
// agent_cli_api.go - Agent CLI 会话历史 REST 接口 // Logan.Li
|
||||
// 供前端展示历史任务列表与回放某次任务的完整推理过程。
|
||||
package controller
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"strconv"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"ezops/middleware"
|
||||
"ezops/model"
|
||||
)
|
||||
|
||||
// ListSessions 会话列表（按当前用户隔离） // Logan.Li
|
||||
// GET /api/v1/aiops/agent-cli/sessions?server_id=&page=&page_size=
|
||||
func (h *AgentCLIHandler) ListSessions(c *gin.Context) {
|
||||
uid := middleware.GetUserID(c)
|
||||
page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
|
||||
if page < 1 {
|
||||
page = 1
|
||||
}
|
||||
pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
|
||||
if pageSize <= 0 || pageSize > 100 {
|
||||
pageSize = 20
|
||||
}
|
||||
|
||||
q := h.db.Model(&model.AgentCLISession{}).Where("user_id = ?", uid)
|
||||
if sid := c.Query("server_id"); sid != "" {
|
||||
q = q.Where("server_id = ?", sid)
|
||||
}
|
||||
|
||||
var total int64
|
||||
q.Count(&total)
|
||||
var sessions []model.AgentCLISession
|
||||
if err := q.Order("created_at DESC").Offset((page - 1) * pageSize).Limit(pageSize).Find(&sessions).Error; err != nil {
|
||||
c.JSON(http.StatusOK, model.Response{Code: 500, Message: "查询失败: " + err.Error()})
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, model.Response{Code: 200, Data: gin.H{"list": sessions, "total": total}})
|
||||
}
|
||||
|
||||
// GetSession 会话详情（含完整推理消息，供回放） // Logan.Li
|
||||
// GET /api/v1/aiops/agent-cli/sessions/:id
|
||||
func (h *AgentCLIHandler) GetSession(c *gin.Context) {
|
||||
id := c.Param("id")
|
||||
var sess model.AgentCLISession
|
||||
if err := h.db.First(&sess, id).Error; err != nil {
|
||||
c.JSON(http.StatusOK, model.Response{Code: 404, Message: "会话不存在"})
|
||||
return
|
||||
}
|
||||
var msgs []model.AgentCLIMessage
|
||||
h.db.Where("session_id = ?", id).Order("id ASC").Find(&msgs)
|
||||
c.JSON(http.StatusOK, model.Response{Code: 200, Data: gin.H{"session": sess, "messages": msgs}})
|
||||
}
|
||||
|
||||
// DeleteSession 删除会话及其消息 // Logan.Li
|
||||
// DELETE /api/v1/aiops/agent-cli/sessions/:id
|
||||
func (h *AgentCLIHandler) DeleteSession(c *gin.Context) {
|
||||
id := c.Param("id")
|
||||
if err := h.db.Where("session_id = ?", id).Delete(&model.AgentCLIMessage{}).Error; err != nil {
|
||||
c.JSON(http.StatusOK, model.Response{Code: 500, Message: "删除消息失败: " + err.Error()})
|
||||
return
|
||||
}
|
||||
if err := h.db.Delete(&model.AgentCLISession{}, id).Error; err != nil {
|
||||
c.JSON(http.StatusOK, model.Response{Code: 500, Message: "删除会话失败: " + err.Error()})
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, model.Response{Code: 200, Message: "已删除"})
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
// agent_cli.go - Agent CLI 会话与消息持久化模型 // Logan.Li
|
||||
// 记录 AI 运维 Agent 的每次任务（关联主机 + 用户）及其 ReAct 推理过程
|
||||
// （思考/工具调用/输出/结果），供前端历史回放与审计。
|
||||
package model
|
||||
|
||||
import "time"
|
||||
|
||||
// AgentCLISession Agent CLI 任务会话 // Logan.Li
|
||||
type AgentCLISession struct {
|
||||
ID uint `gorm:"primarykey" json:"id"`
|
||||
UserID uint `gorm:"index" json:"user_id"` // 发起用户
|
||||
ServerID uint `gorm:"index" json:"server_id"` // 目标主机
|
||||
ServerName string `gorm:"size:128" json:"server_name"` // 主机名快照
|
||||
ServerHost string `gorm:"size:64" json:"server_host"` // 主机 IP 快照
|
||||
Title string `gorm:"size:255" json:"title"` // 任务标题（query 截断）
|
||||
Status string `gorm:"size:32;default:running" json:"status"` // running/done/aborted/error
|
||||
Provider string `gorm:"size:50" json:"provider"` // LLM 提供商
|
||||
Model string `gorm:"size:100" json:"model"` // 模型名
|
||||
Rounds int `json:"rounds"` // ReAct 轮次
|
||||
TotalTokens int `json:"total_tokens"` // token 消耗
|
||||
Duration int64 `json:"duration"` // 耗时（毫秒）
|
||||
Error string `gorm:"type:text" json:"error,omitempty"` // 错误信息
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// TableName 表名 // Logan.Li
|
||||
func (AgentCLISession) TableName() string { return "agent_cli_sessions" }
|
||||
|
||||
// AgentCLIMessage Agent CLI 任务消息（ReAct 推理过程的每一步） // Logan.Li
|
||||
type AgentCLIMessage struct {
|
||||
ID uint `gorm:"primarykey" json:"id"`
|
||||
SessionID uint `gorm:"index;not null" json:"session_id"`
|
||||
Round int `json:"round"` // ReAct 轮次
|
||||
Type string `gorm:"size:32" json:"type"` // thought/tool_call/tool_result/done/error/session
|
||||
Role string `gorm:"size:32" json:"role"` // user/assistant/tool
|
||||
Content string `gorm:"type:text" json:"content"` // 思考文本/最终答案
|
||||
ToolName string `gorm:"size:64" json:"tool_name"` // 工具名
|
||||
ToolArgs string `gorm:"type:text" json:"tool_args"` // 工具参数 JSON
|
||||
ToolOutput string `gorm:"type:text" json:"tool_output"` // 工具输出
|
||||
Risk string `gorm:"size:32" json:"risk"` // 风险等级
|
||||
Success bool `json:"success"`
|
||||
Duration string `gorm:"size:32" json:"duration"` // 工具耗时
|
||||
Tokens int `json:"tokens"`
|
||||
CreatedAt time.Time `gorm:"index" json:"created_at"`
|
||||
}
|
||||
|
||||
// TableName 表名 // Logan.Li
|
||||
func (AgentCLIMessage) TableName() string { return "agent_cli_messages" }
|
||||
@@ -0,0 +1,109 @@
|
||||
// Package agentcli 是 Agent CLI 引擎的顶层入口。 // Logan.Li
|
||||
// 组装 llm 客户端 + 工具注册中心（含 ssh_execute）+ 安全控制器 + Evolver + ReAct 核心，
|
||||
// 对外暴露 Engine，由 controller 通过依赖注入（EventCallback / ConfirmFn / SSH 凭据）驱动。
|
||||
//
|
||||
// 设计原则（参考 opsxcli，适配为 aiops 后端库）：
|
||||
// - 零业务依赖：不 import model/controller，所有持久化与 WS 由 controller 层负责。
|
||||
// - 复用 aiops 既有能力：LLM 走 OpenAI 兼容（model.LLMConfig），SSH 走 pkg/remoteexec。
|
||||
// - 安全：危险命令黑名单硬拒，高危命令经 ConfirmFn 由前端确认。
|
||||
// - 自进化：Evolver 异步学习经验并注入下次 Prompt，失败优雅降级。
|
||||
package agentcli
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"ezops/pkg/agentcli/core"
|
||||
"ezops/pkg/agentcli/evolver"
|
||||
"ezops/pkg/agentcli/llm"
|
||||
"ezops/pkg/agentcli/safety"
|
||||
"ezops/pkg/agentcli/tools"
|
||||
"ezops/pkg/remoteexec"
|
||||
)
|
||||
|
||||
// EngineConfig 引擎配置（由 controller 从 model.LLMConfig + model.Server 构建后注入） // Logan.Li
|
||||
type EngineConfig struct {
|
||||
LLM llm.Config // LLM 客户端配置（endpoint 已解析）
|
||||
SSH remoteexec.SSHConfig // 目标主机 SSH 配置（含凭据）
|
||||
SafetyMode safety.Mode // 安全模式（默认 balanced）
|
||||
Core *core.Config // ReAct 配置（nil 用默认）
|
||||
MemoryDir string // Evolver 记忆目录（空则 data/agentcli）
|
||||
}
|
||||
|
||||
// Engine Agent CLI 引擎实例（每个 WebSocket 连接 / 任务一个） // Logan.Li
|
||||
type Engine struct {
|
||||
agent *core.Agent
|
||||
safety *safety.Controller
|
||||
tools *tools.Registry
|
||||
evolver *evolver.EvolverEngine
|
||||
}
|
||||
|
||||
// NewEngine 组装引擎并注册默认工具集 // Logan.Li
|
||||
func NewEngine(cfg EngineConfig) (*Engine, error) {
|
||||
coreCfg := cfg.Core
|
||||
if coreCfg == nil {
|
||||
coreCfg = core.DefaultConfig()
|
||||
}
|
||||
if cfg.MemoryDir != "" {
|
||||
coreCfg.MemoryDir = cfg.MemoryDir
|
||||
}
|
||||
mode := cfg.SafetyMode
|
||||
if mode == "" {
|
||||
mode = safety.ModeBalanced
|
||||
}
|
||||
|
||||
// LLM 客户端
|
||||
client := llm.NewClient(cfg.LLM)
|
||||
|
||||
// 工具注册中心：ssh_execute（注入目标主机凭据）+ analyze_output
|
||||
registry := tools.NewRegistry()
|
||||
registry.Register(tools.NewSSHExecuteTool(cfg.SSH, coreCfg.ToolTimeout))
|
||||
registry.Register(tools.NewAnalyzeOutputTool())
|
||||
|
||||
// 安全控制器
|
||||
sc := safety.NewController(mode)
|
||||
|
||||
// Evolver（LLM 可用时启用学习；失败降级）
|
||||
ev, err := evolver.NewEvolverEngine(coreCfg.MemoryDir, client)
|
||||
if err != nil {
|
||||
ev = nil // 降级：无自学习，不影响主流程
|
||||
}
|
||||
|
||||
agent := core.NewAgent(client, registry, coreCfg, sc, ev)
|
||||
return &Engine{agent: agent, safety: sc, tools: registry, evolver: ev}, nil
|
||||
}
|
||||
|
||||
// SetCallback 注入事件回调（驱动前端渲染 + DB 持久化） // Logan.Li
|
||||
func (e *Engine) SetCallback(cb core.EventCallback) { e.agent.SetCallback(cb) }
|
||||
|
||||
// SetConfirmFn 注入高危确认回调（controller 推 WS confirm 事件并阻塞等前端回传） // Logan.Li
|
||||
func (e *Engine) SetConfirmFn(fn safety.ConfirmFn) { e.safety.SetConfirmFn(fn) }
|
||||
|
||||
// SetAutoApprove 测试用：自动批准（生产禁用） // Logan.Li
|
||||
func (e *Engine) SetAutoApprove(b bool) { e.safety.SetAutoApprove(b) }
|
||||
|
||||
// Run 执行任务（ReAct 循环），serverInfo 为目标主机摘要（注入 system prompt） // Logan.Li
|
||||
func (e *Engine) Run(ctx context.Context, query, serverInfo string) (string, error) {
|
||||
res, err := e.agent.Run(ctx, query, serverInfo)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if res != nil {
|
||||
return res.Output, nil
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
|
||||
// EvolveStats 进化统计（供审计展示） // Logan.Li
|
||||
func (e *Engine) EvolveStats() map[string]interface{} {
|
||||
if e.evolver == nil {
|
||||
return map[string]interface{}{"enabled": false}
|
||||
}
|
||||
return e.evolver.GetStats()
|
||||
}
|
||||
|
||||
// Close 释放资源 // Logan.Li
|
||||
func (e *Engine) Close() {
|
||||
if e.agent != nil {
|
||||
e.agent.Close()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,436 @@
|
||||
// Package core 实现 Agent CLI 的 ReAct 核心引擎。 // Logan.Li
|
||||
// 设计参考 opsxcli internal/agent/core，剥离 TUI（Bubble Tea），改用 EventCallback 推送事件流
|
||||
// （由 controller 序列化为 WebSocket 消息推给前端 + 持久化到 DB）。
|
||||
// 核心算法保留：16 轮 ReAct 主循环、自适应检查点、循环检测（同参>3 次拒绝）、连续失败追踪、Evolver 集成。
|
||||
package core
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"ezops/pkg/agentcli/evolver"
|
||||
"ezops/pkg/agentcli/llm"
|
||||
"ezops/pkg/agentcli/prompt"
|
||||
"ezops/pkg/agentcli/safety"
|
||||
"ezops/pkg/agentcli/tools"
|
||||
)
|
||||
|
||||
// EventType 事件类型（驱动前端渲染与 DB 持久化） // Logan.Li
|
||||
type EventType string
|
||||
|
||||
const (
|
||||
EventThought EventType = "thought" // AI 思考/推理文本
|
||||
EventToolCall EventType = "tool_call" // 即将执行的工具（名/参数/风险）
|
||||
EventToolResult EventType = "tool_result" // 工具执行结果（输出/成败/耗时）
|
||||
EventProgress EventType = "progress" // 轮次进度 + token
|
||||
EventDone EventType = "done" // 任务完成（最终答案）
|
||||
EventError EventType = "error" // 错误（含达到最大轮次）
|
||||
)
|
||||
|
||||
// Event 引擎产生的事件（controller 序列化后通过 WebSocket 推送） // Logan.Li
|
||||
type Event struct {
|
||||
Type EventType `json:"type"`
|
||||
Round int `json:"round,omitempty"`
|
||||
Thought string `json:"thought,omitempty"`
|
||||
ToolName string `json:"tool_name,omitempty"`
|
||||
ToolArgs map[string]interface{} `json:"tool_args,omitempty"`
|
||||
Risk string `json:"risk,omitempty"`
|
||||
Output string `json:"output,omitempty"`
|
||||
Success bool `json:"success,omitempty"`
|
||||
Duration string `json:"duration,omitempty"`
|
||||
Tokens int `json:"tokens,omitempty"`
|
||||
Answer string `json:"answer,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
|
||||
// EventCallback 事件回调（controller 注入） // Logan.Li
|
||||
type EventCallback func(Event)
|
||||
|
||||
// Config Agent 运行配置 // Logan.Li
|
||||
type Config struct {
|
||||
MaxIterations int
|
||||
Temperature float64
|
||||
ToolTimeout time.Duration
|
||||
MaxTokens int
|
||||
SafetyMode safety.Mode
|
||||
OutputMaxLength int
|
||||
MaxContextTokens int
|
||||
MemoryDir string // Evolver 记忆目录
|
||||
}
|
||||
|
||||
// DefaultConfig 默认配置 // Logan.Li
|
||||
func DefaultConfig() *Config {
|
||||
return &Config{
|
||||
MaxIterations: 16,
|
||||
Temperature: 0.3,
|
||||
ToolTimeout: 120 * time.Second,
|
||||
MaxTokens: 4096,
|
||||
SafetyMode: safety.ModeBalanced,
|
||||
OutputMaxLength: 10000,
|
||||
MaxContextTokens: 8000,
|
||||
MemoryDir: "data/agentcli",
|
||||
}
|
||||
}
|
||||
|
||||
// Agent ReAct 核心引擎 // Logan.Li
|
||||
type Agent struct {
|
||||
llm llm.Client
|
||||
registry *tools.Registry
|
||||
config *Config
|
||||
safetyCtl *safety.Controller
|
||||
evolver *evolver.EvolverEngine
|
||||
callback EventCallback
|
||||
totalTokens int
|
||||
mu sync.Mutex
|
||||
}
|
||||
|
||||
// NewAgent 创建引擎。evolver 为 nil 时降级（无自学习）。 // Logan.Li
|
||||
func NewAgent(client llm.Client, registry *tools.Registry, cfg *Config, sc *safety.Controller, ev *evolver.EvolverEngine) *Agent {
|
||||
if cfg == nil {
|
||||
cfg = DefaultConfig()
|
||||
}
|
||||
if sc == nil {
|
||||
sc = safety.NewController(cfg.SafetyMode)
|
||||
}
|
||||
if cfg.MaxContextTokens <= 0 {
|
||||
cfg.MaxContextTokens = 8000
|
||||
}
|
||||
return &Agent{llm: client, registry: registry, config: cfg, safetyCtl: sc, evolver: ev}
|
||||
}
|
||||
|
||||
// SetCallback 注入事件回调 // Logan.Li
|
||||
func (a *Agent) SetCallback(cb EventCallback) { a.callback = cb }
|
||||
|
||||
// emit 安全触发回调 // Logan.Li
|
||||
func (a *Agent) emit(e Event) {
|
||||
if a.callback != nil {
|
||||
a.callback(e)
|
||||
}
|
||||
}
|
||||
|
||||
// Run 执行单次任务（ReAct 循环 + Evolver 集成） // Logan.Li
|
||||
func (a *Agent) Run(ctx context.Context, query, serverInfo string) (*tools.Result, error) {
|
||||
a.totalTokens = 0
|
||||
start := time.Now()
|
||||
|
||||
// Evolver PREDICT：获取历史经验注入 system prompt
|
||||
evolveCtx := ""
|
||||
if a.evolver != nil {
|
||||
evolveCtx = a.evolver.GetContextForPrompt(query)
|
||||
}
|
||||
|
||||
// 工具描述
|
||||
toolDescs := a.buildToolDescriptions()
|
||||
systemPrompt := prompt.BuildSystemPrompt(serverInfo, toolDescs, evolveCtx)
|
||||
|
||||
messages := []llm.Message{
|
||||
{Role: "system", Content: systemPrompt},
|
||||
{Role: "user", Content: query},
|
||||
}
|
||||
llmTools := a.registry.ToLLMTools()
|
||||
|
||||
toolCallHistory := make(map[string]int) // 循环检测
|
||||
var toolRecords []evolver.ToolCallRecord
|
||||
var consecutiveFailures int
|
||||
var totalToolCalls int
|
||||
|
||||
for iter := 0; iter < a.config.MaxIterations; iter++ {
|
||||
// 检查中断
|
||||
if err := ctx.Err(); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
a.emit(Event{Type: EventProgress, Round: iter + 1})
|
||||
|
||||
// 自适应检查点
|
||||
if hint := a.checkAdaptiveCheckpoint(iter, toolCallHistory, consecutiveFailures, totalToolCalls); hint != "" {
|
||||
messages = append(messages, llm.Message{Role: "user", Content: hint})
|
||||
}
|
||||
|
||||
// 裁剪历史
|
||||
trimmed := a.trimMessages(messages)
|
||||
|
||||
// 调用 LLM
|
||||
resp, err := a.llm.Complete(ctx, &llm.CompletionRequest{
|
||||
Messages: trimmed,
|
||||
Tools: llmTools,
|
||||
Temperature: a.config.Temperature,
|
||||
MaxTokens: a.config.MaxTokens,
|
||||
})
|
||||
if err != nil {
|
||||
a.emit(Event{Type: EventError, Message: "LLM 调用失败: " + err.Error()})
|
||||
return nil, fmt.Errorf("LLM调用失败: %w", err)
|
||||
}
|
||||
|
||||
a.totalTokens += resp.Usage.TotalTokens
|
||||
a.emit(Event{Type: EventProgress, Tokens: a.totalTokens})
|
||||
|
||||
// 推送思考文本
|
||||
if strings.TrimSpace(resp.Message.Content) != "" {
|
||||
a.emit(Event{Type: EventThought, Round: iter + 1, Thought: resp.Message.Content})
|
||||
}
|
||||
messages = append(messages, resp.Message)
|
||||
|
||||
// 无工具调用 → 最终答案
|
||||
if len(resp.Message.ToolCalls) == 0 {
|
||||
answer := resp.Message.Content
|
||||
a.emit(Event{Type: EventDone, Answer: answer, Tokens: a.totalTokens})
|
||||
a.triggerEvolve(ctx, query, serverInfo, answer, toolRecords, true, start)
|
||||
return &tools.Result{Success: true, Output: answer}, nil
|
||||
}
|
||||
|
||||
// 处理工具调用
|
||||
observations, records, failInc := a.processToolCalls(ctx, resp.Message.ToolCalls, toolCallHistory, iter+1)
|
||||
toolRecords = append(toolRecords, records...)
|
||||
messages = append(messages, observations...)
|
||||
totalToolCalls += len(resp.Message.ToolCalls)
|
||||
consecutiveFailures = a.updateConsecutiveFailures(observations, consecutiveFailures) + failInc
|
||||
}
|
||||
|
||||
// 达到最大轮次
|
||||
msg := fmt.Sprintf("达到最大迭代次数(%d)，任务未能完成。可能任务过于复杂或需要更多步骤。", a.config.MaxIterations)
|
||||
a.emit(Event{Type: EventError, Message: msg, Tokens: a.totalTokens})
|
||||
a.triggerEvolve(ctx, query, serverInfo, "", toolRecords, false, start)
|
||||
return nil, fmt.Errorf("%s", msg)
|
||||
}
|
||||
|
||||
// processToolCalls 处理工具调用，返回 observation 消息 + 记录 // Logan.Li
|
||||
func (a *Agent) processToolCalls(ctx context.Context, calls []llm.ToolCall, history map[string]int, round int) ([]llm.Message, []evolver.ToolCallRecord, int) {
|
||||
obs := make([]llm.Message, 0, len(calls))
|
||||
records := make([]evolver.ToolCallRecord, 0, len(calls))
|
||||
var failInc int
|
||||
|
||||
for _, tc := range calls {
|
||||
key := tc.Function.Name + ":" + tc.Function.Arguments
|
||||
history[key]++
|
||||
|
||||
// 循环检测
|
||||
if history[key] > 3 {
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: "错误: 检测到循环调用，相同参数已调用超过3次，请换一种方式"})
|
||||
continue
|
||||
}
|
||||
|
||||
tool, err := a.registry.Get(tc.Function.Name)
|
||||
if err != nil {
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: fmt.Sprintf("错误: 工具 '%s' 未找到", tc.Function.Name)})
|
||||
continue
|
||||
}
|
||||
|
||||
var args map[string]interface{}
|
||||
if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: "错误: 参数解析失败: " + err.Error()})
|
||||
continue
|
||||
}
|
||||
|
||||
risk := a.toolRisk(tool, args)
|
||||
a.emit(Event{Type: EventToolCall, Round: round, ToolName: tc.Function.Name, ToolArgs: args, Risk: risk.Display()})
|
||||
|
||||
// 安全检查（高危触发 confirmFn，由 controller 异步确认）
|
||||
approved, err := a.safetyCtl.Check(tool, args)
|
||||
if err != nil {
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: "安全检查失败: " + err.Error()})
|
||||
continue
|
||||
}
|
||||
if !approved {
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: "操作已被用户拒绝执行"})
|
||||
a.emit(Event{Type: EventToolResult, Round: round, ToolName: tc.Function.Name,
|
||||
Output: "（用户拒绝执行）", Success: false})
|
||||
continue
|
||||
}
|
||||
|
||||
// 执行
|
||||
toolStart := time.Now()
|
||||
toolCtx, cancel := context.WithTimeout(ctx, a.config.ToolTimeout)
|
||||
result, execErr := tool.Execute(toolCtx, args)
|
||||
cancel()
|
||||
dur := time.Since(toolStart)
|
||||
|
||||
var output, errMsg string
|
||||
success := false
|
||||
if result != nil {
|
||||
output, errMsg, success = result.Output, result.Error, result.Success
|
||||
}
|
||||
if execErr != nil {
|
||||
errMsg = execErr.Error()
|
||||
success = false
|
||||
}
|
||||
|
||||
// 输出截断
|
||||
if len(output) > a.config.OutputMaxLength {
|
||||
output = output[:a.config.OutputMaxLength] +
|
||||
fmt.Sprintf("\n[输出已截断，原始 %d 字符]", len(output))
|
||||
}
|
||||
|
||||
a.emit(Event{Type: EventToolResult, Round: round, ToolName: tc.Function.Name,
|
||||
Output: output, Success: success, Duration: dur.Truncate(time.Millisecond).String()})
|
||||
|
||||
records = append(records, evolver.ToolCallRecord{
|
||||
ToolName: tc.Function.Name, Args: args, Output: output,
|
||||
Duration: dur, Success: success, RiskLevel: int(risk),
|
||||
})
|
||||
|
||||
// 构建 observation
|
||||
var content string
|
||||
switch {
|
||||
case execErr != nil:
|
||||
content = "执行错误: " + execErr.Error()
|
||||
failInc++
|
||||
case !success:
|
||||
content = fmt.Sprintf("执行失败: %s\n输出: %s", errMsg, output)
|
||||
failInc++
|
||||
default:
|
||||
content = output
|
||||
}
|
||||
obs = append(obs, llm.Message{Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name, Content: content})
|
||||
}
|
||||
return obs, records, failInc
|
||||
}
|
||||
|
||||
// triggerEvolve 异步触发进化（带超时 + panic 恢复，绝不阻塞主循环） // Logan.Li
|
||||
func (a *Agent) triggerEvolve(ctx context.Context, query, serverHost, answer string, records []evolver.ToolCallRecord, success bool, start time.Time) {
|
||||
if a.evolver == nil {
|
||||
return
|
||||
}
|
||||
exec := &evolver.TaskExecution{
|
||||
Query: query, ToolCalls: records, TotalSteps: len(records),
|
||||
TotalTokens: a.totalTokens, Duration: time.Since(start),
|
||||
Success: success, FinalAnswer: answer, Timestamp: time.Now(), ServerHost: serverHost,
|
||||
}
|
||||
go func() {
|
||||
defer func() { _ = recover() }()
|
||||
eCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel()
|
||||
_ = a.evolver.Evolve(eCtx, exec)
|
||||
}()
|
||||
}
|
||||
|
||||
// buildToolDescriptions 工具描述文本 // Logan.Li
|
||||
func (a *Agent) buildToolDescriptions() string {
|
||||
var sb strings.Builder
|
||||
for _, t := range a.registry.List() {
|
||||
sb.WriteString(fmt.Sprintf("- %s: %s\n", t.Name(), t.Description()))
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// toolRisk 取工具风险（动态优先） // Logan.Li
|
||||
func (a *Agent) toolRisk(tool tools.Tool, args map[string]interface{}) tools.RiskLevel {
|
||||
if dt, ok := tool.(tools.DynamicRiskTool); ok {
|
||||
return dt.RiskLevelForArgs(args)
|
||||
}
|
||||
return tool.RiskLevel()
|
||||
}
|
||||
|
||||
// checkAdaptiveCheckpoint 自适应检查点（iter 3/7/11 注入引导） // Logan.Li
|
||||
func (a *Agent) checkAdaptiveCheckpoint(iter int, history map[string]int, consecFail, totalCalls int) string {
|
||||
switch iter {
|
||||
case 3:
|
||||
repeat := 0
|
||||
for _, c := range history {
|
||||
if c > 1 {
|
||||
repeat += c - 1
|
||||
}
|
||||
}
|
||||
if totalCalls > 0 && (float64(repeat)/float64(totalCalls) > 0.5 || consecFail >= 3) {
|
||||
return "【系统提示】检测到重复使用相同工具或连续失败，请尝试换一种思路或不同命令。"
|
||||
}
|
||||
case 7:
|
||||
return "【系统提示】已执行到中段，请总结进展。信息足够就直接给出最终答案，否则说明剩余步骤。"
|
||||
case 11:
|
||||
return fmt.Sprintf("【系统提示】仅剩 %d 步，请立即整理已有信息给出最终答案，不要再调用新工具。", a.config.MaxIterations-iter-1)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// updateConsecutiveFailures 连续失败计数 // Logan.Li
|
||||
func (a *Agent) updateConsecutiveFailures(obs []llm.Message, current int) int {
|
||||
errs := 0
|
||||
for _, o := range obs {
|
||||
c := o.Content
|
||||
if strings.HasPrefix(c, "错误") || strings.HasPrefix(c, "失败") || strings.HasPrefix(c, "执行错误") || strings.HasPrefix(c, "执行失败") {
|
||||
errs++
|
||||
}
|
||||
}
|
||||
if errs == 0 {
|
||||
return 0
|
||||
}
|
||||
return current + errs
|
||||
}
|
||||
|
||||
// trimMessages 裁剪历史（保留 system + 最近消息，token 不超 90%） // Logan.Li
|
||||
func (a *Agent) trimMessages(msgs []llm.Message) []llm.Message {
|
||||
if len(msgs) <= 1 {
|
||||
return msgs
|
||||
}
|
||||
maxT := a.config.MaxContextTokens * 9 / 10
|
||||
sysT := estimateTokens(msgs[0].Content)
|
||||
kept := make([]llm.Message, 0, len(msgs))
|
||||
keptT := 0
|
||||
for i := len(msgs) - 1; i >= 1; i-- {
|
||||
t := estimateTokens(msgs[i].Content)
|
||||
if sysT+keptT+t > maxT {
|
||||
break
|
||||
}
|
||||
keptT += t
|
||||
kept = append([]llm.Message{msgs[i]}, kept...)
|
||||
}
|
||||
// 最少保留最近 4 条，避免上下文过短
|
||||
if len(kept) < 4 && len(msgs) > 4 {
|
||||
kept = msgs[len(msgs)-4:]
|
||||
}
|
||||
result := append([]llm.Message{msgs[0]}, kept...)
|
||||
return ensureToolMessageIntegrity(result)
|
||||
}
|
||||
|
||||
// ensureToolMessageIntegrity 确保 tool 消息前面有对应 assistant(tool_calls) // Logan.Li
|
||||
func ensureToolMessageIntegrity(msgs []llm.Message) []llm.Message {
|
||||
validIDs := make(map[string]bool)
|
||||
for _, m := range msgs {
|
||||
if m.Role == "assistant" {
|
||||
for _, tc := range m.ToolCalls {
|
||||
validIDs[tc.ID] = true
|
||||
}
|
||||
}
|
||||
}
|
||||
out := make([]llm.Message, 0, len(msgs))
|
||||
for i, m := range msgs {
|
||||
if m.Role == "tool" {
|
||||
if !validIDs[m.ToolCallID] || i == 0 || msgs[i-1].Role != "assistant" {
|
||||
continue
|
||||
}
|
||||
matched := false
|
||||
for _, tc := range msgs[i-1].ToolCalls {
|
||||
if tc.ID == m.ToolCallID {
|
||||
matched = true
|
||||
break
|
||||
}
|
||||
}
|
||||
if !matched {
|
||||
continue
|
||||
}
|
||||
}
|
||||
out = append(out, m)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// estimateTokens 粗略 token 估算（中文约 1 字/token，英文约 1/4，折中 rune/3） // Logan.Li
|
||||
func estimateTokens(s string) int {
|
||||
return len([]rune(s))/3 + 1
|
||||
}
|
||||
|
||||
// Close 释放资源 // Logan.Li
|
||||
func (a *Agent) Close() {
|
||||
if a.registry != nil {
|
||||
// Registry 无 Closer 实现（Web 工具无连接池），保留接口位
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,271 @@
|
||||
// engine.go - 自进化引擎（Evolver）核心 // Logan.Li
|
||||
// 保留 opsxcli 13 步进化循环的思想，精简为核心步骤：
|
||||
// OBSERVE → CLASSIFY → LEARN → STORE → MEMORIZE → PREDICT（注入下次 Prompt）。
|
||||
// 异步执行、失败优雅降级（LLM 不可用退化为规则生成），绝不影响主 ReAct 循环。
|
||||
package evolver
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"ezops/pkg/agentcli/llm"
|
||||
)
|
||||
|
||||
// ToolCallRecord 工具调用记录（供 Evolver 观察学习） // Logan.Li
|
||||
type ToolCallRecord struct {
|
||||
ToolName string `json:"tool_name"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
Output string `json:"output"`
|
||||
Duration time.Duration `json:"duration"`
|
||||
Success bool `json:"success"`
|
||||
RiskLevel int `json:"risk_level"`
|
||||
}
|
||||
|
||||
// TaskExecution 一次任务的完整执行记录 // Logan.Li
|
||||
type TaskExecution struct {
|
||||
Query string `json:"query"`
|
||||
ToolCalls []ToolCallRecord `json:"tool_calls"`
|
||||
TotalSteps int `json:"total_steps"`
|
||||
TotalTokens int `json:"total_tokens"`
|
||||
Duration time.Duration `json:"duration"`
|
||||
Success bool `json:"success"`
|
||||
FinalAnswer string `json:"final_answer"`
|
||||
Timestamp time.Time `json:"timestamp"`
|
||||
ServerHost string `json:"server_host"` // 用于环境记忆
|
||||
}
|
||||
|
||||
// EvolveResult 进化结果（会话级回灌 Prompt） // Logan.Li
|
||||
type EvolveResult struct {
|
||||
TaskType string `json:"task_type"`
|
||||
LearnedHint string `json:"learned_hint"`
|
||||
ToolSequence []string `json:"tool_sequence"`
|
||||
ExperienceAdded bool `json:"experience_added"`
|
||||
Consolidated bool `json:"consolidated"`
|
||||
}
|
||||
|
||||
// EvolverEngine 自进化引擎 // Logan.Li
|
||||
type EvolverEngine struct {
|
||||
mem *Memories
|
||||
llm llm.Client // 可选，用于提炼经验/事实
|
||||
memDir string
|
||||
}
|
||||
|
||||
// NewEvolverEngine 创建进化引擎（llm 可为 nil，退化为规则学习） // Logan.Li
|
||||
func NewEvolverEngine(memDir string, client llm.Client) (*EvolverEngine, error) {
|
||||
if memDir == "" {
|
||||
memDir = "data/agentcli"
|
||||
}
|
||||
if err := ensureDir(memDir); err != nil {
|
||||
return nil, fmt.Errorf("初始化记忆目录失败: %w", err)
|
||||
}
|
||||
return &EvolverEngine{
|
||||
mem: NewMemories(memDir),
|
||||
llm: client,
|
||||
memDir: memDir,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Evolve 执行一次进化（观察任务 → 学习经验 → 存储） // Logan.Li
|
||||
// 设计为幂等、可降级：任何子步骤失败都不返回 error 给调用方（仅影响学习质量）。
|
||||
func (e *EvolverEngine) Evolve(ctx context.Context, exec *TaskExecution) *EvolveResult {
|
||||
if exec == nil {
|
||||
return nil
|
||||
}
|
||||
result := &EvolveResult{}
|
||||
|
||||
// Step 1: OBSERVE —— 提取工具序列
|
||||
for _, tc := range exec.ToolCalls {
|
||||
result.ToolSequence = append(result.ToolSequence, tc.ToolName)
|
||||
}
|
||||
|
||||
// Step 2: CLASSIFY —— 任务类型分类（关键词规则，无需 LLM）
|
||||
result.TaskType = classifyTask(exec.Query, exec.ToolCalls)
|
||||
|
||||
// Step 3: LEARN —— 生成经验 hint（优先 LLM，降级规则）
|
||||
result.LearnedHint = e.learnHint(ctx, exec, result.TaskType)
|
||||
|
||||
// Step 4: STORE —— 存入经验记忆 + 环境记忆（主机）
|
||||
exp := ExperienceEntry{
|
||||
TaskType: result.TaskType,
|
||||
Query: truncate(exec.Query, 200),
|
||||
Hint: result.LearnedHint,
|
||||
ToolSequence: result.ToolSequence,
|
||||
Success: exec.Success,
|
||||
Timestamp: exec.Timestamp.Unix(),
|
||||
}
|
||||
if err := e.mem.AddExperience(exp); err == nil {
|
||||
result.ExperienceAdded = true
|
||||
}
|
||||
if exec.ServerHost != "" {
|
||||
_ = e.mem.AddHost(exec.ServerHost) // 失败忽略
|
||||
}
|
||||
|
||||
// Step 5: MEMORIZE —— LLM 提炼持久事实（可选，失败降级）
|
||||
if e.llm != nil && exec.Success && exec.FinalAnswer != "" {
|
||||
go e.memorizeFact(ctx, exec) // 异步，不阻塞进化主流程
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
// learnHint 生成经验提示（LLM 优先，降级规则） // Logan.Li
|
||||
func (e *EvolverEngine) learnHint(ctx context.Context, exec *TaskExecution, taskType string) string {
|
||||
tools := strings.Join(uniqueStrings(resultToolNames(exec.ToolCalls)), " → ")
|
||||
|
||||
// 尝试用 LLM 提炼
|
||||
if e.llm != nil {
|
||||
if hint := e.llmLearnHint(ctx, exec, taskType, tools, exec.Success); hint != "" {
|
||||
return hint
|
||||
}
|
||||
}
|
||||
|
||||
// 降级：规则生成
|
||||
if exec.Success {
|
||||
return fmt.Sprintf("完成「%s」类任务时，工具序列 %s 最终成功，可作为参考。", taskType, tools)
|
||||
}
|
||||
return fmt.Sprintf("尝试「%s」类任务时，工具序列 %s 未成功，下次可换用不同命令或思路。", taskType, tools)
|
||||
}
|
||||
|
||||
// llmLearnHint 调用 LLM 提炼一句经验 // Logan.Li
|
||||
func (e *EvolverEngine) llmLearnHint(ctx context.Context, exec *TaskExecution, taskType, tools string, success bool) string {
|
||||
result := "失败"
|
||||
if success {
|
||||
result = "成功"
|
||||
}
|
||||
prompt := fmt.Sprintf(
|
||||
"你是运维经验提炼器。根据以下任务执行记录，用一句中文（不超过80字）提炼经验提示，"+
|
||||
"说明下次做同类任务的关键要点或推荐工具顺序。只返回经验文本，不要多余解释。\n"+
|
||||
"任务: %s\n工具序列: %s\n结果: %s",
|
||||
truncate(exec.Query, 150), tools, result)
|
||||
resp, err := e.llm.Complete(ctx, &llm.CompletionRequest{
|
||||
Messages: []llm.Message{{Role: "user", Content: prompt}},
|
||||
})
|
||||
if err != nil || resp == nil {
|
||||
return ""
|
||||
}
|
||||
return strings.TrimSpace(truncate(resp.Message.Content, 120))
|
||||
}
|
||||
|
||||
// memorizeFact 异步提取持久事实存入事实记忆 // Logan.Li
|
||||
func (e *EvolverEngine) memorizeFact(ctx context.Context, exec *TaskExecution) {
|
||||
defer func() { _ = recover() }()
|
||||
prompt := fmt.Sprintf(
|
||||
"从以下运维任务记录中，提炼 1 条值得长期记住的事实（如某主机的固定配置、已知问题、约定）。"+
|
||||
"如果没有明显可沉淀的事实，回复「无」。只返回事实本身，一句话。\n任务: %s\n结论: %s",
|
||||
truncate(exec.Query, 150), truncate(exec.FinalAnswer, 300))
|
||||
ctx2, cancel := context.WithTimeout(ctx, 20*time.Second)
|
||||
defer cancel()
|
||||
resp, err := e.llm.Complete(ctx2, &llm.CompletionRequest{
|
||||
Messages: []llm.Message{{Role: "user", Content: prompt}},
|
||||
})
|
||||
if err != nil || resp == nil {
|
||||
return
|
||||
}
|
||||
fact := strings.TrimSpace(resp.Message.Content)
|
||||
if fact == "" || strings.HasPrefix(fact, "无") {
|
||||
return
|
||||
}
|
||||
_ = e.mem.AddFact(FactEntry{Fact: truncate(fact, 150), Source: truncate(exec.Query, 80)})
|
||||
}
|
||||
|
||||
// GetContextForPrompt 为下一次任务构建记忆上下文（注入 system prompt） // Logan.Li
|
||||
func (e *EvolverEngine) GetContextForPrompt(query string) string {
|
||||
taskType := classifyTask(query, nil)
|
||||
var sb strings.Builder
|
||||
|
||||
if exps := e.mem.FindExperiences(taskType, 3); len(exps) > 0 {
|
||||
sb.WriteString(fmt.Sprintf(" 【%s 类历史经验】\n", taskType))
|
||||
for _, exp := range exps {
|
||||
mark := "成功"
|
||||
if !exp.Success {
|
||||
mark = "未成功"
|
||||
}
|
||||
sb.WriteString(fmt.Sprintf(" - (%s) %s\n", mark, exp.Hint))
|
||||
}
|
||||
}
|
||||
if facts := e.mem.RelevantFacts(query, 3); len(facts) > 0 {
|
||||
sb.WriteString(" 【已知事实】\n")
|
||||
for _, f := range facts {
|
||||
sb.WriteString(fmt.Sprintf(" - %s\n", f.Fact))
|
||||
}
|
||||
}
|
||||
if hosts := e.mem.Hosts(); len(hosts) > 0 {
|
||||
sb.WriteString(fmt.Sprintf(" 【已知主机】%s\n", strings.Join(hosts, ", ")))
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// GetStats 进化统计（供审计/展示） // Logan.Li
|
||||
func (e *EvolverEngine) GetStats() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"enabled": true,
|
||||
"memory": e.mem.CountStats(),
|
||||
}
|
||||
}
|
||||
|
||||
// ---- 任务分类（关键词规则） ---- // Logan.Li
|
||||
|
||||
// classifyTask 按 query + 工具调用关键词分类任务类型 // Logan.Li
|
||||
func classifyTask(query string, calls []ToolCallRecord) string {
|
||||
text := strings.ToLower(query)
|
||||
for _, c := range calls {
|
||||
if cmd, ok := c.Args["command"].(string); ok {
|
||||
text += " " + strings.ToLower(cmd)
|
||||
}
|
||||
}
|
||||
rules := []struct {
|
||||
typ string
|
||||
kws []string
|
||||
}{
|
||||
{"磁盘空间", []string{"disk", "空间", "df", "du", "inode", "磁盘", "满了"}},
|
||||
{"网络", []string{"network", "网络", "ping", "netstat", "ss ", "端口", "连接", "tcp", "dns"}},
|
||||
{"服务管理", []string{"service", "服务", "systemctl", "nginx", "mysql", "redis", "restart", "启动", "停止"}},
|
||||
{"软件安装", []string{"install", "安装", "yum", "apt", "docker", "部署", "deploy", "pip", "npm"}},
|
||||
{"进程排查", []string{"process", "进程", "ps ", "kill", "cpu", "top", "卡死", "hang"}},
|
||||
{"内存排查", []string{"memory", "内存", "mem", "free", "oom", "swap"}},
|
||||
{"日志排查", []string{"log", "日志", "journalctl", "tail", "grep"}},
|
||||
{"权限问题", []string{"permission", "权限", "chmod", "chown", "denied", "拒绝", "forbidden"}},
|
||||
{"性能调优", []string{"performance", "性能", "负载", "load", "慢", "slow", "latency", "延迟"}},
|
||||
{"配置管理", []string{"config", "配置", "conf", "vim", "sed"}},
|
||||
}
|
||||
for _, r := range rules {
|
||||
for _, kw := range r.kws {
|
||||
if strings.Contains(text, kw) {
|
||||
return r.typ
|
||||
}
|
||||
}
|
||||
}
|
||||
return "通用运维"
|
||||
}
|
||||
|
||||
// ---- 辅助 ---- // Logan.Li
|
||||
|
||||
func truncate(s string, n int) string {
|
||||
r := []rune(s)
|
||||
if len(r) <= n {
|
||||
return s
|
||||
}
|
||||
return string(r[:n]) + "..."
|
||||
}
|
||||
|
||||
func resultToolNames(calls []ToolCallRecord) []string {
|
||||
out := make([]string, 0, len(calls))
|
||||
for _, c := range calls {
|
||||
out = append(out, c.ToolName)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func uniqueStrings(in []string) []string {
|
||||
seen := make(map[string]bool)
|
||||
out := make([]string, 0, len(in))
|
||||
for _, s := range in {
|
||||
if !seen[s] {
|
||||
seen[s] = true
|
||||
out = append(out, s)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,246 @@
|
||||
// Package evolver 实现 Agent CLI 的自进化引擎（Evolver）。 // Logan.Li
|
||||
// 设计参考 opsxcli internal/agent/evolver，保留四层记忆 + 进化循环思想，精简适配为后端库：
|
||||
// - 记忆持久化用文件（data/agentcli/*.jsonl），与 opsxcli 原生一致，零 DB 依赖。
|
||||
// - 进化循环异步执行，失败优雅降级，绝不影响主 ReAct 循环。
|
||||
// - LLM 可用时用于提炼经验/事实；不可用时退化为规则生成。
|
||||
package evolver
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// ---- 基础文件存储 ---- // Logan.Li
|
||||
|
||||
// ensureDir 确保目录存在 // Logan.Li
|
||||
func ensureDir(dir string) error { return os.MkdirAll(dir, 0o755) }
|
||||
|
||||
// readJSONL 读取 JSONL 文件为切片 // Logan.Li
|
||||
func readJSONL[T any](path string) []T {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil || len(raw) == 0 {
|
||||
return nil
|
||||
}
|
||||
var out []T
|
||||
for _, line := range strings.Split(strings.TrimSpace(string(raw)), "\n") {
|
||||
line = strings.TrimSpace(line)
|
||||
if line == "" {
|
||||
continue
|
||||
}
|
||||
var item T
|
||||
if json.Unmarshal([]byte(line), &item) == nil {
|
||||
out = append(out, item)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// appendJSONL 追加一行 JSON // Logan.Li
|
||||
func appendJSONL[T any](path string, item T) error {
|
||||
b, err := json.Marshal(item)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
b = append(b, '\n')
|
||||
f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer f.Close()
|
||||
_, err = f.Write(b)
|
||||
return err
|
||||
}
|
||||
|
||||
// readJSON 读取整个 JSON 文件（失败返回默认值） // Logan.Li
|
||||
func readJSON[T any](path string, def T) T {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return def
|
||||
}
|
||||
var v T
|
||||
if json.Unmarshal(raw, &v) != nil {
|
||||
return def
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
// writeJSON 写入整个 JSON 文件 // Logan.Li
|
||||
func writeJSON[T any](path string, v T) error {
|
||||
b, err := json.MarshalIndent(v, "", " ")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return os.WriteFile(path, b, 0o644)
|
||||
}
|
||||
|
||||
// ---- 四层记忆 ---- // Logan.Li
|
||||
|
||||
// ExperienceEntry 经验记忆条目（最核心，直接注入下次 Prompt） // Logan.Li
|
||||
type ExperienceEntry struct {
|
||||
TaskType string `json:"task_type"`
|
||||
Query string `json:"query"`
|
||||
Hint string `json:"hint"` // 经验提示
|
||||
ToolSequence []string `json:"tool_sequence"` // 推荐工具序列
|
||||
Success bool `json:"success"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
// FactEntry 事实记忆条目（持久事实） // Logan.Li
|
||||
type FactEntry struct {
|
||||
Fact string `json:"fact"`
|
||||
Source string `json:"source"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
// SkillEntry 程序记忆条目（运维技能/流程） // Logan.Li
|
||||
type SkillEntry struct {
|
||||
Name string `json:"name"`
|
||||
When string `json:"when"`
|
||||
Steps []string `json:"steps"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
// Memories 四层记忆集合（线程安全） // Logan.Li
|
||||
type Memories struct {
|
||||
dir string
|
||||
mu sync.Mutex
|
||||
|
||||
expPath string // experience.jsonl
|
||||
facPath string // factual.jsonl
|
||||
sklPath string // procedural.jsonl
|
||||
envPath string // environment.json
|
||||
}
|
||||
|
||||
// NewMemories 创建四层记忆（dir 为 data/agentcli） // Logan.Li
|
||||
func NewMemories(dir string) *Memories {
|
||||
return &Memories{
|
||||
dir: dir,
|
||||
expPath: filepath.Join(dir, "experience.jsonl"),
|
||||
facPath: filepath.Join(dir, "factual.jsonl"),
|
||||
sklPath: filepath.Join(dir, "procedural.jsonl"),
|
||||
envPath: filepath.Join(dir, "environment.json"),
|
||||
}
|
||||
}
|
||||
|
||||
// AddExperience 追加经验 // Logan.Li
|
||||
func (m *Memories) AddExperience(e ExperienceEntry) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if e.Timestamp == 0 {
|
||||
e.Timestamp = time.Now().Unix()
|
||||
}
|
||||
return appendJSONL(m.expPath, e)
|
||||
}
|
||||
|
||||
// FindExperiences 按 task_type 查找最近的经验（最多 n 条，优先成功） // Logan.Li
|
||||
func (m *Memories) FindExperiences(taskType string, n int) []ExperienceEntry {
|
||||
all := readJSONL[ExperienceEntry](m.expPath)
|
||||
var matched []ExperienceEntry
|
||||
for _, e := range all {
|
||||
if taskType == "" || e.TaskType == taskType {
|
||||
matched = append(matched, e)
|
||||
}
|
||||
}
|
||||
// 优先成功经验，按时间倒序取前 n
|
||||
successFirst := make([]ExperienceEntry, 0, len(matched))
|
||||
others := make([]ExperienceEntry, 0, len(matched))
|
||||
for _, e := range matched {
|
||||
if e.Success {
|
||||
successFirst = append(successFirst, e)
|
||||
} else {
|
||||
others = append(others, e)
|
||||
}
|
||||
}
|
||||
// 简单逆序（文件本身就是时间顺序，取末尾最新）
|
||||
pick := func(s []ExperienceEntry) []ExperienceEntry {
|
||||
if len(s) <= n {
|
||||
return s
|
||||
}
|
||||
return s[len(s)-n:]
|
||||
}
|
||||
out := append(pick(successFirst), pick(others)...)
|
||||
if len(out) > n {
|
||||
out = out[len(out)-n:]
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// AddFact 追加事实 // Logan.Li
|
||||
func (m *Memories) AddFact(f FactEntry) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if f.Timestamp == 0 {
|
||||
f.Timestamp = time.Now().Unix()
|
||||
}
|
||||
return appendJSONL(m.facPath, f)
|
||||
}
|
||||
|
||||
// RelevantFacts 返回与 query 关键词相关的事实（最多 n 条） // Logan.Li
|
||||
func (m *Memories) RelevantFacts(query string, n int) []FactEntry {
|
||||
all := readJSONL[FactEntry](m.facPath)
|
||||
if len(all) == 0 {
|
||||
return nil
|
||||
}
|
||||
kw := strings.ToLower(query)
|
||||
var out []FactEntry
|
||||
for _, f := range all {
|
||||
if strings.Contains(strings.ToLower(f.Fact), kw) || strings.Contains(kw, strings.ToLower(f.Fact)) {
|
||||
out = append(out, f)
|
||||
}
|
||||
}
|
||||
if len(out) > n {
|
||||
out = out[len(out)-n:]
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// AddSkill 追加技能 // Logan.Li
|
||||
func (m *Memories) AddSkill(s SkillEntry) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if s.Timestamp == 0 {
|
||||
s.Timestamp = time.Now().Unix()
|
||||
}
|
||||
return appendJSONL(m.sklPath, s)
|
||||
}
|
||||
|
||||
// KnownHosts 已知主机（环境记忆） // Logan.Li
|
||||
type KnownHosts struct {
|
||||
Hosts []string `json:"hosts"`
|
||||
}
|
||||
|
||||
// AddHost 记录已知主机（去重） // Logan.Li
|
||||
func (m *Memories) AddHost(host string) error {
|
||||
if host == "" {
|
||||
return nil
|
||||
}
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
env := readJSON(m.envPath, KnownHosts{})
|
||||
for _, h := range env.Hosts {
|
||||
if h == host {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
env.Hosts = append(env.Hosts, host)
|
||||
return writeJSON(m.envPath, env)
|
||||
}
|
||||
|
||||
// Hosts 返回已知主机列表 // Logan.Li
|
||||
func (m *Memories) Hosts() []string {
|
||||
return readJSON(m.envPath, KnownHosts{}).Hosts
|
||||
}
|
||||
|
||||
// CountStats 统计各层记忆条目数 // Logan.Li
|
||||
func (m *Memories) CountStats() map[string]int {
|
||||
return map[string]int{
|
||||
"experience": len(readJSONL[ExperienceEntry](m.expPath)),
|
||||
"factual": len(readJSONL[FactEntry](m.facPath)),
|
||||
"skill": len(readJSONL[SkillEntry](m.sklPath)),
|
||||
"hosts": len(readJSON(m.envPath, KnownHosts{}).Hosts),
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,145 @@
|
||||
// openai.go - OpenAI 兼容 LLM 客户端实现 // Logan.Li
|
||||
// 复用 aiops 既有 LLM 调用模式（model.LLMConfig + resolveEndpoint + /chat/completions + Bearer）。
|
||||
// 支持所有 OpenAI 兼容后端：openai / deepseek / qwen / moonshot / ollama / custom。
|
||||
package llm
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Config LLM 客户端配置（endpoint 已由上层解析为完整 base url） // Logan.Li
|
||||
type Config struct {
|
||||
Endpoint string // 完整 base url，如 https://api.deepseek.com/v1
|
||||
APIKey string // Bearer token
|
||||
Model string // 模型名，如 deepseek-chat / gpt-4o-mini
|
||||
Temperature float64 // 采样温度
|
||||
MaxTokens int // 单次最大输出 token
|
||||
Timeout time.Duration // HTTP 超时（0 表示使用默认 180s）
|
||||
}
|
||||
|
||||
// OpenAIClient OpenAI 兼容客户端 // Logan.Li
|
||||
type OpenAIClient struct {
|
||||
cfg Config
|
||||
client *http.Client
|
||||
}
|
||||
|
||||
// NewClient 创建 OpenAI 兼容客户端 // Logan.Li
|
||||
func NewClient(cfg Config) Client {
|
||||
timeout := cfg.Timeout
|
||||
if timeout <= 0 {
|
||||
timeout = 180 * time.Second
|
||||
}
|
||||
return &OpenAIClient{
|
||||
cfg: cfg,
|
||||
client: &http.Client{Timeout: timeout},
|
||||
}
|
||||
}
|
||||
|
||||
// Name 返回客户端名称 // Logan.Li
|
||||
func (c *OpenAIClient) Name() string { return "openai-compatible(" + c.cfg.Model + ")" }
|
||||
|
||||
// openaiRequest OpenAI chat/completions 请求体 // Logan.Li
|
||||
type openaiRequest struct {
|
||||
Model string `json:"model"`
|
||||
Messages []Message `json:"messages"`
|
||||
Tools []Tool `json:"tools,omitempty"`
|
||||
ToolChoice string `json:"tool_choice,omitempty"` // "auto" 让模型自主决定
|
||||
Temperature float64 `json:"temperature,omitempty"`
|
||||
MaxTokens int `json:"max_tokens,omitempty"`
|
||||
}
|
||||
|
||||
// openaiResponse OpenAI chat/completions 响应体 // Logan.Li
|
||||
type openaiResponse struct {
|
||||
Choices []struct {
|
||||
Message struct {
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
ToolCalls []ToolCall `json:"tool_calls"`
|
||||
} `json:"message"`
|
||||
} `json:"choices"`
|
||||
Usage Usage `json:"usage"`
|
||||
Error *struct {
|
||||
Message string `json:"message"`
|
||||
Type string `json:"type"`
|
||||
} `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
// Complete 调用 OpenAI 兼容接口完成一轮补全 // Logan.Li
|
||||
// 返回 assistant 消息（含思考文本 content 与工具调用计划 tool_calls）+ token 统计。
|
||||
func (c *OpenAIClient) Complete(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error) {
|
||||
payload := openaiRequest{
|
||||
Model: c.cfg.Model,
|
||||
Messages: req.Messages,
|
||||
Tools: req.Tools,
|
||||
ToolChoice: "auto",
|
||||
Temperature: c.cfg.Temperature,
|
||||
MaxTokens: c.cfg.MaxTokens,
|
||||
}
|
||||
if payload.MaxTokens <= 0 {
|
||||
payload.MaxTokens = 4096
|
||||
}
|
||||
body, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("序列化请求失败: %w", err)
|
||||
}
|
||||
|
||||
url := c.cfg.Endpoint + "/chat/completions"
|
||||
httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("构造请求失败: %w", err)
|
||||
}
|
||||
httpReq.Header.Set("Content-Type", "application/json")
|
||||
httpReq.Header.Set("Authorization", "Bearer "+c.cfg.APIKey)
|
||||
|
||||
resp, err := c.client.Do(httpReq)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("LLM 连接失败: %w", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
raw, _ := io.ReadAll(resp.Body)
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("LLM 返回错误 (HTTP %d): %s", resp.StatusCode, extractErrorMessage(raw))
|
||||
}
|
||||
|
||||
var parsed openaiResponse
|
||||
if err := json.Unmarshal(raw, &parsed); err != nil {
|
||||
return nil, fmt.Errorf("解析 LLM 响应失败: %w", err)
|
||||
}
|
||||
if parsed.Error != nil && parsed.Error.Message != "" {
|
||||
return nil, fmt.Errorf("LLM 错误: %s", parsed.Error.Message)
|
||||
}
|
||||
if len(parsed.Choices) == 0 {
|
||||
return nil, fmt.Errorf("LLM 未返回任何结果")
|
||||
}
|
||||
|
||||
choice := parsed.Choices[0].Message
|
||||
return &CompletionResponse{
|
||||
Model: c.cfg.Model,
|
||||
Message: Message{
|
||||
Role: choice.Role,
|
||||
Content: choice.Content,
|
||||
ToolCalls: choice.ToolCalls,
|
||||
},
|
||||
Usage: parsed.Usage,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// extractErrorMessage 从上游错误响应提取 message 字段 // Logan.Li
|
||||
func extractErrorMessage(raw []byte) string {
|
||||
var m struct {
|
||||
Error struct {
|
||||
Message string `json:"message"`
|
||||
} `json:"error"`
|
||||
}
|
||||
if json.Unmarshal(raw, &m) == nil && m.Error.Message != "" {
|
||||
return m.Error.Message
|
||||
}
|
||||
return string(raw)
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
// Package llm 提供 Agent CLI 引擎使用的 LLM 抽象层。 // Logan.Li
|
||||
// 仅保留与 ReAct 循环相关的最小接口：消息、工具调用、补全请求/响应、Client。
|
||||
// 设计参考 opsxcli/internal/llm，剥离 CLI 配置向导与多 Provider 文件配置，
|
||||
// 配置由上层（controller）从 model.LLMConfig 解析后注入。
|
||||
package llm
|
||||
|
||||
import "context"
|
||||
|
||||
// Message 聊天消息（OpenAI 兼容格式） // Logan.Li
|
||||
type Message struct {
|
||||
Role string `json:"role"` // system / user / assistant / tool
|
||||
Content string `json:"content"` // 消息内容
|
||||
Name string `json:"name,omitempty"` // tool 消息对应的工具名
|
||||
ToolCallID string `json:"tool_call_id,omitempty"` // tool 消息对应的 tool_call id
|
||||
ToolCalls []ToolCall `json:"tool_calls,omitempty"` // assistant 消息携带的工具调用
|
||||
}
|
||||
|
||||
// ToolCall 工具调用 // Logan.Li
|
||||
type ToolCall struct {
|
||||
ID string `json:"id"`
|
||||
Type string `json:"type"` // 固定 "function"
|
||||
Function FunctionCall `json:"function"`
|
||||
}
|
||||
|
||||
// FunctionCall 函数调用（名称 + JSON 字符串参数） // Logan.Li
|
||||
type FunctionCall struct {
|
||||
Name string `json:"name"`
|
||||
Arguments string `json:"arguments"` // JSON 字符串
|
||||
}
|
||||
|
||||
// Tool LLM 工具定义（function calling） // Logan.Li
|
||||
type Tool struct {
|
||||
Type string `json:"type"` // 固定 "function"
|
||||
Function ToolFunction `json:"function"`
|
||||
}
|
||||
|
||||
// ToolFunction 工具函数定义（给 LLM 看的 name/description/parameters） // Logan.Li
|
||||
type ToolFunction struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"` // JSON Schema
|
||||
}
|
||||
|
||||
// CompletionRequest 补全请求参数 // Logan.Li
|
||||
type CompletionRequest struct {
|
||||
Messages []Message `json:"messages"`
|
||||
Tools []Tool `json:"tools,omitempty"`
|
||||
Temperature float64 `json:"temperature,omitempty"`
|
||||
MaxTokens int `json:"max_tokens,omitempty"`
|
||||
}
|
||||
|
||||
// CompletionResponse 补全响应（取首个 choice） // Logan.Li
|
||||
type CompletionResponse struct {
|
||||
ID string `json:"id"`
|
||||
Model string `json:"model"`
|
||||
Message Message `json:"message"`
|
||||
Usage Usage `json:"usage"`
|
||||
}
|
||||
|
||||
// Usage token 使用统计 // Logan.Li
|
||||
type Usage struct {
|
||||
PromptTokens int `json:"prompt_tokens"`
|
||||
CompletionTokens int `json:"completion_tokens"`
|
||||
TotalTokens int `json:"total_tokens"`
|
||||
}
|
||||
|
||||
// Client LLM 客户端接口 // Logan.Li
|
||||
type Client interface {
|
||||
// Complete 一次性补全（返回思考文本 + 工具调用计划）。
|
||||
Complete(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error)
|
||||
// Name 返回客户端名称（用于日志/审计）。
|
||||
Name() string
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
// Package prompt 构建 Agent CLI 的 System Prompt（五层架构 + 动态记忆注入）。 // Logan.Li
|
||||
// 设计参考 opsxcli internal/agent/prompt，角色改写为 aiops Web 运维 Agent 语境。
|
||||
package prompt
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// BuildSystemPrompt 构建五层 System Prompt。 // Logan.Li
|
||||
// - Layer 1: 角色定位（aiops 智能运维 Agent）
|
||||
// - Layer 2: 安全规则（黑名单/高危确认/优先只读）
|
||||
// - Layer 3: 工具说明（由 registry 动态生成）
|
||||
// - Layer 4: 工作方式（ReAct 循环：思考→执行→观察→失败则换法重试→直到解决）
|
||||
// - Layer 5: 记忆注入（Evolver 提供的历史经验）
|
||||
//
|
||||
// serverInfo：目标主机摘要；toolDescs：工具描述文本；evolveContext：历史经验。
|
||||
func BuildSystemPrompt(serverInfo, toolDescs, evolveContext string) string {
|
||||
var sb strings.Builder
|
||||
|
||||
// Layer 1: 角色
|
||||
sb.WriteString("你是 aiops 平台的 Agent CLI —— 一个企业级智能运维 Agent，" +
|
||||
"类似 Claude Code / Codex，但运行在 Web 页面上，通过 SSH 工具远程操作真实服务器。\n")
|
||||
sb.WriteString("你的职责是：根据用户的自然语言任务描述，自主在目标服务器上排查故障、安装与配置软件、修复问题，" +
|
||||
"并通过 WebSocket 把每一步思考、执行的命令和输出实时反馈给用户。\n\n")
|
||||
|
||||
// 目标主机
|
||||
if strings.TrimSpace(serverInfo) != "" {
|
||||
sb.WriteString("【目标主机】\n" + serverInfo + "\n\n")
|
||||
}
|
||||
|
||||
// Layer 2: 安全规则
|
||||
sb.WriteString("【安全规则】\n")
|
||||
sb.WriteString("1. 破坏性命令（rm -rf /、mkfs、dd 覆写磁盘等）被严格禁止，绝不执行。\n")
|
||||
sb.WriteString("2. 高危操作（reboot、systemctl restart、kill、卸载软件等）需要用户确认后才能执行。\n")
|
||||
sb.WriteString("3. 排障时优先使用只读命令（df/ps/cat/grep/tail/systemctl status/journalctl）收集信息，确认根因后再动手修复。\n")
|
||||
sb.WriteString("4. 不要执行任何你不确定后果的命令；宁可多问用户，也不盲目操作。\n\n")
|
||||
|
||||
// Layer 3: 工具
|
||||
if strings.TrimSpace(toolDescs) != "" {
|
||||
sb.WriteString("【可用工具】\n" + toolDescs + "\n\n")
|
||||
}
|
||||
|
||||
// Layer 4: 工作方式（ReAct）
|
||||
sb.WriteString("【工作方式（ReAct 循环）】\n")
|
||||
sb.WriteString("你采用「思考-行动-观察」循环解决任务：\n")
|
||||
sb.WriteString("1. 思考：分析当前状态，决定下一步。在回复中先用简短文字说明你的判断和计划。\n")
|
||||
sb.WriteString("2. 行动：调用 ssh_execute 执行命令（一次只做关键的、可验证的一步）。\n")
|
||||
sb.WriteString("3. 观察：仔细阅读命令输出（含 exit_code，0 表示成功）。\n")
|
||||
sb.WriteString("4. 循环：如果命令失败或问题未解决，分析错误原因，换一种方法重试，直到真正解决。不要因一次失败就放弃。\n")
|
||||
sb.WriteString("5. 收尾：问题解决后，用清晰的中文总结：问题根因、你做了什么、最终结果、后续建议。然后停止调用工具。\n\n")
|
||||
|
||||
sb.WriteString("【重要】务必真正解决问题，而不是假装解决。每一步都要基于实际命令输出判断，" +
|
||||
"禁止编造不存在的输出。命令超时或连接失败时，向用户说明并建议排查方向。\n\n")
|
||||
|
||||
// Layer 5: 记忆注入
|
||||
if strings.TrimSpace(evolveContext) != "" {
|
||||
sb.WriteString("【历史经验（来自自进化引擎）】\n" + evolveContext + "\n\n")
|
||||
}
|
||||
|
||||
// 输出要求
|
||||
sb.WriteString("【输出要求】使用简体中文，简洁专业。思考与命令穿插呈现，避免冗长空话。")
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// FormatToolDescriptions 把工具名+描述格式化为列表文本 // Logan.Li
|
||||
func FormatToolDescriptions(items []struct{ Name, Desc string }) string {
|
||||
var sb strings.Builder
|
||||
for _, it := range items {
|
||||
sb.WriteString(fmt.Sprintf("- %s: %s\n", it.Name, it.Desc))
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
// Package safety 提供 Agent CLI 的安全控制层。 // Logan.Li
|
||||
// 设计参考 opsxcli internal/agent/safety，适配 Web 场景：确认动作改为异步回调
|
||||
// （由 controller 实现 confirmFn：推送 WS confirm 事件并阻塞等待前端回传）。
|
||||
// 风险评估逻辑（黑名单 + AssessBashRisk）在 tools 包，本包只做"是否需确认"的策略。
|
||||
package safety
|
||||
|
||||
import (
|
||||
"ezops/pkg/agentcli/tools"
|
||||
)
|
||||
|
||||
// Mode 安全模式 // Logan.Li
|
||||
type Mode string
|
||||
|
||||
const (
|
||||
ModeStrict Mode = "strict" // medium+ 需确认
|
||||
ModeBalanced Mode = "balanced" // high+ 需确认（默认）
|
||||
ModePermissive Mode = "permissive" // 仅 critical 处理
|
||||
)
|
||||
|
||||
// ConfirmFn 确认回调：由 controller 实现，返回用户是否批准执行。 // Logan.Li
|
||||
// risk 为动态评估的风险等级，args 为工具参数（含具体 command），供前端展示。
|
||||
type ConfirmFn func(toolName string, args map[string]interface{}, risk tools.RiskLevel) (bool, error)
|
||||
|
||||
// Controller 安全控制器 // Logan.Li
|
||||
type Controller struct {
|
||||
mode Mode
|
||||
confirmFn ConfirmFn
|
||||
autoApprove bool // 测试用：自动批准（危险，生产禁用）
|
||||
}
|
||||
|
||||
// NewController 创建安全控制器 // Logan.Li
|
||||
func NewController(mode Mode) *Controller {
|
||||
if mode == "" {
|
||||
mode = ModeBalanced
|
||||
}
|
||||
return &Controller{mode: mode}
|
||||
}
|
||||
|
||||
// SetConfirmFn 注入确认回调 // Logan.Li
|
||||
func (c *Controller) SetConfirmFn(fn ConfirmFn) { c.confirmFn = fn }
|
||||
|
||||
// SetAutoApprove 设置自动批准（仅测试） // Logan.Li
|
||||
func (c *Controller) SetAutoApprove(b bool) { c.autoApprove = b }
|
||||
|
||||
// riskThreshold 各模式下的确认阈值 // Logan.Li
|
||||
func (c *Controller) riskThreshold() tools.RiskLevel {
|
||||
switch c.mode {
|
||||
case ModeStrict:
|
||||
return tools.RiskMedium
|
||||
case ModePermissive:
|
||||
return tools.RiskCritical
|
||||
default:
|
||||
return tools.RiskHigh
|
||||
}
|
||||
}
|
||||
|
||||
// Check 执行前安全检查，返回是否允许执行。 // Logan.Li
|
||||
// 策略：
|
||||
// 1. 命中危险命令黑名单（Critical）→ 直接拒绝（硬红线，不可确认放行）。
|
||||
// 2. 按模式阈值，达到等级 → 调 confirmFn 请用户确认。
|
||||
// 3. AutoApprove → 跳过确认。
|
||||
func (c *Controller) Check(tool tools.Tool, args map[string]interface{}) (bool, error) {
|
||||
risk := assessToolRisk(tool, args)
|
||||
|
||||
// 黑名单硬红线：rm -rf /、mkfs 等绝不允许
|
||||
if risk >= tools.RiskCritical {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
// 未达阈值或自动批准：直接放行
|
||||
if c.autoApprove || risk < c.riskThreshold() {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
// 达到阈值：请求用户确认
|
||||
if c.confirmFn == nil {
|
||||
// 无确认回调时，保守拒绝（Web 场景应始终注入 confirmFn）
|
||||
return false, nil
|
||||
}
|
||||
return c.confirmFn(tool.Name(), args, risk)
|
||||
}
|
||||
|
||||
// assessToolRisk 取工具实际风险：优先动态评估（ssh_execute 看命令），否则静态。 // Logan.Li
|
||||
func assessToolRisk(tool tools.Tool, args map[string]interface{}) tools.RiskLevel {
|
||||
if dt, ok := tool.(tools.DynamicRiskTool); ok {
|
||||
return dt.RiskLevelForArgs(args)
|
||||
}
|
||||
return tool.RiskLevel()
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
// builtin.go - 内置只读工具 // Logan.Li
|
||||
// analyze_output：对冗长命令输出做摘要/错误提取，避免 token 爆炸，辅助 LLM 聚焦关键线索。
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// AnalyzeOutputTool 输出分析工具（只读，Safe） // Logan.Li
|
||||
type AnalyzeOutputTool struct{}
|
||||
|
||||
// NewAnalyzeOutputTool 创建输出分析工具 // Logan.Li
|
||||
func NewAnalyzeOutputTool() *AnalyzeOutputTool { return &AnalyzeOutputTool{} }
|
||||
|
||||
// Name 工具名 // Logan.Li
|
||||
func (t *AnalyzeOutputTool) Name() string { return "analyze_output" }
|
||||
|
||||
// Description 给 LLM 的说明 // Logan.Li
|
||||
func (t *AnalyzeOutputTool) Description() string {
|
||||
return "分析一段（可能很长的）命令输出文本：统计行数、提取疑似错误/告警行、必要时截断保留首尾。" +
|
||||
"当 ssh_execute 返回内容过长时调用此工具提炼关键信息再继续推理。"
|
||||
}
|
||||
|
||||
// Parameters 参数定义 // Logan.Li
|
||||
func (t *AnalyzeOutputTool) Parameters() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"output": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "待分析的文本输出",
|
||||
},
|
||||
"focus": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选关注点，如 error、memory、disk",
|
||||
},
|
||||
},
|
||||
"required": []string{"output"},
|
||||
}
|
||||
}
|
||||
|
||||
// RiskLevel 静态风险（只读安全） // Logan.Li
|
||||
func (t *AnalyzeOutputTool) RiskLevel() RiskLevel { return RiskSafe }
|
||||
|
||||
// Execute 执行输出分析 // Logan.Li
|
||||
func (t *AnalyzeOutputTool) Execute(ctx context.Context, args map[string]interface{}) (*Result, error) {
|
||||
output := StringParam(args, "output")
|
||||
focus := strings.ToLower(StringParam(args, "focus"))
|
||||
if output == "" {
|
||||
return &Result{Success: true, Output: "（空输出）"}, nil
|
||||
}
|
||||
|
||||
lines := strings.Split(output, "\n")
|
||||
total := len(lines)
|
||||
|
||||
// 超长截断：保留前 40 + 后 40 行，中间用省略标注
|
||||
truncated := false
|
||||
if total > 120 {
|
||||
head := lines[:40]
|
||||
tail := lines[total-40:]
|
||||
lines = append(append(head, fmt.Sprintf("... [已省略 %d 行] ...", total-80)), tail...)
|
||||
truncated = true
|
||||
}
|
||||
|
||||
// 提取疑似错误/告警行
|
||||
errorKeywords := []string{"error", "fail", "exception", "traceback", "denied",
|
||||
"permission", "timeout", "refused", "unavailable", "critical", "fatal",
|
||||
"错误", "失败", "拒绝", "超时", "无法", "异常"}
|
||||
if focus != "" {
|
||||
errorKeywords = append([]string{focus}, errorKeywords...)
|
||||
}
|
||||
var errorLines []string
|
||||
for _, line := range lines {
|
||||
low := strings.ToLower(line)
|
||||
for _, kw := range errorKeywords {
|
||||
if strings.Contains(low, kw) {
|
||||
errorLines = append(errorLines, strings.TrimSpace(line))
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(errorLines) > 20 {
|
||||
errorLines = errorLines[:20]
|
||||
}
|
||||
|
||||
// 组装分析摘要
|
||||
var sb strings.Builder
|
||||
sb.WriteString(fmt.Sprintf("总行数: %d", total))
|
||||
if truncated {
|
||||
sb.WriteString("（已截断保留首尾）")
|
||||
}
|
||||
sb.WriteString("\n")
|
||||
if len(errorLines) > 0 {
|
||||
sb.WriteString(fmt.Sprintf("疑似错误/告警行 (%d):\n", len(errorLines)))
|
||||
for _, l := range errorLines {
|
||||
sb.WriteString(" " + l + "\n")
|
||||
}
|
||||
} else {
|
||||
sb.WriteString("未发现明显错误关键词\n")
|
||||
}
|
||||
sb.WriteString("\n输出片段:\n" + strings.Join(lines, "\n"))
|
||||
|
||||
return &Result{Success: true, Output: sb.String()}, nil
|
||||
}
|
||||
@@ -0,0 +1,169 @@
|
||||
// Package tools 提供 Agent CLI 引擎的工具注册中心与工具接口。 // Logan.Li
|
||||
// 设计参考 opsxcli/internal/agent/tools，剥离 CLI 专属工具（local_bash 本地执行、scp）。
|
||||
// Web 版聚焦远程运维：ssh_execute（目标主机执行）+ analyze_output（输出分析）。
|
||||
// 风险评估逻辑（黑名单 + AssessBashRisk）置于本包，避免与 safety 包形成循环依赖。
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"sync"
|
||||
|
||||
"ezops/pkg/agentcli/llm"
|
||||
)
|
||||
|
||||
// RiskLevel 工具风险等级 // Logan.Li
|
||||
type RiskLevel int
|
||||
|
||||
const (
|
||||
RiskSafe RiskLevel = iota // 只读操作（cat/grep/df/ps）
|
||||
RiskLow // 低风险（mkdir/touch）
|
||||
RiskMedium // 中风险（chmod/文件修改）
|
||||
RiskHigh // 高风险（远程服务控制/reboot）
|
||||
RiskCritical // 危险操作（rm -rf //mkfs/dd）
|
||||
)
|
||||
|
||||
// String 返回风险等级字符串 // Logan.Li
|
||||
func (r RiskLevel) String() string {
|
||||
switch r {
|
||||
case RiskSafe:
|
||||
return "safe"
|
||||
case RiskLow:
|
||||
return "low"
|
||||
case RiskMedium:
|
||||
return "medium"
|
||||
case RiskHigh:
|
||||
return "high"
|
||||
case RiskCritical:
|
||||
return "critical"
|
||||
default:
|
||||
return "unknown"
|
||||
}
|
||||
}
|
||||
|
||||
// Display 返回风险等级中文显示 // Logan.Li
|
||||
func (r RiskLevel) Display() string {
|
||||
switch r {
|
||||
case RiskSafe:
|
||||
return "安全"
|
||||
case RiskLow:
|
||||
return "低风险"
|
||||
case RiskMedium:
|
||||
return "中风险"
|
||||
case RiskHigh:
|
||||
return "高风险"
|
||||
case RiskCritical:
|
||||
return "危险"
|
||||
default:
|
||||
return "未知"
|
||||
}
|
||||
}
|
||||
|
||||
// Result 工具执行结果 // Logan.Li
|
||||
type Result struct {
|
||||
Success bool `json:"success"`
|
||||
Output string `json:"output"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
// Tool 核心工具接口（5 方法） // Logan.Li
|
||||
type Tool interface {
|
||||
Name() string // 工具名
|
||||
Description() string // 给 LLM 看的描述
|
||||
Parameters() map[string]interface{} // JSON Schema 参数定义
|
||||
RiskLevel() RiskLevel // 静态风险等级
|
||||
Execute(ctx context.Context, args map[string]interface{}) (*Result, error)
|
||||
}
|
||||
|
||||
// DynamicRiskTool 动态风险评估接口 // Logan.Li
|
||||
// 工具可额外实现此接口，依据运行时参数动态计算风险（如 ssh_execute 看具体命令）。
|
||||
// 安全控制器 Check 时优先调用此接口。
|
||||
type DynamicRiskTool interface {
|
||||
Tool
|
||||
RiskLevelForArgs(args map[string]interface{}) RiskLevel
|
||||
}
|
||||
|
||||
// Registry 工具注册中心（线程安全） // Logan.Li
|
||||
type Registry struct {
|
||||
tools map[string]Tool
|
||||
mu sync.RWMutex
|
||||
}
|
||||
|
||||
// NewRegistry 创建空注册中心 // Logan.Li
|
||||
func NewRegistry() *Registry {
|
||||
return &Registry{tools: make(map[string]Tool)}
|
||||
}
|
||||
|
||||
// Register 注册工具 // Logan.Li
|
||||
func (r *Registry) Register(tool Tool) {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
r.tools[tool.Name()] = tool
|
||||
}
|
||||
|
||||
// Get 按名获取工具 // Logan.Li
|
||||
func (r *Registry) Get(name string) (Tool, error) {
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
t, ok := r.tools[name]
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("工具未找到: %s", name)
|
||||
}
|
||||
return t, nil
|
||||
}
|
||||
|
||||
// List 列出所有工具 // Logan.Li
|
||||
func (r *Registry) List() []Tool {
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
list := make([]Tool, 0, len(r.tools))
|
||||
for _, t := range r.tools {
|
||||
list = append(list, t)
|
||||
}
|
||||
return list
|
||||
}
|
||||
|
||||
// ToLLMTools 转换为 LLM function calling 格式 // Logan.Li
|
||||
func (r *Registry) ToLLMTools() []llm.Tool {
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
out := make([]llm.Tool, 0, len(r.tools))
|
||||
for _, t := range r.tools {
|
||||
out = append(out, llm.Tool{
|
||||
Type: "function",
|
||||
Function: llm.ToolFunction{
|
||||
Name: t.Name(),
|
||||
Description: t.Description(),
|
||||
Parameters: t.Parameters(),
|
||||
},
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// ---- 参数解析辅助 ---- // Logan.Li
|
||||
|
||||
// StringParam 取字符串参数 // Logan.Li
|
||||
func StringParam(args map[string]interface{}, key string) string {
|
||||
if v, ok := args[key]; ok {
|
||||
if s, ok := v.(string); ok {
|
||||
return s
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// IntParam 取整型参数（兼容 int/float64/int64） // Logan.Li
|
||||
func IntParam(args map[string]interface{}, key string) int {
|
||||
if v, ok := args[key]; ok {
|
||||
switch val := v.(type) {
|
||||
case int:
|
||||
return val
|
||||
case float64:
|
||||
return int(val)
|
||||
case int64:
|
||||
return int(val)
|
||||
}
|
||||
}
|
||||
return 0
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
// risk.go - 命令风险评估（黑名单 + 动态分级） // Logan.Li
|
||||
// 移植自 opsxcli internal/agent/safety/risk.go，置于 tools 包避免与 safety 循环依赖。
|
||||
// 供 ssh_execute 的 DynamicRiskTool.RiskLevelForArgs 调用，决定是否触发用户确认。
|
||||
package tools
|
||||
|
||||
import "strings"
|
||||
|
||||
// dangerousCommands 危险命令黑名单（系统损坏/数据丢失/服务中断） // Logan.Li
|
||||
var dangerousCommands = []string{
|
||||
"rm -rf /", "rm -rf /*", "rm -rf /bin", "rm -rf /boot", "rm -rf /etc",
|
||||
"rm -rf /home", "rm -rf /lib", "rm -rf /lib64", "rm -rf /proc", "rm -rf /root",
|
||||
"rm -rf /sbin", "rm -rf /sys", "rm -rf /usr", "rm -rf /var",
|
||||
"mkfs", "mkfs.ext", "mkfs.xfs", "mkfs.btrfs", "mkfs.vfat",
|
||||
"dd if=/dev/zero", "dd if=/dev/random", "dd if=/dev/urandom",
|
||||
":(){ :|:& };:", ":() { : | : & }; :",
|
||||
"> /dev/sda", "> /dev/sdb", "> /dev/sdc", "> /dev/hda",
|
||||
"mv / /dev/null", "mv /* /dev/null",
|
||||
"chmod -R 000 /", "chmod -R 777 /",
|
||||
"systemctl stop ssh", "systemctl disable ssh", "kill -9 1",
|
||||
"iptables -F", "iptables --flush",
|
||||
}
|
||||
|
||||
// readOnlyCommands 只读命令（安全） // Logan.Li
|
||||
var readOnlyCommands = []string{
|
||||
"cat", "grep", "egrep", "fgrep", "awk", "sed", "head", "tail", "less", "more",
|
||||
"sort", "uniq", "wc", "ps", "top", "df", "du", "free", "uptime", "uname",
|
||||
"hostname", "ifconfig", "ip addr", "ip link", "ip route", "netstat", "ss",
|
||||
"ls", "ll", "pwd", "who", "w", "last", "vmstat", "iostat", "mpstat", "sar",
|
||||
"lsof", "find", "which", "whereis", "file", "stat", "date", "echo", "id",
|
||||
"whoami", "groups", "getent", "dmesg", "systemctl status", "systemctl list-units",
|
||||
"lsblk", "blkid", "mount", "journalctl",
|
||||
}
|
||||
|
||||
// modificationCommands 文件修改命令（低-中风险） // Logan.Li
|
||||
var modificationCommands = []string{
|
||||
"cp", "mv", "mkdir", "rmdir", "touch", "chmod", "chown", "chgrp", "ln",
|
||||
"tar", "gzip", "gunzip", "zip", "unzip", "rsync", "tee",
|
||||
}
|
||||
|
||||
// highRiskCommands 高风险命令（服务控制/删除/重启） // Logan.Li
|
||||
var highRiskCommands = []string{
|
||||
"rm", "dd", "shutdown", "reboot", "halt", "poweroff", "init",
|
||||
"systemctl restart", "systemctl stop", "systemctl start",
|
||||
"kill", "killall", "pkill", "userdel", "groupdel", "fdisk", "parted", "mkfs",
|
||||
}
|
||||
|
||||
// IsDangerousCommand 检查命令是否命中黑名单 // Logan.Li
|
||||
// 返回 (是否危险, 命中的模式)。
|
||||
func IsDangerousCommand(command string) (bool, string) {
|
||||
trimmed := strings.TrimSpace(command)
|
||||
if trimmed == "" {
|
||||
return false, ""
|
||||
}
|
||||
lower := strings.ToLower(trimmed)
|
||||
for _, d := range dangerousCommands {
|
||||
if strings.Contains(lower, strings.ToLower(d)) {
|
||||
return true, d
|
||||
}
|
||||
}
|
||||
// rm -rf + 根目录路径特殊检测
|
||||
if strings.HasPrefix(lower, "rm") && strings.Contains(lower, "-rf") && containsRootPath(lower) {
|
||||
return true, "rm -rf 包含根目录路径"
|
||||
}
|
||||
return false, ""
|
||||
}
|
||||
|
||||
// containsRootPath 检测是否含系统根目录路径 // Logan.Li
|
||||
func containsRootPath(cmd string) bool {
|
||||
paths := []string{" /boot", " /etc", " /usr", " /var", " /lib", " /lib64",
|
||||
" /sbin", " /bin", " /opt", " /home", " /root", " /tmp", " /var/log"}
|
||||
for _, p := range paths {
|
||||
if strings.Contains(cmd, p) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// AssessBashRisk 动态评估命令风险等级 // Logan.Li
|
||||
// 黑名单→Critical；纯只读→Safe；组合命令取最高；sudo 提升。
|
||||
func AssessBashRisk(command string) RiskLevel {
|
||||
trimmed := strings.TrimSpace(command)
|
||||
if trimmed == "" {
|
||||
return RiskSafe
|
||||
}
|
||||
lower := strings.ToLower(trimmed)
|
||||
|
||||
if isDangerous, _ := IsDangerousCommand(command); isDangerous {
|
||||
return RiskCritical
|
||||
}
|
||||
if isReadOnlyCommand(lower) {
|
||||
return RiskSafe
|
||||
}
|
||||
if strings.Contains(lower, "&&") || strings.Contains(lower, "||") ||
|
||||
strings.Contains(lower, "|") || strings.Contains(lower, ";") {
|
||||
return assessCompoundCommand(lower)
|
||||
}
|
||||
isSudo := strings.HasPrefix(lower, "sudo ")
|
||||
return assessSingleCommand(strings.TrimPrefix(lower, "sudo "), isSudo)
|
||||
}
|
||||
|
||||
// isReadOnlyCommand 是否纯只读命令 // Logan.Li
|
||||
func isReadOnlyCommand(cmd string) bool {
|
||||
cmd = strings.TrimPrefix(cmd, "sudo ")
|
||||
cmd = strings.TrimSpace(cmd)
|
||||
for _, ro := range readOnlyCommands {
|
||||
if strings.HasPrefix(cmd, strings.ToLower(ro)) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// assessCompoundCommand 组合命令取子命令最高风险 // Logan.Li
|
||||
func assessCompoundCommand(cmd string) RiskLevel {
|
||||
maxRisk := RiskSafe
|
||||
parts := []string{cmd}
|
||||
for _, sep := range []string{"&&", "||", "|", ";"} {
|
||||
var next []string
|
||||
for _, p := range parts {
|
||||
for _, sp := range strings.Split(p, sep) {
|
||||
sp = strings.TrimSpace(sp)
|
||||
if sp != "" {
|
||||
next = append(next, sp)
|
||||
}
|
||||
}
|
||||
}
|
||||
parts = next
|
||||
}
|
||||
for _, p := range parts {
|
||||
if r := assessSingleCommand(strings.TrimPrefix(p, "sudo "), false); r > maxRisk {
|
||||
maxRisk = r
|
||||
}
|
||||
}
|
||||
if strings.HasPrefix(cmd, "sudo ") && maxRisk < RiskCritical {
|
||||
maxRisk++
|
||||
}
|
||||
return maxRisk
|
||||
}
|
||||
|
||||
// assessSingleCommand 单命令风险（按前缀分类） // Logan.Li
|
||||
func assessSingleCommand(cmd string, isSudo bool) RiskLevel {
|
||||
cmd = strings.TrimSpace(cmd)
|
||||
fields := strings.Fields(cmd)
|
||||
if len(fields) == 0 {
|
||||
return RiskSafe
|
||||
}
|
||||
main := strings.ToLower(fields[0])
|
||||
|
||||
for _, h := range highRiskCommands {
|
||||
if main == strings.ToLower(h) || strings.HasPrefix(main, strings.ToLower(h)) {
|
||||
if isSudo {
|
||||
return RiskHigh
|
||||
}
|
||||
return RiskMedium
|
||||
}
|
||||
}
|
||||
for _, m := range modificationCommands {
|
||||
if main == strings.ToLower(m) {
|
||||
if isSudo {
|
||||
return RiskMedium
|
||||
}
|
||||
return RiskLow
|
||||
}
|
||||
}
|
||||
if isSudo {
|
||||
return RiskMedium
|
||||
}
|
||||
return RiskLow
|
||||
}
|
||||
@@ -0,0 +1,100 @@
|
||||
// ssh_execute.go - 远程命令执行工具 // Logan.Li
|
||||
// 复用 aiops 既有 pkg/remoteexec（Go 原生 SSH），凭据由 controller 从 model.Server 构建后注入。
|
||||
// 实现 DynamicRiskTool：依据具体命令动态评估风险，决定是否触发用户确认。
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"ezops/pkg/remoteexec"
|
||||
)
|
||||
|
||||
// SSHExecuteTool 远程命令执行工具 // Logan.Li
|
||||
type SSHExecuteTool struct {
|
||||
cfg remoteexec.SSHConfig // 目标主机连接配置（含凭据）
|
||||
timeout time.Duration // 默认命令超时
|
||||
}
|
||||
|
||||
// NewSSHExecuteTool 创建远程执行工具 // Logan.Li
|
||||
func NewSSHExecuteTool(cfg remoteexec.SSHConfig, timeout time.Duration) *SSHExecuteTool {
|
||||
if timeout <= 0 {
|
||||
timeout = 60 * time.Second
|
||||
}
|
||||
return &SSHExecuteTool{cfg: cfg, timeout: timeout}
|
||||
}
|
||||
|
||||
// Name 工具名 // Logan.Li
|
||||
func (t *SSHExecuteTool) Name() string { return "ssh_execute" }
|
||||
|
||||
// Description 给 LLM 的工具说明 // Logan.Li
|
||||
func (t *SSHExecuteTool) Description() string {
|
||||
host := t.cfg.Host
|
||||
if host == "" {
|
||||
host = "目标主机"
|
||||
}
|
||||
return fmt.Sprintf(
|
||||
"在远程服务器 %s（用户 %s）上执行 shell 命令并返回合并的 stdout+stderr 输出与退出码。"+
|
||||
"用于排障（查看日志/进程/磁盘/网络）、安装与配置软件、重启服务等。"+
|
||||
"高危命令（rm -rf /、mkfs、reboot 等）需用户确认。", host, t.cfg.User)
|
||||
}
|
||||
|
||||
// Parameters JSON Schema 参数定义 // Logan.Li
|
||||
func (t *SSHExecuteTool) Parameters() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"command": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "要执行的 shell 命令，例如 df -h、systemctl status nginx、tail -n 100 /var/log/messages",
|
||||
},
|
||||
"timeout": map[string]interface{}{
|
||||
"type": "integer",
|
||||
"description": "命令超时秒数（默认 60）",
|
||||
},
|
||||
},
|
||||
"required": []string{"command"},
|
||||
}
|
||||
}
|
||||
|
||||
// RiskLevel 静态风险等级（高危） // Logan.Li
|
||||
func (t *SSHExecuteTool) RiskLevel() RiskLevel { return RiskHigh }
|
||||
|
||||
// RiskLevelForArgs 依据命令动态评估风险 // Logan.Li
|
||||
func (t *SSHExecuteTool) RiskLevelForArgs(args map[string]interface{}) RiskLevel {
|
||||
return AssessBashRisk(StringParam(args, "command"))
|
||||
}
|
||||
|
||||
// Execute 执行远程命令 // Logan.Li
|
||||
func (t *SSHExecuteTool) Execute(ctx context.Context, args map[string]interface{}) (*Result, error) {
|
||||
command := strings.TrimSpace(StringParam(args, "command"))
|
||||
if command == "" {
|
||||
return &Result{Success: false, Error: "参数 command 不能为空"}, nil
|
||||
}
|
||||
|
||||
timeout := t.timeout
|
||||
if sec := IntParam(args, "timeout"); sec > 0 {
|
||||
timeout = time.Duration(sec) * time.Second
|
||||
}
|
||||
|
||||
res, err := remoteexec.Exec(t.cfg, command, timeout)
|
||||
if err != nil {
|
||||
// 连接级失败（无法 SSH）
|
||||
return &Result{Success: false, Error: fmt.Sprintf("SSH 连接失败: %v", err)}, nil
|
||||
}
|
||||
|
||||
// 附带退出码，便于 agent 判断命令是否成功（排障关键信号）
|
||||
output := res.Output
|
||||
if !strings.HasSuffix(output, "\n") && output != "" {
|
||||
output += "\n"
|
||||
}
|
||||
output += fmt.Sprintf("[exit_code=%d]", res.ExitCode)
|
||||
|
||||
return &Result{
|
||||
Success: res.Success, // exit_code==0
|
||||
Output: output,
|
||||
Error: res.Error,
|
||||
}, nil
|
||||
}
|
||||
@@ -154,6 +154,8 @@ func AutoMigrate(db *gorm.DB) error {
|
||||
&model.HealthProbe{}, // 健康探针配置 // Logan.Li
|
||||
&model.ApprovalWorkflow{}, // 审批流程定义 // Logan.Li
|
||||
&model.ApprovalWorkflowStep{}, // 审批流程步骤 // Logan.Li
|
||||
&model.AgentCLISession{}, // Agent CLI 任务会话 // Logan.Li
|
||||
&model.AgentCLIMessage{}, // Agent CLI 推理消息 // Logan.Li
|
||||
}
|
||||
|
||||
var lastErr error
|
||||
|
||||
@@ -887,6 +887,16 @@ func Register(r *gin.Engine, db *gorm.DB, log *zap.Logger, cfg *config.Config, c
|
||||
}
|
||||
|
||||
// 指标浏览器 — 监控指标元数据 + 时序查询 // Logan.Li
|
||||
// Agent CLI — AI 运维 Agent（WebSocket 推流 + 会话历史回放） // Logan.Li
|
||||
agentCLIHandler := controller.NewAgentCLIHandler(db)
|
||||
r.GET("/ws/agent-cli", middleware.JWTAuth(&cfg.JWT, db), agentCLIHandler.Run)
|
||||
agentCLIGroup := authorized.Group("/aiops/agent-cli")
|
||||
{
|
||||
agentCLIGroup.GET("/sessions", agentCLIHandler.ListSessions)
|
||||
agentCLIGroup.GET("/sessions/:id", agentCLIHandler.GetSession)
|
||||
agentCLIGroup.DELETE("/sessions/:id", agentCLIHandler.DeleteSession)
|
||||
}
|
||||
|
||||
metricsHandler := controller.NewMetricsHandler(db)
|
||||
metricsGroup := authorized.Group("/metrics")
|
||||
{
|
||||
|
||||
@@ -172,6 +172,8 @@ func SeedData(db *gorm.DB) {
|
||||
{Name: "智能助手", Code: "aiops:assistant", Type: "menu", Sort: 60, Status: 1},
|
||||
{Name: "告警分析", Code: "aiops:analysis", Type: "menu", Sort: 61, Status: 1},
|
||||
{Name: "容量预测", Code: "aiops:forecast", Type: "menu", Sort: 62, Status: 1},
|
||||
{Name: "Agent CLI", Code: "aiops:agent-cli", Type: "menu", Sort: 63, Status: 1},
|
||||
{Name: "大模型设置", Code: "aiops:llm-config", Type: "menu", Sort: 64, Status: 1},
|
||||
// 资源申请
|
||||
{Name: "资源申请", Code: "approval:apply", Type: "menu", Sort: 70, Status: 1},
|
||||
{Name: "审批管理", Code: "approval:manage", Type: "button", Sort: 71, Status: 1},
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# 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
|
||||
@@ -0,0 +1,230 @@
|
||||
# 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
|
||||
@@ -0,0 +1,303 @@
|
||||
# 02 - 整体架构设计
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。
|
||||
> opsxcli 的「cmd/ + plugins/ + internal/」CLI 三层在 aiops 中改造为「controller/（HTTP/WS handler）+ model/（GORM）+ pkg/agentcli/（引擎库）+ frontend/（React UI）」四层。
|
||||
|
||||
## 项目结构（Agent CLI 相关部分）
|
||||
|
||||
```
|
||||
aiops/
|
||||
├── backend/
|
||||
│ ├── controller/
|
||||
│ │ └── agent_cli.go # WebSocket 控制器（HTTP/WS handler 层）
|
||||
│ │ # - /ws/agent-cli?id=<serverID> 入口
|
||||
│ │ # - 构建 Engine、注入回调、事件落库
|
||||
│ │ # - ListSessions/GetSession/DeleteSession REST
|
||||
│ ├── model/
|
||||
│ │ ├── agent_cli.go # AgentCLISession / AgentCLIMessage（GORM 模型）
|
||||
│ │ └── llm.go # LLMConfig（ai_llm_configs 表）
|
||||
│ ├── pkg/
|
||||
│ │ ├── agentcli/ # Agent 引擎库（零业务依赖，核心）
|
||||
│ │ │ ├── agentcli.go # Engine 顶层入口
|
||||
│ │ │ ├── core/ # ReAct 主循环 + EventCallback
|
||||
│ │ │ ├── tools/ # Registry + ssh_execute + analyze_output + risk
|
||||
│ │ │ ├── safety/ # 安全控制器（ConfirmFn 注入）
|
||||
│ │ │ ├── prompt/ # 五层 System Prompt
|
||||
│ │ │ ├── evolver/ # 四层记忆 + 精简进化循环
|
||||
│ │ │ └── llm/ # OpenAI 兼容客户端 + 类型定义
|
||||
│ │ └── remoteexec/ # 复用 aiops 既有 Go-native SSH
|
||||
│ └── router/routes.go # 路由注册：WS + REST 会话管理
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── components/aiops/AgentCLI.tsx # React 对话流组件
|
||||
│ │ ├── api/agentCli.ts # 会话历史 REST 客户端
|
||||
│ │ └── components/ui/confirm-dialog.tsx# useConfirm() 高危确认
|
||||
│ └── ...
|
||||
│
|
||||
└── data/agentcli/ # Evolver 记忆目录（运行时生成）
|
||||
├── experience.jsonl # 经验记忆
|
||||
├── factual.jsonl # 事实记忆
|
||||
├── procedural.jsonl # 程序记忆（接口位）
|
||||
└── environment.json # 环境记忆（已知主机）
|
||||
```
|
||||
|
||||
## 架构设计原则
|
||||
|
||||
### 1. 分层 + 依赖注入
|
||||
|
||||
aiops Agent CLI 的核心约束是「引擎库零业务依赖」：
|
||||
|
||||
- **controller 层** —— 负责协议适配（WebSocket）、凭据构建、事件持久化、用户隔离
|
||||
- **model 层** —— GORM 模型（会话、消息、LLM 配置、Server）
|
||||
- **pkg/agentcli 层** —— 纯算法库，只依赖 `pkg/remoteexec` 和自己的子包，**不 import model/controller**
|
||||
- **frontend 层** —— React 对话流 UI，纯事件消费 + 控制消息发送
|
||||
|
||||
依赖通过函数参数注入：
|
||||
|
||||
```go
|
||||
// controller/agent_cli.go 关键注入点
|
||||
engine.SetCallback(ac.onEvent) // EventCallback：推 WS + 落库
|
||||
engine.SetConfirmFn(ac.confirmFn) // ConfirmFn：高危确认（阻塞等前端回传）
|
||||
```
|
||||
|
||||
引擎因此可被任何调度方复用（不仅是 WebSocket，未来也可被 cron 或审批流调用）。
|
||||
|
||||
### 2. 工具化设计
|
||||
|
||||
每个工具都是独立的 struct，实现 `Tool` 接口即可注册：
|
||||
|
||||
```
|
||||
pkg/agentcli/tools/
|
||||
├── registry.go # Registry（线程安全） + Tool/DynamicRiskTool 接口 + RiskLevel
|
||||
├── ssh_execute.go # 远程命令执行（DynamicRiskTool）
|
||||
├── builtin.go # analyze_output（只读 Safe）
|
||||
└── risk.go # 黑名单 + AssessBashRisk 动态评估
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 把风险评估放在 `safety/` 包，aiops 为避免 `tools` ↔ `safety` 循环依赖，把 `risk.go` 置于 `tools` 包，由 `ssh_execute` 直接调用。
|
||||
|
||||
### 3. 配置集中化（DB 驱动）
|
||||
|
||||
opsxcli 通过 `~/.opsxcli/config.yaml` 和环境变量加载配置；aiops 配置来自 DB：
|
||||
|
||||
| 配置项 | opsxcli | aiops |
|
||||
|--------|---------|-------|
|
||||
| LLM 配置 | `~/.opsxcli/providers/*.json` | DB 表 `ai_llm_configs`（model.LLMConfig） |
|
||||
| LLM 配置入口 | CLI 向导 `wizard.go` | 「大模型设置」Web 页面 |
|
||||
| SSH 凭据 | `~/.ssh/config` 解析 | model.Server 关联凭证系统 v2 |
|
||||
| 引擎运行参数 | config.yaml + 环境变量 | `core.DefaultConfig()`（硬编码默认，必要时通过 EngineConfig 覆盖） |
|
||||
| 记忆目录 | `~/.opsxcli/agent/` | 工作目录 `data/agentcli/`（容器化友好） |
|
||||
|
||||
### 4. 协议适配层（controller）
|
||||
|
||||
controller 是「Web 世界」与「引擎世界」的翻译器：
|
||||
|
||||
| Web 协议 | 引擎调用 | 引擎事件 → Web |
|
||||
|----------|----------|----------------|
|
||||
| `WS start {query}` | `engine.Run(ctx, query, serverInfo)` | emit `thought`/`tool_call`/`tool_result`/`progress`/`done`/`error` → 序列化为 `wsEvent` 推 WS |
|
||||
| `WS confirm/deny {confirm_id}` | 解锁 `ConfirmFn` 的 chan | emit 前由 controller 推 `confirm` 事件 |
|
||||
| `WS abort` | `cancel()` 取消 ctx | emit `error`（ctx.Err()） |
|
||||
| `GET /sessions` | — | 直接查 `agent_cli_sessions` 表 |
|
||||
|
||||
---
|
||||
|
||||
## 核心流程图
|
||||
|
||||
### WebSocket 握手 + 任务执行完整流程
|
||||
|
||||
以用户在 Agent CLI 页面输入「检查 nginx 启动失败的原因」为例：
|
||||
|
||||
```
|
||||
用户在 Agent CLI 页面选择主机、输入任务 "检查 nginx 启动失败的原因"
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 1. WebSocket 握手 (controller/agent_cli.go: Run) │
|
||||
│ ├─ 校验 JWT (middleware.JWTAuth) │
|
||||
│ ├─ 加载 model.Server (按 ?id=) │
|
||||
│ ├─ buildSSHConfig: 解析凭证系统 v2 凭据 │
|
||||
│ ├─ 加载 model.LLMConfig (Enabled=true) │
|
||||
│ └─ upgrader.Upgrade 升级 WS │
|
||||
└────────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 2. 推送 session 事件（主机上下文） │
|
||||
│ wsEvent{type:"session", message:"已连接主机…"}│
|
||||
└────────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼ (前端发来 {type:"start", query:"..."})
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 3. startTask │
|
||||
│ ├─ DB 创建 AgentCLISession (status=running) │
|
||||
│ ├─ DB 存用户消息 (role=user) │
|
||||
│ ├─ 构建 Engine (注入 LLM/SSH/SafetyMode) │
|
||||
│ ├─ engine.SetCallback(ac.onEvent) │
|
||||
│ ├─ engine.SetConfirmFn(ac.confirmFn) │
|
||||
│ └─ go engine.Run(ctx, query, serverInfo) │
|
||||
└────────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 4. Engine.Run → core.Agent.Run（ReAct 循环） │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────┐ │
|
||||
│ │ Prompt 构建（五层） │ │
|
||||
│ │ L1 角色 / L2 安全 / L3 工具 │ │
|
||||
│ │ L4 工作方式 / L5 Evolver 记忆 │ │
|
||||
│ └──────────────┬────────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────────────────────┐ │
|
||||
│ │ for iter := 0; iter < 16; iter++ { │ │
|
||||
│ │ emit progress(round) │ │
|
||||
│ │ 自适应检查点（iter 3/7/11） │ │
|
||||
│ │ trimMessages(裁剪历史) │ │
|
||||
│ │ resp = llm.Complete(...) │ │
|
||||
│ │ emit thought(resp.Content) │ │
|
||||
│ │ if 无 tool_calls: │ │
|
||||
│ │ emit done → triggerEvolve │ │
|
||||
│ │ return │ │
|
||||
│ │ for tc in resp.ToolCalls: │ │
|
||||
│ │ risk = toolRisk(...) │ │
|
||||
│ │ emit tool_call(name,args,risk) │ │
|
||||
│ │ approved = safetyCtl.Check(..)│ ←──┐ │
|
||||
│ │ if !approved: 跳过 │ │ 高危 │
|
||||
│ │ result = tool.Execute(ctx,args)│ │ 触发 │
|
||||
│ │ emit tool_result(output,...) │ │ confirm │
|
||||
│ │ records.append(..) │ │ 事件 │
|
||||
│ │ } │ │ │
|
||||
│ │ 循环检测 / 连续失败追踪 │ │ │
|
||||
│ │ } │ │ │
|
||||
│ └────────────────────────────────────┘ │ │
|
||||
└──────────────────────────────────────────┘ │ │
|
||||
│ │
|
||||
┌───────────────────────────┐
|
||||
│ confirmFn (controller) │
|
||||
│ 推 wsEvent{type:"confirm"}│
|
||||
│ ch := make(chan bool) │
|
||||
│ select { │
|
||||
│ case approved := <-ch: │
|
||||
│ case <-5min超时: │
|
||||
│ } │
|
||||
└─────────┬─────────────────┘
|
||||
│ 前端 useConfirm() 弹框
|
||||
│ 发回 {type:"confirm"/"deny"}
|
||||
▼
|
||||
resolveConfirm(confirmID, approved)
|
||||
│ ch <- approved
|
||||
▼ 解锁 safety.Check
|
||||
```
|
||||
|
||||
### 事件落库映射
|
||||
|
||||
`onEvent` 回调把每个事件同时推送 WS 与落库 `agent_cli_messages`：
|
||||
|
||||
| Event.Type | DB 字段 type | DB 字段 role | 备注 |
|
||||
|------------|--------------|--------------|------|
|
||||
| `thought` | thought | assistant | AI 思考文本 |
|
||||
| `tool_call` | tool_call | tool | 含工具名、参数 JSON、风险等级 |
|
||||
| `tool_result` | tool_result | tool | 含输出、成败、耗时 |
|
||||
| `done` | done | assistant | 最终答案 + token 统计 |
|
||||
| `error` | error | assistant | 错误信息（含达到最大轮次） |
|
||||
| `progress` | — | — | 太频繁，不入库 |
|
||||
|
||||
### 系统数据流
|
||||
|
||||
```
|
||||
┌────── controller 层（协议适配） ──────┐
|
||||
│ agent_cli.go (WS handler) │
|
||||
│ ├─ 加载 Server/LLMConfig │
|
||||
│ ├─ DB 创建 Session/Message │
|
||||
│ └─ 注入 Callback/ConfirmFn │
|
||||
└─────────────────┬─────────────────────┘
|
||||
│ 依赖注入
|
||||
▼
|
||||
┌────── pkg/agentcli 层（引擎库） ──────┐
|
||||
│ agentcli.go (Engine) │
|
||||
│ ├─ core.Agent (ReAct) │
|
||||
│ │ ├─ llm.Client (OpenAI 兼容) │
|
||||
│ │ ├─ tools.Registry │
|
||||
│ │ │ ├─ ssh_execute │
|
||||
│ │ │ └─ analyze_output │
|
||||
│ │ ├─ safety.Controller │
|
||||
│ │ ├─ prompt.BuildSystemPrompt │
|
||||
│ │ └─ evolver.EvolverEngine │
|
||||
│ └─ (零 model/controller 依赖) │
|
||||
└─────────────────┬─────────────────────┘
|
||||
│ 调用
|
||||
▼
|
||||
┌────── pkg/remoteexec（Go-native SSH）─┐
|
||||
│ Exec(cfg, command, timeout) │
|
||||
└───────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层 | 技术 |
|
||||
|----|------|
|
||||
| 后端框架 | Gin + GORM + gorilla/websocket |
|
||||
| LLM 协议 | OpenAI 兼容 `/chat/completions` + function calling |
|
||||
| SSH | aiops 既有 `pkg/remoteexec`（Go-native，无外部依赖） |
|
||||
| 前端 | React 19 + TypeScript + shadcn/ui（`useConfirm` 弹框） |
|
||||
| 持久化 | MySQL（主库）/ SQLite（降级） —— 复用 aiops 既有 DB |
|
||||
| 记忆存储 | 文件 `data/agentcli/*.jsonl`（与 opsxcli 原生一致，零 DB 依赖） |
|
||||
|
||||
> 为什么记忆用文件而会话用 DB？记忆是引擎库内部的产物（学习沉淀），与业务无关；会话需要多用户隔离、列表查询、删除等业务操作，必须走 DB。这是「引擎库零业务依赖」原则的延伸。
|
||||
|
||||
## 路由注册
|
||||
|
||||
`backend/router/routes.go`：
|
||||
|
||||
```go
|
||||
// Agent CLI — AI 运维 Agent（WebSocket 推流 + 会话历史回放）
|
||||
agentCLIHandler := controller.NewAgentCLIHandler(db)
|
||||
r.GET("/ws/agent-cli", middleware.JWTAuth(&cfg.JWT, db), agentCLIHandler.Run)
|
||||
|
||||
agentCLIGroup := authorized.Group("/aiops/agent-cli")
|
||||
{
|
||||
agentCLIGroup.GET("/sessions", agentCLIHandler.ListSessions)
|
||||
agentCLIGroup.GET("/sessions/:id", agentCLIHandler.GetSession)
|
||||
agentCLIGroup.DELETE("/sessions/:id", agentCLIHandler.DeleteSession)
|
||||
}
|
||||
```
|
||||
|
||||
WebSocket 因无法设自定义 header，JWT 通过 `?token=` query param 由 `JWTAuth` 中间件兼容解析。
|
||||
|
||||
## 添加新模块示例
|
||||
|
||||
以「增加一个新工具 `ping_check`」为例：
|
||||
|
||||
1. **实现 Tool 接口**（`pkg/agentcli/tools/ping_check.go`）：
|
||||
|
||||
```go
|
||||
type PingCheckTool struct{ cfg remoteexec.SSHConfig }
|
||||
|
||||
func (t *PingCheckTool) Name() string { return "ping_check" }
|
||||
func (t *PingCheckTool) Description() string { return "在目标主机 ping 指定地址" }
|
||||
func (t *PingCheckTool) Parameters() map[string]interface{} { /* JSON Schema */ }
|
||||
func (t *PingCheckTool) RiskLevel() tools.RiskLevel { return tools.RiskSafe }
|
||||
func (t *PingCheckTool) Execute(ctx context.Context, args map[string]interface{}) (*tools.Result, error) {
|
||||
// 调用 remoteexec.Exec 执行 ping
|
||||
}
|
||||
```
|
||||
|
||||
2. **在 Engine 中注册**（`pkg/agentcli/agentcli.go: NewEngine`）：
|
||||
|
||||
```go
|
||||
registry.Register(tools.NewSSHExecuteTool(cfg.SSH, coreCfg.ToolTimeout))
|
||||
registry.Register(tools.NewAnalyzeOutputTool())
|
||||
registry.Register(tools.NewPingCheckTool(cfg.SSH)) // 新增
|
||||
```
|
||||
|
||||
3. 工具自动出现在 LLM 的 `tools` 参数中（`registry.ToLLMTools()`），Prompt Layer 3 工具描述自动生成（`buildToolDescriptions()`）。无需改 Prompt、无需改 controller、无需改前端。
|
||||
|
||||
## 设计目标
|
||||
|
||||
1. **Web 友好**：所有交互经 WebSocket，适配浏览器对话流
|
||||
2. **零业务耦合**：引擎库可独立测试与复用
|
||||
3. **复用 aiops 既有能力**：LLM 配置、SSH、凭证系统、DB
|
||||
4. **易于扩展**：Tool 接口 + Registry，实现接口即扩展
|
||||
5. **可审计**：每条事件落库，会话历史可回放
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,276 @@
|
||||
# 03 - Harness 工程化与反馈回路
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。
|
||||
> Harness Engineering 是与具体语言/形态无关的理论框架，原文的思想性内容（控制论、Steering Loop、四类调节 Harness）几乎完全保留；落地实例部分从「opsxcli CLI + golangci-lint」改写为「aiops 后端库 + WebSocket 反馈回路 + Evolver 自进化」。
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心定义：Agent = Model + Harness
|
||||
|
||||
### 1.1 什么是 Harness
|
||||
|
||||
> **Agent = Model + Harness** — LangChain
|
||||
|
||||
Harness 是 Agent 中除 Model 本身之外的一切。在大模型运维 Agent 的有界上下文中，Harness 分为两个层次：
|
||||
|
||||
- **内置 Harness（built-in harness）**：引擎作者构建的部分 —— System Prompt、工具注册机制、ReAct 编排循环
|
||||
- **外部 Harness（outer harness）**：业务方为自身场景构建的部分 —— 安全模式、确认机制、记忆注入、审计落库
|
||||
|
||||
Model 是「大脑」，Harness 是「身体 + 环境 + 工具 + 规则」。大脑决定智能，但身体和环境决定智能能否被正确、可靠、持续地发挥。
|
||||
|
||||
### 1.2 两个目标
|
||||
|
||||
> 一个构建良好的 Harness 服务于两个目标：
|
||||
> 1. **提高智能体首次就做对的概率**（feedforward）
|
||||
> 2. **提供反馈回路，在问题到达人类前尽可能自我纠正**（feedback）
|
||||
> — Martin Fowler / Birgitta Böckeler
|
||||
|
||||
这两个目标分别对应**前馈指导**和**反馈传感器**，是 Harness 的双引擎。
|
||||
|
||||
### 1.3 核心理念
|
||||
|
||||
> **Humans steer. Agents execute.** — OpenAI
|
||||
|
||||
人类的工作重心从「敲每一条命令」，转向**设计环境、明确意图和构建反馈回路**。在 aiops Agent CLI 中，运维人员的角色从「亲自 SSH 排障」变为「在 Web 上描述任务、审阅高危确认、监督 Agent 执行」。
|
||||
|
||||
---
|
||||
|
||||
## 2. 控制论基础：前馈与反馈
|
||||
|
||||
### 2.1 前馈指导 vs 反馈传感器
|
||||
|
||||
| 维度 | 前馈指导（Feedforward Guides） | 反馈传感器（Feedback Sensors） |
|
||||
|------|-------------------------------|-------------------------------|
|
||||
| **时机** | 智能体行动**之前** | 智能体行动**之后** |
|
||||
| **目的** | 预期行为并加以引导 | 观察产出并帮助自我纠正 |
|
||||
| **效果** | 提高首次做对的概率 | 在问题到达人类前自我纠正 |
|
||||
| **aiops 实例** | 五层 System Prompt、工具描述、安全规则文本 | 安全 Check 拦截、循环检测、连续失败追踪、自适应检查点 |
|
||||
|
||||
> 仅有前馈，规则永远无法验证是否奏效；仅有反馈，智能体会重复同样的错误。两者缺一不可。
|
||||
|
||||
### 2.2 计算型 vs 推理型
|
||||
|
||||
| 类型 | 特点 | 例子 |
|
||||
|------|------|------|
|
||||
| **计算型（Computational）** | 确定性、快速、CPU 执行 | 黑名单匹配、命令风险分级、循环检测、token 估算 |
|
||||
| **推理型（Inferential）** | 语义分析、AI 审查、LLM 调用 | Evolver 用 LLM 提炼经验、LLM 决定下一步工具 |
|
||||
|
||||
计算型传感器成本低、速度快，适合每次工具调用都运行（如 `safety.Controller.Check`、`AssessBashRisk`）。推理型传感器更强大但更贵、不确定，适合关键节点（如任务完成后的经验提炼）。
|
||||
|
||||
推理型传感器的特别威力：当反馈信号被优化为 LLM 可消费的格式时（如把「连续失败」翻译为「请换一种思路」的中文提示注入对话），形成一种**积极的 prompt injection** —— 这正是 aiops 自适应检查点的设计依据。
|
||||
|
||||
### 2.3 Steering Loop 掌舵循环
|
||||
|
||||
Steering Loop 是 Harness Engineering 的元过程 —— 通过迭代改进 Harness 来引导智能体。
|
||||
|
||||
```
|
||||
┌──────────┐ Agent 工作 ┌──────────┐ 系统改进 ┌──────────┐
|
||||
│ Harness │ ──────────► │ 观察问题 │ ──────────► │ 更新Harness│
|
||||
│ (当前版本) │ │(多次发生) │ │ (新版本) │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
▲ │
|
||||
└────────────────────────────────────────────────────┘
|
||||
循环往复
|
||||
```
|
||||
|
||||
在 aiops Agent CLI 中，Steering Loop 有两种实现：
|
||||
|
||||
1. **人工 Steering**：管理员在「大模型设置」调整 SystemPrompt、温度等 → 影响 Agent 下次行为
|
||||
2. **自动 Steering**：Evolver 引擎观察任务执行 → 自动学习经验 → 注入下次 Prompt（详见第 08 篇）
|
||||
|
||||
后者是 opsxcli 设计思想的核心延伸 —— 用代码自动化 Steering Loop。
|
||||
|
||||
### 2.4 Keep Quality Left — 把质量左移
|
||||
|
||||
在 aiops Agent CLI 的执行链路中，反馈传感器按成本分布：
|
||||
|
||||
| 阶段 | 应运行的传感器 | 特点 |
|
||||
|------|---------------|------|
|
||||
| **工具执行前** | 黑名单硬拒、`AssessBashRisk` 分级、安全模式阈值 | 毫秒级，每次必跑 |
|
||||
| **工具执行中** | context 超时（`ToolTimeout` 120s 兜底） | 防卡死 |
|
||||
| **轮次间** | 自适应检查点（Round 4/8/12）、循环检测（>3 次拒绝）、连续失败追踪 | 防 LLM 跑偏 |
|
||||
| **任务完成后** | Evolver 异步学习（30s 超时） | 较贵，异步 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 三类调节 Harness
|
||||
|
||||
> Agent Harness 如同一个控制论调节器（governor），通过前馈和反馈将系统调节到期望状态。
|
||||
|
||||
### 3.1 可维护性 Harness（Maintainability）
|
||||
|
||||
- 计算型：文件大小红线（Go handler ≤400 行、组件 ≤700 行）、`go vet`、`tsc --noEmit`
|
||||
- 推理型：代码审查（review）
|
||||
- 在 Agent CLI 代码中体现为「引擎库零业务依赖」「单文件 ≤300 行」等约束
|
||||
|
||||
### 3.2 架构适应度 Harness（Architecture Fitness）
|
||||
|
||||
- 前馈：分层依赖约定（controller → model + pkg/agentcli，引擎库不反向 import）
|
||||
- 反馈：编译失败即拦截（Go 强类型天然传感器）
|
||||
|
||||
### 3.3 行为 Harness（Behaviour）— 本项目的重点
|
||||
|
||||
如何引导和感知 Agent 是否按预期功能运行：
|
||||
|
||||
- 前馈：五层 System Prompt（角色 + 安全规则 + 工作方式 ReAct 范式）
|
||||
- 反馈：
|
||||
- 安全层硬拦截 + 高危确认（防破坏性操作）
|
||||
- ReAct 循环中的自适应检查点（防 LLM 死循环或编造输出）
|
||||
- WebSocket 事件流的可观测性（人类可随时观察思考与命令）
|
||||
- Evolver 经验学习（成功的工具序列被强化，失败的被记录为「换法」提示）
|
||||
|
||||
---
|
||||
|
||||
## 4. Harnessability 与设计启示
|
||||
|
||||
### 4.1 可 Harness 性
|
||||
|
||||
aiops 后端是 Go 强类型 + 清晰的包边界，天然适合被 Harness：
|
||||
|
||||
- 强类型使 LLM 工具的 JSON Schema 可以严格约束参数
|
||||
- 清晰的 controller / model / pkg 分层使「引擎库零业务依赖」可行
|
||||
- 复用 aiops 既有的凭证系统、SSH 包、DB，大幅缩减 Harness 代码量
|
||||
|
||||
### 4.2 Ashby 必要多样性定律
|
||||
|
||||
> 调节器必须拥有至少与被调节系统相同的多样性。
|
||||
|
||||
aiops Agent CLI 通过两层多样性缩减：
|
||||
|
||||
1. **工具集精简**（6 → 2）：只保留 `ssh_execute` + `analyze_output`，把「在远程主机做任何事」收敛为「执行 shell + 分析输出」，让 LLM 的决策空间可控
|
||||
2. **Prompt 工作方式约束**：明确告诉 LLM「一次只做关键的、可验证的一步」「优先只读命令」「失败要换法重试」
|
||||
|
||||
这是把潜在的「无限可能的 Agent」收敛为「可控的运维 Agent」的关键策略。
|
||||
|
||||
### 4.3 Harness 模板
|
||||
|
||||
aiops Agent CLI 本身就是一个「Web 版运维 Agent Harness 模板」—— 它的前馈（五层 Prompt）、反馈（安全 + 检查点 + Evolver）、工具协议（Tool 接口）可以被视为同类产品的参考实现。
|
||||
|
||||
---
|
||||
|
||||
## 5. 反馈回路设计
|
||||
|
||||
### 5.1 多轮自我评审循环
|
||||
|
||||
aiops ReAct 循环本质就是一种多轮自我评审：
|
||||
|
||||
```
|
||||
Round 1：LLM 思考 + 决定工具
|
||||
│
|
||||
Round 2：执行工具 → 观察输出（exit_code 是关键信号）
|
||||
│
|
||||
Round 3：根据输出判断 → 继续排障或修复
|
||||
│
|
||||
═══ 检查点 Round 4 ═══
|
||||
├─ 若重复调用率 >50% 或连续失败 ≥3 → 注入「换思路」提示
|
||||
│
|
||||
Round N：… 直到 LLM 不再返回 tool_calls
|
||||
│
|
||||
═══ 检查点 Round 8 ═══ 强制中间总结
|
||||
═══ 检查点 Round 12 ═══ 敦促收尾
|
||||
│
|
||||
最终答案 + Evolver 学习（后台）
|
||||
```
|
||||
|
||||
### 5.2 黄金原则
|
||||
|
||||
从 OpenAI Codex 实践提炼的四条原则在 aiops Agent CLI 中的体现：
|
||||
|
||||
1. **优先使用共享抽象**：`pkg/remoteexec`（SSH）、`pkg/agentcli/tools`（Tool 接口）、`pkg/agentcli/llm`（Client 接口），将不变式集中管理
|
||||
2. **不使用「YOLO 式」探测**：所有命令先经 `AssessBashRisk` 评估，黑名单硬拒、高危确认，绝不盲目执行
|
||||
3. **统一错误处理**：工具返回 `Result{Success, Output, Error}`，错误信息以中文回到对话供 LLM 理解；Evolver 失败优雅降级不阻断主循环
|
||||
4. **避免全局状态**：`Engine` 每次任务一个实例，`Registry` 通过 `sync.RWMutex` 保护；会话状态走 DB 不走全局变量
|
||||
|
||||
---
|
||||
|
||||
## 6. aiops Agent CLI 代码对照
|
||||
|
||||
### 6.1 前馈指导实例
|
||||
|
||||
| 理论概念 | aiops 实现 | 代码位置 |
|
||||
|----------|-----------|----------|
|
||||
| 角色与能力引导 | 五层 System Prompt | `pkg/agentcli/prompt/prompt.go` |
|
||||
| 工具能力披露 | Registry 动态生成工具描述 | `core/agent.go: buildToolDescriptions` |
|
||||
| 工作范式引导 | ReAct 范式文本（思考-行动-观察-循环-收尾） | `prompt.go` Layer 4 |
|
||||
| 安全规则文本 | 黑名单 + 优先只读 + 高危确认 | `prompt.go` Layer 2 |
|
||||
|
||||
### 6.2 反馈传感器实例
|
||||
|
||||
| 理论概念 | aiops 实现 | 代码位置 |
|
||||
|----------|-----------|----------|
|
||||
| 计算型反馈（执行前） | 黑名单硬拒 + 风险分级 | `tools/risk.go` + `safety/safety.go: Check` |
|
||||
| 计算型反馈（轮次间） | 循环检测（同参 >3 拒绝） | `core/agent.go: processToolCalls` |
|
||||
| 计算型反馈（轮次间） | 连续失败追踪 | `core/agent.go: updateConsecutiveFailures` |
|
||||
| 结构化反馈 | 自适应检查点（Round 4/8/12 注入提示） | `core/agent.go: checkAdaptiveCheckpoint` |
|
||||
| 上下文保护 | 消息裁剪 + tool 消息完整性修复 | `core/agent.go: trimMessages` + `ensureToolMessageIntegrity` |
|
||||
| 安全反馈 | 三级模式阈值 + 高危确认 | `safety/safety.go` |
|
||||
|
||||
### 6.3 Steering Loop 实例
|
||||
|
||||
aiops 的 **Evolver 自进化引擎**是自动 Steering Loop 的代码级实现：
|
||||
|
||||
```
|
||||
EvolverEngine (pkg/agentcli/evolver/)
|
||||
│
|
||||
├── engine.go 精简进化循环（OBSERVE→CLASSIFY→LEARN→STORE→MEMORIZE→PREDICT）
|
||||
└── memory.go 四层记忆（experience/factual/procedural/environment）
|
||||
```
|
||||
|
||||
每次任务执行后，Evolver 异步学习并存储经验；下次任务开始时，`GetContextForPrompt()` 把相关历史经验注入 System Prompt 的 Layer 5 —— 这就是「观察问题 → 改进 Harness」的自动化实现。
|
||||
|
||||
### 6.4 品味不变式实例
|
||||
|
||||
| 类别 | 不变式 | 理由 |
|
||||
|------|--------|------|
|
||||
| 语言 | 注释和错误信息使用中文，署名 `// Logan.Li` | 项目规范 |
|
||||
| 命名 | 导出函数 PascalCase，包名全小写 | Go 标准 |
|
||||
| 错误 | `Result.Error` 携带中文错误，Evolver 失败降级不 panic | 保留错误链，不阻断主流程 |
|
||||
| 依赖 | controller → model + pkg/agentcli（单向） | 引擎库零业务依赖 |
|
||||
| 日志 | 引擎 emit Event，由 controller 决定落库还是推 WS | 引擎不直接依赖 DB/WS |
|
||||
| 安全 | 黑名单硬拒不可被确认放行 | 安全红线 |
|
||||
|
||||
---
|
||||
|
||||
## 7. Web 可观测性
|
||||
|
||||
> opsxcli 是 CLI 工具，可观测性 = slog + 审计日志 + `--debug`。
|
||||
> aiops Agent CLI 是 Web 服务，可观测性 = **WebSocket 事件流 + DB 持久化 + 会话历史回放**。
|
||||
|
||||
### 7.1 事件流（实时）
|
||||
|
||||
引擎通过 `EventCallback` 推送结构化事件，controller 序列化为 `wsEvent` 后推 WebSocket：
|
||||
|
||||
| Event.Type | 含义 | 前端渲染 |
|
||||
|------------|------|----------|
|
||||
| `progress` | 轮次 + token | 顶部进度条 |
|
||||
| `thought` | AI 思考文本 | 思考气泡 |
|
||||
| `tool_call` | 即将执行的工具 + 风险 | 工具调用卡片（含风险标签） |
|
||||
| `tool_result` | 工具输出 + 成败 + 耗时 | 工具结果卡片 |
|
||||
| `confirm` | 高危确认请求 | useConfirm 弹框 |
|
||||
| `done` | 最终答案 | 完成气泡 |
|
||||
| `error` | 错误（含达到最大轮次） | 错误气泡 |
|
||||
|
||||
### 7.2 持久化（事后审计）
|
||||
|
||||
每条事件（除 progress）落库 `agent_cli_messages`，前端「会话历史」页面可按 session_id 回放完整 ReAct 推理过程：
|
||||
|
||||
```go
|
||||
// controller/agent_cli.go: persistMsg
|
||||
// 每条消息记录：round / type / role / content / tool_name / tool_args /
|
||||
// tool_output / risk / success / duration / tokens
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 把审计日志写到 `~/.opsxcli/audit/audit.log`（文件），aiops 直接走 DB（多用户、可查询、可关联用户与主机）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 参考资源
|
||||
|
||||
| 资源 | 说明 |
|
||||
|------|------|
|
||||
| [Martin Fowler — Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) | 理论框架，控制论视角 |
|
||||
| [OpenAI — Harness Engineering](https://openai.com/zh-Hans-CN/index/harness-engineering) | 实践报告，Codex 实战经验 |
|
||||
| [LangChain — Agent = Model + Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/) | 术语定义 |
|
||||
| [Anthropic — Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) | 长时间运行 Agent 的 Harness 设计 |
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,177 @@
|
||||
# 04 - 插件架构设计
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。
|
||||
> opsxcli 的「plugins/」CLI 插件层（mysql/ssh/ping 等 46+ 命令）在 aiops 中不适用 —— Web 版聚焦远程运维，工具精简为 2 个并改由 `tools.Tool` 接口承载。
|
||||
|
||||
## 工具（Tool）= aiops 版的「插件」
|
||||
|
||||
opsxcli 有完整的 CLI 插件生态（46+ 命令插件）；aiops Agent CLI 把「插件」概念收敛为更纯粹的 **Tool 接口**：
|
||||
|
||||
- 不再有 CLI 命令、参数解析、帮助文本
|
||||
- 工具的唯一职责是：被 LLM 调用 → 在目标主机做事 → 返回结构化结果
|
||||
- LLM 通过 function calling 协议感知工具的存在与用法
|
||||
|
||||
> 这是合理的精简：Web Agent 的能力边界由「Tool 接口 + LLM 推理」共同决定，不再需要 CLI 命令那一层。
|
||||
|
||||
## Tool 接口（5 方法）
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/registry.go
|
||||
|
||||
type Tool interface {
|
||||
Name() string // 工具名（LLM 调用时用）
|
||||
Description() string // 给 LLM 看的描述
|
||||
Parameters() map[string]interface{} // JSON Schema 参数定义
|
||||
RiskLevel() RiskLevel // 静态风险等级
|
||||
Execute(ctx context.Context, args map[string]interface{}) (*Result, error)
|
||||
}
|
||||
```
|
||||
|
||||
设计哲学：**接口最小化** —— 5 个方法覆盖工具的完整生命周期。
|
||||
|
||||
### DynamicRiskTool 扩展接口
|
||||
|
||||
```go
|
||||
type DynamicRiskTool interface {
|
||||
Tool
|
||||
RiskLevelForArgs(args map[string]interface{}) RiskLevel
|
||||
}
|
||||
```
|
||||
|
||||
部分工具的「静态风险」无法反映真实风险（如 `ssh_execute` 静态是 High，但 `df -h` 是 Safe、`rm -rf /` 是 Critical）。这些工具额外实现 `DynamicRiskTool`，安全控制器 `Check` 时优先调用动态评估。
|
||||
|
||||
### Result 结构
|
||||
|
||||
```go
|
||||
type Result struct {
|
||||
Success bool `json:"success"`
|
||||
Output string `json:"output"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
## Registry 注册中心
|
||||
|
||||
```go
|
||||
type Registry struct {
|
||||
tools map[string]Tool
|
||||
mu sync.RWMutex // 读写锁，支持并发注册和查询
|
||||
}
|
||||
```
|
||||
|
||||
核心方法：
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `NewRegistry()` | 创建空注册中心 |
|
||||
| `Register(tool)` | 注册工具（线程安全） |
|
||||
| `Get(name)` | 按名获取工具（LLM 调用时按名查找） |
|
||||
| `List()` | 列出所有工具（构建 Prompt Layer 3 工具描述） |
|
||||
| `ToLLMTools()` | 转换为 OpenAI function calling 格式（自动注入到 LLM `tools` 参数） |
|
||||
|
||||
`ToLLMTools()` 是 Registry 与 LLM 协议的桥梁：注册的工具自动出现在 LLM 的 function 列表中，无需手动维护。
|
||||
|
||||
## 已注册工具一览
|
||||
|
||||
> 与 opsxcli 的关键差异：opsxcli 有 6 个工具（local_bash / ssh_execute / scp_transfer / file_read / file_search / analyze_output），aiops 精简为 2 个。
|
||||
|
||||
| 工具 | 风险等级 | 功能 | 来源 |
|
||||
|------|----------|------|------|
|
||||
| `ssh_execute` | High（静态）/ Safe~Critical（动态） | 在目标主机远程执行 shell 命令 | aiops 既有 `pkg/remoteexec` |
|
||||
| `analyze_output` | Safe | 对冗长输出做摘要/错误提取 | 内置 Go 实现 |
|
||||
|
||||
### 为什么精简？
|
||||
|
||||
| opsxcli 工具 | aiops 处理 | 原因 |
|
||||
|--------------|-----------|------|
|
||||
| `local_bash` | **剥离** | Web 后端不应在服务器本地执行命令（安全风险 + 多用户隔离） |
|
||||
| `scp_transfer` | **剥离** | 文件传输走 aiops 既有的「文件管理」模块，不混入 Agent |
|
||||
| `file_read` | **剥离** | 远程读文件用 `ssh_execute cat`，无需独立工具 |
|
||||
| `file_search` | **剥离** | 远程搜文件用 `ssh_execute grep/find` |
|
||||
| `ssh_execute` | **保留** | 核心远程运维能力 |
|
||||
| `analyze_output` | **保留** | 防止长输出 token 爆炸，辅助 LLM 聚焦关键信息 |
|
||||
|
||||
工具越少，LLM 的决策空间越收敛（呼应 Ashby 定律），首次做对的概率越高。
|
||||
|
||||
## 工具分类标准（aiops 版）
|
||||
|
||||
### 放入内置工具集的条件（需同时满足）
|
||||
|
||||
1. 属于运维 Agent 高频需要的能力
|
||||
2. 无法用现有工具简单组合完成（如 `analyze_output` 不能用 `ssh_execute` 替代 —— 它操作的是已有文本而非远程命令）
|
||||
3. 实现简洁（单文件 < 300 行）
|
||||
|
||||
### 通过 `ssh_execute` 间接覆盖的能力
|
||||
|
||||
opsxcli 用独立插件实现的能力，在 aiops 中全部由 `ssh_execute` 执行远程命令覆盖：
|
||||
|
||||
| opsxcli 插件能力 | aiops 等效 |
|
||||
|------------------|-----------|
|
||||
| `mysql -e "..."` | `ssh_execute "mysql -e \"...\""` |
|
||||
| `redis-cli ...` | `ssh_execute "redis-cli ..."` |
|
||||
| `ping / traceroute` | `ssh_execute "ping ..."` |
|
||||
| `cat / grep / find` | `ssh_execute "cat ..."` |
|
||||
| `systemctl status nginx` | `ssh_execute "systemctl status nginx"` |
|
||||
|
||||
LLM 会根据任务自主决定执行什么命令，无需为每类命令提供独立工具。
|
||||
|
||||
## 混合架构的好处
|
||||
|
||||
1. **职责单一**：每个工具只做一件事，`ssh_execute` 执行、`analyze_output` 分析
|
||||
2. **协议简单**：LLM 只需理解 2 个 function，决策快、错误少
|
||||
3. **风险可控**：所有远程操作统一走 `ssh_execute` 的风险评估（`AssessBashRisk`），不会因为工具增多而出现安全盲区
|
||||
4. **扩展灵活**：未来若需要新工具（如 `kubectl_apply`），实现 Tool 接口注册即可
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新工具
|
||||
|
||||
1. 实现 `Tool` 接口（必要时实现 `DynamicRiskTool`）：
|
||||
|
||||
```go
|
||||
// pkg/agentcli/tools/kubectl_get.go
|
||||
type KubectlGetTool struct{ cfg remoteexec.SSHConfig }
|
||||
|
||||
func (t *KubectlGetTool) Name() string { return "kubectl_get" }
|
||||
func (t *KubectlGetTool) Description() string {
|
||||
return "在目标主机执行 kubectl get 并返回结果"
|
||||
}
|
||||
func (t *KubectlGetTool) Parameters() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"resource": map[string]interface{}{"type": "string", "description": "如 pods/deployments"},
|
||||
},
|
||||
"required": []string{"resource"},
|
||||
}
|
||||
}
|
||||
func (t *KubectlGetTool) RiskLevel() tools.RiskLevel { return tools.RiskSafe }
|
||||
func (t *KubectlGetTool) Execute(ctx context.Context, args map[string]interface{}) (*tools.Result, error) {
|
||||
// 复用 remoteexec 执行 kubectl get
|
||||
}
|
||||
```
|
||||
|
||||
2. 在 `agentcli.NewEngine` 中注册：
|
||||
|
||||
```go
|
||||
registry.Register(tools.NewSSHExecuteTool(cfg.SSH, coreCfg.ToolTimeout))
|
||||
registry.Register(tools.NewAnalyzeOutputTool())
|
||||
registry.Register(tools.NewKubectlGetTool(cfg.SSH)) // 新增
|
||||
```
|
||||
|
||||
3. 工具自动出现在 LLM 的 function 列表与 Prompt Layer 3 工具描述中。无需改 Prompt、controller、前端。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| 忘记设置 `RiskLevel` 导致误判 | 默认按接口返回值，高危工具必须显式声明 |
|
||||
| 高危工具未实现 `DynamicRiskTool` | 静态等级无法反映参数差异（如 `ssh_execute` 看 `df` 还是 `rm -rf`），必须实现动态评估 |
|
||||
| 工具 Execute 无超时 | `Config.ToolTimeout=120s` 兜底（`context.WithTimeout`） |
|
||||
| 工具输出过长导致 token 爆炸 | `OutputMaxLength=10000` 截断 + 引导 LLM 调用 `analyze_output` |
|
||||
|
||||
## 总结
|
||||
|
||||
aiops Agent CLI 的「插件架构」是 opsxcli 的精简版：从「46+ CLI 插件」收敛为「2 个 Tool 接口实现」。这不是能力的退化，而是**收敛决策空间、聚焦远程运维、降低 LLM 误判概率**的有意设计。详细工具实现见 [05 - Builtin 内置工具](05-Builtin内置命令.md)。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,248 @@
|
||||
# 05 - Builtin 内置工具
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/`）。
|
||||
> opsxcli 原文讨论「builtin 基础命令（ls/cat/grep 等）的 Go 原生实现 vs 命令转发」抉择；aiops 版剥离了所有本地命令，仅保留 2 个工具：`ssh_execute`（远程执行）+ `analyze_output`（输出分析）。本文聚焦这 2 个工具的设计。
|
||||
|
||||
## 设计目标
|
||||
|
||||
为 aiops Agent CLI 提供**最小而充分**的工具集：
|
||||
|
||||
- `ssh_execute` 覆盖所有「在远程主机做事」的需求（排障、安装、配置、重启）
|
||||
- `analyze_output` 解决「命令输出过长导致 LLM token 爆炸」的问题
|
||||
|
||||
工具数量从 opsxcli 的 6 个精简为 2 个，但能力边界通过 LLM 自主编排命令来扩展，而非通过堆工具。
|
||||
|
||||
## 工具 1：ssh_execute（远程命令执行）
|
||||
|
||||
### 定位
|
||||
|
||||
在目标主机上执行任意 shell 命令，返回合并的 stdout + stderr + exit_code。这是 Agent 真正「动手」的唯一通道。
|
||||
|
||||
### 实现
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/ssh_execute.go
|
||||
|
||||
type SSHExecuteTool struct {
|
||||
cfg remoteexec.SSHConfig // 目标主机连接配置（含凭据，由 controller 注入）
|
||||
timeout time.Duration // 默认命令超时（60s）
|
||||
}
|
||||
|
||||
func (t *SSHExecuteTool) Name() string { return "ssh_execute" }
|
||||
|
||||
func (t *SSHExecuteTool) Description() string {
|
||||
return fmt.Sprintf(
|
||||
"在远程服务器 %s（用户 %s）上执行 shell 命令并返回合并的 stdout+stderr 输出与退出码。"+
|
||||
"用于排障（查看日志/进程/磁盘/网络）、安装与配置软件、重启服务等。"+
|
||||
"高危命令（rm -rf /、mkfs、reboot 等）需用户确认。", host, user)
|
||||
}
|
||||
|
||||
func (t *SSHExecuteTool) Parameters() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"command": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "要执行的 shell 命令，例如 df -h、systemctl status nginx、tail -n 100 /var/log/messages",
|
||||
},
|
||||
"timeout": map[string]interface{}{
|
||||
"type": "integer",
|
||||
"description": "命令超时秒数（默认 60）",
|
||||
},
|
||||
},
|
||||
"required": []string{"command"},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 风险评估：DynamicRiskTool
|
||||
|
||||
`ssh_execute` 是典型「静态等级无法反映真实风险」的工具，因此实现 `DynamicRiskTool`：
|
||||
|
||||
```go
|
||||
// 静态等级：High（保守）
|
||||
func (t *SSHExecuteTool) RiskLevel() RiskLevel { return RiskHigh }
|
||||
|
||||
// 动态等级：看具体命令
|
||||
func (t *SSHExecuteTool) RiskLevelForArgs(args map[string]interface{}) RiskLevel {
|
||||
return AssessBashRisk(StringParam(args, "command"))
|
||||
}
|
||||
```
|
||||
|
||||
| 命令示例 | 动态风险 | 安全模式 balanced 下的行为 |
|
||||
|----------|----------|--------------------------|
|
||||
| `df -h` / `ps aux` / `cat /etc/hosts` | Safe | 直接执行 |
|
||||
| `mkdir /tmp/foo` / `touch x` | Low | 直接执行 |
|
||||
| `chmod 644 /etc/cfg` / `cp a b` | Medium | strict 需确认，balanced 放行 |
|
||||
| `systemctl restart nginx` / `kill 1234` | High | 弹框确认 |
|
||||
| `rm -rf /var/log/*` | Critical | **硬拒**（不可确认放行） |
|
||||
|
||||
### Execute 流程
|
||||
|
||||
```go
|
||||
func (t *SSHExecuteTool) Execute(ctx context.Context, args map[string]interface{}) (*Result, error) {
|
||||
command := strings.TrimSpace(StringParam(args, "command"))
|
||||
if command == "" {
|
||||
return &Result{Success: false, Error: "参数 command 不能为空"}, nil
|
||||
}
|
||||
// ... timeout 解析
|
||||
res, err := remoteexec.Exec(t.cfg, command, timeout)
|
||||
if err != nil {
|
||||
return &Result{Success: false, Error: "SSH 连接失败: " + err.Error()}, nil
|
||||
}
|
||||
// 关键：附带 exit_code，让 LLM 判断命令是否成功（排障关键信号）
|
||||
output := res.Output + fmt.Sprintf("[exit_code=%d]", res.ExitCode)
|
||||
return &Result{Success: res.Success, Output: output, Error: res.Error}, nil
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**：
|
||||
|
||||
- **复用 aiops 既有 `pkg/remoteexec`**：Go-native SSH，无外部依赖，凭据由 controller 从 `model.Server` 关联凭证系统构建后注入
|
||||
- **`exit_code` 是关键信号**：LLM 通过 `exit_code` 判断命令是否真正成功（避免 LLM 误以为「输出有内容」就是「执行成功」）
|
||||
- **连接级失败与命令级失败分离**：SSH 连不上返回 `Error`，命令执行返回 `exit_code != 0`，让 LLM 区分排查方向
|
||||
- **凭据不暴露给 LLM**：`SSHConfig` 是工具私有的，LLM 只看到 `command` 参数
|
||||
|
||||
## 工具 2：analyze_output（输出分析）
|
||||
|
||||
### 定位
|
||||
|
||||
对一段（可能很长的）命令输出做摘要：统计行数、提取疑似错误/告警行、必要时截断保留首尾。**纯文本处理，不执行任何命令**，因此 `RiskSafe`。
|
||||
|
||||
### 为什么需要它？
|
||||
|
||||
LLM 上下文窗口有限（即使 128k 模型，超长输出也会显著增加成本和延迟）。`ssh_execute` 单次输出截断在 10000 字符，但即便如此，日志类输出（如 `journalctl -n 1000`）仍可能让 LLM 难以聚焦。
|
||||
|
||||
`analyze_output` 让 LLM 自主决定「输出太长时先分析再推理」：
|
||||
|
||||
```
|
||||
Round 3: ssh_execute "journalctl -u nginx -n 500"
|
||||
→ 输出 500 行
|
||||
Round 4: analyze_output(output, focus="error")
|
||||
→ 提取 8 行疑似错误 + 截断保留首尾
|
||||
Round 5: LLM 基于精炼后的信息推理
|
||||
```
|
||||
|
||||
### 实现
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/builtin.go
|
||||
|
||||
func (t *AnalyzeOutputTool) Execute(ctx context.Context, args map[string]interface{}) (*Result, error) {
|
||||
output := StringParam(args, "output")
|
||||
focus := strings.ToLower(StringParam(args, "focus"))
|
||||
// 1. 超长截断：保留前 40 + 后 40 行，中间用省略标注
|
||||
// 2. 提取疑似错误/告警行（errorKeywords，含中英文）
|
||||
// - 英文：error / fail / exception / traceback / denied / timeout / refused / critical / fatal
|
||||
// - 中文：错误 / 失败 / 拒绝 / 超时 / 无法 / 异常
|
||||
// - 若传 focus，把 focus 作为额外关键词优先匹配
|
||||
// 3. 最多 20 条疑似错误行
|
||||
// 4. 组装摘要：总行数 + 截断标注 + 错误行 + 输出片段
|
||||
}
|
||||
```
|
||||
|
||||
**错误关键词列表**：
|
||||
|
||||
```go
|
||||
errorKeywords := []string{
|
||||
"error", "fail", "exception", "traceback", "denied",
|
||||
"permission", "timeout", "refused", "unavailable", "critical", "fatal",
|
||||
"错误", "失败", "拒绝", "超时", "无法", "异常",
|
||||
}
|
||||
```
|
||||
|
||||
**输出格式示例**：
|
||||
|
||||
```
|
||||
总行数: 500（已截断保留首尾）
|
||||
疑似错误/告警行 (8):
|
||||
nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
|
||||
nginx: [emerg] bind() to [::]:80 failed (98: Address already in use)
|
||||
...
|
||||
|
||||
输出片段:
|
||||
... (前 40 行)
|
||||
... [已省略 420 行] ...
|
||||
... (后 40 行)
|
||||
```
|
||||
|
||||
## 工具组合：典型 ReAct 序列
|
||||
|
||||
`ssh_execute` 与 `analyze_output` 的组合覆盖绝大多数运维场景：
|
||||
|
||||
### 场景 1：磁盘满排障
|
||||
|
||||
```
|
||||
Round 1: ssh_execute "df -h" → 发现 /var 满
|
||||
Round 2: ssh_execute "du -sh /var/*" → 定位 /var/log 最大
|
||||
Round 3: ssh_execute "ls -lah /var/log | head -20" → 找到 access.log 巨大
|
||||
Round 4: 给出清理建议（不直接 rm，让用户确认）
|
||||
```
|
||||
|
||||
### 场景 2：服务启动失败
|
||||
|
||||
```
|
||||
Round 1: ssh_execute "systemctl status nginx" → failed
|
||||
Round 2: ssh_execute "journalctl -u nginx -n 500" → 500 行日志
|
||||
Round 3: analyze_output(output, focus="error") → 提取 8 行错误，端口被占
|
||||
Round 4: ssh_execute "ss -tlnp | grep :80" → 确认 80 端口被占用
|
||||
Round 5: 给出根因 + 解决建议
|
||||
```
|
||||
|
||||
### 场景 3：性能排查
|
||||
|
||||
```
|
||||
Round 1: ssh_execute "top -bn1 | head -20" → CPU 100% 进程
|
||||
Round 2: ssh_execute "ps aux --sort=-%cpu | head -10" → 定位 java 进程
|
||||
Round 3: ssh_execute "jstack <pid>" → 线程栈
|
||||
Round 4: analyze_output(jstack_output, focus="BLOCKED") → 死锁线索
|
||||
Round 5: 给出根因（线程死锁）
|
||||
```
|
||||
|
||||
## 工具与 Prompt 的协作
|
||||
|
||||
Prompt Layer 2 明确告诉 LLM：
|
||||
|
||||
> 排障时优先使用只读命令（df/ps/cat/grep/tail/systemctl status/journalctl）收集信息，确认根因后再动手修复。
|
||||
|
||||
Prompt Layer 3 自动列出工具描述（来自 `buildToolDescriptions()`）：
|
||||
|
||||
```
|
||||
【可用工具】
|
||||
- ssh_execute: 在远程服务器 ... 上执行 shell 命令 ...
|
||||
- analyze_output: 分析一段（可能很长的）命令输出文本 ...
|
||||
```
|
||||
|
||||
工具的命名和描述本身就是给 LLM 的「使用说明书」，描述写得好，LLM 就能正确选用。
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 何时应该新增工具（而非用 ssh_execute）？
|
||||
|
||||
满足以下任一条件：
|
||||
|
||||
1. **命令协议复杂、LLM 容易写错**（如 `kubectl apply -f` 需要 YAML 参数，用 `ssh_execute` 难以表达）
|
||||
2. **需要结构化输入/输出**（如数据库查询返回表结构）
|
||||
3. **需要专门的风险评估逻辑**（如 `kubectl delete` 需要按资源类型分级）
|
||||
|
||||
如果只是「执行某条命令」，用 `ssh_execute` 即可，不需要新工具。
|
||||
|
||||
### 实现步骤
|
||||
|
||||
见 [04 - 插件架构设计](04-插件架构设计.md) 的「添加新工具」章节。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| `ssh_execute` 输出过长撑爆上下文 | `OutputMaxLength=10000` 截断 + 引导调用 `analyze_output` |
|
||||
| LLM 把「输出有内容」误判为「命令成功」 | 输出末尾附 `[exit_code=N]`，Prompt 显式提醒 |
|
||||
| `analyze_output` 关键词覆盖不全 | 扩展 `errorKeywords` 列表（含中英文） |
|
||||
| 命令超时无反馈 | `context.WithTimeout(ctx, ToolTimeout)` + 失败信息回写 |
|
||||
| 凭据泄漏给 LLM | `SSHConfig` 是工具私有字段，不在 `Parameters` 中暴露 |
|
||||
|
||||
## 总结
|
||||
|
||||
aiops Agent CLI 的工具集设计遵循「少即是多」：2 个工具 + LLM 自主编排，覆盖绝大多数远程运维场景。`ssh_execute` 是「手」（动手做事），`analyze_output` 是「放大镜」（聚焦关键信息），二者配合让 Agent 既有行动力又有判断力。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,415 @@
|
||||
# 06 - Agent 核心引擎设计
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/core/agent.go`）。
|
||||
> 核心算法（16 轮 ReAct 主循环、自适应检查点、循环检测、连续失败追踪、Evolver 集成）全部保留；TUI 回调（Bubble Tea）剥离，改为 `EventCallback` 推 WebSocket 事件流。
|
||||
|
||||
## 设计理念
|
||||
|
||||
Agent 核心引擎遵循 **ReAct (Reasoning + Acting)** 范式：
|
||||
|
||||
- **Reasoning**：LLM 推理决定下一步行动（产出 `thought` 文本 + 工具调用计划）
|
||||
- **Acting**：调用工具执行具体操作（`ssh_execute` / `analyze_output`）
|
||||
- **Observing**：观察工具结果（`exit_code`、输出、耗时），反馈到下一轮推理
|
||||
|
||||
通过 16 轮迭代循环，让 Agent 从「盲目执行命令」进化为「有目的地探索和解决问题」。
|
||||
|
||||
## 核心结构
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/core/agent.go
|
||||
|
||||
type Agent struct {
|
||||
llm llm.Client // LLM 客户端（OpenAI 兼容）
|
||||
registry *tools.Registry // 工具注册中心
|
||||
config *Config // 运行配置
|
||||
safetyCtl *safety.Controller // 安全控制器
|
||||
evolver *evolver.EvolverEngine // 自进化引擎（可为 nil，降级运行）
|
||||
callback EventCallback // 事件回调（controller 注入，推 WS + 落库）
|
||||
totalTokens int // token 消耗统计
|
||||
mu sync.Mutex
|
||||
}
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：
|
||||
> - 剥离 `tokenizer *TokenEstimator` 独立结构，改为内联的 `estimateTokens` 函数
|
||||
> - 剥离 `lastEvolveResult` + `evolveResultMu`，改为 Evolver 内部维护
|
||||
> - 剥离 `evolveWg sync.WaitGroup`，进化 goroutine 自带 `recover()`，不阻塞主循环
|
||||
|
||||
### 依赖关系
|
||||
|
||||
```
|
||||
┌─────────┐
|
||||
│ Agent │
|
||||
└────┬────┘
|
||||
┌───────┬───────┼───────┬──────────┐
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌────────┐┌──────┐┌──────┐┌──────┐┌────────┐
|
||||
│Config ││Safety││Tools ││Evolver││Prompt │
|
||||
│配置 ││安全 ││工具 ││进化 ││构建器 │
|
||||
└────────┘└──────┘└──────┘└──────┘└────────┘
|
||||
```
|
||||
|
||||
## EventCallback —— 替代 TUI 的事件流
|
||||
|
||||
opsxcli 通过 `ToolCallback` 驱动 Bubble Tea TUI 实时渲染；aiops 改为 `EventCallback`，由 controller 序列化后推 WebSocket + 落库：
|
||||
|
||||
```go
|
||||
type EventType string
|
||||
|
||||
const (
|
||||
EventThought EventType = "thought" // AI 思考文本
|
||||
EventToolCall EventType = "tool_call" // 即将执行的工具（名/参数/风险）
|
||||
EventToolResult EventType = "tool_result" // 工具执行结果（输出/成败/耗时）
|
||||
EventProgress EventType = "progress" // 轮次 + token
|
||||
EventDone EventType = "done" // 任务完成（最终答案）
|
||||
EventError EventType = "error" // 错误（含达到最大轮次）
|
||||
)
|
||||
|
||||
type EventCallback func(Event)
|
||||
```
|
||||
|
||||
controller 的 `onEvent` 实现同时做两件事：
|
||||
|
||||
```go
|
||||
func (ac *agentConn) onEvent(e core.Event) {
|
||||
ac.write(wsEvent{...}) // 1. 推 WebSocket
|
||||
ac.persistMsg(...) // 2. 落库 agent_cli_messages（progress 除外）
|
||||
}
|
||||
```
|
||||
|
||||
## Config 配置
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/core/agent.go
|
||||
|
||||
type Config struct {
|
||||
MaxIterations int // 16 - 最大迭代次数
|
||||
Temperature float64 // 0.3 - LLM 温度（偏低 = 更确定）
|
||||
ToolTimeout time.Duration // 120s - 工具执行超时
|
||||
MaxTokens int // 4096 - 单次 LLM 最大输出 token
|
||||
SafetyMode safety.Mode // balanced
|
||||
OutputMaxLength int // 10000 - 输出截断长度
|
||||
MaxContextTokens int // 8000 - 上下文窗口（裁剪阈值 90%）
|
||||
MemoryDir string // data/agentcli - Evolver 记忆目录
|
||||
}
|
||||
```
|
||||
|
||||
默认值通过 `DefaultConfig()` 提供。controller 可通过 `EngineConfig.Core` 覆盖。
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 用 `LoadConfig()` 从环境变量加载（`OPSXCLI_AGENT_*`），aiops 改为代码默认值 + `EngineConfig` 显式覆盖（Web 场景下环境变量管理不直观）。
|
||||
|
||||
## 16 轮 ReAct 主循环
|
||||
|
||||
### 流程图
|
||||
|
||||
```
|
||||
用户输入
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ ReAct Main Loop │
|
||||
│ │
|
||||
│ Round 1 ──→ LLM 推理 → 工具调用 → 观察 │
|
||||
│ Round 2 ──→ LLM 推理 → 工具调用 → 观察 │
|
||||
│ Round 3 ──→ LLM 推理 → 工具调用 → 观察 │
|
||||
│ ═══════ CHECKPOINT 1 (Round 4) ═══════ │
|
||||
│ Round 4 ──→ 启发式评估 + 纠偏提示 │
|
||||
│ ... │
|
||||
│ Round 7 ──→ LLM 推理 → 工具调用 → 观察 │
|
||||
│ ═══════ CHECKPOINT 2 (Round 8) ═══════ │
|
||||
│ Round 8 ──→ 强制中间总结 │
|
||||
│ ... │
|
||||
│ Round 11 ──→ LLM 推理 → 工具调用 → 观察 │
|
||||
│ ═══════ CHECKPOINT 3 (Round 12) ═════ │
|
||||
│ Round 12 ──→ 最终提醒，敦促收尾 │
|
||||
│ ... │
|
||||
│ Round 16 ──→ 最大迭代，强制结束 │
|
||||
└──────────────┬──────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
最终回答 / 总结
|
||||
│
|
||||
▼ (后台异步)
|
||||
┌──────────────┐
|
||||
│ Evolver 学习 │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 为什么是 16 轮？
|
||||
|
||||
| 迭代次数 | 优点 | 缺点 |
|
||||
|----------|------|------|
|
||||
| 8 轮 | 快速响应 | 复杂运维任务不够用 |
|
||||
| **16 轮** | **覆盖 90% 运维场景** | **偶尔多消耗 token** |
|
||||
| 32 轮 | 兜底极端场景 | 成本高、用户等待久 |
|
||||
|
||||
16 轮是**能力与效率的平衡点**，配合自适应检查点避免无意义循环。
|
||||
|
||||
### 主循环核心代码（精简版）
|
||||
|
||||
```go
|
||||
for iter := 0; iter < a.config.MaxIterations; iter++ {
|
||||
if err := ctx.Err(); err != nil { return nil, err } // 中断检查
|
||||
a.emit(Event{Type: EventProgress, Round: iter + 1})
|
||||
|
||||
// 自适应检查点
|
||||
if hint := a.checkAdaptiveCheckpoint(iter, ...); hint != "" {
|
||||
messages = append(messages, llm.Message{Role: "user", Content: hint})
|
||||
}
|
||||
|
||||
trimmed := a.trimMessages(messages) // 裁剪历史
|
||||
resp, err := a.llm.Complete(ctx, &llm.CompletionRequest{
|
||||
Messages: trimmed, Tools: llmTools,
|
||||
Temperature: a.config.Temperature, MaxTokens: a.config.MaxTokens,
|
||||
})
|
||||
// ...
|
||||
a.emit(Event{Type: EventThought, Round: iter + 1, Thought: resp.Message.Content})
|
||||
|
||||
if len(resp.Message.ToolCalls) == 0 {
|
||||
// 最终答案
|
||||
a.emit(Event{Type: EventDone, Answer: resp.Message.Content, ...})
|
||||
a.triggerEvolve(ctx, query, serverInfo, answer, toolRecords, true, start)
|
||||
return &tools.Result{Success: true, Output: answer}, nil
|
||||
}
|
||||
|
||||
// 处理工具调用（含安全检查、循环检测、风险事件）
|
||||
observations, records, failInc := a.processToolCalls(ctx, resp.Message.ToolCalls, ...)
|
||||
messages = append(messages, observations...)
|
||||
}
|
||||
// 达到最大轮次
|
||||
a.triggerEvolve(ctx, query, serverInfo, "", toolRecords, false, start)
|
||||
return nil, fmt.Errorf("达到最大迭代次数(%d)...", a.config.MaxIterations)
|
||||
```
|
||||
|
||||
## 自适应检查点机制
|
||||
|
||||
### checkAdaptiveCheckpoint()
|
||||
|
||||
```go
|
||||
func (a *Agent) checkAdaptiveCheckpoint(iter int, history map[string]int, consecFail, totalCalls int) string {
|
||||
switch iter {
|
||||
case 3: // 第 4 轮（0-indexed 为 3）
|
||||
repeat := 0
|
||||
for _, c := range history {
|
||||
if c > 1 { repeat += c - 1 }
|
||||
}
|
||||
if totalCalls > 0 && (float64(repeat)/float64(totalCalls) > 0.5 || consecFail >= 3) {
|
||||
return "【系统提示】检测到重复使用相同工具或连续失败，请尝试换一种思路或不同命令。"
|
||||
}
|
||||
case 7: // 第 8 轮
|
||||
return "【系统提示】已执行到中段，请总结进展。信息足够就直接给出最终答案，否则说明剩余步骤。"
|
||||
case 11: // 第 12 轮
|
||||
return fmt.Sprintf("【系统提示】仅剩 %d 步，请立即整理已有信息给出最终答案，不要再调用新工具。",
|
||||
a.config.MaxIterations-iter-1)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
```
|
||||
|
||||
| 检查点 | 轮次 | 策略 | 触发条件 |
|
||||
|--------|------|------|----------|
|
||||
| **Tier 1** | Round 4 | 启发式纠偏 | 重复工具调用率 >50% **或** 连续失败 ≥3 |
|
||||
| **Tier 2** | Round 8 | 强制中间总结 | 始终注入 |
|
||||
| **Tier 3** | Round 12 | 敦促收尾 | 始终注入 |
|
||||
|
||||
### 设计决策：为什么用消息注入而不是额外 LLM 调用？
|
||||
|
||||
| 方案 | 优点 | 缺点 |
|
||||
|------|------|------|
|
||||
| ❌ 额外 LLM 调用评估状态 | 精确 | 每次 +1 API 调用，成本翻倍 |
|
||||
| ✅ **消息注入** | **零额外成本** | 依赖 LLM 自主理解提示 |
|
||||
|
||||
把引导消息以 `user` 角色注入对话，LLM 在下一轮推理时自然调整行为。这是「计算型反馈 + 积极的 prompt injection」的典型应用（见 [03 - Harness 工程化](03-Harness工程化与反馈回路.md)）。
|
||||
|
||||
## 循环检测
|
||||
|
||||
防止 LLM 陷入「用相同参数反复调用同一工具」的死循环：
|
||||
|
||||
```go
|
||||
key := tc.Function.Name + ":" + tc.Function.Arguments
|
||||
history[key]++
|
||||
if history[key] > 3 {
|
||||
obs = append(obs, llm.Message{
|
||||
Role: "tool", ToolCallID: tc.ID, Name: tc.Function.Name,
|
||||
Content: "错误: 检测到循环调用，相同参数已调用超过3次，请换一种方式",
|
||||
})
|
||||
continue
|
||||
}
|
||||
```
|
||||
|
||||
阈值 >3 次：允许 LLM 重试 2~3 次（合理调试），超过则强制换法。
|
||||
|
||||
## 连续失败追踪
|
||||
|
||||
```go
|
||||
func (a *Agent) updateConsecutiveFailures(obs []llm.Message, current int) int {
|
||||
errs := 0
|
||||
for _, o := range obs {
|
||||
c := o.Content
|
||||
if strings.HasPrefix(c, "错误") || strings.HasPrefix(c, "失败") ||
|
||||
strings.HasPrefix(c, "执行错误") || strings.HasPrefix(c, "执行失败") {
|
||||
errs++
|
||||
}
|
||||
}
|
||||
if errs == 0 { return 0 } // 有成功就重置
|
||||
return current + errs
|
||||
}
|
||||
```
|
||||
|
||||
连续失败 ≥3 次会触发 Tier 1 检查点的纠偏提示。
|
||||
|
||||
## Token 估算与消息裁剪
|
||||
|
||||
### estimateTokens（粗略估算）
|
||||
|
||||
```go
|
||||
func estimateTokens(s string) int {
|
||||
return len([]rune(s))/3 + 1
|
||||
}
|
||||
```
|
||||
|
||||
中文约 1 字/token，英文约 1/4，折中 rune/3。够用即可，不需要精确 tokenizer。
|
||||
|
||||
### trimMessages
|
||||
|
||||
```go
|
||||
func (a *Agent) trimMessages(msgs []llm.Message) []llm.Message {
|
||||
maxT := a.config.MaxContextTokens * 9 / 10 // 留 10% 余量
|
||||
sysT := estimateTokens(msgs[0].Content)
|
||||
kept := ... // 从末尾向前累加，超 maxT 停止
|
||||
if len(kept) < 4 && len(msgs) > 4 {
|
||||
kept = msgs[len(msgs)-4:] // 最少保留最近 4 条
|
||||
}
|
||||
result := append([]llm.Message{msgs[0]}, kept...) // system + 最近消息
|
||||
return ensureToolMessageIntegrity(result)
|
||||
}
|
||||
```
|
||||
|
||||
### ensureToolMessageIntegrity（关键）
|
||||
|
||||
LLM API 要求 `role: tool` 消息必须紧跟在带 `tool_calls` 的 `assistant` 消息之后，且 ID 匹配。裁剪后可能出现孤立 tool 消息，导致 API 报错：
|
||||
|
||||
```
|
||||
Messages with role 'tool' must be a response to a preceding message with 'tool_calls'
|
||||
```
|
||||
|
||||
`ensureToolMessageIntegrity` 修复这种孤立：
|
||||
|
||||
```go
|
||||
// 1. 收集所有 assistant.tool_calls 的 ID
|
||||
// 2. 遍历 tool 消息：
|
||||
// - 若 ID 不在 validIDs 中 → 删除
|
||||
// - 若前一条不是 assistant 或 ID 不匹配 → 删除
|
||||
```
|
||||
|
||||
## 工具调用处理（processToolCalls）
|
||||
|
||||
完整流程：
|
||||
|
||||
```
|
||||
对每个 tool_call:
|
||||
├─ 循环检测（>3 次拒绝）
|
||||
├─ registry.Get(name) 查找工具
|
||||
├─ json.Unmarshal 解析参数
|
||||
├─ risk = toolRisk(tool, args) ← 优先 DynamicRiskTool
|
||||
├─ emit EventToolCall(name, args, risk)
|
||||
├─ safetyCtl.Check(tool, args) ← 高危触发 ConfirmFn
|
||||
│ ├─ 黑名单（Critical）→ 拒绝
|
||||
│ ├─ 阈值内 / AutoApprove → 放行
|
||||
│ └─ 达阈值 → confirmFn → controller 推 WS confirm → 等前端回传
|
||||
├─ tool.Execute(ctx, args) ← context.WithTimeout(ToolTimeout)
|
||||
├─ 输出截断（> OutputMaxLength）
|
||||
├─ emit EventToolResult(output, success, duration)
|
||||
└─ 构建 observation 消息追加到 messages
|
||||
```
|
||||
|
||||
## Evolver 集成
|
||||
|
||||
### triggerEvolve（异步进化）
|
||||
|
||||
```go
|
||||
func (a *Agent) triggerEvolve(ctx context.Context, query, serverHost, answer string,
|
||||
records []evolver.ToolCallRecord, success bool, start time.Time) {
|
||||
if a.evolver == nil { return } // 降级
|
||||
exec := &evolver.TaskExecution{...}
|
||||
go func() {
|
||||
defer func() { _ = recover() }() // panic 恢复
|
||||
eCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel()
|
||||
_ = a.evolver.Evolve(eCtx, exec) // 错误忽略
|
||||
}()
|
||||
}
|
||||
```
|
||||
|
||||
**三层保护**：
|
||||
|
||||
1. **后台 goroutine**：不阻塞主循环，用户立即拿到答案
|
||||
2. **30 秒超时**：防止进化过程无限运行
|
||||
3. **panic 恢复**：捕获异常，确保 goroutine 崩溃不影响主流程
|
||||
|
||||
### GetContextForPrompt（经验注入）
|
||||
|
||||
任务开始时（`Run` 入口）：
|
||||
|
||||
```go
|
||||
evolveCtx := ""
|
||||
if a.evolver != nil {
|
||||
evolveCtx = a.evolver.GetContextForPrompt(query) // 按 task_type 取历史经验
|
||||
}
|
||||
systemPrompt := prompt.BuildSystemPrompt(serverInfo, toolDescs, evolveCtx)
|
||||
```
|
||||
|
||||
注入的内容会被放入 Prompt Layer 5（详见 [07 - Prompt 构建](07-Prompt构建与记忆注入.md) 与 [08 - Evolver](08-Evolver自进化引擎.md)）。
|
||||
|
||||
## Agent 初始化流程
|
||||
|
||||
```
|
||||
NewAgent(client, registry, cfg, sc, ev)
|
||||
│
|
||||
├─ cfg == nil → DefaultConfig()
|
||||
├─ sc == nil → safety.NewController(balanced)
|
||||
├─ MaxContextTokens <= 0 → 强制设为 8000（防御性校验）
|
||||
└─ return Agent
|
||||
```
|
||||
|
||||
**优雅降级设计**：Evolver 初始化失败时，`agentcli.NewEngine` 把 `ev` 设为 `nil`，Agent 继续正常工作，只是没有自学习能力。
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 增加新的迭代策略
|
||||
|
||||
1. 在 `Config` 中增加策略配置项（如新的检查点轮次）
|
||||
2. 在 `checkAdaptiveCheckpoint()` 中添加新 case
|
||||
3. 编写对应的中文提示文本
|
||||
|
||||
### 自定义事件类型
|
||||
|
||||
1. 在 `EventType` 常量中新增（如 `EventWarning`）
|
||||
2. 在 `Event` 结构中增加字段
|
||||
3. 在 controller 的 `onEvent` 中增加 case 处理（推 WS + 落库）
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| MaxIterations 设太大导致 token 失控 | 默认 16 + 自适应检查点 |
|
||||
| trimMessages 后 tool 消息孤立 | `ensureToolMessageIntegrity()` 修复 |
|
||||
| Evolver 失败导致 Agent 不可用 | 优雅降级，`evolver=nil` 时跳过进化 |
|
||||
| MaxContextTokens=0 导致上下文异常 | 防御性校验，<=0 时强制 8000 |
|
||||
| 高并发下 messages 切片竞争 | Agent 不是并发安全的，**每个任务用独立实例**（controller 已保证：每次 startTask 新建 Engine） |
|
||||
| LLM 不返回 tool_calls 也不返回 content | 视为完成，emit done（空答案） |
|
||||
|
||||
## 与 opsxcli 的差异总结
|
||||
|
||||
| 维度 | opsxcli | aiops |
|
||||
|------|---------|-------|
|
||||
| 回调机制 | `ToolCallback` 驱动 Bubble Tea TUI | `EventCallback` 推 WebSocket + 落库 |
|
||||
| Token 估算 | 独立 `TokenEstimator` 结构 | 内联 `estimateTokens` 函数 |
|
||||
| 配置加载 | 环境变量 `OPSXCLI_AGENT_*` | `DefaultConfig()` + `EngineConfig` 覆盖 |
|
||||
| 进化 goroutine 同步 | `evolveWg.Wait()` | 自带 recover + 30s 超时，不等 |
|
||||
| MaxContextTokens 默认 | 6000（为 8k 模型留余量） | 8000（适配现代 128k 模型） |
|
||||
|
||||
核心算法（16 轮循环 / 检查点 / 循环检测 / 连续失败追踪 / Evolver 集成）完全保留，差异仅在工程外壳。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,301 @@
|
||||
# 07 - Prompt 构建与记忆注入
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/prompt/prompt.go`）。
|
||||
> 五层 System Prompt 架构保留；opsxcli 的「personaLayer / capabilityLayer / constraintLayer / fewShotLayer / memoryLayer」五常量在 aiops 中合并为单个 `BuildSystemPrompt()` 函数；角色从「opsxcli 智能运维超级助手」改写为「aiops Agent CLI 智能运维 Agent（Web 版，类似 Claude Code）」。
|
||||
|
||||
## 设计理念
|
||||
|
||||
Prompt 是 LLM Agent 的灵魂。aiops Agent CLI 沿用 opsxcli 的 **五层 System Prompt 架构**，将静态知识与动态记忆分层组装：
|
||||
|
||||
- **Layer 1-4 静态层**：编译期确定，不随运行时变化（角色、安全、工具、工作方式）
|
||||
- **Layer 5 动态层**：运行时由 Evolver 注入历史经验，越用越聪明
|
||||
|
||||
## 五层 System Prompt 架构
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Layer 1: 角色定位 │ ← 我是谁
|
||||
│ 「aiops Agent CLI 智能运维 Agent」 │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Layer 2: 安全规则 │ ← 我必须遵守什么
|
||||
│ 黑名单 / 高危确认 / 优先只读 │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Layer 3: 工具说明 │ ← 我能用什么
|
||||
│ 由 Registry 动态生成（ssh_execute 等） │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Layer 4: 工作方式（ReAct 范式） │ ← 我怎么工作
|
||||
│ 思考 → 行动 → 观察 → 循环 → 收尾 │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Layer 5: 记忆注入 │ ← 我学到了什么（动态）
|
||||
│ Evolver 提供的历史经验 │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## BuildSystemPrompt 函数
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/prompt/prompt.go
|
||||
|
||||
func BuildSystemPrompt(serverInfo, toolDescs, evolveContext string) string {
|
||||
var sb strings.Builder
|
||||
|
||||
// Layer 1: 角色
|
||||
sb.WriteString("你是 aiops 平台的 Agent CLI —— 一个企业级智能运维 Agent，" +
|
||||
"类似 Claude Code / Codex，但运行在 Web 页面上，通过 SSH 工具远程操作真实服务器。\n" +
|
||||
"你的职责是：根据用户的自然语言任务描述，自主在目标服务器上排查故障、安装与配置软件、修复问题，" +
|
||||
"并通过 WebSocket 把每一步思考、执行的命令和输出实时反馈给用户。\n\n")
|
||||
|
||||
// 目标主机（动态片段，但不属于记忆层）
|
||||
if strings.TrimSpace(serverInfo) != "" {
|
||||
sb.WriteString("【目标主机】\n" + serverInfo + "\n\n")
|
||||
}
|
||||
|
||||
// Layer 2: 安全规则
|
||||
sb.WriteString("【安全规则】\n")
|
||||
sb.WriteString("1. 破坏性命令（rm -rf /、mkfs、dd 覆写磁盘等）被严格禁止，绝不执行。\n")
|
||||
sb.WriteString("2. 高危操作（reboot、systemctl restart、kill、卸载软件等）需要用户确认后才能执行。\n")
|
||||
sb.WriteString("3. 排障时优先使用只读命令（df/ps/cat/grep/tail/systemctl status/journalctl）收集信息...\n")
|
||||
sb.WriteString("4. 不要执行任何你不确定后果的命令；宁可多问用户，也不盲目操作。\n\n")
|
||||
|
||||
// Layer 3: 工具（动态生成）
|
||||
if strings.TrimSpace(toolDescs) != "" {
|
||||
sb.WriteString("【可用工具】\n" + toolDescs + "\n\n")
|
||||
}
|
||||
|
||||
// Layer 4: 工作方式（ReAct）
|
||||
sb.WriteString("【工作方式（ReAct 循环）】\n")
|
||||
sb.WriteString("1. 思考：分析当前状态，决定下一步...\n")
|
||||
sb.WriteString("2. 行动：调用 ssh_execute 执行命令（一次只做关键的、可验证的一步）。\n")
|
||||
sb.WriteString("3. 观察：仔细阅读命令输出（含 exit_code，0 表示成功）。\n")
|
||||
sb.WriteString("4. 循环：如果命令失败或问题未解决，分析错误原因，换一种方法重试，直到真正解决。\n")
|
||||
sb.WriteString("5. 收尾：问题解决后，用清晰的中文总结：问题根因、你做了什么、最终结果、后续建议。\n\n")
|
||||
sb.WriteString("【重要】务必真正解决问题，而不是假装解决。每一步都要基于实际命令输出判断，" +
|
||||
"禁止编造不存在的输出。\n\n")
|
||||
|
||||
// Layer 5: 记忆注入（动态）
|
||||
if strings.TrimSpace(evolveContext) != "" {
|
||||
sb.WriteString("【历史经验（来自自进化引擎）】\n" + evolveContext + "\n\n")
|
||||
}
|
||||
|
||||
// 输出要求
|
||||
sb.WriteString("【输出要求】使用简体中文，简洁专业。思考与命令穿插呈现，避免冗长空话。")
|
||||
return sb.String()
|
||||
}
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：
|
||||
> - opsxcli 把五层拆为五个独立常量（`personaLayer` / `capabilityLayer` / `constraintLayer` / `fewShotLayer` / `memoryLayerPrefix`），aiops 合并为单个函数，更紧凑
|
||||
> - opsxcli 有独立的 `BuilderV2` 结构和 `NewBuilderV2WithMemory` 工厂，aiops 直接用函数（Web 场景下不需要构建器状态）
|
||||
> - aiops 移除了独立的 fewShot 示例层，把 ReAct 工作方式说明合并到 Layer 4
|
||||
|
||||
## Layer 1: 角色定位
|
||||
|
||||
> **关键改写**：opsxcli 的角色是「opsxcli 智能运维超级助手」（CLI 工具语境）；aiops 改写为「aiops 平台的 Agent CLI —— 企业级智能运维 Agent，类似 Claude Code / Codex，但运行在 Web 页面上」。
|
||||
|
||||
**设计要点**：
|
||||
|
||||
- **明确类比**：用「类似 Claude Code / Codex」让用户和 LLM 都快速理解定位
|
||||
- **强调 Web 语境**：「运行在 Web 页面上」「通过 SSH 远程操作」「通过 WebSocket 反馈」
|
||||
- **明确职责边界**：排障、安装配置、修复 —— 不是「无所不能的 AI」
|
||||
- **不包含版本号**（与 opsxcli 一致）
|
||||
|
||||
### 目标主机片段
|
||||
|
||||
`serverInfo` 由 controller 构建，注入到 Layer 1 之后：
|
||||
|
||||
```go
|
||||
serverInfo := fmt.Sprintf("主机名: %s | IP: %s:%d | 用户: %s | OS: %s",
|
||||
ac.server.Hostname, ac.server.IP, ac.server.Port, ac.server.Username, ac.server.OS)
|
||||
```
|
||||
|
||||
让 LLM 知道当前操作的是哪台主机、什么系统、用什么用户。
|
||||
|
||||
## Layer 2: 安全规则
|
||||
|
||||
四条硬规则：
|
||||
|
||||
1. **破坏性命令严格禁止**（呼应代码层的黑名单硬拒）
|
||||
2. **高危操作需用户确认**（呼应代码层的 ConfirmFn）
|
||||
3. **排障优先只读命令**（引导 LLM 先收集信息再动手）
|
||||
4. **不确定时不盲目操作**（宁可多问）
|
||||
|
||||
> **注意**：Layer 2 是 Prompt 级别的「软约束引导」，与 `safety.Controller.Check` 的代码级「硬拦截」是不同层面的机制。两者互补：Prompt 引导 LLM 主动避免危险操作，代码层兜底防止 LLM 失控。
|
||||
|
||||
## Layer 3: 工具说明
|
||||
|
||||
由 `core.Agent.buildToolDescriptions()` 动态生成：
|
||||
|
||||
```go
|
||||
func (a *Agent) buildToolDescriptions() string {
|
||||
var sb strings.Builder
|
||||
for _, t := range a.registry.List() {
|
||||
sb.WriteString(fmt.Sprintf("- %s: %s\n", t.Name(), t.Description()))
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
```
|
||||
|
||||
**为什么动态生成？**
|
||||
|
||||
- 工具集可扩展（实现 Tool 接口注册即可），硬编码 Prompt 会与代码脱节
|
||||
- 工具描述本身就是给 LLM 的「使用说明书」，由工具自己提供最准确
|
||||
- `ssh_execute` 的描述会包含具体的目标主机和用户信息（动态拼接）
|
||||
|
||||
输出示例：
|
||||
|
||||
```
|
||||
【可用工具】
|
||||
- ssh_execute: 在远程服务器 192.168.1.100（用户 root）上执行 shell 命令并返回合并的 stdout+stderr 输出与退出码...
|
||||
- analyze_output: 分析一段（可能很长的）命令输出文本：统计行数、提取疑似错误/告警行...
|
||||
```
|
||||
|
||||
## Layer 4: 工作方式（ReAct 范式）
|
||||
|
||||
五步循环：
|
||||
|
||||
1. **思考** —— 分析状态，决定下一步（产出 `thought` 文本）
|
||||
2. **行动** —— 调用 `ssh_execute` 执行命令（一次只做关键的、可验证的一步）
|
||||
3. **观察** —— 仔细阅读输出（含 `exit_code`，0 表示成功）
|
||||
4. **循环** —— 失败则换法重试，直到真正解决
|
||||
5. **收尾** —— 清晰中文总结（根因、做了什么、结果、建议）
|
||||
|
||||
**关键约束**（红线）：
|
||||
|
||||
> 务必真正解决问题，而不是假装解决。每一步都要基于实际命令输出判断，禁止编造不存在的输出。
|
||||
|
||||
这条约束非常重要 —— LLM 有「编造输出」的倾向，明确禁止 + 配合 `exit_code` 信号，能显著降低幻觉。
|
||||
|
||||
## Layer 5: 记忆注入（动态）
|
||||
|
||||
由 `evolver.EvolverEngine.GetContextForPrompt(query)` 提供：
|
||||
|
||||
```go
|
||||
func (e *EvolverEngine) GetContextForPrompt(query string) string {
|
||||
taskType := classifyTask(query, nil)
|
||||
var sb strings.Builder
|
||||
|
||||
// 同类任务的历史经验（优先成功）
|
||||
if exps := e.mem.FindExperiences(taskType, 3); len(exps) > 0 {
|
||||
sb.WriteString(fmt.Sprintf(" 【%s 类历史经验】\n", taskType))
|
||||
for _, exp := range exps {
|
||||
mark := "成功"
|
||||
if !exp.Success { mark = "未成功" }
|
||||
sb.WriteString(fmt.Sprintf(" - (%s) %s\n", mark, exp.Hint))
|
||||
}
|
||||
}
|
||||
// 相关事实
|
||||
if facts := e.mem.RelevantFacts(query, 3); len(facts) > 0 {
|
||||
sb.WriteString(" 【已知事实】\n")
|
||||
for _, f := range facts {
|
||||
sb.WriteString(fmt.Sprintf(" - %s\n", f.Fact))
|
||||
}
|
||||
}
|
||||
// 已知主机
|
||||
if hosts := e.mem.Hosts(); len(hosts) > 0 {
|
||||
sb.WriteString(fmt.Sprintf(" 【已知主机】%s\n", strings.Join(hosts, ", ")))
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
```
|
||||
|
||||
注入示例：
|
||||
|
||||
```
|
||||
【历史经验（来自自进化引擎）】
|
||||
【磁盘空间 类历史经验】
|
||||
- (成功) 完成「磁盘空间」类任务时，工具序列 ssh_execute → analyze_output 最终成功，可作为参考。
|
||||
- (成功) 对于磁盘满问题，先检查大日志文件再清理
|
||||
【已知事实】
|
||||
- 生产 nginx 日志目录是 /var/log/nginx
|
||||
【已知主机】192.168.1.10, 192.168.1.11
|
||||
```
|
||||
|
||||
**设计要点**：
|
||||
|
||||
- 按 `query` 分类后只注入**同类**经验，避免无关信息污染
|
||||
- 优先注入**成功**经验（`FindExperiences` 内部排序）
|
||||
- 限制条数（经验 3 条、事实 3 条），控制 token 开销
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 把记忆层细分为 5.0 事实 / 5.1 经验 / 5.1.5 技能 / 5.2 环境 / 5.3 偏好；aiops 精简为 3 段（经验 / 事实 / 已知主机），剥离了用户偏好（Web 场景下偏好由安全模式等显式配置承载）和技能层（未实现自动 Skill 提炼）。
|
||||
|
||||
## 注入流程
|
||||
|
||||
```
|
||||
core.Agent.Run()
|
||||
│
|
||||
├─ evolveCtx = evolver.GetContextForPrompt(query) ← Layer 5 内容
|
||||
│
|
||||
├─ toolDescs = buildToolDescriptions() ← Layer 3 内容
|
||||
│
|
||||
├─ systemPrompt = prompt.BuildSystemPrompt(
|
||||
│ serverInfo, ← Layer 1 目标主机片段
|
||||
│ toolDescs, ← Layer 3
|
||||
│ evolveCtx, ← Layer 5
|
||||
│ )
|
||||
│
|
||||
└─ messages = [{system: systemPrompt}, {user: query}]
|
||||
```
|
||||
|
||||
## 为什么 Layer 1-4 是静态的？
|
||||
|
||||
- 角色定位和工作方式在编译期确定
|
||||
- 安全规则不应该被动态修改（防止 Evolver 污染安全约束）
|
||||
- 静态内容可以利用 LLM Provider 的 Prompt Caching（减少 token 消耗，部分 Provider 如 Anthropic 支持）
|
||||
- 只有事实/经验需要动态更新
|
||||
|
||||
## 输出要求
|
||||
|
||||
最后一段统一约束输出风格：
|
||||
|
||||
> 使用简体中文，简洁专业。思考与命令穿插呈现，避免冗长空话。
|
||||
|
||||
这与 opsxcli 一致 —— 中文运维语境的统一规范。
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 修改角色描述
|
||||
|
||||
直接修改 `BuildSystemPrompt` 中 Layer 1 的字符串。注意：
|
||||
|
||||
- 不要包含版本号
|
||||
- 明确能力边界（不要吹成「无所不能」）
|
||||
- 场景化描述优于抽象形容
|
||||
|
||||
### 增加新的 Prompt 层
|
||||
|
||||
1. 在 `BuildSystemPrompt` 中增加新的 `sb.WriteString(...)` 片段
|
||||
2. 在本文档更新架构图
|
||||
3. 若是动态层，需在 `Agent.Run` 中准备数据并传入
|
||||
|
||||
### 调整记忆注入策略
|
||||
|
||||
修改 `evolver.GetContextForPrompt`：
|
||||
|
||||
- 增加新的记忆段（如「最近失败的任务」）
|
||||
- 调整条数限制
|
||||
- 改进分类匹配逻辑
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| Prompt 过长导致 token 超限 | Layer 1-4 精简 + Layer 5 按需注入 + 条数限制 |
|
||||
| 记忆注入了无关经验 | `GetContextForPrompt` 按 `task_type` 匹配，不全量注入 |
|
||||
| Layer 1-4 被 Evolver 污染 | 静态层硬编码在函数中，Evolver 只能影响 Layer 5 |
|
||||
| LLM 编造命令输出 | Layer 4 显式禁止 + 输出附 `exit_code` 验证 |
|
||||
| 角色描述含版本号 | 已清理，禁止再加版本号 |
|
||||
| 工具描述与实际工具脱节 | Layer 3 由 Registry 动态生成，永远一致 |
|
||||
|
||||
## 与 opsxcli 的差异总结
|
||||
|
||||
| 维度 | opsxcli | aiops |
|
||||
|------|---------|-------|
|
||||
| 代码组织 | 5 个独立常量 + BuilderV2 结构 | 单个 `BuildSystemPrompt` 函数 |
|
||||
| 角色 | opsxcli 智能运维超级助手（CLI） | aiops Agent CLI（Web 版，类比 Claude Code） |
|
||||
| fewShot 层 | 独立 Layer 4（运维场景示例） | 合并进 Layer 4 工作方式 |
|
||||
| 记忆子层 | 5 个（事实/经验/技能/环境/偏好） | 3 个（经验/事实/已知主机） |
|
||||
| 静态/动态分离 | 严格（BuilderV2.enableMemory 开关） | 严格（函数内 if 判断） |
|
||||
|
||||
思想完全保留（五层架构 + 静态动态分离 + 记忆按需注入），实现更紧凑。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,515 @@
|
||||
# 08 - Evolver 自进化引擎
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/evolver/`）。
|
||||
> **保留**：四层记忆架构（经验/环境/事实/程序）+ 进化循环思想（OBSERVE → ... → PREDICT）+ 异步非阻塞 + 优雅降级。
|
||||
> **精简**：opsxcli 13 步循环 + 3300 行精简为 6 步核心循环 + ~400 行；剥离反射评分、经验整合去重、自动 Skill 提炼等重型子流程。这是有意的精简适配，保留学习能力和注入机制。
|
||||
|
||||
## 包位置
|
||||
|
||||
```
|
||||
backend/pkg/agentcli/evolver/
|
||||
├── engine.go # 进化引擎核心（精简进化循环）
|
||||
└── memory.go # 四层记忆 + JSONL/JSON 文件存储
|
||||
```
|
||||
|
||||
## 设计哲学
|
||||
|
||||
> **让 Agent 越用越聪明** —— 每次任务完成后自动学习经验，优化后续表现。
|
||||
|
||||
Evolver 借鉴 opsxcli 的设计理念：通过经验积累、LLM 反射分析和环境自适应，实现 Agent 的持续自我优化。用户使用越多，Agent 越了解服务器环境、最佳工具组合和已知事实。
|
||||
|
||||
**精简原则**：保留「学习 → 存储 → 注入」的核心闭环，剥离重型分析（评分、整合、Skill 提炼）。精简后的 Evolver 仍是真正的自学习引擎，而非装饰品 —— 它真的会把上次任务的经验存下来，并在下次同类任务时注入 Prompt。
|
||||
|
||||
## 核心数据结构
|
||||
|
||||
### EvolverEngine
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/evolver/engine.go
|
||||
|
||||
type EvolverEngine struct {
|
||||
mem *Memories // 四层记忆集合
|
||||
llm llm.Client // 可选，用于提炼经验/事实（nil 时退化为规则学习）
|
||||
memDir string // 记忆目录（默认 data/agentcli）
|
||||
}
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：剥离了 `minSteps` / `simpleThresh` / `moderateThresh` / `onProgress` 等配置字段；剥离 `reflectionClient` 独立接口（直接用 `llm.Client`）。
|
||||
|
||||
### TaskExecution（任务执行记录）
|
||||
|
||||
每次任务完成后由 `core.Agent.triggerEvolve` 构造：
|
||||
|
||||
```go
|
||||
type TaskExecution struct {
|
||||
Query string // 用户原始查询
|
||||
ToolCalls []ToolCallRecord // 工具调用序列
|
||||
TotalSteps int // 总迭代步数
|
||||
TotalTokens int // 消耗的 token 数
|
||||
Duration time.Duration // 执行耗时
|
||||
Success bool // 是否成功
|
||||
FinalAnswer string // 最终回答
|
||||
Timestamp time.Time // 执行时间
|
||||
ServerHost string // 目标主机（用于环境记忆）
|
||||
}
|
||||
```
|
||||
|
||||
### ToolCallRecord / EvolveResult
|
||||
|
||||
```go
|
||||
type ToolCallRecord struct {
|
||||
ToolName string
|
||||
Args map[string]interface{}
|
||||
Output string
|
||||
Duration time.Duration
|
||||
Success bool
|
||||
RiskLevel int
|
||||
}
|
||||
|
||||
type EvolveResult struct {
|
||||
TaskType string // 自动分类的任务类型
|
||||
LearnedHint string // 学到的经验提示
|
||||
ToolSequence []string // 工具序列
|
||||
ExperienceAdded bool // 是否新增经验
|
||||
Consolidated bool // 是否触发整合（aiops 版保留字段，未实现）
|
||||
}
|
||||
```
|
||||
|
||||
## 精简进化循环（6 步）
|
||||
|
||||
opsxcli 是 13 步（OBSERVE → EXTRACT → REFLECT → SCORE → COMPARE → LEARN → STORE → CONSOLIDATE → PREDICT → ADAPT → MEMORIZE → DISTILL → FEEDBACK），aiops 精简为 6 步核心：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Evolve 6 步核心循环 │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Step 1: OBSERVE ── 观察工具序列 │
|
||||
│ ↓ 提取 ToolSequence（如 ssh → analyze） │
|
||||
│ │
|
||||
│ Step 2: CLASSIFY ── 任务类型分类 │
|
||||
│ ↓ 关键词规则匹配（11 类，无需 LLM） │
|
||||
│ │
|
||||
│ Step 3: LEARN ── 生成经验提示 │
|
||||
│ ↓ LLM 优先提炼一句经验，失败降级规则生成 │
|
||||
│ │
|
||||
│ Step 4: STORE ── 存入经验 + 环境记忆 │
|
||||
│ ↓ experience.jsonl + environment.json │
|
||||
│ │
|
||||
│ Step 5: MEMORIZE ── LLM 提炼持久事实 │
|
||||
│ ↓ 异步，从 FinalAnswer 提炼事实存 factual │
|
||||
│ │
|
||||
│ Step 6: PREDICT ── 注入下次 Prompt │
|
||||
│ ↓ GetContextForPrompt（下次任务开始时） │
|
||||
│ │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 各步骤详解
|
||||
|
||||
#### Step 1: OBSERVE（观察）
|
||||
|
||||
提取工具序列：
|
||||
|
||||
```go
|
||||
for _, tc := range exec.ToolCalls {
|
||||
result.ToolSequence = append(result.ToolSequence, tc.ToolName)
|
||||
}
|
||||
```
|
||||
|
||||
输出如 `["ssh_execute", "analyze_output", "ssh_execute"]`。
|
||||
|
||||
#### Step 2: CLASSIFY（任务分类）
|
||||
|
||||
关键词规则匹配（不调 LLM，零成本）：
|
||||
|
||||
```go
|
||||
func classifyTask(query string, calls []ToolCallRecord) string {
|
||||
text := strings.ToLower(query)
|
||||
for _, c := range calls {
|
||||
if cmd, ok := c.Args["command"].(string); ok {
|
||||
text += " " + strings.ToLower(cmd)
|
||||
}
|
||||
}
|
||||
// 11 类规则匹配
|
||||
rules := []struct{ typ string; kws []string }{
|
||||
{"磁盘空间", []string{"disk", "空间", "df", "du", "inode", "磁盘", "满了"}},
|
||||
{"网络", []string{"network", "网络", "ping", "netstat", "ss ", "端口", "tcp", "dns"}},
|
||||
{"服务管理", []string{"service", "服务", "systemctl", "nginx", "mysql", "redis", "restart"}},
|
||||
{"软件安装", []string{"install", "安装", "yum", "apt", "docker", "部署", "deploy"}},
|
||||
{"进程排查", []string{"process", "进程", "ps ", "kill", "cpu", "top", "卡死"}},
|
||||
{"内存排查", []string{"memory", "内存", "mem", "free", "oom", "swap"}},
|
||||
{"日志排查", []string{"log", "日志", "journalctl", "tail", "grep"}},
|
||||
{"权限问题", []string{"permission", "权限", "chmod", "chown", "denied", "拒绝"}},
|
||||
{"性能调优", []string{"performance", "性能", "负载", "load", "慢", "slow"}},
|
||||
{"配置管理", []string{"config", "配置", "conf", "vim", "sed"}},
|
||||
}
|
||||
// ... 命中即返回，否则 "通用运维"
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**：把 query + 实际命令拼起来分类，比单看 query 更准（用户问「检查 nginx」，实际命令可能是 `systemctl status nginx`，分类为「服务管理」更合理）。
|
||||
|
||||
#### Step 3: LEARN（生成经验提示）
|
||||
|
||||
LLM 优先，失败降级规则：
|
||||
|
||||
```go
|
||||
func (e *EvolverEngine) learnHint(ctx context.Context, exec *TaskExecution, taskType string) string {
|
||||
tools := strings.Join(uniqueStrings(resultToolNames(exec.ToolCalls)), " → ")
|
||||
|
||||
// 尝试用 LLM 提炼一句经验
|
||||
if e.llm != nil {
|
||||
if hint := e.llmLearnHint(ctx, exec, taskType, tools, exec.Success); hint != "" {
|
||||
return hint
|
||||
}
|
||||
}
|
||||
// 降级：规则生成
|
||||
if exec.Success {
|
||||
return fmt.Sprintf("完成「%s」类任务时，工具序列 %s 最终成功，可作为参考。", taskType, tools)
|
||||
}
|
||||
return fmt.Sprintf("尝试「%s」类任务时，工具序列 %s 未成功，下次可换用不同命令或思路。", taskType, tools)
|
||||
}
|
||||
```
|
||||
|
||||
LLM 提炼的 prompt（中文）：
|
||||
|
||||
```
|
||||
你是运维经验提炼器。根据以下任务执行记录，用一句中文（不超过80字）提炼经验提示，
|
||||
说明下次做同类任务的关键要点或推荐工具顺序。只返回经验文本，不要多余解释。
|
||||
任务: <query>
|
||||
工具序列: <tools>
|
||||
结果: 成功/失败
|
||||
```
|
||||
|
||||
**降级策略**：LLM 不可用或超时 → 用规则模板生成（仍然有价值，只是不够精炼）。
|
||||
|
||||
#### Step 4: STORE（存储经验 + 环境记忆）
|
||||
|
||||
```go
|
||||
exp := ExperienceEntry{
|
||||
TaskType: result.TaskType,
|
||||
Query: truncate(exec.Query, 200),
|
||||
Hint: result.LearnedHint,
|
||||
ToolSequence: result.ToolSequence,
|
||||
Success: exec.Success,
|
||||
Timestamp: exec.Timestamp.Unix(),
|
||||
}
|
||||
e.mem.AddExperience(exp)
|
||||
if exec.ServerHost != "" {
|
||||
e.mem.AddHost(exec.ServerHost) // 环境记忆
|
||||
}
|
||||
```
|
||||
|
||||
写入 `data/agentcli/experience.jsonl`（追加）和 `environment.json`（去重合并）。
|
||||
|
||||
#### Step 5: MEMORIZE（LLM 提炼持久事实）
|
||||
|
||||
仅在任务成功 + 有 FinalAnswer + LLM 可用时触发，**异步执行不阻塞**：
|
||||
|
||||
```go
|
||||
if e.llm != nil && exec.Success && exec.FinalAnswer != "" {
|
||||
go e.memorizeFact(ctx, exec) // 异步
|
||||
}
|
||||
```
|
||||
|
||||
LLM 提炼 prompt：
|
||||
|
||||
```
|
||||
从以下运维任务记录中，提炼 1 条值得长期记住的事实（如某主机的固定配置、已知问题、约定）。
|
||||
如果没有明显可沉淀的事实，回复「无」。只返回事实本身，一句话。
|
||||
任务: <query>
|
||||
结论: <final_answer>
|
||||
```
|
||||
|
||||
提炼出的事实存入 `factual.jsonl`。
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 的 MEMORIZE 从执行过程中提取结构化事实（key-value），aiops 简化为让 LLM 自由提炼一句事实。更简单，覆盖面更广。
|
||||
|
||||
#### Step 6: PREDICT（注入下次 Prompt）
|
||||
|
||||
`GetContextForPrompt(query)` 在下次任务开始时被 `core.Agent.Run` 调用：
|
||||
|
||||
```go
|
||||
evolveCtx := a.evolver.GetContextForPrompt(query)
|
||||
systemPrompt := prompt.BuildSystemPrompt(serverInfo, toolDescs, evolveCtx)
|
||||
```
|
||||
|
||||
注入内容会被放入 Prompt Layer 5（详见 [07 - Prompt 构建](07-Prompt构建与记忆注入.md)）。
|
||||
|
||||
## 四层记忆系统
|
||||
|
||||
aiops 保留 opsxcli 的四层记忆架构：
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 四层记忆架构 │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Layer 1: ExperienceMemory（经验层） │
|
||||
│ 任务完成后的经验，按 task_type 分类 │
|
||||
│ 存储: data/agentcli/experience.jsonl │
|
||||
│ │
|
||||
│ Layer 2: EnvironmentMemory（环境层） │
|
||||
│ 已知主机列表 │
|
||||
│ 存储: data/agentcli/environment.json │
|
||||
│ │
|
||||
│ Layer 3: FactualMemory（事实层） │
|
||||
│ LLM 提炼的持久事实 │
|
||||
│ 存储: data/agentcli/factual.jsonl │
|
||||
│ │
|
||||
│ Layer 4: ProceduralMemory（程序层） │
|
||||
│ 程序性知识（接口位，未实现自动 Skill 提炼） │
|
||||
│ 存储: data/agentcli/procedural.jsonl │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Memories 结构
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/evolver/memory.go
|
||||
|
||||
type Memories struct {
|
||||
dir string
|
||||
mu sync.Mutex
|
||||
|
||||
expPath string // experience.jsonl
|
||||
facPath string // factual.jsonl
|
||||
sklPath string // procedural.jsonl
|
||||
envPath string // environment.json
|
||||
}
|
||||
```
|
||||
|
||||
### ExperienceEntry / FactEntry / SkillEntry
|
||||
|
||||
```go
|
||||
type ExperienceEntry struct {
|
||||
TaskType string `json:"task_type"`
|
||||
Query string `json:"query"`
|
||||
Hint string `json:"hint"`
|
||||
ToolSequence []string `json:"tool_sequence"`
|
||||
Success bool `json:"success"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
type FactEntry struct {
|
||||
Fact string `json:"fact"`
|
||||
Source string `json:"source"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
type SkillEntry struct {
|
||||
Name string `json:"name"`
|
||||
When string `json:"when"`
|
||||
Steps []string `json:"steps"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：
|
||||
> - opsxcli 的 `Experience` 有 `SuccessRate` / `UsageCount` / `Tags`（用于整合去重），aiops 简化为 `Success` 布尔（剥离整合逻辑）
|
||||
> - opsxcli 的 `FactEntry` 是 key-value（`Key` / `Value` / `Category`），aiops 简化为单字段 `Fact`（一句话）
|
||||
> - opsxcli 的 `SkillEntry` 有完整的 ID/Version/Triggers/Pitfalls/SuccessRate，aiops 简化为 Name/When/Steps（接口位，未实际使用）
|
||||
|
||||
### 存储格式
|
||||
|
||||
#### experience.jsonl（追加写入）
|
||||
|
||||
```json
|
||||
{"task_type":"磁盘空间","query":"检查磁盘空间","hint":"对于磁盘满问题，先检查大日志文件再清理","tool_sequence":["ssh_execute","analyze_output"],"success":true,"timestamp":1748000000}
|
||||
```
|
||||
|
||||
#### environment.json（整体读写）
|
||||
|
||||
```json
|
||||
{
|
||||
"hosts": ["192.168.1.10", "192.168.1.11"]
|
||||
}
|
||||
```
|
||||
|
||||
#### factual.jsonl（追加写入）
|
||||
|
||||
```json
|
||||
{"fact":"生产 nginx 日志目录是 /var/log/nginx","source":"检查 nginx 启动失败","timestamp":1748000000}
|
||||
```
|
||||
|
||||
### 核心查询方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `AddExperience(e)` | 追加经验 |
|
||||
| `FindExperiences(taskType, n)` | 按类型查找，**优先成功**，取最近 n 条 |
|
||||
| `AddFact(f)` | 追加事实 |
|
||||
| `RelevantFacts(query, n)` | 按 query 关键词匹配事实（双向 Contains） |
|
||||
| `AddHost(host)` | 记录已知主机（去重） |
|
||||
| `Hosts()` | 已知主机列表 |
|
||||
| `CountStats()` | 各层条目数（供审计展示） |
|
||||
|
||||
**`FindExperiences` 的排序策略**：
|
||||
|
||||
```go
|
||||
// 优先成功经验，按时间取最近 n 条
|
||||
successFirst := ... // 过滤 success=true
|
||||
others := ... // 过滤 success=false
|
||||
out := append(pick(successFirst), pick(others)...)
|
||||
```
|
||||
|
||||
让 LLM 优先看到成功的经验。
|
||||
|
||||
## 与 Agent 的集成
|
||||
|
||||
### 初始化与优雅降级
|
||||
|
||||
在 `agentcli.NewEngine` 中：
|
||||
|
||||
```go
|
||||
ev, err := evolver.NewEvolverEngine(coreCfg.MemoryDir, client)
|
||||
if err != nil {
|
||||
ev = nil // 降级：无自学习，不影响主流程
|
||||
}
|
||||
agent := core.NewAgent(client, registry, coreCfg, sc, ev)
|
||||
```
|
||||
|
||||
**降级场景**：
|
||||
|
||||
- 记忆目录无法创建（权限问题）→ `ev = nil`
|
||||
- 此时 Agent 正常运行，只是 Layer 5 为空
|
||||
|
||||
### 异步进化流程
|
||||
|
||||
```
|
||||
用户查询 → core.Agent.Run() ReAct 循环 → 任务完成
|
||||
↓
|
||||
triggerEvolve()（异步 goroutine）
|
||||
↓
|
||||
30s 超时上下文 + panic 恢复
|
||||
↓
|
||||
EvolverEngine.Evolve()
|
||||
↓
|
||||
存入 experience.jsonl / factual.jsonl
|
||||
↓
|
||||
下次 Run() → GetContextForPrompt() → 注入 Layer 5
|
||||
```
|
||||
|
||||
**三层保护**：
|
||||
|
||||
1. **后台 goroutine**：不阻塞用户，答案立即返回
|
||||
2. **30 秒超时**：`context.WithTimeout(ctx, 30*time.Second)`
|
||||
3. **panic 恢复**：`defer func() { _ = recover() }()`
|
||||
|
||||
### 经验注入
|
||||
|
||||
下次任务开始时，`GetContextForPrompt(query)` 按 `task_type` 取相关经验注入 Layer 5：
|
||||
|
||||
```
|
||||
【历史经验（来自自进化引擎）】
|
||||
【磁盘空间 类历史经验】
|
||||
- (成功) 对于磁盘满问题，先检查大日志文件再清理
|
||||
- (成功) 完成「磁盘空间」类任务时，工具序列 ssh_execute → analyze_output 最终成功
|
||||
【已知事实】
|
||||
- 生产 nginx 日志目录是 /var/log/nginx
|
||||
【已知主机】192.168.1.10, 192.168.1.11
|
||||
```
|
||||
|
||||
## 任务分类系统（11 类）
|
||||
|
||||
`classifyTask` 把用户查询 + 实际命令分类为 11 类：
|
||||
|
||||
| 任务类型 | 关键词（部分） |
|
||||
|----------|---------------|
|
||||
| 磁盘空间 | disk / 空间 / df / du / inode / 磁盘 / 满了 |
|
||||
| 网络 | network / 网络 / ping / netstat / ss / 端口 / tcp / dns |
|
||||
| 服务管理 | service / 服务 / systemctl / nginx / mysql / redis / restart |
|
||||
| 软件安装 | install / 安装 / yum / apt / docker / 部署 |
|
||||
| 进程排查 | process / 进程 / ps / kill / cpu / top / 卡死 |
|
||||
| 内存排查 | memory / 内存 / mem / free / oom / swap |
|
||||
| 日志排查 | log / 日志 / journalctl / tail / grep |
|
||||
| 权限问题 | permission / 权限 / chmod / chown / denied / 拒绝 |
|
||||
| 性能调优 | performance / 性能 / 负载 / load / 慢 / slow |
|
||||
| 配置管理 | config / 配置 / conf / vim / sed |
|
||||
| 通用运维 | （兜底） |
|
||||
|
||||
## 创建方式
|
||||
|
||||
```go
|
||||
// 基础引擎（无 LLM 提炼，纯规则学习）
|
||||
engine, _ := evolver.NewEvolverEngine("data/agentcli", nil)
|
||||
|
||||
// 带 LLM 提炼的引擎（推荐）
|
||||
engine, _ := evolver.NewEvolverEngine("data/agentcli", llmClient)
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 有 `NewEvolverEngine` 和 `NewEvolverEngineWithLLM` 两个工厂；aiops 合并为一个，通过 `client` 参数是否为 nil 区分。
|
||||
|
||||
## 统计与监控
|
||||
|
||||
```go
|
||||
func (e *EvolverEngine) GetStats() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"enabled": true,
|
||||
"memory": e.mem.CountStats(), // {experience: N, factual: N, skill: N, hosts: N}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
由 `Engine.EvolveStats()` 暴露，供审计展示。
|
||||
|
||||
## 精简决策说明
|
||||
|
||||
### 剥离了什么
|
||||
|
||||
| opsxcli 步骤 | aiops 处理 | 原因 |
|
||||
|--------------|-----------|------|
|
||||
| Step 2.5 REFLECT（LLM 反射分析） | 合并进 Step 3 LEARN | 单次 LLM 调用同时做「分析 + 提炼」更高效 |
|
||||
| Step 3 SCORE（效率评分） | 剥离 | 评分用于整合决策，aiops 不做整合 |
|
||||
| Step 4 COMPARE（历史对比） | 简化为 `FindExperiences` 查询 | 不需要复杂相似度计算 |
|
||||
| Step 7 CONSOLIDATE（经验整合） | 剥离 | JSONL 追加 + 查询时去重足够，不需要主动合并 |
|
||||
| Step 9.7 DISTILL（自动 Skill 提炼） | 剥离 | Skill 提炼需要复杂条件判断 + 文件管理，价值/复杂比不高 |
|
||||
| Step 10 FEEDBACK（用户反馈消息） | 剥离 | Web 场景下经验学习对用户透明，不需要弹消息 |
|
||||
|
||||
### 保留了什么
|
||||
|
||||
- **四层记忆架构** —— 思想完整保留，只是程序层未实际使用
|
||||
- **OBSERVE → LEARN → STORE → MEMORIZE → PREDICT 闭环** —— 真正的学习与注入
|
||||
- **LLM 提炼 + 规则降级** —— 学习质量有保障
|
||||
- **异步非阻塞 + 优雅降级** —— 工程可靠性
|
||||
- **按 task_type 分类注入** —— 避免无关污染
|
||||
|
||||
精简后的 Evolver 仍是「真正的自学习引擎」，而非装饰品。
|
||||
|
||||
## 设计亮点
|
||||
|
||||
1. **异步非阻塞**：进化在后台 goroutine，不增加用户等待
|
||||
2. **优雅降级**：LLM 失败退化为规则学习，Evolver 初始化失败 Agent 正常运行
|
||||
3. **四层记忆**：经验 + 环境 + 事实 + 程序，覆盖从瞬时到持久的认知链路
|
||||
4. **会话级反馈**：上次任务的经验立即注入下次 Prompt
|
||||
5. **线程安全**：`Memories.mu sync.Mutex` 保护文件读写
|
||||
6. **零 DB 依赖**：纯文件存储，与引擎库「零业务依赖」原则一致
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| 记忆目录权限不足 | `NewEvolverEngine` 返回 error，`NewEngine` 把 ev 设为 nil 降级 |
|
||||
| LLM 提炼经验超时 | 30s 超时 + 降级为规则模板 |
|
||||
| 经验注入污染上下文 | 按 `task_type` 匹配 + 条数限制（3 条） |
|
||||
| 事实记忆累积过多无关项 | LLM prompt 明确「无明显事实回复『无』」+ 不写入 |
|
||||
| 并发写入 JSONL 冲突 | `Memories.mu sync.Mutex` 串行化写入 |
|
||||
| 程序层未实现却被引用 | 当前版本 `procedural.jsonl` 仅作为接口位，`GetContextForPrompt` 不读它 |
|
||||
|
||||
## 与 opsxcli 的差异总结
|
||||
|
||||
| 维度 | opsxcli | aiops |
|
||||
|------|---------|-------|
|
||||
| 进化步骤 | 13 步 | 6 步 |
|
||||
| 代码规模 | ~3300 行 | ~400 行 |
|
||||
| 记忆查询 | 复杂相似度 + 整合去重 | 简单 task_type 匹配 + 时间倒序 |
|
||||
| 经验字段 | SuccessRate / UsageCount / Tags | Success（布尔） |
|
||||
| Skill 提炼 | 自动（Step 9.7） | 未实现（接口位） |
|
||||
| 反射分析 | 独立 Step + JSON 结构 | 合并进 LEARN |
|
||||
| 用户反馈 | Step 10 弹消息 | 剥离（Web 透明） |
|
||||
|
||||
**核心思想保留度**：四层记忆 ✓ / 进化闭环 ✓ / 异步降级 ✓ / 经验注入 ✓。精简的是重型分析，不是学习能力本身。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,468 @@
|
||||
# 09 - 安全系统与工具注册
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/pkg/agentcli/safety/safety.go` + `tools/registry.go` + `tools/risk.go`）。
|
||||
> **保留**：三级安全模式 / 五级风险 / 危险命令黑名单 / AssessBashRisk 动态评估 / Tool 接口 + Registry。
|
||||
> **适配**：确认机制从 CLI 终端 `bufio.Reader` 改为 WebSocket `confirm` 事件 + 前端 `useConfirm()` 弹框；审计日志从文件改为 DB 落库。
|
||||
|
||||
## 设计理念
|
||||
|
||||
安全系统是运维 Agent 的生命线。aiops Agent CLI 安全系统遵循两个核心原则：
|
||||
|
||||
1. **默认安全**：balanced 模式下，high+ 操作需要确认，覆盖 95% 日常运维
|
||||
2. **可审计**：每次工具调用都通过 EventCallback 落库，事后可追溯
|
||||
|
||||
工具注册系统遵循**工具化思维**：万物皆 Tool，实现接口即可扩展。
|
||||
|
||||
---
|
||||
|
||||
## Part 1: 安全系统
|
||||
|
||||
### 架构总览
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ safety.Controller │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ risk.go │ │ controller.go │ │
|
||||
│ │ （在 tools 包）│ │ （在 safety 包）│ │
|
||||
│ │ 黑名单 + 分级 │ │ 阈值 + ConfirmFn│ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ Safety Modes: │
|
||||
│ strict → medium+ 确认 │
|
||||
│ balanced → high+ 确认（默认） │
|
||||
│ permissive → critical 仅处理 │
|
||||
└────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：opsxcli 把风险评估和审计都放在 `safety/` 包；aiops 为避免 `tools` ↔ `safety` 循环依赖，把 `risk.go`（黑名单 + AssessBashRisk）置于 `tools` 包，由 `ssh_execute` 的 `DynamicRiskTool` 直接调用；`safety` 包只做「是否需确认」的策略。
|
||||
|
||||
### Controller 结构
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/safety/safety.go
|
||||
|
||||
type Controller struct {
|
||||
mode Mode // 当前安全模式
|
||||
confirmFn ConfirmFn // 确认回调（controller 注入：推 WS confirm + 阻塞等回传）
|
||||
autoApprove bool // 自动批准（仅测试用，生产禁用）
|
||||
}
|
||||
```
|
||||
|
||||
> 与 opsxcli 的差异：剥离 `reader *bufio.Reader`（CLI 终端交互）和 `history []ExecutionRecord`（内存审计历史），改为通过 EventCallback 落库 DB；剥离 `auditLog *AuditLogWriter`（文件审计）。
|
||||
|
||||
### ConfirmFn —— Web 版的确认机制
|
||||
|
||||
```go
|
||||
type ConfirmFn func(toolName string, args map[string]interface{}, risk tools.RiskLevel) (bool, error)
|
||||
```
|
||||
|
||||
controller 实现的 `confirmFn`：
|
||||
|
||||
```go
|
||||
// backend/controller/agent_cli.go
|
||||
|
||||
func (ac *agentConn) confirmFn(toolName string, args map[string]interface{}, risk tools.RiskLevel) (bool, error) {
|
||||
confirmID := fmt.Sprintf("cf-%d", time.Now().UnixNano())
|
||||
cmd, _ := args["command"].(string)
|
||||
// 1. 推 WS confirm 事件（前端 useConfirm 弹框）
|
||||
ac.write(wsEvent{
|
||||
Type: "confirm", ConfirmID: confirmID,
|
||||
ToolName: toolName, Command: cmd, Risk: risk.Display(), ToolArgs: args,
|
||||
})
|
||||
|
||||
// 2. 注册 channel 等待前端回传
|
||||
ch := make(chan bool, 1)
|
||||
ac.cfMu.Lock()
|
||||
ac.confirms[confirmID] = ch
|
||||
ac.cfMu.Unlock()
|
||||
|
||||
// 3. 阻塞等待（5 分钟超时）
|
||||
select {
|
||||
case approved := <-ch:
|
||||
return approved, nil
|
||||
case <-time.After(5 * time.Minute):
|
||||
ac.delConfirm(confirmID)
|
||||
return false, fmt.Errorf("确认超时")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
前端处理（`AgentCLI.tsx`）：
|
||||
|
||||
```tsx
|
||||
case 'confirm': {
|
||||
const ok = await confirm({
|
||||
title: '确认执行高危命令',
|
||||
description: `即将执行：${ev.command}`,
|
||||
confirmText: '确认执行',
|
||||
});
|
||||
wsRef.current?.send(JSON.stringify({
|
||||
type: ok ? 'confirm' : 'deny',
|
||||
confirm_id: ev.confirm_id,
|
||||
}));
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
这是「Web 版 CLI 终端确认」的完整替代 —— 用户在浏览器看到弹框，点确认/拒绝，结果通过 WebSocket 回传解锁引擎。
|
||||
|
||||
### 三级安全模式
|
||||
|
||||
```go
|
||||
const (
|
||||
ModeStrict Mode = "strict" // medium+ 需确认
|
||||
ModeBalanced Mode = "balanced" // high+ 需确认（默认）
|
||||
ModePermissive Mode = "permissive" // 仅 critical 处理
|
||||
)
|
||||
```
|
||||
|
||||
| 模式 | 需要确认的等级 | 适用场景 |
|
||||
|------|---------------|----------|
|
||||
| `strict` | medium 及以上 | 生产环境、关键主机、新手操作 |
|
||||
| `balanced`（默认） | high 及以上 | 日常运维 |
|
||||
| `permissive` | 仅 critical | 测试环境、自动化脚本 |
|
||||
|
||||
阈值映射：
|
||||
|
||||
```go
|
||||
func (c *Controller) riskThreshold() tools.RiskLevel {
|
||||
switch c.mode {
|
||||
case ModeStrict: return tools.RiskMedium
|
||||
case ModePermissive: return tools.RiskCritical
|
||||
default: return tools.RiskHigh
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 五级风险评估
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/registry.go
|
||||
|
||||
const (
|
||||
RiskSafe RiskLevel = iota // 0 - 只读（cat, grep, df, ps）
|
||||
RiskLow // 1 - 低风险（mkdir, touch）
|
||||
RiskMedium // 2 - 中风险（chmod, 文件修改）
|
||||
RiskHigh // 3 - 高风险（ssh_execute, 服务控制）
|
||||
RiskCritical // 4 - 危险（rm -rf /, mkfs, dd, 数据删除）
|
||||
)
|
||||
```
|
||||
|
||||
每级都有中文显示（`Display()`）：
|
||||
|
||||
```go
|
||||
case RiskSafe: return "安全"
|
||||
case RiskLow: return "低风险"
|
||||
case RiskMedium: return "中风险"
|
||||
case RiskHigh: return "高风险"
|
||||
case RiskCritical: return "危险"
|
||||
```
|
||||
|
||||
前端在 `tool_call` 事件中拿到 `risk` 字段，渲染为风险标签。
|
||||
|
||||
### 危险命令黑名单（硬红线）
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/risk.go
|
||||
|
||||
var dangerousCommands = []string{
|
||||
// 文件系统毁灭性操作
|
||||
"rm -rf /", "rm -rf /*", "rm -rf /bin", "rm -rf /boot", "rm -rf /etc",
|
||||
"rm -rf /home", "rm -rf /lib", "rm -rf /lib64", "rm -rf /proc", "rm -rf /root",
|
||||
"rm -rf /sbin", "rm -rf /sys", "rm -rf /usr", "rm -rf /var",
|
||||
// 磁盘格式化
|
||||
"mkfs", "mkfs.ext", "mkfs.xfs", "mkfs.btrfs", "mkfs.vfat",
|
||||
// 磁盘覆写
|
||||
"dd if=/dev/zero", "dd if=/dev/random", "dd if=/dev/urandom",
|
||||
// Fork bomb
|
||||
":(){ :|:& };:", ":() { : | : & }; :",
|
||||
// 设备重定向
|
||||
"> /dev/sda", "> /dev/sdb", "> /dev/sdc", "> /dev/hda",
|
||||
// 数据销毁
|
||||
"mv / /dev/null", "mv /* /dev/null",
|
||||
// 权限破坏
|
||||
"chmod -R 000 /", "chmod -R 777 /",
|
||||
// 服务自毁
|
||||
"systemctl stop ssh", "systemctl disable ssh", "kill -9 1",
|
||||
// 防火墙清空
|
||||
"iptables -F", "iptables --flush",
|
||||
}
|
||||
```
|
||||
|
||||
**特殊检测**：`rm -rf` + 根目录路径（即使不在黑名单字面中）：
|
||||
|
||||
```go
|
||||
if strings.HasPrefix(lower, "rm") && strings.Contains(lower, "-rf") && containsRootPath(lower) {
|
||||
return true, "rm -rf 包含根目录路径"
|
||||
}
|
||||
```
|
||||
|
||||
`containsRootPath` 检测 `/boot`、`/etc`、`/usr`、`/var` 等系统目录。
|
||||
|
||||
### Check 策略
|
||||
|
||||
```go
|
||||
func (c *Controller) Check(tool tools.Tool, args map[string]interface{}) (bool, error) {
|
||||
risk := assessToolRisk(tool, args)
|
||||
|
||||
// 1. 黑名单硬红线：绝不允许（不可确认放行）
|
||||
if risk >= tools.RiskCritical {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
// 2. 未达阈值或自动批准：直接放行
|
||||
if c.autoApprove || risk < c.riskThreshold() {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
// 3. 达阈值：请求用户确认
|
||||
if c.confirmFn == nil {
|
||||
return false, nil // 无确认回调时保守拒绝（Web 场景应始终注入 confirmFn）
|
||||
}
|
||||
return c.confirmFn(tool.Name(), args, risk)
|
||||
}
|
||||
```
|
||||
|
||||
**三层策略**：
|
||||
|
||||
1. **硬红线**（Critical）：黑名单命令直接拒绝，**不可被确认放行**
|
||||
2. **阈值放行**：低于模式阈值的操作直接执行
|
||||
3. **用户确认**（达阈值）：调 `confirmFn` 推 WS 弹框等用户决定
|
||||
|
||||
### AssessBashRisk 动态评估
|
||||
|
||||
```go
|
||||
func AssessBashRisk(command string) RiskLevel {
|
||||
// 1. 黑名单精确匹配 → Critical
|
||||
if isDangerous, _ := IsDangerousCommand(command); isDangerous {
|
||||
return RiskCritical
|
||||
}
|
||||
// 2. 纯只读命令 → Safe
|
||||
if isReadOnlyCommand(lower) {
|
||||
return RiskSafe
|
||||
}
|
||||
// 3. 组合命令（&& || | ;）→ 取子命令最高风险
|
||||
if isCompound(lower) {
|
||||
return assessCompoundCommand(lower)
|
||||
}
|
||||
// 4. 单命令分类
|
||||
isSudo := strings.HasPrefix(lower, "sudo ")
|
||||
return assessSingleCommand(strings.TrimPrefix(lower, "sudo "), isSudo)
|
||||
}
|
||||
```
|
||||
|
||||
### 命令分类表
|
||||
|
||||
| 类别 | 命令示例 | 风险等级 |
|
||||
|------|---------|---------|
|
||||
| 只读（Safe） | cat, grep, awk, sed, head, tail, ps, top, df, du, free, uptime, uname, hostname, ifconfig, ip addr, netstat, ss, ls, pwd, who, w, last, vmstat, iostat, lsof, find, which, file, stat, date, echo, id, whoami, dmesg, systemctl status, journalctl, lsblk, mount | Safe |
|
||||
| 修改（Low/Medium） | cp, mv, mkdir, rmdir, touch, chmod, chown, chgrp, ln, tar, gzip, gunzip, zip, unzip, rsync, tee | Low（sudo 时 Medium） |
|
||||
| 高危（Medium/High） | rm, dd, shutdown, reboot, halt, poweroff, init, systemctl restart/stop/start, kill, killall, pkill, userdel, groupdel, fdisk, parted, mkfs | Medium（sudo 时 High） |
|
||||
| 危险（Critical） | rm -rf /, mkfs, dd if=/dev/zero, fork bomb, > /dev/sda, chmod -R 000 / | Critical（硬拒） |
|
||||
|
||||
### sudo 提升
|
||||
|
||||
`sudo` 会让风险等级 +1（最高到 Critical 前）：
|
||||
|
||||
```go
|
||||
// assessSingleCommand
|
||||
if isSudo {
|
||||
return RiskHigh // 高危命令 + sudo → High
|
||||
}
|
||||
return RiskMedium // 高危命令无 sudo → Medium
|
||||
```
|
||||
|
||||
### 组合命令取最高
|
||||
|
||||
```go
|
||||
// assessCompoundCommand: 拆分 && || | ; 后取子命令最高风险
|
||||
// "df -h && rm /tmp/file" → max(Safe, Medium) = Medium
|
||||
// "cat /etc/passwd; rm -rf /tmp" → max(Safe, Low) = Low
|
||||
```
|
||||
|
||||
### 审计落库（替代文件审计）
|
||||
|
||||
> opsxcli 把审计写到 `~/.opsxcli/audit/audit.log`；aiops 直接走 DB（`agent_cli_messages` 表），多用户场景下可按 user_id / session_id 查询。
|
||||
|
||||
controller 的 `onEvent` 回调把每个 `tool_call` / `tool_result` 落库：
|
||||
|
||||
```go
|
||||
case core.EventToolCall:
|
||||
argsJSON, _ := json.Marshal(e.ToolArgs)
|
||||
ac.persistMsg(sid, e.Round, "tool_call", "tool", "",
|
||||
e.ToolName, string(argsJSON), "", e.Risk, false, "", 0)
|
||||
case core.EventToolResult:
|
||||
ac.persistMsg(sid, e.Round, "tool_result", "tool", e.Output,
|
||||
e.ToolName, "", "", "", e.Success, e.Duration, 0)
|
||||
```
|
||||
|
||||
每条记录包含：工具名、参数 JSON、风险等级、成败、耗时、轮次、会话 ID、用户 ID（通过 session 关联）。前端「会话历史」页面可完整回放。
|
||||
|
||||
---
|
||||
|
||||
## Part 2: 工具注册系统
|
||||
|
||||
### Registry 注册中心
|
||||
|
||||
```go
|
||||
// backend/pkg/agentcli/tools/registry.go
|
||||
|
||||
type Registry struct {
|
||||
tools map[string]Tool
|
||||
mu sync.RWMutex
|
||||
}
|
||||
```
|
||||
|
||||
核心方法：
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `NewRegistry()` | 创建空注册中心 |
|
||||
| `Register(tool)` | 注册工具（线程安全） |
|
||||
| `Get(name)` | 按名获取工具（LLM 调用时按名查找） |
|
||||
| `List()` | 列出所有工具 |
|
||||
| `ToLLMTools()` | 转换为 OpenAI function calling 格式 |
|
||||
|
||||
### Tool 接口（5 方法）
|
||||
|
||||
```go
|
||||
type Tool interface {
|
||||
Name() string
|
||||
Description() string
|
||||
Parameters() map[string]interface{} // JSON Schema
|
||||
RiskLevel() RiskLevel
|
||||
Execute(ctx context.Context, args map[string]interface{}) (*Result, error)
|
||||
}
|
||||
```
|
||||
|
||||
### DynamicRiskTool 扩展接口
|
||||
|
||||
```go
|
||||
type DynamicRiskTool interface {
|
||||
Tool
|
||||
RiskLevelForArgs(args map[string]interface{}) RiskLevel
|
||||
}
|
||||
```
|
||||
|
||||
安全控制器 `Check` 时优先调用动态评估：
|
||||
|
||||
```go
|
||||
func assessToolRisk(tool tools.Tool, args map[string]interface{}) tools.RiskLevel {
|
||||
if dt, ok := tool.(tools.DynamicRiskTool); ok {
|
||||
return dt.RiskLevelForArgs(args) // 动态优先
|
||||
}
|
||||
return tool.RiskLevel()
|
||||
}
|
||||
```
|
||||
|
||||
### Result 结构
|
||||
|
||||
```go
|
||||
type Result struct {
|
||||
Success bool `json:"success"`
|
||||
Output string `json:"output"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
### 参数解析辅助
|
||||
|
||||
```go
|
||||
func StringParam(args map[string]interface{}, key string) string
|
||||
func IntParam(args map[string]interface{}, key string) int // 兼容 int/float64/int64
|
||||
```
|
||||
|
||||
LLM 返回的 JSON 参数反序列化后，数字可能是 `float64`（JSON 原生），`IntParam` 统一处理。
|
||||
|
||||
### 已注册工具一览
|
||||
|
||||
| 工具 | 静态风险 | 动态风险 | 功能 |
|
||||
|------|---------|---------|------|
|
||||
| `ssh_execute` | High | Safe~Critical | 远程命令执行（DynamicRiskTool） |
|
||||
| `analyze_output` | Safe | — | 输出分析（纯文本，只读） |
|
||||
|
||||
详细设计见 [05 - Builtin 内置工具](05-Builtin内置命令.md)。
|
||||
|
||||
> 与 opsxcli 的差异：剥离了 `local_bash` / `scp_transfer` / `file_read` / `file_search` 四个工具；剥离 SSH 连接池（aiops 直接用 `pkg/remoteexec`，无连接池需求）；剥离 `Closer` 接口（Web 工具无资源需释放）。
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新工具
|
||||
|
||||
```go
|
||||
// 1. 实现 Tool 接口（必要时实现 DynamicRiskTool）
|
||||
type MyTool struct{}
|
||||
func (t *MyTool) Name() string { return "my_tool" }
|
||||
func (t *MyTool) Description() string { return "我的工具" }
|
||||
func (t *MyTool) Parameters() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"target": map[string]interface{}{"type": "string", "description": "目标"},
|
||||
},
|
||||
"required": []string{"target"},
|
||||
}
|
||||
}
|
||||
func (t *MyTool) RiskLevel() tools.RiskLevel { return tools.RiskMedium }
|
||||
func (t *MyTool) Execute(ctx context.Context, args map[string]interface{}) (*tools.Result, error) {
|
||||
// 实现
|
||||
return &tools.Result{Success: true, Output: "done"}, nil
|
||||
}
|
||||
|
||||
// 2. 在 agentcli.NewEngine 中注册
|
||||
registry.Register(&MyTool{})
|
||||
```
|
||||
|
||||
### 扩展危险命令黑名单
|
||||
|
||||
修改 `tools/risk.go` 的 `dangerousCommands` 切片：
|
||||
|
||||
```go
|
||||
var dangerousCommands = []string{
|
||||
// ... 现有
|
||||
"your-critical-command",
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义确认逻辑
|
||||
|
||||
controller 的 `confirmFn` 可对接企业审批系统（如先走工单再确认）：
|
||||
|
||||
```go
|
||||
engine.SetConfirmFn(func(toolName string, args map[string]interface{}, risk tools.RiskLevel) (bool, error) {
|
||||
// 1. 推 WS 弹框让用户初步确认
|
||||
// 2. 高危场景额外对接审批工单系统
|
||||
// 3. 返回最终批准结果
|
||||
})
|
||||
```
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| 忘记设置 RiskLevel 导致误判 | 默认按接口返回值，高危工具必须显式声明 |
|
||||
| 高危工具未实现 DynamicRiskTool | 静态等级无法反映参数差异，必须实现动态评估 |
|
||||
| 黑名单只看前缀匹配 | `IsDangerousCommand` 同时做精确匹配 + `rm -rf` 根路径特殊检测 |
|
||||
| 工具 Execute 无超时 | `Config.ToolTimeout=120s` 兜底（`context.WithTimeout`） |
|
||||
| 确认回调无超时 | controller 的 `confirmFn` 内置 5 分钟超时 |
|
||||
| 黑名单可被确认放行 | Check 策略第一层 Critical 直接 `return false, nil`，不走 confirmFn |
|
||||
| LLM 编造工具名 | `registry.Get` 找不到时返回 observation「工具未找到」，LLM 自动换法 |
|
||||
| 参数 JSON 解析失败 | `json.Unmarshal` 失败时返回 observation「参数解析失败」，不 panic |
|
||||
|
||||
## 与 opsxcli 的差异总结
|
||||
|
||||
| 维度 | opsxcli | aiops |
|
||||
|------|---------|-------|
|
||||
| 确认机制 | `bufio.Reader` CLI 终端交互 | WebSocket `confirm` 事件 + 前端 `useConfirm()` 弹框 |
|
||||
| 审计日志 | 文件 `~/.opsxcli/audit/audit.log` | DB 表 `agent_cli_messages` |
|
||||
| 风险评估位置 | `safety/risk.go` | `tools/risk.go`（避免循环依赖） |
|
||||
| 内存审计历史 | `history []ExecutionRecord`（上限 1000 FIFO） | 剥离（直接走 DB） |
|
||||
| 工具集 | 6 个 | 2 个 |
|
||||
| SSH 连接池 | 有（`ssh_pool.go`） | 剥离（用 `pkg/remoteexec`） |
|
||||
| Closer 接口 | 有 | 剥离 |
|
||||
|
||||
安全核心（三级模式 / 五级风险 / 黑名单 / 动态评估）完全保留，差异仅在确认机制和审计载体。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -0,0 +1,388 @@
|
||||
# 10 - 会话管理
|
||||
|
||||
> 本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（`backend/model/agent_cli.go` + `controller/agent_cli.go`）。
|
||||
> **核心改造**：opsxcli 用本地 JSONL 文件存储会话（单用户 CLI 场景）；aiops 用 **GORM 数据库表**存储会话与消息，支持多用户并发、按 user_id 隔离、REST 查询与历史回放。
|
||||
|
||||
## 设计理念
|
||||
|
||||
- **会话管理**：Agent 引擎本身无状态（每次任务独立），所有对话过程持久化到会话层，支持历史回溯、审计、断点排查
|
||||
- **多用户隔离**：Web 场景下多个用户同时使用 Agent CLI，会话必须按 user_id 隔离
|
||||
- **结构化查询**：会话需要列表、筛选、删除等业务操作，必须走 DB 而非文件
|
||||
|
||||
> 为什么改用 DB？opsxcli 是 CLI 工具，单用户、单机使用，JSONL 文件够用且零依赖；aiops 是 Web 平台，多用户并发、需要列表查询和按主机/用户筛选、需要与其他业务表（Server、User）关联 —— DB 是必然选择。
|
||||
|
||||
## 架构总览
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ REST + WebSocket │
|
||||
│ /ws/agent-cli (WebSocket 推流) │
|
||||
│ /aiops/agent-cli/* (REST 会话管理) │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ controller/agent_cli.go │
|
||||
│ AgentCLIHandler │
|
||||
│ ├─ Run (WebSocket) │
|
||||
│ ├─ ListSessions / GetSession / DeleteSession │
|
||||
│ └─ agentConn (单连接运行态) │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ model/agent_cli.go (GORM) │
|
||||
│ AgentCLISession (agent_cli_sessions 表) │
|
||||
│ AgentCLIMessage (agent_cli_messages 表) │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ MySQL / SQLite (aiops 既有 DB) │
|
||||
└────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心数据模型
|
||||
|
||||
### AgentCLISession（会话）
|
||||
|
||||
```go
|
||||
// backend/model/agent_cli.go
|
||||
|
||||
type AgentCLISession struct {
|
||||
ID uint `gorm:"primarykey" json:"id"`
|
||||
UserID uint `gorm:"index" json:"user_id"` // 发起用户（隔离）
|
||||
ServerID uint `gorm:"index" json:"server_id"` // 目标主机
|
||||
ServerName string `gorm:"size:128" json:"server_name"` // 主机名快照
|
||||
ServerHost string `gorm:"size:64" json:"server_host"` // 主机 IP 快照
|
||||
Title string `gorm:"size:255" json:"title"` // 任务标题（query 截断）
|
||||
Status string `gorm:"size:32;default:running" json:"status"` // running/done/aborted/error
|
||||
Provider string `gorm:"size:50" json:"provider"` // LLM 提供商
|
||||
Model string `gorm:"size:100" json:"model"` // 模型名
|
||||
Rounds int `json:"rounds"` // ReAct 轮次
|
||||
TotalTokens int `json:"total_tokens"` // token 消耗
|
||||
Duration int64 `json:"duration"` // 耗时（毫秒）
|
||||
Error string `gorm:"type:text" json:"error,omitempty"` // 错误信息
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
func (AgentCLISession) TableName() string { return "agent_cli_sessions" }
|
||||
```
|
||||
|
||||
**设计要点**：
|
||||
|
||||
- **`UserID` 索引**：多用户隔离的核心，所有查询都按 user_id 过滤
|
||||
- **`ServerID` + `ServerName` + `ServerHost`**：关联主机的同时保存快照（主机 later 被删/改名时历史仍可读）
|
||||
- **`Status` 四态**：`running`（进行中）/ `done`（完成）/ `aborted`（用户中断）/ `error`（出错或达最大轮次）
|
||||
- **`Title`**：query 截断到 60 字符，作为会话列表的显示标题
|
||||
|
||||
### AgentCLIMessage（消息）
|
||||
|
||||
```go
|
||||
type AgentCLIMessage struct {
|
||||
ID uint `gorm:"primarykey" json:"id"`
|
||||
SessionID uint `gorm:"index;not null" json:"session_id"`
|
||||
Round int `json:"round"` // ReAct 轮次
|
||||
Type string `gorm:"size:32" json:"type"` // thought/tool_call/tool_result/done/error/session
|
||||
Role string `gorm:"size:32" json:"role"` // user/assistant/tool
|
||||
Content string `gorm:"type:text" json:"content"` // 思考文本/最终答案
|
||||
ToolName string `gorm:"size:64" json:"tool_name"` // 工具名
|
||||
ToolArgs string `gorm:"type:text" json:"tool_args"` // 工具参数 JSON
|
||||
ToolOutput string `gorm:"type:text" json:"tool_output"` // 工具输出
|
||||
Risk string `gorm:"size:32" json:"risk"` // 风险等级
|
||||
Success bool `json:"success"`
|
||||
Duration string `gorm:"size:32" json:"duration"` // 工具耗时
|
||||
Tokens int `json:"tokens"`
|
||||
CreatedAt time.Time `gorm:"index" json:"created_at"`
|
||||
}
|
||||
|
||||
func (AgentCLIMessage) TableName() string { return "agent_cli_messages" }
|
||||
```
|
||||
|
||||
**消息类型映射引擎事件**：
|
||||
|
||||
| Event.Type | DB Type | DB Role | Content | ToolName | ToolOutput |
|
||||
|------------|---------|---------|---------|----------|------------|
|
||||
| 用户输入 | (无 Type) | user | query | — | — |
|
||||
| `thought` | thought | assistant | AI 思考文本 | — | — |
|
||||
| `tool_call` | tool_call | tool | (空) | 工具名 | (空，Args 在 ToolArgs) |
|
||||
| `tool_result` | tool_result | tool | 输出 | 工具名 | 输出（冗余便于查询） |
|
||||
| `done` | done | assistant | 最终答案 | — | — |
|
||||
| `error` | error | assistant | 错误信息 | — | — |
|
||||
| `progress` | — | — | — | — | — |（不入库，太频繁）
|
||||
|
||||
## 会话生命周期
|
||||
|
||||
```
|
||||
WebSocket start {query}
|
||||
│
|
||||
▼
|
||||
startTask
|
||||
├─ 创建 AgentCLISession (status=running)
|
||||
├─ 存用户消息 (role=user, content=query)
|
||||
├─ 构建 Engine、注入 Callback
|
||||
└─ go engine.Run(ctx, query, serverInfo)
|
||||
│
|
||||
│ 每个事件触发 onEvent → 落库 agent_cli_messages
|
||||
│ ├─ thought → persistMsg(type=thought, role=assistant)
|
||||
│ ├─ tool_call → persistMsg(type=tool_call, role=tool, args, risk)
|
||||
│ ├─ tool_result → persistMsg(type=tool_result, role=tool, output, success)
|
||||
│ ├─ done → persistMsg(type=done, role=assistant, answer, tokens)
|
||||
│ └─ error → persistMsg(type=error, role=assistant, message)
|
||||
│
|
||||
▼
|
||||
finish (更新 session.status / rounds / duration / error)
|
||||
├─ ctx.Err() != nil → status=aborted
|
||||
├─ err != nil → status=error
|
||||
└─ 否则 → status=done
|
||||
```
|
||||
|
||||
## controller 实现
|
||||
|
||||
### startTask（创建会话）
|
||||
|
||||
```go
|
||||
// backend/controller/agent_cli.go
|
||||
|
||||
func (ac *agentConn) startTask(sshCfg remoteexec.SSHConfig, llmCfg model.LLMConfig, query string) {
|
||||
ac.abort() // 取消上一次任务
|
||||
|
||||
// 1. 创建 DB 会话
|
||||
title := query
|
||||
if r := []rune(title); len(r) > 60 {
|
||||
title = string(r[:60]) + "..."
|
||||
}
|
||||
sess := &model.AgentCLISession{
|
||||
UserID: ac.userID, ServerID: ac.server.ID,
|
||||
ServerName: ac.server.Hostname, ServerHost: ac.server.IP,
|
||||
Title: title, Status: "running",
|
||||
Provider: llmCfg.Provider, Model: llmCfg.Model,
|
||||
}
|
||||
ac.db.Create(sess)
|
||||
ac.session = sess
|
||||
|
||||
// 2. 存用户消息
|
||||
ac.persistMsg(sess.ID, 0, "user", "user", query, "", "", "", "", false, "", 0)
|
||||
|
||||
// 3. 构建 Engine
|
||||
engine, _ := agentcli.NewEngine(...)
|
||||
engine.SetCallback(ac.onEvent)
|
||||
engine.SetConfirmFn(ac.confirmFn)
|
||||
|
||||
// 4. 启动 ReAct 循环（goroutine）
|
||||
go func() {
|
||||
defer engine.Close()
|
||||
_, err := engine.Run(ctx, query, serverInfo)
|
||||
// ... finish
|
||||
}()
|
||||
}
|
||||
```
|
||||
|
||||
### onEvent（事件落库 + 推 WS）
|
||||
|
||||
```go
|
||||
func (ac *agentConn) onEvent(e core.Event) {
|
||||
ev := wsEvent{...} // 序列化
|
||||
if ac.session != nil {
|
||||
ev.SessionID = ac.session.ID
|
||||
}
|
||||
ac.write(ev) // 推 WS
|
||||
|
||||
// 持久化（progress 不入库）
|
||||
if ac.session == nil { return }
|
||||
sid := ac.session.ID
|
||||
switch e.Type {
|
||||
case core.EventThought:
|
||||
ac.persistMsg(sid, e.Round, "thought", "assistant", e.Thought, ...)
|
||||
case core.EventToolCall:
|
||||
argsJSON, _ := json.Marshal(e.ToolArgs)
|
||||
ac.persistMsg(sid, e.Round, "tool_call", "tool", "", e.ToolName, string(argsJSON), "", e.Risk, ...)
|
||||
case core.EventToolResult:
|
||||
ac.persistMsg(sid, e.Round, "tool_result", "tool", e.Output, e.ToolName, "", "", "", e.Success, e.Duration, 0)
|
||||
case core.EventDone:
|
||||
ac.persistMsg(sid, e.Round, "done", "assistant", e.Answer, ..., true, "", e.Tokens)
|
||||
case core.EventError:
|
||||
ac.persistMsg(sid, e.Round, "error", "assistant", e.Message, ...)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### finish（结束会话）
|
||||
|
||||
```go
|
||||
func (ac *agentConn) finish(sess *model.AgentCLISession, status, errMsg string, rounds int, dur time.Duration) {
|
||||
// 推 WS 结束事件
|
||||
ac.write(wsEvent{Type: status, SessionID: sess.ID, Message: errMsg, Round: rounds})
|
||||
// 更新 DB
|
||||
updates := map[string]interface{}{
|
||||
"status": status, "rounds": rounds, "duration": dur.Milliseconds(),
|
||||
}
|
||||
if errMsg != "" {
|
||||
updates["error"] = errMsg
|
||||
}
|
||||
ac.db.Model(sess).Updates(updates)
|
||||
}
|
||||
```
|
||||
|
||||
### REST 接口
|
||||
|
||||
```go
|
||||
// backend/router/routes.go
|
||||
|
||||
agentCLIGroup := authorized.Group("/aiops/agent-cli")
|
||||
{
|
||||
agentCLIGroup.GET("/sessions", agentCLIHandler.ListSessions) // 列表（按 user_id 过滤）
|
||||
agentCLIGroup.GET("/sessions/:id", agentCLIHandler.GetSession) // 详情（含全部消息）
|
||||
agentCLIGroup.DELETE("/sessions/:id", agentCLIHandler.DeleteSession) // 删除（校验归属）
|
||||
}
|
||||
```
|
||||
|
||||
前端 `frontend/src/api/agentCli.ts` 调用这些接口实现「会话历史」页面：
|
||||
|
||||
- 列表展示用户的所有会话（标题、主机、状态、耗时、token）
|
||||
- 点击某会话查看完整 ReAct 推理过程（thought / tool_call / tool_result 时间线）
|
||||
- 删除会话（连带消息）
|
||||
|
||||
## WebSocket 协议
|
||||
|
||||
### 后端 → 前端（wsEvent）
|
||||
|
||||
```go
|
||||
type wsEvent struct {
|
||||
Type string `json:"type"` // session/thought/tool_call/tool_result/progress/done/error/confirm
|
||||
Round int `json:"round,omitempty"`
|
||||
SessionID uint `json:"session_id,omitempty"`
|
||||
Thought string `json:"thought,omitempty"`
|
||||
ToolName string `json:"tool_name,omitempty"`
|
||||
ToolArgs map[string]interface{} `json:"tool_args,omitempty"`
|
||||
Risk string `json:"risk,omitempty"`
|
||||
Output string `json:"output,omitempty"`
|
||||
Success bool `json:"success,omitempty"`
|
||||
Duration string `json:"duration,omitempty"`
|
||||
Tokens int `json:"tokens,omitempty"`
|
||||
Answer string `json:"answer,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
ConfirmID string `json:"confirm_id,omitempty"` // confirm 事件专属
|
||||
Command string `json:"command,omitempty"` // confirm 事件专属
|
||||
}
|
||||
```
|
||||
|
||||
### 前端 → 后端（wsControl）
|
||||
|
||||
```go
|
||||
type wsControl struct {
|
||||
Type string `json:"type"` // start/confirm/deny/abort
|
||||
Query string `json:"query,omitempty"` // start 时任务描述
|
||||
ConfirmID string `json:"confirm_id,omitempty"` // confirm/deny 时
|
||||
}
|
||||
```
|
||||
|
||||
## 并发与隔离
|
||||
|
||||
### 单连接串行
|
||||
|
||||
每个 WebSocket 连接（`agentConn`）同一时刻只运行一个任务：
|
||||
|
||||
```go
|
||||
func (ac *agentConn) startTask(...) {
|
||||
ac.abort() // 取消上一次任务，再启动新的
|
||||
}
|
||||
```
|
||||
|
||||
### 多用户隔离
|
||||
|
||||
- 每个会话绑定 `UserID`（JWT 中间件注入）
|
||||
- REST 查询自动按 `user_id` 过滤
|
||||
- 删除会话时校验归属
|
||||
|
||||
### 线程安全
|
||||
|
||||
- `agentConn.writeMu sync.Mutex` —— 串行化 WebSocket 写入
|
||||
- `agentConn.cfMu sync.Mutex` —— 保护 `confirms` map
|
||||
- 引擎 `core.Agent.mu sync.Mutex` —— 保护 token 计数等内部状态
|
||||
|
||||
## 持久化策略
|
||||
|
||||
### 落库失败不阻断
|
||||
|
||||
```go
|
||||
func (ac *agentConn) persistMsg(...) {
|
||||
if err := ac.db.Create(msg).Error; err != nil {
|
||||
_ = err // 持久化失败不阻断主流程
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
DB 写入失败时，WS 推送仍正常，用户体验不受影响（只是历史回放缺这条）。
|
||||
|
||||
### progress 不入库
|
||||
|
||||
`progress` 事件每个轮次都发，且只含 round 和 token，价值低、频率高，不入库（避免 DB 压力）。
|
||||
|
||||
## 历史回放
|
||||
|
||||
前端通过 `GET /sessions/:id` 拿到完整消息列表，按时间顺序渲染：
|
||||
|
||||
```
|
||||
[会话 #42] 检查 nginx 启动失败的原因
|
||||
├─ 用户：检查 nginx 启动失败的原因
|
||||
├─ Round 1 [thought]：我先查看 nginx 服务状态...
|
||||
├─ Round 1 [tool_call] ssh_execute "systemctl status nginx" (高风险)
|
||||
├─ Round 1 [tool_result] failed (1.2s) [exit_code=3]
|
||||
├─ Round 2 [thought]：服务 failed，查看日志...
|
||||
├─ Round 2 [tool_call] ssh_execute "journalctl -u nginx -n 500" (安全)
|
||||
├─ Round 2 [tool_result] 500 行 (0.8s)
|
||||
├─ Round 3 [thought]：日志太长，先分析...
|
||||
├─ Round 3 [tool_call] analyze_output(output, focus="error")
|
||||
├─ Round 3 [tool_result] 8 行疑似错误 (0.05s)
|
||||
├─ Round 4 [thought]：端口被占，确认一下...
|
||||
├─ Round 4 [tool_call] ssh_execute "ss -tlnp | grep :80" (安全)
|
||||
├─ Round 4 [tool_result] (0.3s)
|
||||
└─ [done] 根因：80 端口被 apache 占用。建议：systemctl stop httpd && systemctl start nginx
|
||||
```
|
||||
|
||||
这是 opsxcli「会话导出为 Markdown」的 Web 升级版 —— 不需要导出，直接在线回放。
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加会话标签 / 收藏
|
||||
|
||||
1. 在 `AgentCLISession` 增加 `Tags string` / `Starred bool` 字段
|
||||
2. 增加 REST 接口 `PATCH /sessions/:id`
|
||||
3. 前端列表增加标签筛选
|
||||
|
||||
### 会话统计
|
||||
|
||||
```go
|
||||
// 例：用户本月使用的 token 总数
|
||||
db.Model(&AgentCLIMessage{}).
|
||||
Where("session_id IN (?) AND type = ?",
|
||||
db.Model(&AgentCLISession{}).Select("id").Where("user_id = ?", uid),
|
||||
"done").
|
||||
Select("COALESCE(SUM(tokens), 0)").Scan(&totalTokens)
|
||||
```
|
||||
|
||||
### 导出会话为 Markdown
|
||||
|
||||
参考 opsxcli 的 `ExportMarkdown`，在 controller 增加一个 REST 接口，遍历消息组装 Markdown 文本返回。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
| 陷阱 | 解决方案 |
|
||||
|------|----------|
|
||||
| 多用户看到别人的会话 | 所有查询按 `user_id` 过滤，删除时校验归属 |
|
||||
| WebSocket 断开导致会话悬挂 | `ctx.Err()` 触发 finish(status=aborted)；前端重连后可查看历史 |
|
||||
| 消息表无限增长 | 定期清理老会话（运维任务）；或按 `created_at` 分区 |
|
||||
| 落库失败丢失历史 | 不阻断主流程，但应在日志记录；progress 不入库减少压力 |
|
||||
| 长任务超过 WS 超时 | ReAct 循环每步检查 `ctx.Err()`，前端断开 → ctx cancel → finish(aborted) |
|
||||
| 并发写 WS 错乱 | `writeMu sync.Mutex` 串行化写入 |
|
||||
| ConfirmFn 无人响应 | 5 分钟超时自动拒绝 |
|
||||
| `lastRound` 不准 | 从 DB 查 `MAX(round)` 而非内存计数（断线重连场景） |
|
||||
|
||||
## 与 opsxcli 的差异总结
|
||||
|
||||
| 维度 | opsxcli | aiops |
|
||||
|------|---------|-------|
|
||||
| 存储后端 | JSONL 文件（`~/.opsxcli/agent/sessions/`） | GORM DB（`agent_cli_sessions` / `agent_cli_messages` 表） |
|
||||
| 多用户 | 不支持（单用户 CLI） | 原生支持（user_id 索引隔离） |
|
||||
| 会话结构 | `{session-id}/meta.json + messages.jsonl` | 单表 sessions + 单表 messages（一对多） |
|
||||
| 查询能力 | 只能遍历文件 | SQL 任意查询、JOIN、聚合 |
|
||||
| 导出 | ExportMarkdown / ExportJSON / ExportToFile | 在线回放（前端时间线） |
|
||||
| 消息字段 | role/content/tool_calls | type/role/content/tool_name/tool_args/tool_output/risk/success/duration/tokens |
|
||||
| 接口 | Manager 接口（10 方法） | REST（3 方法）+ WebSocket 推流 |
|
||||
|
||||
存储载体变了，但「会话 = 元数据 + 消息流」的核心模型保留。DB 方案在多用户 Web 场景下是必然选择，也使会话与其他业务表（Server、User、LLMConfig）的关联变得自然。
|
||||
|
||||
> 作者：Logan.Li
|
||||
@@ -54,6 +54,8 @@ const CronJobManager = lazy(() => import('@/components/automation/CronJobManager
|
||||
const AIOpsAssistant = lazy(() => import('@/components/aiops/AIOpsAssistant').then(m => ({ default: m.AIOpsAssistant })));
|
||||
const AIAlertAnalyzer = lazy(() => import('@/components/aiops/AIAlertAnalyzer').then(m => ({ default: m.AIAlertAnalyzer })));
|
||||
const AIPredictiveAnalytics = lazy(() => import('@/components/aiops/AIPredictiveAnalytics').then(m => ({ default: m.AIPredictiveAnalytics })));
|
||||
const AgentCLI = lazy(() => import('@/components/aiops/AgentCLI').then(m => ({ default: m.default })));
|
||||
const LLMConfigPage = lazy(() => import('@/components/aiops/LLMConfig').then(m => ({ default: m.default })));
|
||||
const AlertCenter = lazy(() => import('@/components/monitor/alert-center/AlertCenter').then(m => ({ default: m.default })));
|
||||
const TraceManager = lazy(() => import('@/components/monitor/trace/TraceManager').then(m => ({ default: m.default })));
|
||||
const HostMonitor = lazy(() => import('@/pages/HostMonitor').then(m => ({ default: m.HostMonitor })));
|
||||
@@ -197,6 +199,8 @@ function App() {
|
||||
<Route path="ai-assistant" element={<LazyPage><AIOpsAssistant /></LazyPage>} />
|
||||
<Route path="ai-alert-analyzer" element={<LazyPage><AIAlertAnalyzer /></LazyPage>} />
|
||||
<Route path="ai-predictive" element={<LazyPage><AIPredictiveAnalytics /></LazyPage>} />
|
||||
<Route path="ai-agent-cli" element={<LazyPage><AgentCLI /></LazyPage>} />
|
||||
<Route path="ai-llm-config" element={<LazyPage><LLMConfigPage /></LazyPage>} />
|
||||
|
||||
{/* Audit — 各 Tab 独立路由，支持 URL 直链 // Logan.Li */}
|
||||
<Route path="audit/terminal" element={<LazyPage><TerminalAuditTab /></LazyPage>} />
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
// Agent CLI API — WebSocket 连接 + 会话历史 REST // Logan.Li
|
||||
import { http } from '@/utils/request';
|
||||
import { useUserStore } from '@/store';
|
||||
|
||||
// 会话与消息类型（与后端 model.AgentCLISession/Message 对应） // Logan.Li
|
||||
export interface AgentCliSession {
|
||||
id: number;
|
||||
user_id: number;
|
||||
server_id: number;
|
||||
server_name: string;
|
||||
server_host: string;
|
||||
title: string;
|
||||
status: string; // running/done/aborted/error
|
||||
provider: string;
|
||||
model: string;
|
||||
rounds: number;
|
||||
total_tokens: number;
|
||||
duration: number;
|
||||
error?: string;
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
|
||||
export interface AgentCliMessage {
|
||||
id: number;
|
||||
session_id: number;
|
||||
round: number;
|
||||
type: string; // thought/tool_call/tool_result/done/error/user
|
||||
role: string;
|
||||
content: string;
|
||||
tool_name: string;
|
||||
tool_args: string;
|
||||
tool_output: string;
|
||||
risk: string;
|
||||
success: boolean;
|
||||
duration: string;
|
||||
tokens: number;
|
||||
created_at: string;
|
||||
}
|
||||
|
||||
export const agentCliApi = {
|
||||
// 会话列表（按当前用户隔离）
|
||||
getSessions: async (params?: { server_id?: number; page?: number; page_size?: number }) => {
|
||||
return http.get<{ list: AgentCliSession[]; total: number }>('/aiops/agent-cli/sessions', params);
|
||||
},
|
||||
// 会话详情（含完整推理消息，供回放）
|
||||
getSession: async (id: number | string) => {
|
||||
return http.get<{ session: AgentCliSession; messages: AgentCliMessage[] }>(`/aiops/agent-cli/sessions/${id}`);
|
||||
},
|
||||
// 删除会话
|
||||
deleteSession: async (id: number | string) => {
|
||||
return http.delete(`/aiops/agent-cli/sessions/${id}`);
|
||||
},
|
||||
};
|
||||
|
||||
// buildAgentCliWsUrl 构造 Agent CLI WebSocket 地址（浏览器无法设 header，用 ?token= 回退） // Logan.Li
|
||||
export function buildAgentCliWsUrl(serverId: number | string): string {
|
||||
const proto = typeof location !== 'undefined' && location.protocol === 'https:' ? 'wss' : 'ws';
|
||||
// Token 双保险：store 优先，localStorage 兜底 // Logan.Li
|
||||
const token = useUserStore.getState().token || localStorage.getItem('token') || '';
|
||||
return `${proto}://${location.host}/ws/agent-cli?id=${serverId}&token=${encodeURIComponent(token)}`;
|
||||
}
|
||||
@@ -12,3 +12,4 @@ export * from './agent';
|
||||
export * from './cloud';
|
||||
export * from './system';
|
||||
export * from './ai';
|
||||
export * from './agentCli';
|
||||
@@ -0,0 +1,379 @@
|
||||
// AgentCLI.tsx - AI 运维 Agent 执行页面（Claude Code 风格 Web 版） // Logan.Li
|
||||
// 关联主机后，用自然语言描述任务，AI 通过 SSH 工具自主排障/部署，循环重试直到解决。
|
||||
// 通过 WebSocket 实时展示思考、执行的命令、输出与结果；高危命令弹框确认。
|
||||
import { useState, useRef, useEffect, useCallback } from 'react';
|
||||
import { useNavigate } from 'react-router-dom';
|
||||
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Badge } from '@/components/ui/badge';
|
||||
import { ScrollArea } from '@/components/ui/scroll-area';
|
||||
import {
|
||||
Select, SelectContent, SelectItem, SelectTrigger, SelectValue,
|
||||
} from '@/components/ui/select';
|
||||
import { useConfirm } from '@/components/ui/confirm-dialog';
|
||||
import { serverApi, buildAgentCliWsUrl } from '@/api';
|
||||
import {
|
||||
Send, Square, Terminal, Settings, ChevronDown, ChevronRight,
|
||||
Shield, Brain, Cpu, Database, Loader2, Bot, AlertTriangle, CheckCircle2, Lightbulb, Server,
|
||||
} from 'lucide-react';
|
||||
|
||||
// 对话流条目模型 // Logan.Li
|
||||
interface ChatItem {
|
||||
id: number;
|
||||
kind: 'user' | 'thought' | 'tool' | 'done' | 'error' | 'info';
|
||||
round?: number;
|
||||
content?: string;
|
||||
toolName?: string;
|
||||
command?: string;
|
||||
risk?: string;
|
||||
output?: string;
|
||||
success?: boolean;
|
||||
duration?: string;
|
||||
pending?: boolean;
|
||||
}
|
||||
|
||||
// 四大核心模块说明（页面 tips） // Logan.Li
|
||||
const TIPS = [
|
||||
{ icon: Cpu, title: 'LLM + 工具层（llm / tools）', color: 'text-sky-400',
|
||||
desc: 'OpenAI 兼容 LLM 客户端（复用「大模型设置」中的配置）；工具系统注册 ssh_execute（远程执行命令，复用 pkg/remoteexec）与 analyze_output（超长输出分析）。AI 借助工具真正动手操作服务器。' },
|
||||
{ icon: Shield, title: '安全 + Prompt（safety / prompt）', color: 'text-amber-400',
|
||||
desc: '五级风险评估 + 三级安全模式：危险命令（rm -rf /、mkfs）硬性拒绝，高危命令（reboot、restart）弹框确认；五层 System Prompt 定义角色、安全规则、工具与 ReAct 工作方式。' },
|
||||
{ icon: Brain, title: 'ReAct 核心引擎（core）', color: 'text-violet-400',
|
||||
desc: '「思考→行动→观察」循环（最多 16 轮）：每轮调用工具、读取输出，失败则分析原因换法重试；自适应检查点 + 循环检测（同参超过 3 次拒绝），直到真正解决问题而非假装解决。' },
|
||||
{ icon: Database, title: '自进化引擎（evolver）', color: 'text-emerald-400',
|
||||
desc: '四层记忆（经验 / 环境 / 事实 / 程序）：任务完成后异步学习经验，下次同类任务自动注入历史经验，越用越聪明；学习失败优雅降级，绝不影响主流程。' },
|
||||
];
|
||||
|
||||
// riskVariant 风险等级对应 badge 颜色 // Logan.Li
|
||||
function riskClass(risk?: string): string {
|
||||
switch ((risk || '').toLowerCase()) {
|
||||
case '安全': case 'safe': return 'bg-emerald-500/15 text-emerald-400 border-emerald-500/30';
|
||||
case '低风险': case 'low': return 'bg-sky-500/15 text-sky-400 border-sky-500/30';
|
||||
case '中风险': case 'medium': return 'bg-amber-500/15 text-amber-400 border-amber-500/30';
|
||||
case '高风险': case 'high': return 'bg-orange-500/15 text-orange-400 border-orange-500/30';
|
||||
case '危险': case 'critical': return 'bg-red-500/15 text-red-400 border-red-500/30';
|
||||
default: return 'bg-slate-500/15 text-slate-400 border-slate-500/30';
|
||||
}
|
||||
}
|
||||
|
||||
export default function AgentCLI() {
|
||||
const navigate = useNavigate();
|
||||
const confirm = useConfirm();
|
||||
|
||||
const [servers, setServers] = useState<{ id: number; hostname: string; ip: string }[]>([]);
|
||||
const [serverId, setServerId] = useState<string>('');
|
||||
const [items, setItems] = useState<ChatItem[]>([]);
|
||||
const [input, setInput] = useState('');
|
||||
const [running, setRunning] = useState(false);
|
||||
const [round, setRound] = useState(0);
|
||||
const [tokens, setTokens] = useState(0);
|
||||
const [tipsOpen, setTipsOpen] = useState(true);
|
||||
const [connected, setConnected] = useState(false);
|
||||
|
||||
const wsRef = useRef<WebSocket | null>(null);
|
||||
const idSeq = useRef(0);
|
||||
const scrollRef = useRef<HTMLDivElement | null>(null);
|
||||
|
||||
const nextId = () => ++idSeq.current;
|
||||
const push = useCallback((it: Omit<ChatItem, 'id'>) => {
|
||||
setItems((prev) => [...prev, { ...it, id: nextId() }]);
|
||||
}, []);
|
||||
|
||||
// 加载主机列表 // Logan.Li
|
||||
useEffect(() => {
|
||||
serverApi.getServers({ page: 1, page_size: 500 }).then((res) => {
|
||||
setServers((res as { list?: { id: number; hostname: string; ip: string }[] })?.list || []);
|
||||
}).catch(() => {});
|
||||
}, []);
|
||||
|
||||
// 选中主机后建立 WebSocket 连接 // Logan.Li
|
||||
useEffect(() => {
|
||||
if (!serverId) return;
|
||||
setItems([]);
|
||||
setRound(0); setTokens(0); setRunning(false);
|
||||
const ws = new WebSocket(buildAgentCliWsUrl(serverId));
|
||||
wsRef.current = ws;
|
||||
ws.onopen = () => setConnected(true);
|
||||
ws.onclose = () => { setConnected(false); setRunning(false); };
|
||||
ws.onmessage = (e) => {
|
||||
try { handleEvent(JSON.parse(e.data)); } catch { /* 忽略非 JSON */ }
|
||||
};
|
||||
return () => { ws.close(); wsRef.current = null; };
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||
}, [serverId]);
|
||||
|
||||
// 自动滚到底部 // Logan.Li
|
||||
useEffect(() => {
|
||||
scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight, behavior: 'smooth' });
|
||||
}, [items]);
|
||||
|
||||
// 处理后端事件 // Logan.Li
|
||||
const handleEvent = (ev: Record<string, unknown>) => {
|
||||
const type = ev.type as string;
|
||||
switch (type) {
|
||||
case 'session':
|
||||
push({ kind: 'info', content: ev.message as string });
|
||||
break;
|
||||
case 'progress':
|
||||
if (ev.round) setRound(ev.round as number);
|
||||
if (ev.tokens) setTokens(ev.tokens as number);
|
||||
break;
|
||||
case 'thought':
|
||||
push({ kind: 'thought', round: ev.round as number, content: ev.thought as string });
|
||||
break;
|
||||
case 'tool_call': {
|
||||
const args = (ev.tool_args || {}) as Record<string, unknown>;
|
||||
push({
|
||||
kind: 'tool', round: ev.round as number, toolName: ev.tool_name as string,
|
||||
command: (args.command as string) || '', risk: ev.risk as string, pending: true,
|
||||
});
|
||||
break;
|
||||
}
|
||||
case 'tool_result':
|
||||
// 配对：从末尾找最近的 pending 同名工具块填充输出 // Logan.Li
|
||||
setItems((prev) => {
|
||||
const next = [...prev];
|
||||
for (let i = next.length - 1; i >= 0; i--) {
|
||||
if (next[i].kind === 'tool' && next[i].pending && next[i].toolName === ev.tool_name) {
|
||||
next[i] = {
|
||||
...next[i], output: ev.output as string, success: ev.success as boolean,
|
||||
duration: ev.duration as string, pending: false,
|
||||
};
|
||||
break;
|
||||
}
|
||||
}
|
||||
return next;
|
||||
});
|
||||
break;
|
||||
case 'confirm':
|
||||
handleConfirm(ev);
|
||||
break;
|
||||
case 'done':
|
||||
push({ kind: 'done', content: ev.answer as string, round: ev.round as number });
|
||||
setRunning(false);
|
||||
break;
|
||||
case 'error':
|
||||
case 'aborted':
|
||||
push({ kind: type === 'aborted' ? 'info' : 'error', content: (ev.message as string) || (type === 'aborted' ? '任务已中断' : '发生错误') });
|
||||
setRunning(false);
|
||||
break;
|
||||
}
|
||||
};
|
||||
|
||||
// 高危命令确认（后端驱动 → 弹框 → 回传） // Logan.Li
|
||||
const handleConfirm = async (ev: Record<string, unknown>) => {
|
||||
const ok = await confirm({
|
||||
title: '⚠️ 确认执行高危操作',
|
||||
description: `工具：${ev.tool_name}\n风险：${ev.risk}\n命令：${ev.command || '(无)'}`,
|
||||
confirmText: '确认执行',
|
||||
cancelText: '拒绝',
|
||||
variant: 'destructive',
|
||||
});
|
||||
wsRef.current?.send(JSON.stringify({ type: ok ? 'confirm' : 'deny', confirm_id: ev.confirm_id }));
|
||||
if (!ok) push({ kind: 'info', content: `已拒绝执行：${ev.command || ev.tool_name}` });
|
||||
};
|
||||
|
||||
// 发送任务 // Logan.Li
|
||||
const send = () => {
|
||||
const q = input.trim();
|
||||
if (!q || running || !wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) return;
|
||||
push({ kind: 'user', content: q });
|
||||
wsRef.current.send(JSON.stringify({ type: 'start', query: q }));
|
||||
setInput('');
|
||||
setRunning(true);
|
||||
};
|
||||
|
||||
// 中断任务 // Logan.Li
|
||||
const stop = () => wsRef.current?.send(JSON.stringify({ type: 'abort' }));
|
||||
|
||||
return (
|
||||
<div className="h-full flex flex-col gap-3 p-4">
|
||||
{/* 顶部工具栏：主机选择 + 状态 + 大模型设置入口 */}
|
||||
<Card className="bg-slate-900/60 border-slate-800">
|
||||
<CardContent className="p-3 flex items-center gap-3 flex-wrap">
|
||||
<div className="flex items-center gap-2 text-slate-200 font-medium">
|
||||
<Bot className="w-5 h-5 text-blue-400" /> Agent CLI
|
||||
</div>
|
||||
<div className="w-px h-6 bg-slate-700" />
|
||||
<Server className="w-4 h-4 text-slate-400" />
|
||||
<Select value={serverId} onValueChange={setServerId}>
|
||||
<SelectTrigger className="w-64 bg-slate-800 border-slate-700 text-slate-200">
|
||||
<SelectValue placeholder="选择目标主机" />
|
||||
</SelectTrigger>
|
||||
<SelectContent className="bg-slate-800 border-slate-700 max-h-72">
|
||||
{servers.map((s) => (
|
||||
<SelectItem key={s.id} value={String(s.id)}>
|
||||
{s.hostname}（{s.ip}）
|
||||
</SelectItem>
|
||||
))}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
{connected && (
|
||||
<Badge className="bg-emerald-500/15 text-emerald-400 border-emerald-500/30">
|
||||
<span className="w-1.5 h-1.5 rounded-full bg-emerald-400 mr-1.5" />已连接
|
||||
</Badge>
|
||||
)}
|
||||
{running && (
|
||||
<Badge className="bg-blue-500/15 text-blue-400 border-blue-500/30">
|
||||
<Loader2 className="w-3 h-3 mr-1 animate-spin" />第 {round} 轮 · {tokens} tokens
|
||||
</Badge>
|
||||
)}
|
||||
<div className="flex-1" />
|
||||
<Button variant="outline" size="sm" className="border-slate-700 text-slate-300" onClick={() => navigate('/ai-llm-config')}>
|
||||
<Settings className="w-4 h-4 mr-1" /> 大模型设置
|
||||
</Button>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
{/* tips 面板：核心功能 / 逻辑 / 设计思路 */}
|
||||
<Card className="bg-slate-900/40 border-slate-800">
|
||||
<CardHeader className="py-2 px-3 cursor-pointer select-none" onClick={() => setTipsOpen((v) => !v)}>
|
||||
<div className="flex items-center gap-2 text-slate-300 text-sm">
|
||||
{tipsOpen ? <ChevronDown className="w-4 h-4" /> : <ChevronRight className="w-4 h-4" />}
|
||||
<Lightbulb className="w-4 h-4 text-yellow-400" />
|
||||
<span className="font-medium">核心能力与设计思路</span>
|
||||
<span className="text-slate-500 text-xs">— Agent CLI 由四大模块构成，参考 opsxcli AI Agent 移植</span>
|
||||
</div>
|
||||
</CardHeader>
|
||||
{tipsOpen && (
|
||||
<CardContent className="pt-2 grid grid-cols-1 md:grid-cols-2 gap-3">
|
||||
{TIPS.map((t) => (
|
||||
<div key={t.title} className="flex gap-2.5 p-2.5 rounded-lg bg-slate-800/40 border border-slate-800">
|
||||
<t.icon className={`w-5 h-5 mt-0.5 shrink-0 ${t.color}`} />
|
||||
<div>
|
||||
<div className="text-sm font-medium text-slate-200">{t.title}</div>
|
||||
<div className="text-xs text-slate-400 leading-relaxed mt-0.5">{t.desc}</div>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
</CardContent>
|
||||
)}
|
||||
</Card>
|
||||
|
||||
{/* 对话流 */}
|
||||
<Card className="flex-1 min-h-0 bg-slate-900/40 border-slate-800 flex flex-col">
|
||||
<div ref={scrollRef} className="flex-1 min-h-0 overflow-y-auto p-4 space-y-3">
|
||||
{items.length === 0 && (
|
||||
<div className="h-full flex flex-col items-center justify-center text-slate-500 gap-2">
|
||||
<Terminal className="w-10 h-10 opacity-40" />
|
||||
<div className="text-sm">{serverId ? '描述你要执行的任务，例如「检查磁盘使用率并清理大文件」' : '请先选择一台目标主机'}</div>
|
||||
</div>
|
||||
)}
|
||||
{items.map((it) => (
|
||||
<MessageView key={it.id} item={it} />
|
||||
))}
|
||||
</div>
|
||||
{/* 输入区 */}
|
||||
<div className="border-t border-slate-800 p-3 flex items-end gap-2">
|
||||
<textarea
|
||||
value={input}
|
||||
onChange={(e) => setInput(e.target.value)}
|
||||
onKeyDown={(e) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(); } }}
|
||||
placeholder={serverId ? '输入任务描述，回车发送（Shift+回车换行）' : '请先选择目标主机'}
|
||||
disabled={!connected}
|
||||
rows={1}
|
||||
className="flex-1 resize-none bg-slate-800 border border-slate-700 rounded-md px-3 py-2 text-sm text-slate-200 placeholder:text-slate-600 focus:outline-none focus:ring-1 focus:ring-blue-500 max-h-32"
|
||||
/>
|
||||
{running ? (
|
||||
<Button variant="destructive" onClick={stop} className="bg-red-600 hover:bg-red-700">
|
||||
<Square className="w-4 h-4 mr-1" /> 停止
|
||||
</Button>
|
||||
) : (
|
||||
<Button onClick={send} disabled={!connected || !input.trim()} className="bg-blue-600 hover:bg-blue-700">
|
||||
<Send className="w-4 h-4 mr-1" /> 执行
|
||||
</Button>
|
||||
)}
|
||||
</div>
|
||||
</Card>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// MessageView 单条消息渲染（按 kind 分流） // Logan.Li
|
||||
function MessageView({ item }: { item: ChatItem }) {
|
||||
if (item.kind === 'user') {
|
||||
return (
|
||||
<div className="flex justify-end">
|
||||
<div className="max-w-[80%] rounded-lg bg-blue-600/90 text-white px-3 py-2 text-sm whitespace-pre-wrap">{item.content}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
if (item.kind === 'info') {
|
||||
return <div className="text-center text-xs text-slate-500 py-1">{item.content}</div>;
|
||||
}
|
||||
if (item.kind === 'thought') {
|
||||
return <ThoughtBlock text={item.content || ''} round={item.round} />;
|
||||
}
|
||||
if (item.kind === 'tool') {
|
||||
return <ToolBlock item={item} />;
|
||||
}
|
||||
if (item.kind === 'done') {
|
||||
return (
|
||||
<div className="flex gap-2 rounded-lg bg-emerald-500/10 border border-emerald-500/30 p-3">
|
||||
<CheckCircle2 className="w-5 h-5 text-emerald-400 shrink-0 mt-0.5" />
|
||||
<div className="text-sm text-emerald-100 whitespace-pre-wrap leading-relaxed">{item.content}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
// error
|
||||
return (
|
||||
<div className="flex gap-2 rounded-lg bg-red-500/10 border border-red-500/30 p-3">
|
||||
<AlertTriangle className="w-5 h-5 text-red-400 shrink-0 mt-0.5" />
|
||||
<div className="text-sm text-red-100 whitespace-pre-wrap">{item.content}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// ThoughtBlock AI 思考（可折叠，灰底斜体） // Logan.Li
|
||||
function ThoughtBlock({ text, round }: { text: string; round?: number }) {
|
||||
const [open, setOpen] = useState(false);
|
||||
const preview = text.length > 80 ? text.slice(0, 80) + '...' : text;
|
||||
return (
|
||||
<div className="rounded-lg bg-slate-800/40 border border-slate-800 p-2.5">
|
||||
<button className="flex items-center gap-1.5 text-xs text-slate-400 w-full text-left" onClick={() => setOpen((v) => !v)}>
|
||||
{open ? <ChevronDown className="w-3.5 h-3.5" /> : <ChevronRight className="w-3.5 h-3.5" />}
|
||||
<Brain className="w-3.5 h-3.5 text-violet-400" />
|
||||
{round != null && <span className="text-slate-500">第 {round} 轮思考</span>}
|
||||
<span className="ml-1 text-slate-500 truncate">{!open && preview}</span>
|
||||
</button>
|
||||
{open && <div className="mt-1.5 text-sm text-slate-300 whitespace-pre-wrap leading-relaxed">{text}</div>}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// ToolBlock 工具调用块（命令 + 风险 + 可展开输出） // Logan.Li
|
||||
function ToolBlock({ item }: { item: ChatItem }) {
|
||||
const [open, setOpen] = useState(true);
|
||||
return (
|
||||
<div className="rounded-lg bg-slate-800/40 border border-slate-800 overflow-hidden">
|
||||
<div className="flex items-center gap-2 px-3 py-2 bg-slate-800/60">
|
||||
<button className="flex items-center gap-1.5 flex-1 min-w-0 text-left" onClick={() => setOpen((v) => !v)}>
|
||||
{open ? <ChevronDown className="w-3.5 h-3.5 text-slate-400" /> : <ChevronRight className="w-3.5 h-3.5 text-slate-400" />}
|
||||
<Terminal className="w-3.5 h-3.5 text-sky-400 shrink-0" />
|
||||
<span className="text-xs text-slate-400 shrink-0">{item.toolName}</span>
|
||||
{item.round != null && <span className="text-xs text-slate-600">· R{item.round}</span>}
|
||||
</button>
|
||||
{item.risk && <Badge className={`text-[10px] border ${riskClass(item.risk)}`}>{item.risk}</Badge>}
|
||||
{item.pending && <Loader2 className="w-3.5 h-3.5 text-blue-400 animate-spin" />}
|
||||
{!item.pending && item.success != null && (
|
||||
item.success
|
||||
? <CheckCircle2 className="w-3.5 h-3.5 text-emerald-400" />
|
||||
: <AlertTriangle className="w-3.5 h-3.5 text-red-400" />
|
||||
)}
|
||||
</div>
|
||||
{open && (
|
||||
<div className="px-3 py-2 space-y-2">
|
||||
{item.command && (
|
||||
<pre className="text-xs text-emerald-300 bg-slate-950/60 rounded px-2 py-1.5 overflow-x-auto"><code>$ {item.command}</code></pre>
|
||||
)}
|
||||
{!item.pending && item.output != null && (
|
||||
<>
|
||||
{item.duration && <div className="text-[10px] text-slate-600">耗时 {item.duration}</div>}
|
||||
<pre className="text-xs text-slate-300 bg-slate-950/40 rounded px-2 py-1.5 overflow-x-auto max-h-80 whitespace-pre-wrap">{item.output || '（无输出）'}</pre>
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,149 @@
|
||||
// LLMConfig.tsx - 大模型设置独立页（AIOps 智能菜单下统一 LLM 配置入口） // Logan.Li
|
||||
// 调用既有 /aiops/llm-config 接口（GET/PUT/POST test），Agent CLI 与智能助手共用同一配置。
|
||||
import { useState, useEffect } from 'react';
|
||||
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Input } from '@/components/ui/input';
|
||||
import { Label } from '@/components/ui/label';
|
||||
import { Switch } from '@/components/ui/switch';
|
||||
import {
|
||||
Select, SelectContent, SelectItem, SelectTrigger, SelectValue,
|
||||
} from '@/components/ui/select';
|
||||
import { toast } from 'sonner';
|
||||
import { Loader2, Save, Wifi, KeyRound, Brain } from 'lucide-react';
|
||||
import { aiApi, type LLMConfigData } from '@/api';
|
||||
|
||||
// OpenAI 兼容提供商列表 // Logan.Li
|
||||
const PROVIDERS = [
|
||||
{ id: 'openai', name: 'OpenAI', endpoint: 'https://api.openai.com/v1', models: 'gpt-4o-mini, gpt-4o' },
|
||||
{ id: 'deepseek', name: 'DeepSeek', endpoint: 'https://api.deepseek.com/v1', models: 'deepseek-chat, deepseek-reasoner' },
|
||||
{ id: 'qwen', name: '通义千问 (DashScope)', endpoint: 'https://dashscope.aliyuncs.com/compatible-mode/v1', models: 'qwen-plus, qwen-turbo, qwen-max' },
|
||||
{ id: 'moonshot', name: 'Moonshot 月之暗面', endpoint: 'https://api.moonshot.cn/v1', models: 'moonshot-v1-8k, moonshot-v1-32k' },
|
||||
{ id: 'ollama', name: 'Ollama 本地', endpoint: 'http://localhost:11434/v1', models: 'qwen2.5:7b, llama3.2' },
|
||||
{ id: 'custom', name: '自定义 (OpenAI 兼容)', endpoint: '', models: '' },
|
||||
];
|
||||
|
||||
const defaultCfg: LLMConfigData = {
|
||||
provider: 'deepseek', model: 'deepseek-chat', api_key: '',
|
||||
endpoint: 'https://api.deepseek.com/v1', temperature: 0.3, max_tokens: 4096,
|
||||
system_prompt: '', enabled: false,
|
||||
};
|
||||
|
||||
export default function LLMConfigPage() {
|
||||
const [cfg, setCfg] = useState<LLMConfigData>(defaultCfg);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [saving, setSaving] = useState(false);
|
||||
const [testing, setTesting] = useState(false);
|
||||
|
||||
useEffect(() => { load(); }, []);
|
||||
const load = async () => {
|
||||
setLoading(true);
|
||||
try { setCfg({ ...defaultCfg, ...(await aiApi.getConfig()) }); }
|
||||
catch { /* 首次无配置，使用默认 */ }
|
||||
finally { setLoading(false); }
|
||||
};
|
||||
const save = async () => {
|
||||
setSaving(true);
|
||||
try { await aiApi.saveConfig(cfg); toast.success('配置已保存'); }
|
||||
catch { toast.error('保存失败'); }
|
||||
finally { setSaving(false); }
|
||||
};
|
||||
const test = async () => {
|
||||
setTesting(true);
|
||||
try { await aiApi.testConnection(); toast.success('连接成功'); }
|
||||
catch { /* 拦截器已提示 */ }
|
||||
finally { setTesting(false); }
|
||||
};
|
||||
const onProvider = (p: string) => {
|
||||
const prov = PROVIDERS.find((x) => x.id === p);
|
||||
setCfg({ ...cfg, provider: p, endpoint: prov?.endpoint || cfg.endpoint });
|
||||
};
|
||||
const set = <K extends keyof LLMConfigData>(k: K, v: LLMConfigData[K]) => setCfg({ ...cfg, [k]: v });
|
||||
|
||||
if (loading) {
|
||||
return <div className="flex items-center justify-center h-full text-slate-400"><Loader2 className="w-5 h-5 animate-spin mr-2" />加载配置...</div>;
|
||||
}
|
||||
const prov = PROVIDERS.find((x) => x.id === cfg.provider);
|
||||
|
||||
return (
|
||||
<div className="max-w-3xl mx-auto p-4 space-y-4">
|
||||
<div className="flex items-center gap-2 text-slate-200">
|
||||
<Brain className="w-5 h-5 text-blue-400" />
|
||||
<span className="text-lg font-medium">大模型设置</span>
|
||||
<span className="text-xs text-slate-500">— Agent CLI 与智能助手共用此配置</span>
|
||||
</div>
|
||||
|
||||
<Card className="bg-slate-900/60 border-slate-800">
|
||||
<CardHeader><CardTitle className="text-slate-200 text-base">模型与凭证</CardTitle></CardHeader>
|
||||
<CardContent className="space-y-4">
|
||||
<div className="grid grid-cols-2 gap-4">
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">提供商</Label>
|
||||
<Select value={cfg.provider} onValueChange={onProvider}>
|
||||
<SelectTrigger className="bg-slate-800 border-slate-700 text-slate-200"><SelectValue /></SelectTrigger>
|
||||
<SelectContent className="bg-slate-800 border-slate-700">
|
||||
{PROVIDERS.map((p) => <SelectItem key={p.id} value={p.id}>{p.name}</SelectItem>)}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
</div>
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">模型</Label>
|
||||
<Input value={cfg.model} onChange={(e) => set('model', e.target.value)}
|
||||
placeholder={prov?.models || '模型名'} className="bg-slate-800 border-slate-700 text-slate-200" />
|
||||
</div>
|
||||
</div>
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300 flex items-center gap-1"><KeyRound className="w-3.5 h-3.5" />API Key</Label>
|
||||
<Input type="password" value={cfg.api_key} onChange={(e) => set('api_key', e.target.value)}
|
||||
placeholder="sk-..." className="bg-slate-800 border-slate-700 text-slate-200" />
|
||||
</div>
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">接口地址（Endpoint）</Label>
|
||||
<Input value={cfg.endpoint} onChange={(e) => set('endpoint', e.target.value)}
|
||||
placeholder="https://api.xxx.com/v1" className="bg-slate-800 border-slate-700 text-slate-200" />
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<Card className="bg-slate-900/60 border-slate-800">
|
||||
<CardHeader><CardTitle className="text-slate-200 text-base">生成参数</CardTitle></CardHeader>
|
||||
<CardContent className="space-y-4">
|
||||
<div className="grid grid-cols-2 gap-4">
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">温度（Temperature）</Label>
|
||||
<Input type="number" step="0.1" min="0" max="2" value={cfg.temperature}
|
||||
onChange={(e) => set('temperature', Number(e.target.value))}
|
||||
className="bg-slate-800 border-slate-700 text-slate-200" />
|
||||
</div>
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">最大输出 Token</Label>
|
||||
<Input type="number" min="256" value={cfg.max_tokens}
|
||||
onChange={(e) => set('max_tokens', Number(e.target.value))}
|
||||
className="bg-slate-800 border-slate-700 text-slate-200" />
|
||||
</div>
|
||||
</div>
|
||||
<div className="space-y-1.5">
|
||||
<Label className="text-slate-300">系统提示词（可选，留空使用内置运维助手角色）</Label>
|
||||
<textarea value={cfg.system_prompt} onChange={(e) => set('system_prompt', e.target.value)} rows={3}
|
||||
className="w-full bg-slate-800 border border-slate-700 rounded-md px-3 py-2 text-sm text-slate-200 resize-none" />
|
||||
</div>
|
||||
<div className="flex items-center justify-between">
|
||||
<Label className="text-slate-300">启用 LLM 服务</Label>
|
||||
<Switch checked={cfg.enabled} onCheckedChange={(v) => set('enabled', v)} />
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<div className="flex items-center gap-2">
|
||||
<Button onClick={save} disabled={saving} className="bg-blue-600 hover:bg-blue-700">
|
||||
{saving ? <Loader2 className="w-4 h-4 mr-1 animate-spin" /> : <Save className="w-4 h-4 mr-1" />} 保存配置
|
||||
</Button>
|
||||
<Button variant="outline" onClick={test} disabled={testing || !cfg.enabled}
|
||||
className="border-slate-700 text-slate-300">
|
||||
{testing ? <Loader2 className="w-4 h-4 mr-1 animate-spin" /> : <Wifi className="w-4 h-4 mr-1" />} 测试连接
|
||||
</Button>
|
||||
{!cfg.enabled && <span className="text-xs text-slate-500">请先保存并启用后再测试</span>}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -144,6 +144,8 @@ const menuItems: MenuItem[] = [
|
||||
{ id: 'ai-assistant', name: '智能助手', icon: Bot, path: '/ai-assistant', permission: 'aiops:assistant' },
|
||||
{ id: 'ai-alert-analyzer', name: '告警分析', icon: AlertTriangle, path: '/ai-alert-analyzer', permission: 'aiops:analysis' },
|
||||
{ id: 'ai-predictive', name: '容量预测', icon: BarChart3, path: '/ai-predictive', permission: 'aiops:forecast' },
|
||||
{ id: 'ai-agent-cli', name: 'Agent CLI', icon: Terminal, path: '/ai-agent-cli', permission: 'aiops:agent-cli' },
|
||||
{ id: 'ai-llm-config', name: '大模型设置', icon: Settings, path: '/ai-llm-config', permission: 'aiops:llm-config' },
|
||||
],
|
||||
},
|
||||
{ id: 'approval', name: '资源申请', icon: CheckSquare, permission: 'approval:apply',
|
||||
|
||||
Reference in new issue
Block a user