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
@@ -1,205 +1,29 @@
-# MVP 演示手册
+# 单 Diagnosis Agent Demo

-本目录用于演示 MVP 从用户问题到诊断 Trace 的完整闭环。
+**更新日期**：2026-07-22

-面试时建议先读：
+## 运行前提

- `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`：安全降级讨论请求。
+- 应用、MySQL、Redis、Milvus 与模型配置可用。
+- `cls.mock-enabled=true` 用于 query_logs Mock 证据。
+- query_mysql 只使用 `mysql-tool.datasources` 配置的隔离只读数据源；不查询应用数据库。

-## 1. 前置条件
+## 主流程

- MySQL、Redis、Milvus/Zilliz、LLM 和 embedding 配置可用。
- 安全和密钥清理不属于当前 MVP 演示范围。
- `mvp-demo` profile 会启用 mock Prometheus 和 mock CLS，让日志和指标工具返回可复现证据。
+1. 启动应用：`mvn spring-boot:run`。
+2. 向 `POST /api/chat` 提交 `requests/payment-timeout-chat.json`。
+3. 验证 SSE：`metadata -> status* -> content|failure -> done`。
+4. 保存 metadata 的 exact `session_id` 与 `run_id`。
+5. 检查 `logs/application.log` 的 Run/Tool/Guard/Release 状态，确认无 Prompt、Thought 或 raw Tool payload。
+6. 使用 `scripts/query_mysql.py` 按 exact runId 查询 `diagnosis_run`、`agent_step`、`tool_invocation`。
+7. 打开 `/trace.html?sessionId=...&runId=...` 检查聚合 Trace。

-## 2. 启动服务
+## 验收重点

-```powershell
-mvn spring-boot:run "-Dspring-boot.run.profiles=mvp-demo"
-```
+- 只有 `diagnosis_agent` 具有 Tool loop。
+- Tool 只包含 `lookup_knowledge`、`query_logs`、`query_mysql`。
+- EvidenceGuard/SemanticGuard 完成前没有 content。
+- SUCCESS 发布 typed diagnosis report；证据或语义不支持时发布固定 safe fallback。
+- query_logs 为 Mock；不把它表述为真实 CLS live 结果。

-服务地址：
-
-```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 通过。
-
-这样可以同时展示真实链路和确定性回归能力。
+旧多角色与第二诊断入口的 demo 已保存在 `archive/2026-07-22-legacy/`，不代表当前运行时。