osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(mvp): align architecture and audit table design

Browse Source
This commit is contained in:
zhuyongxin
2026-07-23 20:16:29 +08:00
parent 49180abccf
commit e47f2dead0
12 changed files with 227 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mvp/tables/Agent推理审计表-agent_reasoning_audit.md
+50
View File
@@ -0,0 +1,50 @@
# 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 跟踪；治理完成前不应将该接口暴露给普通业务用户。
mvp/tables/Agent步骤表-agent_step.md
+3 -1
View File
@@ -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 原文。
mvp/tables/README.md
+6 -2
View File
@@ -1,6 +1,6 @@
# MVP 数据表索引
**更新日期**：2026-07-10
**更新日期**：2026-07-23
**状态**：当前表文档入口
本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。
@@ -13,6 +13,8 @@
| `diagnosis_run` | `/api/chat` 运行主记录，保存 intent、终态与安全发布结果 | [诊断运行表-diagnosis_run.md](诊断运行表-diagnosis_run.md) |
| `agent_step` | Diagnosis Agent metadata-only 模型步骤审计 | [Agent步骤表-agent_step.md](Agent步骤表-agent_step.md) |
| `tool_invocation` | Harness ToolBoundary metadata-only 长期审计 | [工具调用表-tool_invocation.md](工具调用表-tool_invocation.md) |
| `diagnosis_trace_event` | 按 Run 追加的统一诊断生命周期 Timeline | [诊断Trace事件表-diagnosis_trace_event.md](诊断Trace事件表-diagnosis_trace_event.md) |
| `agent_reasoning_audit` | Provider reasoning 独立敏感审计；不属于普通 Trace | [Agent推理审计表-agent_reasoning_audit.md](Agent推理审计表-agent_reasoning_audit.md) |
| `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) |
| `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) |
| `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) |
@@ -31,6 +33,8 @@ chat_session.session_id
-> diagnosis_run.session_id
-> agent_step.run_id
-> tool_invocation.run_id
-> diagnosis_trace_event.run_id
-> agent_reasoning_audit.run_id (restricted)
-> case_library.diagnosis_id (new AUTO cases use run_id)
diagnosis_session.session_id
@@ -43,4 +47,4 @@ knowledge_domain.domain_id
-> api_document metadata.category / vector chunk metadata.category
```
当前实现主要使用逻辑关联，不依赖数据库外键。
当前实现主要使用 `session_id + run_id` 逻辑关联，不依赖数据库外键。`agent_reasoning_audit` 是敏感审计数据，不与普通 Trace、Evidence Snapshot 或业务结果合并读取。
mvp/tables/诊断Trace事件表-diagnosis_trace_event.md
+52
View File
@@ -0,0 +1,52 @@
# 诊断 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`。
mvp/tables/诊断运行表-diagnosis_run.md
+3
View File
@@ -45,6 +45,8 @@
- `diagnosis_run.session_id` 逻辑关联 `chat_session.session_id`。
- `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `tool_invocation.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `diagnosis_trace_event.run_id` 逻辑关联 `diagnosis_run.run_id`，形成统一生命周期 Timeline。
- `agent_reasoning_audit.run_id` 逻辑关联 `diagnosis_run.run_id`，但只能通过独立敏感审计读路径查询。
- 新的自动案例沉淀使用 `case_library.diagnosis_id = diagnosis_run.run_id`。
## 注意点
@@ -53,3 +55,4 @@
- latest run 排序使用 `created_at DESC, id DESC`，避免 feedback 或自评估更新 `updated_at` 后改变回放目标。
- 历史 `diagnosis_session` 会被迁移成兼容 run，但旧混合数据不能被还原成真实多轮边界。
- 当前诊断发布结果以 `release_outcome + published_result` 为准，不得从旧 self-evaluation 推断 Release Policy 结果。
- `diagnosis_run` 不保存 reasoning 原文；普通 Run/Trace 查询也不得通过聚合将其带出。