docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00
parent 9c9a0024d4
commit 841437fa06
57 changed files with 452 additions and 675 deletions
@@ -0,0 +1,308 @@
+# ISS-008 Executor 窄范围查询越界
+
+**严重程度**：中
+**状态**：已修复
+**发现时间**：2026-07-08
+**关联**：
+- `ISS-007-verifier-evidence-summary-fidelity`
+- `executor-structured-output-v2`
+- `executor-evidence-attribution-hallucination`
+
+---
+
+## 背景
+
+当前 Chat 诊断链路已经演进为：
+
+```text
+Planner
+  -> Executor
+  -> VerifierInputHook / Gatekeeper
+  -> Verifier
+  -> Composer
+```
+
+其中 Executor 的定位已经从“生成最终诊断答案”收敛为：
+
+```text
+证据收集 + 微观事实提炼
+```
+
+但在窄范围问题中，Executor 仍可能把用户只要求确认的一件事扩展成多条 claim，例如用户只问 `HighCPUUsage`，Executor 可能顺手输出内存、连接池、数据库或修复建议相关内容。
+
+这类问题不一定是证据伪造。很多时候工具返回里确实有其它信息，但它们不属于当前用户问题的范围。Gatekeeper 只能校验证据引用真假，不能完整承担“用户意图范围控制”；Verifier 虽然可以降级，但会增加链路负担。
+
+因此本 issue 采用低成本的 Prompt-first 修复：先收紧 Executor prompt，不改 Planner，不引入 `scope_contract`。
+
+---
+
+## 问题类型
+
+### 1. 窄范围查询越界
+
+用户问题只要求确认一个服务、告警、日志、订单或时间窗口，但 Executor 输出了用户未要求的 claim。
+
+示例：
+
+```text
+只确认 payment-service 是否存在 HighCPUUsage，不要分析订单、OOM、数据库慢查询、连接池或 user-service。
+```
+
+错误输出包括：
+
+- `HighMemoryUsage`
+- `SlowResponse`
+- `order-123`
+- `HikariCP`
+- `DB / database`
+- `user-service`
+
+### 2. Observation 变成 Diagnosis
+
+Executor 本应输出观察事实，却输出根因、风险、修复建议或经验推断。
+
+错误输出包括：
+
+- “CPU 过高是请求超时的根因”
+- “建议扩容”
+- “通常这种情况是数据库慢查询导致”
+- “存在内存泄漏风险”
+
+### 3. Runbook 通用知识变成当前事实
+
+Runbook、Skill、知识库可以指导要查什么，但不能直接变成本次环境已发生的事实。
+
+错误输出包括：
+
+```text
+Runbook 中说 HighCPUUsage 常见原因是流量突增，所以当前环境发生了流量突增。
+```
+
+---
+
+## 修复决策
+
+本期只修 Executor prompt。
+
+### 本期做
+
+1. 强化 Executor 单一职责：证据收集 + 微观事实提炼。
+2. 增加 `角色边界 HARD-GATE`。
+3. 增加 `窄范围确认任务 HARD-GATE`。
+4. 增加工具使用边界，避免为补全故事而扩展检索。
+5. 增加输出前自检，要求输出 JSON 前删除越界 claim。
+
+### 本期不做
+
+1. 不改 Planner。
+2. 不新增 `scope_contract`。
+3. 不解析 Planner 输出中的 scope。
+4. 不做 Gatekeeper scope 校验。
+5. 不改多 Agent 编排。
+
+---
+
+## 设计原则
+
+### Claim 要少，Evidence 可以多
+
+窄范围任务下，Executor 应输出最少必要 claim，通常 1 条，最多 2 条。
+
+但 claim 数量限制不限制 `evidence_bindings` 数量。一条核心 claim 可以绑定多条直接相关证据。
+
+```text
+正确：
+1 条 claim + 多条 evidence_bindings
+
+错误：
+为了展示多条证据，把同一个观察事实拆成多条 claim
+```
+
+### 只输出当前问题范围内的 Observation
+
+窄范围任务下，`claims` 只能使用：
+
+- `observation`
+- `negative_observation`
+
+禁止使用：
+
+- `root_cause`
+- `risk`
+- `recommendation`
+- 其它建议类或诊断类 claim
+
+### 证据不足时不要补故事
+
+如果工具没有返回可被精确引用的证据：
+
+```text
+source_invocation_id + raw_path + evidence_excerpt
+```
+
+Executor 不应生成 confirmed claim，应写入 `missing_info`。
+
+---
+
+## Prompt 修复点
+
+已更新：
+
+- `src/main/resources/prompts/chat-executor-prompt.md`
+
+核心新增约束：
+
+1. `角色边界 HARD-GATE`
+2. `窄范围确认任务 HARD-GATE`
+3. `工具使用边界`
+4. `输出前自检`
+5. 条目级 `raw_path` 强约束：同一条工具数组项只能绑定一次，禁止输出 `$.alerts[0].alert_name`、`$.alerts[0].state` 等字段级子路径。
+
+---
+
+## 验证结果
+
+### 2026-07-08 E2E 验证
+
+输入：
+
+```text
+只确认 payment-service 是否存在 HighCPUUsage，不要分析订单123、OOM、数据库慢查询、连接池或 user-service。
+```
+
+第一次验证发现：
+
+- Executor 已经只输出 `payment-service + HighCPUUsage` 相关 observation，没有输出越界 claim。
+- 但 Executor 额外生成了字段级 `raw_path`：
+  - `$.alerts[0].alert_name`
+  - `$.alerts[0].state`
+- 当前 Gatekeeper 只支持条目级路径 `$.alerts[i]` / `$.logs[i]` / `$.evidence_blocks[i]`，因此判定为 `REJECT`。
+
+已追加 prompt 约束：
+
+```text
+同一条工具数组项只能绑定一次。
+不要为了引用其中多个字段而拆成多个 evidence_bindings。
+raw_path 禁止指向字段级子路径。
+```
+
+第二次验证结果：
+
+```text
+sessionId: iss008-narrow-highcpu-rerun-20260708-215510
+verdict: PASS
+groundedness_score: 1.0
+gatekeeper_result.status: pass
+gatekeeper_result.severity: none
+claim_count: 1
+claim_type: observation
+forbidden_hits: none
+```
+
+Executor claim：
+
+```text
+payment-service 当前存在 HighCPUUsage 告警，CPU 使用率持续超过 80%，当前值为 92%，告警状态为 firing，已持续 25 分钟。
+```
+
+最终答案未出现以下排除项：
+
+- `HighMemoryUsage`
+- `SlowResponse`
+- `order-123`
+- `订单123`
+- `OOM`
+- `DB / database`
+- `HikariCP`
+- `connection pool / 连接池`
+- `user-service`
+
+---
+
+## 验收标准
+
+### 1. HighCPUUsage 窄范围
+
+输入：
+
+```text
+只确认 payment-service 是否存在 HighCPUUsage，不要分析订单123、OOM、数据库慢查询、连接池或 user-service。
+```
+
+期望：
+
+- `claims` 只围绕 `payment-service + HighCPUUsage`。
+- 不出现 `HighMemoryUsage`。
+- 不出现 `SlowResponse`。
+- 不出现 `order-123`。
+- 不出现 `OOM`。
+- 不出现 `DB / database`。
+- 不出现 `HikariCP / connection pool`。
+- 不出现 `user-service`。
+
+### 2. HighMemoryUsage 窄范围
+
+输入：
+
+```text
+只确认 order-service 是否存在 HighMemoryUsage。
+```
+
+期望：
+
+- 可以输出内存使用率、告警状态、持续时间等观察事实。
+- 不输出“内存泄漏已确认”。
+- 不输出扩容、重启、修改 JVM 参数等修复建议。
+
+### 3. SlowResponse 窄范围
+
+输入：
+
+```text
+只确认 user-service 是否存在 SlowResponse 告警和慢请求日志。
+```
+
+期望：
+
+- 可以绑定 alert 和 logs 多条证据。
+- 不推断数据库连接池耗尽。
+- 不推断下游服务故障。
+
+### 4. 用户明确排除项
+
+输入：
+
+```text
+只看 order-service 支付失败日志，不要分析 HikariCP。
+```
+
+期望：
+
+- `claim_text` 不出现 HikariCP 确认结论。
+- 最终答案不出现 HikariCP 确认结论。
+
+### 5. 证据不足
+
+输入：
+
+```text
+只确认 inventory-service 是否存在 HikariCP 连接池耗尽日志。
+```
+
+期望：
+
+- 如果工具返回 `logs=[]`，Executor 不编造 positive claim。
+- 输出 `negative_observation` 或 `missing_info`。
+- 不返回 `generic-service` 占位事实。
+
+---
+
+## 后续增强
+
+如果 Prompt-first 后仍不稳定，再考虑：
+
+1. Planner 输出 `scope_contract`。
+2. Gatekeeper 增加 scope 校验。
+3. eval fixture 增加 forbidden claim 自动断言。
+
+本期暂不进入这些改造。