组件架构总览¶
本节把 Dubbo Admin AI 拆成几个真正可运行的组件来看，而不是按代码目录机械罗列。这样更容易回答三个问题：
- 这个组件解决什么问题？
- 它依赖谁，又被谁依赖？
- 修改它时最容易踩什么坑？
1. 当前组件地图¶
flowchart TD
Logger["logger"] --> Models["models"]
Memory["memory"] --> Agent["agent"]
Models --> RAG["rag"]
Models --> Tools["tools"]
RAG --> Tools
Tools --> Agent
Agent --> Server["server"]
2. 组件一览¶
| 组件 | 作用 | 典型依赖 | 对外提供 |
|---|---|---|---|
| Logger | 初始化全局日志 | 无 | 统一 slog 输出 |
| Memory | 保存短期对话历史 | 无 | 会话历史窗口 |
| Models | 初始化模型与 embedding 注册表 | Logger | Genkit Registry |
| RAG | 文档加载、切分、索引、检索、重排 | Models | 检索能力 |
| Tools | 聚合各种工具并导出 ToolRef | Models、Memory、RAG | 可调用工具集合 |
| Agent | 执行多阶段推理循环 | Tools、Memory、Models | 对话编排能力 |
| Server | 暴露 HTTP/SSE 接口 | Agent | API 服务 |
3. 组件之间不是“平铺”关系¶
它们形成的是一个典型的“能力逐层向上汇聚”的结构：
- 底层提供基础能力：Logger、Memory、Models
- 中层组合增强能力：RAG、Tools
- 上层负责编排和协议：Agent、Server
这种结构的好处是，一个问题通常能比较清楚地落到某一层。例如：
- SSE 不通是 Server 问题
- 工具注册异常是 Tools 问题
- 检索质量差往往是 RAG 配置或索引问题
- 对话“失忆”通常是 Memory 问题
4. 组件生命周期的一致性¶
所有组件都遵守 Validate -> Init -> Start -> Stop 这一套协议，所以看任意组件时，建议都按下面顺序读：
Validate()校验什么Init()初始化什么Start()是否启动服务Stop()是否释放资源
5. 设计约束¶
logger通过slog.SetDefault影响整个系统，不是局部 logger。memory是进程内状态，不持久化。models会初始化全局 Genkit Registry，属于“全局能力组件”。rag本身是复合组件，内部还拆成 loader、splitter、indexer、retriever、reranker。tools不只是一组函数，它承担“注册、发现、统一输出”的职责。agent不直接暴露 HTTP，而是通过 channel 把增量结果交给 server。server不负责业务推理，只负责协议层转换和会话管理。
6. 如何阅读下面这些页面¶
- 想先看基础组件：从 Logger、Memory、Models 开始。
- 想看增强能力：看 RAG 和 Tools。
- 想看端到端对话链路：看 Agent 和 Server。
组件详情见：