zhuyongxin
7ae9707a3b
Persist provider reasoning and assistant text separately on agent_reasoning_audit (DeepSeekAssistantMessage path), extract diagnosis_run.conclusion, enrich RAG tool audit (step_id/query/qualityScore), gate empty mysql tools, drop devtools, and align MVP docs after live E2E verification.
52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# 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。
|