docs(mvp): organize mvp documentation

mvp/tables/工具调用表-tool_invocation.md

@@ -0,0 +1,66 @@
+# 工具调用表：tool_invocation
+
+**状态**：当前表  
+**来源**：`V005__create_session_storage.sql`、`V010__add_relevance_level_to_tool_invocation.sql`、`ToolInvocation`
+
+## 定位
+
+`tool_invocation` 记录 Agent 显式调用工具的事实，包括工具名、入参、输出摘要、检索层级、证据引用和失败信息。它是 Trace、Verifier、评测和人工排查的共同数据源。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 关联 `diagnosis_session.session_id` |
+| `step_id` | BIGINT | 否 | 可关联 `agent_step.id` |
+| `tool_name` | VARCHAR(64) | 是 | 工具名称，例如 `lookup_knowledge`、日志查询、指标查询 |
+| `input_params` | JSON | 是 | 工具入参 |
+| `output_preview` | TEXT | 否 | 工具输出摘要或前缀 |
+| `output_length` | INT | 否 | 工具输出字符数 |
+| `retrieval_layer` | VARCHAR(8) | 否 | 检索层级，例如 `L0`、`L1`、`L0+L1` |
+| `l0_match_count` | INT | 否 | L0 命中数量 |
+| `l1_match_count` | INT | 否 | L1 命中数量 |
+| `is_truncated` | BOOLEAN | 否 | 输出是否被截断 |
+| `relevance_level` | VARCHAR(20) | 否 | 归一化质量等级：`PRECISE`、`HIGHLY_RELEVANT`、`REFERENCE`、`DEDUPED` |
+| `dedup_reason` | VARCHAR(32) | 否 | 去重原因，例如 `doc_retrieved`、`domain_retrieved` |
+| `retrieval_details` | JSON | 否 | 检索明细、证据引用、Gatekeeper 可用导航信息 |
+| `duration_ms` | INT | 否 | 工具耗时 |
+| `success` | BOOLEAN | 否 | 工具是否成功 |
+| `error_message` | TEXT | 否 | 失败原因 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_session_id` | `session_id` | 按会话查询工具调用 |
+| `idx_tool_name` | `tool_name` | 按工具类型排查 |
+| `idx_retrieval_layer` | `retrieval_layer` | 观察 RAG L0/L1 行为 |
+
+## 关系
+
+- `tool_invocation.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前不强制。
+
+## 关键 JSON
+
+`retrieval_details` 是扩展字段。当前重要结构包括：
+
+```json
+{
+  "evidence_status": "supported",
+  "evidence_refs": [
+    {
+      "raw_path": "$.logs[0]",
+      "text": "工具返回中可核对的最小证据文本"
+    }
+  ]
+}
+```
+
+## 注意点
+
+- Verifier 不应只信任 RAG 证据；所有工具只要能提供 `evidence_refs`，都应该进入可校验证据链。
+- `output_preview` 只适合展示和排查，不应被当成完整原始输出。
+- `$.no_evidence` 只代表“本次工具未命中证据”，不能推导为“故障不存在”。