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 是 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 结构为：

{
  "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 结果。