refactor(harness): remove legacy agent architecture

2026-07-22 18:02:01 +08:00
parent bc36248cd8
commit 8ee7cc0b70
148 changed files with 3091 additions and 13889 deletions
@@ -1,444 +1,86 @@
 # 当前 MVP 架构

-**更新日期**：2026-07-08
+**更新日期**：2026-07-22
 **状态**：当前可运行架构
-**适用范围**：Demo、面试讲解、后续迭代规划

 ## 1. 系统定位

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

-核心目标：
-
- 支持用户主动发起的 Chat 诊断。
- 支持 AIOps 告警触发的自动诊断。
- 保留 Agent 的规划、执行、验证过程。
- 工具调用必须显式、可追踪、可回放。
- RAG 检索必须通过 `lookup_knowledge` 暴露证据链。
- 每次诊断都沉淀 session、step、tool invocation 和 self evaluation。
-
-## 2. 总体分层
+## 2. 分层

 ```mermaid
 flowchart TB
-    subgraph API["API Layer"]
-        ChatController["ChatController"]
-        TraceController["DiagnosisTraceController"]
-        SearchController["SearchController"]
-        DocumentController["DocumentController"]
-    end
-
-    subgraph App["Application Service"]
-        ChatService["ChatService"]
-        AiOpsService["AiOpsService"]
-        TraceService["DiagnosisTraceService"]
-    end
-
-    subgraph Agent["Agent Orchestration"]
-        Supervisor["Supervisor"]
-        Planner["Planner"]
-        Executor["Executor"]
-        Gatekeeper["Gatekeeper"]
-        Verifier["Verifier"]
-        Composer["Composer"]
-    end
-
-    subgraph Tools["Evidence Tools"]
-        KnowledgeTool["lookup_knowledge"]
-        LogsTool["query_logs"]
-        MetricsTool["query_metrics"]
-        AlertsTool["queryPrometheusAlerts"]
-    end
-
-    subgraph Skills["Skill / Playbook"]
-        SkillRegistry["SkillRegistry"]
-        PlannerSkillHook["PlannerSkillMetadataHook"]
-        SkillsHook["SkillsAgentHook"]
-        ReadSkill["read_skill"]
-    end
-
-    subgraph RAG["RAG Retrieval"]
-        L0["KnowledgeIndexService"]
-        VectorSearch["VectorSearchService"]
-        VectorStore["Spring AI VectorStore"]
-        SdkFallback["Milvus SDK fallback"]
-    end
-
-    subgraph Store["Persistence and Trace"]
-        ChatSession["chat_session"]
-        Run["diagnosis_run"]
-        Step["agent_step"]
-        Invocation["tool_invocation"]
-        ApiDoc["api_document"]
-        Milvus["Milvus/Zilliz"]
-    end
-
-    API --> App
-    ChatService --> Agent
-    AiOpsService --> Agent
-    SkillRegistry --> PlannerSkillHook
-    PlannerSkillHook --> Planner
-    SkillRegistry --> SkillsHook
-    SkillsHook --> Executor
-    Executor --> ReadSkill
-    Agent --> Tools
-    KnowledgeTool --> RAG
-    RAG --> Store
-    Tools --> Invocation
-    Agent --> Step
-    App --> Session
-    TraceService --> Session
-    TraceService --> Step
-    TraceService --> Invocation
+    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"]
+    Tools --> Invocation["tool_invocation metadata audit"]
+    Run --> Trace["Diagnosis Trace API"]
+    Step --> Trace
+    Invocation --> Trace
 ```

-```text
-API Layer
-  -> ChatController
-  -> DiagnosisTraceController
-  -> SearchController
-  -> DocumentController
-
-Application Service
-  -> ChatService
-  -> AiOpsService
-  -> DiagnosisTraceService
-
-Agent Orchestration
-  -> Supervisor
-  -> Planner
-  -> Executor
-  -> Gatekeeper
-  -> Verifier
-  -> Composer
-
-Evidence Tools
-  -> lookup_knowledge
-  -> query_logs
-  -> query_metrics
-  -> queryPrometheusAlerts
-
-Skill / Playbook
-  -> SkillRegistry
-  -> PlannerSkillMetadataHook gives Planner name/description only
-  -> SkillsAgentHook gives Executor read_skill
-  -> Verifier is isolated from skills
-
-RAG Retrieval
-  -> KnowledgeIndexService
-  -> VectorSearchService
-  -> Spring AI VectorStore
-  -> Milvus SDK fallback
-
-Persistence
-  -> chat_session
-  -> diagnosis_run
-  -> agent_step.run_id
-  -> tool_invocation.run_id
-  -> api_document
-  -> Milvus/Zilliz collection
-
-Quality Gates
-  -> executor gatekeeper
-  -> chat verifier
-  -> AIOps rule evaluation
-  -> diagnosis eval baseline
-  -> RAG retrieval baseline
-```
-
-## 3. Chat 诊断链路
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User as 用户
-    participant API as POST /api/chat
-    participant Chat as ChatService
-    participant Planner as Planner Agent
-    participant Executor as Executor Agent
-    participant Tool as Evidence Tools
-    participant Gatekeeper as Gatekeeper Hook
-    participant Verifier as Verifier Agent
-    participant Composer as Composer Agent
-    participant DB as Trace Tables
-    participant Trace as Trace API
-
-    User->>API: 提交诊断问题
-    API->>Chat: execute chat strategy
-    Chat->>DB: 创建 chat_session metadata + diagnosis_run(runId)
-    Chat->>Planner: 复杂问题进入规划
-    Planner->>DB: 写入 agent_step.run_id
-    Planner->>Executor: 下发排查方向
-    Executor->>Tool: lookup_knowledge / logs / metrics
-    Tool->>DB: 写入 tool_invocation.run_id
-    Tool-->>Executor: 返回证据
-    Executor->>Gatekeeper: 输出 executor_evidence_v2
-    Gatekeeper->>DB: 读取 tool_invocation.evidence_refs 并校验引用
-    Gatekeeper->>Verifier: 传入已验真的 claims / excerpts
-    Verifier->>DB: 合并 diagnosis_run.self_evaluation.verifier_evaluation
-    Verifier->>Composer: 传入 allowed_claims / missing_info / actions
-    Composer->>Chat: 生成最终用户答复
-    Chat->>DB: 保存 diagnosis_run.answer
-    User->>Trace: GET /api/diagnosis/{sessionId}/trace?runId=...
-    Trace->>DB: 聚合 run / step / tool
-    Trace-->>User: 返回可回放诊断链路
-```
+## 3. 唯一 Chat 主链

 ```text
 POST /api/chat
-  -> ChatService
-      -> 简单问题：轻量回答
-      -> 复杂诊断：Agent 编排
-          -> Planner 制定排查方向
-          -> Executor 调用证据工具
-              -> lookup_knowledge
-              -> query_logs
-              -> query_metrics
-          -> Gatekeeper 校验 Executor 证据引用真实性
-          -> Verifier 判断 claim 是否能由已核验证据推出
-          -> Composer 生成最终用户答复
-      -> 保存 chat_session metadata
-      -> 保存 diagnosis_run
-      -> 保存 agent_step.run_id
-      -> 保存 tool_invocation.run_id
-      -> 合并 diagnosis_run.self_evaluation.verifier_evaluation
+  -> metadata(session_id, run_id)
+  -> status*
+  -> ChatApplicationUseCase
+     -> SYSTEM_CHAT | KNOWLEDGE_QUERY | DIAGNOSIS
+  -> content | failure
+  -> done(SUCCESS | FALLBACK | FAILED)
 ```

-Chat 链路的质量门禁由三段组成：Gatekeeper 先做代码级引用验真，Verifier 再做 LLM 可推导性判断，Composer 最后控制对用户的表达边界。Gatekeeper、Verifier、Composer 的输出合并到当前 `diagnosis_run.self_evaluation.verifier_evaluation`，Trace API 会展示该验证结果。
+- Controller 只处理请求校验、bounded worker、SSE 和 disconnect。
+- Application Use Case 拥有 Session/Run、路由、PreviousTurn 和终态持久化。
+- Diagnosis Agent 是唯一报告作者和唯一拥有 evidence Tool loop 的业务 Agent。
+- EvidenceGuard 只做确定性结构/引用验真；SemanticGuard 在隔离上下文做整份报告语义审查。
+- 未通过 Release Policy 的 Draft 永不进入公开 SSE。

-Agent 编排细节见 [agent-orchestration.md](agent-orchestration.md)。
+## 4. Tool 与数据边界

-关键代码：
+Agent 只看到三个固定 Tool：

- `src/main/java/com/superbiz/agent/controller/ChatController.java`
- `src/main/java/com/superbiz/agent/service/ChatService.java`
- `src/main/java/com/superbiz/agent/service/SelfEvaluationMergeService.java`
- `src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`
+- `lookup_knowledge`
+- `query_logs`
+- `query_mysql`

-## 4. AIOps 诊断链路
+每次调用由框架提供 `tool_call_id`，Harness 校验 exact run、只读、Schema、预算和容量。Redis 保存 TTL 内完整 canonical invocation；MySQL `tool_invocation` 只保存长期有界 metadata，不保存完整参数、SQL/日志正文、raw response 或 Agent projection。

-```mermaid
-flowchart TD
-    Request["POST /api/ai_ops"] --> Payload{"包含告警 payload?"}
-    Payload -->|是| Targeted["PAYLOAD_TARGETED"]
-    Payload -->|否| Discovery["AUTO_DISCOVERY"]
-
-    Targeted --> BuildPrompt["构造聚焦 payload 的诊断 prompt"]
-    Targeted --> QueryAug["生成 recommended lookup_knowledge query"]
-    Discovery --> DiscoverAlert["通过 queryPrometheusAlerts 发现活跃告警"]
-
-    BuildPrompt --> Plan["Planner 规划排查"]
-    QueryAug --> Plan
-    DiscoverAlert --> Plan
-
-    Plan --> Execute["Executor 收集证据"]
-    Execute --> Knowledge["lookup_knowledge"]
-    Execute --> Metrics["query_metrics / Prometheus"]
-    Execute --> Logs["query_logs"]
-
-    Knowledge --> Report["告警分析报告"]
-    Metrics --> Report
-    Logs --> Report
-
-    Report --> RuleEval["AiOpsRuleEvaluationService"]
-    RuleEval --> SelfEval["self_evaluation.aiops_rule_evaluation"]
-    Report --> Trace["DiagnosisTraceService"]
-    SelfEval --> Trace
-```
+## 5. Trace 与持久化

 ```text
-POST /api/ai_ops
-  -> AiOpsService
-      -> 判断是否有告警 payload
-          -> PAYLOAD_TARGETED
-          -> AUTO_DISCOVERY
-      -> 构造 AIOps 诊断 prompt
-      -> payload 模式补充 recommended lookup_knowledge query
-      -> Agent 编排
-          -> Planner / Executor
-          -> Prometheus / logs / knowledge tools
-      -> 生成告警分析报告
-      -> AiOpsRuleEvaluationService
-      -> 合并 diagnosis_run.self_evaluation.aiops_rule_evaluation
-      -> Trace API 可查看全链路
+chat_session(sessionId)
+  -> diagnosis_run(runId)
+      -> agent_step(runId)
+      -> tool_invocation(runId)
 ```

-AIOps 保留两种模式：
+- `chat_session` 是 JPA Run 目录与多轮 metadata，不保存完整对话历史。
+- `diagnosis_run` 是 Run 状态、intent、release outcome、安全发布结果和预算汇总真理源。
+- `agent_step` 只保存模型步骤 metadata，不保存 Prompt、消息正文、模型正文或 Thought。
+- `tool_invocation` 只保存 Tool durable audit metadata；完整调用由 Redis canonical store 短期保存。

-| 模式 | 触发条件 | 行为 |
-|---|---|---|
-| `PAYLOAD_TARGETED` | 请求包含 alertName、service、severity、description、timeRange 等字段 | 以 payload 为唯一主诊断对象，并生成推荐知识库 query |
-| `AUTO_DISCOVERY` | 请求没有明确告警 payload | 先查询当前活跃告警，再选择目标排查 |
+## 6. 公开 API

-AIOps 当前使用轻量规则验证器，重点检查：
+当前诊断执行入口只有 `POST /api/chat`。Trace、feedback、文档与检索 API 保持独立；已删除的旧诊断和 Redis conversation Session endpoint 不提供兼容分支。

- 最终报告是否存在。
- payload 模式是否聚焦输入告警。
- 是否使用关键证据工具，例如 `lookup_knowledge`、日志、指标。
+## 7. 安全边界

-关键代码：
-
- `src/main/java/com/superbiz/agent/service/AiOpsService.java`
- `src/main/java/com/superbiz/agent/service/AiOpsRuleEvaluationService.java`
-
-## 5. RAG 位置
-
-RAG 不是隐藏在 Chat Advisor 里的隐式能力，而是 Executor 可以显式调用的工具：
-
-```mermaid
-flowchart LR
-    Executor["Executor Agent"] --> Tool["lookup_knowledge Tool"]
-    Tool --> L0["L0 domain/entity hint"]
-    Tool --> Search["VectorSearchService"]
-    L0 --> Search
-    Search --> VectorStore["Spring AI VectorStore"]
-    Search --> Fallback["Milvus SDK fallback"]
-    VectorStore --> Normalize["score/rawScore/scoreLabel"]
-    Fallback --> Normalize
-    Normalize --> Evidence["evidence output"]
-    Evidence --> Invocation["tool_invocation"]
-    Evidence --> Executor
-```
-
-```text
-Executor
-  -> lookup_knowledge(query)
-      -> L0 domain/entity hint
-      -> VectorSearchService
-          -> Spring AI VectorStore
-          -> Milvus SDK fallback
-      -> evidence shaping
-      -> tool_invocation
-```
-
-保留显式工具的原因：
-
- Agent 何时检索、检索什么、证据是什么，必须能在 trace 中解释。
- AIOps payload 到 query 的业务映射需要项目内控制。
- `tool_invocation` 是后续评测、回放和面试讲解的核心材料。
-
-RAG 总体设计见 [rag-architecture.md](rag-architecture.md)，检索运行细节见 [retrieval-observability.md](retrieval-observability.md)。
-
-## 6. 持久化模型
-
-当前诊断持久化以 session/run/trace 明细为核心：
-
-```text
-chat_session
-  -> 多轮会话目录和元数据
-  -> session_id / status / message_pair_count
-
-diagnosis_run
-  -> 一次诊断运行的主记录
-  -> run_id / session_id
-  -> query / status / agent_flow / answer
-  -> self_evaluation
-  -> step_count / tool_call_count / duration
-
-agent_step
-  -> Agent 模型调用步骤
-  -> session_id / run_id
-  -> step_index / agent_name
-  -> model_input / model_output / thought
-  -> duration / token_count
-
-tool_invocation
-  -> 工具调用事实
-  -> session_id / run_id
-  -> tool_name / input_params / output_preview
-  -> retrieval_layer / retrieval_details
-  -> retrieval_details.evidence_refs
-  -> relevance_level / dedup_reason
-  -> duration / success
-```
-
-说明：
-
- 旧的 `diagnosis_record` 已不是当前主模型。
- `diagnosis_session` 已降级为历史兼容和回滚表，新执行写入 `chat_session + diagnosis_run`。
- `api_document` 仍用于文档元数据管理。
- 文档向量内容存放在 Milvus/Zilliz collection 中。
-
-会话和 Trace 生命周期见 [session-trace-lifecycle.md](session-trace-lifecycle.md)，完整数据关系见 [data-model.md](data-model.md)。
-
-## 7. Trace API
-
-```text
-GET /api/diagnosis/{sessionId}/trace
-GET /api/diagnosis/{sessionId}/trace?runId=run-...
-```
-
-Trace API 聚合：
-
- 会话元数据、运行状态和最终报告。
- Agent step 序列。
- 工具调用和检索细节。
- Chat Gatekeeper / Verifier / Composer 结果。
- AIOps rule evaluation 结果。
-
-Trace 是本项目区别于普通问答系统的关键：答案不是孤立文本，而是可以追溯到 Agent 决策、工具调用和证据来源。
-
-Prompt、Hook、Gatekeeper、Verifier、Composer 和评测门禁的完整说明见 [harness-quality-gates.md](harness-quality-gates.md)，用户反馈与 `self_evaluation` 闭环见 [feedback-architecture.md](feedback-architecture.md)。
-
-## 8. 质量门禁
-
-当前质量门禁分层如下：
-
-| 门禁 | 位置 | 作用 |
-|---|---|---|
-| Executor Gatekeeper | `VerifierInputHook` / `ExecutorGatekeeperService` | 校验 Executor 引用的 invocation、`raw_path`、`evidence_excerpt` 是否真实 |
-| Chat Verifier | `ChatService` | 判断已验真证据是否能推出 Executor claims |
-| Chat Composer | `ChatService` | 只表达 Verifier 允许输出的内容，避免把 no-evidence 说成已排除 |
-| AIOps Rule Evaluation | `AiOpsRuleEvaluationService` | 校验告警诊断是否聚焦 payload 并使用证据 |
-| Diagnosis Eval Baseline | `mvp/eval/` | 固化诊断 trace 和报告行为 |
-| RAG Retrieval Baseline | `eval/rag-retrieval/` | 固化检索召回行为，避免 RAG 重构回退 |
-| Live RAG Acceptance | `scripts/eval_rag_live_acceptance.py` | 在运行环境中验证重建索引后的真实检索 |
-
-## 9. 当前完成状态
-
-已经完成：
-
- Chat 和 AIOps 两条入口链路。
- 显式 `lookup_knowledge` Agent Tool。
- L0 从最终决策降级为 domain/entity hint。
- `VectorSearchService` 作为稳定检索门面。
- Spring AI VectorStore 读取路径。
- Milvus SDK fallback。
- `score` / `rawScore` / `scoreLabel` 分数语义拆分。
- `title`、`breadcrumb`、`content` 参与 embedding 文本。
- `tool_invocation` 记录检索层、relevance level、dedup reason。
- Chat verifier 和 AIOps rule evaluation 合并进 `self_evaluation`。
- Chat Executor 结构化输出 `executor_evidence_v2`，不再直接承担最终用户答复。
- `tool_invocation.retrieval_details.evidence_refs` 支持 `raw_path` 精确引用和 `$.no_evidence` 负向证据。
- Gatekeeper 对 Executor 引用做代码级验真，并在审计中记录 `rule_set_version` 和规则元数据摘要。
- Verifier 只判断可推导性。
- Composer 在 Verifier 之后生成最终用户表达，并限制 negative observation 过度表述。
- RAG offline baseline 和 live acceptance 脚本。
-
-暂不作为当前已完成能力声明：
-
- 完整 QueryTransformer / MultiQuery。
- BM25、RRF、cross-encoder rerank。
- 完整邻居 chunk / section context expansion。
- VectorStore 写入路径全面迁移。
- 完整 LLM-based AIOps verifier。
-
-后续 Agent 拆分、Skill/Playbook、MCP 工具协议化和进程隔离等方向见 [evolution-roadmap.md](evolution-roadmap.md)。
-
-## 10. 关键代码索引
-
-| 能力 | 代码 |
-|---|---|
-| Chat 入口与编排 | `ChatController`, `ChatService` |
-| AIOps 入口与编排 | `ChatController.aiOps`, `AiOpsService` |
-| AIOps 规则验证 | `AiOpsRuleEvaluationService` |
-| 知识库工具 | `LookupKnowledgeTool` |
-| L0 hint | `KnowledgeIndexService` |
-| 向量检索门面 | `VectorSearchService` |
-| 文档切片 | `DocumentChunkService` |
-| 向量写入 | `VectorIndexService` |
-| Spring AI VectorStore 配置辅助 | `SpringAiVectorStoreSidecarService` |
-| Trace 聚合 | `DiagnosisTraceService` |
-| 工具调用记录 | `ToolInvocationRecorder` |
-| Executor 引用验真 | `ExecutorGatekeeperService`, `VerifierInputHook` |
-| self_evaluation 合并 | `SelfEvaluationMergeService` |
+- 不输出或长期持久化 Chain of Thought。
+- 不向 Agent 暴露 Redis、canonical key、完整 Tool 请求/响应或数据库凭据。
+- EvidenceGuard 只接受当前 Run 的 READY canonical invocation。
+- SemanticGuard 无 Tool、无记忆、无回调主 Agent 能力。
+- technical failure 与 guard rejection 只能产生 stable failure 或固定 safe fallback。