# Modular RAG Pipeline — Acceptance

## 验收状态

状态：通过，OpenSpec 已归档。

任务完成：

- OpenSpec tasks：31/31 完成。
- Review 后新增去重边界修复和回归测试。
- OpenSpec archive：`openspec/changes/archive/2026-07-06-modular-rag-pipeline`。

## 静态验证

```powershell
openspec validate modular-rag-pipeline --strict
```

结果：

```text
Change 'modular-rag-pipeline' is valid
```

```powershell
git diff --check
```

结果：

```text
PASS
```

说明：仅出现 Windows LF/CRLF warning，无 whitespace error。

## 脚本验证

```powershell
mvn -q -DskipTests compile
```

结果：PASS。

```powershell
mvn -q "-Dtest=LookupKnowledgeToolTest,ToolInvocationRecorderTest" test
```

结果：PASS。

覆盖：

- filtered L1 成功不 retry。
- filtered L1 低质量触发 raw unfiltered retry。
- filtered L1 无 evidence 触发 raw unfiltered retry。
- L0 hint 不作为 standalone fact evidence。
- 无 L0 hint 时直接 unfiltered vector search。
- rerank 使用 hint match 并记录 trace。
- context pack 保留 source/title/breadcrumb/hit reasons。
- evidence blocks 按 source 去重。
- session dedup 不再返回可消费 evidence/context。
- recorder 记录 retrieval trace、rerank trace、context pack summary 和 evidence summaries。

```powershell
$env:MILVUS_TOKEN = <application.yml 中的 milvus.token>; mvn -q test
```

结果：PASS。

说明：

- `MilvusConnectionTest` 需要 `MILVUS_TOKEN` 环境变量，直接读 `System.getenv`，不会自动读 `application.yml`。
- 注入该环境变量后完整测试通过。

## 实现验收

已验证行为：

- `LookupKnowledgeTool` 已变为 pipeline orchestrator。
- `LookupResult` 新契约包含 `evidenceBlocks`、`contextPack`、`retrievalTrace`、`rerankTrace`。
- 旧 `primary/supplement` 字段和 DTO 已删除。
- `ToolInvocationRecorder` 不再依赖 `result.getPrimary()`。
- filtered retrieval 失败时会记录 `filtered_vector_no_evidence` 或 `filtered_vector_low_quality`。
- no-evidence 情况返回 `found=false` 且保留 retrieval trace。
- session dedup 情况返回 `found=false` 且 evidence/context 为空。

## 未验证项

人工 Demo 未执行：

- 还没有通过真实 Chat/AIOps 会话观察 Agent 是否稳定按 `contextPack.packedText` 和 `evidenceBlocks` 引用证据。

风险：

- 工具 JSON 契约是 L4 breaking change，prompt 已更新，但真实对话行为仍建议做一次端到端 demo。

## 后续建议

- 增加一组 RAG eval cases，固定 query、期望 evidence source、期望 fallback path。
- 将 `MilvusConnectionTest` 改成 Spring 配置驱动或 integration profile，避免配置源混用。
- 后续可在评测数据足够后再考虑 model-based rerank 或 hybrid retrieval。