# 16 - AI 会话产品层：状态机 · incomplete · Harness · 排队

> 更新：2026-10-15 · 承接 `docs/15-AI-MCP-Agent.md`（工具面已齐）  
> 借鉴：`/Users/logan/devops/aiops/docs/ai-agent` 的 03 / 05 / 06 / 13 / 14  
> 产品锁：MCP-first；默认只读；写需 `mode=read_write` + 确认；桌面单用户；**不做** Evolver / 审批流 / 跨产品共用执行器

本文定义 OpsxDB **会话产品层**契约：工具层（aitools / MCP）之上，侧栏 Agent 如何持久化、触顶、续跑、排队与安全确认。

---

## 1. 与 MCP / Agent 的关系

```
外部 Cursor/Claude ──stdio──▶ opsxdb-mcp ──┐
                                           ▼
侧栏 Ask（不调工具）                  aitools.Runtime（同源）
侧栏 Agent ──▶ ai.runAgent / Harness ──▶ Runtime.Call
                     │                      │
                     ▼                      ▼
              会话落盘（目标）          mcp-audit.jsonl（含 run_id）
```

| 层 | 职责 | 不负责 |
|----|------|--------|
| **aitools.Runtime** | 白名单、只读/可写闸、危险 SQL、确认令牌、审计 | 多轮对话、预算、续跑 |
| **MCP stdio** | 把 Runtime 暴露给外部 Agent | 会话 UI、incomplete |
| **ai.RunAgent** | ReAct 循环、步骤事件、SSE | 连接增删、公网后端 |
| **会话产品层（本文）** | 落盘轨迹、RunOutcome、Harness 预算、排队、脱敏、确认绑定 | Evolver、审批流 |

**真·续跑**（对齐 aiops 13）：必须同时满足 (1) 持久化含 `tool_calls` + `tool` observation（含 `tool_call_id`）；(2) 下次 Run 把历史注入引擎。仅恢复气泡不算 resume。

---

## 2. 会话状态机

### 2.1 Session（会话）

| 状态 | 含义 |
|------|------|
| `idle` | 有历史或空会话，无进行中的 run |
| `running` | 正在执行一轮 Agent |
| `awaiting_confirm` | 写操作待用户确认（可与 running 同条气泡内嵌） |
| `incomplete` | 上一趟因预算/超时停住，轨迹可续 |
| `completed` | 上一趟正常结束 |
| `failed` | 不可恢复错误 |
| `cancelled` | 用户停止 |

桌面单用户：会话默认落 `~/.opsxdb/ai-sessions/<session_id>.json`（目标态；首版可仅内存 + 可选落盘）。

### 2.2 RunOutcome（单次运行结束，必填）

对齐 aiops `13-运行结果状态与可续跑契约.md`：

| outcome | 含义 | UI |
|---------|------|-----|
| `completed` | 预算内给出最终答案 | 正常 |
| `incomplete` | 未完成但有部分轨迹 | 「加预算继续」/「继续」 |
| `failed` | 协议/鉴权/致命工具错 | 失败 |
| `cancelled` | 用户 Abort | 已取消 |
| `awaiting_confirm` | 安全闸等待确认 | 确认条 |

### 2.3 IncompleteReason

| reason | 触发 |
|--------|------|
| `max_steps` | 触达 MaxRounds / MaxIterations |
| `context_budget` | trim 后无法安全继续 |
| `tool_timeout` | 单工具超时 |
| `llm_timeout` | LLM 超时 |
| `safety_abort` | 安全中止（非等待确认） |

**规则**：触顶步数 → `incomplete` + `max_steps`，**不得**伪装成 `completed`（现状 `agent.go` 触顶仍发 `done`，见 §6 审查）。

### 2.4 对外字段（API / SSE 目标态）

```text
run_id                 # 一次 Run 全链路 ID（审计 / 步骤共用）
session_id             # 可选；有落盘时必填
run_outcome            # completed | incomplete | failed | cancelled | awaiting_confirm
incomplete_reason?     # 见上表
resumable              # 是否满足真·续跑条件
steps_used / steps_budget
partial_summary?       # 触顶时进展摘要
```

SSE：在现有 `step_start` / `step` / `delta` / `done` / `error` 上，目标增加显式 `incomplete` 事件（或 `done` 携带 `run_outcome=incomplete`）。首版代码已在 `AgentRes` / `AgentEvent` 挂上 outcome 字段。

---

## 3. Harness 预算与反馈

参考 aiops 03；OpsxDB 裁剪为桌面 DB Agent：

| 旋钮 | 默认 | 说明 |
|------|------|------|
| `MaxRounds` | 8（上限 16） | ReAct 轮数预算，非质量承诺 |
| `MaxToolResultChars` | 12000 | 回灌 LLM 前截断 |
| `MaxContextTokens` | 8000（目标） | trimMessages 预算 |
| `ToolTimeout` | 与 db 层对齐（目标显式化） | 单工具 |
| `SameCallLimit` | 3（目标） | 同工具同参循环拒 |
| `Checkpoints` | 第 4 / 6 轮（目标） | 提示换思路 / 收尾 |

### 3.1 trimMessages（目标行为）

1. 永远保留 system  
2. 从最近向前保留，约 `MaxContextTokens * 90%`  
3. 至少保留最近 4 条  
4. 裁剪后按 `tool_call_id` 整组保留 assistant.tool_calls + tool 消息  

代码：`ai.TrimMessages` 钩子已落地；Agent 主循环接入时机在「多轮续跑 / 长会话」打开时启用（单次短问可跳过）。

### 3.2 检查点与循环检测

目标：同参 ≥3 次拒绝并写入 tool observation；第 4/6 轮向 msgs 注入短 system/user 提醒。不做 Evolver。

---

## 4. 会话落盘与真·续跑

### 4.1 存储形状（目标）

```json
{
  "id": "sess_…",
  "title": "列出 demo 表",
  "createdAt": "…",
  "updatedAt": "…",
  "status": "incomplete",
  "messages": [
    {"role":"system","content":"…"},
    {"role":"user","content":"…"},
    {"role":"assistant","content":"…","toolCalls":[{"id":"c1","function":{…}}]},
    {"role":"tool","toolCallId":"c1","name":"opsxdb_list_tables","content":"…"}
  ],
  "runs": [{"runId":"run_…","outcome":"incomplete","reason":"max_steps","stepsUsed":8}]
}
```

脱敏后落盘（见 §5）。密码、连接串明文、大结果全文不进会话文件。

### 4.2 API 契约（目标，大 UI 可后做）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ai/sessions` | 列表 |
| GET | `/api/ai/sessions/:id` | 含 messages |
| POST | `/api/ai/agent` | 现有；增加可选 `sessionId` / `continue:true` / `prior` |
| POST | `/api/ai/sessions/:id/continue` | 注入 prior + 可选提高 MaxRounds |

骨架：`server/internal/ai/session.go`（文件存储接口 + 类型；HTTP 路由可后挂）。

---

## 5. 脱敏与确认绑定

### 5.1 脱敏（落盘 / 审计 / 展示）

对齐 aiops 05，桌面范围：

| 类型 | 示例 |
|------|------|
| Bearer / API Key | `Bearer …`、`sk-…` |
| 密码 | `password=`、`pwd=` |
| 连接串 | `mysql://user:pass@host` |
| PEM 私钥块 | `BEGIN … PRIVATE KEY` |

`ai.RedactSensitive` 已提供；会话落盘与审计 summary 应过脱敏。

### 5.2 确认绑定（写操作）

写确认不得只靠 UI 气泡里的明文 SQL 再次提交而无绑定：

```text
confirm_bind = sha256(connection_id + "\n" + normalize(sql_or_command))
```

规则：

1. `needConfirm` 响应带上 `confirmBind`（或服务端会话内缓存）  
2. `/api/ai/agent/confirm` 校验：connection_id + 语句 与绑定一致，否则拒绝并要求重确认  
3. 用户改了 SQL → 哈希变 → 必须重新确认（防 TOCTOU）

首版：`aitools.ConfirmBindHash` + Runtime needConfirm 返回字段；confirm 端点校验（见代码）。

---

## 6. 忙时单槽排队

对齐 aiops 14；桌面侧栏：

| 动作 | 语义 |
|------|------|
| 排队 | running 时新输入进 `pending`（单槽；再提交覆盖） |
| 自动续发 | 当前 run 结束（任一 outcome）后若有 pending → 自动 continue |
| 立即 | 停止当前 → 立刻跑 pending |
| 编辑 / 撤销 | 拉回输入框 / 丢弃 |

与 incomplete 续跑可叠加：排队是同会话并发输入；incomplete 是上一趟未完成再继续。

**首版**：文档 + 前端状态契约；服务端仍单请求单 run（Abort 用 ctx cancel）。不做跨会话队列、不做长 FIFO。

---

## 7. 细节审查：现状 → 缺口 → 建议

### 7.1 Agent loop（`server/internal/ai/agent.go`）

| | |
|--|--|
| **现状** | ReAct：`ChatWithTools` → `execOneTool` → 回灌；默认 MaxRounds=8（帽 16）；触顶文案后仍 `AgentEventDone`；无 session_id / prior；取消走 ctx → error 事件；NeedConfirm 回灌模型但不暂停 loop 为 `awaiting_confirm` outcome |
| **缺口** | 无结构化 `run_outcome`；触顶伪装 completed；无真·续跑；无同参循环拒；无中段检查点；确认不打断为等待态 |
| **建议** | 触顶 → `incomplete`/`max_steps` + `resumable`；`AgentRes` 带 outcome/run_id；可选 `Prior []Message`；NeedConfirm 可提前结束本 run 为 `awaiting_confirm`（UI 已有确认条，语义对齐即可） |

### 7.2 Harness 架构

| | |
|--|--|
| **现状** | 预算散落常量（`defaultAgentMaxRounds`、`maxToolResultFeedChars`）；无独立 Harness 配置对象；无 trim / 循环检测 / checkpoint；SSE 事件无 outcome |
| **缺口** | 与 aiops 03 的「工程 Harness」不对齐；上下文窗口未 own；长会话必炸或静默丢配对 |
| **建议** | `HarnessConfig` + `TrimMessages` + `DetectRepeatedToolCall`；Run 开头生成 `run_id` 写入 Runtime.Audit；检查点用轻量 user 消息注入，勿上 Evolver |

### 7.3 MCP 同源 Runtime（`server/internal/aitools`）

| | |
|--|--|
| **现状** | MCP 与 Agent 共用 `Runtime.Call`；Policy 白名单 + 只读默认；P1 `read_write` + needConfirm；审计 JSONL 有 source；无 run_id；确认端点不校验语句哈希绑定；Agent 剥离模型 confirm_danger |
| **缺口** | 审计无法按一次 Agent run 聚合；确认存在「改 SQL 仍用旧气泡点执行」窗口；MCP 外部客户端若带 confirm_danger 可在 read_write 下写（设计允许外部 Agent 自带确认语义，但桌面应对齐绑定） |
| **建议** | `AuditEntry.RunID`；`ConfirmBindHash`；confirm API 校验绑定；MCP 文档写明：外部客户端的 confirm 等同操作者授权，桌面 GUI 必须绑定哈希 |

---

## 8. 落地节奏（本轮 / 下一刀）

| 优先级 | 项 | 本轮 |
|--------|-----|------|
| P0 | 文档契约（本文）+ 15 交叉引用 | ✅ |
| P0 | RunOutcome 类型、触顶 incomplete、run_id 进审计 | ✅ 代码 |
| P0 | TrimMessages / Redact / ConfirmBind 钩子 | ✅ 代码 |
| P1 | 会话落盘 + continue API + UI 恢复 | 文档契约 + session 骨架 |
| P1 | 单槽排队 UI | 文档；前端后做 |
| P2 | 同参循环拒、检查点、Ask 真 token 流 | 后置 |

---

## 9. 验收（会话层）

- [ ] `go test ./internal/ai/ ./internal/aitools/` 通过（含 outcome / trim / redact / bind）  
- [ ] 触顶轮次：响应 `run_outcome=incomplete`，`incomplete_reason=max_steps`  
- [ ] 审计行含 `run_id`（Agent 路径）  
- [ ] confirm：改 SQL 后旧 bind 拒绝  
- [ ] （P1）关窗再开：同 session 注入 prior 能继续调工具  

---

*文档版本: v1.0 | 2026-10-15 CST | 先契约与小改，大 UI 后挂*


---

## 10. 仍未完清单（对照本契约 · 2026-10-15）

| 状态 | 项 |
|------|-----|
| ✅ | MCP 工具面、Ask\|Agent、SSE、P1 确认写、`run_id` / confirmBind、触顶 incomplete |
| ✅ | 设置 → **MCP** 子页（安装检测、只读/危险 SQL、白名单、多客户端片段） |
| ✅ | 官网 AI/MCP 块 + 文档 `/docs/mcp` |
| ⬜ | 会话落盘 + HTTP 续跑（`/api/ai/sessions`）+ UI「加预算继续」 |
| ⬜ | NeedConfirm 结束 run 为 `awaiting_confirm` outcome（语义对齐） |
| ⬜ | 同参循环拒 / 中段检查点接入主循环 |
| ⬜ | 忙时单槽排队 UI |
| ⬜ | Ask 真 token 流式（非假打字） |
| ⬜ | MCP「断开」结束外部 Cursor 会话（当前仅 UI 提示） |
| ⬜ | 设置页一键 `npm install -g`（现为复制命令；避免桌面代跑需授权） |

*本节随交付勾选；大 UI 续跑优先于 Evolver / 审批流。*