Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,13 +126,21 @@ query_memory(user_id, query, session_id=None) -> Dict

---

## 10. 测试体系(26 用例全绿)
## 10. 测试体系(58 用例全绿)

> ⚠️ 2026-09-21 更新:原为 26 用例。新增 test_day20(KV 淘汰/隔离/缓存)、
> test_day21(技能生成守卫)、test_day22(embedding 契约)、test_day23(RAG 条件性)。
> 其中 test_day18/19 共 13 个依赖 Ollama `bge-m3`,CI 里单独成一个**不阻断**的 job(见 DEC-002)。

| 文件 | 用例数 | 覆盖 |
|---|---|---|
| `test_day17_deterministic_backtrack.py` | 13 | 确定性、时间回溯、KV 零噪声、多租户隔离、Append-Only、参数化隔离、时间范围 |
| `test_day18_evolution_conditional.py` | 8 | 程序性记忆进化链路、RAG 条件判定、RAG 版本对比、技能候选隔离、description 匹配、参数化不串扰 |
| `test_day19_performance_stability.py` | 5 | 性能基线、tool_call/skill_call 一致性、RAG 版本同步、并发压力分档 |
| `test_day20_kv_demotion.py` | 11 | KV 淘汰四条规则、淘汰路径多租户隔离、删除后缓存失效、TTL 参数校验 |
| `test_day21_skill_generator_guard.py` | 11 | 技能生成失败/哨兵**不得落盘**(SkillGenerationError、save 拒绝无 name:) |
| `test_day22_embedding_contract.py` | 4 | embedding 外部契约:三者维度都是 1024、超时都是 30s |
| `test_day23_rag_conditional.py` | 6 | RAG 条件性判据:内部足够则不调、不足才调、调用方必须传 summary_count |

- 清理统一在 `conftest.py`(`clean_db` autouse),前缀 `user_test_%`;含 ledger 临时禁用触发器、`memory_embedding`、`rag_knowledge_base`(`source LIKE 'test-%'`)
- 性能归档:`perf_baselines.json`(追加式,保留历史对比)
Expand Down
26 changes: 25 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,31 @@

---

## [第 2 轮] · 2026-09-21 · 挂 CI(GitHub Actions)· 🚧 进行中
## [第 2 轮] · 2026-09-21 · 挂 CI + RAG 条件性判据 · 🚧 进行中

### 修复(Fixed)· ⭐ 本轮起改用 **TDD(先写会失败的测试)**

- **A3 · RAG「条件性」名实不符** —— 判据里 `summary_confidence` **没有生产者**(恒为 `0.0`)
⇒ `is_result_complete` 恒假 ⇒ 条件 3 恒真 ⇒ **除 KV 命中外的查询全都调 RAG**。
裁决:**判据里不许出现没有生产者的量** → 见 `docs/decisions决策/DEC-003-内部结果完整性的判据-20260921.md`
- **B1① · `summary_count` 有生产者却没接线** —— `rag_conditional_search` 收到含 `summary_count` 的
`summary_result`,却不往下传(默认 0)。已接线
- **B1② · 移除幻影形参** —— `is_result_complete` / `should_call_rag` 的 `summary_confidence` 形参**删除**
(保留=留着旋钮没人转,正是 A3 的成因);新增具名常量 `SUMMARY_COMPLETENESS_MIN_COUNT = 2`
- **顺带修掉** `views_api` 里的 `len(字典)` 当"摘要条数"用(`len()` 恒为 5,与条数无关),
以及那句未兑现的注释「第8天实现 Summary 后提供真实置信度」

### 工程 · TDD 纪律落地

- **本轮两次都按 红→绿 走,且 RED 是**看着**失败的**(不是事后补测):
· `test_day23` 先跑 → **3 failed**(`assert True is False` 等,全因"功能不存在"而非笔误)→ 改代码 → **6 passed**
- ⭐ 纪律已写进 `CLAUDE.md §5`:**改代码 / 提交前必须走红绿**;新用例必须**先看它失败**

### 文档校正(我的改动导致的过时陈述)

- `README.md` / `ARCHITECTURE.md` / `性能基线与容量规划.md`:**26 用例 → 58 用例**(并补上新文件与用途)
- `README.md` 技术栈:**Python 3.9 → 3.11**(3.9 已证装不上)
- ⚠️ `ARCHITECTURE.md §1` 那句「RAG 是条件性调用——不默认触发」**此前与实现不符**,**本轮修完后才成立**

### 新增(Added)

Expand Down
40 changes: 34 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,10 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
**新增表或新增落盘位置要自己在这里补一条**(文件里留了注释提示)。
- **删 Ledger 必须临时 `DISABLE TRIGGER ledger_append_only_trigger` 再恢复** —— 生产严禁。Append-Only 有测试真的断言了 UPDATE/DELETE 被拒(`test_day17:193+`)。
- ⚠️ 该断言**必须把 payload 包成 `Json()`**,否则 psycopg2 在参数适配阶段就报错、触发器根本没被触发 ⇒ **测试假绿**(`test_day17` 里有注释写明)。
- **当前 45 用例** = `test_day17`(13,含 3×2 参数化) + `test_day18`(8) + `test_day19`(5) + `test_day20_kv_demotion`(8) + `test_day21_skill_generator_guard`(11)。
- **当前 58 用例** = `test_day17`(13,含 3×2 参数化) + `test_day18`(8) + `test_day19`(5) + `test_day20_kv_demotion`(11) + `test_day21_skill_generator_guard`(11) + `test_day22_embedding_contract`(4) + `test_day23_rag_conditional`(6)。
⚠️ `test_day18`/`test_day19` 共 13 个带 `requires_ollama` 标记(要 Ollama + bge-m3)。
**不起 Ollama 时**:`pytest -m "not requires_ollama"` → 45 个。
- **⛔ 改代码 / 提交前必须走红绿(TDD)** —— 见下 §7。
⚠️ **新加测试文件必须同时加进 `pytest.ini` 的 `testpaths`** —— 它是显式枚举的,不加就**不会被 `pytest` 收集**(第 1 轮新增的两个文件都加了)。
- **新增用例要做反证**:用 git 取旧代码(`git stash push -- <file>` 或 `git show HEAD:<file>`)确认用例**真的会红**,否则等于没测。
- `perf_baselines.json` 是 `test_day19` 的**追加式**产物,已 gitignore(本仓不存在,原目录有)。
Expand All @@ -144,16 +147,16 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
| **`audit源码通读-待修清单-20260921.md`** | ⭐ **待修队列**。按 A/B/C/D/E 分类 + 优先级,每条带文件行号证据。⚠️ 第 1 轮已修掉 A2/C2/D1/D2/B2/B3/D3,**它的行号已部分失效**,当线索用、别当现状 |
| `ARCHITECTURE.md §11` | 仓库自己承认的 5 条缺口(tool_call 不自动进向量/Summary、`TTL_RAG` 未使用、`SimpleConnectionPool` 非线程安全、向量层未进检索链、程序性记忆自动触发未实现) |

### 剩下没做的(第 2 轮的活)
### 剩下没做的(后续轮次)

| 条目 | 说明 |
|---|---|
| **A1** | `rerank_with_llm` 未接线 —— 定义在 `vector_semantic.py`,唯一调用点在自己模块的 `main()` 演示里;真检索走 `rrf_fusion` 后**直接截断**,没有重排那一步 |
| **A3** | RAG「条件性」退化成「非 KV 命中即调用」(`summary_confidence` 恒为 `0.0` ⇒ `is_result_complete` 必为 False ⇒ 条件 3 恒真)|
| **B1②** | `summary_confidence` 无生产者(`views_api` 里是硬编码 `0.0`)|
| **A1** | `rerank_with_llm` 未接线 —— 定义在 `vector_semantic.py`,唯一调用点在自己模块的 `main()` 演示里;真检索走 `rrf_fusion` 后**直接截断**,没有重排那一步。**改它要先做 DEC**(接进去 / 还是删掉或标"未启用") |
| **E** | 性能断言缺口:`性能基线与容量规划.md` 声称"排序验证结论…断言通过",但测试只断言了 2 条关系 |
| **待裁决** | embedding 超时不一致(15s vs 30s)· `set_profile_value` 负 TTL 无校验 · `requirements.txt` 在 3.9 装不上 |
| **D4** | `search_rag_knowledge` 同一查询查两遍 + BM25 语料每次现建 |
| **口令轮换** | 旧 PG 口令仍在公开 git 历史里,改代码抹不掉 —— 需 `ALTER USER` + 更新 `.env` |

> ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正

> ⚠️ **第 1 轮已修的:A2 · C2 · D1 · D2 · B2 · B3 · D3**,外加两条新发现(**删除不清缓存** · 7 个模块的死 `PG_CONN`)。
> 细节与证据全在 `CHANGELOG.md` 与复盘里 —— **别再照待修清单去"修"已修好的东西**。
Expand All @@ -172,6 +175,31 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
**⇒ 落笔前先报三个数**:① 仓总行数 ② 我读了多少行 ③ 哪几块没读 —— **报完再下结论**。
推论:**凡引用本仓文档中的结论(如性能数字、用例数、架构承诺),先在代码里找到出处**;找不到出处的,标注为"文档自述,未核实"。

### 7.1 ⛔ TDD:改代码 / 提交前**必须**走红绿

> 用户 2026-09-21 定:**「tdd红绿测试是代码修改和提交前必做」**。
> 触发条件见 skill `test-driven-development`:**任何新功能 / 修 bug / 重构 / 行为变更**。

**铁律:没有失败的测试,不写生产代码。**

```
RED → 写一个最小的、描述**期望行为**的测试
⏸ → **跑它、看着它为对的原因失败**(不是笔误、不是环境错)
GREEN → 只写够让它通过的最小代码
⏸ → 再跑,看它通过、且别的没坏
REFACTOR → 只在绿了之后清理
```

**两条判据**(本项目已踩过的坑):
1. **RED 必须"看着"发生** —— 先写代码再补测试,测试会立刻绿,**那证明不了它能抓到 bug**。
第 1 轮的做法(实现 → 补测 → 用 `git stash` 回退旧代码看它变红)**能证明用例有效,但不是 TDD**:
它管不到"实现写错会怎样"。第 2 轮起改为先红后绿。
2. **新用例不得立刻变绿** —— 若一写就过,说明它在测**已有行为**,要问:我到底想改什么?
3. **新测试文件必须同时加进 `pytest.ini` 的 `testpaths`** —— 它是显式枚举的,不加就**不会被收集**
(第 2 轮真踩过:新文件 6 个用例写好了,`pytest` 却是 39 passed —— 没被收)。
4. **⛔ 判据里不许出现没有生产者的量** —— A3 的成因就是 `summary_confidence` 恒为 `0.0` 却卡在判据里。
要么连生产者一起做,要么把参数删掉(别留着旋钮没人转)。见 `DEC-003`。

---

## 8 · 推送节奏(跨项目纪律)
Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
- 六类记忆存储:KV 精准 / Summary 摘要 / Ledger 账本 / 向量语义 / 程序性记忆 / RAG 外部知识
- 五层检索优先级:KV → Summary → Ledger → Skills → RAG
- 统一入口:`record_event()`(写入) / `query_memory()`(读取)
- 完整测试:26 个用例(确定性 / 回溯 / 隔离 / 进化 / 性能)
- 完整测试:**58 个用例**(确定性 / 回溯 / 隔离 / 进化 / 性能 / 淘汰 / 生成守卫 / RAG 条件性)
⚠️ 其中 13 个依赖 Ollama `bge-m3`,用 `pytest -m "not requires_ollama"` 可只跑不依赖 embedding 的 45 个

## 快速开始

Expand Down Expand Up @@ -35,7 +36,8 @@ ollama pull bge-m3 # embedding 模型,用于向量检索与技能
### 4. 跑测试

```bash
pytest # 26 个用例(配置见 pytest.ini)
pytest # 58 个用例(配置见 pytest.ini)
# 不想起 Ollama:pytest -m "not requires_ollama"(45 个)
```

## 架构一览
Expand Down Expand Up @@ -188,7 +190,7 @@ memory-system/
├── skill_matcher_v2.py # description 语义匹配复用
├── rag_knowledge.py # RAG 外部知识 + 版本快照
├── retrieval_orchestrator.py # 五层检索编排
├── test_day17/18/19_*.py # 测试(26 用例)
├── test_day17~23_*.py # 测试(58 用例;day18/19 依赖 Ollama)
├── conftest.py # 测试统一清理(user_test_%)
└── docs/*.md # 架构 / 性能 / 阶段总结 / FAQ
```
Expand All @@ -203,7 +205,9 @@ memory-system/

## 技术栈

PostgreSQL 16 + pgvector · Redis 7 · Python 3.9 · Ollama(bge-m3 embedding)· DeepSeek API
PostgreSQL 16 + pgvector · Redis 7 · **Python 3.11** · Ollama(bge-m3 embedding)· DeepSeek API

> ⚠️ 原写「Python 3.9」——**已不成立**:依赖里的 `urllib3==2.6.3` 现要求 ≥3.10(实测装不上)。详见 `requirements.txt` 头部。

## 文档导航

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# DEC-003 · 「内部结果是否完整」用什么判据(RAG 条件性调用)

| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已裁决 |
| **触发** | `audit源码通读-待修清单-20260921.md` **A3**(RAG「条件性」名实不符)+ **B1**(`summary_confidence` 无生产者) |
| **相关** | `policy_api.is_result_complete` / `should_call_rag` · `rag_knowledge.rag_conditional_search` · `views_api` |

---

## 一 · 问题

`ARCHITECTURE.md §1` 承诺:**RAG 是条件性调用 —— 不默认触发,避免无谓的外部查询。**
但按实际取值路径,**除了 KV 命中,其余查询都会触发 RAG**。

**证据链**(全部实读):

1. `retrieval_orchestrator._search_kv` 只在 query 含「位置 / 在哪 / location / 偏好 / 语言 / preference」时才返回结果,
其余查询 `kv_result = None`
2. `should_call_rag` 条件 3:只要有任一层命中,就检查 `is_result_complete`
3. `is_result_complete` 要求 `summary_confidence >= 0.6 **且** summary_count >= 2`
4. **但 `summary_confidence` 恒为 `0.0`** —— 全仓唯一字面量是 `views_api` 里的硬编码,
`rag_knowledge` 那条调用链**根本不传**
⇒ 该分支永不成立 ⇒ `is_result_complete` 恒为 False ⇒ **条件 3 恒真 ⇒ 必调 RAG**

**⇒「条件性」退化成「非 KV 命中即调用」,外部检索频率被系统性低估。**

## 二 · 备选方案(三选一)

| 方案 | 做法 | 优 | 劣 |
|---|---|---|---|
| A. 补一个真的 `summary_confidence` | 让 `summary_api` 产出真实置信度(如摘要与 query 的相似度) | 判据最有信息量 | **高成本**:要给摘要做 embedding 相似度 ⇒ 引入新的 embedding 调用;且阈值 0.6 从哪来也无依据 |
| **B. 去掉对它的依赖,只用有生产者的量** ✅**选定** | 完整性 = KV 命中 **或** `summary_count >= 2` | 判据的每个输入**都有生产者**;不新增 embedding 成本;立刻让「条件性」成立 | 判据粒度变粗(只看条数,不看相关度) |
| C. 保留参数但"没传就不拦" | 保留 `summary_confidence`,缺省时不参与判定 | 改动最小 | **仍然是幻影旋钮** —— 参数在、没人生产、读代码的人会以为它生效(这正是 A3 的成因) |

**选 B 的核心理由**:**判据里不许出现没有生产者的量。**
这条判据是本次两个条目(A3 + B1)的共同根因,比"这次用什么阈值"更重要。

## 三 · 决定

1. `is_result_complete(kv_result, summary_result, summary_count)` —— **移除 `summary_confidence` 形参**。
完整性判定:**KV 命中 → 完整**;否则 **`summary_count >= SUMMARY_COMPLETENESS_MIN_COUNT` → 完整**;否则不完整。
2. 新增常量 `SUMMARY_COMPLETENESS_MIN_COUNT = 2`(沿用原判据里的"2 条",**不新造阈值**)。
3. `should_call_rag(...)` 同步**移除 `summary_confidence` 形参**,并更新两处调用方
(`rag_knowledge.rag_conditional_search` · `views_api`)。
4. **接线**:`rag_conditional_search` 把 `summary_result["summary_count"]` 传下去
(`unified_search` 早就把它放在 `summary_result` 里了,只是没人往下传)。

## 四 · 若将来要做「真实的置信度」

**必须连同生产者一起做**(`summary_api` 产出 + 本文件更新 + 测试),
⛔ **不许**先把参数加回来、指望以后有人填 —— 那正是本次要消除的形态。
`views_api` 里那句注释「第8天实现 Summary 后提供真实置信度」应视为**未兑现的承诺**,随本次一并删除。

## 五 · 验收判据

- [ ] **RED**:`should_call_rag(summary_count=3, 无 KV, 无 rag_reference, query 无外部关键词)` 目前返回 True(应为 False)
- [ ] **GREEN**:同上一例返回 **False**(不调 RAG)
- [ ] **不过度纠正**:`summary_count=1` 时仍返回 **True**(内部确实不足)
- [ ] **接线**:`rag_conditional_search` 传入 `summary_count=3` 时 `should_use_rag=False`
- [ ] 全量 52+ 用例仍绿

## 六 · 反悔成本

低。判据集中在 `is_result_complete` 一个函数;阈值是一个具名常量。
若将来要换回"带置信度"的判据,在**补出生产者**之后改这一个函数即可。
Loading
Loading