docs(mvp): align architecture and audit table design

2026-07-23 20:16:29 +08:00
parent 49180abccf
commit e47f2dead0
12 changed files with 227 additions and 124 deletions
@@ -5,7 +5,7 @@

 ## 定位

-`agent_step` 记录 Diagnosis Agent 模型步骤的有界审计 metadata。`run_id` 是执行隔离边界；当前写入不得保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。
+`agent_step` 记录 Diagnosis Agent 模型步骤的有界审计 metadata。`run_id` 是执行隔离边界；当前写入不得保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。Provider reasoning 使用独立 `agent_reasoning_audit` 表，不复用历史 `thought` 字段。

 ## 字段

@@ -37,9 +37,11 @@
 - `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。
 - `agent_step.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。
 - `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。
+- `agent_reasoning_audit` 通过相同的 `session_id + run_id + step_index` 逻辑定位模型步骤，不建立数据库外键。

 ## 注意点

 - 前端展示步骤时应使用 Trace API 返回顺序；服务端会在同一 `run_id` 范围内整理步骤顺序。
 - 新 Trace 和验收读路径必须按 exact `run_id` 取数，避免同一 `sessionId` 多次运行混入。
 - 当前 Run 若出现 `diagnosis_agent` 之外的新写入，或 `thought` 非空，视为审计边界违规。
+- `model_output` 可保存 `has_text`、`tool_names`、`reasoning_available` 和 `reasoning_bytes` 等有界 metadata，不得保存 reasoning 原文。