zhuyongxin
7ae9707a3b
Persist provider reasoning and assistant text separately on agent_reasoning_audit (DeepSeekAssistantMessage path), extract diagnosis_run.conclusion, enrich RAG tool audit (step_id/query/qualityScore), gate empty mysql tools, drop devtools, and align MVP docs after live E2E verification.
57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# Session、Run 与 Trace 生命周期
|
||
|
||
**更新日期**：2026-07-23
|
||
**状态**：当前可运行架构
|
||
|
||
## 1. Identity
|
||
|
||
- `sessionId`：多轮对话目录，由客户端传入或应用生成。
|
||
- `runId`：一次 Chat 执行，由 Harness 生成并在 SSE metadata 首事件返回。
|
||
- 所有 Run、AgentStep、ToolInvocation 和 Trace 查询必须使用同一个 exact ID；禁止用“最新一条”替代。
|
||
|
||
## 2. 生命周期
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
disconnect、timeout 与 send failure 通过同一个 `ChatRunControl` 请求取消。正常 SSE complete 在 callback 前标记 terminal，避免误取消；late content 被 state machine 拒绝。
|
||
|
||
## 3. Trace 聚合
|
||
|
||
`GET /api/diagnosis/{sessionId}/trace?runId={runId}` 聚合：
|
||
|
||
- `chat_session` metadata。
|
||
- 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` 的 **原文**。Agent 模型步骤和 Timeline 只暴露 `reasoning_available`、`reasoning_bytes` / `assistant_bytes`、`content_source` 等有界 metadata。
|
||
普通 Trace 的 `run` 可返回 `query` 与提取后的 `conclusion`（业务结论读出，非 thinking）。
|
||
|
||
## 4. PreviousTurn
|
||
|
||
应用在创建当前 Run 前读取同 Session 最近安全发布结果。只允许结构化 PublishedResult 的固定字段进入 PreviousTurn，且执行字节上限；完整历史、失败、Fallback、Tool raw data 和 guard reason 均排除。
|
||
|
||
## 5. Reasoning 审计查询
|
||
|
||
`GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}` 提供独立 LLM 步骤审计读取：
|
||
|
||
- `runId` 必填，服务端先验证 Run 存在且属于 path `sessionId`，禁止跨 Session 串读。
|
||
- 结果按 `step_index` 返回：`reasoningAvailable`、`reasoningContent`、`assistantText`、`contentSource`、`contentBytes`、创建时间等。
|
||
- Provider 未返回 reasoning 时仍保留记录（`reasoningAvailable=false`，可仍有 `assistantText`），以区分“没有 thinking”与“审计遗漏”。
|
||
- Reasoning / assistant 审计原文不回流到 PreviousTurn，不进入普通 Trace 的 steps/timeline 原文、SSE、Evidence Snapshot 或发布结果。
|
||
|
||
该端点属于敏感审计面。分表、独立查询、归属校验，以及 DeepSeek 真实 thinking 捕获路径（`DeepSeekAssistantMessage.reasoningContent`）与 V015–V017 迁移已验证；身份认证、权限模型、保留期限、加密仍由 ISS-015 阶段 3 收敛。
|