zhuyongxin
8bd758dbaf
创建 Phase 1 基础设施搭建的完整 devflow 文档： - brief.md: 项目背景、目标、范围、技术选型、关键决策 - decisions.md: 6 个架构决策记录 (ADR) - ADR-001: Flyway 数据库版本管理 - ADR-002: 枚举类型存储为 VARCHAR - ADR-003: Redis JSON 序列化 - ADR-004: Spring Data JPA 命名约定 - ADR-005: 会话 TTL 可配置 - ADR-006: 包名暂时混用 - evidence.md: 测试证据、性能指标、编译验证、数据库结构 - 27 个测试全部通过 - 性能指标达标 - 提交记录追踪 - acceptance.md: 验收标准、测试结果、遗留问题 - 20/33 任务完成 - 部分验收通过 更新全局文档： - devflow/index.md: 新增 phase1-infrastructure 项目索引 - devflow/glossary/CONTEXT.md: 新增 8 个术语和 4 条业务规则 Progress: 20/33 tasks completed (61%)
5.5 KiB
5.5 KiB
上下文词汇表
术语
ChatModel
- 定义：Spring AI 的聊天模型抽象接口，所有 LLM 提供商（DashScope、OpenAI、Ollama 等）都实现此接口
- 使用场景：所有需要 LLM 推理/生成回答的代码应面向此接口编程
EmbeddingModel
- 定义：Spring AI 的文本向量化抽象接口，将文本转换为向量
- 使用场景：RAG 流程中将文档文本转为向量存入 Milvus
DashScopeChatModel
- 定义：DashScope（阿里云）对 ChatModel 的具体实现
- 使用场景：当前项目硬编码使用，需要改为通过 ChatModel 接口引用
ReactAgent
- 定义：Spring AI Alibaba Agent Framework 的反应式 Agent 实现
- 使用场景：Planner-Executor-Replanner 多 Agent 协作
Spring AI Alibaba Agent Framework
- 定义：基于 Spring AI 的多 Agent 协作框架，提供 ReactAgent、PlannerAgent、ExecutorAgent 等
- 使用场景：项目核心 Agent 逻辑，ReactAgent.builder().model() 接受 ChatModel 接口
DeepSeekChatModel
- 定义：Spring AI 原生 DeepSeek 实现（
spring-ai-starter-model-deepseek），非 OpenAI 兼容模式 - 使用场景：Chat → DeepSeek V4 Flash/Pro，支持 reasoning_content
- 配置前缀：
spring.ai.deepseek.*
ModelRoutingConfig
- 定义：项目自定义配置类，yml 关键字驱动的
@Primary路由 - 使用场景：多厂商 starter 并存时，通过
model-routing.chat/model-routing.embedding声明启用哪个模型 - 路由策略：
Map<String, EmbeddingModel>按 Bean 名匹配List<ChatModel>按类名匹配- 未匹配则回退到第一个
- 示例：
model-routing.chat: deepseek→ 选中类名含DeepSeek的 Bean
SiliconFlow
- 定义：硅基流动 AI 平台，提供 OpenAI 兼容 API，项目用它跑 BGE-M3 embedding
- 配置：
siliconflow.*（自定义配置前缀），base-url =https://api.siliconflow.cn - model:
BAAI/bge-m3，1024 维
BGE-M3
- 定义：BAAI 开源的多语言 embedding 模型，1024 维输出
- 使用场景：通过 SiliconFlow API 调用，替代 DashScope text-embedding-v4
- 维度兼容：1024 = 原 DashScope text-embedding-v4，Milvus 无需重建
DiagnosisRecord
- 定义：诊断记录实体类，存储每次 Agent 诊断任务的完整记录
- 表名：diagnosis_record
- 主键：id (自增 BIGINT)，唯一标识：diagnosis_id (UUID)
- 关联字段：session_id（Redis 会话）、business_id（业务标识）、trace_id（链路追踪）
- 故障分类：fault_category、fault_source、fault_target
- 诊断结果：root_cause（根因）、solution（方案）、report_markdown（完整报告）
- 使用场景：持久化诊断结果，支持历史查询和案例提取
CaseLibrary
- 定义：案例库实体类，存储高质量诊断案例
- 表名：case_library
- 来源类型：AUTO（自动生成）、MANUAL（人工录入）
- 引用追踪：reference_count（被推荐次数）
- 使用场景：相似案例推荐、知识沉淀
ApiDocument
- 定义：API 文档元数据实体类，管理接口文档的元信息
- 表名：api_document
- 文件去重：file_hash（MD5 hash）
- 索引状态：PENDING（待处理）、PROCESSING（处理中）、INDEXED（已索引）、FAILED（失败）
- 关联：doc_id 关联 Milvus 中的文档向量
- 使用场景：文档上传、检索、版本管理
SessionContext
- 定义：会话上下文数据类，存储在 Redis 中的会话数据
- 包含字段：sessionId、userId、businessId、traceId、status、toolCalls、TTL
- 序列化方式：JSON（GenericJackson2JsonRedisSerializer）
- 使用场景：多轮对话上下文管理、工具调用历史追踪
ToolCall
- 定义：工具调用记录数据类，追踪 Agent 使用的工具及其结果
- 包含字段：toolName、arguments、result、status、duration、calledAt
- 使用场景：诊断过程可观测性、调试、复现
SessionManager
- 定义：会话管理器接口，定义会话的 CRUD 操作
- 实现：RedisSessionManager（基于 RedisTemplate）
- 核心方法：createSession、getSession、updateSession、deleteSession、refreshSession、addToolCall
- 使用场景：分布式会话管理、Agent 状态维护
Flyway
- 定义：数据库版本迁移工具，管理 SQL 脚本的版本化执行
- 配置：spring.flyway.enabled=true, baseline-on-migrate=true
- 迁移路径：src/main/resources/db/migration/
- 命名约定：V{version}__{description}.sql（如 V001__create_diagnosis_record.sql）
- 使用场景：数据库表结构版本管理、多环境部署
业务规则
- ChatModel 是唯一 LLM 调用抽象：替换模型只需更换 Spring Boot starter 和配置
- EmbeddingModel 是唯一向量化抽象：替换向量模型只需更换 starter 和配置
- ReactAgent 已兼容 ChatModel 接口，不绑定 DashScope
- base-url 只写 host（如
https://api.deepseek.com），不写版本路径（如/v1），Spring AI 会自动追加 - 多 starter 并存时，必须通过
@Primary或@Qualifier指定默认 Bean - Milvus collection 启动时必须
loadCollection()，否则搜索报collection not loaded - 枚举类型在数据库中存储为 VARCHAR，JPA 使用
@Enumerated(EnumType.STRING)+columnDefinition = "VARCHAR" - JPA ddl-auto 使用
validate模式，表结构修改必须通过 Flyway 迁移脚本 - Redis 会话 TTL 由调用方指定，不同场景使用不同过期时间（短诊断 5 分钟，长会话 1 小时）
- Repository 查询方法遵循 Spring Data JPA 命名约定，复杂查询使用
@Query