# Diagnosis Agent 执行架构

**更新日期**：2026-07-23
**状态**：当前可运行架构

## 1. 单 Agent 原则

当前业务诊断只有一个 `Diagnosis Agent`。它使用框架 `ReactAgent` 完成规划、行动、观察和最终 Draft，但项目不在外层复制 ReAct 状态机，也不使用业务 Graph 或多角色协作链。

## 2. 职责

Diagnosis Agent：

- 接收当前 query 与可选、受限的安全 PreviousTurn。
- 自主选择只读 evidence Tool。
- 根据 Agent projection 判断是否需要继续查询。
- 输出结构化 `DiagnosisDraft`，每条 analysis 绑定 framework `tool_call_id`。
- 证据不足时明确限制，不补造事实。

Diagnosis Agent 不负责：

- HTTP/SSE、Session/Run 生命周期和持久化。
- 模型/Tool/Token/timeout/cancel 预算。
- Tool 参数授权、raw response 投影或证据物理验真。
- SemanticGuard 与最终发布决定。

## 3. 执行序列

```mermaid
sequenceDiagram
    participant App as Chat Application
    participant Core as Harness Core
    participant Agent as Diagnosis Agent
    participant Tool as ACI Tool Boundary
    participant Audit as Audit Hook / Trace Recorder
    participant EG as EvidenceGuard
    participant SG as SemanticGuard
    participant Release as Release Policy

    App->>Core: start RunContext
    App->>Agent: query + safe previous_turn
    Agent->>Tool: tool name + framework tool_call_id + typed args
    Tool-->>Agent: bounded agent_result
    Tool->>Audit: bounded Tool lifecycle metadata
    Agent->>Audit: step metadata + Provider reasoning availability
    Agent-->>App: DiagnosisDraft
    App->>EG: Draft + current Run canonical invocations
    EG-->>App: verified snapshot or deterministic failure
    App->>SG: query + full Draft + verified snapshot
    SG-->>App: SUPPORTED / UNSUPPORTED
    App->>Release: decide public content
    Release-->>App: report or fixed fallback
```

## 4. PreviousTurn

PreviousTurn 只来自同一 Session 最近一个 `DIAGNOSIS + SUCCESS + published_result`。Fallback、失败、取消、raw evidence 和完整历史都不能进入下一轮；字段与字节上限由 Harness 配置控制。

## 5. Provider Reasoning 与 Assistant 正文审计

`HarnessAgentAuditHook` 在每次模型步骤结束后写入独立表 `agent_reasoning_audit`，**同时**尝试捕获：

| 列 | 含义 |
|---|---|
| `reasoning_content` | Provider thinking / CoT |
| `assistant_text` | 本步 assistant 可见正文，和/或 tool-call **计划**（不含 tool 结果） |
| `content_source` | `PROVIDER_REASONING+ASSISTANT_TEXT` 等组合标记 |
| `content_bytes` | 两列截断后 UTF-8 字节合计 |

### 捕获路径（DeepSeek 生产）

当前 Chat 为 Spring AI 原生 `DeepSeekChatModel`（`deepseek-v4-flash`）。API 返回的 `message.reasoning_content` 被映射到 **`DeepSeekAssistantMessage.getReasoningContent()`**，而不是普通 `AssistantMessage.metadata`。Hook 优先读该专用字段，再反射 `getReasoningContent()`，最后才回退 metadata 键（`reasoning_content` / `thinking` 等）。

只接受 Provider 实际返回的非空文本；不得根据最终回答反推或生成伪 reasoning。

### 边界

- 单字段最多保留 32000 字符；tool **结果**只在 `tool_invocation`。
- `agent_step.model_*` 仍为有界 metadata（含 `reasoning_available` / bytes / `content_source`）。
- `agent_step.thought` 为兼容镜像：优先 reasoning，否则 assistant 正文；完整双字段以 `agent_reasoning_audit` 为准。
- 普通 Timeline 的 `AGENT_MODEL_STEP` 不保存 reasoning/assistant 原文。
- Reasoning / assistant 审计原文只用于受限审计 API，不进入 Agent 后续上下文，不参与 EvidenceGuard、SemanticGuard 或 Release Policy 的事实判断。

### 运行级结论读出

Run 结束时 `JpaChatRunStore` 从安全发布 JSON 提取 `diagnosis_run.conclusion`（与 `query` 并列），便于 Trace/DB 直接读结论；它不是 Provider thinking。

### 验证与治理

- **已 live 验证（2026-07-28）**：DeepSeek thinking 模式下 `reasoning_available=true`，且 reasoning 与 assistant 可同时非空。
- 查询隔离已实现；访问控制、保留期限、加密等完整治理仍属 ISS-015。