dsh-knit 0.5.1 → 0.11.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.
@@ -0,0 +1,439 @@
1
+ /**
2
+ * Knit 相关性排序 · 离线评测集
3
+ *
4
+ * 用途:给 `rankByRelevance` 一个**可重复、可对比**的质量刻度。
5
+ * v0.6(BM25 + IDF)的目标就是让这个刻度明显高于 v0.5.2 的基线,
6
+ * 并且此后任何改动都不许把它弄坏(PRD §6.1 / SDD §7.2)。
7
+ *
8
+ * 两条设计决定,都是为了「隔离出相关性本身」:
9
+ *
10
+ * 1. **所有文档共用同一个 mtimeMs。** 新鲜度因子 `(1 + 0.1·freshness)` 于是变成
11
+ * 一个对所有文档相同的常数 —— 它不影响名次,评测测的就纯粹是相关性。
12
+ * 2. **直接构造 `{haystack, mtimeMs}`,不走文件系统。** 被测对象是排序器,
13
+ * 不是扫描器/解析器;把 I/O 与解析拉进来只会制造混淆变量。
14
+ * haystack 的口径严格照抄宿主(`src/host/index.js:237-239`):
15
+ * **先截前 2500 字,再转小写**。
16
+ *
17
+ * 覆盖六类用例(PRD §6.1):纯中文 / 纯英文技术词 / 中英混合 /
18
+ * 高频词陷阱 / 长文档陷阱 / 退化场景,另加一条一次性罕见词(SDD §4.8)。
19
+ */
20
+
21
+ /** 与宿主一致的正文截断长度。 */
22
+ const HAYSTACK_CHARS = 2500
23
+
24
+ /** 固定的「现在」,让评测完全确定(不受运行时间影响)。 */
25
+ export const NOW = 1_760_000_000_000
26
+
27
+ /**
28
+ * 所有文档共用同一个 mtime —— 见文件头说明 1。
29
+ * 取 `NOW - 60s`,保证新鲜度因子是一个固定的正数而不是 0。
30
+ */
31
+ const SHARED_MTIME = NOW - 60_000
32
+
33
+ /**
34
+ * 造一条文档记录,haystack 口径与宿主一致。
35
+ * @param {string} rel - 工作区相对路径
36
+ * @param {{title: string, summary?: string, body?: string}} text - 三段文本
37
+ * @returns {object} 文档记录
38
+ */
39
+ function doc(rel, { title, summary = '', body = '' }) {
40
+ return {
41
+ rel,
42
+ path: rel,
43
+ name: rel.split('/').pop(),
44
+ size: body.length,
45
+ mtimeMs: SHARED_MTIME,
46
+ haystack: {
47
+ title: title.toLowerCase(),
48
+ summary: summary.toLowerCase(),
49
+ body: body.slice(0, HAYSTACK_CHARS).toLowerCase(),
50
+ },
51
+ }
52
+ }
53
+
54
+ /**
55
+ * 语料。
56
+ *
57
+ * 刻意让项目名 `knit` 与 `dsh` 出现在**几乎每一篇**里(高 df),
58
+ * 这样「高频词污染」这个缺陷才有机会暴露出来:
59
+ * 旧算法会给它们和别人一样的权重,于是满篇「knit」的 README 什么都赢。
60
+ */
61
+ export const CORPUS = [
62
+ doc('README.md', {
63
+ title: 'Knit',
64
+ summary: '把工作区最近的 Markdown 放到对话旁边,按相关性排序。零模型、零网络。',
65
+ body: `
66
+ Knit 是 DeepSeek Harness(DSH)的一个插件。Knit 扫描当前会话工作区里的 Markdown 文档,
67
+ 把 Knit 认为跟当前对话相关的那些放到侧边栏。Knit 不调用模型,Knit 也不联网。
68
+ 安装 Knit:dsh plugin --profile web add dsh-knit。装完重启 DSH,然后硬刷新浏览器。
69
+ Knit 支持文档、图片与视频三类。Knit 的面板可以在文件与媒体之间切换。
70
+ 本段刻意重复插件名:knit knit knit dsh dsh 插件 插件 文档 文档 工作区 工作区。
71
+ Knit 的目标用户是每天产出很多 Markdown 的人。Knit 的定位是项目级的文档导航层。
72
+ `,
73
+ }),
74
+
75
+ doc('CHANGELOG.md', {
76
+ title: 'Knit 变更记录',
77
+ summary: 'Knit 的版本变更记录。',
78
+ body: `
79
+ Knit 0.5.2 阅读态与灰底降档。Knit 0.5.1 测试不再依赖目录布局。Knit 0.5.0 图片与视频、类型切换、媒体就地预览。
80
+ Knit 0.4.0 第一版:侧边栏列出最近的 Markdown。Knit 修复了路径越界、键盘导航、主题令牌等若干问题。
81
+ 这次还调整了 Knit 的发布流程、npm 打包内容、市场条目描述与截图。
82
+ `,
83
+ }),
84
+
85
+ doc('docs/relevance-algorithm.md', {
86
+ title: '相关性排序算法',
87
+ summary: '对话关键词与文档打分:加权命中、IDF、BM25 饱和与长度归一化。',
88
+ body: `
89
+ Knit 的相关性排序分三步。第一步从当前会话最近六条消息里抽关键词:英文词按原样取,中文按 2-gram 与 3-gram 近似,
90
+ 再按出现次数与词长排序、贪心去重叠。第二步给每篇文档算加权命中:标题权重最高,摘要次之,正文再次。
91
+ 第三步按分数降序,并在分数相同时用 mtime 兜底 —— 也就是 tie 到同一分时,改动更新的那篇排前面。
92
+
93
+ 每篇文档最终对外给出的 score 是零到一百的整数,由本次最高分归一化而来;
94
+ 排序依据不足时 score 为 null。名次本身才是答案,界面上不显示 score。
95
+
96
+ Knit 这套打分的已知缺陷是**没有 IDF**:一个在语料里到处都是的词(比如项目名)和罕见词拿到同样的权重,
97
+ 于是高频词不产生任何区分度。第二个缺陷是**没有长度归一化**:长文档天然命中次数多,靠堆词就能赢。
98
+ 第三个缺陷是命中次数被硬性封顶,饱和曲线是拍的而不是算出来的。
99
+
100
+ Knit v0.6 的修法是把加权命中换成 BM25:引入语料级 df 统计得到 IDF,用 k1 控制词频饱和、
101
+ 用 b 控制长度归一化,字段权重仍是标题大于摘要大于正文。全程仍然是零模型、零网络、零依赖的字符串运算。
102
+ `,
103
+ }),
104
+
105
+ doc('docs/media-browse.md', {
106
+ title: '图片与视频浏览',
107
+ summary: '方形缩略图网格、最少三列、一屏八个基准、视频取首帧当海报。',
108
+ body: `
109
+ Knit 的媒体视图把图片与视频铺成方形缩略图网格。列数最少三列,面板变宽才加列,格子边长六十四像素起步。
110
+ 一屏基准八个,超过八个不隐藏,而是整块等比缩小,此时卡片文字让位给缩略图。
111
+ 视频用 video 标签的 preload metadata 让浏览器自己解出首帧当海报,中间叠播放三角,右下角叠时长角标,
112
+ 零依赖、零转码、宿主不解析容器格式。点开图片看大图,点开视频可以播放和拖动进度,
113
+ 视频走 HTTP Range 流式取字节,不会全量下载。图片的扩展名白名单包含 png jpg gif webp avif,
114
+ 视频包含 mp4 webm mov。单张图片上限十二兆,单个视频上限二百五十六兆。
115
+ Knit 按扩展名放行媒体,不解析画面内容。
116
+ `,
117
+ }),
118
+
119
+ doc('docs/release-checklist.md', {
120
+ title: '发布清单',
121
+ summary: 'npm 发布、版本号、打包内容、市场收录与截图。',
122
+ body: `
123
+ Knit 发布前先跑测试并确认全绿,再核对版本号、确认没有 private 字段、确认 dsh 的 bundle patch 声明存在、
124
+ 确认包名在 package json 与 cordis patch yml 里一致。用 npm pack 的 dry run 看打包内容与体积。
125
+ 发布 Knit 到 npm 与 GitHub 之后,再提交市场收录的 pull request,附上中英双语描述与截图。
126
+ 市场收录是人工合并的,要盯着队列。dshfind 那个目录是按 GitHub topic 自动爬的,
127
+ 记得给 Knit 的仓库打上 dsh-plugin 标签。
128
+ `,
129
+ }),
130
+
131
+ doc('docs/competitor-research.md', {
132
+ title: '竞品调研',
133
+ summary: '插件市场的竞争格局、下载量分布与差异化判断。',
134
+ body: `
135
+ Knit 所在的插件市场里总数三千多,其中有 npm 包的接近一半,剩下的一半下载量统计不到。
136
+ 文档类目的头部全是 office、pdf、ppt、流程图这类生成工具;记忆类目又深又热,头部有五万多下载,
137
+ 而且那批插件做的是可检索的项目文档、语义召回与侧栏界面,和 Knit 的文档导航直接相邻。
138
+ Knit 真正的差异化只剩两条:扫描范围是整个项目工作区,以及排序跟着对话走。
139
+ 风险是没有护城河,而且需求本身还没有被验证 —— 竞品里最像 Knit 的那个星标只有二,下载是零。
140
+ `,
141
+ }),
142
+
143
+ doc('docs/path-safety.md', {
144
+ title: '路径越界防护',
145
+ summary: '读文件接口的沙箱边界、扩展名白名单与响应头。',
146
+ body: `
147
+ Knit 按路径读文件的接口必须守住两条边界。第一条:路径解析之后必须落在会话工作区之内,
148
+ 任何越界一律拒绝,包括目录穿越、绝对路径逃逸和符号链接绕行。第二条:扩展名白名单,
149
+ 只放行图片与视频,图片上限十二兆、视频上限二百五十六兆。只允许 GET,只允许回环地址访问。
150
+ 响应必须带 nosniff 与 default-src none sandbox。Knit 新增任何读文件的路由都要照抄这两条防护。
151
+ `,
152
+ }),
153
+
154
+ doc('docs/keyboard-nav.md', {
155
+ title: '键盘导航',
156
+ summary: '上下键移动即预览、回车切换、Esc 收起。',
157
+ body: `
158
+ Knit 面板的键盘导航用上下方向键在列表里移动,移动即预览,不需要再按一次。回车切换当前项的展开与收起。
159
+ Esc 收起预览,如果焦点在过滤框里则先清空过滤词。顶部与底部会停住,不循环。
160
+ Knit 的焦点环用中性的描边,不用品牌色。
161
+ `,
162
+ }),
163
+
164
+ doc('docs/theme-tokens.md', {
165
+ title: '主题令牌',
166
+ summary: '品牌色、中性灰、分层表面与明暗两套值。',
167
+ body: `
168
+ Knit 面板里的强调色只允许有一个来源,绑定到 DSH 的品牌主色令牌,浅色与暗色各一套,随主题切换。
169
+ 表面分层不能用 layer 系列,浅色主题下那三个令牌解析出来全是白色,做不出层级;
170
+ 要用 module platform 那个令牌。半透明的灰底要在 DSH 默认档上降一档,
171
+ 悬停保留四成、选中保留六成 —— 默认那档灰色太深,读文档时对比度被吃掉。
172
+ 不要自己用 color mix 混色,旧内核下整条声明会失效。
173
+ Knit 里变量必须先定义再引用,缺了会静默少一块样式。
174
+ `,
175
+ }),
176
+
177
+ doc('docs/api-contract.md', {
178
+ title: '接口契约',
179
+ summary: 'recent 与 doc 两个路由的响应字段与错误码。',
180
+ body: `
181
+ Knit 列表接口的响应里,文档记录包含 kind、path、rel、name、title、summary、size、mtimeMs 与 score。
182
+ score 在没有排序依据时为 null,否则是零到一百的整数。响应顶层还有 mode、topic、keywords、
183
+ total 与 truncated。Knit 读正文的接口只接受工作区内的相对路径,越界返回错误码而不是文案。
184
+ Knit 的宿主只返回错误码,面向用户的文字全部由客户端词典翻译。
185
+ `,
186
+ }),
187
+
188
+ // 长文档陷阱:很长、把很多话题词各提一次,但哪一件都没讲清楚。
189
+ doc('docs/long-archive.md', {
190
+ title: 'Knit 归档长文',
191
+ summary: 'Knit 的历史归档,涵盖许多话题。',
192
+ body: `
193
+ 这是 Knit 的一篇很长的归档文档,里面什么都会提一句。相关性排序提到了一次。图片与视频浏览提到了一次。
194
+ 发布清单提到了一次。竞品调研提到了一次。路径越界防护提到了一次。键盘导航提到了一次。
195
+ 主题令牌提到了一次。接口契约提到了一次。悬停浮层提到了一次。缩略图网格提到了一次。
196
+ 市场下载量提到了一次。版本号提到了一次。扩展名白名单提到了一次。焦点环提到了一次。
197
+ 颜色令牌提到了一次。错误码提到了一次。工作区扫描提到了一次。摘要截断提到了一次。
198
+ 为了制造长度,下面这段重复但不含新话题词:
199
+ ${'Knit 归档归档归档归档归档归档归档归档归档。'.repeat(60)}
200
+ `,
201
+ }),
202
+
203
+ // 短文档陷阱的「正解」:短,但整篇都在讲一件事。
204
+ doc('docs/peek-overlay.md', {
205
+ title: '悬停浮层',
206
+ summary: 'Knit 悬停入口按钮偷看最近五篇。',
207
+ body: `
208
+ Knit 的悬停入口按钮会弹一个只读浮层,列出最近五篇文档。浮层是自己画的,不碰框架布局,所以不会把页面推开。
209
+ 点击浮层里的某一篇才真正进入右边栏并预览那一篇。浮层有延迟显示与延迟收起,避免鼠标掠过时闪。
210
+ Knit 浮层里的点击是即时响应的,不走列表接口,也不等轮询。
211
+ `,
212
+ }),
213
+
214
+ // 媒体记录:haystack 只有文件名,summary 与 body 恒为空 —— 用来验证排序器不炸。
215
+ {
216
+ rel: 'docs/knit-screenshot.png',
217
+ path: 'docs/knit-screenshot.png',
218
+ name: 'knit-screenshot.png',
219
+ kind: 'image',
220
+ size: 4096,
221
+ mtimeMs: SHARED_MTIME,
222
+ haystack: { title: 'knit-screenshot.png', summary: '', body: '' },
223
+ },
224
+
225
+ // 一次性罕见词:整个语料里只有这一篇含它。
226
+ doc('docs/one-off.md', {
227
+ title: '临时记录',
228
+ summary: 'Knit 的一段临时笔记。',
229
+ body: `
230
+ 这里记了 Knit 的一个只在本次对话里出现过的记号 zqxwv,别的地方都没有。除此之外这篇没有别的内容。
231
+ `,
232
+ }),
233
+
234
+ doc('notes/short-note.md', {
235
+ title: '随手记',
236
+ summary: '很短的一条。',
237
+ body: 'Knit 记得把缩略图网格的列数上限再确认一遍。',
238
+ }),
239
+ ]
240
+
241
+ /**
242
+ * 用例。
243
+ *
244
+ * `expect` 是**期望的 top-1**。
245
+ * `notTop` 是**必须不能排第一**的文档 —— 专门用来钉死两个陷阱:
246
+ * 满篇项目名的 README、以及什么话题都提一句的归档长文。
247
+ * `expectTop3` 用来表达「排在前面就行」的弱断言(MRR 会自然反映)。
248
+ */
249
+ export const CASES = [
250
+ // ── 纯中文 ────────────────────────────────────────────
251
+ {
252
+ name: '中文:问排序怎么算',
253
+ messages: ['相关性排序到底是怎么算出来的?', '我看不懂它凭什么把这篇排第一'],
254
+ expect: 'docs/relevance-algorithm.md',
255
+ notTop: ['README.md', 'docs/long-archive.md'],
256
+ },
257
+ {
258
+ name: '中文:问 IDF 和长度归一化',
259
+ messages: ['没有 IDF 的话高频词不就没区分度了吗', '还有长度归一化也缺'],
260
+ expect: 'docs/relevance-algorithm.md',
261
+ notTop: ['README.md'],
262
+ },
263
+ {
264
+ name: '中文:问图片视频怎么展示',
265
+ messages: ['图片和视频在面板里怎么展示的', '缩略图网格几列、视频首帧怎么来的'],
266
+ expect: 'docs/media-browse.md',
267
+ notTop: ['docs/long-archive.md'],
268
+ },
269
+ {
270
+ name: '中文:问视频要不要转码',
271
+ messages: ['视频要转码吗?还是浏览器直接解首帧', '网格最多几列'],
272
+ expect: 'docs/media-browse.md',
273
+ },
274
+ {
275
+ name: '中文:问发布流程',
276
+ messages: ['这版发之前要检查什么', 'npm 打包内容和市场收录的顺序是什么'],
277
+ expect: 'docs/release-checklist.md',
278
+ },
279
+ {
280
+ name: '中文:问越界防护',
281
+ messages: ['读文件的接口怎么防止目录穿越', '扩展名白名单都放行什么'],
282
+ expect: 'docs/path-safety.md',
283
+ notTop: ['README.md'],
284
+ },
285
+ {
286
+ name: '中文:问键盘操作',
287
+ messages: ['面板里能用键盘吗', '上下键和 Esc 分别干什么'],
288
+ expect: 'docs/keyboard-nav.md',
289
+ },
290
+ {
291
+ name: '中文:问颜色令牌',
292
+ messages: ['这个灰色太深了,读文档对比度不够', '表面分层该用哪个令牌'],
293
+ expect: 'docs/theme-tokens.md',
294
+ },
295
+
296
+ // ── 纯英文技术词 ───────────────────────────────────────
297
+ {
298
+ name: '英文:HTTP Range',
299
+ messages: ['does the video use HTTP Range for streaming', 'preload metadata only'],
300
+ expect: 'docs/media-browse.md',
301
+ notTop: ['README.md'],
302
+ },
303
+ {
304
+ name: '英文:nosniff 与 sandbox',
305
+ messages: ['the response should carry nosniff and default-src none sandbox'],
306
+ expect: 'docs/path-safety.md',
307
+ },
308
+ {
309
+ name: '英文:mtime 兜底',
310
+ messages: ['when scores tie, does it fall back to mtime'],
311
+ expect: 'docs/relevance-algorithm.md',
312
+ },
313
+
314
+ // ── 中英混合 ──────────────────────────────────────────
315
+ {
316
+ name: '混合:score 字段语义',
317
+ messages: ['recent 接口里的 score 什么时候是 null', 'mode 有哪几种取值'],
318
+ expect: 'docs/api-contract.md',
319
+ },
320
+ {
321
+ name: '混合:BM25 的 k1 和 b',
322
+ messages: ['用 BM25 的话 k1 和 b 取多少合适', '标题权重还是最高的吗'],
323
+ expect: 'docs/relevance-algorithm.md',
324
+ },
325
+
326
+ // ── 高频词陷阱:对话里塞满项目名 ────────────────────────
327
+ {
328
+ name: '陷阱:满口项目名,问的是排序',
329
+ messages: [
330
+ 'knit 这个插件挺好用的,但是 knit 的排序我不是很懂',
331
+ 'knit 为什么把这篇放第一?knit 的排序依据是什么',
332
+ ],
333
+ expect: 'docs/relevance-algorithm.md',
334
+ notTop: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
335
+ },
336
+ {
337
+ name: '陷阱:满口项目名,问的是安全',
338
+ messages: [
339
+ 'knit 的接口安全吗?knit 会不会被目录穿越打穿',
340
+ 'knit 读文件的时候 knit 有没有做越界检查',
341
+ ],
342
+ expect: 'docs/path-safety.md',
343
+ notTop: ['README.md', 'CHANGELOG.md'],
344
+ },
345
+
346
+ // ── 长文档陷阱:正解是短文档,干扰项是长归档 ────────────
347
+ {
348
+ name: '陷阱:话题只在长归档里提了一句',
349
+ messages: ['悬停浮层是怎么做的,会不会把页面推开', '点浮层里的东西是即时的吗'],
350
+ expect: 'docs/peek-overlay.md',
351
+ notTop: ['docs/long-archive.md', 'README.md'],
352
+ },
353
+ {
354
+ name: '陷阱:短笔记对长归档',
355
+ messages: ['缩略图网格的列数上限再确认一下'],
356
+ expect: 'notes/short-note.md',
357
+ notTop: ['docs/long-archive.md'],
358
+ },
359
+
360
+ // ── 中文 n-gram 细分 ───────────────────────────────────
361
+ {
362
+ name: '中文:归档与竞品',
363
+ messages: ['竞品里下载量最高的是哪一类插件', 'star 和下载量哪个更能说明问题'],
364
+ expect: 'docs/competitor-research.md',
365
+ notTop: ['README.md'],
366
+ },
367
+ {
368
+ name: '中文:变更历史',
369
+ messages: ['上一版改了什么', '阅读态是哪个版本加的'],
370
+ expect: 'CHANGELOG.md',
371
+ notTop: ['docs/long-archive.md'],
372
+ },
373
+ {
374
+ name: '中文:暂存笔记',
375
+ messages: ['把临时记的那个记号找出来', 'zqxwv 写在哪个文件里'],
376
+ expect: 'docs/one-off.md',
377
+ notTop: ['README.md'],
378
+ },
379
+
380
+ // ── 一次性的罕见词(SDD §4.8 的观察项)────────────────
381
+ {
382
+ name: '观察:罕见词是否会失控',
383
+ messages: ['zqxwv 这个东西是什么'],
384
+ expect: 'docs/one-off.md',
385
+ },
386
+ ]
387
+
388
+ /**
389
+ * 跑一遍评测。
390
+ *
391
+ * @param {(messages: string[], limit?: number) => Array<{term: string, weight: number}>} extract -
392
+ * 关键词抽取(注入真实实现,便于新旧对比)
393
+ * @param {(docs: object[], keywords: object[], now: number) => {docs: object[]}} rank -
394
+ * 排序(注入真实实现)
395
+ * @returns {{total: number, top1: number, top1Rate: number, mrr: number,
396
+ * misses: Array<{name: string, got: string, want: string}>,
397
+ * trapViolations: Array<{name: string, offender: string}>,
398
+ * degenerate: number, ranks: number[]}} 评测结果
399
+ */
400
+ export function runEval(extract, rank) {
401
+ let top1 = 0
402
+ let mrrSum = 0
403
+ let degenerate = 0
404
+ const misses = []
405
+ const trapViolations = []
406
+ const ranks = []
407
+
408
+ for (const testCase of CASES) {
409
+ const keywords = extract(testCase.messages, 30)
410
+ const { docs: ranked } = rank(CORPUS, keywords, NOW)
411
+ const order = ranked.map((d) => d.rel)
412
+ const position = order.indexOf(testCase.expect)
413
+ // 名次从 1 开始;找不到记为 0(对 MRR 没有贡献)
414
+ const rank1 = position === -1 ? 0 : position + 1
415
+ ranks.push(rank1)
416
+ mrrSum += rank1 > 0 ? 1 / rank1 : 0
417
+ if (rank1 === 1) top1 += 1
418
+ else misses.push({ name: testCase.name, got: order[0] || '(空)', want: testCase.expect })
419
+
420
+ // 退化排序:只有一篇有分、其余全 0。名次就没有信息量了 ——
421
+ // 这种情况必须被看见,否则「提升」可能只是语料没配对。
422
+ if (ranked.filter((d) => d.raw > 0).length <= 1) degenerate += 1
423
+
424
+ for (const offender of testCase.notTop || []) {
425
+ if (order[0] === offender) trapViolations.push({ name: testCase.name, offender })
426
+ }
427
+ }
428
+
429
+ return {
430
+ total: CASES.length,
431
+ top1,
432
+ top1Rate: top1 / CASES.length,
433
+ mrr: mrrSum / CASES.length,
434
+ misses,
435
+ trapViolations,
436
+ degenerate,
437
+ ranks,
438
+ }
439
+ }
@@ -0,0 +1,115 @@
1
+ /**
2
+ * v0.5.2 的排序实现 —— **只作为评测对照存在,不参与生产路径**。
3
+ *
4
+ * 为什么留一份副本:`test/eval/fixture.mjs` 的阈值是「新引擎必须显著优于基线」
5
+ * (PRD §6.2),而基线必须可复现、可重测 —— 语料一改,历史基线数字就作废。
6
+ * 把它冻在这里,评测就能随时自己算一遍「旧 vs 新」,而不是引用一个无法核对的常数。
7
+ *
8
+ * 包含两部分,因为 v0.6 两处都动了:
9
+ * - `extractKeywordsLegacy`:去重叠**按分数降序**(这是垃圾 3-gram 挤走真实词的原因)
10
+ * - `rankByRelevanceLegacy`:加权命中,**没有 IDF、没有长度归一化**,命中封顶 6 次
11
+ *
12
+ * ⚠️ `tokenize` 是共用的 —— 它在 v0.5.2 → v0.6 之间**行为逐字未变**(只是从
13
+ * `accumulate` 里抽成了独立函数),所以这里直接引用来路一致的实现。
14
+ */
15
+ import { tokenize } from '../../src/host/relevance.js'
16
+
17
+ /** 新鲜度奖励的时间常数(7 天)。 */
18
+ const FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000
19
+
20
+ /**
21
+ * v0.5.2 的关键词抽取:与 `extractKeywords` 的唯一差别是
22
+ * **去重叠顺序按分数降序**(没有「短词优先」),输出顺序也不再重排。
23
+ *
24
+ * @param {readonly string[]} messages - 对话文本,最新在前
25
+ * @param {number} limit - 最多返回多少个关键词
26
+ * @returns {Array<{term: string, weight: number}>} 关键词及其权重
27
+ */
28
+ export function extractKeywordsLegacy(messages, limit = 30) {
29
+ const raw = new Map()
30
+ const weighted = new Map()
31
+
32
+ messages.forEach((text, index) => {
33
+ const weight = index === 0 ? 3 : index === 1 ? 2 : 1
34
+ for (const term of tokenize(text)) {
35
+ raw.set(term, (raw.get(term) || 0) + 1)
36
+ weighted.set(term, (weighted.get(term) || 0) + weight)
37
+ }
38
+ })
39
+
40
+ const ranked = [...weighted.entries()]
41
+ .map(([term, weight]) => ({ term, weight, seen: raw.get(term) || 0 }))
42
+ .filter((entry) => {
43
+ if (/^[a-z]/.test(entry.term)) return entry.seen >= 1
44
+ return entry.seen >= 2 || entry.weight >= 3
45
+ })
46
+ .map((entry) => ({ ...entry, score: entry.weight * entry.term.length * entry.term.length }))
47
+ .sort((a, b) => b.score - a.score)
48
+
49
+ const picked = []
50
+ for (const entry of ranked) {
51
+ if (picked.length >= limit) break
52
+ if (picked.some((p) => p.term.includes(entry.term) || entry.term.includes(p.term))) continue
53
+ picked.push(entry)
54
+ }
55
+
56
+ return picked.map((entry) => ({ term: entry.term, weight: entry.score }))
57
+ }
58
+
59
+ /**
60
+ * 数一个词在文本里出现几次(封顶,避免长文档靠堆词刷分)。
61
+ * @param {string} hay - 小写后的可搜索文本
62
+ * @param {string} needle - 关键词(小写)
63
+ * @returns {number} 命中次数,最多 6
64
+ */
65
+ function countOccurrences(hay, needle) {
66
+ if (!hay || !needle) return 0
67
+ let hits = 0
68
+ let from = 0
69
+ for (;;) {
70
+ const at = hay.indexOf(needle, from)
71
+ if (at === -1 || hits >= 6) break
72
+ hits += 1
73
+ from = at + needle.length
74
+ }
75
+ return hits
76
+ }
77
+
78
+ /**
79
+ * v0.5.2 的打分与排序。
80
+ * @param {Array<object>} docs - 文档记录
81
+ * @param {readonly {term: string, weight: number}[]} keywords - 关键词表
82
+ * @param {number} now - 当前时间(epoch ms)
83
+ * @returns {{docs: Array<object>, maxRaw: number}} 带 `score` 的文档
84
+ */
85
+ export function rankByRelevanceLegacy(docs, keywords, now) {
86
+ if (keywords.length === 0) {
87
+ return { docs: docs.map((doc) => ({ ...doc, score: 0 })), maxRaw: 0 }
88
+ }
89
+
90
+ const raws = docs.map((doc) => {
91
+ const hay = doc.haystack || { title: '', summary: '', body: '' }
92
+ let raw = 0
93
+ for (const { term, weight } of keywords) {
94
+ const hits = countOccurrences(hay.title, term) * 4
95
+ + countOccurrences(hay.summary, term) * 2
96
+ + countOccurrences(hay.body, term)
97
+ if (hits > 0) raw += weight * hits
98
+ }
99
+ const age = Math.max(0, now - (doc.mtimeMs || 0))
100
+ const freshness = 1 - Math.min(1, age / FRESHNESS_WINDOW_MS)
101
+ return raw * (1 + 0.1 * freshness)
102
+ })
103
+
104
+ const maxRaw = Math.max(...raws, 0)
105
+
106
+ const scored = docs.map((doc, index) => ({
107
+ ...doc,
108
+ raw: raws[index],
109
+ score: maxRaw > 0 ? Math.round((raws[index] / maxRaw) * 100) : 0,
110
+ }))
111
+
112
+ scored.sort((a, b) => b.raw - a.raw || b.mtimeMs - a.mtimeMs)
113
+
114
+ return { docs: scored, maxRaw }
115
+ }
@@ -0,0 +1,80 @@
1
+ /**
2
+ * 相关性排序的**离线质量回归**。
3
+ *
4
+ * 这是 v0.6 引入的新交付物(PRD §6.1):排序质量第一次有了可重复的刻度,
5
+ * 而且此后任何改动都不许把它弄坏 —— 包括「不小心把 BM25 换回加权命中」。
6
+ *
7
+ * 阈值不是拍脑袋的常数,而是**每次运行时自己算出来的基线**:
8
+ * `test/eval/legacy.mjs` 冻结了 v0.5.2 的抽取与排序,所以
9
+ * 「新引擎必须显著优于旧引擎」这句话是可以自动验证的(PRD §6.2)。
10
+ */
11
+ import test from 'node:test'
12
+ import assert from 'node:assert/strict'
13
+
14
+ import { runEval } from './eval/fixture.mjs'
15
+ import { extractKeywordsLegacy, rankByRelevanceLegacy } from './eval/legacy.mjs'
16
+ import { extractKeywords, rankByRelevance } from '../src/host/relevance.js'
17
+
18
+ /** 要求的最小提升幅度(PRD §6.2)。 */
19
+ const MIN_TOP1_GAIN = 0.15
20
+ const MIN_MRR_GAIN = 0.10
21
+ /** 绝对下限。 */
22
+ const MIN_TOP1 = 0.8
23
+ const MIN_MRR = 0.85
24
+
25
+ const baseline = runEval(extractKeywordsLegacy, rankByRelevanceLegacy)
26
+ const current = runEval(extractKeywords, rankByRelevance)
27
+
28
+ /** 百分比,便于失败信息阅读。 */
29
+ const pct = (x) => `${(x * 100).toFixed(1)}%`
30
+
31
+ test('评测集: 新引擎的 top-1 显著优于 v0.5.2 基线', () => {
32
+ assert.ok(
33
+ current.top1Rate >= baseline.top1Rate + MIN_TOP1_GAIN,
34
+ `top-1 提升不足:基线 ${pct(baseline.top1Rate)} → 现在 ${pct(current.top1Rate)},`
35
+ + `要求至少 +${pct(MIN_TOP1_GAIN)}。未命中:${current.misses.map((m) => `${m.name}(得 ${m.got},期望 ${m.want})`).join(';')}`,
36
+ )
37
+ assert.ok(
38
+ current.top1Rate >= MIN_TOP1,
39
+ `top-1 低于绝对下限:${pct(current.top1Rate)} < ${pct(MIN_TOP1)}`,
40
+ )
41
+ })
42
+
43
+ test('评测集: 新引擎的 MRR 显著优于 v0.5.2 基线', () => {
44
+ assert.ok(
45
+ current.mrr >= baseline.mrr + MIN_MRR_GAIN,
46
+ `MRR 提升不足:基线 ${baseline.mrr.toFixed(3)} → 现在 ${current.mrr.toFixed(3)},要求至少 +${MIN_MRR_GAIN}`,
47
+ )
48
+ assert.ok(current.mrr >= MIN_MRR, `MRR 低于绝对下限:${current.mrr.toFixed(3)} < ${MIN_MRR}`)
49
+ })
50
+
51
+ test('评测集: 两个「陷阱」用例必须全部翻正', () => {
52
+ // 陷阱有两种:对话里塞满项目名(高频词),以及什么话题都提一句的长归档。
53
+ // 它们是 PRD §三 的三个失效场景的直接化身,一个都不许失守。
54
+ assert.deepEqual(
55
+ current.trapViolations, [],
56
+ `不该排第一的文档排了第一:${current.trapViolations.map((v) => `${v.name} → ${v.offender}`).join(';')}`,
57
+ )
58
+ })
59
+
60
+ test('评测集: 基线已经答对的用例,一条都不许变错', () => {
61
+ // 只看「基线拿第一」的那些用例 —— 基线答错的用例不构成约束(那正是要修的)。
62
+ const regressions = []
63
+ baseline.ranks.forEach((rank, index) => {
64
+ if (rank !== 1) return
65
+ if (current.ranks[index] !== 1) {
66
+ regressions.push(`第 ${index + 1} 个用例:基线第 1 名,现在第 ${current.ranks[index] || '未命中'} 名`)
67
+ }
68
+ })
69
+ assert.deepEqual(regressions, [], `出现回归:${regressions.join(';')}`)
70
+ })
71
+
72
+ test('评测集: 排序不能退化成一枝独秀', () => {
73
+ // 「只有一篇有分、其余全 0」的排序没有信息量,名次是假的。
74
+ // 这个指标是 v0.6 开发中真实踩过的坑(第一版语料没让项目名铺开,整个评测都在
75
+ // 比较「唯一命中的那篇」),留在这里防止语料或引擎悄悄退化成那样。
76
+ assert.ok(
77
+ current.degenerate < current.total / 2,
78
+ `退化排序过多:${current.degenerate}/${current.total} 个用例只有一篇文档有分`,
79
+ )
80
+ })
package/test/harness.mjs CHANGED
@@ -58,7 +58,7 @@ export function loadClientModule(options = {}) {
58
58
  .replace(
59
59
  "module.exports.inject = ['slots', 'locale']",
60
60
  'module.exports.__test = { KnitBody, OfficialTabBody, BetterSidebarTabBody, '
61
- + 'sessionFileAddress, relTime, resolveRelative, pathImagesFor, clampRatio, '
61
+ + 'sessionFileAddress, relTime, resolveRelative, pathImagesFor, clampRatio, splitRelPath, '
62
62
  + 'openKnitPanel, makeEntryButton, KnitGlyph, KnitTitle, KNIT_ICON_PATH, openLocalPath, '
63
63
  + 'requestPreview, fmtDuration, readKindPref, mediaUrl, isMedia, mediaLayoutFor, '
64
64
  + 'MIN_RATIO, MAX_RATIO, ALL_DOC_CAP, MEDIA_MAX_ITEMS, MEDIA_MIN_PX, MEDIA_VIEW_ROWS }\n'