docs: reorganize MVP interview documentation

interview/design-tradeoffs.md

@@ -1,99 +1,107 @@
-# Design Tradeoffs
+# 关键设计取舍
 
-## 1. 为什么要做 trace，而不是只返回答案
+## 1. 为什么先做 Trace，而不是只返回答案
 
-普通 Chatbot 只关注最终回答，但故障诊断更需要可审计性。一次诊断至少要回答三件事：
+普通 Chatbot 只关注最终回答，但故障诊断更需要可审计性。一次诊断至少要回答：
 
-- 结论是什么
-- 证据来自哪里
-- 哪些步骤由哪个 Agent 完成
+- 结论是什么。
+- 证据来自哪里。
+- 哪些步骤由哪个 Agent 完成。
+- 如果答案不可靠，系统怎么降级。
 
 因此项目把一次会话拆成：
 
-- `diagnosis_session`：会话级摘要、最终答案、质量评估、反馈。
-- `agent_step`：Agent 模型输入输出、耗时、token 和工具调用标记。
+- `diagnosis_session`：会话摘要、最终答案、自评估、用户反馈。
+- `agent_step`：模型输入输出、耗时、token 和工具调用标记。
 - `tool_invocation`：真实工具调用参数、输出预览、成功状态和检索元数据。
 
-这个设计牺牲了一些实现复杂度，但换来了可回放、可调试、可演示。
+代价是实现复杂度上升，收益是可回放、可调试、可演示。
 
-## 2. 为什么 Chat 有 Verifier，AIOps 暂时没有
+## 2. 为什么 RAG 不直接隐藏在 Advisor 里
 
-Chat 入口的问题更开放，用户可能要求复杂推理或跨领域结论，所以 Verifier 是必要的质量门。当前 Chat 链路通过 `Planner -> Executor -> Verifier` 固定流程，把 groundedness 和 facts checked 写入 `self_evaluation`。
+Spring AI Advisor 可以让 RAG 更隐式，但本项目的核心是 Agent 证据链。`lookup_knowledge` 必须作为显式工具调用出现，这样 Trace 里才能看到：
 
-AIOps 当前阶段先不加 Verifier，原因是：
+- Agent 什么时候决定检索。
+- 用了什么 query。
+- 命中了哪些文档。
+- 相关性等级是什么。
+- 证据如何支撑最终答案。
 
-- AIOps 刚完成从“自动跑告警”到“可追踪告警入口”的改造。
-- 先要确认告警 payload、工具证据、最终报告和 trace 能闭环。
-- AIOps Verifier 的规则不同于 Chat Verifier，需要检查告警 scope、证据覆盖和处置建议，不宜直接复用。
-
-后续可以做 lightweight AIOps Verifier，检查报告是否聚焦 payload、是否引用工具证据、是否误展开无关告警。
-
-## 3. 为什么 AIOps payload scope 先用 prompt 控制
-
-运行验证发现：传入 `HighCPUUsage/payment-service` 后，Agent 仍可能把 mock Prometheus 返回的所有 active alerts 都展开分析。这个问题的本质是任务边界不清晰。
-
-当前选择 prompt-level scope control：
-
-- 有 payload：`PAYLOAD_TARGETED`，最终报告围绕传入告警。
-- 无 payload：`AUTO_DISCOVERY`，先调用 `queryPrometheusAlerts` 自动发现告警。
-
-没有先做 Java 侧过滤，是因为：
-
-- 过滤工具结果会降低 Agent 发现关联风险的能力。
-- 目前需要的是报告主线聚焦，而不是完全屏蔽上下文。
-- Prompt 改动小，风险低，能保留 Agent 灵活性。
-
-已验证结果：主报告有 `HighCPUUsage/payment-service` 的完整根因分析，`HighMemoryUsage` 和 `SlowResponse` 只作为相关风险出现。
-
-## 4. 为什么用 `tool_invocation` 统计真实工具调用次数
-
-早期可以通过 `agent_step.hasToolCall` 粗略判断是否调用工具，但它统计的是“哪些模型步骤包含工具调用”，不是“真实调用了几次工具”。
-
-现在 `tool_call_count` 来自：
+所以当前设计是：
 
 ```text
-ToolInvocationRepository.countBySessionId(sessionId)
+Executor -> lookup_knowledge -> VectorSearchService -> VectorStore / SDK fallback
 ```
 
-这样更符合 trace 语义：
+这牺牲了一点框架自动化，但保留了可审计性。
 
-- 一个 step 可能调用多个工具。
-- 工具可能来自不同来源：知识库、日志、指标、Prometheus。
-- 面试时可以把 `tool_call_count` 和 trace 中返回的工具明细对上。
+## 3. 为什么 L0 只做 hint，不直接返回
 
-## 5. 为什么保留 mock Prometheus 和 mock CLS
+旧版 L0 关键词唯一命中时可能直接跳过 L1。这个策略速度快，但风险是：关键词子串命中不等于最终语义相关。
 
-面试 Demo 最怕不稳定。真实 Prometheus、日志平台和线上故障都有不可控因素，所以 MVP profile 保留 mock 工具：
+当前改成：
 
-- `prometheus.mock-enabled=true`
-- `cls.mock-enabled=true`
+```text
+L0 = domain/entity hint
+L1 = semantic retrieval
+postprocess = evidence shaping + trace
+```
 
-这样可以稳定复现：
+L0 仍然有价值：错误码、服务名、告警名、指标名都很适合做精确 hint。但最终证据仍需要 L1 和后处理支撑。
 
-- `HighCPUUsage/payment-service`
-- `HighMemoryUsage/order-service`
-- `SlowResponse/user-service`
-- system-metrics、application-logs、database-slow-query 等日志证据
+## 4. 为什么保留 Milvus SDK fallback
 
-这不是逃避真实集成，而是把“Agent 编排和证据追踪”作为面试演示的主目标。
+Spring AI VectorStore 是当前读路径主方向，但 SDK fallback 没有删除，原因有三点：
 
-## 6. 为什么把面试材料单独放 `interview/`
+- 迁移安全：旧 SDK 路径已经被验证过。
+- 运行韧性：VectorStore 配置、schema、collection 出问题时可以回退。
+- 面试稳定：检索抽象迁移不应该破坏主 demo。
 
-`mvp/` 是持续迭代现场，包含过程文档、验收记录和 runbook。面试材料的目标不同，它应该是可讲、可演示、可评估的展示层。
+这不是“没有迁完”，而是分阶段迁移：先稳定读路径，再决定是否迁移写入和索引。
 
-因此：
+## 5. 为什么 Chat 有 Verifier，AIOps 先用规则评估
 
-- `mvp/` 保留真实演进材料。
-- `devflow/` 保留决策沉淀。
-- `interview/` 只组织面试叙事和演示脚本。
+Chat 问题更开放，容易出现跨领域推理，所以需要 LLM Verifier 做 groundedness 校验。
 
-这样后续继续做 AIOps Verifier、UI、更多工具集成时，不会污染面试讲稿。
+AIOps 当前优先解决更具体的问题：
 
-## 7. 可以主动承认的限制
+- 最终报告是否存在。
+- payload 模式是否聚焦输入告警。
+- 是否使用了证据工具。
+- 是否把无关活跃告警展开成主根因。
 
-- AIOps 还没有 Verifier。
-- Prompt-level scope control 不能做到强约束，只能通过 trace 和测试观察遵循情况。
-- 当前 mock 数据适合 demo，不代表生产接入已经完成。
-- Hikari 连接池已经加了短生命周期和 keepalive，但真实生产还需要按数据库 wait_timeout 和连接数预算调优。
+这些用规则就能稳定检查。后续可以在同一个 `self_evaluation` 容器下增加 AIOps LLM Verifier。
+
+## 6. 为什么 AIOps payload scope 先用 Prompt + Rule
+
+真实告警环境里可能同时有多个 active alerts。用户传入 `HighCPUUsage/payment-service` 时，Agent 如果把所有告警都展开分析，报告会跑偏。
+
+当前选择：
+
+- Prompt 中加入 `PAYLOAD_TARGETED`。
+- 从 payload 生成 recommended `lookup_knowledge` query。
+- 用 `AiOpsRuleEvaluationService` 检查报告是否聚焦输入告警。
+
+没有先做硬过滤，是因为有些相关告警可以作为风险背景。目标不是屏蔽上下文，而是控制主诊断对象。
+
+## 7. 为什么反馈不改 status
+
+`status` 表示执行状态，`feedback` 表示用户评价。一个执行成功但用户觉得没用的诊断，应该是：
+
+```text
+status = SUCCESS
+feedback = not_useful
+```
+
+这样才能区分系统异常和质量问题。`useful` 反馈会沉淀 `case_library`，`not_useful` 作为 bad case 信号保留。
+
+## 8. 可以主动承认的限制
+
+- AIOps 还没有完整 LLM Verifier。
+- RAG 还没有 hybrid search、rerank、邻居 chunk 扩展。
+- `case_library` 的 rootCause/solution 仍需要结构化抽取。
+- `tool_invocation.step_id` 关联还可以更严格。
+- `mvp-demo` profile 使用 mock 日志和指标，主要服务稳定面试演示。
+
+主动讲清这些限制，能体现工程判断：先把可追踪闭环打通，再逐步增强质量门和生产可靠性。
 
-主动讲清这些限制，反而能体现工程判断：先把可追踪闭环打通，再逐步增强质量门和生产可靠性。