SuperBizAgent-java/mvp/demo/README.md

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：面试预检脚本，绑定 exact runId，强制校验 Run orchestration trace，并输出 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. 启动服务

mvn spring-boot:run "-Dspring-boot.run.profiles=mvp-demo"

服务地址：

http://localhost:9900

3. Chat 诊断 Demo

最快方式：

powershell -ExecutionPolicy Bypass -File mvp/demo/scripts/run-interview-demo-check.ps1

脚本会生成：

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

自动化验收应传入唯一 -SessionId，并用 -OutputDir target/... 避免覆盖仓库样例。脚本从 Chat 响应取得 exact runId，缺少 data.run.orchestrationTrace 或 version/final node/termination reason/transitions/degraded/evidence retry count 时会立即失败。summary 额外包含 orchestrationVersion、finalNode、terminationReason、degraded、transitionCount 和 evidenceRetryCount。

手动请求：

$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：

$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

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.run.orchestrationTrace.version 非空
• data.run.orchestrationTrace.final_node 和 termination_reason 非空
• data.run.orchestrationTrace.transitions 是本次 Graph 的条件边记录
• data.run.orchestrationTrace.degraded 和 evidence_retry_count 记录安全降级与补证据次数
• 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. 提交反馈

$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

$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：

Invoke-RestMethod `
  -Method Get `
  -Uri "http://localhost:9900/api/diagnosis/$aiopsSessionId/trace?runId=$aiopsRunId"

7. Demo 主线

Chat 主线：

一个 session id + 一个 run id
-> 用户问题
-> bounded StateGraph（Planner / Executor / Gatekeeper / Verified Input / Verifier / Composer / Fallback）
-> 证据工具
-> Verifier / self_evaluation
-> run.orchestrationTrace 路由摘要
-> 最终答案
-> 用户反馈
-> Trace API 回放

AIOps 主线：

一个 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 通过。

这样可以同时展示真实链路和确定性回归能力。