SuperBizAgent-java/mvp/architecture/current-mvp-architecture.md

当前 MVP 架构

更新日期：2026-09-29 状态：当前可运行架构

1. 系统定位

SuperBizAgent 是面向故障诊断的可追踪 Agent 应用。当前系统只保留一个拥有 Tool loop 的 Diagnosis Agent；Harness 负责确定性的预算、取消、工具边界、证据验真、语义审查和安全发布。

知识检索当前为显式 lookup_knowledge 工具 + 独立 py-rag 知识服务（HTTP /api/v1）；检索算法（dense+BM25 融合、rerank、判级）与文档入库全部在 py-rag 侧，Java 只保留 harness 消费面与 HTTP 客户端。详细链路见 RAG知识检索架构.md。

2. 分层

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 主链

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 检索边界

Agent
  -> RagToolAdapter / ToolBoundary
  -> LookupKnowledgeTool
      -> 原始 query 直传（L0 已下沉 py-rag）
      -> KnowledgeSearchPort
      -> PyRagKnowledgeSearchAdapter   # HTTP 客户端（PyRagClient）
      -> py-rag 知识服务 /api/v1/search # 融合 / rerank / 判级
  -> KnowledgeEvidencePostProcessor    # chunk 去重 / return-n / 判级（Java 侧）
  -> RagResultProjector                # 有界 Agent 投影

要点：

• 默认 retrieval.search.mode=hybrid：映射 py-rag hybrid（dense+BM25 融合）；dense 映射 semantic 作对照。
• 证据按 chunk 级 evidenceKey 去重；Agent 侧 document_id 为 chunk 级身份。
• py-rag evidence_status=no_evidence 按正常"无知识可用"处理，不是错误。
• 知识库全量重建：py-rag POST /api/v1/collections:rebuild?confirm=REBUILD（异步任务）。

完整契约映射、入库、重建与历史差异见 RAG知识检索架构.md。

5. Trace 与持久化

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/documents/upload：文档上传（MySQL 业务元数据 + 本地原件 + py-rag ingest）
• POST /api/upload：简单上传（本地保存 + py-rag ingest，可选 category）
• GET /api/documents/{docId} / GET /api/documents/status/{status} / GET /api/documents/faultSource/{faultSource}：文档元数据查询
• DELETE /api/documents/{docId}：删除 MySQL 元数据与本地原件（py-rag 侧索引需全量重建生效）

知识库检索/入库/重建的服务端健康与统计由 py-rag 提供：GET /api/v1/health、GET /api/v1/stats（{pyrag.base-url}）。

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。