# RAG 审计补丁 E2E：`step_id` + query（含业务 FALLBACK 样本）

**日期**：2026-07-28  
**状态**：审计字段 live 验收记录  
**关联主文档**：[一次诊断到底发生了什么（SUCCESS 全流程）](../diagnosis/一次诊断全流程-E2E导读.md)

> 主文档只保留 **SUCCESS 完整诊断** 与 **现行审计能力说明**。  
> 本页单独记录：改造后的一次 live 验收——**审计字段 PASS**，业务因 Milvus 空结果走了 **FALLBACK**。

---

## 1. 样本身份

| 项 | 值 |
|----|----|
| `session_id` | `e2e-audit-20260728171858` |
| `run_id` | `0be605f6-e036-40d3-b364-11b73672241f` |
| 入口 | `POST /api/chat`（与 SUCCESS 样例同构的 RAG-only 约束题） |
| 冷启动 | 含 `AgentStepAuditTracker` 等补丁后的 `mvn spring-boot:run` |
| 业务结局 | `release_outcome=FALLBACK`，`content_type=SAFE_FALLBACK` |
| 工具 | 1× `lookup_knowledge` |

本地产物（若仍在）：`target/e2e-audit-sse.txt`、`target/e2e-audit-session.txt`、`target/e2e-audit-run.txt`。

---

## 2. 验收目标 vs 非目标

| 目标 | 是否本页重点 |
|------|----------------|
| `tool_invocation.step_id` = 发出 tool_call 的 `agent_step.id` | **是** |
| `input_params` 含安全 `query` 预览 | **是** |
| Trace / timeline 带回 `step_id` | **是** |
| 业务必须 SUCCESS | **否**（本 run 为 FALLBACK，归因环境） |

---

## 3. 审计结果：PASS

### 3.1 `agent_step`

| id | step_index | has_tool_call | 说明 |
|----|------------|---------------|------|
| **962** | 0 | 1 | 发出 `lookup_knowledge` |
| 963 | 1 | 0 | 无证据后的收尾轮 |

### 3.2 `tool_invocation`（id=860）

| 字段 | 值 |
|------|-----|
| `step_id` | **962**（= step0） |
| `tool_name` | `lookup_knowledge` |
| `success` | 1（工具跑完；无证据也算执行成功） |
| `search_mode` | hybrid |
| `evidence_status` | `NO_EVIDENCE` |
| `candidate_count` | 0 |
| `relevance_level` | null |

**`input_params` 实值：**

```json
{
  "query": "MySQL connection pool exhausted HikariCP diagnosis",
  "step_id": 962,
  "tool_call_id": "call_00_LireJzbiFEsbZ9ZVvgYp8330",
  "request_bytes": 62
}
```

### 3.3 Trace API

- `toolInvocations[0].stepId = 962`
- `inputParams.query` 有值  
- timeline `TOOL_INVOCATION.details.step_id = 962`

### 3.4 对照表

| 检查项 | 预期 | 实际 | 判定 |
|--------|------|------|------|
| `tool_invocation.step_id` | = agent_step.id | 962 | **PASS** |
| `input_params.query` | 有预览 | 有 | **PASS** |
| `input_params.step_id` | 与列一致 | 962 | **PASS** |
| Trace `stepId` | 非空 | 962 | **PASS** |
| timeline `step_id` | 非空 | 962 | **PASS** |
| `search_mode` | hybrid | hybrid | **PASS** |
| 业务 outcome | （非本页 KPI） | FALLBACK | 见 §4 |

```mermaid
flowchart LR
    S0[agent_step 962<br/>r1 tool_call] --> TI[tool_invocation 860<br/>step_id=962]
    TI --> IP[input_params.query]
    TI --> TR[Trace / timeline]
    TI --> RAG[hybrid candidate_count=0]
    RAG --> FB[FALLBACK<br/>NO_EVIDENCE]
```

---

## 4. 业务 FALLBACK 原因（与审计无关）

| 现象 | 说明 |
|------|------|
| 日志 | `found=false`，`evidenceBlocks=0` |
| audit | `attempts[].usable=false`，`candidate_count=0` |
| warm 检索 | 同期 `GET /api/search/similar` 亦失败 |
| 日志噪音 | Milvus channel 未正确 shutdown 等提示（环境/客户端生命周期） |

**结论**：hybrid **路径进了**，但当次 **0 候选** → 无证据可写报告 → `SAFE_FALLBACK` / `INSUFFICIENT_EVIDENCE`。  
这不否定 `step_id` / `query` 落库；完整 SUCCESS 业务故事见主文档。

```mermaid
flowchart TB
    Q[同一 RAG-only 题] --> LK[lookup_knowledge]
    LK --> AUD[审计: step_id + query PASS]
    LK --> HIT{有候选?}
    HIT -->|SUCCESS 主文档 run| OK[PRECISE → DIAGNOSIS_REPORT]
    HIT -->|本页 run| NO[0 候选 → FALLBACK]
```

---

## 5. 实现索引（补丁代码）

| 组件 | 职责 |
|------|------|
| `AgentStepAuditTracker` | run 级 bind/current/clear `agent_step.id` |
| `HarnessAgentAuditHook` | `beforeModel` 落 step 后 `bind` |
| `ToolBoundary.auditSafely` | 读 tracker，带上 `stepId` + `requestJson` |
| `JpaToolInvocationAuditSink` | 写 `step_id` 列；安全展开 `input_params` |
| `TraceAuditEvents.toolInvocation` | timeline details 的 `step_id` |
| `JpaChatRunStore.finish` | `clear(runId)` |

**`input_params` 安全规则摘要**：

- 始终：`tool_call_id`、`request_bytes`；有则：`step_id`
- 顶层 string/number/boolean/纯字符串数组；文本 ≤160 字符  
- 键名含 password/token/secret/apikey 等 → 不落库  

更完整的字段词典与 SUCCESS 阶段拆解见主文档 §3.4 / §3.4.1。

---

## 6. 复盘 SQL

```bash
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), 500) AS details FROM tool_invocation WHERE run_id = '0be605f6-e036-40d3-b364-11b73672241f'"

python scripts/query_mysql.py "SELECT id, step_index, agent_name, has_tool_call, token_count FROM agent_step WHERE run_id = '0be605f6-e036-40d3-b364-11b73672241f' ORDER BY step_index"

python scripts/query_mysql.py "SELECT run_id, status, release_outcome, tool_call_count, total_token_count FROM diagnosis_run WHERE run_id = '0be605f6-e036-40d3-b364-11b73672241f'"
```

```http
GET /api/diagnosis/e2e-audit-20260728171858/trace?runId=0be605f6-e036-40d3-b364-11b73672241f
```

---

## 7. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-07-28 | 从主 walkthrough 拆出：专门记录 audit 验收 run（FALLBACK 业务 + step_id/query PASS） |