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.
134 lines
6.7 KiB
Markdown
134 lines
6.7 KiB
Markdown
# 当前 MVP 架构
|
||
|
||
**更新日期**：2026-07-28
|
||
**状态**：当前可运行架构
|
||
|
||
## 1. 系统定位
|
||
|
||
SuperBizAgent 是面向故障诊断的可追踪 Agent 应用。当前系统只保留一个拥有 Tool loop 的 `Diagnosis Agent`；Harness 负责确定性的预算、取消、工具边界、证据验真、语义审查和安全发布。
|
||
|
||
知识检索当前为显式 `lookup_knowledge` 工具 + 单一 MilvusClientV2 后端（dense / dense+BM25 hybrid）。详细链路见 [RAG知识检索架构.md](RAG知识检索架构.md)。
|
||
|
||
## 2. 分层
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Browser["Browser / API client"] --> Chat["POST /api/chat named SSE"]
|
||
Chat --> App["ChatApplicationUseCase"]
|
||
App --> Router["Intent Router"]
|
||
Router --> System["System Chat"]
|
||
Router --> Knowledge["Knowledge Query"]
|
||
Router --> Diagnosis["Diagnosis Agent"]
|
||
Diagnosis --> Tools["Harness ACI Tools"]
|
||
Tools --> Canonical["Redis canonical invocation"]
|
||
Diagnosis --> Evidence["EvidenceGuard"]
|
||
Evidence --> Semantic["SemanticGuard"]
|
||
Semantic --> Release["Release Policy"]
|
||
Release --> Chat
|
||
App --> Run["diagnosis_run"]
|
||
Diagnosis --> Step["agent_step metadata audit"]
|
||
App --> Timeline["diagnosis_trace_event"]
|
||
Diagnosis --> Reasoning["agent_reasoning_audit restricted"]
|
||
Tools --> Invocation["tool_invocation metadata audit"]
|
||
Run --> Trace["Diagnosis Trace API"]
|
||
Step --> Trace
|
||
Invocation --> Trace
|
||
Timeline --> Trace
|
||
Reasoning --> ReasoningAPI["Reasoning Audit API"]
|
||
```
|
||
|
||
## 3. 唯一 Chat 主链
|
||
|
||
```text
|
||
POST /api/chat
|
||
-> metadata(session_id, run_id)
|
||
-> status*
|
||
-> ChatApplicationUseCase
|
||
-> SYSTEM_CHAT | KNOWLEDGE_QUERY | DIAGNOSIS
|
||
-> content | failure
|
||
-> done(SUCCESS | FALLBACK | FAILED)
|
||
```
|
||
|
||
- Controller 只处理请求校验、bounded worker、SSE 和 disconnect。
|
||
- Application Use Case 拥有 Session/Run、路由、PreviousTurn 和终态持久化。
|
||
- Diagnosis Agent 是唯一报告作者和唯一拥有 evidence Tool loop 的业务 Agent。
|
||
- EvidenceGuard 只做确定性结构/引用验真；SemanticGuard 在隔离上下文做整份报告语义审查。
|
||
- 未通过 Release Policy 的 Draft 永不进入公开 SSE。
|
||
|
||
## 4. Tool 与数据边界
|
||
|
||
Agent 只看到三个固定 Tool：
|
||
|
||
- `lookup_knowledge`
|
||
- `query_logs`
|
||
- `query_mysql`
|
||
|
||
每次调用由框架提供 `tool_call_id`，Harness 校验 exact run、只读、Schema、预算和容量。Redis 保存 TTL 内完整 canonical invocation；MySQL `tool_invocation` 只保存长期有界 metadata，不保存完整参数、SQL/日志正文、raw response 或 Agent projection。
|
||
|
||
### 4.1 `lookup_knowledge` 检索边界
|
||
|
||
```text
|
||
Agent
|
||
-> RagToolAdapter / ToolBoundary
|
||
-> LookupKnowledgeTool
|
||
-> L0 hint（可选 category filter）
|
||
-> KnowledgeSearchPort
|
||
-> VectorSearchService
|
||
-> MilvusHybridKnowledgeStore # 唯一知识向量后端
|
||
-> RagResultProjector # 有界 Agent 投影
|
||
```
|
||
|
||
要点：
|
||
|
||
- 默认 `retrieval.search.mode=hybrid`：dense ANN + BM25 sparse ANN + RRFRanker。
|
||
- 也可切 `dense`：仅 dense ANN。
|
||
- 已移除知识路径上的 legacy `MilvusServiceClient` search 与 `vector-store.mode=sdk|spring|auto` 路由。
|
||
- 证据按 chunk 级 `evidenceKey` 去重；Agent 侧 `document_id` 为 chunk 级身份。
|
||
- 知识库全量重建：`python scripts/rebuild_hybrid_knowledge.py --confirm REBUILD`，默认操作 collection `biz`。
|
||
|
||
完整 schema、模式、重建与历史差异见 [RAG知识检索架构.md](RAG知识检索架构.md)。
|
||
|
||
## 5. Trace 与持久化
|
||
|
||
```text
|
||
chat_session(sessionId)
|
||
-> diagnosis_run(runId)
|
||
-> agent_step(runId)
|
||
-> tool_invocation(runId)
|
||
-> diagnosis_trace_event(runId)
|
||
-> agent_reasoning_audit(runId, restricted)
|
||
```
|
||
|
||
- `chat_session` 是 JPA Run 目录与多轮 metadata，不保存完整对话历史。
|
||
- `diagnosis_run` 是 Run 状态、intent、release outcome、安全发布结果、预算汇总真理源；另含与 `query` 并列的提取字段 `conclusion`（业务结论读出，非 thinking）。
|
||
- `agent_step` 保存模型步骤有界 metadata；`thought` 可为 reasoning/assistant 的兼容镜像，完整双字段不在此表。
|
||
- `tool_invocation` 只保存 Tool durable audit metadata；完整调用由 Redis canonical store 短期保存。
|
||
- `diagnosis_trace_event` 是追加式统一 Timeline，记录 Run、Routing、Agent、Tool、Evidence、Semantic 和 Release 生命周期事件；`details` 只能保存有界安全 metadata。
|
||
- `agent_reasoning_audit` 与普通 Trace 分表，按模型步骤保存 Provider `reasoning_content` 与 `assistant_text`（及 `content_source`），或明确的 unavailable；二者均不属于事实证据。
|
||
|
||
## 6. 公开 API
|
||
|
||
当前诊断执行入口只有 `POST /api/chat`。诊断审计读取分为：
|
||
|
||
- `GET /api/diagnosis/{sessionId}/trace?runId={runId}`：普通 Trace，返回 Run（含 `query`/`conclusion`）、步骤、Tool metadata 和统一 Timeline，**不**返回 reasoning/assistant 原文。
|
||
- `GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}`：独立 LLM 步骤审计读取（`reasoningContent` + `assistantText`），`runId` 必填并校验其属于 path `sessionId`。
|
||
|
||
Reasoning endpoint 是敏感审计面，不属于普通业务 API。数据和查询隔离、DeepSeek thinking 捕获路径已 live 验证；认证授权、保留期限、加密要求仍由 ISS-015 收敛。Feedback、文档与检索 API 保持独立；已删除的旧诊断和 Redis conversation Session endpoint 不提供兼容分支。
|
||
|
||
与知识检索相关的独立 API：
|
||
|
||
- `POST /api/knowledge/init`：导入/增量初始化 `knowledge_base`
|
||
- `POST /api/knowledge/rebuild-hybrid?confirm=REBUILD`：清空并重建 dense+BM25 collection（默认 `biz`）
|
||
- `GET /api/knowledge/stats`：文档元数据统计
|
||
- `GET /milvus/health`：MilvusClientV2 健康检查与 knowledge collection 名
|
||
|
||
## 7. 安全边界
|
||
|
||
- 普通 SSE、普通 Trace 的 steps/timeline、Evidence Snapshot、业务结果和应用日志不输出或保存 reasoning / assistant 审计原文。
|
||
- 审计 Hook 仅当 Provider **实际返回** thinking（DeepSeek：`DeepSeekAssistantMessage.reasoningContent`；其它：metadata 键）时写入 `reasoning_content`；未返回时不得伪造。`assistant_text` 来自本步 assistant 可见输出与 tool-call 计划，不含 tool 结果。
|
||
- Reasoning / assistant 审计原文不能作为事实证据，也不能绕过 EvidenceGuard 或 SemanticGuard。
|
||
- 不向 Agent 暴露 Redis、canonical key、完整 Tool 请求/响应或数据库凭据。
|
||
- EvidenceGuard 只接受当前 Run 的 READY canonical invocation。
|
||
- SemanticGuard 无 Tool、无记忆、无回调主 Agent 能力。
|
||
- technical failure 与 guard rejection 只能产生 stable failure 或固定 safe fallback。
|