osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(mvp): move engineering notes under mvp/engineering

Browse Source 
Relocate RAG and diagnosis decision/E2E writeups from docs/ root into
mvp/engineering so architecture, issues, and engineering narrative stay
together. Update indexes and cross-links; leave docs/learning as legacy.
This commit is contained in:
zhuyongxin
2026-07-29 10:49:45 +08:00
parent bdac35567c
commit 584639fa2a
18 changed files with 155 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files
devflow/projects/2026-07-27-rag-chunk-evidence-identity-dedup/brief.md
+1 -1
View File
@@ -14,7 +14,7 @@ lookup_knowledge 同文档多 chunk 在后处理与投影阶段被 source 级去
## 范围 ## 范围
Delivery 1 only（见 `docs/Milvus-Hybrid接入清单.md` §1.1）。 Delivery 1 only（见 `mvp/engineering/rag/Milvus-Hybrid接入清单.md` §1.1）。
## 非目标 ## 非目标
devflow/projects/2026-07-27-rag-chunk-evidence-identity-dedup/decisions.md
+1 -1
View File
@@ -93,7 +93,7 @@ Reference files:
- `RagResultProjector.java` - `RagResultProjector.java`
- `LookupKnowledgeToolTest.java` - `LookupKnowledgeToolTest.java`
- `RagResultProjectorTest.java` - `RagResultProjectorTest.java`
- `docs/Milvus-Hybrid接入清单.md` - `mvp/engineering/rag/Milvus-Hybrid接入清单.md`
Stack notes: Stack notes:
devflow/projects/2026-07-27-rag-chunk-evidence-identity-dedup/evidence.md
+1 -1
View File
@@ -9,7 +9,7 @@
## 规格证据 ## 规格证据
- 旧 `openspec/specs/rag-knowledge-retrieval` 要求 source 级 dedup（本 change 以 delta 修正） - 旧 `openspec/specs/rag-knowledge-retrieval` 要求 source 级 dedup（本 change 以 delta 修正）
- `docs/Milvus-Hybrid接入清单.md` §1.1 定义 Delivery 1 地基 - `mvp/engineering/rag/Milvus-Hybrid接入清单.md` §1.1 定义 Delivery 1 地基
## 验证证据 ## 验证证据
docs/INDEX.md
+56 -101
View File
@@ -1,120 +1,75 @@
# 文档索引 # 文档索引
## 📂 目录结构 **更新日期**：2026-07-29
``` ## 目录结构
```text
docs/ docs/
├── README.md # 项目文档总览 ├── INDEX.md # 本索引
├── INDEX.md # 本索引文件 ├── learning/ # 早期学习笔记（可能过时）
│ ├── analysis/ # 早期代码/问题分析
├── learning/ # 📚 学习笔记（个人学习理解） ├── reports/ # 历史修复/验证报告
│ ├── 00-项目学习路径.md └── guides/ # 操作指南
│ ├── 01~08-*.md # 按学习顺序编号
│ └── README.md mvp/ # 现行 MVP 文档（主入口）
│ ├── architecture/ # 现行架构：系统现在怎么跑
├── analysis/ # 🔍 分析笔记（代码/问题分析） ├── engineering/ # 工程纪要：问题 / 决策 / E2E
│ ├── essence-report-*.md ├── issues/ # 未完成事项
│ ├── explore-report.md ├── tables/ # 表结构
│ ├── chunking-issues-analysis.md ├── demo/ # Demo
│ └── 功能分析报告.md └── eval/ # 诊断评测材料
│
├── reports/ # 📝 临时报告（修复/验证报告）
│ ├── 修复报告-*.md
│ ├── 验证报告-*.md
│ └── 日志配置完成总结.md
│
└── guides/ # 📖 指南文档
└── 日志配置与分析指南.md
``` ```
**⚠️ 注意：MVP 架构设计文档已移至项目根目录 `../mvp/`** **现行架构、工程纪要、表结构、Issue 均以 [mvp/README.md](../mvp/README.md) 为准。**
本目录 `learning/` / `analysis/` / `reports/` 偏早期学习与历史记录，**可能与当前实现不一致**。
查看 [mvp/README.md](../mvp/README.md) 了解 MVP 架构、数据库设计、实施计划等。
--- ---
## 🚀 快速导航 ## 快速导航
### 我是新人/学习者 ### 我是开发者（优先）
1. [项目学习路径](learning/00-项目学习路径.md) - 从这里开始
2. [learning/README.md](learning/README.md) - 学习笔记索引
3. 按编号顺序阅读 `learning/` 目录下的文档
### 我是开发者 1. [mvp/README.md](../mvp/README.md) — MVP 总入口
👉 **MVP 架构设计文档已移至 `../mvp/`** 2. [mvp/architecture/](../mvp/architecture/) — 现行架构
3. [mvp/engineering/](../mvp/engineering/) — 工程纪要（RAG / 诊断 E2E）
4. [mvp/issues/](../mvp/issues/) — 活跃 Issue
请查看 [mvp/README.md](../mvp/README.md) 了解： ### RAG 工程纪要（已迁入 mvp）
- MVP 架构设计
- 数据库设计和表结构
- 实施规划（Phase 1/2/3）
- 会话管理设计
### 我要查看分析报告 1. [RAG 排序：多路召回与 RRF](../mvp/engineering/rag/RAG排序-多路召回与RRF.md)
1. [分析笔记目录](analysis/) - 代码分析和问题分析 2. [Hybrid 之后的 qualityScore 与后处理](../mvp/engineering/rag/RAG-Hybrid质量分与后处理.md)
2. [临时报告目录](reports/) - 修复和验证报告 3. [Agent 如何读 relevance_level](../mvp/engineering/rag/RAG-Agent如何读relevance_level.md)
4. [RAG 离线评测：基线设计](../mvp/engineering/rag/RAG离线评测-基线设计.md)
5. [Milvus hybrid 接入清单](../mvp/engineering/rag/Milvus-Hybrid接入清单.md)
6. [RAG 审计补丁 E2E](../mvp/engineering/rag/RAG审计补丁-stepid-query-E2E验收.md)
7. 架构对照：[RAG 知识检索架构](../mvp/architecture/RAG知识检索架构.md)、[RAG 检索可观测性与审计](../mvp/architecture/RAG检索可观测性与审计.md)
### RAG 设计讨论（docs 根目录） ### 诊断全流程（已迁入 mvp）
1. [RAG 排序：多路召回与 RRF](RAG排序-多路召回与RRF.md) - K、融合、L0 边界
2. [Hybrid 之后的 qualityScore 与后处理](RAG-Hybrid质量分与后处理.md) - 上一代问题、L2 伪装、统一归一化
3. [Agent 如何读 relevance_level](RAG-Agent如何读relevance_level.md) - 粗相关度标签的含义与误读
4. [RAG 离线评测：讨论、设计与落地](RAG离线评测-基线设计.md) - Golden/Fixture、流程图、hybrid 对齐与闸门修复
5. [Milvus hybrid 接入清单](Milvus-Hybrid接入清单.md)
6. [RAG Trace / 审计（架构）](../mvp/architecture/RAG检索可观测性与审计.md) - 请求内 trace、tool_invocation、Trace API
### 诊断全流程（E2E 导读） 1. [一次诊断到底发生了什么](../mvp/engineering/diagnosis/一次诊断全流程-E2E导读.md)
1. [一次诊断到底发生了什么](一次诊断全流程-E2E导读.md) - SUCCESS 全流程：阶段拆解、token、timeline、字段词典
2. [RAG 审计补丁 E2E：step_id + query](RAG审计补丁-stepid-query-E2E验收.md) - 审计字段 live 验收（含业务 FALLBACK 样本） ### 我是新人 / 想看早期学习笔记
1. [项目学习路径](learning/00-项目学习路径.md)
2. [learning/README.md](learning/README.md)
3. 注意：内容可能过时，实现以 `mvp/architecture` 为准
### 分析 / 历史报告 / 指南
- [analysis/](analysis/) — 早期分析
- [reports/](reports/) — 历史修复与验证报告
- [guides/日志配置与分析指南.md](guides/日志配置与分析指南.md)
--- ---
## 📚 学习笔记 (learning/) ## 文档维护
按学习顺序编号，建议按顺序阅读： | 类型 | 位置 |
|---|---|
1. [00-项目学习路径](learning/00-项目学习路径.md) | 现行架构 | `mvp/architecture/` |
2. [01-AI-Ops-核心设计-Essence报告](learning/01-AI-Ops-核心设计-Essence报告.md) | 工程纪要（问题/决策/E2E） | `mvp/engineering/` |
3. [02-outputKey-深度解析](learning/02-outputKey-深度解析.md) | Issue | `mvp/issues/` |
4. [03-核心疑问解答](learning/03-核心疑问解答.md) | 表结构 | `mvp/tables/` |
5. [04-RAG-分块策略-Essence报告](learning/04-RAG-分块策略-Essence报告.md) | 早期学习 | `docs/learning/`（归档向，不充当现行规范） |
6. [05-文件上传自动索引-Essence报告](learning/05-文件上传自动索引-Essence报告.md) | 操作指南 | `docs/guides/` |
7. [06-RAG查询流程-Essence报告](learning/06-RAG查询流程-Essence报告.md)
8. [07-Tool定义方式对比与优化](learning/07-Tool定义方式对比与优化.md)
9. [08-MethodToolCallback-vs-ToolCallingManager深度分析](learning/08-MethodToolCallback-vs-ToolCallingManager深度分析.md)
---
## 🔍 分析笔记 (analysis/)
代码分析和问题分析文档：
- [essence-report-rag.md](analysis/essence-report-rag.md)
- [essence-report-rag-chunking.md](analysis/essence-report-rag-chunking.md)
- [explore-report.md](analysis/explore-report.md)
- [chunking-issues-analysis.md](analysis/chunking-issues-analysis.md)
- [功能分析报告.md](analysis/功能分析报告.md)
---
## 📝 临时报告 (reports/)
修复报告和验证报告：
- [修复报告-多轮对话时间查询缓存问题](reports/修复报告-多轮对话时间查询缓存问题.md)
- [验证报告-时间查询问题](reports/验证报告-时间查询问题.md)
- [日志配置完成总结](reports/日志配置完成总结.md)
---
## 📖 指南文档 (guides/)
- [日志配置与分析指南](guides/日志配置与分析指南.md)
---
## 🔄 文档维护
- **学习笔记** 放在 `learning/` 目录，按编号顺序命名
- **分析笔记** 放在 `analysis/` 目录
- **临时报告** 放在 `reports/` 目录
- **指南文档** 放在 `guides/` 目录
- **MVP 架构设计** 已移至项目根目录 `../mvp/`（包含架构、数据库、实施计划）
eval/rag-retrieval/README.md
+2 -2
View File
@@ -9,8 +9,8 @@ Production knowledge path: `MilvusHybridKnowledgeStore` with `retrieval.search.m
Related design notes: Related design notes:
- `docs/RAG-Hybrid质量分与后处理.md` - `mvp/engineering/rag/RAG-Hybrid质量分与后处理.md`
- `docs/RAG-Agent如何读relevance_level.md` - `mvp/engineering/rag/RAG-Agent如何读relevance_level.md`
- `mvp/architecture/RAG知识检索架构.md` §6 - `mvp/architecture/RAG知识检索架构.md` §6
## Offline vs live ## Offline vs live
mvp/README.md
+11 -30
View File
@@ -1,60 +1,41 @@
# SuperBizAgent MVP 文档 # SuperBizAgent MVP 文档
**更新日期**：2026-07-23 **更新日期**：2026-07-29
本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。 本目录保存 MVP 阶段的架构、工程纪要、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。
## 当前入口 ## 当前入口
| 目录/文档 | 用途 | | 目录/文档 | 用途 |
|---|---| |---|---|
| [architecture/README.md](architecture/README.md) | 当前 MVP 架构入口 | | [architecture/README.md](architecture/README.md) | **现行架构**（系统现在怎么跑） |
| [engineering/README.md](engineering/README.md) | **工程纪要**（问题 / 决策 / 思路 / E2E 导读） |
| [architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md) | 当前可运行系统架构 | | [architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md) | 当前可运行系统架构 |
| [architecture/agent-orchestration.md](architecture/agent-orchestration.md) | Agent 编排架构 | | [architecture/agent-orchestration.md](architecture/agent-orchestration.md) | Agent 编排架构 |
| [architecture/harness-quality-gates.md](architecture/harness-quality-gates.md) | Harness 与质量门禁 | | [architecture/harness-quality-gates.md](architecture/harness-quality-gates.md) | Harness 与质量门禁 |
| [architecture/session-trace-lifecycle.md](architecture/session-trace-lifecycle.md) | 会话与 Trace 生命周期 | | [architecture/session-trace-lifecycle.md](architecture/session-trace-lifecycle.md) | 会话与 Trace 生命周期 |
| [architecture/RAG知识检索架构.md](architecture/RAG知识检索架构.md) | 当前 hybrid 检索架构 |
| [issues/README.md](issues/README.md) | MVP issue 索引 | | [issues/README.md](issues/README.md) | MVP issue 索引 |
| [tables/README.md](tables/README.md) | 当前 MySQL 表说明 | | [tables/README.md](tables/README.md) | 当前 MySQL 表说明 |
| [demo/README.md](demo/README.md) | Demo 运行和演示材料 | | [demo/README.md](demo/README.md) | Demo 运行和演示材料 |
| [eval/README.md](eval/README.md) | 诊断评测材料 | | [eval/README.md](eval/README.md) | 诊断评测材料 |
当前架构、运行链路和后续规划分别以 `architecture/`、`issues/README.md`、`tables/README.md` 以及 OpenSpec/devflow 的最新记录为准。 **读法**：改行为先看 `architecture/`；要理解「为什么这样定、踩过什么坑」再看 `engineering/`。
早期个人学习笔记仍在仓库根目录 `docs/learning/` 等，**可能过时**，不以之为现行口径。
## 文档结构 ## 文档结构
```text ```text
mvp/ mvp/
architecture/ architecture/ # 现行架构规范
engineering/ # 工程纪要（问题/决策/E2E）
README.md README.md
current-mvp-architecture.md
agent-orchestration.md
harness-quality-gates.md
session-trace-lifecycle.md
archive/
2026-07-05-legacy/
2026-07-22-legacy/
issues/
README.md
active/
archived/
design-notes/
rag/ rag/
diagnosis/
issues/
tables/ tables/
README.md
*表-*.md
archive/
demo/ demo/
README.md
ten-minute-interview-demo.md
requests/
scripts/
output/
eval/ eval/
README.md
schema.md
cases/
fixtures/
reports/
archive/ archive/
``` ```
mvp/architecture/RAG检索可观测性与审计.md
+3 -3
View File
@@ -388,7 +388,7 @@ flowchart LR
| 文档 | 内容 | | 文档 | 内容 |
|------|------| |------|------|
| `mvp/architecture/RAG知识检索架构.md` | 检索主架构 | | `mvp/architecture/RAG知识检索架构.md` | 检索主架构 |
| `docs/RAG-Agent如何读relevance_level.md` | Agent 如何读 level | | `../engineering/rag/RAG-Agent如何读relevance_level.md` | Agent 如何读 level |
| `docs/RAG-Hybrid质量分与后处理.md` | quality / 排序闸门 | | `../engineering/rag/RAG-Hybrid质量分与后处理.md` | quality / 排序闸门 |
| `docs/RAG离线评测-基线设计.md` | 离线评测（非运行时 Trace） | | `../engineering/rag/RAG离线评测-基线设计.md` | 离线评测（非运行时 Trace） |
| `mvp/architecture/session-trace-lifecycle.md` | 会话/run Trace 总览（若存在） | | `mvp/architecture/session-trace-lifecycle.md` | 会话/run Trace 总览（若存在） |
mvp/architecture/README.md
+3 -1
View File
@@ -1,6 +1,6 @@
# MVP 架构文档 # MVP 架构文档
**更新日期**：2026-07-28 **更新日期**：2026-07-29
**状态**：当前单 Diagnosis Agent + Harness 架构 **状态**：当前单 Diagnosis Agent + Harness 架构
当前文档入口： 当前文档入口：
@@ -15,6 +15,8 @@
| [RAG知识检索架构.md](RAG知识检索架构.md) | 当前 `lookup_knowledge` 检索：MilvusClientV2 dense+BM25 hybrid、chunk 证据身份、重建运维 | | [RAG知识检索架构.md](RAG知识检索架构.md) | 当前 `lookup_knowledge` 检索：MilvusClientV2 dense+BM25 hybrid、chunk 证据身份、重建运维 |
| [RAG检索可观测性与审计.md](RAG检索可观测性与审计.md) | RAG Trace / 审计：请求内 retrievalTrace、tool_invocation 富字段、Trace API 读法 | | [RAG检索可观测性与审计.md](RAG检索可观测性与审计.md) | RAG Trace / 审计：请求内 retrievalTrace、tool_invocation 富字段、Trace API 读法 |
**工程纪要**（问题 / 决策 / E2E，非架构规范正文）见 [../engineering/README.md](../engineering/README.md)。
2026-07-22 前的多角色编排、双入口和旧证据链文档已移动到 `archive/2026-07-22-legacy/`，仅用于历史决策追溯，不代表当前运行时。其中旧 RAG 描述（Spring AI VectorStore 主路径 + Milvus SDK fallback）已被当前 hybrid 实现取代，请以 [RAG知识检索架构.md](RAG知识检索架构.md) 为准。检索可观测与 Trace 以 [RAG检索可观测性与审计.md](RAG检索可观测性与审计.md) 为准（勿再依赖 archive 内旧 retrieval-observability）。 2026-07-22 前的多角色编排、双入口和旧证据链文档已移动到 `archive/2026-07-22-legacy/`，仅用于历史决策追溯，不代表当前运行时。其中旧 RAG 描述（Spring AI VectorStore 主路径 + Milvus SDK fallback）已被当前 hybrid 实现取代，请以 [RAG知识检索架构.md](RAG知识检索架构.md) 为准。检索可观测与 Trace 以 [RAG检索可观测性与审计.md](RAG检索可观测性与审计.md) 为准（勿再依赖 archive 内旧 retrieval-observability）。
当前普通 Trace 与 LLM 步骤审计（`agent_reasoning_audit`：`reasoning_content` + `assistant_text`）使用独立存储和独立接口。 当前普通 Trace 与 LLM 步骤审计（`agent_reasoning_audit`：`reasoning_content` + `assistant_text`）使用独立存储和独立接口。
mvp/engineering/README.md
+53
View File
@@ -0,0 +1,53 @@
# MVP 工程纪要（Engineering Notes）
**更新日期**：2026-07-29
**定位**：项目推进中真实遇到的问题、决策、解决思路与 E2E 验收叙事。
与其它目录分工：
| 目录 | 读什么 |
|---|---|
| [architecture/](../architecture/) | **现行架构**（系统现在怎么跑） |
| **engineering/**（本目录） | **为何这样定**、踩坑、方案取舍、live 验收导读 |
| [issues/](../issues/) | 未完成事项与状态 |
| [tables/](../tables/) | 表结构说明 |
| `docs/learning/` 等 | 早期学习/分析（可能过时，不以之为现行口径） |
| `devflow/projects/` | 单次变更的 brief/decisions/evidence 切片 |
本文档**不是** API 规范的唯一真理源；冲突时以 `architecture/` 与代码为准。
---
## RAG
| 文档 | 内容 |
|---|---|
| [rag/RAG排序-多路召回与RRF.md](rag/RAG排序-多路召回与RRF.md) | K、多路融合、RRF、L0 边界 |
| [rag/RAG-Hybrid质量分与后处理.md](rag/RAG-Hybrid质量分与后处理.md) | qualityScore 统一、L2 伪装废止、后处理 |
| [rag/RAG-Agent如何读relevance_level.md](rag/RAG-Agent如何读relevance_level.md) | Agent 侧相关度标签含义与误读 |
| [rag/RAG离线评测-基线设计.md](rag/RAG离线评测-基线设计.md) | Golden/Fixture、hybrid 评测与闸门 |
| [rag/Milvus-Hybrid接入清单.md](rag/Milvus-Hybrid接入清单.md) | Hybrid 交付拆分与接入清单 |
| [rag/RAG审计补丁-stepid-query-E2E验收.md](rag/RAG审计补丁-stepid-query-E2E验收.md) | step_id / query 审计 live 验收 |
架构对照：
- [architecture/RAG知识检索架构.md](../architecture/RAG知识检索架构.md)
- [architecture/RAG检索可观测性与审计.md](../architecture/RAG检索可观测性与审计.md)
相关 Issue：
- [ISS-017 L0 过滤收窄与 Fallback 加固](../issues/active/ISS-017-rag-l0-filter-fallback-hardening.md)（暂缓，保持现网）
---
## 诊断 / E2E
| 文档 | 内容 |
|---|---|
| [diagnosis/一次诊断全流程-E2E导读.md](diagnosis/一次诊断全流程-E2E导读.md) | SUCCESS 全流程：阶段、token、timeline、字段 |
架构对照：
- [architecture/current-mvp-architecture.md](../architecture/current-mvp-architecture.md)
- [architecture/session-trace-lifecycle.md](../architecture/session-trace-lifecycle.md)
- [architecture/agent-orchestration.md](../architecture/agent-orchestration.md)
docs/一次诊断全流程-E2E导读.md → mvp/engineering/diagnosis/一次诊断全流程-E2E导读.md
+11 -10
View File
@@ -2,7 +2,7 @@
**日期**：2026-07-28 **日期**：2026-07-28
**状态**：SUCCESS 完整诊断主文档；工具阶段按**现行**审计能力（`step_id` / `query`）说明 **状态**：SUCCESS 完整诊断主文档；工具阶段按**现行**审计能力（`step_id` / `query`）说明
**文档路径**：`docs/一次诊断全流程-E2E导读.md` **文档路径**：`mvp/engineering/diagnosis/一次诊断全流程-E2E导读.md`
### 主样本（正文数值与 timeline 来源） ### 主样本（正文数值与 timeline 来源）
@@ -19,14 +19,14 @@
**现行审计**（`step_id` 挂 step、`input_params.query` 等）已合入主路径，见 [§3.4.1](#341-step_id--query-审计如何写入2026-07-28-改造)。 **现行审计**（`step_id` 挂 step、`input_params.query` 等）已合入主路径，见 [§3.4.1](#341-step_id--query-审计如何写入2026-07-28-改造)。
专项 live 验收（含一次业务 FALLBACK 样本）见独立文档： 专项 live 验收（含一次业务 FALLBACK 样本）见独立文档：
→ [RAG 审计补丁 E2E：step_id + query](RAG审计补丁-stepid-query-E2E验收.md) → [RAG 审计补丁 E2E：step_id + query](../rag/RAG审计补丁-stepid-query-E2E验收.md)
**关联文档**： **关联文档**：
- [RAG Trace / 审计架构](../mvp/architecture/RAG检索可观测性与审计.md) - [RAG Trace / 审计架构\](../../architecture/RAG检索可观测性与审计.md)
- [RAG qualityScore 与后处理](RAG-Hybrid质量分与后处理.md) - [RAG qualityScore 与后处理](../rag/RAG-Hybrid质量分与后处理.md)
- [Agent 如何读 relevance_level](RAG-Agent如何读relevance_level.md) - [Agent 如何读 relevance_level](../rag/RAG-Agent如何读relevance_level.md)
- [知识检索架构](../mvp/architecture/RAG知识检索架构.md) - [知识检索架构\](../../architecture/RAG知识检索架构.md)
**回放 API**： **回放 API**：
@@ -520,7 +520,7 @@ sequenceDiagram
| `tool_invocation.step_id` | 指向上述 step | | `tool_invocation.step_id` | 指向上述 step |
| `input_params.query` | 工具检索 query（安全截断后） | | `input_params.query` | 工具检索 query（安全截断后） |
live 数字级验收与 FALLBACK 对照见 → [审计补丁 E2E 专项](RAG审计补丁-stepid-query-E2E验收.md)。 live 数字级验收与 FALLBACK 对照见 → [审计补丁 E2E 专项](../rag/RAG审计补丁-stepid-query-E2E验收.md)。
#### 3.5 分数语义（避免误读） #### 3.5 分数语义（避免误读）
@@ -949,7 +949,7 @@ flowchart TB
| Token 对账 | 通过 | 13236，`tokens_reconciled=true` | | Token 对账 | 通过 | 13236，`tokens_reconciled=true` |
| Trace 闭环 | 通过 | 2 steps / 1 tool / 15 events，persisted=returned | | Trace 闭环 | 通过 | 2 steps / 1 tool / 15 events，persisted=returned |
| SUCCESS 报告 | 通过 | `DIAGNOSIS_REPORT`，action/rec 为空，refs=RAG | | SUCCESS 报告 | 通过 | `DIAGNOSIS_REPORT`，action/rec 为空，refs=RAG |
| 现行审计能力 | 已合入代码 | 见 §3.4.1；专项 live 数字见 [审计补丁 E2E](RAG审计补丁-stepid-query-E2E验收.md) | | 现行审计能力 | 已合入代码 | 见 §3.4.1；专项 live 数字见 [审计补丁 E2E](../rag/RAG审计补丁-stepid-query-E2E验收.md) |
### 9.2 仍未关闭的缺口 ### 9.2 仍未关闭的缺口
@@ -957,7 +957,7 @@ flowchart TB
|---|------|------|--------| |---|------|------|--------|
| 1 | 检索 top 混入弱相关源（如 payment-service-latency） | hybrid 生效但纯度一般；报告可克制，sources 仍可能挂噪声 | 后续过滤/重排 | | 1 | 检索 top 混入弱相关源（如 payment-service-latency） | hybrid 生效但纯度一般；报告可克制，sources 仍可能挂噪声 | 后续过滤/重排 |
| 2 | Semantic Guard 约占 5k tokens | 正确但贵 | 后评估是否可降 | | 2 | Semantic Guard 约占 5k tokens | 正确但贵 | 后评估是否可降 |
| 3 | 偶发 hybrid 空结果 → FALLBACK | 环境/Milvus 抖动 | 见 [审计验收页 §4](RAG审计补丁-stepid-query-E2E验收.md#4-业务-fallback-原因与审计无关) | | 3 | 偶发 hybrid 空结果 → FALLBACK | 环境/Milvus 抖动 | 见 [审计验收页 §4](../rag/RAG审计补丁-stepid-query-E2E验收.md#4-业务-fallback-原因与审计无关) |
缺口 1 示意： 缺口 1 示意：
@@ -1038,4 +1038,5 @@ python scripts/query_mysql.py "SELECT id, step_index, agent_name, has_tool_call,
| 2026-07-28 | 初版：SUCCESS 全流程、字段词典与多图 | | 2026-07-28 | 初版：SUCCESS 全流程、字段词典与多图 |
| 2026-07-28 | 审计补丁代码与 §3.4.1 能力说明 | | 2026-07-28 | 审计补丁代码与 §3.4.1 能力说明 |
| 2026-07-28 | 文档迁入 `docs/`；INDEX 挂接 | | 2026-07-28 | 文档迁入 `docs/`；INDEX 挂接 |
| 2026-07-28 | **拆分**：FALLBACK 审计验收样本迁至 [RAG审计补丁-stepid-query-E2E验收.md](RAG审计补丁-stepid-query-E2E验收.md)；本文只保留 SUCCESS 主线 | | 2026-07-29 | 迁入 `mvp/engineering/diagnosis/`，与 RAG 工程纪要集中到 mvp |
| 2026-07-28 | **拆分**：FALLBACK 审计验收样本迁至 [RAG审计补丁-stepid-query-E2E验收.md](../rag/RAG审计补丁-stepid-query-E2E验收.md)；本文只保留 SUCCESS 主线 |
docs/Milvus-Hybrid接入清单.md → mvp/engineering/rag/Milvus-Hybrid接入清单.md
+1 -1
View File
@@ -4,7 +4,7 @@
**前提**：旧 Milvus SDK 直连检索路径后续废弃，不作为长期实现基础 **前提**：旧 Milvus SDK 直连检索路径后续废弃，不作为长期实现基础
**目标**：在现有 `lookup_knowledge` pipeline 上接入 dense + sparse/BM25 混合检索，融合优先走服务端 RRF **目标**：在现有 `lookup_knowledge` pipeline 上接入 dense + sparse/BM25 混合检索，融合优先走服务端 RRF
**关联文档**： **关联文档**：
- `docs/RAG排序-多路召回与RRF.md`（排序与多路召回判断框架） - `RAG排序-多路召回与RRF.md`（排序与多路召回判断框架）
- 本文后续实现讨论以本节 **「交付拆分：分块去重 + Hybrid 同规划」** 为基线 - 本文后续实现讨论以本节 **「交付拆分：分块去重 + Hybrid 同规划」** 为基线
--- ---
docs/RAG-Agent如何读relevance_level.md → mvp/engineering/rag/RAG-Agent如何读relevance_level.md
+2 -2
View File
@@ -7,8 +7,8 @@
- ACI 契约：`RagToolResult.relevance_level` / `RagRelevanceLevel` - ACI 契约：`RagToolResult.relevance_level` / `RagRelevanceLevel`
- 计算：`KnowledgeEvidencePostProcessor` → `qualityScore` 阈值 - 计算：`KnowledgeEvidencePostProcessor` → `qualityScore` 阈值
- 质量统一：`docs/RAG-Hybrid质量分与后处理.md` - 质量统一：`RAG-Hybrid质量分与后处理.md`
- 多路与 RRF：`docs/RAG排序-多路召回与RRF.md` - 多路与 RRF：`RAG排序-多路召回与RRF.md`
- **运行时 Trace / 审计**：`mvp/architecture/RAG检索可观测性与审计.md` - **运行时 Trace / 审计**：`mvp/architecture/RAG检索可观测性与审计.md`
--- ---
docs/RAG-Hybrid质量分与后处理.md → mvp/engineering/rag/RAG-Hybrid质量分与后处理.md
+2 -2
View File
@@ -9,7 +9,7 @@
- `MilvusHybridKnowledgeStore`（dense / hybrid） - `MilvusHybridKnowledgeStore`（dense / hybrid）
- `RetrievalScoreNormalizer` / `KnowledgeEvidencePostProcessor` - `RetrievalScoreNormalizer` / `KnowledgeEvidencePostProcessor`
- OpenSpec / devflow：`rag-quality-score-unify` - OpenSpec / devflow：`rag-quality-score-unify`
- 前置讨论：`docs/RAG排序-多路召回与RRF.md` - 前置讨论：`RAG排序-多路召回与RRF.md`
- 架构：`mvp/architecture/RAG知识检索架构.md` §6 - 架构：`mvp/architecture/RAG知识检索架构.md` §6
--- ---
@@ -585,7 +585,7 @@ flowchart TB
| 材料 | 路径 | | 材料 | 路径 |
|------|------| |------|------|
| 多路与 RRF 讨论 | `docs/RAG排序-多路召回与RRF.md` | | 多路与 RRF 讨论 | `RAG排序-多路召回与RRF.md` |
| 当前架构 | `mvp/architecture/RAG知识检索架构.md` | | 当前架构 | `mvp/architecture/RAG知识检索架构.md` |
| OpenSpec 归档 | `openspec/changes/archive/2026-07-28-rag-quality-score-unify/` | | OpenSpec 归档 | `openspec/changes/archive/2026-07-28-rag-quality-score-unify/` |
| 主规格 | `openspec/specs/rag-retrieval-quality-score/spec.md` | | 主规格 | `openspec/specs/rag-retrieval-quality-score/spec.md` |
docs/RAG审计补丁-stepid-query-E2E验收.md → mvp/engineering/rag/RAG审计补丁-stepid-query-E2E验收.md
+1 -1
View File
@@ -2,7 +2,7 @@
**日期**：2026-07-28 **日期**：2026-07-28
**状态**：审计字段 live 验收记录 **状态**：审计字段 live 验收记录
**关联主文档**：[一次诊断到底发生了什么（SUCCESS 全流程）](一次诊断全流程-E2E导读.md) **关联主文档**：[一次诊断到底发生了什么（SUCCESS 全流程）](../diagnosis/一次诊断全流程-E2E导读.md)
> 主文档只保留 **SUCCESS 完整诊断** 与 **现行审计能力说明**。 > 主文档只保留 **SUCCESS 完整诊断** 与 **现行审计能力说明**。
> 本页单独记录：改造后的一次 live 验收——**审计字段 PASS**，业务因 Milvus 空结果走了 **FALLBACK**。 > 本页单独记录：改造后的一次 live 验收——**审计字段 PASS**，业务因 Milvus 空结果走了 **FALLBACK**。
docs/RAG排序-多路召回与RRF.md → mvp/engineering/rag/RAG排序-多路召回与RRF.md
View File
docs/RAG离线评测-基线设计.md → mvp/engineering/rag/RAG离线评测-基线设计.md
+4 -4
View File
@@ -8,7 +8,7 @@
- 目录：`eval/rag-retrieval/` - 目录：`eval/rag-retrieval/`
- 脚本：`scripts/eval_rag_retrieval.py`、`generate_rag_lookup_snapshots.ps1`、`prepare_rag_eval_seed.ps1` - 脚本：`scripts/eval_rag_retrieval.py`、`generate_rag_lookup_snapshots.ps1`、`prepare_rag_eval_seed.ps1`
- OpenSpec / devflow：`rag-eval-hybrid-baseline`（已归档） - OpenSpec / devflow：`rag-eval-hybrid-baseline`（已归档）
- 前置：`docs/RAG-Hybrid质量分与后处理.md`、`docs/RAG-Agent如何读relevance_level.md` - 前置：`RAG-Hybrid质量分与后处理.md`、`RAG-Agent如何读relevance_level.md`
--- ---
@@ -576,8 +576,8 @@ python scripts\eval_rag_retrieval.py
| 文档 | 内容 | | 文档 | 内容 |
|------|------| |------|------|
| `eval/rag-retrieval/README.md` | 操作说明（以仓库为准） | | `eval/rag-retrieval/README.md` | 操作说明（以仓库为准） |
| `docs/RAG-Hybrid质量分与后处理.md` | quality / 后处理 | | `RAG-Hybrid质量分与后处理.md` | quality / 后处理 |
| `docs/RAG-Agent如何读relevance_level.md` | Agent 如何读 level | | `RAG-Agent如何读relevance_level.md` | Agent 如何读 level |
| `docs/RAG排序-多路召回与RRF.md` | 多路与 RRF | | `RAG排序-多路召回与RRF.md` | 多路与 RRF |
| `devflow/projects/2026-07-28-rag-eval-hybrid-baseline/` | 本 change 档案 | | `devflow/projects/2026-07-28-rag-eval-hybrid-baseline/` | 本 change 档案 |
| `openspec/specs/rag-eval-offline-baseline/spec.md` | 主规格 | | `openspec/specs/rag-eval-offline-baseline/spec.md` | 主规格 |
openspec/changes/archive/2026-07-27-rag-chunk-evidence-identity-dedup/design.md
+1 -1
View File
@@ -3,7 +3,7 @@
## Context ## Context
- Modular RAG pipeline already exists (`KnowledgeQueryTransformer` → retriever → post-processor → packer → assembler → projector). - Modular RAG pipeline already exists (`KnowledgeQueryTransformer` → retriever → post-processor → packer → assembler → projector).
- Delivery baseline: `docs/Milvus-Hybrid接入清单.md` §1.1 Delivery 1. - Delivery baseline: `mvp/engineering/rag/Milvus-Hybrid接入清单.md` §1.1 Delivery 1.
- Historical decision (modular RAG): L0 is hint-only; L1 is fact evidence. This change keeps that boundary. - Historical decision (modular RAG): L0 is hint-only; L1 is fact evidence. This change keeps that boundary.
- Legacy Milvus SDK search path will be abandoned later; this change must not thicken SDK-specific logic. - Legacy Milvus SDK search path will be abandoned later; this change must not thicken SDK-specific logic.
openspec/changes/archive/2026-07-27-rag-chunk-evidence-identity-dedup/proposal.md
+2 -2
View File
@@ -9,7 +9,7 @@
As a result, L1 can recall multiple useful chunks from one document, but Agent often sees only one. This blocks multi-path / hybrid retrieval benefits and hurts long runbook completeness. As a result, L1 can recall multiple useful chunks from one document, but Agent often sees only one. This blocks multi-path / hybrid retrieval benefits and hurts long runbook completeness.
This change is **Delivery 1** from `docs/Milvus-Hybrid接入清单.md`. Hybrid schema/search is **out of scope** and will be a separate change after this is archived. This change is **Delivery 1** from `mvp/engineering/rag/Milvus-Hybrid接入清单.md`. Hybrid schema/search is **out of scope** and will be a separate change after this is archived.
## What Changes ## What Changes
@@ -47,7 +47,7 @@ This change is **Delivery 1** from `docs/Milvus-Hybrid接入清单.md`. Hybrid s
- Code: retrieval DTO/services, post-processor, lookup tool config, projector, tests - Code: retrieval DTO/services, post-processor, lookup tool config, projector, tests
- Agent-visible: more evidence items possible for same logical document when multiple chunks are relevant - Agent-visible: more evidence items possible for same logical document when multiple chunks are relevant
- Interface level: **L2/L3** — Agent `document_id` semantics become chunk-scoped evidence id (often `docId#chunk-N`); EvidenceGuard still validates against tool projection ids - Interface level: **L2/L3** — Agent `document_id` semantics become chunk-scoped evidence id (often `docId#chunk-N`); EvidenceGuard still validates against tool projection ids
- Docs baseline: `docs/Milvus-Hybrid接入清单.md` §1.1 Delivery 1 - Docs baseline: `mvp/engineering/rag/Milvus-Hybrid接入清单.md` §1.1 Delivery 1
## Risks ## Risks