# 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 和连接数预算调优。

主动讲清这些限制，反而能体现工程判断：先把可追踪闭环打通，再逐步增强质量门和生产可靠性。