chore(docs): 归档 ISS-001 session-dedup-knowledge-map + ISS-002 mvp 文档
- 移动 session-dedup-knowledge-map OpenSpec 到 archive 目录 - 提交 ISS-001 遗留的 devflow 档案文件 - 更新 ISS-002 状态为已修复 - 新增 mvp/architecture/action-memory-relevance.md 设计文档 - 更新 mvp/README.md 文档导航 - 更新 devflow/index.md OpenSpec 链接指向 archive
This commit is contained in:
zhuyongxin
@@ -14,6 +14,7 @@
|
||||
- [会话管理](architecture/session-management.md) - Redis + MySQL 会话管理
|
||||
- [实施规划](architecture/implementation-plan.md) - 分阶段实施计划
|
||||
- [证据评分与用户反馈](architecture/confidence-feedback.md) - evidence_score 规则引擎 + feedback API ⭐新增
|
||||
- [行动记忆与检索归一化](architecture/action-memory-relevance.md) - Executor 行动记忆 + 归一化质量等级解决 ISS-002 ⭐新增
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,275 @@
|
||||
# 行动记忆与检索质量归一化
|
||||
|
||||
Executor 行动记忆 + 归一化质量等级设计，解决 ISS-002 Executor 无约束重复检索问题。
|
||||
|
||||
---
|
||||
|
||||
## 一、问题背景
|
||||
|
||||
ISS-001 修复文档级去重后，Executor 在单次会话中仍调用 `lookup_knowledge` 20+ 次。根因：
|
||||
|
||||
1. **行动记忆缺失**：Executor 不知道自己已检索过哪些域
|
||||
2. **质量信号缺失**：检索结果没有给 LLM 判断"结果够不够"的信号
|
||||
3. **Prompt 缺少合法出口**：原 prompt 要求"所有外部信息都必须调用工具"，LLM 不敢停止检索
|
||||
|
||||
---
|
||||
|
||||
## 二、整体架构
|
||||
|
||||
```
|
||||
lookup_knowledge(query)
|
||||
│
|
||||
├─ Step 1: L0 精确匹配（keywords 索引）
|
||||
├─ Step 2: L1 语义检索（Milvus 向量）
|
||||
├─ Step 3: computeRelevance()
|
||||
│ ├─ 归一化：L2 → similarity [0,1]
|
||||
│ └─ 判定：PRECISE / HIGHLY_RELEVANT / REFERENCE
|
||||
├─ Step 4: RetrievedDocTracker 检查
|
||||
│ ├─ 文档级去重 → isDocRetrieved(sessionId, docKey)
|
||||
│ ├─ 域级检查 → isDomainRetrieved(sessionId, domain)
|
||||
│ └─ 记录 → markRetrieved(sessionId, domain, docKey)
|
||||
└─ Step 5: 返回 LookupResult
|
||||
├─ primary / supplement（原始内容，不含分数）
|
||||
├─ relevanceLevel（PRECISE / HIGHLY_RELEVANT / REFERENCE）
|
||||
├─ completenessHint（兜底信号）
|
||||
└─ retrievedDomainsThisSession（行动记忆）
|
||||
```
|
||||
|
||||
### 设计原则
|
||||
|
||||
| 原则 | 说明 |
|
||||
|------|------|
|
||||
| **Agent 边界清晰** | 不给 Executor 注入 knowledge map，Executor 只知道做了什么，不用知道有什么 |
|
||||
| **分数封装** | L0/L1 原始分数不在 LookupResult 中返回 LLM，只在归一化层内部使用 |
|
||||
| **原始分数只入库** | 原始 L2 距离写进 `tool_invocation.retrieval_details` JSON 用于可观测 |
|
||||
| **软约束 + 硬拦截** | Prompt 约束（软）+ 工具层域级去重（硬）两层防御 |
|
||||
|
||||
---
|
||||
|
||||
## 三、归一化质量等级
|
||||
|
||||
### L2 距离归一化
|
||||
|
||||
BGE-M3 输出为 L2 归一化单位向量（实测范数=1.00000002），L2 距离数学硬上界 = 2.0。
|
||||
|
||||
```
|
||||
similarity = 1 - min(l2Score, maxL2Distance) / maxL2Distance
|
||||
```
|
||||
|
||||
| L2 距离 | similarity | 等级 |
|
||||
|---------|-----------|------|
|
||||
| 0.0 | 1.0 | PRECISE |
|
||||
| 0.383 | 0.8085 | HIGHLY_RELEVANT |
|
||||
| 0.5 | 0.75 | HIGHLY_RELEVANT |
|
||||
| 0.6031 | 0.6984 | REFERENCE |
|
||||
| 1.0 | 0.5 | REFERENCE 边界 |
|
||||
| 2.0+ | 0.0 | 不视为有效结果 |
|
||||
|
||||
### 三等级判定
|
||||
|
||||
| 等级 | 条件 | completenessHint | LLM 行为 |
|
||||
|------|------|-----------------|---------|
|
||||
| PRECISE | L0 matchCount == 1 | "知识库中不存在比上述结果更精准的文档" | 直接使用，禁止再检索 |
|
||||
| HIGHLY_RELEVANT | L0 命中 + similarity ≥ 0.75，或仅 L1 similarity ≥ 0.75 | "当前结果已高度相关，继续检索不太可能找到更精准的文档" | 可综合推理，大概率不需要继续查 |
|
||||
| REFERENCE | 其余命中（similarity ≥ 0.5） | "当前结果为相关参考，如需更精准信息请明确缺少的具体维度" | 可参考，如需更精准请指出缺少的维度后定向补充 |
|
||||
|
||||
### 阈值配置
|
||||
|
||||
```yaml
|
||||
retrieval:
|
||||
normalization:
|
||||
max-l2-distance: 2.0 # L2 距离上界
|
||||
highly-relevant-threshold: 0.75 # similarity ≥ 0.75 → HIGHLY_RELEVANT
|
||||
reference-threshold: 0.5 # similarity ≥ 0.5 → REFERENCE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、行动记忆
|
||||
|
||||
### RetrievedDocTracker 数据结构
|
||||
|
||||
```java
|
||||
// 从单层升级为双层：session → domain → filePath 集合
|
||||
ConcurrentHashMap<String, Map<String, Set<String>>> sessionRetrievals;
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
| 方法 | 作用 |
|
||||
|------|------|
|
||||
| `markRetrieved(sessionId, domain, filePath)` | 记录一次检索 |
|
||||
| `isDocRetrieved(sessionId, filePath)` | 文档级去重 |
|
||||
| `isDomainRetrieved(sessionId, domain)` | 域级检查 |
|
||||
| `getRetrievedDomains(sessionId)` | 获取已检索域列表 |
|
||||
| `clearSession(sessionId)` | 清理会话记录 |
|
||||
|
||||
### LookupResult 返回
|
||||
|
||||
```java
|
||||
LookupResult.builder()
|
||||
.found(true)
|
||||
.primary(primaryResult)
|
||||
.supplement(supplementResult)
|
||||
.relevanceLevel("HIGHLY_RELEVANT") // PRECISE / HIGHLY_RELEVANT / REFERENCE
|
||||
.completenessHint("当前结果已高度相关...") // 兜底信号
|
||||
.retrievedDomainsThisSession(["infrastructure", "api"]) // 行动记忆
|
||||
.message("...")
|
||||
.build();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、Executor Prompt 约束
|
||||
|
||||
### 4 条检索约束
|
||||
|
||||
1. **判断重复**：基于 `retrievedDomainsThisSession` 判断语义重叠
|
||||
2. **重复了怎么办**：禁止换关键词重查；先指缺少的维度，再定向补充
|
||||
3. **合法出口**："不查全不会被追责，重复检索才会被惩罚"
|
||||
4. **利用质量信号**：PRECISE → 停止；HIGHLY_RELEVANT + 域已检索 → 禁止；REFERENCE → 指出缺少维度
|
||||
|
||||
### 关键变化
|
||||
|
||||
原有 prompt："所有需要外部信息的地方，都必须调用对应的工具"
|
||||
→ 改为："需要外部信息时调用工具，但须遵守下方的检索约束"
|
||||
|
||||
---
|
||||
|
||||
## 六、数据库变更
|
||||
|
||||
### V010
|
||||
|
||||
```sql
|
||||
ALTER TABLE tool_invocation
|
||||
ADD COLUMN relevance_level VARCHAR(20) COMMENT 'PRECISE/HIGHLY_RELEVANT/REFERENCE/DEDUPED',
|
||||
ADD COLUMN dedup_reason VARCHAR(32) COMMENT 'doc_retrieved/domain_retrieved/null';
|
||||
```
|
||||
|
||||
### retrieval_details JSON 扩展
|
||||
|
||||
```json
|
||||
{
|
||||
"l0_titles": ["MySQL 数据库连接池配置", "Redis 缓存配置指南"],
|
||||
"l1_scores": [0.383, 0.4502, 0.7011],
|
||||
"l1_top_score": 0.383,
|
||||
"l1_top_similarity": 0.8085,
|
||||
"relevance_level": "HIGHLY_RELEVANT",
|
||||
"completeness_hint": "当前结果已高度相关，继续检索不太可能找到更精准的文档",
|
||||
"retrieved_domains": ["infrastructure"]
|
||||
}
|
||||
```
|
||||
|
||||
扩展字段使用方式：
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `l1_top_score` | 原始 L2 距离最小值（可观测性） |
|
||||
| `l1_top_similarity` | 归一化后的相似度 [0,1] |
|
||||
| `relevance_level` | 归一化质量等级 |
|
||||
| `completeness_hint` | 兜底信号 |
|
||||
| `retrieved_domains` | 已检索域列表 |
|
||||
| `dedup_reason` | 去重原因（如有） |
|
||||
|
||||
---
|
||||
|
||||
## 七、使用场景
|
||||
|
||||
### 场景 1：正常检索
|
||||
|
||||
```
|
||||
用户：数据库连接池怎么配置？
|
||||
|
||||
Executor 内部：
|
||||
1. lookup_knowledge("数据库连接池配置")
|
||||
→ relevanceLevel=HIGHLY_RELEVANT (similarity=0.8085)
|
||||
→ completenessHint="当前结果已高度相关..."
|
||||
→ retrievedDomainsThisSession=["infrastructure"]
|
||||
2. 基于已有信息直接回答，不再检索
|
||||
```
|
||||
|
||||
### 场景 2：行动记忆阻止重复
|
||||
|
||||
```
|
||||
Executor 步骤列表：
|
||||
- 查数据库连接池配置
|
||||
- 查 HikariCP 参数
|
||||
- 查连接池耗尽排查
|
||||
|
||||
实际行为：
|
||||
1. lookup("数据库连接池") → relevance=HIGHLY_RELEVANT, domains=["infrastructure"]
|
||||
2. lookup("HikariCP 参数") → retrievedDomainsThisSession=["infrastructure"]
|
||||
LLM 判断：infrastructure 域已检索过，禁止换关键词重查
|
||||
→ 基于已有信息回答，指出缺少的具体维度
|
||||
3. lookup("连接池耗尽") → 同域，被 prompt 约束拦截或工具层去重拦截
|
||||
```
|
||||
|
||||
### 场景 3：PRECISE 精确匹配
|
||||
|
||||
```
|
||||
用户：ERR_TIMEOUT 是什么？
|
||||
|
||||
Executor 内部：
|
||||
1. lookup_knowledge("ERR_TIMEOUT")
|
||||
→ L0 matchCount=1（唯一精确匹配）
|
||||
→ relevanceLevel=PRECISE
|
||||
→ completenessHint="知识库中不存在比上述结果更精准的文档"
|
||||
2. 直接使用，不再检索
|
||||
```
|
||||
|
||||
### 场景 4：REFERENCE + 定向补充
|
||||
|
||||
```
|
||||
用户：如何排查生产故障？
|
||||
|
||||
Executor 内部：
|
||||
1. lookup_knowledge("故障排查")
|
||||
→ relevanceLevel=REFERENCE (similarity=0.6)
|
||||
→ retrievedDomainsThisSession=["troubleshooting"]
|
||||
2. LLM 判断：信息不足，缺少"日志分析"维度的具体步骤
|
||||
3. lookup_knowledge("日志分析步骤")
|
||||
→ 定向补充，不盲目换关键词
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、可观测性
|
||||
|
||||
### 查询质量分布
|
||||
|
||||
```sql
|
||||
SELECT relevance_level, COUNT(*) AS cnt
|
||||
FROM tool_invocation
|
||||
WHERE tool_name = 'lookup_knowledge'
|
||||
GROUP BY relevance_level;
|
||||
```
|
||||
|
||||
### 去重原因分布
|
||||
|
||||
```sql
|
||||
SELECT dedup_reason, COUNT(*) AS cnt
|
||||
FROM tool_invocation
|
||||
WHERE tool_name = 'lookup_knowledge'
|
||||
GROUP BY dedup_reason;
|
||||
```
|
||||
|
||||
### 归一化分数分布
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
JSON_EXTRACT(retrieval_details, '$.l1_top_similarity') AS similarity,
|
||||
COUNT(*) AS cnt
|
||||
FROM tool_invocation
|
||||
WHERE tool_name = 'lookup_knowledge'
|
||||
AND retrieval_details IS NOT NULL
|
||||
GROUP BY similarity
|
||||
ORDER BY similarity;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、扩展方向（Phase 2）
|
||||
|
||||
- **域级硬限流**：`isDomainRetrieved` 已就绪，在 LookupKnowledgeTool 入口直接拦截同域调用，不依赖 LLM 遵守 prompt
|
||||
- **DEDUPED 等级**：去重时单独标记为 DEDUPED 等级，与 REFERENCE 区分
|
||||
- **分数反馈调优**：基于 feedback 数据优化归一化阈值
|
||||
@@ -0,0 +1,81 @@
|
||||
# ISS-001 Executor 重复召回同一文档
|
||||
|
||||
**状态**：已修复（2026-06-30）
|
||||
**严重程度**：中（影响 token 消耗和上下文质量，不影响功能正确性）
|
||||
**发现时间**：2026-06-30
|
||||
**修复版本**：session-dedup-knowledge-map
|
||||
|
||||
---
|
||||
|
||||
## 现象
|
||||
|
||||
单次对话中 `lookup_knowledge` 被调用 20 次，其中"故障诊断流程规范"被重复召回约 13 次，多个文档被重复召回 3-6 次。
|
||||
|
||||
```
|
||||
tool_invocation 记录（db8bfa0f）：
|
||||
L0 命中"故障诊断流程规范" × 13
|
||||
L0+L1 命中"MySQL 数据库连接池配置" × 5
|
||||
L1 命中性能类故障 × 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 根本原因
|
||||
|
||||
**两个层面同时缺失去重机制：**
|
||||
|
||||
1. **工具层无去重**：`LookupKnowledgeTool` 每次独立检索，不感知调用历史，同一查询关键词必然返回同一文档
|
||||
2. **Agent 层无记忆**：Executor Prompt 未要求跟踪已使用文档，LLM 每步倾向于"再确认一下"，反复触发相同检索
|
||||
|
||||
**调用链路：**
|
||||
|
||||
```
|
||||
Planner step 0：制定排查计划
|
||||
Executor step 0：检索知识库 → 命中故障诊断流程规范
|
||||
Executor step 1：继续检索 → 又命中故障诊断流程规范（不知道已取过）
|
||||
Executor step 3：继续检索 → 又命中故障诊断流程规范
|
||||
... （重复 13 次）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 影响
|
||||
|
||||
- **Token 浪费**：同一文档内容反复塞入上下文，多 Agent 场景尤为明显
|
||||
- **上下文窗口压缩**：重复内容占用有效 token 空间，可能导致有用信息被截断
|
||||
- **evidence_score 失真**：`tool_call_count` 虚高，规则评分中"成功调用次数"被膨胀
|
||||
|
||||
---
|
||||
|
||||
## 修法方向
|
||||
|
||||
### 方案 A：Prompt 层约束（简单，优先验证）
|
||||
|
||||
在 `chat-executor-prompt.md` 中加规则：
|
||||
|
||||
```
|
||||
已检索过的文档不要重复检索。每次调用 lookup_knowledge 前，
|
||||
先检查对话历史中是否已有该文档的内容，有则直接使用，不再重复调用。
|
||||
```
|
||||
|
||||
优点：不改代码，立即可验证
|
||||
缺点：依赖 LLM 遵守指令，不保证 100% 生效
|
||||
|
||||
### 方案 B：工具层去重（可靠，推荐长期方案）
|
||||
|
||||
`LookupKnowledgeTool` 在 session 维度维护已召回文档 ID 集合，检索结果返回前过滤掉已召回的文档。
|
||||
|
||||
优点：彻底解决，不依赖 LLM
|
||||
缺点：需要改工具代码，需要 session 级状态传递
|
||||
|
||||
### 建议
|
||||
|
||||
MVP 阶段先做**方案 A**验证效果，若重复率明显下降则保留；
|
||||
若 LLM 不稳定遵守，再升级到**方案 B**。
|
||||
|
||||
---
|
||||
|
||||
## 相关文件
|
||||
|
||||
- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
|
||||
- `src/main/resources/prompts/chat-executor-prompt.md`
|
||||
@@ -1,8 +1,9 @@
|
||||
# ISS-002 Executor 无约束重复调用 lookup_knowledge
|
||||
|
||||
**状态**：待修复
|
||||
**状态**：已修复
|
||||
**严重程度**：中（工具层去重已拦截重复文档，但调用本身仍浪费 token 和耗时）
|
||||
**发现时间**：2026-07-01
|
||||
**修复时间**：2026-07-01
|
||||
**关联**：ISS-001（Part A 已修，Part B 注入范围不足）
|
||||
|
||||
---
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
| # | 标题 | 严重程度 | 状态 | 文件 |
|
||||
|---|---|---|---|---|
|
||||
| ISS-001 | Executor 重复召回同一文档 | 中 | 已修复 | [ISS-001-duplicate-retrieval.md](ISS-001-duplicate-retrieval.md) |
|
||||
| ISS-002 | Executor 无约束重复调用 lookup_knowledge | 中 | 待修复 | [ISS-002-executor-unconstrained-lookup.md](ISS-002-executor-unconstrained-lookup.md) |
|
||||
| ISS-002 | Executor 无约束重复调用 lookup_knowledge | 中 | 已修复 | [ISS-002-executor-unconstrained-lookup.md](ISS-002-executor-unconstrained-lookup.md) |
|
||||
|
||||
Reference in New Issue
Block a user