dsh-knit 0.13.1 → 0.14.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 +128 -0
- package/README.en.md +113 -11
- package/README.md +112 -15
- package/package.json +5 -2
- package/src/client/client.js +501 -197
- package/src/host/context.js +568 -0
- package/src/host/index.js +305 -20
- package/src/host/relevance.js +44 -6
- package/src/host/tool.js +274 -58
- package/test/client.test.mjs +488 -92
- package/test/context/fixture.mjs +553 -0
- package/test/context-eval.test.mjs +576 -0
- package/test/context.test.mjs +542 -0
- package/test/harness.mjs +33 -7
- package/test/host-http.test.mjs +71 -0
- package/test/host.test.mjs +105 -0
- package/test/i18n.test.mjs +46 -3
- package/test/tool.test.mjs +328 -96
- package/tools/json-schema-subset.mjs +89 -0
|
@@ -0,0 +1,553 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Knit v0.14 · **Context Pack 离线评测集**
|
|
3
|
+
*
|
|
4
|
+
* 与 `test/eval/fixture.mjs`(v0.6 的检索质量评测)**分开,且不覆盖它**。
|
|
5
|
+
* 两者测的是两件事:
|
|
6
|
+
*
|
|
7
|
+
* | 文件 | 测什么 | 指标 |
|
|
8
|
+
* |---|---|---|
|
|
9
|
+
* | `test/eval/fixture.mjs` | **Retrieval**:哪几篇排得对 | top-1 / MRR / 陷阱 |
|
|
10
|
+
* | 本文件 | **Context Assembly**:排出来之后,哪些该先看、哪些是支撑 | 层次集合关系 |
|
|
11
|
+
*
|
|
12
|
+
* 分开是硬要求(需求 §十九):Context Pack 加了新的分层层,
|
|
13
|
+
* **不许**因此把 BM25 的评测删掉或改成不可比的指标。
|
|
14
|
+
*
|
|
15
|
+
* ## 语料是这个项目自己
|
|
16
|
+
*
|
|
17
|
+
* 用 Knit 自己的文档树当语料,而不是编一套假文档。理由:验收标准问的是
|
|
18
|
+
* 「Context Pack 是否比原来的相关文档列表提供了新的决策价值」——
|
|
19
|
+
* 拿真实项目问真实问题,答案才有意义。
|
|
20
|
+
*
|
|
21
|
+
* ## 与检索评测集的一条刻意差别
|
|
22
|
+
*
|
|
23
|
+
* 这里的语料**带原文 `text`**,因为引用关系要从原文里解析(`links.js` 只认路径字面量)。
|
|
24
|
+
* 检索评测集只需要小写 haystack,不带原文 —— 它的被测对象是打分器,不需要引用图。
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** 与宿主一致的正文截断长度(`HAYSTACK_CHARS`)。 */
|
|
28
|
+
const HAYSTACK_CHARS = 2500
|
|
29
|
+
|
|
30
|
+
/** 固定的「现在」,让评测完全确定。 */
|
|
31
|
+
export const NOW = 1_760_000_000_000
|
|
32
|
+
|
|
33
|
+
/** 所有文档共用同一个 mtime —— 新鲜度因子成为一个公共常数,测的就纯粹是分层。 */
|
|
34
|
+
const SHARED_MTIME = NOW - 60_000
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* 造一条文档记录。
|
|
38
|
+
*
|
|
39
|
+
* haystack 口径严格照抄宿主(`src/host/index.js` 的 `readDoc`):
|
|
40
|
+
* **先截前 2500 字,再转小写**。
|
|
41
|
+
*
|
|
42
|
+
* @param {string} rel - 工作区相对路径
|
|
43
|
+
* @param {{title: string, summary?: string, body?: string}} doc - 三段文本
|
|
44
|
+
* @returns {object} 文档记录
|
|
45
|
+
*/
|
|
46
|
+
function make(rel, { title, summary = '', body = '' }) {
|
|
47
|
+
return {
|
|
48
|
+
rel,
|
|
49
|
+
path: rel,
|
|
50
|
+
name: rel.split('/').pop(),
|
|
51
|
+
kind: 'md',
|
|
52
|
+
size: body.length,
|
|
53
|
+
mtimeMs: SHARED_MTIME,
|
|
54
|
+
// 原文首部:引用解析用(`buildLinkGraph` 的 `read`)
|
|
55
|
+
text: body,
|
|
56
|
+
haystack: {
|
|
57
|
+
title: title.toLowerCase(),
|
|
58
|
+
summary: summary.toLowerCase(),
|
|
59
|
+
body: body.slice(0, HAYSTACK_CHARS).toLowerCase(),
|
|
60
|
+
},
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* 语料。
|
|
66
|
+
*
|
|
67
|
+
* 刻意保留两条真实污染源:
|
|
68
|
+
* - `README.md` 满篇项目名 `Knit`(高频词陷阱),而且它是根目录文档、入度最高
|
|
69
|
+
* - `CHANGELOG.md` 每一条版本都提一遍所有话题词(「什么话题都提一句」的长尾)
|
|
70
|
+
*
|
|
71
|
+
* 它们在**检索**里已经被 BM25 的 IDF 压住了(见 `test/eval/`),
|
|
72
|
+
* 这里要验的是**另一件事**:即使它们排在前面,也不该霸占 Primary。
|
|
73
|
+
*/
|
|
74
|
+
export const CORPUS = [
|
|
75
|
+
make('README.md', {
|
|
76
|
+
title: 'Knit',
|
|
77
|
+
summary: '把工作区最近的 Markdown 放到对话旁边,按相关性排序。零模型、零网络。',
|
|
78
|
+
body: `
|
|
79
|
+
Knit 是 DeepSeek Harness(DSH)的一个插件。Knit 扫描当前会话工作区里的 Markdown 文档,
|
|
80
|
+
把 Knit 认为跟当前对话相关的那些放到侧边栏。Knit 不调用模型,Knit 也不联网。
|
|
81
|
+
安装 Knit:dsh plugin --profile web add dsh-knit。装完重启 DSH,然后硬刷新浏览器。
|
|
82
|
+
Knit 支持文档、图片与视频三类。Knit 的面板可以在文件与媒体之间切换。
|
|
83
|
+
本段刻意重复插件名:knit knit knit dsh dsh 插件 插件 文档 文档 工作区 工作区。
|
|
84
|
+
设计取舍与算法细节见 \`docs/relevance-algorithm.md\`,接口字段见 \`docs/api-contract.md\`,
|
|
85
|
+
裁剪后的检索评测见 \`docs/eval-benchmark.md\`,npm 打包与目录布局见 \`docs/package-layout.md\`。
|
|
86
|
+
Knit 的目标用户是每天产出很多 Markdown 的人。Knit 的定位是项目级的文档导航层。
|
|
87
|
+
`,
|
|
88
|
+
}),
|
|
89
|
+
|
|
90
|
+
make('CHANGELOG.md', {
|
|
91
|
+
title: 'Knit 变更记录',
|
|
92
|
+
summary: 'Knit 的版本变更记录。',
|
|
93
|
+
body: `
|
|
94
|
+
Knit 0.5.2 阅读态与灰底降档。Knit 0.5.1 测试不再依赖目录布局。Knit 0.5.0 图片与视频、类型切换、媒体就地预览。
|
|
95
|
+
Knit 0.4.0 第一版:侧边栏列出最近的 Markdown。Knit 修复了路径越界、键盘导航、主题令牌等若干问题。
|
|
96
|
+
这次还调整了 Knit 的发布流程、npm 打包内容、市场条目描述与截图。
|
|
97
|
+
每一条都提了一句:相关性排序、图片与视频浏览、发布清单、竞品调研、路径越界防护、
|
|
98
|
+
键盘导航、主题令牌、接口契约、悬停浮层、缩略图网格、扩展名白名单、错误码。
|
|
99
|
+
`,
|
|
100
|
+
}),
|
|
101
|
+
|
|
102
|
+
make('docs/relevance-algorithm.md', {
|
|
103
|
+
title: '相关性排序算法',
|
|
104
|
+
summary: '对话关键词与文档打分:BM25、IDF、长度归一化、长文档与命中段落。',
|
|
105
|
+
body: `
|
|
106
|
+
Knit 的相关性排序分三步。第一步从当前会话最近六条消息里抽关键词:英文词按原样取,
|
|
107
|
+
中文按 2-gram 与 3-gram 近似,再按出现次数与词长排序、贪心去重叠。
|
|
108
|
+
第二步给每篇文档算 BM25 分数:引入语料级 df 统计得到 IDF,用 k1 控制词频饱和、
|
|
109
|
+
用 b 控制长度归一化,字段权重仍是标题大于摘要大于正文。
|
|
110
|
+
第三步按分数降序,并在分数相同时用 mtime 兜底。
|
|
111
|
+
|
|
112
|
+
为什么不能只数关键词出现次数:一个在语料里到处都是的词(比如项目名)和罕见词拿到同样的权重,
|
|
113
|
+
于是高频词不产生任何区分度;长文档又天然命中次数多,靠堆词就能赢。
|
|
114
|
+
所以 Knit 用 BM25 取代关键词计数,并用 IDF 压住高频词。
|
|
115
|
+
|
|
116
|
+
排序结果之上还有一层上下文分层:把名次分成主要上下文、辅助上下文与相关上下文,
|
|
117
|
+
见 \`docs/sdd-context-assembly.md\`。评测在 \`docs/eval-benchmark.md\`。
|
|
118
|
+
`,
|
|
119
|
+
}),
|
|
120
|
+
|
|
121
|
+
make('docs/package-layout.md', {
|
|
122
|
+
title: 'npm 打包与目录布局',
|
|
123
|
+
summary: '测试为什么在 clone 之后失败,以及打包要带上哪些文件。',
|
|
124
|
+
body: `
|
|
125
|
+
这篇记录一个真实缺陷:测试在作者本机全绿,但别人 clone 公开仓库之后 npm 测试就会失败。
|
|
126
|
+
根因是测试把样本工作区写成包根的上一层目录 —— 作者本机那层恰好有样本,
|
|
127
|
+
clone 出来的那层是 clone 的父目录,从 npm 装进 node_modules 之后那层就是 node_modules,
|
|
128
|
+
两处都没有样本文件。所以目录布局依赖必须彻底去掉,样本一律现场造。
|
|
129
|
+
|
|
130
|
+
同一类问题还出现在三处硬编码的 knit 前缀上。修法是把样本工作区造在临时目录里,
|
|
131
|
+
并让测试在任何目录布局下都能跑。打包内容见 \`package.json\` 的 files 字段。
|
|
132
|
+
`,
|
|
133
|
+
}),
|
|
134
|
+
|
|
135
|
+
make('docs/eval-benchmark.md', {
|
|
136
|
+
title: '排序评测集',
|
|
137
|
+
summary: '离线评测:top-1、MRR、高频词陷阱与长文档陷阱、退化场景。',
|
|
138
|
+
body: `
|
|
139
|
+
Knit 的排序评测是一套离线、可重复的刻度,用的是固定的假语料与固定的当前时间,
|
|
140
|
+
评测的是相关性排序本身,不碰文件系统。指标有三类:top-1 命中率、
|
|
141
|
+
MRR(第一个正确结果名次的倒数)、以及陷阱用例是否失守。
|
|
142
|
+
|
|
143
|
+
陷阱有两类。第一类是高频词陷阱:对话里塞满项目名,旧的关键词计数算法会让满篇项目名的
|
|
144
|
+
README 霸榜。第二类是长文档陷阱:什么话题都提一句的归档长文,因为堆词而排到前面。
|
|
145
|
+
退化场景也要盯着:如果只有一个文档有分,名次就没有信息量。
|
|
146
|
+
|
|
147
|
+
评测只测排序与集合关系,不设「分数必须大于多少」这种拍出来的阈值。
|
|
148
|
+
`,
|
|
149
|
+
}),
|
|
150
|
+
|
|
151
|
+
make('docs/tool-contract.md', {
|
|
152
|
+
title: 'knit_docs 工具契约',
|
|
153
|
+
summary: 'agent 工具的输入输出:为什么只给 snippet、不给完整正文。',
|
|
154
|
+
body: `
|
|
155
|
+
knit_docs 是给模型用的只读工具,返回当前任务最值得先看的项目上下文。
|
|
156
|
+
它只返回工作区相对路径,不返回绝对路径、不返回内部 haystack、不返回 score。
|
|
157
|
+
命中段落字段叫 snippet:它给的是每篇文档里真正命中的那一小段原文,
|
|
158
|
+
让模型据此判断要不要读整篇文档,而不必为了判断先读五篇。
|
|
159
|
+
|
|
160
|
+
为什么不直接返回完整正文:一次工具调用返回五篇文档的正文会占掉大量上下文,
|
|
161
|
+
而模型多数时候只需要确认「这篇讲的确实是我要的那件事」。
|
|
162
|
+
snippet 的具体截断规则见 \`docs/sdd-context-assembly.md\`。
|
|
163
|
+
`,
|
|
164
|
+
}),
|
|
165
|
+
|
|
166
|
+
make('docs/path-safety.md', {
|
|
167
|
+
title: '路径越界防护',
|
|
168
|
+
summary: '读文件接口的沙箱边界、扩展名白名单与响应头。',
|
|
169
|
+
body: `
|
|
170
|
+
Knit 按路径读文件的接口必须守住两条边界。第一条:路径解析之后必须落在会话工作区之内,
|
|
171
|
+
任何越界一律拒绝,包括目录穿越、绝对路径逃逸和符号链接绕行。第二条:扩展名白名单,
|
|
172
|
+
只放行图片与视频,图片上限十二兆、视频上限二百五十六兆。只允许 GET,只允许回环地址访问。
|
|
173
|
+
响应必须带 nosniff 与 default-src none sandbox。Knit 新增任何读文件的路由都要照抄这两条防护。
|
|
174
|
+
接口字段与错误码见 \`docs/api-contract.md\`。
|
|
175
|
+
`,
|
|
176
|
+
}),
|
|
177
|
+
|
|
178
|
+
make('docs/api-contract.md', {
|
|
179
|
+
title: '接口契约',
|
|
180
|
+
summary: 'recent 与 doc 两个路由的响应字段与错误码。',
|
|
181
|
+
body: `
|
|
182
|
+
Knit 列表接口的响应里,文档记录包含 kind、path、rel、name、title、summary、size、mtimeMs 与 score。
|
|
183
|
+
score 在没有排序依据时为 null,否则是零到一百的整数。响应顶层还有 mode、topic、keywords、
|
|
184
|
+
total 与 truncated。Knit 读正文的接口只接受工作区内的相对路径,越界返回错误码而不是文案。
|
|
185
|
+
Knit 的宿主只返回错误码,面向用户的文字全部由客户端词典翻译。
|
|
186
|
+
`,
|
|
187
|
+
}),
|
|
188
|
+
|
|
189
|
+
make('docs/sdd-context-assembly.md', {
|
|
190
|
+
title: '上下文装配设计',
|
|
191
|
+
summary: '主要上下文 / 辅助上下文 / 相关上下文的确定性判据,为什么不做 AI 判断。',
|
|
192
|
+
body: `
|
|
193
|
+
Context Pack 是一层纯投影:输入是已经算好的相关度名次与命中词,输出是三层上下文。
|
|
194
|
+
判据全部是确定性规则,不引入第二个打分系统。主要上下文要求「够锚定」:
|
|
195
|
+
命中标题、或命中两个以上不同话题词、或命中比足够高且跨两个字段。
|
|
196
|
+
辅助上下文收「命中了但没进主要」的,以及与主要上下文有引用关系的,
|
|
197
|
+
还有本身是代码角色的文档。相关上下文是其余有命中的条目。
|
|
198
|
+
|
|
199
|
+
引用关系不是「更相关」,它只是上下文信号:被主要文档引用的那篇,
|
|
200
|
+
往往就是读主文档时下一步该打开的东西。所以引用关系不能把一篇文档抬进主要上下文。
|
|
201
|
+
`,
|
|
202
|
+
}),
|
|
203
|
+
|
|
204
|
+
make('docs/media-browse.md', {
|
|
205
|
+
title: '图片与视频浏览',
|
|
206
|
+
summary: '方形缩略图网格、列数、视频首帧当海报。',
|
|
207
|
+
body: `
|
|
208
|
+
Knit 的媒体视图把图片与视频铺成方形缩略图网格。列数由 CSS 的 auto-fill 连续数出来,
|
|
209
|
+
格子基准边长固定,面板变宽就多一列而不是把格子吹大。视频用 video 标签的 preload metadata
|
|
210
|
+
让浏览器自己解出首帧当海报,中间叠播放三角,右下角叠时长角标,零依赖、零转码。
|
|
211
|
+
视频走 HTTP Range 流式取字节,不会全量下载。按扩展名放行媒体,不解析画面内容。
|
|
212
|
+
`,
|
|
213
|
+
}),
|
|
214
|
+
|
|
215
|
+
// 长文档陷阱:很长、把很多话题词各提一次,但哪一件都没讲清楚。
|
|
216
|
+
make('docs/long-archive.md', {
|
|
217
|
+
title: 'Knit 归档长文',
|
|
218
|
+
summary: 'Knit 的历史归档,涵盖许多话题。',
|
|
219
|
+
body: `
|
|
220
|
+
这是 Knit 的一篇很长的归档文档,里面什么都会提一句。相关性排序提到了一次。
|
|
221
|
+
BM25 与 IDF 提到了一次。关键词计数提到了一次。图片与视频浏览提到了一次。
|
|
222
|
+
发布清单提到了一次。竞品调研提到了一次。路径越界防护提到了一次。
|
|
223
|
+
npm 打包提到了一次。目录布局提到了一次。clone 之后测试失败提到了一次。
|
|
224
|
+
knit_docs 提到了一次。snippet 提到了一次。命中段落提到了一次。
|
|
225
|
+
接口契约提到了一次。错误码提到了一次。扩展名白名单提到了一次。
|
|
226
|
+
上下文分层提到了一次。主要上下文提到了一次。辅助上下文提到了一次。
|
|
227
|
+
为了制造长度,下面这段重复但不含新话题词:
|
|
228
|
+
${'Knit 归档归档归档归档归档归档归档归档归档。'.repeat(60)}
|
|
229
|
+
`,
|
|
230
|
+
}),
|
|
231
|
+
|
|
232
|
+
// ── 下面这批是「工作区里正常会有的其他文档」────────────────────────
|
|
233
|
+
// 它们的作用不是提供答案,而是让语料**像真的**:真实项目里 20 篇文档中
|
|
234
|
+
// 只有 1 篇是当前任务的答案,剩下的都是背景。没有它们,「Related 层装不下」
|
|
235
|
+
// 与「层内排序」这两件事都测不到(语料太小时每条都能进某一层)。
|
|
236
|
+
make('docs/user-guide.md', {
|
|
237
|
+
title: '使用说明',
|
|
238
|
+
summary: '安装、打开面板、切换类型、过滤与预览。',
|
|
239
|
+
body: `
|
|
240
|
+
装好插件之后重启 DSH,然后硬刷新浏览器。点会话头部的 Knit 图标进入右边栏。
|
|
241
|
+
面板顶部是工作区路径,下面是排序方式与过滤框,再下面是类型切换。
|
|
242
|
+
单击列表里的一条会就地展开预览,双击会在新标签页里打开。
|
|
243
|
+
`,
|
|
244
|
+
}),
|
|
245
|
+
|
|
246
|
+
make('docs/contributing.md', {
|
|
247
|
+
title: '贡献指南',
|
|
248
|
+
summary: '怎么跑测试、怎么改代码、提交信息怎么写。',
|
|
249
|
+
body: `
|
|
250
|
+
改代码之前先跑一遍测试,确认基线是绿的。新加的文案必须同时进中英两本词典,
|
|
251
|
+
只加一边会被测试拦下。提交信息用约定式前缀。
|
|
252
|
+
不要为了更准引入模型调用 —— 纯本地是这个产品对外的承诺。
|
|
253
|
+
`,
|
|
254
|
+
}),
|
|
255
|
+
|
|
256
|
+
make('docs/security.md', {
|
|
257
|
+
title: '安全说明',
|
|
258
|
+
summary: '只读、回环地址、响应头与攻击面。',
|
|
259
|
+
body: `
|
|
260
|
+
这个插件只有两个读文件的路由,都只接受工作区内的相对路径。
|
|
261
|
+
它不发起任何外部网络请求,也不执行工作区里的任何代码。
|
|
262
|
+
报告安全问题时请附上可复现的最小步骤,不要贴真实项目内容。
|
|
263
|
+
`,
|
|
264
|
+
}),
|
|
265
|
+
|
|
266
|
+
make('docs/architecture.md', {
|
|
267
|
+
title: '架构总览',
|
|
268
|
+
summary: '扫描、排序、引用图、上下文装配四层的分工。',
|
|
269
|
+
body: `
|
|
270
|
+
工作区扫描负责找出 Markdown 与媒体,排序引擎负责算名次,引用图负责解析关系,
|
|
271
|
+
上下文装配负责把这三样投影成三层上下文。四层之间是单向依赖。
|
|
272
|
+
装配层是纯函数,不读盘;扫描结果是它唯一的输入。
|
|
273
|
+
`,
|
|
274
|
+
}),
|
|
275
|
+
|
|
276
|
+
make('docs/roadmap.md', {
|
|
277
|
+
title: '路线图',
|
|
278
|
+
summary: '已经做完的、正在做的、明确不做的。',
|
|
279
|
+
body: `
|
|
280
|
+
已经做完的:侧边栏列表、相关性排序、媒体浏览、agent 工具、引用关系、上下文分层。
|
|
281
|
+
明确不做的:向量检索、长期记忆、文档格式解析、图谱界面。
|
|
282
|
+
`,
|
|
283
|
+
}),
|
|
284
|
+
|
|
285
|
+
make('docs/release-checklist.md', {
|
|
286
|
+
title: '发布清单',
|
|
287
|
+
summary: 'npm 发布、版本号、打包内容与市场收录。',
|
|
288
|
+
body: `
|
|
289
|
+
发布前先跑测试并确认全绿,再核对版本号、确认没有 private 字段、
|
|
290
|
+
确认包名在 package json 与 cordis patch yml 里一致。
|
|
291
|
+
发布顺序是硬规则:先推成功,确认本地与远端与 npm 三处对齐,最后才发布。
|
|
292
|
+
`,
|
|
293
|
+
}),
|
|
294
|
+
|
|
295
|
+
make('docs/PRD-v0.14-context-pack.md', {
|
|
296
|
+
title: '上下文包需求',
|
|
297
|
+
summary: '把相关文档列表升级成三层任务上下文。',
|
|
298
|
+
body: `
|
|
299
|
+
这一版的目标不是继续堆文件浏览功能,而是把「按当前对话给文档排序」
|
|
300
|
+
升级成「按当前对话构建当前任务最需要的项目上下文」。
|
|
301
|
+
分类必须来自确定性的、本地可解释的规则,不许引入模型。
|
|
302
|
+
`,
|
|
303
|
+
}),
|
|
304
|
+
|
|
305
|
+
make('docs/faq.md', {
|
|
306
|
+
title: '常见问题',
|
|
307
|
+
summary: '装不上、看不到、排序不动、预览空白怎么办。',
|
|
308
|
+
body: `
|
|
309
|
+
看不到面板时先确认插件真的挂上了。排序不动时确认当前排序方式是「相关」而不是「最新」。
|
|
310
|
+
如果对话内容还不足,面板会退回按修改时间排序,这是有意为之。
|
|
311
|
+
`,
|
|
312
|
+
}),
|
|
313
|
+
|
|
314
|
+
make('docs/glossary.md', {
|
|
315
|
+
title: '术语表',
|
|
316
|
+
summary: '上下文包、主要上下文、辅助上下文、相关上下文。',
|
|
317
|
+
body: `
|
|
318
|
+
上下文包是一层投影,不是新的数据库。主要上下文是当前任务最直接相关的几篇。
|
|
319
|
+
辅助上下文用于验证、补充或继续工作。相关上下文与当前任务有关,但不该抢占前两层。
|
|
320
|
+
`,
|
|
321
|
+
}),
|
|
322
|
+
|
|
323
|
+
make('docs/decisions.md', {
|
|
324
|
+
title: '技术决策记录',
|
|
325
|
+
summary: '为什么不用向量检索、为什么不做长期记忆。',
|
|
326
|
+
body: `
|
|
327
|
+
第一版明确不做向量检索与语义召回,因为那需要模型或外部服务,与「零模型零网络」冲突。
|
|
328
|
+
也不做长期记忆:当前对话只是检索的输入,工作区才是上下文的来源。
|
|
329
|
+
`,
|
|
330
|
+
}),
|
|
331
|
+
|
|
332
|
+
make('docs/testing.md', {
|
|
333
|
+
title: '测试说明',
|
|
334
|
+
summary: '测试不许依赖目录布局,样本一律现场造。',
|
|
335
|
+
body: `
|
|
336
|
+
所有测试都在临时目录里现造样本工作区,不许借仓库里的真实文件。
|
|
337
|
+
理由是同一个测试在作者本机、clone 之后、从 npm 装进 node_modules 之后,
|
|
338
|
+
三种目录布局下的「上一层」是三件不同的东西。
|
|
339
|
+
`,
|
|
340
|
+
}),
|
|
341
|
+
|
|
342
|
+
make('docs/changelog-policy.md', {
|
|
343
|
+
title: '变更记录规范',
|
|
344
|
+
summary: '每一条变更写清做了什么与为什么。',
|
|
345
|
+
body: `
|
|
346
|
+
变更记录按版本分节,每条先说做了什么、再说为什么。破坏性变更要单独标出来。
|
|
347
|
+
不要把内部实现细节写进去,用户关心的是行为变了没有。
|
|
348
|
+
`,
|
|
349
|
+
}),
|
|
350
|
+
|
|
351
|
+
make('notes/scratch.md', {
|
|
352
|
+
title: '随手记',
|
|
353
|
+
summary: '很短的一条。',
|
|
354
|
+
body: '把上下文分层的解释文案再读一遍,确认没有出现「AI 判断」这种说法。',
|
|
355
|
+
}),
|
|
356
|
+
]
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* 真实任务型用例。
|
|
360
|
+
*
|
|
361
|
+
* 每个用例声明三层的**期望集合**。断言方式是**包含**(expected ⊆ actual)而不是相等:
|
|
362
|
+
* 多出来的条目不算失败(它可能就是下一条该看的),但**该出现的没出现必须红**。
|
|
363
|
+
*
|
|
364
|
+
* `notPrimary` 专门用来钉死污染源 —— README / CHANGELOG / 长归档
|
|
365
|
+
* 在**检索**里已经排得不错了,但仍不许它们霸占 Primary。
|
|
366
|
+
*/
|
|
367
|
+
export const CASES = [
|
|
368
|
+
{
|
|
369
|
+
name: '任务 1:BM25 为什么比关键词计数好',
|
|
370
|
+
messages: [
|
|
371
|
+
'这个排序算法为什么这样设计?',
|
|
372
|
+
'BM25 这里我还是觉得有问题,它凭什么比关键词计数好?',
|
|
373
|
+
],
|
|
374
|
+
expectPrimary: ['docs/relevance-algorithm.md'],
|
|
375
|
+
expectSupporting: ['docs/eval-benchmark.md'],
|
|
376
|
+
// ⚠️ 这里曾经写 `['CHANGELOG.md']`(需求 §十七 案例 1 的示意)。
|
|
377
|
+
// 但实测本语料的 CHANGELOG **一次都没提 BM25 / 关键词计数**(raw=0)——
|
|
378
|
+
// 它之所以能进 Related,靠的是旧实现里「零命中的都塞进 Related」那条兜底,
|
|
379
|
+
// 而那条兜底给出的理由是 `related`(客户端译作「与当前工作区相关」),
|
|
380
|
+
// 恰好是需求 §九 明令禁止的「可能对你有帮助」。
|
|
381
|
+
// 2026-09-29 把 Related 收紧成「有命中、或与 Primary 有引用关系」之后,
|
|
382
|
+
// 本用例的 Related 变成真正命中了话题、但没有落脚点的长尾归档。
|
|
383
|
+
// (真实仓库的 CHANGELOG 里确实写着「排序升级为 BM25」,所以那个示意在真机上照样成立 ——
|
|
384
|
+
// 只是它成立的理由是「CHANGELOG 提到了这个话题」,而不是「工作区里还有这么一篇」。)
|
|
385
|
+
expectRelated: ['docs/long-archive.md'],
|
|
386
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
387
|
+
},
|
|
388
|
+
{
|
|
389
|
+
name: '任务 2:npm 包为什么测试在 clone 后失败',
|
|
390
|
+
messages: [
|
|
391
|
+
'这个 npm 包为什么测试在 clone 之后就失败?',
|
|
392
|
+
'目录布局依赖不是已经去掉了吗?',
|
|
393
|
+
],
|
|
394
|
+
expectPrimary: ['docs/package-layout.md'],
|
|
395
|
+
expectSupporting: ['README.md'],
|
|
396
|
+
expectRelated: [],
|
|
397
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
398
|
+
},
|
|
399
|
+
{
|
|
400
|
+
name: '任务 3:knit_docs 为什么要返回 snippet',
|
|
401
|
+
messages: [
|
|
402
|
+
'knit_docs 为什么要返回 snippet?',
|
|
403
|
+
'直接把完整正文给它不行吗?',
|
|
404
|
+
],
|
|
405
|
+
expectPrimary: ['docs/tool-contract.md'],
|
|
406
|
+
// 设计文档由**引用关系**带进辅助上下文,理由必须是 linkTarget(不是假装命中)
|
|
407
|
+
expectSupporting: ['docs/sdd-context-assembly.md'],
|
|
408
|
+
expectRelated: [],
|
|
409
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
410
|
+
},
|
|
411
|
+
{
|
|
412
|
+
name: '任务 4:路径越界怎么防',
|
|
413
|
+
messages: [
|
|
414
|
+
'路径越界怎么防?',
|
|
415
|
+
'目录穿越和绝对路径逃逸都挡住了吗,扩展名白名单呢?',
|
|
416
|
+
],
|
|
417
|
+
expectPrimary: ['docs/path-safety.md'],
|
|
418
|
+
// 接口契约由引用关系带进来(「被主要文档引用」)
|
|
419
|
+
expectSupporting: ['docs/api-contract.md'],
|
|
420
|
+
// 需求 §十七 案例 4 的示意是「Related: API contract」—— 这里 api-contract 走得更前,
|
|
421
|
+
// 它在 **Supporting**(比 Related 强)。原先 Related 断言的是 README,
|
|
422
|
+
// 但 README 对本话题 raw=0,属于同一条被删掉的零命中兜底(见任务 1 的注释)。
|
|
423
|
+
expectRelated: ['docs/long-archive.md'],
|
|
424
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
425
|
+
},
|
|
426
|
+
{
|
|
427
|
+
name: '任务 5:上下文分层凭什么这么分',
|
|
428
|
+
messages: [
|
|
429
|
+
'Context Pack 为什么把这篇放在主要上下文?',
|
|
430
|
+
'辅助上下文和相关上下文的判据是什么?',
|
|
431
|
+
],
|
|
432
|
+
expectPrimary: ['docs/sdd-context-assembly.md'],
|
|
433
|
+
expectSupporting: [],
|
|
434
|
+
// Related 上限按 PRD §5 收到 5 之后,`notes/scratch.md`(raw=1、名次第 9)落在上限之外 ——
|
|
435
|
+
// 它在本用例里确实是尾部噪音。改断言这两篇:术语表与 PRD 都是「有关但不该先看」的典型。
|
|
436
|
+
// scratch.md 的守卫由任务 12 承担(那条它 raw=41 排第 1,但三层都进不去)。
|
|
437
|
+
expectRelated: ['docs/glossary.md', 'docs/PRD-v0.14-context-pack.md'],
|
|
438
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
439
|
+
},
|
|
440
|
+
{
|
|
441
|
+
name: '任务 6:评测指标为什么要看 MRR',
|
|
442
|
+
messages: [
|
|
443
|
+
'排序评测的指标为什么要看 MRR?',
|
|
444
|
+
'top-1 和陷阱用例分别管什么?',
|
|
445
|
+
],
|
|
446
|
+
expectPrimary: ['docs/eval-benchmark.md'],
|
|
447
|
+
expectSupporting: [],
|
|
448
|
+
expectRelated: [],
|
|
449
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
450
|
+
},
|
|
451
|
+
{
|
|
452
|
+
name: '任务 7:媒体网格的列数怎么定',
|
|
453
|
+
messages: [
|
|
454
|
+
'图片和视频的缩略图网格列数是怎么定的?',
|
|
455
|
+
'为什么不用条目数反推格宽?',
|
|
456
|
+
],
|
|
457
|
+
expectPrimary: ['docs/media-browse.md'],
|
|
458
|
+
expectSupporting: [],
|
|
459
|
+
expectRelated: [],
|
|
460
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
461
|
+
},
|
|
462
|
+
{
|
|
463
|
+
name: '任务 8:recent 接口的字段与错误码',
|
|
464
|
+
messages: [
|
|
465
|
+
'recent 接口的响应字段有哪些?',
|
|
466
|
+
'宿主为什么只返回错误码不返回文案?',
|
|
467
|
+
],
|
|
468
|
+
expectPrimary: ['docs/api-contract.md'],
|
|
469
|
+
expectSupporting: [],
|
|
470
|
+
expectRelated: [],
|
|
471
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
472
|
+
},
|
|
473
|
+
{
|
|
474
|
+
name: '任务 9:高频词陷阱到底指什么',
|
|
475
|
+
messages: [
|
|
476
|
+
'高频词陷阱具体是指什么情况?',
|
|
477
|
+
'满篇项目名的 README 会霸榜吗?',
|
|
478
|
+
],
|
|
479
|
+
expectPrimary: ['docs/eval-benchmark.md'],
|
|
480
|
+
expectSupporting: ['docs/relevance-algorithm.md'],
|
|
481
|
+
expectRelated: [],
|
|
482
|
+
notPrimary: ['README.md', 'docs/long-archive.md'],
|
|
483
|
+
},
|
|
484
|
+
{
|
|
485
|
+
name: '任务 10:长文档靠堆词赢的问题',
|
|
486
|
+
messages: [
|
|
487
|
+
'长文档靠堆词就能排前面,这个问题怎么解决的?',
|
|
488
|
+
'长度归一化具体压的是什么?',
|
|
489
|
+
],
|
|
490
|
+
// Primary 上限收到 1(PRD §5「Top 1」)后这里只能断言一篇:问的是**长度归一化**,
|
|
491
|
+
// 该先看的显然是讲算法的那篇(raw=9,摘要命中),评测基准(raw=7)退到 Supporting。
|
|
492
|
+
expectPrimary: ['docs/relevance-algorithm.md'],
|
|
493
|
+
expectSupporting: ['docs/eval-benchmark.md'],
|
|
494
|
+
// 原先断言 CHANGELOG —— 它对「长文档 / 长度归一化 / 堆词」这个话题 raw=0,
|
|
495
|
+
// 靠的是已被删除的零命中兜底(见任务 1 的注释)。收紧之后本用例 Related 为空:
|
|
496
|
+
// **「这里没有相关背景」是合法结论**,不该用一篇没提过这个话题的文档去补位。
|
|
497
|
+
expectRelated: [],
|
|
498
|
+
notPrimary: ['README.md', 'CHANGELOG.md', 'docs/long-archive.md'],
|
|
499
|
+
},
|
|
500
|
+
{
|
|
501
|
+
name: '任务 11:这批文档一共多少篇、按什么排序',
|
|
502
|
+
messages: [
|
|
503
|
+
'你现在列出来的是按什么排序的?',
|
|
504
|
+
'是不是把工作区里的文档都列全了?',
|
|
505
|
+
],
|
|
506
|
+
// ⚠️ **已知不能判**:这两篇的 raw 都是 4,且**标题里都含「排序」**(`排序[TB3]`)。
|
|
507
|
+
// 「按什么排序」问的语义上更像排序算法那篇,但 BM25 只看得见词 —— 它没有任何
|
|
508
|
+
// 依据在这一对上分高下。所以这里断言的是**一对可接受的答案**,不是二者之一。
|
|
509
|
+
// 这条断言就是那条局限的存档:如果哪天它变成唯一解,说明我们偷偷加了语义判断。
|
|
510
|
+
expectPrimaryOneOf: ['docs/relevance-algorithm.md', 'docs/eval-benchmark.md'],
|
|
511
|
+
expectSupporting: [],
|
|
512
|
+
expectRelated: [],
|
|
513
|
+
notPrimary: ['docs/long-archive.md'],
|
|
514
|
+
},
|
|
515
|
+
{
|
|
516
|
+
name: '任务 12:把上下文分层的解释文案再核一遍',
|
|
517
|
+
messages: [
|
|
518
|
+
'把上下文分层的解释文案再读一遍',
|
|
519
|
+
'确认没有出现 AI 判断这种说法',
|
|
520
|
+
],
|
|
521
|
+
// ⚠️ 这一条是**分层的价值**最直白的证据:语料里名次最高的是 `notes/scratch.md`
|
|
522
|
+
// (它就是那句「把上下文分层的解释文案再读一遍」的出处),但它是张便签,
|
|
523
|
+
// 不是这个任务的答案。装配层不把它当主要上下文 —— 名次第一 ≠ 先看这篇。
|
|
524
|
+
expectPrimary: [],
|
|
525
|
+
expectSupporting: ['docs/sdd-context-assembly.md'],
|
|
526
|
+
expectRelated: ['notes/scratch.md'],
|
|
527
|
+
notPrimary: ['notes/scratch.md', 'README.md', 'CHANGELOG.md'],
|
|
528
|
+
},
|
|
529
|
+
]
|
|
530
|
+
|
|
531
|
+
/**
|
|
532
|
+
* 从语料里造一个引用图 —— **走真实的 `buildLinkGraph`**,不用手写边。
|
|
533
|
+
*
|
|
534
|
+
* 这样测的才是「`links.js` 解析出来的关系真的被装配层用上了」,
|
|
535
|
+
* 而不是「装配层能用上一张我自己造的图」。
|
|
536
|
+
*
|
|
537
|
+
* @param {Function} buildLinkGraph - `links.js` 的实现(注入,理由同其余模块)
|
|
538
|
+
* @param {Array<object>} [corpus] - 语料;默认 `CORPUS`
|
|
539
|
+
* @returns {Promise<object>} 引用图
|
|
540
|
+
*/
|
|
541
|
+
export async function buildFixtureGraph(buildLinkGraph, corpus = CORPUS) {
|
|
542
|
+
const byRel = new Map(corpus.map((doc) => [doc.rel, doc]))
|
|
543
|
+
return buildLinkGraph('/knit-context-eval', {
|
|
544
|
+
// ⚠️ list 给的是**全量**语料(不是切片)—— 与宿主里 `linkGraphFor` 的做法一致。
|
|
545
|
+
list: async () => ({ docs: corpus.map((doc) => ({ rel: doc.rel, title: doc.title })), truncated: false }),
|
|
546
|
+
// read 用文档记录上现成的原文 —— 与宿主复用 `head` 的做法同源,零额外 I/O。
|
|
547
|
+
read: async (_root, rel) => {
|
|
548
|
+
const entry = byRel.get(rel)
|
|
549
|
+
if (!entry || typeof entry.text !== 'string') return { ok: false }
|
|
550
|
+
return { ok: true, text: entry.text }
|
|
551
|
+
},
|
|
552
|
+
})
|
|
553
|
+
}
|