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
18 changes: 10 additions & 8 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
# 本仓的 CI:跑 pytest。
#
# ⚠️ 为什么分两个 job(不是一个):
# · job `test`(**必过**)—— 只跑不依赖 embedding 的用例(day17/20/21/22)。
# · job `test` —— 只跑不依赖 embedding 的用例(day17/20/21/22)。
# 起 PG(pgvector) + Redis 服务容器,用仓内的 schema.sql 建表。
# · job `test-embedding`(**不阻断**)—— 额外装 Ollama + 拉 bge-m3,跑 day18/day19。
# 它设 continue-on-error 的原因有二:
# ① GitHub runner 只有 CPU,1.2 GB 的 bge-m3 走 CPU 很慢;
# ② day19 是**性能断言**(KV≤Ledger、RAG>KV),在共享 runner 上噪声大。
# 红了先判断是不是环境抖动,别当逻辑错。
# · job `test-embedding` —— 额外装 Ollama + 拉 bge-m3,跑 day18/day19。
#
# ✅ 两个 job **都阻断**(2026-09-21 用户裁决,推翻 DEC-002 原来的"后者不阻断")。
# 依据:`test-embedding` 在 CI 上**连续两次通过**(1m28s / 2m36s),
# 原先担心的两件事都没发生 —— ① CPU 推理没有慢到不可用;② 性能断言没有抖。
# ⇒ 让 13 个用例也有"第二双眼睛"。
# ⚠️ 若将来它开始 flaky:先看是不是 runner 负载/网络抖动(Ollama 拉模型走公网),
# 再考虑退回不阻断 —— 别第一反应就把它关掉。裁决与反悔成本见 DEC-002。
#
# ⚠️ CI 里的 PG 口令是**刻意的公开值**:容器是一次性的、只活在 runner 内网,不是机密。
# 真环境的凭据一律走 .env(不入库)—— 见 CLAUDE.md §8。
Expand Down Expand Up @@ -80,9 +83,8 @@ jobs:
run: pytest -m "not requires_ollama" -q

test-embedding:
name: pytest(含 embedding · 不阻断)
name: pytest(含 embedding)
runs-on: ubuntu-latest
continue-on-error: true

services:
postgres:
Expand Down
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ query_memory(user_id, query, session_id=None) -> Dict

> ⚠️ 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_day18/19 共 13 个依赖 Ollama `bge-m3`,CI 里单独成一个 job(**也阻断**,见 DEC-002 §七的修订)。

| 文件 | 用例数 | 覆盖 |
|---|---|---|
Expand Down
14 changes: 12 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,18 @@

- **`.github/workflows/tests.yml`** —— 本仓**首份 CI**(此前 `gh pr checks` → `no checks reported`,即**没有任何 CI**)
- job `test`(**必过**):PG(pgvector pg16) + Redis 服务容器 → `psql -f schema.sql` 建表 → `pytest -m "not requires_ollama"`(39 用例)
- job `test-embedding`(**不阻断**,`continue-on-error: true`):装 Ollama + 拉 `bge-m3` → `pytest -m requires_ollama`(13 用例)
- 为什么分两个 job、为什么后者不阻断 → **`docs/decisions决策/DEC-002-CI的embedding边界-20260921.md`**
- job `test-embedding`:装 Ollama + 拉 `bge-m3` → `pytest -m requires_ollama`(13 用例)
- 为什么分两个 job → **`docs/decisions决策/DEC-002-CI的embedding边界-20260921.md`**

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

- 去掉 `test-embedding` 的 `continue-on-error: true`(**推翻 DEC-002 原裁决**,当日修订,见该文档 §七)
- **推翻的依据是实测,不是判断**:该 job 在 CI 上**连续两次通过**(1m28s / 2m36s),
原先担心的"CPU 太慢"与"性能断言会抖"**都没发生**
- 元教训(已写进 DEC-002 §八):**别在没有任何实测数据时做预防性退让** ——
先按最严的做,观测到问题再退;而不是先退让、再等一个也许永远不会来的理由去收紧
- 同时把「**堆叠分支 + squash 合并 ⇒ 必须 `rebase --onto`**」写进 `CLAUDE.md §8`
(本次 PR #3 真实撞上:不 `--onto` 就会把已合并的 CI 改动重放一遍)
- **`requires_ollama` 标记** —— `pytest.ini` 注册;`test_day18` / `test_day19` 各加 `pytestmark`
- 本地同样可用:`pytest -m "not requires_ollama"`(39)/ `pytest -m requires_ollama`(13)
- ⚠️ `test_day19` 原本**没有 `import pytest`**,加标记时一并补上(否则 collection 直接 NameError)
Expand Down
23 changes: 23 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,8 +224,31 @@ REFACTOR → 只在绿了之后清理
(本地 `origin/main` ref 根本没更新)。**判据:读文件内容核对,别信那句提示。**
- 推送前**先 fetch**;fetch 失败**要重试**(本机实测失败过 2 次,重试第 1 次即通)。

### ⛔ 堆叠分支 + squash 合并 = 必须 `rebase --onto`

**squash 合并会把一整支压成一个新 SHA,原来的提交在 main 上就不存在了。**
若本地还有一支**从被 squash 的那支派生**出来的分支,直接推它会把**已经合并的改动重放一遍**
(PR diff 里出现重复内容,甚至冲突)。

**判据**:合并了 PR 之后,**先从新 main 派生的分支要 `rebase --onto`**,把已合并的那个提交摘掉:

```bash
git fetch origin # ⚠️ 失败要重试,别信 "Already up to date"
git checkout <你的分支>
git rebase --onto origin/main <被squash掉的提交SHA> # 只重放你真正新增的提交
git log --oneline origin/main..HEAD # 核对:应只剩你自己的提交
```

**本次实测(2026-09-21)**:PR #2(CI)squash 合并后,PR #3 那支就是从它派生的 ⇒
用 `git rebase --onto origin/main 6894442` 摘掉 `6894442` 才推干净。

> 📌 同族的假信号(第 1 轮就写进纪律里了,本次**真命中一次**):
> `git fetch` 失败时 `git merge --ff-only origin/main` 会说 **「Already up to date」—— 那是假的**。
> **判据:`git ls-remote origin refs/heads/main` 读实际值,别信提示。**

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


**判据:任何要提交的内容,先问「这段能不能贴到公网」。**

- ✅ **历史里从未提交过 `.env` / 密钥文件**(只有模板 `.env.example`)。`.gitignore` 已排除 `.env`。
Expand Down
37 changes: 36 additions & 1 deletion docs/decisions决策/DEC-002-CI的embedding边界-20260921.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
| 项 | 值 |
|---|---|
| **日期** | 2026-09-21 |
| **状态** | ✅ 已裁决(用户 2026-09-21 指示「把 pytest 挂成 GitHub Actions」) |
| **状态** | ⚠️ **已修订** —— 原选 C(后者不阻断),**当日被用户推翻,改为两个 job 都阻断**(见 §七) |
| **触发** | 本仓此前**没有任何 CI**(`gh pr checks` → `no checks reported`) |
| **相关** | `.github/workflows/tests.yml` · `pytest.ini` 的 `requires_ollama` 标记 · `DEC-001` |

Expand Down Expand Up @@ -50,3 +50,38 @@
低。要收紧成"embedding 也阻断",删掉 `continue-on-error: true` 即可;
要放宽成"只在手动触发时跑",给该 job 加 `if: github.event_name == 'workflow_dispatch'`。
**都不涉及代码改动**,只动本 workflow。

---

## 七 · ⚠️ 修订:当日推翻,改为**两个 job 都阻断**(2026-09-21)

### 为什么原裁决错了

原选 C 的两条担心,**在真实 CI 上都没发生**:

| 原担心 | 实测 |
|---|---|
| ① runner 只有 CPU,1.2 GB 模型走 CPU 太慢、不可用 | ❌ 没发生 —— `test-embedding` **1m28s / 2m36s** 跑完(含装 Ollama + 拉模型) |
| ② `test_day19` 是性能断言,共享 runner 上噪声大、必 flaky | ❌ 没发生 —— **连续两次通过**,排序断言没抖 |

**且原裁决的代价是实打实的**:13 个用例(`day18` 全部 + `day19` 全部)**永远没有 CI 把关** ——
而本机内存紧张(8 GB),它们在本地本来就跑得勉强。

### 修订后的决定

**删掉 `continue-on-error: true`,两个 job 都阻断。**
判据:**能不阻断就不阻断** —— 只有当"阻断带来的误报成本 > 漏报成本"时才退让,
而原裁决是在**没有一次真实运行数据**的情况下做的(属预防性退让)。

### 若将来它真的开始 flaky

⛔ **别第一反应就关掉它**。先分辨:
- **环境抖动**(runner 负载 / 拉模型走公网超时)⇒ 先重试,或给该 job 加缓存/超时
- **真 flaky**(同一 commit 重复跑,结果不稳定)⇒ 再考虑退回不阻断,并**更新本 DEC**

## 八 · 本次修订的元教训

> **别在没有任何实测数据时做预防性退让。**
> 原裁决的措辞是"因为它**会**很慢/很抖"—— 那是**推测**,不是观测。
> 正确顺序:先按最严的做(都阻断)→ 观测到问题再退;
> 而不是先退让 → 再等一个"也许永远不会来"的理由去收紧。
Loading