From d926bf988c3bb206520c5ad7ac4ca9b3174808a5 Mon Sep 17 00:00:00 2001 From: heweidong-ecco <290444878+heweidong-ecco@users.noreply.github.com> Date: Mon, 21 Sep 2026 21:12:37 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20C1=20=E5=88=A0=E9=99=A4=20TTL=5FSKILLS?= =?UTF-8?q?=EF=BC=88=E5=81=87=E6=89=BF=E8=AF=BA=EF=BC=89+=20CLAUDE.md=20?= =?UTF-8?q?=E8=A1=A5=E4=B8=A4=E6=9D=A1=E6=93=8D=E4=BD=9C=E6=95=99=E8=AE=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 · TTL_SKILLS 从未被任何代码使用 → **删除,而不是接上去** · 全仓零引用;技能摘要实际走 event_bus 里的 TTL_SUMMARY=3600 · 而 ARCHITECTURE.md §5 把它当生效项写进「分层 TTL:…Skills 1 年」——**那句话是假的** · 为什么不接上:1 年缓存 ⇒ 技能更新后脏一年;且技能匹配读的是磁盘 skills/ 目录,**根本不吃这条 Redis 缓存** ⇒ 收益为零、代价确定 · 与 DEC-004(重排序不接)同一条纪律:别留旋钮没人转 留了「为什么删、别再加回来」的说明;§5/§11 同步更正 与 TTL_RAG 的区别(同是未使用,一个删一个留)见 DEC-007 CLAUDE.md §8 补两条本次真实踩到的操作教训 · **gh 通、git 不通**:git 传输连续 6 次 16s 超时,而同一时刻 gh pr view / gh run list 正常 ⇒ 判断真实远端状态要用 gh API / git ls-remote, ⛔ 别拿本地 origin/* ref 当"已同步"(它只在成功的 fetch 后才更新) —— 本次真实踩到:合并 PR #6 后网络断,本地跑出的是旧主干的用例数(58 而非 61), 差点把过期签出当成"主干已验证" · **合并后别手动推进本地 main**:squash 产生新 SHA,手动推到本地那个未 squash 的 提交会与远端分叉,下次 pull 变成合并而非快进 ⇒ 等 fetch 成功再 merge --ff-only; 拿不到就如实说"本地落后",别用本地状态冒充远端状态 提交前两问 ① 本次有决策事项 ⇒ 新建 DEC-007-TTL-SKILLS删除还是接上-20260921.md (二选一 + 与 TTL_RAG 为何一处删一处留的判据) ② CHANGELOG 已写(C1 小节) ⚠️ 本地落后于远端:本提交基于 2811d57,而远端 main 已是 b1f6356(PR #6 已合并)。 本机到 GitHub 的 git 传输当前持续失败,故**尚未推送**。 网络恢复后需:git fetch → 本地 main 快进 → 本分支 rebase 到新 main → 推 + PR。 测试:58 passed(这是本地过期主干的基线;C1 只删常量,不涉测试) --- CHANGELOG.md | 9 ++++ CLAUDE.md | 31 +++++++++-- cache_manager.py | 12 ++++- ...0\257\346\216\245\344\270\212-20260921.md" | 52 +++++++++++++++++++ 4 files changed, 99 insertions(+), 5 deletions(-) create mode 100644 "docs/decisions\345\206\263\347\255\226/DEC-007-TTL-SKILLS\345\210\240\351\231\244\350\277\230\346\230\257\346\216\245\344\270\212-20260921.md" diff --git a/CHANGELOG.md b/CHANGELOG.md index 11172cb..365bb6e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 原裁决**,当日修订,见该文档 §七) diff --git a/CLAUDE.md b/CLAUDE.md index 3a27d9e..cdae712 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -160,11 +160,13 @@ skill_candidate_store(候选 + 双阈值 0.85/0.65 检索) |---|---| | ~~**A1**~~ | ✅ **已裁决:不接,明确标注未启用**(`DEC-004`)。docstring 已写「⛔ 未启用」+ 为什么 + 将来怎么启用;`ARCHITECTURE.md §11` 同步 | | ~~**E**~~ | ✅ 已处置(`DEC-005`):断言只保留**稳定成立**的关系;`Vector ✅ 第 2 轮已完成:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正 -> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,标注未启用,见 DEC-004)· **E**(性能断言:**`Vector ✅ 第 2 轮:**A3**(RAG 条件性判据)· **B1①②**(接线 + 删幻影形参)· 挂 CI · 文档计数校正 +> ✅ 第 3 轮:**A1**(重排序:裁决为**不接**,见 DEC-004)· **E**(性能断言:**`Vector ⚠️ **第 1 轮已修的:A2 · C2 · D1 · D2 · B2 · B3 · D3**,外加两条新发现(**删除不清缓存** · 7 个模块的死 `PG_CONN`)。 > 细节与证据全在 `CHANGELOG.md` 与复盘里 —— **别再照待修清单去"修"已修好的东西**。 @@ -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 仓专属:推之前先做密钥检查 diff --git a/cache_manager.py b/cache_manager.py index 440e9fc..1c2ca57 100644 --- a/cache_manager.py +++ b/cache_manager.py @@ -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 ==================== diff --git "a/docs/decisions\345\206\263\347\255\226/DEC-007-TTL-SKILLS\345\210\240\351\231\244\350\277\230\346\230\257\346\216\245\344\270\212-20260921.md" "b/docs/decisions\345\206\263\347\255\226/DEC-007-TTL-SKILLS\345\210\240\351\231\244\350\277\230\346\230\257\346\216\245\344\270\212-20260921.md" new file mode 100644 index 0000000..28eb185 --- /dev/null +++ "b/docs/decisions\345\206\263\347\255\226/DEC-007-TTL-SKILLS\345\210\240\351\231\244\350\277\230\346\230\257\346\216\245\344\270\212-20260921.md" @@ -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,说明**谁来读这条缓存**、**技能更新时如何失效**,并补一条 +"技能更新后不得读到旧值"的测试。