# 诊断 Trace 事件表：diagnosis_trace_event

**状态**：当前统一 Trace Timeline
**来源**：`V014__create_diagnosis_trace_event.sql`、`DiagnosisTraceEvent`

## 定位

`diagnosis_trace_event` 是按 Run 追加的统一生命周期事件表。它记录诊断执行经过哪些阶段、每个阶段的稳定事件类型和结果，使普通 Trace 不再依赖从多个业务表推测完整时序。

该表只保存有界安全 metadata，不保存 Prompt、Thought、DiagnosisDraft 正文或 raw Tool payload。事件写入失败可观测，但不改变业务执行结果。

## 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | BIGINT | 是 | 自增主键；同一 `sequence_no` 下作为稳定次序补充 |
| `session_id` | VARCHAR(64) | 是 | 所属 Chat Session ID |
| `run_id` | VARCHAR(64) | 是 | 所属 Diagnosis Run ID |
| `sequence_no` | INT | 是 | 同一 Run 内递增事件序号 |
| `phase` | VARCHAR(32) | 是 | `RUN`、`ROUTING`、`AGENT`、`TOOL`、`EVIDENCE`、`SEMANTIC` 或 `RELEASE` |
| `event_type` | VARCHAR(48) | 是 | 稳定事件类型，如 `RUN_STARTED`、`AGENT_MODEL_STEP`、`RELEASE_DECISION` |
| `status` | VARCHAR(32) | 是 | 稳定事件结果，如 `SUCCEEDED`、`FAILED`、`PASSED`、`REJECTED`、`FALLBACK` |
| `attempt_no` | INT | 否 | Retry 或模型尝试序号；不适用时为空 |
| `duration_ms` | INT | 否 | 事件耗时；无法计算时为空 |
| `details` | JSON | 是 | 有界安全 metadata；不得包含敏感正文和原始载荷 |
| `created_at` | DATETIME | 是 | 创建时间，默认当前时间 |

## 索引

| 索引 | 字段 | 用途 |
|---|---|---|
| `idx_trace_event_run_sequence` | `run_id, sequence_no, id` | exact Run Timeline 顺序查询 |
| `idx_trace_event_session_created` | `session_id, created_at, id` | Session 范围历史排查 |
| `idx_trace_event_phase` | `phase, event_type` | 按生命周期阶段和事件类型统计 |

## 关系

- `run_id` 逻辑关联 `diagnosis_run.run_id`。
- `session_id` 逻辑关联 `chat_session.session_id`，同时用于 Run 所有权排查。
- 不建立数据库外键；应用必须使用 exact `sessionId + runId` 做归属校验。

## 事件范围

当前事件类型覆盖 Run 开始/结束、路由尝试/决策、Agent 模型步骤、Tool 调用、Evidence 初检/Repair/复检、Semantic 尝试/决策和 Release 决策。

普通 Trace API 按 `sequence_no ASC, id ASC` 返回 Timeline。Agent 模型事件最多包含 reasoning availability 和字节数，不包含 reasoning 原文。

## 注意点

- 该表是追加式审计时间线，不是 `diagnosis_run` 终态的替代品。
- `details` 必须保持结构化、有界和非敏感；禁止将其他表的正文复制进来。
- 不应仅依赖 `created_at` 排序，同一 Run 必须使用 `sequence_no, id`。