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

工具调用表：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)	是	所属会话目录 ID，保留用于粗粒度过滤和兼容
run_id	VARCHAR(64)	否	所属 diagnosis_run.run_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_invocation_run_id	run_id, id	Trace、Verifier、评测按运行查询工具调用
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

retrieval_details 是扩展字段。当前重要结构包括：

{
  "evidence_status": "supported",
  "evidence_refs": [
    {
      "raw_path": "$.logs[0]",
      "text": "工具返回中可核对的最小证据文本"
    }
  ]
}

注意点

• Verifier 不应只信任 RAG 证据；所有工具只要能提供 evidence_refs，都应该进入可校验证据链。
• output_preview 只适合展示和排查，不应被当成完整原始输出。
• $.no_evidence 只代表“本次工具未命中证据”，不能推导为“故障不存在”。