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

feat(trace): finish run-aware demo verification

Browse Source
This commit is contained in:
zhuyongxin
2026-07-10 21:37:43 +08:00
parent 78c1477198
commit f9df94377b
28 changed files with 779 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mvp/architecture/data-model.md
+70 -194
View File
@@ -1,31 +1,44 @@
# 数据模型总览
**更新日期**：2026-07-08
**更新日期**：2026-07-10
**状态**：当前可运行架构
## 1. 定位
本文从架构角度说明当前 MVP 的核心数据模型。详细字段仍以 Flyway migration 和 `mvp/tables/` 为准。
本文从架构角度说明当前 MVP 的核心数据模型。详细字段以 Flyway migration、实体类和 `mvp/tables/` 为准。
核心数据分三组：
- 诊断 Trace：`diagnosis_session`、`agent_step`、`tool_invocation`
- 会话与诊断 Trace：`chat_session`、`diagnosis_run`、`agent_step`、`tool_invocation`
- 知识库：`api_document`、`knowledge_domain`、Milvus/Zilliz metadata
- 反馈沉淀：`case_library`
`diagnosis_session` 仍保留为历史兼容和回滚表，不再是新执行写入的主模型。
## 2. 总体关系
```mermaid
erDiagram
diagnosis_session ||--o{ agent_step : has
diagnosis_session ||--o{ tool_invocation : has
diagnosis_session ||--o| case_library : creates_when_useful
chat_session ||--o{ diagnosis_run : owns
diagnosis_run ||--o{ agent_step : has
diagnosis_run ||--o{ tool_invocation : has
diagnosis_run ||--o| case_library : creates_when_useful
api_document ||--o{ milvus_chunk : indexed_as
knowledge_domain ||--o{ api_document : groups
diagnosis_session {
chat_session {
bigint id
varchar session_id
varchar status
int message_pair_count
datetime last_active_at
datetime expires_at
}
diagnosis_run {
bigint id
varchar run_id
varchar session_id
text query
varchar status
varchar agent_flow
@@ -37,42 +50,23 @@ erDiagram
agent_step {
bigint id
varchar session_id
varchar run_id
int step_index
varchar agent_name
text model_input
text model_output
text thought
boolean has_tool_call
}
tool_invocation {
bigint id
varchar session_id
varchar run_id
bigint step_id
varchar tool_name
json input_params
text output_preview
varchar retrieval_layer
json retrieval_details
varchar relevance_level
varchar dedup_reason
}
api_document {
bigint id
varchar doc_id
varchar file_name
varchar file_path
varchar status
int chunk_count
text metadata
}
knowledge_domain {
bigint id
varchar domain_id
varchar description
text when_to_retrieve
int document_count
}
case_library {
@@ -84,58 +78,52 @@ erDiagram
text root_cause
text solution
}
milvus_chunk {
varchar id
text content
json metadata
vector vector
}
```
说明：Milvus/Zilliz collection 不是 MySQL 表，图中的 `milvus_chunk` 是逻辑模型。
## 3. 诊断 Trace 模型
## 3. 会话与运行模型
### diagnosis_session
### chat_session
会话级主记录。
关键字段：
`chat_session` 是会话目录表，保存 `sessionId` 的元数据：
| 字段 | 说明 |
|---|---|
| `session_id` | 外部关联键，Trace 和 Feedback 都使用它 |
| `query` | 用户原始问题或 AIOps 输入摘要 |
| `status` | 执行状态 |
| `session_id` | 外部会话 ID，用于多轮上下文和 run 列表 |
| `status` | 会话目录状态 |
| `message_pair_count` | Redis 对话轮次数快照 |
| `last_active_at` | 最近活跃时间 |
| `expires_at` | 可为空的目录 TTL 元数据 |
它不保存完整对话历史，正文消息仍由 Redis `SessionContext.messageHistory` 管理。
### diagnosis_run
`diagnosis_run` 是一次可回放诊断执行的主记录：
| 字段 | 说明 |
|---|---|
| `run_id` | 运行 ID，格式为 `run-` + UUID |
| `session_id` | 所属 `chat_session.session_id` |
| `query` | 本次 Chat 问题或 AIOps 告警摘要 |
| `status` | 本次执行状态 |
| `agent_flow` | `CHAT` / `AI_OPS` |
| `answer` | 最终答复或告警报告 |
| `self_evaluation` | rule/verifier/aiops 自评估容器 |
| `feedback` | 用户反馈 |
| `answer` | 本次运行最终答复或告警报告 |
| `self_evaluation` | 本次运行的 rule/verifier/aiops 自评估容器 |
| `feedback` | 本次运行的用户反馈 |
同一个 `sessionId` 可以有多个 `runId`。Trace、反馈、评测和案例沉淀都应优先使用 `runId`，避免多轮同 session 下的数据混合。
## 4. Trace 明细模型
### agent_step
记录模型调用步骤。
用途：
- 回放 Agent 推理过程。
- 查看 Planner / Executor / Verifier 的输入输出摘要。
- 统计 step count、duration、token count。
`agent_step` 记录模型调用步骤。新写入同时保留 `session_id` 和 `run_id`，其中 `run_id` 是回放边界。Trace 页面和评测应先按 `run_id` 隔离取数，展示顺序以 Trace API 返回顺序为准。
### tool_invocation
记录工具调用事实。
用途：
- 给 Trace API 展示证据。
- 给 Gatekeeper 提供 `retrieval_details.evidence_refs` 引用验真源。
- 给 Verifier 构造 `tool_trace_summary` 审计导航。
- 给 `EvaluationService` 计算 evidence score。
- 给 RAG eval 和人工排查提供检索细节。
`retrieval_details.evidence_refs` 是当前 Chat 证据链路的关键字段：
`tool_invocation` 记录显式工具调用事实。`retrieval_details.evidence_refs` 是 Chat 证据链路的关键字段：
```json
{
@@ -149,83 +137,28 @@ erDiagram
}
```
字段边界：
| 字段 | 说明 |
|---|---|
| `evidence_status` | 工具证据状态，例如 `supported`、`no_evidence`、`deduped`、`failed` |
| `evidence_refs[].raw_path` | Executor 可引用的稳定路径，例如 `$.logs[0]`、`$.alerts[0]`、`$.evidence_blocks[0]`、`$.no_evidence` |
| `evidence_refs[].text` | 系统抽取的最小证据文本，Gatekeeper 用它核对 `evidence_excerpt` |
`$.no_evidence` 只表示“本次工具查询未检索到匹配证据”，不能被解释为“问题不存在”或“根因已排除”。
## 4. 知识库模型
### api_document
MySQL 中的文档元数据表。
职责：
- 管理上传文件。
- 保存 file hash，用于去重。
- 记录索引状态和 chunk 数量。
- 保存 frontmatter JSON。
### knowledge_domain
领域级元数据。
职责：
- 按 category 聚合文档。
- 存储领域描述。
- 存储 `when_to_retrieve`，辅助 Planner/Executor 判断什么时候检索该领域。
### Milvus/Zilliz metadata
向量 collection 中每个 chunk 的 metadata 主要包括：
```text
docId
_source
chunkIndex
totalChunks
title
breadcrumb
category
```
这些字段支撑：
- category filter。
- source 展示。
- breadcrumb 上下文。
- docId 删除和重建索引。
- evidence block 构造。
## 5. 反馈沉淀模型
### case_library
`useful` 反馈会触发 `CaseLibraryService.createFromSession`。
`useful` 反馈会触发 `CaseLibraryService.createFromRun`。
当前自动映射：
| 字段 | 来源 |
|---|---|
| `case_id` | UUID |
| `diagnosis_id` | `diagnosis_session.session_id` |
| `diagnosis_id` | 新数据为 `diagnosis_run.run_id`；历史数据可能为 `diagnosis_session.session_id` |
| `source_type` | `AUTO` |
| `fault_category` | 当前默认 `GENERAL` |
| `title` | session query 前 100 字符 |
| `root_cause` | session answer |
| `solution` | session answer |
| `title` | run query 前 100 字符 |
| `root_cause` | run answer |
| `solution` | run answer |
| `created_by` | `system` |
## 6. self_evaluation 结构
`diagnosis_session.self_evaluation` 是 JSON 容器：
`diagnosis_run.self_evaluation` 是运行级 JSON 容器：
```json
{
@@ -235,78 +168,21 @@ category
}
```
边界：
Chat 通常写入 `rule_evaluation` 和 `verifier_evaluation`；AIOps 写入 `aiops_rule_evaluation`。
- `rule_evaluation` 评估证据收集充分度。
- `verifier_evaluation` 评估 Chat 结构化 claims 是否能由已验真证据推出，并保存 Gatekeeper、Verifier、Composer 的审计数据。
- `aiops_rule_evaluation` 评估 AIOps 报告是否聚焦告警并使用证据。
当前 `verifier_evaluation` 关键结构：
```json
{
"verdict": "PASS",
"groundedness_score": 1.0,
"critical_fact_count": 1,
"claim_checks": [],
"facts_checked": [],
"rationale": "...",
"round": 1,
"traceability_version": "v1",
"executor_output_parse_status": {},
"executor_structured_output": {},
"gatekeeper_result": {},
"composer_output": {},
"tool_trace_summary": []
}
```
必要审计字段：
| 字段 | 说明 |
|---|---|
| `executor_output_parse_status` | Executor 输出是否能解析为 `executor_evidence_v2` |
| `executor_structured_output` | Executor 结构化 claims、hypotheses、recommended_actions、missing_info |
| `gatekeeper_result` | 引用真实性校验结果，包括 rule set version、checked bindings、failed rules、warnings、errors |
| `composer_output` | Composer 最终表达及解析状态 |
| `tool_trace_summary` | Verifier 调用时使用的工具调用导航索引，不是唯一证据源 |
## 7. 数据写入时序
```mermaid
sequenceDiagram
autonumber
participant API as API
participant Svc as ChatService/AiOpsService
participant Session as diagnosis_session
participant Agent as Agent
participant Step as agent_step
participant Tool as tool_invocation
participant Eval as self_evaluation
participant Feedback as case_library
API->>Svc: request
Svc->>Session: create/update RUNNING
Agent->>Step: before/after model
Agent->>Tool: tool call record
Svc->>Session: SUCCESS/FAILED + answer
Svc->>Eval: merge evaluation
API->>Svc: feedback useful
Svc->>Feedback: create case
```
## 8. 当前边界和后续
## 7. 当前边界和后续
当前边界：
- `agent_step.session_id` 和 `tool_invocation.session_id` 通过 sessionId 关联，不强制外键。
- `tool_invocation.step_id` 可为空。
- Milvus chunk 与 `api_document` 通过 metadata.docId 逻辑关联。
- `case_library` 与 session 通过 `diagnosis_id=session_id` 关联。
- `chat_session` 只存会话元数据，不存完整正文历史。
- `diagnosis_run` 存一次运行的长期审计状态。
- `agent_step.run_id` 和 `tool_invocation.run_id` 是 Trace、Verifier、Eval 的运行边界。
- 当前实现主要使用逻辑关联，不依赖数据库外键。
- `case_library.diagnosis_id` 是过渡字段，新值按 `run_id` 解释，旧值可能按 `session_id` 解释。
- `diagnosis_session` 只作为历史兼容和回滚表保留。
后续可增强：
1. 增加 run id，支持同 session 多次独立诊断。
2. 强化 `tool_invocation.step_id` 关联。
3. 将 Gatekeeper 规则配置化时的规则元数据保存为可审计版本。
4. 将 `case_library` 的 rootCause/solution 从完整 answer 中结构化抽取。
1. 强化 `tool_invocation.step_id` 关联。
2. 将 Gatekeeper 规则配置化时的规则元数据保存为可审计版本。
3. 将 `case_library` 的 rootCause/solution 从完整 answer 中结构化抽取。