docs: 记录"窗口当索引"陷阱与本次改动
build / build (push) Successful in 1m26s

trap-17:分页窗口当索引 —— "当前生效版本"不能按最近 N 条找。它比 trap-14 更
隐蔽:读成"没有"不报错,只是让错误的选择看起来合理(重写已上线的目标、给已有
权威版本的目标再建基线)。写清判据(250 条历史 + 窗口里看不到 + 精确查询仍命中)
与修法(身份/当前状态一律精确查,窗口只用于列表)。AGENTS.md 的陷阱索引同步加
一行;CHANGELOG 记录当前生效版本查询修复与固定同步屏障;test-scope 声明新增的
真实 PG 用例为"可选未运行"并写清理由(未声明 skip 判红)。
This commit is contained in:
姚章浩
2026-10-30 03:09:37 +08:00
parent ed307f3c20
commit 465cae80bd
4 changed files with 68 additions and 0 deletions
+1
View File
@@ -71,3 +71,4 @@ python3 ~/.hermes/scripts/gitea_api.py GET "/api/v1/repos/Weknora/knowledge-gove
| 14 | 包一层装饰器就丢掉可选接口 ⇒ 写集合台账被静默跳过 | `docs/agents/traps.md` |
| 15 | Stat/Delete/Copy 与 Open/Put 吃不同的定位符形状 | `docs/agents/traps.md` |
| 16 | "资源不在预备份范围"≠"属于别的知识库",复用只认可审计证据 | `docs/agents/traps.md` |
| 17 | 分页窗口当索引:"当前生效版本"不能按最近 N 条找 | `docs/agents/traps.md` |
+30
View File
@@ -1,5 +1,35 @@
# Changelog
## 开发快照(当前生效版本精确查询 + 真实中断演练的固定屏障)
### Fixed
- **"当前生效版本"靠最近 50 条找,历史一长就把已生效读成没有**:接管分类
(`classifyTakeover`)、基线判定(`classifyBaselineVersions`)与"已知索引映射"
都把分页窗口当索引;窗口之外的生效版本被读成"不存在"之后,接管会把已经上线的
目标重写一遍,基线入口会为已有权威版本的目标再建一次基线。现在统一走两条精确
查询:`LibraryCurrentVersion`(`kind='production_effective' AND superseded_at IS NULL`,
每 scope 至多一行)与 `LibraryVersionOfSnapshot`(按快照身份取回"已顶替"证据)。
同一含义只保留一份实现:同步与恢复共用 `knownIndexMapping`。
- **同一判断在接口侧也要改,不是"只是展示"**:整库页的生产版本、生产同步闸口
(这是**创建**判据:读错会放行一次不必要的覆盖)、建立基线入口(读错会覆盖
别人的版本)、归档保留里"生产生效版本"的保护标记,全部改用精确查询;查询失败
一律 fail closed(500/拒绝),不猜。历史列表仍是分页展示,`LibraryVersions`
的 1..100 上限没动。
### Added
- **真实 worker 中断演练的固定同步屏障**(`internal/testbarrier`,默认关闭):
只有 `KG_TEST_BARRIER_DIR` 与 `KG_TEST_BARRIER_POINTS` 同时在场才生效,且只在
本机测试栈通过 compose overlay 注入。worker 每个阶段写完后写现场文件并停在固定
点位,演练方看到它再 SIGKILL——命中是确定的,不是靠 sleep 猜时间。进程被杀后
重启的 worker 看到同一份现场文件直接通过,不会把接管再拦住。
- `scripts/library-kill-takeover.sh`:前置体检(目标拓扑、无在飞作业、无未释放
维护窗口、镜像真的带屏障代码)→ 注入屏障 → 等命中 → 锁住这一个作业 → 读回写
集合台账并独立校验摘要 → SIGKILL 容器 → 等同一作业被接管 → 校对目标内容、
维护释放与服务恢复 → 撤掉注入。只有整条链路成立才 exit 0;missed / 超时 /
接管失败分别用不同退出码,**"没做"与"做成"分开**。
## 开发快照(真实同步/恢复后的页面修正与写集合转发)
### Fixed
+32
View File
@@ -410,3 +410,35 @@ scheme)。`validObjectKey` 认这种形状并把它拆成裸 key,`ValidObjec
证据单独落盘在 `reuse/<digest>.json`,摘要在写集合行里 —— 不冒充历史台账。
**反例**:为了"让同步能过"把"不在预备份范围"直接放行,或者恢复时按"没被引用就删"清理。
## trap-17:分页窗口当索引 —— "当前生效版本"不能按最近 N 条找
**症状**(比 trap-14 更隐蔽:它不报错,只是判错):
- 接管时把一个"其实已经生效"的作业判成 `fresh`,于是把已经上线的目标**重写一遍**;
- 基线入口为一个已经有权威版本的目标放行"建基线"(会覆盖别人的版本);
- 页面上"生产当前版本"显示成"没有生效版本记录",同步闸口据此要求先建基线;
- 只有把窗口 N 从 50 调到 100/200 才"暂时好一点",再长一点又复发。
**根因**:`LibraryVersions(scope, N)` 是**分页展示**用的窗口(真实上限 1..100),
它按 `created_at DESC` 截断。可"当前生效版本"是每 scope 唯一一行、可能很久以前
登记的事实;"本快照是否生效过"更是身份查询。用窗口当索引,历史一长就把**存在**
读成**不存在**——而且读成"没有"不会报错,只会让错误的选择看起来合理。
**判据**:把生效版本登记在 48 小时前、再灌 250 条更新的版本记录,然后:
- `LibraryVersions(scope, 100)` 里**看不到**它(用例先断言这一点,否则夹具失效);
- `LibraryCurrentVersion`(`kind='production_effective' AND superseded_at IS NULL`)
仍精确命中,接管判定是 `pending_final` 而不是 `fresh`;
- 换个更新的快照生效后,旧快照 `LibraryVersionOfSnapshot` 仍取回并带
`superseded_at`,接管判定 `superseded`(拒绝用旧快照覆盖);
- 台账被写坏(同一身份两行、未顶替却不是当前生效、已顶替却是当前生效)⇒
**拒绝挑选** / 判 `unknown`,不许挑一条"看起来对"的继续写。
**修法**:身份/当前状态一律走精确查询(`LibraryCurrentVersion`、
`LibraryVersionOfSnapshot`、`LibraryVersionByRef`),窗口只用于列表展示;
同一含义的判定(worker 接管、基线、同步闸口的创建判据、归档保留的保护标记)
共用同一份实现,别各写一份"取最近几条再筛"。
**反例**:把窗口上限调大、或在内存里 `for` 一遍再 `break`——那是换了个数字,
不是换了判据。
+5
View File
@@ -227,6 +227,11 @@
"package": "knowledge-governance/cmd/worker",
"test": "TestLibraryRunAnchorsWriteSetAndKeepsLookingItUpBeyondHistoryWindow",
"reason": "必须在真实 PostgreSQL(TEST_DATABASE_URL 指向可销毁测试库)上跑:要证明的正是 Store 的『版本列表 1..100 上限』与按身份精确查询的差别,假版本库不实现该上限(本轮缺陷就是这样一路绿的);默认 CI 无库 ⇒ 跳过,本机一次性 PG 已实跑:原码红(library version limit out of range)、只改 200→100 仍红(超出窗口找不到)、修后绿"
},
{
"package": "knowledge-governance/cmd/worker",
"test": "TestTakeoverClassificationUsesExactCurrentVersionBeyondHistoryWindow",
"reason": "必须在真实 PostgreSQL(TEST_DATABASE_URL 指向可销毁测试库)上跑:要证明的是『当前生效版本』不能按最近 N 条找——先灌 250 条历史把窗口挤满,再断言接管判定仍是 pending_final / superseded;假 store 不实现窗口语义,默认 CI 无库 ⇒ 跳过(补验路径:起一次性 PG 后设 TEST_DATABASE_URL 单跑这条)"
}
]
}