SuperBizAgent-java/devflow/glossary/CONTEXT.md

上下文词汇表

术语

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 表承载。

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 正文支撑。

Diagnosis Harness

• 定义：围绕 Diagnosis Agent 提供确定性运行控制的边界，负责 Run、预算、取消、重试装配、Tool 调用记录、证据验真和最终释放，不承担业务诊断推理。
• 边界：Harness 不是工作流引擎，不实现 Planner/Executor/Composer 节点或自行编写 ReAct 循环。

Diagnosis Agent

• 定义：诊断链路中唯一拥有 ReAct 工具循环并生成 DiagnosisDraft 的 Agent，负责规划证据查询、判断证据充分性和撰写完整诊断草稿。
• 边界：不负责意图路由、Run/Session 生命周期、证据物理验真、独立语义审查或最终发布；证据不足时必须明确停止并保留限制。

EvidenceGuard

• 定义：Harness 内部的确定性证据验真能力，校验 Draft 引用、当前 Run 所有权、Tool 调用状态和有界 Agent 投影。
• 边界：EvidenceGuard 不调用 LLM，也不判断证据是否足以推出业务结论。

SemanticGuard

• 定义：使用隔离上下文对完整诊断 Draft 与已验真证据做报告级语义审查的单轮 Agent。
• 边界：无工具、无记忆、无 ReAct 循环，不访问 Redis，不生成或改写用户报告。

Invocation Status

• 定义：Tool 调用及结果投影的生命周期状态，固定为 PROJECTING、READY、ERROR。
• 边界：它只说明调用记录是否完成，不说明结果是否包含证据。

Durable Audit

• 定义：为 Diagnosis Trace 长期保存的 Run、Agent 模型步骤和 Tool 调用元数据，用于 exact sessionId/runId 回放、评测和运维核对。
• 边界：只保存有界、脱敏、可长期保留的身份、状态、耗时、预算和结果摘要；不保存 Prompt、Thought、完整 Tool 参数、raw response 或 Redis canonical invocation。

Evidence Status

• 定义：证据 Tool 的结果语义，固定为 EVIDENCE_FOUND、NO_EVIDENCE、ERROR。
• 边界：EVIDENCE_FOUND 只表示存在候选内容，不保证内容能够支持当前诊断；NO_EVIDENCE 只表示当前查询范围内没有匹配结果，不能解释为问题不存在、根因被排除或系统健康。

Information Gain

• 定义：一次 Tool 结果是否推进当前 Diagnosis Run 的语义评价，固定为 GAINED 或 NO_GAIN。
• 边界：它评价的是结果对当前诊断的作用，不评价 Tool 产品质量；NO_EVIDENCE 和重复的规范化 tool + scope 可由 Harness 机械标记为 NO_GAIN，其他成功非空结果（包括 RAG REFERENCE）由模型评价。

Collection State

• 定义：Diagnosis Harness 对当前 Run 是否允许继续收集证据的控制状态，固定为 COLLECTING 或 SATURATED。
• 边界：状态由 Harness 维护；SATURATED 可因连续 NO_GAIN 或连续进展协议错误达到各自配置阈值而进入，不包括硬预算耗尽。模型可以请求新的 Tool 调用，但不能绕过 SATURATED。

Diagnosis Stop Reason

• 定义：Harness 停止当前 Run 继续调用 Tool 的内部原因，首版区分 INFORMATION_SATURATED、BUDGET_LIMIT_REACHED 与 PROGRESS_PROTOCOL_VIOLATED。
• 边界：它用于控制、Trace 和 Release 输入，不是用户可见生命周期状态，也不进入模型上下文；真正的不可恢复技术故障走失败通道。协议错误不累计为 NO_GAIN，使用独立阈值与 stop reason。

Progress Protocol Violation

• 定义：模型未遵守 Tool Call Envelope 进展协议时的安全错误分类，例如缺失/错序/意外 previous_observation、缺失 input 或非法 Envelope。
• 边界：返回可修正 observation（repair_required、violation_type、期望上一轮 Tool Call ID、允许的 information_gain）；连续错误达到阈值后交付一次 STOP_REQUIRED/PROGRESS_PROTOCOL_VIOLATED。不泄露业务参数、上一轮观察正文、raw response 或内部异常。

Progress Snapshot

• 定义：Tool Loop 结束时，从当前 Run 的 Canonical Tool Result 一次性投影出的有界发布视图，用于生成已检查范围和客观结果。
• 边界：Canonical Tool Result 是真理源；Progress Snapshot 不逐轮维护、不保存原始 Tool Response、Prompt 或内部 thought，也不直接进入模型上下文。

Safe Fallback Type

• 定义：SafeFallback.type 对没有发布诊断结论的业务原因分类，例如 INSUFFICIENT_EVIDENCE、MISSING_REQUIRED_CONTEXT、BUDGET_EXHAUSTED 或安全校验失败。
• 边界：它是 ReleaseOutcome.FALLBACK 的原因字段，不是与 SUCCESS / FALLBACK / FAILED / CANCELLED 平行的第二套生命周期状态。

Diagnosis Release Use Case

• 定义：诊断业务发布的唯一决策入口，接收 DiagnosisDraft 和/或 Harness stop_reason + ProgressSnapshot，生成安全的 SUCCESS / FALLBACK 结果。
• 边界：conclusion=null 不触发 EvidenceRepair；只有存在结论时才执行完整 EvidenceGuard、EvidenceRepair 和 SemanticGuard 链路。不可形成安全业务内容的技术故障由 Chat Application Use Case 映射为 FAILED / CANCELLED。

Diagnosis Draft Contract Failure

• 定义：Diagnosis Agent 最终文本为空、不是严格 JSON，或不满足 DiagnosisDraft Schema 时产生的 Agent 输出合同失败。
• 边界：非法文本始终丢弃，不做 Markdown/自然语言提取，也不调用模型修复；仅当当前 Run 的 ProgressSnapshot 含已验真 observed facts 时，Release 才能确定性发布 INSUFFICIENT_EVIDENCE，否则保持 FAILED。它不是 Diagnosis Stop Reason，不得伪装成信息饱和或预算终止。

Model Observation

• 定义：Tool 内部标准化结果经过白名单投影后，作为 Tool Response 进入 Diagnosis Agent 上下文的有界视图。
• 边界：只包含模型完成语义判断和证据引用所需的信息；预算、阈值、重复指纹、原始相似度、原始 Tool Response 和完整 Harness 控制状态不得进入该视图。

RunContext

• 定义：一次 Diagnosis Run 的显式执行上下文，结构不可变地携带 sessionId、runId、deadline，以及该 Run 独占的取消、预算、重试策略和生命周期状态句柄。
• 边界：RunContext 通过方法参数或框架受控 context 显式传播，不依赖 ThreadLocal；结构不可变不等于内部计数和取消状态不能变化，这些变化由线程安全句柄管理。

Run Lifecycle

• 定义：Diagnosis Harness 对单次 Run 执行状态的内存控制，采用 first-terminal-wins 规则保证成功、失败、取消、超时和预算耗尽只能产生一个最终终态。
• 边界：Run Lifecycle 不直接等同于数据库实体写入；应用用例负责把最终状态映射到 diagnosis_run 持久化。

Run Budget

• 定义：单次 Run 的模型调用、Tool 调用、单 Tool 调用、输入/输出/总 Token 和 canonical invocation 字节容量的线程安全消耗计数与门禁。
• 边界：预算上限由 Harness 配置显式提供；实际 Token 在模型响应后记录，超限后保留真实消耗并阻止后续执行。

Harness Retry Policy

• 定义：Harness 对同一技术操作 attempt 数和可重试失败类型的显式策略。
• 边界：Router 与 SemanticGuard 的技术失败最多两次 attempt；Diagnosis Agent、Tool 和 Evidence repair 只有一次 attempt。Agent 正常 ReAct 轮次不是 retry，NO_EVIDENCE、业务拒绝、取消和预算耗尽不可重试。

Chat Application Use Case

• 定义：一次 Chat 请求的唯一业务入口，拥有 Session/Run、意图路由、固定执行器、PreviousTurn 和最终持久化。
• 边界：不拥有 HTTP/SSE 连接，不把 ChatModel 或 Tool 选择权交给 Controller，也不在 Diagnosis Release Use Case 之外单独决定预算 Fallback 的业务内容。

Chat SSE Contract

• 定义：Chat 公开入口的五事件协议，顺序固定为 metadata -> status* -> content|failure -> done。
• 边界：过程状态实时发送，最终安全内容最多释放一次；它不是 Token streaming，也不包含内部计划、Prompt、raw Tool 数据或异常。

Verifier Skill Isolation

• 定义：Chat Verifier 与 skill 系统隔离，只校验 Executor 答案和 tool_trace_summary。
• 使用场景：防止 Verifier 把 playbook 指令当作事实证据；Verifier 只判断已有证据是否支持结论。
• 边界：Verifier 不接收 skill_catalog，不暴露 read_skill，不读取 SKILL.md。

Diagnosis Playbook Business Rules

• Planner 只看 skill metadata，输出 selected_skill、selection_reason 和 plan。
• Executor 才能调用 read_skill(selected_skill)，并且读取 skill 后仍必须调用 evidence tools。
• Skill 正文不得替代 lookup_knowledge、日志、指标或告警数据。
• Verifier 只基于 tool_trace_summary 校验事实，不基于 skill 正文校验事实。
• 当前阶段保留单 active skill 白名单：diagnose-mysql-connection-pool。