SuperBizAgent-java/mvp/engineering/diagnosis/一次诊断全流程-E2E导读.md

一次诊断到底发生了什么（E2E 全流程导读）

日期：2026-07-28
状态：SUCCESS 完整诊断主文档；工具阶段按现行审计能力（step_id / query）说明
文档路径：mvp/engineering/diagnosis/一次诊断全流程-E2E导读.md

现状说明（2026-09-29）：本文基于 2026-07 的 live Run 编写，图中 VectorSearchService / MilvusHybridKnowledgeStore（进程内 Milvus）已替换为 py-rag 服务调用；审计/Trace 结构不变。 当前检索链路见 ../architecture/RAG知识检索架构.md。

主样本（正文数值与 timeline 来源）

项	值
session_id	e2e-rag-success-20260728162949
run_id	27415045-e674-41af-9cea-de01f27ce040
入口	POST /api/chat（SSE）
结果	outcome=SUCCESS，content_type=DIAGNOSIS_REPORT
工具	仅 1 次 lookup_knowledge（hybrid）
模型	4 次（Router + Agent×2 + Semantic Guard）
Token	13236（tokens_reconciled=true）
耗时	~25s

现行审计（step_id 挂 step、input_params.query 等）已合入主路径，见 §3.4.1。
专项 live 验收（含一次业务 FALLBACK 样本）见独立文档：
→ RAG 审计补丁 E2E：step_id + query

关联文档：

• [RAG Trace / 审计架构](../../architecture/RAG检索可观测性与审计.md)
• RAG qualityScore 与后处理
• Agent 如何读 relevance_level
• [知识检索架构](../../architecture/RAG知识检索架构.md)

回放 API：

GET /api/diagnosis/{sessionId}/trace?runId={runId}
GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}

本地产物（若仍在）：target/e2e-rag-success-sse.txt、target/e2e-rag-success-trace.json。

---

1. 先建立心智模型

一次「诊断」不是「调一次 LLM 再返回答案」，而是 Harness 编排的多阶段流水线：

1. 协议层建 session/run，打开 SSE
2. 路由模型判定意图（本次 DIAGNOSIS）
3. 诊断 Agent 规划并调用工具（本次 RAG）
4. 工具返回证据（Agent 只看投影结果，完整轨迹进审计）
5. 诊断 Agent 基于证据写报告草稿
6. 证据结构门控 + 语义门控
7. 放行 SUCCESS 报告，或降级 FALLBACK
8. 落库并对账 token / timeline，供 Trace 回放

flowchart LR
    U[用户 / 客户端] -->|POST /api/chat| API[ChatController SSE]
    API --> H[Diagnosis Harness]
    H --> R[Intent Router]
    H --> A[Diagnosis Agent]
    H --> T[Tools]
    H --> G[Guards]
    H --> REL[Release]
    T --> RAG[lookup_knowledge<br/>Hybrid Milvus]
    T --> LOG[query_logs / 其它]
    REL --> SSE[SSE content + done]
    H --> DB[(MySQL 审计与 Trace)]
    DB --> TR[GET .../trace]

读本文时记住三句话：

1. SSE 是对外协议；timeline / tool_invocation 是对内账本。
2. Agent 看到的工具结果 ≠ 完整 RAG trace（中间有投影边界）。
3. run.total_token_count 含 Router + Agent + Guard；agent_step.tokenCount 只含诊断 Agent 各轮。

---

2. 逻辑架构：谁在场

flowchart TB
    subgraph edge["边缘 / 协议"]
        CC[ChatController]
        SSE[ChatSseSession]
    end

    subgraph app["应用用例"]
        UC[ChatApplicationUseCase]
        EX[DiagnosisChatExecutor]
    end

    subgraph harness["Harness 核心"]
        CORE[DiagnosisHarnessCore<br/>RunContext / Budget]
        ROUTER[Intent Router]
        AGENT[Diagnosis Agent<br/>+ Tool Calling]
        BOUND[ToolBoundary]
        EG[Evidence Guard]
        SG[Semantic Guard]
        REL[DiagnosisReleaseUseCase]
    end

    subgraph tools["工具层"]
        LK[LookupKnowledgeTool]
        QL[QueryLogsTools]
        OTHER[其它工具...]
    end

    subgraph rag["RAG 子系统"]
        EMB[Embedding BGE-M3]
        VS[VectorSearchService]
        HY[MilvusHybridKnowledgeStore<br/>dense + BM25 + RRF]
        PP[Evidence PostProcessor<br/>quality / relevance_level]
    end

    subgraph audit["审计与回放"]
        MCA[ModelCallAuditor]
        TIS[JpaToolInvocationAuditSink<br/>+ RagLookupAuditEnricher]
        DTR[DiagnosisTraceRecorder]
        API2[DiagnosisTraceController]
        MY[(diagnosis_run<br/>agent_step<br/>tool_invocation<br/>diagnosis_trace_event)]
    end

    CC --> SSE
    CC --> UC --> EX --> CORE
    CORE --> ROUTER
    CORE --> AGENT
    AGENT --> BOUND --> LK
    BOUND --> QL
    LK --> EMB --> VS --> HY
    VS --> PP
    EX --> EG --> SG --> REL --> SSE
    CORE --> MCA --> DTR
    BOUND --> TIS --> MY
    DTR --> MY
    API2 --> MY

角色	职责一句话
ChatController	HTTP/SSE 适配，不承载诊断逻辑
Intent Router	判断是否进入诊断
Diagnosis Agent	规划工具、消化证据、写草稿
ToolBoundary	工具执行边界：投影给 Agent + 审计落库
lookup_knowledge	只检索，不写结论
Evidence Guard	结构/引用可核验性（偏规则）
Semantic Guard	语义是否被证据支撑（偏模型）
Release	终态与对外 content 形态
Auditors / Trace	token、步骤、工具、事件可回放

---

3. 端到端时序（本次真实路径）

sequenceDiagram
    autonumber
    actor User as 客户端
    participant API as ChatController
    participant H as Harness
    participant Router as Intent Router LLM
    participant Agent as Diagnosis Agent LLM
    participant Tool as lookup_knowledge
    participant Emb as Embedding
    participant Milvus as Hybrid Milvus
    participant EG as Evidence Guard
    participant SG as Semantic Guard LLM
    participant DB as MySQL

    User->>API: POST /api/chat {Id, Question}
    API->>User: event metadata {session_id, run_id}
    API->>H: start run
    H->>DB: diagnosis_run + RUN_STARTED
    API->>User: event status ROUTING

    H->>Router: 路由 prompt + 用户问题
    Router-->>H: intent=DIAGNOSIS (906 tokens)
    H->>DB: ROUTING_* + MODEL_TOKEN_USAGE

    API->>User: event status DIAGNOSIS_RUNNING
    H->>Agent: round1 system/user + tools schema
    Agent-->>H: tool_call lookup_knowledge (2657 tokens)
    H->>DB: agent_step#0 + AGENT_MODEL_STEP

    H->>Tool: execute(query)
    Tool->>Emb: embed query (1024-d)
    Emb-->>Tool: vector
    Tool->>Milvus: hybridSearch dense+BM25+RRF
    Milvus-->>Tool: topK candidates
    Tool-->>H: LookupResult + projected RagToolResult
    H->>DB: tool_invocation + TOOL_INVOCATION<br/>PRECISE / hybrid / EVIDENCE_FOUND

    H->>Agent: round2 user+assistant+tool
    Agent-->>H: DIAGNOSIS draft JSON (4703 tokens)
    H->>DB: agent_step#1

    H->>EG: 校验 tool_call 引用
    EG-->>H: PASSED
    API->>User: event status SAFETY_VALIDATING

    H->>SG: 报告 + 证据摘要
    SG-->>H: verdict=SUPPORTED (4970 tokens)

    H->>H: RELEASE SUCCESS
    API->>User: event content DIAGNOSIS_REPORT
    API->>User: event done SUCCESS
    H->>DB: RUN_FINISHED tokens_reconciled<br/>total=13236

---

4. 状态机与对外 SSE 契约

4.1 内部阶段机

stateDiagram-v2
    [*] --> RUN_STARTED
    RUN_STARTED --> ROUTING
    ROUTING --> DIAGNOSIS_AGENT: intent=DIAGNOSIS
    ROUTING --> OTHER_PATH: 非诊断意图
    DIAGNOSIS_AGENT --> TOOL_LOOP: 发出 tool_call
    TOOL_LOOP --> DIAGNOSIS_AGENT: 工具结果回注
    DIAGNOSIS_AGENT --> EVIDENCE_GUARD: 产出草稿且不再调工具
    EVIDENCE_GUARD --> SEMANTIC_GUARD: PASSED
    EVIDENCE_GUARD --> FALLBACK_OR_REPAIR: 结构失败
    SEMANTIC_GUARD --> RELEASE_SUCCESS: SUPPORTED
    SEMANTIC_GUARD --> RELEASE_FALLBACK: 不足/不支持
    RELEASE_SUCCESS --> RUN_FINISHED
    RELEASE_FALLBACK --> RUN_FINISHED
    OTHER_PATH --> RUN_FINISHED

4.2 SSE 事件顺序（成功路径）

flowchart LR
    M[metadata] --> S1[status ROUTING]
    S1 --> S2[status DIAGNOSIS_RUNNING]
    S2 --> S3[status SAFETY_VALIDATING]
    S3 --> C[content DIAGNOSIS_REPORT]
    C --> D[done SUCCESS]

event	何时出现	本次含义
metadata	立刻	绑定 session_id / run_id
status	可多次	进度码：路由 / 收集证据 / 安全校验
content	成功终稿一次	DIAGNOSIS_REPORT 载荷
done	最后	outcome=SUCCESS / FALLBACK / FAILED
failure	与 content 互斥	本次未出现

请求体字段：

字段	含义
Id	会话 ID（可多轮复用）
Question	本轮问题 → 写入 diagnosis_run.query

---

5. 分阶段详解：发送了什么、产出什么、字段含义

下面每阶段统一用四块说明：职责 / 发送 / 产出 / 字段。数值均来自样本 run。

---

阶段 0 — HTTP 接入与 Run 创建

职责：协议适配；创建 session/run；打开 SSE。不做诊断推理。

发送：

• 客户端 → 服务：POST /api/chat JSON
• 服务 → 客户端：metadata

产出：

• diagnosis_run 初始行
• timeline：RUN_STARTED

字段	含义
session_id	对话会话身份
run_id	这一次诊断执行 ID（一问一 run）
agent_flow	入口形态；Chat 为 CHAT
query	用户原问题

flowchart LR
    REQ[Request Id+Question] --> NEW[创建 run_id]
    NEW --> META[SSE metadata]
    NEW --> ROW[diagnosis_run PENDING/RUNNING]
    NEW --> EV[timeline RUN_STARTED]

---

阶段 1 — ROUTING（意图路由）

职责：判断走诊断 / 其它路径。不调业务工具、不查知识库。

发送：1 次 Chat 模型（Intent Router）

	tokens
input	323
output	583
total	906

产出 timeline：

1. MODEL_TOKEN_USAGE（component=INTENT_ROUTER）
2. ROUTING_ATTEMPT
3. ROUTING_DECISION → intent=DIAGNOSIS

字段	含义
component	模型组件名：INTENT_ROUTER
component_round	该组件第几轮
input_tokens / output_tokens / total_tokens	本调用 usage
usage_available	供应商是否返回 usage
intent	路由结果；DIAGNOSIS 进入诊断 harness

SSE：status: ROUTING。

flowchart TB
    Q[用户问题] --> RP[路由 Prompt]
    RP --> LLM[Intent Router LLM]
    LLM --> D{intent}
    D -->|DIAGNOSIS| DIAG[进入诊断执行器]
    D -->|其它| OTH[非诊断路径]
    LLM --> TU[MODEL_TOKEN_USAGE 入账]

---

阶段 2 — AGENT round 1（规划并调用工具）

职责：读问题与工具 schema，决定调谁、参数是什么。本轮通常 只出 tool_call，不写最终报告。

发送：1 次 Diagnosis Agent 模型

step_index	0
duration	1454 ms
tokens	in 2554 / out 103 / total 2657
modelOutput	has_text=false, tool_names=["lookup_knowledge"]

产出：

• agent_step #0
• timeline：MODEL_TOKEN_USAGE + AGENT_MODEL_STEP
• 内部 tool_call_id：call_00_91fKPqaJg4z4gvvZIqcA8891

字段	含义
stepIndex	Agent 模型轮次，从 0 起
agentName	如 diagnosis_agent
tokenCount	本步模型 total tokens（不含 router/guard）
durationMs	本步墙钟耗时
modelInput	输入摘要（roles、message_count），非全文 prompt
modelOutput	输出摘要：是否有正文、工具名列表、reasoning 标记
hasToolCall	是否触发工具
thought	思维链（若有）；样本为空

flowchart LR
    CTX[上下文: user + tools schema] --> A1[Agent LLM r1]
    A1 --> TC[tool_call<br/>lookup_knowledge]
    A1 --> ST0[agent_step 0 落库]
    TC --> BOUND[进入 ToolBoundary]

---

阶段 3 — TOOL：lookup_knowledge（Hybrid RAG）

职责：只检索。把 query 变成可引用证据；完整轨迹进审计，Agent 只拿投影后的证据契约。

3.1 工具内架构

flowchart TB
    TC[tool_call query] --> TB[ToolBoundary]
    TB --> LK[LookupKnowledgeTool]
    LK --> L0[L0 Hint<br/>关键词 / 域]
    LK --> QT[QueryTransformer<br/>category / keywords]
    LK --> EMB[EmbeddingService<br/>BGE-M3 1024d]
    EMB --> VS[VectorSearchService]
    VS --> HY[Milvus hybridSearch]
    HY --> D[dense ANN L2]
    HY --> S[BM25 sparse]
    D --> RRF[服务端 RRF 融合]
    S --> RRF
    RRF --> PP[PostProcess<br/>qualityScore / relevance_level<br/>截断预算]
    PP --> RAW[LookupResult 内部 JSON]
    RAW --> PROJ[Projector → RagToolResult]
    PROJ --> AGENT[返回 Agent]
    RAW --> AUD[RagLookupAuditEnricher]
    AUD --> TI[(tool_invocation)]
    TB --> TL[timeline TOOL_INVOCATION]

3.2 样本实测

项	值
query_chars	50
retrieveK	20
search_mode	hybrid
tool duration_ms	1243
attempt duration_ms	~1174
relevance_level	PRECISE
evidence_status	EVIDENCE_FOUND
candidates → blocks	20 → 5
top_similarity	~0.808（dense 闸门侧）
context	3022 / 4000，truncated=false
L0 domains	infrastructure, database
selected_attempt	UNFILTERED_VECTOR（无 fallback）

3.3 retrieval_details（audit_schema=rag_lookup_v1）字段词典

字段	含义
audit_schema	审计 JSON 版本
search_mode	配置检索模式：hybrid / dense
tool_call_id	与 Agent tool_call 对齐
status / invocation_status	工具执行态；成功多为 READY
evidence_status	EVIDENCE_FOUND / NO_EVIDENCE 等
retrieval_evidence_status	更细状态，如 supported
attempts[]	每次检索尝试列表
attempts[].name	如 FILTERED_VECTOR / UNFILTERED_VECTOR
attempts[].usable	该次结果是否被采用
attempts[].duration_ms	该次检索耗时
attempts[].top_similarity	质量闸门用相似度（非 RRF 主分本身）
attempts[].candidate_count	原始候选数
selected_attempt	最终采用的 attempt
l0_hints.domains	L0 域提示
l0_hints.matched_keywords	L0 命中词
sources	返回块来源（可重复 doc）
evidence_keys	稳定键，如 docId#chunk-n
evidence_candidate_count	候选规模
evidence_block_count / returned_count	交给 Agent 的块数
context_used_chars / context_char_budget	证据字符占用与预算
agent_result_bytes	投影后 JSON 字节数
completeness_hint	完整度提示文案
truncated	是否因预算截断

3.4 tool_invocation 表字段

字段	含义	样本
tool_name	工具名	lookup_knowledge
success	是否执行完成（无证据也可为 true）	1
duration_ms	工具总耗时	1243
retrieval_layer	主命中层，如 L1	L1
l0_match_count / l1_match_count	L0 命中 / L1 块数	3 / 5
relevance_level	PRECISE / REFERENCE / RELATED / 空	PRECISE
input_params	入参审计	tool_call_id + request_bytes + 可选 step_id + 安全请求字段（如 query 预览，≤160 字符；敏感键过滤）
output_preview	短摘要	level=PRECISE ...
output_length	投影结果长度	3212
step_id	关联 agent_step.id	由 AgentStepAuditTracker 在 Agent beforeModel 绑入；工具执行时写入
retrieval_details	上表富 JSON	rag_lookup_v1

3.4.1 step_id + query 审计如何写入（2026-07-28 改造）

sequenceDiagram
    participant Hook as HarnessAgentAuditHook
    participant DB as agent_step
    participant Tr as AgentStepAuditTracker
    participant TB as ToolBoundary
    participant Sink as JpaToolInvocationAuditSink
    participant TI as tool_invocation

    Hook->>DB: beforeModel 落库 step 行
    DB-->>Hook: step.id
    Hook->>Tr: bind(runId, stepId)
    Note over Hook,TB: afterModel 发出 tool_call 后仍保持 bind<br/>直到下一轮 beforeModel 或 run finish clear
    TB->>Tr: currentStepId(runId)
    Tr-->>TB: stepId
    TB->>Sink: AuditEvent(stepId, requestJson)
    Sink->>TI: step_id 列 + input_params 安全展开

组件	职责
AgentStepAuditTracker	run 级当前 agent_step.id 绑定表
HarnessAgentAuditHook	beforeModel 落 step 后 bind
ToolBoundary.auditSafely	读 tracker，把 stepId + requestJson 放进 audit event
JpaToolInvocationAuditSink	写 step_id 列；input_params 展开安全字段
TraceAuditEvents.toolInvocation	timeline details 带 step_id（有则写）
JpaChatRunStore.finish	clear(runId) 防泄漏

input_params 安全规则（实现于 sink，非原样 dump request）：

• 始终：tool_call_id、request_bytes；有则：step_id
• 从 request JSON 顶层提取 string / number / boolean / 纯字符串数组
• 文本最多 160 字符；超长附加 *_truncated、*_chars
• 键名含 password / token / secret / apikey / authorization 等 → 不落库
• 嵌套 object / 混合数组不整段写入

现行 input_params 形态示例（逻辑结构；含 PRECISE 时另有 retrieval_details 富字段）：

{
  "query": "MySQL connection pool exhausted HikariCP diagnosis",
  "step_id": 123,
  "tool_call_id": "call_…",
  "request_bytes": 62
}

关联	含义
agent_step.id	发出该 tool_call 的 Agent 轮次
tool_invocation.step_id	指向上述 step
input_params.query	工具检索 query（安全截断后）

live 数字级验收与 FALLBACK 对照见 → 审计补丁 E2E 专项。

3.5 分数语义（避免误读）

flowchart LR
    subgraph hybrid["hybrid 主路径"]
        RRF[RRF 融合分] --> ORD[返回序 = 权威排序]
        RRF --> SL[scoreLabel = hybrid]
    end
    subgraph gate["质量闸门侧"]
        L2[dense L2 / similarity] --> QS[qualityScore / top_similarity]
        QS --> RL[relevance_level]
    end
    ORD --> AGENT[Agent 所见证据序]
    RL --> AGENT

• 排序权威：hybrid 下是 RRF 返回序，不是 L2 重排。
• scoreLabel=hybrid：主分来自融合，不要当「越大越像 cosine」。
• top_similarity / denseDistance：服务后处理绝对质量闸门（如 L0 过滤过严时的 fallback），不覆盖 hybrid 主序。

SSE：保持 DIAGNOSIS_RUNNING。

---

阶段 4 — AGENT round 2（写诊断草稿）

职责：把工具结果收成结构化报告候选；遵守「不编造、证据不足写 limitations」。

发送：1 次 Diagnosis Agent

step_index	1
duration	8196 ms
tokens	in 3580 / out 1123 / total 4703
roles	user + assistant + tool
输出	has_text=true，tool_names=[]（不再调工具）

产出：内部 Draft（尚未对用户最终生效）→ 进入门控。

flowchart TB
    M1[user 原问题] --> CTX
    M2[assistant tool_call] --> CTX
    M3[tool RagToolResult] --> CTX
    CTX[消息上下文] --> A2[Agent LLM r2]
    A2 --> DRAFT[报告草稿 JSON]
    DRAFT --> EG[Evidence Guard]

为何 input 比 r1 大：上下文多了 tool 结果（证据约 3k 字符级）。

---

阶段 5 — EVIDENCE GUARD（证据结构门控）

职责：规则/结构校验——引用是否指向真实 tool_call、有无虚构来源等。通常不再调大模型。

样本：

EVIDENCE_GUARD_INITIAL = PASSED
violation_count = 0
referenced_tool_call_ids = [call_00_91fK...]
verified_analysis_count = 3
verified_source_count = 4

字段	含义
violation_count	违规条数
violations	违规明细
referenced_tool_call_ids	报告点名的工具调用
verified_analysis_count	通过核验的分析条数
verified_source_count	通过核验的来源数
invalid_tool_reference_count	非法工具引用数

flowchart LR
    DRAFT[报告草稿] --> EG[Evidence Guard]
    TI[真实 tool_call 账本] --> EG
    EG -->|PASSED| SG[Semantic Guard]
    EG -->|FAIL| FB[修复 / FALLBACK]

---

阶段 6 — SEMANTIC GUARD（语义门控）

职责：再用 1 次模型判断「结论是否被证据支撑」，抑制夸大与臆测根因。

样本 tokens：in 4141 / out 829 / total 4970（整次 run 最大单段）

产出：SEMANTIC_GUARD_DECISION，verdict=SUPPORTED

verdict 倾向	后果
SUPPORTED	可走向 SUCCESS 发布
不支持 / 证据不足	FALLBACK 或安全改写

SSE：status: SAFETY_VALIDATING。

flowchart TB
    DRAFT[草稿] --> SG[Semantic Guard LLM]
    EV[证据摘要 / 引用] --> SG
    SG --> V{verdict}
    V -->|SUPPORTED| OK[可 RELEASE SUCCESS]
    V -->|其它| NO[FALLBACK / 再约束]
    SG --> TOK[MODEL_TOKEN_USAGE 入账]

成本观察：本样本中 Semantic Guard ≈ 总 token 的 37%。是否压缩留给后续评估。

---

阶段 7 — RELEASE（发布）

职责：终态裁决 + 选择对外 content 形态。

样本：

• RELEASE_DECISION → release_outcome=SUCCESS
• SSE content_type=DIAGNOSIS_REPORT
• SSE done.outcome=SUCCESS

7.1 成功报告结构

flowchart TB
    CT[content_type = DIAGNOSIS_REPORT] --> P[payload]
    P --> R[report]
    P --> REF[references]
    R --> C[conclusion]
    R --> A[analysis]
    R --> AP[action_plan]
    R --> RC[recommendations]
    R --> L[limitations]
    C --> CTXT[text]
    C --> IDS[based_on_analysis_ids]
    L --> SC[scope]
    L --> MI[missing_info]

字段	含义	样本要点
content_type	对外内容类型	DIAGNOSIS_REPORT（对比 SAFE_FALLBACK）
conclusion.text	结论文本	有 runbook、无 live 数据不能定根因
conclusion.based_on_analysis_ids	结论依据哪些分析	A-001..003
analysis[]	分条事实/推理	3 条 NORMAL
action_plan / recommendations	动作与建议	约束为空 []
limitations.scope	证据范围声明	仅 lookup_knowledge + 源名
limitations.missing_info	缺口	未查生产指标/日志
references[]	溯源列表	全为 source_type=RAG
references[].source	源标识	docId / upload id
references[].scope	查询范围描述	本次 query 摘要
outcome	发布结局	SUCCESS

7.2 SUCCESS vs FALLBACK（概念）

flowchart LR
    DRAFT[草稿] --> GATES{Evidence + Semantic}
    GATES -->|通过| S[SUCCESS<br/>DIAGNOSIS_REPORT]
    GATES -->|证据不足/不支持| F[FALLBACK<br/>SAFE_FALLBACK]
    F --> IE[常见 type:<br/>INSUFFICIENT_EVIDENCE]

---

阶段 8 — 收尾、Token 对账与 Trace 回放

职责：汇总预算与 usage；固化 run；供 Trace API。

样本 RUN_FINISHED：

model_call_count = 4
run_input_tokens = 10598
run_output_tokens = 2638
run_total_tokens = 13236
tokens_reconciled = true
usage_unavailable_count = 0
duration ≈ 25264 ms

8.1 Token 分解

pie title 样本 run 总 Token 13236
    "INTENT_ROUTER 906" : 906
    "AGENT r1 2657" : 2657
    "AGENT r2 4703" : 4703
    "SEMANTIC_GUARD 4970" : 4970

调用	component	in	out	total	角色
1	INTENT_ROUTER	323	583	906	路由
2	DIAGNOSIS_AGENT r1	2554	103	2657	规划 + tool_call
3	DIAGNOSIS_AGENT r2	3580	1123	4703	写报告
4	SEMANTIC_GUARD	4141	829	4970	语义放行
Σ		10598	2638	13236

对账关系：

sum(MODEL_TOKEN_USAGE.total_tokens) = 13236
= diagnosis_run.total_token_count
= RUN_FINISHED.run_total_tokens
= audited_total_tokens
tokens_reconciled = true

易混点：

指标	含什么	样本
agent_step.tokenCount 之和	仅诊断 Agent 两轮	2657+4703=7360
run.total_token_count	Router+Agent+Guard 全部	13236

8.2 耗时粗拆

gantt
    title 样本墙钟粗拆（示意，非精确并行）
    dateFormat X
    axisFormat %s
    section 路由
    Intent Router           :0, 2
    section Agent/Tool
    Agent r1                :2, 4
    lookup_knowledge hybrid :4, 5
    Agent r2 写报告         :5, 14
    section 门控发布
    Evidence + Semantic     :14, 22
    Release + 落库          :22, 25

RAG 热路径工具段约 1.2s；主体时间在 LLM（尤其 r2 与 Semantic Guard）。

---

6. 数据落库与 Trace 结构

6.1 表关系

erDiagram
    CHAT_SESSION ||--o{ DIAGNOSIS_RUN : contains
    DIAGNOSIS_RUN ||--o{ AGENT_STEP : has
    DIAGNOSIS_RUN ||--o{ TOOL_INVOCATION : has
    DIAGNOSIS_RUN ||--o{ DIAGNOSIS_TRACE_EVENT : timeline
    DIAGNOSIS_RUN ||--o{ AGENT_REASONING_AUDIT : optional
    AGENT_STEP ||--o| TOOL_INVOCATION : "step_id 已由 AgentStepAuditTracker 绑定"

    DIAGNOSIS_RUN {
        string run_id PK
        string session_id
        string status
        string intent
        string release_outcome
        int total_duration_ms
        int total_token_count
        int step_count
        int tool_call_count
        text query
        longtext answer
    }

    AGENT_STEP {
        long id PK
        string run_id
        int step_index
        string agent_name
        int token_count
        int duration_ms
        json model_input
        json model_output
    }

    TOOL_INVOCATION {
        long id PK
        string run_id
        long step_id
        string tool_name
        json input_params
        json retrieval_details
        string relevance_level
        int duration_ms
        boolean success
    }

    DIAGNOSIS_TRACE_EVENT {
        long id PK
        string run_id
        int sequence_no
        string phase
        string event_type
        string status
        json details
    }

6.2 Trace API 响应骨架

flowchart TB
    TR[DiagnosisTraceResponse] --> RUN[run]
    TR --> STEPS[steps]
    TR --> TOOLS[toolInvocations]
    TR --> TL[timeline]
    TR --> SUM[summary]
    RUN --> R1[status / intent / tokens / answer]
    STEPS --> S1[每轮 Agent 摘要]
    TOOLS --> T1[RAG 富字段]
    TL --> E1[15 条有序事件]
    SUM --> C1[persisted vs returned 计数]

样本 summary：

计数	persisted	returned
steps	2	2
tools	1	1
timeline events	15	15

6.3 样本 timeline 全表（15 事件）

seq	phase	event_type	要点
1	RUN	RUN_STARTED	开跑
2	ROUTING	MODEL_TOKEN_USAGE	Router 906
3	ROUTING	ROUTING_ATTEMPT
4	ROUTING	ROUTING_DECISION	intent=DIAGNOSIS
5	AGENT	MODEL_TOKEN_USAGE	Agent r1 2657
6	AGENT	AGENT_MODEL_STEP	step0 tool_call
7	TOOL	TOOL_INVOCATION	lookup READY / EVIDENCE_FOUND
8	AGENT	MODEL_TOKEN_USAGE	Agent r2 4703
9	AGENT	AGENT_MODEL_STEP	step1 写报告
10	EVIDENCE	EVIDENCE_GUARD_INITIAL	PASSED
11	SEMANTIC	MODEL_TOKEN_USAGE	Guard 4970
12	SEMANTIC	SEMANTIC_GUARD_ATTEMPT
13	SEMANTIC	SEMANTIC_GUARD_DECISION	SUPPORTED
14	RELEASE	RELEASE_DECISION	SUCCESS
15	RUN	RUN_FINISHED	13236 reconciled

flowchart TB
    E1[1 RUN_STARTED] --> E2[2-4 ROUTING]
    E2 --> E3[5-6 AGENT r1]
    E3 --> E4[7 TOOL RAG]
    E4 --> E5[8-9 AGENT r2]
    E5 --> E6[10 EVIDENCE PASSED]
    E6 --> E7[11-13 SEMANTIC SUPPORTED]
    E7 --> E8[14 RELEASE SUCCESS]
    E8 --> E9[15 RUN_FINISHED]

---

7. 「边界」图：Agent 可见 vs 审计可见

这是理解 RAG 与 Trace 的关键。

flowchart TB
    subgraph internal["工具内部（完整）"]
        LR[LookupResult<br/>retrievalTrace / attempts / blocks 全文]
    end

    subgraph agent_view["Agent 可见（投影后）"]
        RT[RagToolResult<br/>evidence 块 + 可选 relevance_level<br/>无完整 internal trace]
    end

    subgraph audit_view["审计 / Trace 可见"]
        TI[tool_invocation.retrieval_details<br/>rag_lookup_v1 富字段]
        EV[timeline TOOL_INVOCATION 摘要]
    end

    LK[LookupKnowledgeTool] --> LR
    LR --> PROJ[RagResultProjector]
    PROJ --> RT
    LR --> ENR[RagLookupAuditEnricher]
    ENR --> TI
    ENR --> EV
    RT --> AGENT[Diagnosis Agent r2]
    TI --> API[Trace API]

视角	目的	不该指望它
Agent 投影	控制上下文体积、稳定契约	完整排障 trace
tool_invocation	复盘检索质量与模式	替代评测集
timeline	阶段时序与 token	存证据全文

---

8. 责任总表（一张表串起来）

阶段	组件	发送什么	产出什么	明确不负责
0 接入	ChatController	SSE 壳	session/run	诊断内容
1 路由	Intent Router	1×LLM	intent	检索/结论
2 规划	Diagnosis Agent r1	1×LLM	tool_call	最终报告
3 检索	lookup_knowledge	Embed+Milvus	证据+audit	写结论
4 撰写	Diagnosis Agent r2	1×LLM	报告草稿	放行裁决
5 证据门	Evidence Guard	规则	PASS/违规	语义是否夸大
6 语义门	Semantic Guard	1×LLM	SUPPORTED 等	再检索
7 发布	Release	—	SUCCESS/FALLBACK 内容	—
8 审计	DB + Trace	—	可回放账本	—

---

9. 本样本结论与剩余缺口

9.1 本 SUCCESS run 已对齐

能力	状态	证据
hybrid RAG 命中	通过	search_mode=hybrid，PRECISE，EVIDENCE_FOUND
单次 lookup 约束	通过	tool_call_count=1
门控放行	通过	Evidence PASSED → Semantic SUPPORTED → SUCCESS
Token 对账	通过	13236，tokens_reconciled=true
Trace 闭环	通过	2 steps / 1 tool / 15 events，persisted=returned
SUCCESS 报告	通过	DIAGNOSIS_REPORT，action/rec 为空，refs=RAG
现行审计能力	已合入代码	见 §3.4.1；专项 live 数字见 审计补丁 E2E

9.2 仍未关闭的缺口

#	问题	含义	优先级
1	检索 top 混入弱相关源（如 payment-service-latency）	hybrid 生效但纯度一般；报告可克制，sources 仍可能挂噪声	后续过滤/重排
2	Semantic Guard 约占 5k tokens	正确但贵	后评估是否可降
3	偶发 hybrid 空结果 → FALLBACK	环境/Milvus 抖动	见 审计验收页 §4

缺口 1 示意：

flowchart TB
    Q[Query: HikariCP pool] --> H[Hybrid top]
    H --> G1[连接池 runbook 强相关]
    H --> N1[支付延迟等弱相关]
    G1 --> REPORT[SUCCESS 报告正文]
    N1 --> REF[references 可能仍出现]

---

10. 如何自己复盘下一次 run

flowchart LR
    A[拿 session_id + run_id] --> B[拉 Trace API]
    B --> C[看 timeline 阶段是否闭环]
    C --> D[看 toolInvocations.retrieval_details]
    D --> E[核对 search_mode / relevance / attempts]
    E --> F[加总 MODEL_TOKEN_USAGE]
    F --> G[对比 run.total_token_count]
    G --> H[读 answer 与 references]
    H --> I[对照 logs/application.log]

建议核对清单：

1. release_outcome 与 SSE done.outcome 一致
2. tool_call_count 与真实工具次数一致
3. RAG：search_mode、selected_attempt、evidence_status
4. Token：tokens_reconciled=true 且分项和 = 总额
5. 门控：Evidence 与 Semantic 事件状态
6. 报告：limitations 是否覆盖未观测范围
7. 审计：tool_invocation.step_id 非空且等于对应 agent_step.id
8. 审计：input_params 含 query（或其它安全标量）与 tool_call_id

日志关键字：

lookup_knowledge
Hybrid dense+BM25 search
relevanceLevel=
MODEL_TOKEN_USAGE  (在 Trace，不在普通业务日志全文)

MySQL 入口（只读脚本）：

python scripts/query_mysql.py "SELECT run_id, status, release_outcome, total_token_count, total_duration_ms, step_count, tool_call_count FROM diagnosis_run WHERE run_id = '<runId>'"

python scripts/query_mysql.py "SELECT id, step_id, tool_name, relevance_level, CAST(input_params AS CHAR) AS inputp, LEFT(CAST(retrieval_details AS CHAR), 400) AS details FROM tool_invocation WHERE run_id = '<runId>' ORDER BY id"

python scripts/query_mysql.py "SELECT id, step_index, agent_name, has_tool_call, token_count FROM agent_step WHERE run_id = '<runId>' ORDER BY step_index, id"

---

11. 一页故事版

1. 用户用 Chat 提「只用知识库、只调一次 lookup」的诊断题。
2. Router（~0.9k tokens）判成 DIAGNOSIS。
3. Agent 第 1 轮（~2.7k tokens）决定调用 lookup_knowledge；落 agent_step 并 bind step_id。
4. Hybrid RAG（~1.2s）命中 PRECISE；tool_invocation 写 step_id + query，进 Trace。
5. Agent 第 2 轮（~4.7k tokens）只依据证据写报告。
6. Evidence Guard 校验引用。
7. Semantic Guard（~5.0k tokens）判 SUPPORTED。
8. Release → DIAGNOSIS_REPORT + SUCCESS；13236 tokens / ~25s，15 步 timeline；run 结束 clear 绑定。

---

12. 修订记录

日期	说明
2026-07-28	初版：SUCCESS 全流程、字段词典与多图
2026-07-28	审计补丁代码与 §3.4.1 能力说明
2026-07-28	文档迁入 docs/；INDEX 挂接
2026-07-29	迁入 mvp/engineering/diagnosis/，与 RAG 工程纪要集中到 mvp
2026-07-28	拆分：FALLBACK 审计验收样本迁至 RAG审计补丁-stepid-query-E2E验收.md；本文只保留 SUCCESS 主线