175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# 上下文词汇表
|
||
|
||
## 术语
|
||
|
||
### 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` 声明启用哪个模型
|
||
- 路由策略：
|
||
1. `Map<String, EmbeddingModel>` 按 Bean 名匹配
|
||
2. `List<ChatModel>` 按类名匹配
|
||
3. 未匹配则回退到第一个
|
||
- 示例：`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、messageHistory、TTL
|
||
- 序列化方式：JSON（GenericJackson2JsonRedisSerializer）
|
||
- 使用场景：多轮对话上下文管理、工具调用历史追踪
|
||
- 边界：messageHistory 是热路径对话历史缓存，用于下一轮 prompt 上下文；长期审计的问题和答案应落到 Diagnosis Run，而不是依赖 Redis TTL 内的上下文正文。
|
||
|
||
### ToolCall
|
||
- 定义：工具调用记录数据类，追踪 Agent 使用的工具及其结果
|
||
- 包含字段：toolName、arguments、result、status、duration、calledAt
|
||
- 使用场景：诊断过程可观测性、调试、复现
|
||
|
||
### SessionManager
|
||
- 定义：会话管理器接口，定义会话的 CRUD 操作
|
||
- 实现：RedisSessionManager（基于 RedisTemplate）
|
||
- 核心方法：createSession、getSession、updateSession、deleteSession、refreshSession、addToolCall
|
||
- 使用场景：分布式会话管理、Agent 状态维护
|
||
|
||
### Chat Session
|
||
- 定义：一次多轮对话上下文，由 `sessionId` 唯一标识。
|
||
- 使用场景：保存用户连续对话的上下文窗口、会话状态和最近活跃时间。
|
||
- 边界：Chat Session 不代表一次诊断执行；同一个 Chat Session 可以包含多次 Diagnosis Run。
|
||
|
||
### Diagnosis Run
|
||
- 定义：一次独立诊断执行，由 `runId` 唯一标识，属于一个 Chat Session。
|
||
- 使用场景：保存某一轮诊断的 query、answer、status、耗时、token、反馈和自评估结果。
|
||
- 边界：Diagnosis Run 是 Trace、Feedback 和 Evidence score 的绑定对象；多轮对话中的每次 `/api/chat` 或 `/api/ai_ops` 执行都应创建新的 Diagnosis Run。
|
||
|
||
### Diagnosis Trace
|
||
- 定义：一次 Diagnosis Run 的可回放执行轨迹，由 run 主记录、AgentStep 和 ToolInvocation 聚合形成。
|
||
- 使用场景：Trace API、Trace UI、Verifier 审计、评测 fixture 和人工排查。
|
||
- 边界：Diagnosis Trace 是聚合视图，不要求单独的 trace 主表；当前 trace 明细由 `agent_step` 和 `tool_invocation` 表承载。
|
||
|
||
### Diagnosis Orchestration Trace
|
||
- 定义：一次 Diagnosis Run 的紧凑编排审计摘要，记录实际节点路径、条件边原因、技术重试、降级和终止原因。
|
||
- 使用场景：解释诊断编排为何进入某个节点、为何重试或为何提前终止，并支撑路由验收和人工审计。
|
||
- 边界：它是 Diagnosis Trace 的编排维度，不是完整事件日志、自评估结果或持久恢复检查点；不保存 Prompt、模型思考、工具原文和完整编排上下文快照。
|
||
|
||
### 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`
|
||
|
||
## Diagnosis Playbook Skills
|
||
|
||
### Diagnosis Playbook Skill
|
||
- 定义：项目内可版本化的诊断流程包，存放在 `src/main/resources/skills/{skill-name}/SKILL.md`。
|
||
- 使用场景：把高频故障诊断流程从大 prompt / 知识库文档中抽出，形成可审查、可复用、可按需加载的 playbook。
|
||
- 边界：skill 只定义排查 workflow、证据顺序、停止条件、低置信度行为和报告规则；事实性知识仍放在 `knowledge_base/`，事实证据仍来自 evidence tools。
|
||
|
||
### SkillRegistry
|
||
- 定义：Spring AI Alibaba Agent Framework 的 skill 元数据和正文读取入口。本项目使用 `ClasspathSkillRegistry` 从 classpath `skills/` 加载 skill。
|
||
- 使用场景：统一提供 skill `name` / `description` 元数据，并支撑 Executor 通过官方 `read_skill` 读取完整 `SKILL.md`。
|
||
- 当前约束：`SkillConfig.SingleSkillRegistry` 临时只暴露 active skill `diagnose-mysql-connection-pool`，用于验证单 skill 流程和避免一次性注入全部 skill。
|
||
|
||
### PlannerSkillMetadataHook
|
||
- 定义：项目本地 hook，只向 Planner 注入结构化 `skill_catalog` 元数据。
|
||
- 使用场景：Planner 根据 skill `name` / `description` 选择 `selected_skill`，输出 `selection_reason` 和执行计划。
|
||
- 边界：Planner 不暴露官方 `read_skill` 工具，不读取完整 `SKILL.md`；Planner 只能选择 skill，不能执行 skill。
|
||
|
||
### SkillsAgentHook
|
||
- 定义：Spring AI Alibaba 官方 skill hook，会同时注入官方 Skills System prompt，并暴露 `read_skill` 工具。
|
||
- 使用场景：只挂到 Executor 和 single-agent Chat；Executor 根据 `planner_plan.selected_skill` 读取完整 playbook 后再调用证据工具。
|
||
- 边界：不要挂到 Planner，否则 Planner 会获得 `read_skill` 工具并可能读取完整 skill；Verifier 也不能挂该 hook。
|
||
|
||
### read_skill
|
||
- 定义：官方 skill 读取工具，参数为 `skill_name`，返回对应 `SKILL.md` 正文。
|
||
- 使用场景：Executor 在执行场景化诊断前读取 Planner 选中的 playbook。
|
||
- 边界：`read_skill` 是流程指导工具，不是事实证据工具；不应作为诊断事实写入 `tool_invocation` 证据链。
|
||
|
||
### Evidence Tools
|
||
- 定义：产生可验证诊断事实的工具集合，包括 `lookup_knowledge`、`query_logs`、`query_metrics`、告警/Prometheus 工具等。
|
||
- 使用场景：Executor 按 skill workflow 调用 evidence tools 收集事实，`tool_invocation` 记录这些事实证据。
|
||
- 边界：最终诊断结论必须被 evidence tools 支撑，不能仅由 skill 正文支撑。
|
||
|
||
### Verifier Skill Isolation
|
||
- 定义：Chat Verifier 与 skill 系统隔离，只校验 Gatekeeper 投影后的 `verified_executor_output` 和 `verified_evidence`。
|
||
- 使用场景：防止 Verifier 把 playbook 指令当作事实证据；Verifier 只判断已有证据是否支持结论。
|
||
- 边界：Verifier 不接收 `skill_catalog`，不暴露 `read_skill`，不读取 `SKILL.md`、完整 `tool_trace_summary` 或未经验真的 Executor 自由文本。
|
||
|
||
## Diagnosis Playbook Business Rules
|
||
|
||
- Planner 只看 skill metadata，输出 `selected_skill`、`selection_reason` 和 plan。
|
||
- Executor 才能调用 `read_skill(selected_skill)`，并且读取 skill 后仍必须调用 evidence tools。
|
||
- Skill 正文不得替代 `lookup_knowledge`、日志、指标或告警数据。
|
||
- Verifier 只基于 Gatekeeper 通过的 `verified_executor_output` 和 `verified_evidence` 校验事实，不基于 skill 正文、完整工具 Trace 或未验真输出校验事实。
|
||
- 当前阶段保留单 active skill 白名单：`diagnose-mysql-connection-pool`。
|