dsh-knit 0.21.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,240 @@
3
3
  本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
4
4
  版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
5
5
 
6
+ ## [0.23.0] - 2026-10-12
7
+
8
+ > **Optional Hybrid Retrieval(可选混合检索)** —— 在**保留「可解释的词法检索」为默认**的前提下,
9
+ > 给 Knit 加一条**可选的**语义候选召回通道,并且**先把能证伪它的实验准备好**,而不是先相信它。
10
+ > **默认 = 纯词法**(BM25 + IDF;纯本地、零模型调用、零网络出口):**不碰它时这一版与 v0.22 逐字一致**
11
+ > (有守卫钉住)。只有用户在**「相关」档**把检索模式切到「混合」、**并且配置了 provider**,
12
+ > 语义那条路才会跑。
13
+ > 语义**只补候选、不参与排名**:它只可能落在「相关」层、**只追加在最后**(`raw === 0 && semantic` 才准入),
14
+ > 主要 / 辅助两层与既有条目的顺序**一个字不动**;`capRelated` 满时**先牺牲语义条目**。
15
+ > 来源多一值 `provenance: 'semantic'`,理由码 `semantic`(`terms` 恒为空 —— **不冒充关键词命中**)。
16
+ > **任何失败一律明着回退**成词法:`no-provider` / `probe-failed` / `timeout` / `bad-response` /
17
+ > `no-query` /(时间序)`not-applicable`;回退时结果与词法**逐字一致**,面板与工具输出都如实写原因。
18
+ > 🔴 **诚实边界**:本机没有 provider ⇒ 真模型那条路(H1)**没跑**,`value-evidence: pending`;
19
+ > 下面那组「H0」数字是**确定性替身**造出来的**机制证据**,**不能**读成「语义提升召回」。
20
+
21
+ ### 一句话结论(这一版证明了机制,还没有证明价值)
22
+
23
+ 三句话:① **默认路径是干净的** —— 词法模式下一次 provider 调用都不发(连探测都不发),
24
+ 载荷与 v0.22 逐字相同,这条有守卫、可证伪;② **语义的准入被写成了结构性保证** ——
25
+ 不是「约定只往相关层放」,而是装配层**单独收一份** `semanticOnly`、在既有条目收完之后才追加,
26
+ 所以「只追加、不插队、满员先牺牲它」都能被断言;③ **价值证据没拿到** ——
27
+ 本机没有可用的 embedding provider,真模型路径如实 skip,因此**「默认关闭」就是这一版的正式交付结果**,
28
+ 而不是没做完。
29
+
30
+ ### 变化
31
+
32
+ - **新增 `src/host/semantic.js`(provider 接口 + 有界语义候选 + 回退叙事)**:
33
+ · 两种协议形状:Ollama(探测 `/api/tags`、嵌入 `/api/embed`)与 OpenAI 兼容
34
+ (`/v1/models` + `/v1/embeddings`);配置一律**收敛**后才使用(不可信输入丢弃,不抛);
35
+ · **`fetchImpl` 参数注入**:宿主自身**零 `fetch` 调用**,「谁在联网」这件事因此在签名上可见、可测;
36
+ · **有界**:每轮最多嵌 `SEM_EMBED_PER_PASS = 8` 篇;进程内向量缓存,键 = `headHash + provider`
37
+ (换模型即作废,不混用不同向量空间);嵌入失败 / 超时 / 形状不对一律收敛成一条 `reason`;
38
+ · **嵌入输入只有标题 + 摘要**(不是正文)—— 这条是刻意的:正文一旦进嵌入输入,复用路径上
39
+ (`body` 为空)就会算出不同的向量,语义结果将取决于「这一轮有没有命中索引缓存」。
40
+ - **`src/host/index.js`:把语义那一轮接进取数路径(默认短路)**:
41
+ · 新选项 `retrieval: 'lexical' | 'hybrid'`(默认 `lexical`);语义那一轮插在**排除之后、
42
+ `rankByRelevance()` 之前** —— 被排除的文件因此**不可能**从语义路径回来;
43
+ · 语义候选只把命中的记录**标一个 `semantic` 标记**(不改名次、不抬层);`context.js` **只在
44
+ `raw === 0` 时**才认这个标记 ⇒「有词法证据的仍按词法分层」是结构性保证,不靠纪律;
45
+ · **时间序整层短路**:时间序不产出 Context Pack(`contextPayload()` 要求 `sort === 'relevance'`),
46
+ 语义候选没有消费者 ⇒ 直接回 `not-applicable`,**不探测、不嵌入**(原来会白花 provider 调用,这是本版修掉的缺陷之一);
47
+ · **查询文本用原话**:显式 `query` 路径原来拿去做嵌入的是 `extractKeywords()` 去重叠后的
48
+ **3-gram 碎片**(实测 `失效策略怎么定` → `["失效策","效策略"]`)⇒ 改成
49
+ **显式 query > 会话原话 > 关键词(兜底)**(本版修掉的缺陷之二);
50
+ · 配置存 DSH `ctx.storage` 的**独立单元 `knit_semantic`**(与 `knit_control` / `knit_index` 各开各的),
51
+ **只存配置,向量只在内存**;新写路由 `POST /knit/api/semantic`(第二条也是最后一条写通道:
52
+ 只回环、只 POST、坏 body 400、空配置即清空)。
53
+ - **`src/host/context.js`:准入、来源与理由(三分支)**:
54
+ · 准入门槛 = `raw === 0 && semantic === true` 的记录**单独收一份**(`semanticOnly`),
55
+ 在词法条目与「引用了 Primary」的邻居都收完之后**才追加**,且只吃剩下的 `capRelated` 名额;
56
+ · `explainContext()` 多一个 `semantic` 分支,判定次序写死为 **词法 > 关系 > 语义 > 兜底**,
57
+ `terms` 恒为空数组(语义**不冒充**任何关键词命中);
58
+ · `provenance` 从两分支变**三分支**:`semantic` 单独判 —— 否则它会掉进默认分支伪装成 `retrieval`,
59
+ 或被 `related` 兜底码误标成 `relation`。
60
+ - **`src/host/tool.js`:工具面如实说**:`knit_docs` 多一个参数 `retrieval`(默认 `lexical`,
61
+ 不传它时入参与返回值与 v0.22 逐字一致);`reason.code` 与 `provenance` 两个 enum 各加一个值;
62
+ **新增一行 `Retrieval: …`**,只在调用方要了 `hybrid` 时出现,回退时写明原因
63
+ (如 `Retrieval: lexical — fell back from hybrid (no-provider)`);`whyText()` 给 `semantic`
64
+ 一句**可复核**的说法,不落进「与当前工作区相关」那句不可验证的兜底话。
65
+ - **界面(两条决定)**:
66
+ · **检索模式 = 搜索框右端的小下拉**(`词法⌄` / `混合⌄`),**不再**是左端排序 / 类型之间的第三个分段控件
67
+ (左端因此回到两组,那根多余的竖线删掉);**「最新」档整块不渲染**(不是置灰、不是 `display:none`);
68
+ **未配 provider 也出现** —— 菜单里如实写状态(未配置 / 已生效 / 已回退 + 原因),并给
69
+ 「配置语义 provider…」入口,就地展开那行最小配置区(附披露:回环地址写「内容不离开这台机器」,
70
+ 其余地址写「内容会发送到你配置的服务 <地址>」);
71
+ · **「全部」档 = 整份包的原样** —— 三层(主要 / 辅助 / 相关)**混排文档 + 代码**,
72
+ 媒体作为**末尾一个不截断的网格**(⚠️ 媒体**靠文件名也能命中**并拿到 `raw > 0` —— 实测 `docs/clip.mp4` 凭 “clip” 进过 Primary ⇒ 剔除发生在**装配之前**,层里永远不会出现媒体,有 e2e 钉住);
73
+ **删掉**了原来「按类型分三区 + 文档 / 代码各 4 条 + 查看全部」整套特例。
74
+ - **量尺(Phase C,随包发布的部分在 `test/`)**:固定语料
75
+ `test/retrieval-corpus.mjs` = **19 篇 / 13 条查询**(每条人工标注 `expected`;含 **4 条刻意造
76
+ 「词法必漏」的答案** 与 **2 个 hard negative**:相邻话题、不同意图);机器
77
+ `test/retrieval-eval.mjs`(指标 / 跑一条路径 / provider 探测)随包发布,
78
+ CLI 外壳 `tools/hybrid-retrieval-eval.mjs` **不进包**。四路径:
79
+ **L** 词法基线 / **H0** hybrid + 确定性替身(只证机制)/ **H1** hybrid + 真 provider(探测不到即 skip)/
80
+ **H2** hybrid + 探测失败(验回退)。
81
+ **实测(2026-10-12,K=5,按包内顺序)**:
82
+ | 路径 | R@5 | MRR | 无关@5 | 墙钟 | provider 调用 |
83
+ |---|---|---|---|---|---|
84
+ | L 词法 | 0.808 | 0.808 | 0.167 | 48 ms | **0** |
85
+ | H0 混合 + 替身 | 1.000 | 0.962 | 0.205 | 65 ms | 56(≈1.08/轮) |
86
+ | H2 混合 + 探测失败 | 0.808 | 0.808 | 0.167 | 62 ms | 0 |
87
+ H0 共**追加 5 条**,其中 **4 条命中标注答案**;**H2 与 L 的面板载荷逐字一致**
88
+ (剥掉 `semantic` 状态行后 JSON 相等)。**H1 本机 skip**:`SKIPPED: no provider at http://127.0.0.1:11434`
89
+ ⇒ `value-evidence: pending (no provider)`。
90
+ ⚠️ **H0 的 1.000 是替身(加权同义词表)造出来的**,它证明的是「候选算得出来、进得了相关层、
91
+ 有界、可复现」,**不是**「语义检索提升了召回」——替身的召回率不可外推到任何真模型。
92
+ - **测试**:`npm test` **728 → 778 项**(33 个测试文件;v0.22 的 728 条**一条未删、未放宽、未 skip**)。
93
+ 新增 `test/semantic.test.mjs`(provider 两协议 / 配置收敛 / 有界嵌入与缓存 / 五条回退 reason)、
94
+ `test/hybrid-retrieval.test.mjs`(判据 1/2/2c/3/3b/5/6/7,含**证伪用例**:拿掉准入标记,语义条目必然消失)、
95
+ `test/hybrid-eval.test.mjs`(把量尺钉住:回退逐字一致、只追加相关层、标注救回、有界、指标手算)。
96
+ ⚠️ **量尺放在 `test/` 而不是 `tools/`**:`tools/` 不随包发布,而测试要引它 —— v0.20.0 的
97
+ `test/deep-scale.test.mjs` 就是这么让发出去的包「自测 638/1」的,这次提前避开了。
98
+
99
+ ### 刻意不做
100
+
101
+ - **不引入任何 SDK / 向量库 / 数据库 / 常驻服务**(仍然零新依赖、无构建步骤);
102
+ - **不建云服务、不替用户挑付费 API、不在没有证据时把语义默认打开**;
103
+ - **不用 chat 模型生成「为什么」**(理由必须来自确定性事实:命中在哪个字段、哪条引用、或是语义候选);
104
+ - **不替换 BM25**、不让相似度直接驱动最终名次(这一版语义**只补候选**);
105
+ - **不做语义 Dashboard / 相似度百分比 / 维度 / confidence**;界面上只多两个字和一个下拉;
106
+ - **不把向量写进盘**(进程内缓存;`knit_semantic` 只存配置),也不把正文送进嵌入输入。
107
+
108
+ > **验证(2026-10-12 15:21 实测)**:`npm test` **778 / 778**(0 fail,33 个测试文件);
109
+ > `node tools/agents-budget.mjs --claims` **exit 0**(版本 `0.23.0` / 33 个测试文件 / 778 项);
110
+ > `node tools/clean-room-test.mjs` 打包 **`dsh-knit-0.23.0.tgz` · 65 个文件**(`tools/` 里只有白名单那两个),
111
+ > 解包目录里 `npm test` **778 pass / 0 fail** ⇒ exit 0。
112
+ > ⚠️ 这组读数取自「界面第二条决定(「全部」档)落地过程中」的时刻;**提交 / 打包前必须重跑**
113
+ > (`knit/` 里任何一个在包内的字节被改,文件数与这一行都要重测)。
114
+
115
+ ## [0.22.0] - 2026-10-10
116
+
117
+ > **Incremental Context Index** —— 让**未变化的文件在进程重启后复用已有索引**,变化的文件
118
+ > **只重建它自己**,索引坏了 / 存储不在 / 版本不对时**明着退回全量扫描**,而不是悄悄交付
119
+ > 一份陈旧的 Context Pack。索引**只在那条检索真的用不着正文时才被查**(修法 ②)——
120
+ > 要正文的路径(相关检索)走的就是 v0.21 那条路,一个字都不多付。
121
+ > 旧格式的**遗留记录会被有界地清掉**(清理补丁),不会永远留在盘上白付装载成本。
122
+ > 这是**内部能力,不是用户可见功能**:UI 一行没改,没有索引面板、没有命中率、没有 Epoch。
123
+ > 硬约束照旧:**零模型 / 零网络 / 零新依赖 / 无构建步骤**(`node:crypto` 是内置模块)。
124
+
125
+ ### 一句话结论(先审计,再动手)
126
+
127
+ Phase 0 审计推翻了这个版本号原本的卖点:**「未变化的文件不重读」v0.20/v0.21 早就做到了**
128
+ (进程内 `cache` 按 `mtime + size` 命中,暖扫的 `readFile` 恒为 0)。真正的缺口只有四个:
129
+ **跨进程重启要全量重读**、**`mtime + size` 是唯一的一致性证据**、**没有对账**、**没有降级叙事**。
130
+ 所以这一版只补这四件事 —— 稳定模块(`relevance.js` 的 BM25 语义、`control.js`、关系投影)
131
+ 一行未改,见 `99_暂存文档/01_ Knit PRD-历史版本/Knit-v0.22-Phase0-审计.md`。
132
+
133
+ ### 变化
134
+
135
+ - **新增 `src/host/index-store.js`**:索引的持久层,走 DSH 自己的 `ctx.storage` KV facet
136
+ (与 `control.js` 同一个后端、**各开各的单元** `knit_index`)。
137
+ · 布局 `per-record`(**不是** `single`):改一个文件只碰一个键,而不是重写整份索引;
138
+ · 键 = `rootHashOf(root) + base64url(rel)`(`per-record` 的键必须是 `[a-zA-Z0-9_-]+`);
139
+ **root 必须进键** —— 只用 `rel` 的话两个项目里的同名文件会抢同一个键互相覆盖(写测试时
140
+ 抓到的真实故障);值里也带 `root`,读的一侧再过滤一遍;
141
+ · 记录 = `{root, rel, mtimeMs, size, headHash, title, summary, refs}`,
142
+ **`body` 永远不进索引**(正文一旦持久化,「同 mtime 同 size 的编辑」就会被静默交付成旧内容);
143
+ `refs` 是**抽取后的**引用 / 导入列表(`{md, any, imports}`,`md` 与 `any` 分开存 ——
144
+ `extractRefsWithLines()` 有每篇 500 条的截断,用一套近似另一套会在超限文件上改变目标集合,
145
+ 破坏第 7 条验收)。**原文首部不进索引**:它只为关系投影服务,而关系投影要的只是这份列表;
146
+ · `INDEX_VERSION = 3` + `compatibleVersions: [1, 2]`:v1 记录缺 `headHash`、v2 记录存的是
147
+ `head` 而不是 `refs`,两者都读得进来、都过不了 `refsShapeOk()` 这一关,
148
+ 于是当「没有可用记录」处理、下一轮重建 —— 迁移不需要任何专用代码;
149
+ · `canonicalRoot()` 在**进出两侧**都做 `realpathSync`:`/var/...` 与 `/private/var/...`
150
+ 是同一个目录的两个字符串,只靠调用方守纪律就会「索引时灵时不灵且不报错」(也真的踩到了);
151
+ · 任何失败(没有存储 / unit 开不起来 / `malformed-medium` / 版本不符)⇒ 空 Map + 一个
152
+ `reason`,**绝不抛进检索路径**;`persisted` 只在读成功或写成功后才是 true。
153
+ - **`src/host/index.js` 的取数路径重写**:`readDoc()` / `readCode()` 这对「先查缓存再决定读不读」
154
+ 的包装函数被删掉(留两份判定只会漂移),唯一读取路径是 `readDocFromDisk()` / `readCodeFromDisk()`。
155
+ 每条候选现在走三选一:① 进程内 `cache` 命中(**单独计数**,这是 v0.20 就有的能力,不许算进
156
+ 这一版的成绩)→ ② 索引记录可复用(`mtime + size` 当快速筛子,`headHash` 是可复核的第二证据)
157
+ → ③ 整读 + 重解析 + 重算指纹。复用出来的条目 `body === ''`、`bodyReady: false`。
158
+ - **有界对账(没有 watcher)**:每轮抽验 `INDEX_VERIFY_PER_PASS = 8` 条复用项,按**游标轮转**
159
+ 取样(不是每轮都核同一批),逐条读**头部**算指纹比对;对不上就重读该文件、就地改正并写回。
160
+ 这是「`mtime`/`size` 不得作为可靠内容一致性的唯一证据」的落实方式 —— 不是每次扫都重读一遍
161
+ (那等于没省),而是**读到的那一份永远能被指纹复核**。删除项也按同一个游标分批清理,
162
+ 否则「1000 个文件全删掉」会变成一次 O(N) 写风暴。
163
+ - **修法 ②(2026-10-10):索引只在那条路真的用不着正文时才查。** `collectDocs()` 现在接受
164
+ `{index: false}`;相关检索那条路(`scan()` 里 `mode === 'relevance'`)显式传它,于是
165
+ **不装载、不对账、不写回**索引 —— 因为 BM25 的 `df` / `avgdl` 都是正文的函数,那些记录
166
+ 反正会被立刻整读补回正文,唯一净效果是**多付一次索引装载**(每条记录一个文件 open + read
167
+ + `JSON.parse`,实测 600 条约 60–75 ms,且这个成本与记录里的载荷大小**几乎无关**)。
168
+ 低层 API 不替调用方做这个决定:不传 `options.index` 仍然查索引(工具、测试、基准的语料阶段
169
+ 就是这样)。这一轮没查索引时读数记 `skipped: true` / `reason: 'index-skipped'`,
170
+ 与「这个进程没有存储」的 `no-storage` **分开报**,否则两种 0 混成一个数就没法排查了。
171
+ - **目录级 memo**:同一轮扫描里目录的 `readdir` 结果按**目录自身 mtime** 复用;
172
+ 新增/删除/重命名会更新父目录 mtime,而**改动已有文件不会**(APFS 实测),
173
+ 所以每个候选文件仍然**逐条重新 `stat`** —— memo 只省 `readdir`,不省变更检测。
174
+ - **`hydrateBodies()` 必须跑在 `rankByRelevance()` 之前**:复用路径上没有正文,而 BM25 的
175
+ `avgdl` 与 `df` 都是正文的函数;顺序错了,「索引开 / 关」两份 Context Pack 就对不上。
176
+ 这是正确性问题,不是优化顺序。
177
+ - **实测(`node tools/index-benchmark.mjs`,合成语料、mtime 固定)**:语料阶段(`collectDocs`)
178
+ 的整读次数在**重启后**从 `100 / 500 / 600 / 700 / 700`(N=100…10000)降到 **8** 条
179
+ (= 抽验预算,与规模无关),读入量从 `25 / 126 / 154 / 183 / 183 KiB` 降到 **1.9 KiB**;
180
+ 改一个文件只重读 **1** 篇;新增/删除/重命名后索引项同步增删且不返回过期结果;
181
+ 「索引开 / 关」两份 Context Pack 的指纹逐字相同(`parity-on = parity-off`)。
182
+ 三次重复的中位数与计数型读数逐次一致(`c.read` 冷 `100/500/600/700/700`、暖恒 `8`、
183
+ `touch` 恒 `9`;parity 指纹 **12/12 次**完全相同),不是「碰巧一致」。
184
+ - **最终同口径实测(12 次重复取中位数;N=1000、每篇另加 8 KiB 填充 ⇒ 600 个文件 / 13.45 MiB,平均 22.4 KiB/篇)**:
185
+ 两条检索序要分开说,因为它们**走的路不一样**。
186
+ · **相关序(面板默认,要正文)—— 生产形状下没有回归**:`--shape scan`(一次检索 = 新进程
187
+ 首次取数)warm **259.4 ms** vs `nostorage`(等价 v0.21)**242.6 ms**,而计数**逐项相同**
188
+ (`readFiles` 600 / 读入 13453 KiB / `readdir` 21 / 复用 0)—— 因为这条路上索引**根本没被查**
189
+ (`index-skipped`)。差距在噪声内,且路径就是同一条。
190
+ · **时间序 / 无关键词(不吃正文)—— 这才是这一版真正省下来的地方**:同形状 warm **106.0 ms**
191
+ vs `nostorage` **216.2 ms**(**2.04×**),整读 **8** 次 vs **600** 次、读入 **179 KiB** vs
192
+ **13453 KiB**(**约 75×** 更少),复用 600 条、其中 8 条按指纹抽验过。
193
+ ⚠️ 报告里必须写明的一件事:**旧的历史形状(`--shape collect`,先单独跑一次 `collectDocs`
194
+ 再跑检索)会给出误导性的读数** —— 那个形状下同一份语料被取两遍,于是 warm 的账会拆成
195
+ 「语料阶段 93.2ms(省了)+ 检索 219.3ms(补正文)」而 `nostorage` 是「214.7 + 47.6」,
196
+ 两列相加看起来仍慢 1.19×。那**不是生产行为**:真实的一轮相关检索没有那个预热的
197
+ `collectDocs`。1.31× 那条旧结论来自这个形状,修法 ② 之后它已经不成立。
198
+ 取舍、复现命令与逐条读数见 `99_暂存文档/01_ Knit PRD-历史版本/Knit-v0.22-实现与基准报告.md`,
199
+ - **清理补丁(2026-10-10,真机复验之后;裁决 F)**:真机 `~/.dsh/storages/knit_index/files`
200
+ 里查出 **164 条记录,键全部是旧格式**(`base64url(rel)`,没有 root 指纹),其中 **152 条是存
201
+ 16 KiB 原文首部的 v2 记录**(共 **1.7 MiB**,平均 10.7 KiB/条)。它们对**任何**工作区都不可用
202
+ (`refsShapeOk()` 判不过 ⇒ 每轮重建),但本版的写入路径只写
203
+ `rootHashOf(root) + base64url(rel)` ⇒ **永远覆盖不到这些键**。`compatibleVersions: [1, 2]`
204
+ 本意是「读得进来、下一轮重建」,代价却是**永久残留**:`loadAll()` 每次都要为它们付钱,
205
+ 而装载成本正比于**记录条数**(600 条小记录 60 ms ≈ 600 条肥记录 75 ms)。修法:
206
+ `read()` 用 `keyFitsRecord(key, row)`(键必须是 `recordKey()` 的形状**且** 16 位之后解回来
207
+ **逐字等于这条记录自己的 `rel`** —— 只查 hex 前缀不够,`relToKey()` 的字符集本身就含 `a-f`/`0-9`)
208
+ 把不合规的键收进清理队列,`write()` 在**本轮本来就要写盘时**顺手删,上界
209
+ **`INDEX_CLEAN_PER_WRITE = 32` 条/次**(与对账的 `INDEX_VERIFY_PER_PASS = 8` 同一条纪律:
210
+ 不许为了维护索引把一次检索拖长)。删除幂等 ⇒ 不需要事务,中途失败下一轮接着删;真实工作区
211
+ 164 条 ⇒ **6 轮写盘内清完**。同源的键一律放行(包括**别的 root 的合法记录**),实测真机 164 条里
212
+ 同源 **0** 条 ⇒ 清理对象与活记录零重叠。**证伪**:把 `unit.deleteRecord()` 那行换成 `void key`
213
+ ⇒ 新增的 2 项恰好变红(`pass 14 / fail 2`),恢复后 16/16。
214
+ ⚠️ 一处如实记录的小浪费:其中 12 条键不合规而内容仍可用(`refs` 在、mtime+size+headHash 相符),
215
+ 它们在**同一轮里先被复用、再被删掉**,下一轮多付 12 次读盘重建 —— 正确性不受影响(内容可重新推导),
216
+ 一次性、只发生在迁移期。
217
+ 决策见 `Knit-决策记录.md` 的裁决 A / A′ / D / E / F。
218
+ - **测试**:`npm test` **697 → 728 项**,新增 `test/index-store.test.mjs`(持久层 16 项:键/指纹/
219
+ 隔离/降级/**清理与上界**)与 `test/index-incremental.test.mjs`(端到端:§6 七条验收逐条可证伪,
220
+ 含两条**证伪用例** —— ① 把抽验预算设成 0,同 `mtime` 同 `size` 的改写必然漏掉;
221
+ ② 相关序必须 `skipped: true` 且不装载索引,时间序必须真的复用)。
222
+ 两个文件都已挂进 `package.json` 的 `scripts.test` 显式清单。
223
+
224
+ ### 刻意不做
225
+
226
+ - **不做索引状态 Dashboard**、不新增任何 UI 区块、不改列表与工具栏;
227
+ - 不把内部索引 revision 暴露成第二种用户可见的 Epoch;
228
+ - **不引入 `fs.watch`**:`recursive` 跨平台语义不一致、丢事件是必然(`git checkout` / 分支切换 /
229
+ 批量操作 / 外部编辑),它只能加速不能当权威 —— 权威是每轮的有界对账。这条明确记为「未做」;
230
+ - 不引入 SQLite / 常驻服务 / 新依赖,不建立云端索引,不改变 Context Pack 排名算法与关系语义;
231
+ - 不为「让索引看起来有用」而在要正文的路径上查索引:那一条路按需查询,宁可这一次完全不碰它;
232
+ > ✅ **2026-10-11 已发布**:轻量 tag `v0.22.0` = 发布提交 `ba17b23` = npm `gitHead`;OIDC 可信发布
233
+ > run `38100521035`(24 s,`conclusion=success`);registry `latest = 0.22.0`(共 **19 个**版本,
234
+ > `publishedAt 2026-10-11T01:05:48Z`);GitHub Release `published_at 2026-10-11T01:06:17Z`。
235
+ > registry 上的真包 = **59 文件 / 677 704 B tarball / 1 986 907 B 解包**、
236
+ > shasum `3813b5d85e94368eed3e85fe179fb424a53b0530`(= registry `dist.shasum`),下载解包后 `npm test` **728 / 0**。
237
+ > ⚠️ **这一行不在已发布的 tarball 里** —— 那份里这个位置仍是发布前写的「未发布」,
238
+ > 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
239
+
6
240
  ## [0.21.0] - 2026-10-08
7
241
 
8
242
  > **Relations & Context Control** —— **原 v0.21 与 原 v0.22 合并成一个版本**(用户 2026-10-08 拍板:
@@ -121,6 +355,11 @@
121
355
  - `src/host/tool.js` 与面板**同源**:同一条任务下,面板每项关系的前 2 条与工具侧逐字相同
122
356
  (`test/tool.test.mjs` 的跨面守卫,把工具里的截断拿掉即变红)。
123
357
 
358
+ > ✅ **2026-10-09 已发布**:轻量 tag `v0.21.0` = 发布提交 `af7a9a39995d080381217e7f84121f17e15445d5`;npm `latest = 0.21.0`、`gitHead` = 同一个提交、共 **18 个**版本;registry 真包 **56 文件 / 637 155 B tarball / 1 870 085 B 解包 / shasum `a536984cfd908c8f1a3b117f1e4c0062e1d619a6`**;OIDC 可信发布 + provenance(`/slsa.dev/provenance/v1`,workflow run `37875191973`,19 s);GitHub Release 正文取自本节(前置「更新后必须重启 DSH」与「新增写动作 `POST /knit/api/control`」两条),`publishedAt 2026-10-09T02:39:05Z`。
359
+ > **解包净室自测 697/0**(v0.20.0 那条 `tools/` 包装缺陷不复现;判据 = 真 `npm pack` 产物解包后跑 `npm test`)。
360
+ >
361
+ > ⚠️ **这一行不在已发布的 tarball 里** —— 它在 publish 成功之后才写进来(下次 `npm view` 看到的是这份仓库里的文件)。
362
+
124
363
  ## [0.20.0] - 2026-10-07
125
364
 
126
365
  > **Deep Context Retrieval**。核心体验从「任务 → 相关文件」升级为
package/README.md CHANGED
@@ -739,7 +739,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
739
739
  git clone https://github.com/PolinniZhong/dsh-knit.git
740
740
  cd dsh-knit
741
741
 
742
- npm test # 697 项,零依赖,不需要先 npm install
742
+ npm test # 728 项,零依赖,不需要先 npm install
743
743
  node tools/clean-room-test.mjs # 发版前闸门:npm pack → 解包 → 在解包目录里再跑一遍测试
744
744
  ```
745
745
 
@@ -765,10 +765,11 @@ knit/
765
765
  │ ├── host/passage.js # 内容片段层:切分 / 片段打分 / 行号映射(纯函数,零 I/O)
766
766
  │ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
767
767
  │ ├── host/control.js # 固定 / 排除:纯逻辑 + 可选 ctx.storage 持久化
768
+ │ ├── host/index-store.js # 增量索引持久层:per-record KV + 头部指纹 + 降级 + 遗留键清理(v0.22)
768
769
  │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
769
770
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
770
771
  │ └── client/client.js # 双宿主注册 + 面板 UI
771
- └── test/ # 697 项测试
772
+ └── test/ # 728 项测试
772
773
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
773
774
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
774
775
  ```
package/SECURITY.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  > **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
4
4
  >
5
- > 最后更新:2026-10-08(v0.21.0)—— 新增 `POST /knit/api/control` 与固定/排除的落盘,两条属性已按实际情况改写
5
+ > 最后更新:2026-10-12(v0.23.0)—— 写通道由一条变两条(新增 `POST /knit/api/semantic`,只存 provider 配置)、
6
+ > 会落盘的单元由两个变三个(`knit_index` 起于 v0.22、`knit_semantic` 起于 v0.23);
7
+ > 「**唯一的**写动作」那条从 v0.22 起就已经不成立,本次按实际改写,并补一条 ⚠️ 说明第二条写通道的守卫缺口
6
8
 
7
9
  ## 为什么有这份文件
8
10
 
@@ -31,8 +33,9 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
31
33
  | 读文件接口守在会话工作区内 | ✅ | `test/host.test.mjs` 的越界用例(解析后必须落在工作区内,否则一律拒绝) |
32
34
  | `/knit/api/doc` 只放行文本类产物 | ✅ | v0.19 起因代码而放宽(原为「仅 Markdown」),所以边界要重新说清:**文档 / 代码 / 生成产物**放行,**媒体与未知后缀一律拒绝**。`test/host.test.mjs` 的 `notPreviewable` 用例 + `test/classification.test.mjs` 的 `isPreviewKind` 闭集断言 |
33
35
  | `/knit/api/raw` 叠扩展名白名单 | ✅ | `test/host-http.test.mjs`(非图片/视频扩展名一律拒绝) |
34
- | 只允许 GET、只允许回环地址 | ✅ | `test/host-http.test.mjs`。**v0.21 起有一个例外**:`POST /knit/api/control`(写固定 / 排除),它同样只认回环地址,且只接受 `pin`/`unpin`/`exclude`/`restore` 四个动作 + 一条工作区内的相对路径;非 POST 打这个路由回 405、坏 body 回 400 |
35
- | 唯一的写动作 = 固定 / 排除,且只写 DSH 给的存储单元 | ✅ | `src/host/control.js` 只通过 `ctx` 注入的 storage 服务读写单元 `knit_control`(`~/.dsh/storages/knit_control.json`,按工作区隔离),**不碰工作区里的任何文件**;`test/control.test.mjs` + `test/host-http.test.mjs` |
36
+ | 只允许 GET、只允许回环地址(写通道是**例外**,不是放开 POST) | ✅ | `test/host-http.test.mjs`。写路由**只认 POST**、GET 打它回 405;**别的路由的 POST 仍回 405**(有对照断言);坏 body 回 400。v0.21 起有 `POST /knit/api/control`(写固定 / 排除,只接受 `pin`/`unpin`/`exclude`/`restore` 四个动作 + 一条工作区内的相对路径) |
37
+ | 会写盘的东西只有三类,且只写 DSH 给的存储单元 —— **不碰工作区里的任何文件** | ✅ | 三个 kv 单元各开各的:`knit_control`(`src/host/control.js`,v0.21,固定 / 排除)、`knit_index`(`src/host/index-store.js`,v0.22,增量索引,**非 HTTP 触发**)、`knit_semantic`(`src/host/semantic.js`,v0.23,**只存 provider 配置**,向量只在内存)。落盘路径由 DSH 的 storage 服务决定,Knit 不自己拼;`test/control.test.mjs` + `test/index-store.test.mjs` |
38
+ | 第二条写通道 `POST /knit/api/semantic` 的主机侧 e2e 守卫 | ⚠️ | **如实说明(v0.23 新增,尚未补)**:它目前只有**客户端侧**断言(`test/client.test.mjs` 认这条 URL),**没有**像 `/api/control` 那样在真实回环端口上验「GET→405 / 别的路由 POST→405 / 坏 body→400」。两条写路由在 `src/host/index.js` 里共用同一段前置守卫,但「共用同一段代码」**不等于**「被验过」 |
36
39
  | 响应带 `nosniff` 与 `default-src 'none'; sandbox` | ✅ | `test/host-http.test.mjs`(两个指令各自断言) |
37
40
  | 零网络出口:客户端 `fetch` 全部同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头。HTML 的「网页预览」按钮是把文件交给 **DSH 自己的**文档预览标签页去渲染(Knit 这一侧一个请求都不发),渲染的沙箱与 CSP 归 DSH 管 —— 所以这条承诺不变 |
38
41
  | 宿主半边不 import `@deepseek-ai/*` | ✅ | `test/security.test.mjs` 扫三个宿主文件,注释里提到可以、真实 `import` 不行 |
@@ -48,6 +51,9 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
48
51
  ## 如何自己复核
49
52
 
50
53
  ```sh
51
- npm test # 641 项,含本节所有断言
52
- npm test -- test/security.test.mjs # 只跑安全守卫
54
+ npm test # 全套(含本节所有断言)
55
+ node --test test/security.test.mjs # 只跑安全守卫
53
56
  ```
57
+
58
+ > ⚠️ **别用 `npm test -- test/security.test.mjs`**:`scripts.test` 是**逐文件枚举**的,
59
+ > 追加参数不会把范围收窄 —— 实测它照样跑全套。要只跑这一份就直接用 `node --test`。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.21.0",
3
+ "version": "0.23.0",
4
4
  "type": "module",
5
5
  "description": "Task-aware workspace context retrieval and lifecycle tracking for DeepSeek Harness. Finds the documents, source files and media most relevant to the current conversation, organises them into a Context Pack (primary / supporting / related) in the sidebar with inline preview, and tracks which of them were actually read and what changed afterwards. Zero model calls, zero network, nothing leaves the machine.",
6
6
  "main": "./src/host/index.js",
@@ -24,7 +24,7 @@
24
24
  ],
25
25
  "scripts": {
26
26
  "agents:budget": "node tools/agents-budget.mjs",
27
- "test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs"
27
+ "test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs test/index-store.test.mjs test/index-incremental.test.mjs test/hybrid-eval.test.mjs test/semantic.test.mjs test/hybrid-retrieval.test.mjs"
28
28
  },
29
29
  "dsh": {
30
30
  "bundle": {