docs(mvp): align architecture and audit table design

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
+17 -1
View File
@@ -1,6 +1,6 @@
# Session、Run 与 Trace 生命周期
**更新日期**:2026-07-22
**更新日期**:2026-07-23
**状态**:当前可运行架构
## 1. Identity
@@ -15,9 +15,11 @@
request accepted
-> start RunContext
-> persist diagnosis_run RUNNING
-> append diagnosis_trace_event RUN_STARTED
-> metadata(session_id, run_id)
-> route / execute / guard / release
-> SUCCESS | FALLBACK | FAILED | CANCELLED
-> append diagnosis_trace_event RUN_FINISHED
-> persist terminal state and budget usage
```
@@ -31,9 +33,23 @@ disconnect、timeout 与 send failure 通过同一个 `ChatRunControl` 请求取
- exact `diagnosis_run` 状态、intent、release outcome、安全 answer 与预算。
- `agent_step` metadata-only 模型步骤。
- `tool_invocation` metadata-only Tool durable audit。
- `diagnosis_trace_event` 按 `sequence_no, id` 排序的统一生命周期 Timeline。
Redis canonical invocation 不是 Trace API 的长期响应内容;它只供当前 Run EvidenceGuard 验真。
普通 Trace 不读取 `agent_reasoning_audit`,也不返回 reasoning 原文。Agent 模型步骤和 Timeline 只暴露 `reasoning_available`、`reasoning_bytes` 等有界 metadata。
## 4. PreviousTurn
应用在创建当前 Run 前读取同 Session 最近安全发布结果。只允许结构化 PublishedResult 的固定字段进入 PreviousTurn,且执行字节上限;完整历史、失败、Fallback、Tool raw data 和 guard reason 均排除。
## 5. Reasoning 审计查询
`GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}` 提供独立 reasoning 审计读取:
- `runId` 必填,服务端先验证 Run 存在且属于 path `sessionId`,禁止跨 Session 串读。
- 结果按 `step_index` 返回 Agent、reasoning availability、受限原文、字节数和创建时间。
- Provider 未返回 reasoning 时仍保留 unavailable 记录,以区分“没有返回”与“审计遗漏”。
- Reasoning 数据不回流到 PreviousTurn,不进入普通 Trace、SSE、Evidence Snapshot 或发布结果。
该端点属于敏感审计面。当前完成了分表、独立查询和归属校验;身份认证、权限模型、保留期限、加密及真实 Provider/V015 验证尚未完成,由 ISS-015 阶段 3 收敛。