SuperBizAgent-java/mvp/tables/Agent步骤表-agent_step.md

Agent 步骤表：agent_step

状态：当前表
来源：V005__create_session_storage.sql、V006__fix_agent_step_json_to_text.sql、AgentStep、HarnessAgentAuditHook

定位

agent_step 记录 Diagnosis Agent 模型步骤的有界审计 metadata。run_id 是执行隔离边界；当前写入不得保存完整 Prompt、完整消息列表、Tool 结果体。

Provider reasoning 与 assistant 正文的完整双字段 在独立表 agent_reasoning_audit；本表只保留步骤级摘要与兼容镜像。

字段

字段	类型	必填	说明
id	BIGINT	是	自增主键
session_id	VARCHAR(64)	是	所属会话目录 ID，保留用于粗粒度过滤和兼容
run_id	VARCHAR(64)	否	所属 diagnosis_run.run_id；新执行应写入
step_index	INT	是	步骤序号，从 0 开始
agent_name	VARCHAR(32)	是	当前 Harness 写入固定为 diagnosis_agent
model_input	TEXT	否	JSON metadata，仅包含 message count 与 roles
model_output	TEXT	否	JSON metadata：has_text、tool_names、reasoning_available、reasoning_bytes、assistant_bytes、content_source
thought	TEXT	否	兼容镜像：优先 Provider reasoning，否则 assistant 正文；完整双字段以 agent_reasoning_audit 为准
has_tool_call	BOOLEAN	否	本步骤是否触发工具调用
duration_ms	INT	否	本步骤耗时
token_count	INT	否	本步骤 Token 消耗
created_at	DATETIME	是	创建时间

索引

索引	字段	用途
idx_session_step	session_id, step_index	历史兼容和粗粒度排查
idx_agent_step_run_step	run_id, step_index	按运行筛选步骤并辅助顺序查询
idx_agent_name	agent_name	按 Agent 类型筛选

关系

• agent_step.run_id 逻辑关联 diagnosis_run.run_id。
• agent_step.session_id 保留为 chat_session.session_id 的冗余关联，便于粗粒度过滤和兼容查询。
• tool_invocation.step_id 应关联当前模型步骤的 agent_step.id（由 AgentStepAuditTracker 在 beforeModel 绑定）。
• agent_reasoning_audit 通过相同的 session_id + run_id + step_index 逻辑定位模型步骤，不建立数据库外键。

注意点

• 前端展示步骤时应使用 Trace API 返回顺序；服务端会在同一 run_id 范围内整理步骤顺序。
• 新 Trace 和验收读路径必须按 exact run_id 取数，避免同一 sessionId 多次运行混入。
• 当前 Run 若出现 diagnosis_agent 之外的新写入，视为审计边界违规。
• model_output 不得保存 reasoning/assistant 原文；只允许有界 metadata。
• thought 非空 不再视为违规：它是受限镜像，便于旧读路径一眼看到“本步在想什么/说什么”；敏感完整审计仍走 /trace/reasoning。
• 需要同时查看 thinking 与 assistant 正文时，必须查 agent_reasoning_audit 或 reasoning Trace API。