feat(ai): session harness contract — incomplete, run_id, confirm bind

Add docs/16 for session state machine, incomplete/resume, queue semantics, and agent-loop/harness/MCP gap review. Wire RunOutcome on max-rounds, run_id through audit, TrimMessages/Redact hooks, ConfirmBindHash on write confirm path; session file skeleton without HTTP yet. No push.
2026-10-15 13:58:10 +08:00
1 parent 0aeee2b692
commit 5416e86379
@@ -0,0 +1,255 @@
+# 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 后挂*