dsh-knit 0.22.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,115 @@
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
+
6
115
  ## [0.22.0] - 2026-10-10
7
116
 
8
117
  > **Incremental Context Index** —— 让**未变化的文件在进程重启后复用已有索引**,变化的文件
@@ -19,7 +128,7 @@ Phase 0 审计推翻了这个版本号原本的卖点:**「未变化的文件
19
128
  (进程内 `cache` 按 `mtime + size` 命中,暖扫的 `readFile` 恒为 0)。真正的缺口只有四个:
20
129
  **跨进程重启要全量重读**、**`mtime + size` 是唯一的一致性证据**、**没有对账**、**没有降级叙事**。
21
130
  所以这一版只补这四件事 —— 稳定模块(`relevance.js` 的 BM25 语义、`control.js`、关系投影)
22
- 一行未改,见 `01_ Knit PRD/Knit-v0.22-Phase0-审计.md`。
131
+ 一行未改,见 `99_暂存文档/01_ Knit PRD-历史版本/Knit-v0.22-Phase0-审计.md`。
23
132
 
24
133
  ### 变化
25
134
 
@@ -86,7 +195,7 @@ Phase 0 审计推翻了这个版本号原本的卖点:**「未变化的文件
86
195
  「语料阶段 93.2ms(省了)+ 检索 219.3ms(补正文)」而 `nostorage` 是「214.7 + 47.6」,
87
196
  两列相加看起来仍慢 1.19×。那**不是生产行为**:真实的一轮相关检索没有那个预热的
88
197
  `collectDocs`。1.31× 那条旧结论来自这个形状,修法 ② 之后它已经不成立。
89
- 取舍、复现命令与逐条读数见 `01_ Knit PRD/Knit-v0.22-实现与基准报告.md`,
198
+ 取舍、复现命令与逐条读数见 `99_暂存文档/01_ Knit PRD-历史版本/Knit-v0.22-实现与基准报告.md`,
90
199
  - **清理补丁(2026-10-10,真机复验之后;裁决 F)**:真机 `~/.dsh/storages/knit_index/files`
91
200
  里查出 **164 条记录,键全部是旧格式**(`base64url(rel)`,没有 root 指纹),其中 **152 条是存
92
201
  16 KiB 原文首部的 v2 记录**(共 **1.7 MiB**,平均 10.7 KiB/条)。它们对**任何**工作区都不可用
@@ -120,7 +229,13 @@ Phase 0 审计推翻了这个版本号原本的卖点:**「未变化的文件
120
229
  批量操作 / 外部编辑),它只能加速不能当权威 —— 权威是每轮的有界对账。这条明确记为「未做」;
121
230
  - 不引入 SQLite / 常驻服务 / 新依赖,不建立云端索引,不改变 Context Pack 排名算法与关系语义;
122
231
  - 不为「让索引看起来有用」而在要正文的路径上查索引:那一条路按需查询,宁可这一次完全不碰它;
123
- - **未发布**:`package.json` 版本已到 `0.22.0`,但**没有 `npm publish`、没有打 tag**。
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` 之后(同一版本号不能再发一次)。
124
239
 
125
240
  ## [0.21.0] - 2026-10-08
126
241
 
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.22.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 test/index-store.test.mjs test/index-incremental.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": {