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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,15 @@
- **`CLAUDE.md` 保鲜** —— 清掉 5 处已过时的警告(如"Ollama 未安装"、"7 个模块留着死 `PG_CONN`"、
"15s 超时待修"、"45 passed"),**过时的警告比没有更坏**

### C1 · `TTL_SKILLS` 未使用 → **删除**(2026-09-21)

- `cache_manager.py` 的 `TTL_SKILLS = 86400 * 365` 全仓**零引用**;技能摘要实际走 `TTL_SUMMARY=3600`
- 而 `ARCHITECTURE.md §5` 曾把它当**生效项**写进「分层 TTL:KV 60s / Summary 3600s / **Skills 1 年**」——**是假的**
- **裁决:删除,而不是"接上去"** —— 1 年缓存意味着技能更新后**脏一年**;
且技能匹配(`skill_matcher_v2`)读的是磁盘 `skills/` 目录,**根本不吃这个缓存**。
意图(技能少变 ⇒ 缓存久)不成立 ⇒ 与 A3/D3 同一条纪律:**别留旋钮没人转**
- 代码里留了「为什么删、别再加回来」的说明;§5 与 §11 同步更正

### 修订(Changed)· **CI 改成两个 job 都阻断**

- 去掉 `test-embedding` 的 `continue-on-error: true`(**推翻 DEC-002 原裁决**,当日修订,见该文档 §七)
Expand Down
31 changes: 28 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,11 +160,13 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索)
|---|---|
| ~~**A1**~~ | ✅ **已裁决:不接,明确标注未启用**(`DEC-004`)。docstring 已写「⛔ 未启用」+ 为什么 + 将来怎么启用;`ARCHITECTURE.md §11` 同步 |
| ~~**E**~~ | ✅ 已处置(`DEC-005`):断言只保留**稳定成立**的关系;`Vector<RAG` 实测不成立(差 6%),已在文档与测试里改掉 |
| ~~**D4**~~ | ✅ 已处置(`DEC-006`):合并为一次查询;BM25 索引缓存**有意不做**(失效边界会静默返回过期结果) |
| ~~**D4**~~ | ✅ 已处置(`DEC-006`):合并为**一次查询**(先核实过"没有向量索引可丢");BM25 索引缓存**有意不做** |
| ~~**C1**~~ | ✅ 已处置:`TTL_SKILLS` **删除**(不是"待落地",是意图不成立 —— 1 年缓存会让技能更新后脏一年,而技能匹配读磁盘、不吃这缓存) |
| ~~**口令轮换**~~ | ✅ 已完成(2026-09-21):旧口令失效,`.env` 已更新 |
| — | **audit 清单至此全部处置完毕**(A1–A3 · B1–B3 · C1–C2 · D1–D4 · E) |

> ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正
> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,标注未启用,见 DEC-004)· **E**(性能断言:**`Vector<RAG` 不成立**,改为只断言稳定关系,见 DEC-005)
> ✅ 第 2 轮:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正
> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,见 DEC-004)· **E**(性能断言:**`Vector<RAG` 不成立**,见 DEC-005)· **D4**(检索合并为一次查询,见 DEC-006)· **C1**(删 `TTL_SKILLS`)· 口令轮换 · CI 改双 job 阻断

> ⚠️ **第 1 轮已修的:A2 · C2 · D1 · D2 · B2 · B3 · D3**,外加两条新发现(**删除不清缓存** · 7 个模块的死 `PG_CONN`)。
> 细节与证据全在 `CHANGELOG.md` 与复盘里 —— **别再照待修清单去"修"已修好的东西**。
Expand Down Expand Up @@ -254,6 +256,29 @@ git log --oneline origin/main..HEAD # 核对:应只剩你自己
> `git fetch` 失败时 `git merge --ff-only origin/main` 会说 **「Already up to date」—— 那是假的**。
> **判据:`git ls-remote origin refs/heads/main` 读实际值,别信提示。**

### ⚠️ `gh` 通、`git` 不通 —— 判断真实远端状态要用 `gh` / `ls-remote`

**本机实测(2026-09-21)**:`git fetch/push` 连续 6 次 16 秒超时(`Failed to connect to github.com port 443`),
**而同一时刻 `gh pr view` / `gh run list` 正常返回** —— 两者走不同路径,会**各自独立地**断。

⇒ **判据**:
- 远端到底合没合、CI 绿没绿 ⇒ 用 **`gh pr view --json state,mergedAt,mergeCommit`** / **`gh run list --branch main`**
- 远端 main 的真实 SHA ⇒ 用 **`git ls-remote origin refs/heads/main`**(它也要网络,失败就**直说拿不到**)
- ⛔ **别拿本地 `origin/*` ref 当"已同步"** —— 它只在**成功的** fetch 后才更新。

> 📌 本次真实踩到:合并 PR #6 后网络断了,本地 `origin/main` 仍停在旧 SHA,
> 于是本地跑出的是**旧主干**的用例数(58 而非 61)。**差点把过期签出当成"主干已验证"。**
> ⇒ **要报"主干验证过",先确认你要么 `ls-remote` 读到了新 SHA,要么依据的是主干上的 CI 结果。**

### ⛔ 合并后别手动推进本地 main(会与 squash 分叉)

squash 合并产生的是**新 SHA**(内容同、身份不同)。若本地因网络拿不到它,
**⛔ 不要**手动把本地 main 推到本地那个未 squash 的提交 —— 那会让两边**分叉**,
下次 `pull` 就变成"合并"而不是快进。

**正确做法**:网络恢复后 `git fetch origin` → `git merge --ff-only origin/main`。
拿不到就**如实说"本地落后"**,别用本地状态冒充远端状态。

### 🔐 Public 仓专属:推之前先做密钥检查


Expand Down
12 changes: 10 additions & 2 deletions cache_manager.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,17 @@ def sliding_key(user_id: str, entity_id: str) -> str:

# ==================== 分层 TTL ====================
TTL_KV = 60 # KV 层:60 秒(可能频繁变)
TTL_SUMMARY = 3600 # Summary 层:1 小时
TTL_SUMMARY = 3600 # Summary 层:1 小时(**技能摘要也走它**,见 event_bus)
TTL_RAG = 300 # RAG 层:5 分钟
TTL_SKILLS = 86400 * 365 # Skills 层:永久(1 年近似)
# ⚠️ TTL_RAG 已定义但**未被任何代码使用**(search_rag_knowledge 不缓存)——
# 登记在 ARCHITECTURE.md §11,属"潜在待落地项",不是遗漏。
#
# ⛔ 此处原有一个 `TTL_SKILLS = 86400 * 365`("Skills 层:1 年"),已于 2026-09-21 删除(audit C1):
# · 全仓**零引用**;技能摘要实际走的是 event_bus 里的 TTL_SUMMARY=3600
# · 而 ARCHITECTURE.md §5 曾把它当**生效项**写进"分层 TTL"——那是**假的**
# · 为什么不"接上去":1 年的缓存意味着技能更新后**脏一年**;
# 而技能匹配(skill_matcher_v2)读的是磁盘 `skills/` 目录,**根本不吃这个缓存**
# ⇒ 意图(技能少变 ⇒ 缓存久)不成立,留着只会误导。**别再加回来。**


# ==================== 缓存 API ====================
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# DEC-007 · `TTL_SKILLS` 删除还是接上

| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已裁决:**删除** |
| **触发** | `audit源码通读-待修清单-20260921.md` **C1** ——「`TTL_SKILLS` 从未被任何代码使用」 |
| **相关** | `cache_manager.py` · `event_bus._update_redis_cache` · `DEC-004`(同类:都不接) |

---

## 一 · 问题

`cache_manager.py` 里 `TTL_SKILLS = 86400 * 365`("Skills 层:1 年")**全仓零引用**;
而 `ARCHITECTURE.md §5` 把它当**生效项**写进了「分层 TTL」:

> 分层 TTL:KV 60s / Summary 3600s / **Skills 1 年(86400×365)** ← **这一句是假的**

**实际**:技能摘要走的是 `event_bus._update_redis_cache` 里的 **`TTL_SUMMARY = 3600`**(注释写的也是"技能摘要 1 小时")。

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

| 方案 | 做法 | 优 | 劣 |
|---|---|---|---|
| A. 接上去 | 让 `skill:` 缓存条目改用 `TTL_SKILLS`(1 年),使文档那句话成真 | 文档不用改;"技能少变 ⇒ 缓存久"听上去合理 | **1 年缓存 ⇒ 技能更新后脏一年**;且**白付代价**:技能匹配读的是磁盘 `skills/` 目录,**根本不吃这个 Redis 条目** |
| **B. 删除常量并改正文档** ✅**选定** | 删 `TTL_SKILLS`;§5 改成事实;代码里留"为什么删、别再加回来" | 消除一个假承诺;不留旋钮 | 少一个"也许将来能用"的常量 |

**选 B 的核心理由**:方案 A 的收益是**零**(这条缓存没人读),代价是**确定的**(陈旧风险 + 维护一个假承诺)。
这与 `DEC-004`(重排序不接)是同一条纪律:**别留旋钮没人转**。

## 三 · 决定

1. 删除 `TTL_SKILLS`,并在原处留说明:为什么删、别再加回来。
2. `ARCHITECTURE.md §5` 改正为:`KV 60s / Summary 3600s(**技能摘要也走它**)`;并保留 `TTL_RAG` 未使用的既有登记。
3. `ARCHITECTURE.md §11` 补第 6 条,说明**这不是"待落地",而是意图不成立**。

## 四 · 与 `TTL_RAG` 的差别(为什么不一起删)

`TTL_RAG = 300` 同样未被使用,但**两者性质不同**,故处置不同:

| | `TTL_SKILLS` | `TTL_RAG` |
|---|---|---|
| 若接上 | 1 年缓存 ⇒ **脏一年**;且那条缓存无人读 | 5 分钟缓存 RAG 结果 ⇒ 时长合理,是**真实可行的待落地优化** |
| 处置 | **删除**(意图不成立) | **保留**(已在 §11 登记为潜在待落地项,并在代码处加注) |

⇒ 判据:**"未使用"不等于"该删"** —— 要看**接上之后是否成立**。

## 五 · 反悔成本

低。若将来真的要让技能相关缓存长驻,**不要复活这个常量** ——
正确做法是另开 DEC,说明**谁来读这条缓存**、**技能更新时如何失效**,并补一条
"技能更新后不得读到旧值"的测试。
Loading