# Agent 推理审计表：agent_reasoning_audit

**状态**：当前独立敏感审计表；治理待 ISS-015 收敛
**来源**：`V015__create_agent_reasoning_audit.sql`、`AgentReasoningAudit`

## 定位

`agent_reasoning_audit` 保存模型 Provider 在 Agent 步骤 metadata 中实际返回的 reasoning 内容。它与普通 Trace、AgentStep、Evidence Snapshot 和业务发布结果物理分离，不能作为事实证据或诊断结论来源。

Provider 未返回 reasoning 时仍写入 unavailable 记录，防止把“没有返回”误判为“审计链路漏写”。系统不得从最终回答、Tool 调用或其他字段生成伪 reasoning。

## 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | BIGINT | 是 | 自增主键 |
| `session_id` | VARCHAR(64) | 是 | 所属 Chat Session ID |
| `run_id` | VARCHAR(64) | 是 | 所属 Diagnosis Run ID |
| `step_index` | INT | 是 | Agent 模型步骤序号 |
| `agent_name` | VARCHAR(64) | 是 | Agent 身份，当前为 `diagnosis_agent` |
| `reasoning_available` | BOOLEAN | 是 | Provider 是否实际返回非空 reasoning |
| `reasoning_content` | LONGTEXT | 否 | Provider reasoning 原文；Hook 当前最多保留 32000 个字符 |
| `content_bytes` | INT | 是 | 截断后 reasoning 的 UTF-8 字节数；unavailable 时为 0 |
| `created_at` | DATETIME | 是 | 创建时间，默认当前时间 |

## 索引

| 索引 | 字段 | 用途 |
|---|---|---|
| `idx_reasoning_run_step` | `run_id, step_index` | exact Run 下按模型步骤查询 |
| `idx_reasoning_session_created` | `session_id, created_at` | Session 范围审计排查 |

## 关系

- `run_id` 逻辑关联 `diagnosis_run.run_id`。
- `session_id` 逻辑关联 `chat_session.session_id`。
- 通过 `session_id + run_id + step_index` 与 `agent_step` 逻辑对应，不建立数据库外键。

## 写入规则

- Provider 返回非空 reasoning：`reasoning_available=true`，保存截断后的原文及实际 UTF-8 字节数。
- Provider 未返回 reasoning：`reasoning_available=false`，`reasoning_content=NULL`，`content_bytes=0`。
- `agent_step.thought` 继续保持为空；普通 Trace 仅保留 availability/bytes metadata。
- Reasoning 不进入 SSE、PreviousTurn、Evidence Snapshot、发布结果或应用日志。

## 查询与治理

当前独立接口为 `GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}`。`runId` 必填，服务端校验其属于 path `sessionId`，并按 `step_index` 返回记录。

分表和归属校验已经实现，但不能等同于完整安全治理。身份认证、角色授权、保留/删除期限、静态与传输加密以及真实 Provider/V015 验证仍由 ISS-015 阶段 3 跟踪；治理完成前不应将该接口暴露给普通业务用户。