# 工具调用表：tool_invocation

**状态**：当前表  
**来源**：`V005__create_session_storage.sql`、`V010__add_relevance_level_to_tool_invocation.sql`、`ToolInvocation`

## 定位

`tool_invocation` 是 Harness ToolBoundary 的长期 metadata-only 审计表。它记录 exact Run/Tool identity、状态、稳定错误码、耗时与字节数；完整请求、raw response 和 Agent projection 只短期存在于 Redis canonical invocation，不写入本表。

## 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | BIGINT | 是 | 自增主键 |
| `session_id` | VARCHAR(64) | 是 | 所属会话目录 ID，保留用于粗粒度过滤和兼容 |
| `run_id` | VARCHAR(64) | 否 | 所属 `diagnosis_run.run_id`；新执行应写入 |
| `step_id` | BIGINT | 否 | 可关联 `agent_step.id` |
| `tool_name` | VARCHAR(64) | 是 | ACI Tool 名：`lookup_knowledge`、`query_logs` 或 `query_mysql` |
| `input_params` | JSON | 是 | 仅 `tool_call_id` 与 `request_bytes` metadata，不含 Tool 参数正文 |
| `output_preview` | TEXT | 否 | 仅 invocation/evidence status metadata |
| `output_length` | INT | 否 | Agent projection UTF-8 字节数 |
| `retrieval_layer` | VARCHAR(8) | 否 | 当前 Harness 审计固定为 `HARNESS` |
| `l0_match_count` | INT | 否 | L0 命中数量 |
| `l1_match_count` | INT | 否 | L1 命中数量 |
| `is_truncated` | BOOLEAN | 否 | 输出是否被截断 |
| `relevance_level` | VARCHAR(20) | 否 | 当前 Harness 复用该字段保存 evidence status |
| `dedup_reason` | VARCHAR(32) | 否 | 历史字段；当前 Harness 不写入 |
| `retrieval_details` | JSON | 否 | `tool_call_id`、status、evidence status、result bytes 与可选稳定错误码 |
| `duration_ms` | INT | 否 | 工具耗时 |
| `success` | BOOLEAN | 否 | 工具是否成功 |
| `error_message` | TEXT | 否 | 仅稳定错误码，不保存内部异常或 vendor message |
| `created_at` | DATETIME | 是 | 创建时间 |

## 索引

| 索引 | 字段 | 用途 |
|---|---|---|
| `idx_session_id` | `session_id` | 历史兼容和粗粒度排查 |
| `idx_tool_invocation_run_id` | `run_id, id` | Trace 与验收按 exact Run 查询 Tool 审计 |
| `idx_tool_name` | `tool_name` | 按工具类型排查 |
| `idx_retrieval_layer` | `retrieval_layer` | 观察 RAG L0/L1 行为 |

## 关系

- `tool_invocation.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `tool_invocation.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。
- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前不强制。

## 关键 JSON

当前 Harness 写入的 `retrieval_details` 结构为：

```json
{
  "tool_call_id": "framework-call-id",
  "status": "READY",
  "evidence_status": "EVIDENCE_FOUND",
  "agent_result_bytes": 512
}
```

## 注意点

- 本表不是完整证据真理源，EvidenceGuard 只读取当前 Run 的 Redis canonical invocation。
- `input_params`、`output_preview` 和 `retrieval_details` 均不得出现 SQL、日志 query、evidence body、凭据或 raw response。
- audit 写入失败应记录安全 warning，但不能改变已确定的 canonical Tool 结果。