osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(harness): remove legacy agent architecture

Browse Source
This commit is contained in:
zhuyongxin
2026-07-22 18:02:01 +08:00
parent bc36248cd8
commit 8ee7cc0b70
148 changed files with 3091 additions and 13889 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mvp/demo/README.md
+21 -197
View File
@@ -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/`，不代表当前运行时。
mvp/demo/archive/2026-07-22-legacy/README.md
+205
View File
@@ -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 通过。
这样可以同时展示真实链路和确定性回归能力。
mvp/demo/archive/2026-07-22-legacy/_ARCHIVE_NOTE.md
+3
View File
@@ -0,0 +1,3 @@
# Archive Note
本目录保存旧多角色与旧诊断入口 demo。当前 demo 以 `mvp/demo/README.md` 和唯一 `/api/chat` named SSE 为准。
mvp/demo/aiops-alert-acceptance.md → mvp/demo/archive/2026-07-22-legacy/aiops-alert-acceptance.md
View File
mvp/demo/evidence-pipeline-scenarios.md → mvp/demo/archive/2026-07-22-legacy/evidence-pipeline-scenarios.md
View File
mvp/demo/interview-q-and-a.md → mvp/demo/archive/2026-07-22-legacy/interview-q-and-a.md
View File
mvp/demo/interview-walkthrough.md → mvp/demo/archive/2026-07-22-legacy/interview-walkthrough.md
View File
mvp/demo/scripts/run-interview-demo-check.ps1 → mvp/demo/archive/2026-07-22-legacy/run-interview-demo-check.ps1
View File
mvp/demo/ten-minute-interview-demo.md → mvp/demo/archive/2026-07-22-legacy/ten-minute-interview-demo.md
View File
mvp/demo/archive/2026-07-22-legacy/trace-inspection-checklist.md
+58
View File
@@ -0,0 +1,58 @@
# Trace 检查清单
运行 `scripts/run-interview-demo-check.ps1` 后，用这份清单检查 `trace-response.json` 和 `interview-demo-summary.json`。
## 1. Session
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.runId` / `data.run.runId` | 是否等于 demo 响应中的 `runId` | `runId` 精确绑定这一次诊断运行 |
| `data.session.sessionId` | 是否等于 `mvp-demo-payment-timeout-001` | `sessionId` 保留多轮上下文，Trace 精确回放依赖 `runId` |
| `data.session.query` | 是否包含支付超时问题 | Trace 记录了原始用户意图 |
| `data.session.answer` | 是否包含最终诊断答案 | 最终答案没有脱离 Trace |
| `data.session.selfEvaluation` | 是否包含 verifier 或 rule evaluation | 答案经过质量门，不只是模型原始输出 |
| `data.session.selfEvaluation.verifier_evaluation.gatekeeper_result.rule_set_version` | 如果是 Chat V2 链路，是否记录 Gatekeeper 规则版本 | 安全规则可审计、可回归 |
| `data.session.selfEvaluation.verifier_evaluation.prompt_audit.version` | 如果是 Chat V2 链路，是否记录 Prompt 审计版本 | Prompt 变更可解释、可回归 |
| `data.session.selfEvaluation.verifier_evaluation.prompt_audit.prompts[*].version` | 是否记录 planner / executor / verifier / composer 版本 | 便于定位 Prompt 变更影响 |
| `data.session.feedback` | 提交反馈后是否变为 `useful` | 用户反馈挂在当前 diagnosis run 上 |
## 2. Agent 步骤
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.steps[*].agentName` | 是否有 Planner / Executor / Verifier 或等价步骤 | 流程被拆成可检查的 Agent 步骤 |
| `data.steps[*].thought` | 是否有高层步骤摘要 | 内部过程可审计，不只看最终文本 |
| `data.steps[*].durationMs` | 是否有步骤耗时 | Trace 可用于耗时分析 |
| `data.steps[*].tokenCount` | 如可用，是否记录 token | Trace 可用于模型成本分析 |
## 3. 工具证据
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.toolInvocations[*].toolName` | 是否包含 `lookup_knowledge`、`query_logs`、`query_metrics` 等证据工具 | Agent 通过工具收集证据，而不是无依据猜测 |
| `data.toolInvocations[*].inputParams` | 是否能看到每个工具的入参 | 工具输入可审计、可调试 |
| `data.toolInvocations[*].outputPreview` | 是否有受控长度的证据预览 | 保留证据但不倾倒巨大 payload |
| `data.toolInvocations[*].success` | 是否区分成功和失败 | 工具失败对 Verifier 和 reviewer 可见 |
| `data.toolInvocations[*].retrievalDetails` | 是否包含检索 metadata | 检索质量可事后检查 |
| `data.toolInvocations[*].retrievalDetails.evidence_refs` | 是否包含 `raw_path + text` | Gatekeeper 可以用代码核对 Executor 引用 |
| `data.toolInvocations[*].relevanceLevel` | 是否有相关性等级 | 可解释检索结果强弱 |
## 4. Summary
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.summary.persistedStepCount` | step 行是否持久化 | Trace 来自存储，不是响应内存 |
| `data.summary.persistedToolCallCount` | tool 行是否持久化 | 工具证据在请求结束后仍可回放 |
| `data.summary.hasVerifierEvaluation` | 是否存在 Verifier 结果 | 最终答案经过质量门 |
| `data.summary.hasFeedback` | 提交反馈后是否为 true | 人类反馈闭环完成 |
## 5. 好的结果长什么样
```text
同一个 session id + run id
-> 最终答案
-> 持久化 agent steps
-> 持久化 evidence tool calls
-> verifier / self-evaluation
-> feedback attached to the same run
```
mvp/demo/output/README.md
+5 -3
View File
@@ -2,11 +2,13 @@
本目录是本地 Demo 响应的默认输出位置。
生成文件会被 Git 忽略：
当前 named SSE Demo 生成以下文件，均被 Git 忽略：
- `chat-response.json`
- `chat-sse.txt`
- `chat-events.json`
- `trace-response.json`
- `feedback-response.json`
目录中可能存在旧版 Demo 生成的 `chat-response.json`、`feedback-response.json` 或历史 Trace；它们不是当前架构的验收证据。阶段验收必须使用本次 SSE metadata 返回的 exact `session_id + run_id` 重新生成结果。
保留此 README 是为了让目录存在于仓库中。
mvp/demo/payment-timeout-acceptance.md
+17 -24
View File
@@ -2,41 +2,34 @@
## 1. 目标
验证 MVP 能诊断支付超时问题，并暴露完整 Trace 供回放。
验证当前单 Diagnosis Agent 能诊断支付超时问题，并为一次精确 Run 暴露安全、可核对的 Trace。
## 2. 输入
- Session id：`mvp-demo-payment-timeout-001`
- 问题：`支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。`
- `session_id`：`mvp-demo-payment-timeout-001`
- 问题：结合知识库和日志证据诊断支付超时，并给出有边界的修复建议
- Profile：`mvp-demo`
## 3. 验收标准
1. Chat 返回成功答复，且 session id 与请求一致，并返回本次诊断的 run id。
2. Trace API 使用 `sessionId + runId` 返回会话元数据、运行摘要、最终答案、按顺序排列的 agent steps 和 tool invocations。
3. Trace 中有足够证据说明用了哪些工具，以及 verifier / self-evaluation 是否已持久化。
4. 可以使用同一个 session id 和本次 run id 提交反馈。
5. 后续精确 Trace 查询能看到已持久化的 feedback 值。
1. `POST /api/chat` 按 `metadata -> status* -> content|failure -> done` 顺序发送 named SSE；`content` 与 `failure` 必须互斥且只出现一次。
2. `metadata.session_id` 和 `metadata.run_id` 非空；该精确 ID 对能唯一定位持久化 Run 与 Trace。
3. Run 的 `intent=DIAGNOSIS`，终态、`release_outcome` 与 SSE `done` outcome 一致。
4. `agent_step.agent_name` 只出现 `diagnosis_agent`。AgentStep 只保存消息数量/角色、输出是否存在、Tool 名称等 metadata，不保存 Prompt、消息正文、模型正文或 Thought。
5. 每条 `tool_invocation` 都属于精确 `run_id`，Tool 名称属于 ACI allowlist，只保存有界的身份、状态、错误码、耗时和字节数 metadata；不得包含 SQL、日志查询正文、raw response、凭据或 evidence body。
6. `content` 只在 Harness guards 与 Release Policy 完成后发布；guard 或技术失败只能发布固定安全 fallback，不能泄漏 Agent 或 Tool 原始 JSON。
7. `query_logs` 明确标记为 Mock。`query_mysql` 只针对配置的隔离只读数据源验证；本验收不声称接入真实 CLS 或生产业务 MySQL。
## 4. 需要检查的 Trace 字段
- `data.runId`
- `data.run.runId`
- `data.session.query`
- `data.session.answer`
- `data.session.selfEvaluation`
- `data.session.feedback`
- `data.steps[*].agentName`
- `data.steps[*].thought`
- `data.toolInvocations[*].toolName`
- `data.toolInvocations[*].inputParams`
- `data.toolInvocations[*].outputPreview`
- `data.toolInvocations[*].retrievalDetails`
- `data.runId` 与 `data.run.runId`
- `data.session.sessionId`、`data.session.intent`、`data.session.releaseOutcome`
- `data.steps[*].agentName`、`data.steps[*].thought` 与 metadata 字段
- `data.toolInvocations[*].toolName`、identity、status、error code、duration 与 size 字段
- `data.summary`
## 5. 已知边界
- 这不是完整离线测试，仍需要有效的 chat、持久化、向量检索和模型调用环境。
- `mvp-demo` profile 启用 mock 日志和指标，让证据工具返回更稳定。
- 敏感配置清理不属于当前 MVP 优先级。
- 这是一次真实应用 E2E 验收，不能替代确定性的单元与契约测试。
- 外部模型、Redis、Milvus 和隔离数据源的可用性可能影响 live Run；失败时必须记录精确 session/run identity。
- 敏感配置治理和生产 CLS/业务 MySQL 接入不属于本次 MVP 验收范围。
mvp/demo/requests/payment-timeout-chat.json
+1 -1
View File
@@ -1,4 +1,4 @@
{
"Id": "mvp-demo-payment-timeout-001",
"Question": "支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。"
"Question": "支付接口最近出现超时。在给出结论前必须实际调用 lookup_knowledge 和 query_logs 各一次，日志范围使用 APPLICATION 并查询 payment-service error slow database；随后结束诊断，证据不足时明确说明缺口。"
}
mvp/demo/scripts/run-payment-timeout-demo.ps1
+97 -30
View File
@@ -7,55 +7,122 @@ param(
$ErrorActionPreference = "Stop"
function ConvertFrom-NamedSse {
param([Parameter(Mandatory = $true)][string]$Content)
$events = @()
foreach ($frame in ($Content -split "(?:\r?\n){2,}")) {
if ([string]::IsNullOrWhiteSpace($frame)) {
continue
}
$name = $null
$dataLines = @()
foreach ($line in ($frame -split "\r?\n")) {
if ($line.StartsWith("event:")) {
$name = $line.Substring(6).Trim()
} elseif ($line.StartsWith("data:")) {
$dataLines += $line.Substring(5).TrimStart()
}
}
if ([string]::IsNullOrWhiteSpace($name) -or $dataLines.Count -eq 0) {
throw "Invalid named SSE frame: $frame"
}
$rawData = $dataLines -join "`n"
$events += [pscustomobject]@{
name = $name
payload = $rawData | ConvertFrom-Json
}
}
return @($events)
}
function Assert-ChatSseContract {
param(
[Parameter(Mandatory = $true)][array]$Events,
[Parameter(Mandatory = $true)][string]$ExpectedSessionId
)
if ($Events.Count -lt 3) {
throw "Chat SSE must contain metadata, a terminal event, and done"
}
if ($Events[0].name -ne "metadata") {
throw "First Chat SSE event must be metadata"
}
if ($Events[-1].name -ne "done") {
throw "Last Chat SSE event must be done"
}
$terminalEvents = @($Events | Where-Object { $_.name -in @("content", "failure") })
if ($terminalEvents.Count -ne 1 -or $Events[-2].name -ne $terminalEvents[0].name) {
throw "Chat SSE must contain exactly one content or failure immediately before done"
}
$allowed = @("metadata", "status", "content", "failure", "done")
$unknown = @($Events | Where-Object { $_.name -notin $allowed })
if ($unknown.Count -gt 0) {
throw "Chat SSE contains unknown events: $($unknown.name -join ', ')"
}
$invalidMiddle = @()
if ($Events.Count -gt 3) {
$invalidMiddle = @($Events[1..($Events.Count - 3)] |
Where-Object { $_.name -ne "status" })
}
if ($invalidMiddle.Count -gt 0) {
throw "Only status events are allowed between metadata and the terminal event"
}
$metadata = $Events[0].payload
if ($metadata.session_id -ne $ExpectedSessionId) {
throw "SSE session_id does not match the requested SessionId"
}
if ([string]::IsNullOrWhiteSpace([string]$metadata.run_id)) {
throw "SSE metadata is missing run_id"
}
$outcome = [string]$Events[-1].payload.outcome
if ($terminalEvents[0].name -eq "failure" -and $outcome -ne "FAILED") {
throw "A failure event must end with outcome FAILED"
}
if ($terminalEvents[0].name -eq "content" -and $outcome -notin @("SUCCESS", "FALLBACK")) {
throw "A content event must end with outcome SUCCESS or FALLBACK"
}
}
New-Item -ItemType Directory -Force -Path $OutputDir | Out-Null
$request = Get-Content -Raw -Encoding UTF8 -Path $RequestFile | ConvertFrom-Json
$request.Id = $SessionId
$body = $request | ConvertTo-Json -Depth 8
Write-Host "正在运行支付超时 Chat 诊断 Demo..."
Write-Host "Running payment-timeout Chat E2E"
Write-Host "BaseUrl: $BaseUrl"
Write-Host "SessionId: $SessionId"
$chat = Invoke-RestMethod `
$response = Invoke-WebRequest `
-UseBasicParsing `
-Method Post `
-Uri "$BaseUrl/api/chat" `
-Headers @{ Accept = "text/event-stream" } `
-ContentType "application/json; charset=utf-8" `
-Body $body
$chat | ConvertTo-Json -Depth 20 | Set-Content -Encoding UTF8 -Path "$OutputDir/chat-response.json"
Write-Host "已保存 Chat 响应: $OutputDir/chat-response.json"
$response.Content | Set-Content -Encoding UTF8 -Path "$OutputDir/chat-sse.txt"
$events = @(ConvertFrom-NamedSse -Content $response.Content)
Assert-ChatSseContract -Events $events -ExpectedSessionId $SessionId
$events | ConvertTo-Json -Depth 50 | Set-Content -Encoding UTF8 -Path "$OutputDir/chat-events.json"
$runId = $chat.data.runId
if (-not $runId) {
throw "Chat 响应缺少 runId，无法查询精确 Trace。"
}
$runId = [string]$events[0].payload.run_id
Write-Host "RunId: $runId"
Write-Host "SSE sequence: $($events.name -join ' -> ')"
$trace = Invoke-RestMethod `
-Method Get `
-Uri "$BaseUrl/api/diagnosis/$SessionId/trace?runId=$([System.Uri]::EscapeDataString($runId))"
$trace | ConvertTo-Json -Depth 50 | Set-Content -Encoding UTF8 -Path "$OutputDir/trace-response.json"
Write-Host "已保存 Trace 响应: $OutputDir/trace-response.json"
$feedbackBody = @{
sessionId = $SessionId
runId = $runId
feedback = "useful"
} | ConvertTo-Json
$feedback = Invoke-RestMethod `
-Method Post `
-Uri "$BaseUrl/api/feedback" `
-ContentType "application/json; charset=utf-8" `
-Body $feedbackBody
$feedback | ConvertTo-Json -Depth 20 | Set-Content -Encoding UTF8 -Path "$OutputDir/feedback-response.json"
Write-Host "已保存反馈响应: $OutputDir/feedback-response.json"
Write-Host ""
Write-Host "Demo 已完成，请检查:"
Write-Host "- mvp/demo/output/chat-response.json"
Write-Host "- mvp/demo/output/trace-response.json"
Write-Host "- mvp/demo/output/feedback-response.json"
Write-Host "E2E artifacts:"
Write-Host "- $OutputDir/chat-sse.txt"
Write-Host "- $OutputDir/chat-events.json"
Write-Host "- $OutputDir/trace-response.json"
mvp/demo/trace-inspection-checklist.md
+10 -56
View File
@@ -1,58 +1,12 @@
# Trace 检查清单
运行 `scripts/run-interview-demo-check.ps1` 后，用这份清单检查 `trace-response.json` 和 `interview-demo-summary.json`。
## 1. Session
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.runId` / `data.run.runId` | 是否等于 demo 响应中的 `runId` | `runId` 精确绑定这一次诊断运行 |
| `data.session.sessionId` | 是否等于 `mvp-demo-payment-timeout-001` | `sessionId` 保留多轮上下文，Trace 精确回放依赖 `runId` |
| `data.session.query` | 是否包含支付超时问题 | Trace 记录了原始用户意图 |
| `data.session.answer` | 是否包含最终诊断答案 | 最终答案没有脱离 Trace |
| `data.session.selfEvaluation` | 是否包含 verifier 或 rule evaluation | 答案经过质量门，不只是模型原始输出 |
| `data.session.selfEvaluation.verifier_evaluation.gatekeeper_result.rule_set_version` | 如果是 Chat V2 链路，是否记录 Gatekeeper 规则版本 | 安全规则可审计、可回归 |
| `data.session.selfEvaluation.verifier_evaluation.prompt_audit.version` | 如果是 Chat V2 链路，是否记录 Prompt 审计版本 | Prompt 变更可解释、可回归 |
| `data.session.selfEvaluation.verifier_evaluation.prompt_audit.prompts[*].version` | 是否记录 planner / executor / verifier / composer 版本 | 便于定位 Prompt 变更影响 |
| `data.session.feedback` | 提交反馈后是否变为 `useful` | 用户反馈挂在当前 diagnosis run 上 |
## 2. Agent 步骤
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.steps[*].agentName` | 是否有 Planner / Executor / Verifier 或等价步骤 | 流程被拆成可检查的 Agent 步骤 |
| `data.steps[*].thought` | 是否有高层步骤摘要 | 内部过程可审计，不只看最终文本 |
| `data.steps[*].durationMs` | 是否有步骤耗时 | Trace 可用于耗时分析 |
| `data.steps[*].tokenCount` | 如可用，是否记录 token | Trace 可用于模型成本分析 |
## 3. 工具证据
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.toolInvocations[*].toolName` | 是否包含 `lookup_knowledge`、`query_logs`、`query_metrics` 等证据工具 | Agent 通过工具收集证据，而不是无依据猜测 |
| `data.toolInvocations[*].inputParams` | 是否能看到每个工具的入参 | 工具输入可审计、可调试 |
| `data.toolInvocations[*].outputPreview` | 是否有受控长度的证据预览 | 保留证据但不倾倒巨大 payload |
| `data.toolInvocations[*].success` | 是否区分成功和失败 | 工具失败对 Verifier 和 reviewer 可见 |
| `data.toolInvocations[*].retrievalDetails` | 是否包含检索 metadata | 检索质量可事后检查 |
| `data.toolInvocations[*].retrievalDetails.evidence_refs` | 是否包含 `raw_path + text` | Gatekeeper 可以用代码核对 Executor 引用 |
| `data.toolInvocations[*].relevanceLevel` | 是否有相关性等级 | 可解释检索结果强弱 |
## 4. Summary
| JSON path | 检查点 | 面试讲点 |
|---|---|---|
| `data.summary.persistedStepCount` | step 行是否持久化 | Trace 来自存储，不是响应内存 |
| `data.summary.persistedToolCallCount` | tool 行是否持久化 | 工具证据在请求结束后仍可回放 |
| `data.summary.hasVerifierEvaluation` | 是否存在 Verifier 结果 | 最终答案经过质量门 |
| `data.summary.hasFeedback` | 提交反馈后是否为 true | 人类反馈闭环完成 |
## 5. 好的结果长什么样
```text
同一个 session id + run id
-> 最终答案
-> 持久化 agent steps
-> 持久化 evidence tool calls
-> verifier / self-evaluation
-> feedback attached to the same run
```
- [ ] SSE metadata 的 `session_id`、`run_id` 非空且与数据库完全一致。
- [ ] `diagnosis_run.intent=DIAGNOSIS`，status/release_outcome 与 done outcome 一致。
- [ ] `agent_step.agent_name` 只出现 `diagnosis_agent`。
- [ ] AgentStep model_input/model_output 只含 metadata，thought 为空。
- [ ] ToolInvocation 全部属于 exact runId，Tool 名在 ACI allowlist 内。
- [ ] ToolInvocation input/output/retrieval details 不含 SQL、日志 query、raw response 或 evidence body。
- [ ] Run 的模型/Tool/Token/字节预算均未超过集中配置。
- [ ] content 只出现一次并来自 Release Policy；failure 与 content 互斥。
- [ ] `logs/application.log` 不含 Prompt、Thought、完整 Tool 参数、raw response、vendor exception 或 stack 泄漏。
- [ ] query_logs 标记为 Mock；query_mysql 只使用隔离只读 datasource contract。