refactor(harness): remove legacy agent architecture

2026-07-22 18:02:01 +08:00
parent bc36248cd8
commit 8ee7cc0b70
148 changed files with 3091 additions and 13889 deletions
@@ -0,0 +1,205 @@
+# MVP 演示手册
+
+本目录用于演示 MVP 从用户问题到诊断 Trace 的完整闭环。
+
+面试时建议先读：
+
+- `ten-minute-interview-demo.md`：10 分钟现场演示脚本。
+- `interview-walkthrough.md`：面试讲解话术。
+- `evidence-pipeline-scenarios.md`：PASS / LOW_CONFID / REJECT / no-evidence 场景矩阵。
+- `trace-inspection-checklist.md`：Trace 字段检查清单。
+- `scripts/run-interview-demo-check.ps1`：面试预检脚本，包含服务可达性、Chat、Trace、反馈和 summary 输出。
+- `scripts/run-payment-timeout-demo.ps1`：本地可执行 Demo 脚本。
+- `interview-q-and-a.md`：面试追问回答，覆盖 Agent 工程取舍、审计和评测。
+- `requests/payment-timeout-chat.json`：固定 Chat 请求 payload。
+- `requests/narrow-highcpu-chat.json`：窄范围正向观察请求。
+- `requests/hikari-no-evidence-chat.json`：no-evidence 负向观察请求。
+- `requests/safety-unsupported-claim-chat.json`：安全降级讨论请求。
+
+## 1. 前置条件
+
+- MySQL、Redis、Milvus/Zilliz、LLM 和 embedding 配置可用。
+- 安全和密钥清理不属于当前 MVP 演示范围。
+- `mvp-demo` profile 会启用 mock Prometheus 和 mock CLS，让日志和指标工具返回可复现证据。
+
+## 2. 启动服务
+
+```powershell
+mvn spring-boot:run "-Dspring-boot.run.profiles=mvp-demo"
+```
+
+服务地址：
+
+```text
+http://localhost:9900
+```
+
+## 3. Chat 诊断 Demo
+
+最快方式：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File mvp/demo/scripts/run-interview-demo-check.ps1
+```
+
+脚本会生成：
+
+```text
+mvp/demo/output/chat-response.json
+mvp/demo/output/trace-response.json
+mvp/demo/output/feedback-response.json
+mvp/demo/output/interview-demo-summary.json
+```
+
+手动请求：
+
+```powershell
+$sessionId = "mvp-demo-payment-timeout-001"
+$body = @{
+  Id = $sessionId
+  Question = "支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。"
+} | ConvertTo-Json
+
+Invoke-RestMethod `
+  -Method Post `
+  -Uri "http://localhost:9900/api/chat" `
+  -ContentType "application/json" `
+  -Body $body
+```
+
+如果要继续手动查询同一次诊断运行，先保留响应中的 run id：
+
+```powershell
+$chat = Invoke-RestMethod `
+  -Method Post `
+  -Uri "http://localhost:9900/api/chat" `
+  -ContentType "application/json" `
+  -Body $body
+
+$runId = $chat.data.runId
+```
+
+期望结果：
+
+- `data.success = true`
+- `data.sessionId = mvp-demo-payment-timeout-001`
+- `data.runId` 为本次诊断运行的唯一 ID
+- `data.answer` 包含诊断答复
+
+## 4. 查询 Trace
+
+```powershell
+Invoke-RestMethod `
+  -Method Get `
+  -Uri "http://localhost:9900/api/diagnosis/$sessionId/trace?runId=$runId"
+```
+
+期望结果：
+
+- `code = 200`
+- `data.runId` 等于 `$runId`
+- `data.session.sessionId` 等于 Chat session id
+- `data.run.runId` 等于 `$runId`
+- `data.steps` 包含 planner / executor / verifier 等步骤
+- `data.toolInvocations` 包含 `lookup_knowledge`、`query_logs`、`query_metrics` 等证据工具
+- `data.session.selfEvaluation` 包含 verifier 或 rule evaluation
+- Chat V2 链路中，`data.session.selfEvaluation.verifier_evaluation.prompt_audit.version` 记录 Chat Prompt 审计版本
+- Chat V2 链路中，`data.session.selfEvaluation.verifier_evaluation.gatekeeper_result.rule_set_version` 记录 Gatekeeper 规则集版本
+
+## 5. 提交反馈
+
+```powershell
+$feedback = @{
+  sessionId = $sessionId
+  runId = $runId
+  feedback = "useful"
+} | ConvertTo-Json
+
+Invoke-RestMethod `
+  -Method Post `
+  -Uri "http://localhost:9900/api/feedback" `
+  -ContentType "application/json" `
+  -Body $feedback
+```
+
+期望结果：
+
+- `success = true`
+- `runId = $runId`
+- 后续精确 Trace 中 `data.session.feedback = useful`
+- useful 反馈会尝试沉淀 `case_library`
+
+## 6. AIOps 告警诊断 Demo
+
+```powershell
+$aiopsSessionId = "mvp-demo-aiops-payment-cpu-001"
+$aiopsBody = @{
+  sessionId = $aiopsSessionId
+  alertName = "HighCPUUsage"
+  service = "payment-service"
+  severity = "P1"
+  description = "服务 payment-service 的 CPU 使用率持续超过 80%，当前值为 92%。实例: pod-payment-service-7d8f9c6b5-x2k4m。"
+  timeRange = "last_15m"
+  userRequest = "请结合 Prometheus 活动告警、system-metrics 日志和知识库生成告警分析报告。"
+} | ConvertTo-Json
+
+Invoke-WebRequest `
+  -Method Post `
+  -Uri "http://localhost:9900/api/ai_ops" `
+  -ContentType "application/json" `
+  -Body $aiopsBody
+```
+
+期望结果：
+
+- SSE 首条是 `type=metadata` 的 `message` 事件，包含 sessionId `mvp-demo-aiops-payment-cpu-001` 和本次 AIOps `runId`
+- 后续流式输出包含 AIOps 告警分析报告
+- 报告聚焦输入的 `HighCPUUsage/payment-service`
+- 精确 Trace 中 `data.session.agentFlow = AI_OPS`
+- `data.session.answer` 包含最终告警报告
+- `data.toolInvocations` 包含证据工具调用
+
+查询 AIOps Trace 时优先使用 SSE metadata 中的 runId：
+
+```powershell
+Invoke-RestMethod `
+  -Method Get `
+  -Uri "http://localhost:9900/api/diagnosis/$aiopsSessionId/trace?runId=$aiopsRunId"
+```
+
+## 7. Demo 主线
+
+Chat 主线：
+
+```text
+一个 session id + 一个 run id
+-> 用户问题
+-> 多 Agent 执行
+-> 证据工具
+-> Verifier / self_evaluation
+-> 最终答案
+-> 用户反馈
+-> Trace API 回放
+```
+
+AIOps 主线：
+
+```text
+一个 session id + 一个 run id
+-> 告警 payload
+-> AIOps Planner / Executor
+-> 证据工具
+-> 告警分析报告
+-> AIOps rule evaluation
+-> Trace API 回放
+```
+
+## 8. Evidence Pipeline 场景矩阵
+
+面试时不要把所有安全场景都压到 live LLM 现场表现上。建议使用：
+
+- `scripts/run-interview-demo-check.ps1` 跑主路径和预检 summary。
+- `evidence-pipeline-scenarios.md` 讲解 PASS / LOW_CONFID / REJECT / no-evidence 矩阵。
+- `mvp/eval/reports/baseline-report.md` 证明固定 fixture 12/12 通过。
+
+这样可以同时展示真实链路和确定性回归能力。