aiops/docs/agent/10-会话管理.md

# 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