zhuyongxin
e438df4355
- RetrievedDocTracker 升级为域级+文档级双层记录（Map<sessionId, Map<domain, Set<filePath>>>） - LookupKnowledgeTool 新增 Min-Max 归一化层（BGE-M3 L2 距离→[0,1] similarity） - 三等级 relevanceLevel：PRECISE / HIGHLY_RELEVANT / REFERENCE + completenessHint 兜底信号 - LookupResult 新增 relevanceLevel、completenessHint、retrievedDomainsThisSession - Executor prompt 重写：4 条检索约束 + 合法出口不查全不追责，重复检索才惩罚 - 入库可观测性：V010 迁移 + retrieval_details JSON 扩展 - 归档 executor-action-memory-relevance change
71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
# Acceptance: executor-action-memory-relevance
|
||
|
||
## 分档
|
||
|
||
standard
|
||
|
||
## 任务完成状态
|
||
|
||
| 任务 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| T1: RetrievedDocTracker 域级升级 | ✅ 完成 | 双层 Map 结构，域级+文档级记录 |
|
||
| T2: LookupResult 新增字段 | ✅ 完成 | relevanceLevel / completenessHint / retrievedDomainsThisSession |
|
||
| T3: 归一化计算逻辑 | ✅ 完成 | Min-Max 归一化 + 三等级判定 |
|
||
| T4: LookupKnowledgeTool 集成 | ✅ 完成 | 归一化层 + 行动记忆注入 + 域拦截 |
|
||
| T5: Executor Prompt 重写 | ✅ 完成 | 4 条检索约束，无 knowledge map |
|
||
| T6: 入库可观测性 | ✅ 完成 | V010 + Entity + JSON 扩展 |
|
||
| T7: BGE-M3 归一化验证测试 | ✅ 完成 | 范数=1.00000002，测试通过 |
|
||
|
||
## 静态验证
|
||
|
||
- [x] **语法/编译检查**: 所有 Java 文件编译通过
|
||
- [x] **Impact Analysis**: LookupKnowledgeTool、RetrievedDocTracker 变更范围经 `gitnexus_impact` 检查，均为 L2 内部接口影响
|
||
- [x] **Cross-artifact 对齐检查**: brief → proposal → design → specs → tasks 闭环，无 gap
|
||
- [x] **Prompt 约束检查**: chat-executor-prompt.md 不包含 knowledge map，包含 4 条检索约束
|
||
|
||
## 脚本验证
|
||
|
||
- [x] **V010 Flyway 迁移**: 迁移成功，`relevance_level` 和 `dedup_reason` 列已添加
|
||
```sql
|
||
ALTER TABLE tool_invocation
|
||
ADD COLUMN relevance_level VARCHAR(20),
|
||
ADD COLUMN dedup_reason VARCHAR(32);
|
||
```
|
||
- [x] **FullPipelineSmokeTest**: BGE-M3 归一化测试通过（范数=1.00000002）
|
||
- [x] **数据库数据校验**:
|
||
- `relevance_level` 列已写入 HIGHLY_RELEVANT / REFERENCE
|
||
- `dedup_reason` 列已写入 doc_retrieved / null
|
||
- `retrieval_details` JSON 包含 l1_top_similarity、completeness_hint、retrieved_domains、dedup_reason
|
||
|
||
## 浏览器/人工验证
|
||
|
||
- [x] **应用启动验证**: Spring Boot 应用正常启动，端口 9900
|
||
- [x] **Chat API 调用验证**: 通过 curl 测试 chat 接口，lookup_knowledge 调用链完整
|
||
```
|
||
curl -X POST "http://localhost:9900/api/chat/send" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"sessionId": "b66d799e", "question": "..."}'
|
||
```
|
||
- [x] **日志验证**: 应用日志可观察到 relevanceLevel、retrievedDomainsThisSession 输出
|
||
- [x] **归一化数学验证**: l1_top_score=0.383 → l1_top_similarity=0.8085（`1 - 0.383/2.0 = 0.8085`）✅
|
||
- [x] **域追踪验证**: `[infrastructure]` → `[infrastructure, api]` 域列表正常扩展
|
||
|
||
## 未验证
|
||
|
||
| 场景 | 原因 | 风险 | 补验建议 |
|
||
|------|------|------|---------|
|
||
| PRECISE 等级（L0 唯一精确匹配） | 测试会话无精确匹配场景 | 低 — L0 matchCount=1 的判断逻辑与 HIGHLY_RELEVANT 共用，实现确定性强 | 构造一条 L0 精确匹配的知识库文档后测试 |
|
||
| domain_retrieved 域级去重 | 需要同一域全部文档已检索再查该域才触发 | 低 — isDomainRetrieved 逻辑简单，与 isDocRetrieved 等价 | Phase 2 启用域级硬限流时测试 |
|
||
| DEDUPED 等级 | 当前 code path 去重时仍写 REFERENCE，DEDUPED 未被使用 | 低 — 设计预留，当前未启用 | Phase 2 若启用 DEDUPED 等级时验证 |
|
||
| Phase 2 域级硬限流 | 非本次范围 | 中 — 当前仅有软约束（prompt），LLM 仍可能在 REFERENCE 下继续检索 | 实测观察，如果 lookup 调用仍偏高，启动 Phase 2 |
|
||
|
||
## 剩余风险
|
||
|
||
1. **Prompt 软约束局限性**：实测 10 次调用中 9 次为 REFERENCE，说明 LLM 仍倾向于继续检索。如果 prompt 约束效果不足，需启用 Phase 2 域级硬限流。
|
||
2. **L1 Metadata 解析兼容性**：L1 domain 兜底路径解析 metadata JSON，如果知识库文档 frontmatter 格式不一致可能解析失败，已有 try-catch 兜底。
|
||
|
||
## 归档状态
|
||
|
||
- [ ] OpenSpec change 尚未归档
|
||
- [ ] devflow/index.md 状态为 `implemented`，待改为 `archived`
|