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
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,16 @@
⇒ **不只是"文档没验证过",而是那句话本身不成立**。文档已改成与事实相符,
并发耗时列标注为**记录值、非断言值**。判据与证据见 **`DEC-005`**
(「断言只能写机制决定的关系,不能写当次测量决定的关系」)
- **D4 · `search_rag_knowledge` 查两遍** —— ✅ 合并为**一次查询**(`DEC-006`)。
**先核实"合并会不会丢掉索引优化"**:`content_embedding` 上**没有任何向量索引**,
原 `ORDER BY cosine_distance LIMIT k` 本来就是全表扫描 + 排序 ⇒ 合并**零损失**。
TDD:先写 `test_day24`(3 用例)—— 特征测试 2 条**重构前后都绿**(安全网),
往返次数那条**先红**(实测 2 次)→ 改完变绿(1 次)。
⚠️ **有意不做** BM25 索引缓存:失效边界不好划,键选错会**静默返回过期结果**(比慢更糟)—— 理由见 `DEC-006 §四`
- **🔧 顺带修掉一个反复踩中的陷阱**:`pytest.ini` 从**逐个文件名枚举**改为**自动收集**
(`testpaths = .` + `norecursedirs`)。本仓**第三次**撞上"新测试文件不加进 testpaths 就不被收集"
—— `pytest` 会**静默少跑**,看着绿其实没测。⛔ `norecursedirs` 必须含 `memory-system-venv`
(pytest 默认只认 "venv" 这个名字)
- **`CLAUDE.md` 保鲜** —— 清掉 5 处已过时的警告(如"Ollama 未安装"、"7 个模块留着死 `PG_CONN`"、
"15s 超时待修"、"45 passed"),**过时的警告比没有更坏**

Expand Down Expand Up @@ -140,6 +150,13 @@
- ✅ `git grep memory_pass_2026` **零命中**
- ⚠️ **旧口令仍在公开 git 历史里** —— 改代码抹不掉历史,**要真正消除暴露必须轮换口令**(待办)

### 安全(续)· **旧口令已轮换失效**(2026-09-21)

- `ALTER USER memory_user PASSWORD <新值>` + 更新 `.env`(不入库)
- **实测验证**:旧口令登录**被拒** ✓;新口令走代码正式路径可连 ✓
- ⇒ **改代码抹不掉历史,唯一解是让历史里的值失效** —— 不是删历史,是让那个值没用
- ⛔ 仍不得在任何真环境复用 `memory_pass_2026`(它在历史上仍是公开的)

### 挂起(Blocked)


Expand Down
18 changes: 11 additions & 7 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,11 +128,15 @@ 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` 里有注释写明)。
- **当前 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)。
- **当前 61 用例** = `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 轮新增的两个文件都加了)。
- **`pytest.ini` 已改为自动收集**(`testpaths = .` + `norecursedirs`)——
新加 `test_*.py` 放仓根即被收,**不必再改 testpaths**。
⚠️ 这条改动修的是一个**反复踩中**的陷阱:枚举式 testpaths 下,新文件不加就**静默不跑**、看着绿其实没测
(本仓撞过 3 次:day20 / day22 / day24)。⛔ 若你新加了目录,记得同步 `norecursedirs`
(**必须含 `memory-system-venv`** —— pytest 默认只认 "venv" 这个名字)。
- **新增用例要做反证**:用 git 取旧代码(`git stash push -- <file>` 或 `git show HEAD:<file>`)确认用例**真的会红**,否则等于没测。
- `perf_baselines.json` 是 `test_day19` 的**追加式**产物,已 gitignore(本仓不存在,原目录有)。

Expand All @@ -156,8 +160,8 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
|---|---|
| ~~**A1**~~ | ✅ **已裁决:不接,明确标注未启用**(`DEC-004`)。docstring 已写「⛔ 未启用」+ 为什么 + 将来怎么启用;`ARCHITECTURE.md §11` 同步 |
| ~~**E**~~ | ✅ 已处置(`DEC-005`):断言只保留**稳定成立**的关系;`Vector<RAG` 实测不成立(差 6%),已在文档与测试里改掉 |
| **D4** | `search_rag_knowledge` 同一查询查两遍 + BM25 语料每次现建 |
| **口令轮换** | 旧 PG 口令仍在公开 git 历史里,改代码抹不掉 —— 需 `ALTER USER` + 更新 `.env` |
| ~~**D4**~~ | ✅ 已处置(`DEC-006`):合并为一次查询;BM25 索引缓存**有意不做**(失效边界会静默返回过期结果) |
| ~~**口令轮换**~~ | ✅ 已完成(2026-09-21):旧口令失效,`.env` 已更新 |

> ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正
> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,标注未启用,见 DEC-004)· **E**(性能断言:**`Vector<RAG` 不成立**,改为只断言稳定关系,见 DEC-005)
Expand Down Expand Up @@ -259,9 +263,9 @@ git log --oneline origin/main..HEAD # 核对:应只剩你自己
- ✅ **跟踪文件里的明文口令已清零**(2026-09-21):`PG_PASSWORD` 与 `REDIS_*` 已改为从 `.env` 读,
`db_pool` / `cache_manager` 是唯一来源,`event_bus` 复用它们;`docker-compose` 用 `${PG_PASSWORD:?}`。
`git grep memory_pass_2026` 现在**零命中**。
- ⚠️ **但旧口令仍留在公开的 git 历史里** —— 改代码**不能**把它从历史中抹掉。
**要真正消除暴露,得轮换口令**(`ALTER USER` + 更新 `.env`),让历史里那个值失效。
⛔ **且永远别在任何真环境复用 `memory_pass_2026` 这个值**。
- ✅ **旧口令已于 2026-09-21 轮换**(`ALTER USER` + 更新 `.env`)—— **历史里那个值现已失效**
(实测旧口令登录被拒)。这是"改代码抹不掉历史"的唯一解:不是删历史,是**让历史里的值变成没用的**。
⛔ **仍别在任何真环境复用 `memory_pass_2026`**(它在历史上仍是公开的)。
- ⛔ **绝不**把 `DEEPSEEK_API_KEY` 之类真密钥写进代码或提交 `.env`(代码只从环境变量读,保持住)。
- 推之前可跑 `/留痕-checks` 做体检(查明文密钥、误提交文件、CI 状态)。

95 changes: 95 additions & 0 deletions docs/decisions决策/DEC-006-rag检索的往返次数-20260921.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# DEC-006 · `search_rag_knowledge` 到底要查几次库

| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已处置(合并为一次查询;BM25 索引缓存**有意不做**,理由见 §四) |
| **触发** | `audit源码通读-待修清单-20260921.md` **D4** ——「同一查询查两遍 + BM25 语料每次现建」 |
| **相关** | `rag_knowledge.search_rag_knowledge` · `test_day24_rag_search_roundtrip.py` · `pytest.ini` |

---

## 一 · 问题

`search_rag_knowledge` 对**同一张表、同一过滤条件**发两次查询:

| # | 目的 | 形态 |
|---|---|---|
| 1 | 取**全部** active 行 → 喂 BM25 当语料 | `SELECT ... WHERE status='active' AND tenant_id=%s [AND source=%s]`(无 ORDER BY) |
| 2 | 取**距离最近的 k 条** | 同一张表同样过滤 + `content_embedding <=> %s` + `ORDER BY cosine_distance LIMIT k` |

⇒ 一次请求两次往返(且第二次要先把查询向量算出来,即 `_get_embedding` 夹在两次查询之间)。

## 二 · 关键核实:合并会不会丢掉"索引优化"?

**直觉上会** —— 合并意味着"取回全部行再在 Python 里排",看起来放弃了数据库的 top-k 能力。

**但实测核实:不会**,因为**根本没有向量索引**可丢:

```
rag_knowledge_base 上的索引:
rag_knowledge_base_pkey PRIMARY KEY (knowledge_id)
idx_rag_kb_source btree (source)
idx_rag_kb_version btree (version)
← content_embedding 上没有任何 hnsw / ivfflat 索引
```

⇒ 原来那句 `ORDER BY cosine_distance LIMIT k` **本来就是全表扫描 + 排序**。
合并成一次查询后,把同样的排序搬到 Python,**在规模上没有任何损失**。

> 📌 本条是本 DEC 的实质:**"合并会不会更慢"必须先看有没有索引可丢**,
> 不能凭"聚合查询更慢"的一般印象下判断。

## 三 · 决定

**合并为一次查询**:带上 `content_embedding <=> %s::vector AS cosine_distance` 取回全部行,然后:

- `all_records`:全部行 → 喂 BM25(顺序不影响打分)
- `vector_results`:按**原始距离**升序取前 `limit*3` 条
- ⚠️ **必须用原始距离排,不能用四舍五入后的 `similarity`** ——
极近的距离会因取整而换序,那就不再等价于原 SQL 的 `ORDER BY cosine_distance`
- `_get_embedding(query)` 上移到唯一那次查询之前

**等价性**:结果集与排序均与原实现一致(原 SQL 排的就是同一个距离)。

## 四 · 有意**不做**:BM25 语料/索引的缓存

audit 还提到「`BM25Okapi(corpus)` 每次调用现建索引」。**本次不做**,理由:

1. **合并后,语料本来就每次都要取回来**(BM25 要全量语料),省不掉那趟 IO;
能省的只是 `BM25Okapi` 的构造与 jieba 分词。
2. **缓存的失效边界不好划**:语料随 `add_external_knowledge` 变化,
要么在写入端做失效(多一处耦合),要么按键(行数/最新时间)判缓存 ——
键选错就会**静默返回过期检索结果**,那是比慢更糟的错。
3. 当前数据量下**无感**(audit 自己也标了这一条为低优先)。

⇒ 按"**别留旋钮没人转**"的同一条纪律:**宁可先不做,也不留一个半正确的缓存**。
若将来规模上来,正确做法是**在 `add_external_knowledge` 里显式失效**,并补一条
"写入后检索必须看到新内容"的测试 —— 届时另开 DEC。

## 五 · 验收判据

- [x] **RED**:`test_search_uses_single_round_trip` 修复前 FAIL(实测 **2 次**往返)
- [x] **GREEN**:修复后 PASS(**1 次**)
- [x] **安全网**:`test_search_returns_relevant_row_first` / `test_search_respects_source_and_tenant_filter`
在重构**前后都通过**(特征测试,锁住行为不变)
- [x] 全量 `pytest` 61 passed

## 六 · 顺带修掉一个反复踩中的陷阱(`pytest.ini`)

本次新增 `test_day24` 时**第三次**撞上「新文件不加进 `testpaths` 就不被收集」——
`pytest` 会静默少跑,看着绿其实没测。已把 `pytest.ini` 从**逐个文件名枚举**改为**自动收集**:

```ini
testpaths = .
norecursedirs = memory-system-venv data .git __pycache__ archive docs .github
```

⛔ `norecursedirs` 里**必须**写 `memory-system-venv` —— pytest 默认只认 "venv" 这个名字,
而本仓的 venv 叫 `memory-system-venv`(README 起的名),不排除就会把 site-packages 里的测试扫进来。

## 七 · 反悔成本

低。若将来加了向量索引(hnsw/ivfflat),则"取回全部行"会变得不划算 ——
届时应**退回两次查询**(让索引做 top-k),并更新本 DEC。
判据同 §二:**先看索引,再决定查几次。**
16 changes: 13 additions & 3 deletions pytest.ini
Original file line number Diff line number Diff line change
@@ -1,10 +1,20 @@
[pytest]
testpaths = test_day17_deterministic_backtrack.py test_day18_evolution_conditional.py test_day19_performance_stability.py test_day20_kv_demotion.py test_day21_skill_generator_guard.py test_day22_embedding_contract.py test_day23_rag_conditional.py
# ⚠️ 2026-09-21 改成**自动收集**(原来是逐个文件名枚举)。
# 原因:枚举式的 testpaths 有个反复踩中的陷阱 ——
# **新加的测试文件不加进来就不会被收集**,而 `pytest` 会静默少跑,
# 看着是绿的、其实没测(本仓 3 次撞上:day20/day22/day24)。
# 改成 `.` + 显式排除目录后,新文件 `test_*.py` 放进仓根就自动被收。
testpaths = .
norecursedirs = memory-system-venv data .git __pycache__ archive docs .github
# ↑ ⛔ 必须排除 memory-system-venv —— pytest 的默认 norecursedirs 只认"venv"这个名字,
# "memory-system-venv" 不在其中,会把 site-packages 里的测试文件一起扫进来。
# (本仓 venv 目录名来自 README,见 CLAUDE.md §2)

addopts = -ra
filterwarnings =
ignore:.*NotOpenSSLWarning.*
ignore:.*urllib3.*
markers =
requires_ollama: 需要本地 Ollama + bge-m3 才能跑(CI 默认跳过)
requires_ollama: 需要本地 Ollama + bge-m3 才能跑
—— 用 `pytest -m "not requires_ollama"` 跳过,`pytest -m requires_ollama` 只跑这些。
见 .github/workflows/tests.yml(那个 job 设了 continue-on-error,因为它依赖 CPU 推理且含性能断言)
见 .github/workflows/tests.yml(两个 job 都阻断,见 DEC-002 §七)
70 changes: 29 additions & 41 deletions rag_knowledge.py
Original file line number Diff line number Diff line change
Expand Up @@ -159,32 +159,45 @@ def search_rag_knowledge(query: str, source: Optional[str] = None, limit: int =
- tenant_id: 租户 ID,用于多租户隔离,默认 public

返回: 检索结果列表

⚠️ 2026-09-21(audit D4):本函数此前**同一张表、同一过滤条件查两遍**
(一次取全部行喂 BM25 语料,一次取 top-k 算余弦距离)。现合并为**一次查询**:
带上 `cosine_distance` 取回全部行,top-k 在 Python 里排。
**不会损失索引优化** —— `content_embedding` 上没有任何向量索引
(只有 pkey + 两个 btree),原来那句 `ORDER BY cosine_distance LIMIT k` 本来就是全表扫描 + 排序。
见 `docs/decisions决策/DEC-006-rag检索的往返次数-20260921.md`
"""
# 获取外部知识库中的所有记录(或按 source 过滤)
# 查询向量先算 —— 下面那唯一一次查询要用它
query_embedding = _get_embedding(query)

# 唯一一次查询:取回该(租户[, 来源])下全部 active 记录,并顺带算出余弦距离
with get_cursor() as cur:
if source:
cur.execute(
"""
SELECT knowledge_id, source, title, content, version, updated_at, metadata
SELECT knowledge_id, source, title, content, version, updated_at, metadata,
content_embedding <=> %s::vector AS cosine_distance
FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s AND source = %s
""",
(tenant_id, source),
(query_embedding, tenant_id, source),
)
else:
cur.execute(
"""
SELECT knowledge_id, source, title, content, version, updated_at, metadata
SELECT knowledge_id, source, title, content, version, updated_at, metadata,
content_embedding <=> %s::vector AS cosine_distance
FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s
""",
(tenant_id,),
(query_embedding, tenant_id),
)
rows = cur.fetchall()

if not rows:
return []

# 构建临时向量检索结果和 BM25 检索结果
# 注意:这里需要把外部知识库记录转换成与 vector_semantic 检索函数兼容的格式
# 同一次结果同时喂两条检索链:
# · all_records —— BM25 的语料(**全部行**;顺序不影响 BM25 打分)
# · vector_results —— 向量侧只取距离最近的 limit*3
all_records = []
for row in rows:
all_records.append({
Expand All @@ -197,47 +210,22 @@ def search_rag_knowledge(query: str, source: Optional[str] = None, limit: int =
},
})

# 向量检索:我们需要基于 content_embedding 计算,而不是重新 embedding 所有记录
# 简单实现:临时构建一个向量结果,用 embedding 字段
query_embedding = _get_embedding(query)

vector_scores = []
with get_cursor() as cur:
if source:
cur.execute(
"""
SELECT knowledge_id, source, title, content, version, updated_at, metadata,
content_embedding <=> %s::vector AS cosine_distance
FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s AND source = %s
ORDER BY cosine_distance LIMIT %s
""",
(query_embedding, tenant_id, source, limit * 3),
)
else:
cur.execute(
"""
SELECT knowledge_id, source, title, content, version, updated_at, metadata,
content_embedding <=> %s::vector AS cosine_distance
FROM rag_knowledge_base WHERE status = 'active' AND tenant_id = %s
ORDER BY cosine_distance LIMIT %s
""",
(query_embedding, tenant_id, limit * 3),
)
rows = cur.fetchall()

vector_results = []
for row in rows:
similarity = 1.0 - float(row["cosine_distance"])
vector_results.append({
# 向量侧:与原 SQL `ORDER BY cosine_distance LIMIT limit*3` 严格等价 ——
# ⚠️ 必须按**原始距离**排序,不能用四舍五入后的 similarity(极近的距离会因取整换序)
nearest = sorted(rows, key=lambda r: float(r["cosine_distance"]))[: limit * 3]
vector_results = [
{
"id": row["knowledge_id"],
"content": f"{row['title']}:{row['content']}",
"similarity": round(similarity, 4),
"similarity": round(1.0 - float(row["cosine_distance"]), 4),
"metadata": {
"source": row["source"],
"version": row["version"],
"updated_at": str(row["updated_at"]),
},
})
}
for row in nearest
]

# BM25 检索
corpus = [_tokenize(r["content"]) for r in all_records]
Expand Down
Loading
Loading