dsh-engramory-recall 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.5.3] — 2026-10-15
+
+### 新增
+
+- **合成基准变成一道可执行的门**：`npm run bench:check` 把这次跑出来的数字跟 `bench/expectations.json` 对账，任何一项偏差超过 2 个百分点就退出非零；桥组与 verbatim 组要求满分（它们掉下来就是改坏了）。分数低不红 —— 绝对值会随语料演化，卡死绝对值只会逼人改尺子；数字悄悄漂走才红。CI 已接上这一步。
+
+### 文档
+
+- 「测试与自检」补上基准自检这一条，并说明 CI 跑的是哪两件事。
+
+## [0.5.2] — 2026-10-15
+
+### 文档
+
+- README 加一节「不用信这段话，两分钟自己验一遍」：把写入闸门的四条实地探针（索引超限、库外同名文件、文件名不合规、含凭据）连预期原话和实测结论一起写进去。唯一卖点值得一个能当场复现的验法。
+
 ## [0.5.1] — 2026-10-15
 
 ### 修复

package/README.md

@@ -89,7 +89,9 @@
 224 篇程序生成的笔记（中文书面 99 / 英文术语 85 / 口语体 40，其中 42 篇写了 `aliases`）、
 683 条查询、固定随机种子。查询按三种风格分开记分：`verbatim` 抄笔记自己的写法（对照组）、
 `colloquial` 只用口语说法（与正文没有字面重叠）、`keyword` 口语症状加域特征词
-（同域候选很多，必须靠事件词分辨）。语料是程序生成的，不依赖任何私人库，任何人可复算。
+（同域候选很多，必须靠事件词分辨）。语料是程序生成的，不依赖任何私人库，任何人可复算：
+`npm run bench` 整跑 4 秒，零依赖、零网络，消融表里对我们不利的那几行也照打（去掉字段加权反而高 4 个百分点），
+CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 
 | 引擎 | 总 hit@1 | 总 hit@4 | verbatim | colloquial | keyword |
 |---|---|---|---|---|---|
@@ -245,6 +247,21 @@
 **边界**：`guard` 只拦 `write` / `edit` 工具调用，`bash` 重定向它看不见。它是正路守卫，
 不是沙箱；兜底靠体检器定时扫（真实抓到过两篇绕过闸门的裸 markdown）。
 
+#### 不用信这段话，两分钟自己验一遍
+
+闸门跑在宿主进程里，验法就是在你的 agent 会话里让它做下面四件事 —— 全部走普通的 `write` / `edit` 工具，不需要装任何东西：
+
+| 让它做 | 你会看到 |
+|---|---|
+| 往 `MEMORY.md` 追加 130 行（凑到 203 行） | 拒绝：**「这次写入会把索引 MEMORY.md 顶过上限（203 行 > 200）」** |
+| 在记忆库外（比如项目目录里）写一份同名、同样 203 行的 `MEMORY.md` | 放行（闸门只认配置的那一个库） |
+| 往库里写 `bad-name.md` | 拒绝：**「文件名不合规。必须是 \<user\|feedback\|project\|reference\>-\<小写slug\>.md」** |
+| 写一篇带 `api_key: sk-…` 的笔记 | 拒绝：**「疑似含真实凭据（OpenAI 风格密钥）」** |
+
+作者实测（0.5.1 / 2026-10-15 / 库 63 篇、索引 73 行）：四条全中，两次被拒的写入**磁盘上零字节变化** —— 被拒后索引与操作前逐字一致。
+
+这就是它跟别家最本质的一处不同：别人的记忆预算卡在**注入**上（超了就少喂几段给模型），这里卡在**写入**上 —— 索引文件本身长不到超限，所以「超限的部分静默不再被召回」在这个库里不会发生。
+
 ### 体检器（`doctor.js`）
 
 纯静态、只报告不动手。12 项检查：库不可读、索引指向不存在的文件、孤儿笔记、索引重复、
@@ -490,10 +507,15 @@ npm test        # 分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技
 npm run check   # 接线自检：配置键认不认、库路径对不对、装的是哪一份、包清单漏没漏文件
 npm run probe   # 召回质量探针：3 组 query + 三道对照，跑在真实记忆库上
 npm run probe -- --save   # 把这次结果存成基线，之后每次跑自动比对
-node bench/run.mjs        # 合成基准（含消融与参数扫描）
+npm run bench:check       # 合成基准 + 和 bench/expectations.json 对账（CI 跑的就是它）
 ```
 
-前三条是克隆仓库开发时用的：`test/`、`scripts/`、`bench/` 不在 npm 包的 `files` 白名单里。
+CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄悄漂走」的：任何一项
+跟期望值的偏差超过 2 个百分点就红，桥组与 verbatim 组要求满分（它们掉下来就是我们改坏了）。
+分数低不红 —— 绝对值会随语料演化，卡死绝对值只会逼人去改尺子；漂了才红，因为那说明
+要么是回归、要么是刻意改动而没人说清楚。
+
+上面这些命令是克隆仓库开发时用的：`test/`、`scripts/`、`bench/` 不在 npm 包的 `files` 白名单里。
 发布出去的是运行时真正需要的那十几个文件（`npm pack --dry-run` 可核），
 其中 `package.test.mjs` 会从 `index.js` 递归跟所有 `./x.js` 的 import，逐个核对是否都在白名单里。
 这个检查已经抓到过两次真事故（漏 `audit.js`、漏 `archive.js`），两次的后果都是
@@ -503,7 +525,7 @@ node bench/run.mjs        # 合成基准（含消融与参数扫描）
 库路径指空、profile 里跑的不是你改的那份、`files` 白名单漏文件、这一行被 `enabled: false` 关掉。
 它顺带跑一遍 `node --check` 校验客户端 bundle 的语法（面板写坏了不会连累宿主加载）。
 唯一做不了的是活体守卫测试：守卫只拦 `write`/`edit` 工具调用，脚本写盘会绕过去，
-所以脚本最后打印的是要由 agent 亲手执行的两个方向探针。
+所以脚本最后打印的是要由 agent 亲手执行的两个方向探针（完整的四条见上面「写入闸门」一节的复现表）。
 
 ## 集百家之长
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Local BM25 auto-recall, fail-closed write guard, static doctor and a memory panel for the Engramory markdown store — no network, no model, no daemon.",
   "keywords": [
     "dsh",
@@ -71,6 +71,8 @@
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "check": "node scripts/check-recall-wiring.mjs",
-    "probe": "node scripts/recall-probe.mjs"
+    "probe": "node scripts/recall-probe.mjs",
+    "bench": "node bench/run.mjs",
+    "bench:check": "node bench/run.mjs --check"
   }
 }