SuperBizAgent-java/mvp/architecture/README.md

MVP 架构文档

更新日期：2026-07-20

这里是 MVP 当前架构的唯一入口。旧版设计、早期拆解和已经被新实现替代的方案已归档到：

• mvp/architecture/archive/2026-07-05-legacy/

归档材料只作为设计历史阅读，不再作为当前实现依据。

当前文档

文档	用途
current-mvp-architecture.md	当前可运行 MVP 的总体架构、链路、持久化和质量门禁
stategraph-runtime-architecture.md	最新复杂 Chat StateGraph 运行时权威快照，覆盖 Node 路由、状态边界、Run/Trace 持久化和验收层次
interview-one-pager.md	面试一页式架构讲解，包含总图、亮点、取舍和追问回答
agent-orchestration.md	Agent 编排细节，覆盖 Chat bounded StateGraph、AIOps SupervisorAgent、工具边界
executor-evidence-pipeline-refactor.md	Chat 证据链路当前数据契约，覆盖 Executor V2、Gatekeeper、Verifier、Composer、evidence_refs
harness-quality-gates.md	Prompt、StateGraph、Trace、Gatekeeper、Verifier、Composer、评测基线组成的质量门禁
rag-architecture.md	RAG/知识检索新架构，覆盖 L0 hint、VectorStore 主路径、SDK fallback、证据追踪
modular-rag-pipeline.md	lookup_knowledge 模块化 RAG 落地架构，覆盖 pipeline、fallback、evidence-first contract、trace
rag-eval-closure.md	RAG 评测闭环，覆盖 offline baseline、baseline diff、diagnosis eval 和 live acceptance
retrieval-observability.md	检索运行细节和可观测性，覆盖 L0/L1、去重、分数归一、评测
feedback-architecture.md	反馈与自评估闭环，覆盖 rule evaluation、Verifier、AIOps rule、用户反馈和案例沉淀
session-trace-lifecycle.md	会话和 Trace 生命周期，覆盖 sessionId、状态流转、agent_step、tool_invocation、Trace API
knowledge-base-authoring.md	知识库文档编写与维护规范，覆盖 frontmatter、category、chunk、reindex
data-model.md	数据模型总览，覆盖 Trace、知识库、反馈沉淀和 Milvus metadata
evolution-roadmap.md	从旧版 Agent 蓝图继承的后续演进路线，不代表当前已实现

当前架构一句话

SuperBizAgent MVP 是一个面向故障诊断的可追踪 Agent 系统：复杂 Chat 由有界 StateGraph 显式编排 Planner、Executor、Gatekeeper、Verified Input、Verifier、Composer 与安全 Fallback，Executor 通过工具收集日志、指标和知识库证据；多轮会话元数据落到 chat_session，每次诊断运行落到 diagnosis_run，步骤和工具明细通过 run_id 关联，Graph 路由摘要独立保存为 orchestration_trace，最终通过精确 Run Trace API 和评测脚本证明诊断链路可解释、可回放、可对比。

阅读顺序

1. 先读 current-mvp-architecture.md，理解系统边界和主链路。
2. 再读 stategraph-runtime-architecture.md，理解复杂 Chat 的真实运行时和路由边界。
3. 面试前读 interview-one-pager.md，准备 2-5 分钟讲解。
4. 再读 agent-orchestration.md，理解当前 Agent 如何协作。
5. 接着读 executor-evidence-pipeline-refactor.md，理解 Chat 证据链路的数据结构和验真边界。
6. 然后读 harness-quality-gates.md，理解为什么系统可追踪、可验证。
7. 再读 rag-architecture.md，理解当前 RAG 为什么保留显式 lookup_knowledge，以及 Spring AI VectorStore 如何接入。
8. 继续读 modular-rag-pipeline.md，看 lookup_knowledge 的模块化落地和 evidence-first contract。
9. 再读 rag-eval-closure.md，看 RAG baseline 如何形成质量闭环。
10. 然后读 retrieval-observability.md，看检索细节和质量回归方式。
11. 再读 feedback-architecture.md，理解 self_evaluation、用户反馈和案例沉淀。
12. 按需读 session-trace-lifecycle.md、knowledge-base-authoring.md、data-model.md，补齐运行生命周期、知识库维护和数据关系。
13. 最后读 evolution-roadmap.md，区分后续演进和当前实现。
14. 需要追溯旧方案时，再进入 archive/2026-07-05-legacy/。