docs: add interview project materials

interview/design-tradeoffs.md

@@ -0,0 +1,99 @@
+# Design Tradeoffs
+
+## 1. 为什么要做 trace，而不是只返回答案
+
+普通 Chatbot 只关注最终回答，但故障诊断更需要可审计性。一次诊断至少要回答三件事：
+
+- 结论是什么
+- 证据来自哪里
+- 哪些步骤由哪个 Agent 完成
+
+因此项目把一次会话拆成：
+
+- `diagnosis_session`：会话级摘要、最终答案、质量评估、反馈。
+- `agent_step`：Agent 模型输入输出、耗时、token 和工具调用标记。
+- `tool_invocation`：真实工具调用参数、输出预览、成功状态和检索元数据。
+
+这个设计牺牲了一些实现复杂度，但换来了可回放、可调试、可演示。
+
+## 2. 为什么 Chat 有 Verifier，AIOps 暂时没有
+
+Chat 入口的问题更开放，用户可能要求复杂推理或跨领域结论，所以 Verifier 是必要的质量门。当前 Chat 链路通过 `Planner -> Executor -> Verifier` 固定流程，把 groundedness 和 facts checked 写入 `self_evaluation`。
+
+AIOps 当前阶段先不加 Verifier，原因是：
+
+- 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)
+```
+
+这样更符合 trace 语义：
+
+- 一个 step 可能调用多个工具。
+- 工具可能来自不同来源：知识库、日志、指标、Prometheus。
+- 面试时可以把 `tool_call_count` 和 trace 中返回的工具明细对上。
+
+## 5. 为什么保留 mock Prometheus 和 mock CLS
+
+面试 Demo 最怕不稳定。真实 Prometheus、日志平台和线上故障都有不可控因素，所以 MVP profile 保留 mock 工具：
+
+- `prometheus.mock-enabled=true`
+- `cls.mock-enabled=true`
+
+这样可以稳定复现：
+
+- `HighCPUUsage/payment-service`
+- `HighMemoryUsage/order-service`
+- `SlowResponse/user-service`
+- system-metrics、application-logs、database-slow-query 等日志证据
+
+这不是逃避真实集成，而是把“Agent 编排和证据追踪”作为面试演示的主目标。
+
+## 6. 为什么把面试材料单独放 `interview/`
+
+`mvp/` 是持续迭代现场，包含过程文档、验收记录和 runbook。面试材料的目标不同，它应该是可讲、可演示、可评估的展示层。
+
+因此：
+
+- `mvp/` 保留真实演进材料。
+- `devflow/` 保留决策沉淀。
+- `interview/` 只组织面试叙事和演示脚本。
+
+这样后续继续做 AIOps Verifier、UI、更多工具集成时，不会污染面试讲稿。
+
+## 7. 可以主动承认的限制
+
+- AIOps 还没有 Verifier。
+- Prompt-level scope control 不能做到强约束，只能通过 trace 和测试观察遵循情况。
+- 当前 mock 数据适合 demo，不代表生产接入已经完成。
+- Hikari 连接池已经加了短生命周期和 keepalive，但真实生产还需要按数据库 wait_timeout 和连接数预算调优。
+
+主动讲清这些限制，反而能体现工程判断：先把可追踪闭环打通，再逐步增强质量门和生产可靠性。