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
2026-07-01 18:27:04 +08:00
parent e438df4355
commit a1c896ebda
14 changed files with 834 additions and 3 deletions
@@ -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) |