dsh-wiki-notes 0.0.0-stage → 1.1.1

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/lib/engine.js ADDED
@@ -0,0 +1,921 @@
1
+ /**
2
+ * engine.js —— 检索/取页/目录/总览四种查询。纯函数风格,输入 corpus,输出可序列化对象。
3
+ *
4
+ * 评分规则是 search.py 的超集(权重保持一致,方便 A/B 对比召回是否下降):
5
+ * 标题全等 120 / 标题包含 60 / 别名包含 50 / 标签包含 25 / 正文命中 ×3 封顶 12
6
+ * 新增一项 index 摘要包含 8 —— index.md 那行摘要是人工提炼的,正文里常常没有
7
+ * 这个词,如果没有它,「上下文怎么管」这种说法就搜不到「上下文工程」。
8
+ */
9
+
10
+ import { asList } from './corpus.js'
11
+
12
+ const DEFAULT_SECTION_CHARS = 900
13
+ const DEFAULT_PAGE_CHARS = 6000
14
+
15
+ /**
16
+ * 参数边界只在入口解析一次,里面的函数直接信这个数。
17
+ * 越界不炸(llm 偶尔会写 limit: 999),但也不能让它真返回一万条。
18
+ */
19
+ function intOption(options, key, fallback, lo, hi) {
20
+ const value = Number(options[key] ?? fallback) || fallback
21
+ return Math.max(lo, Math.min(value, hi))
22
+ }
23
+
24
+ /** 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。 */
25
+ export function tokenize(query) {
26
+ const trimmed = String(query ?? '').trim()
27
+ if (trimmed === '') return []
28
+ const parts = trimmed.split(/[\s,,、。;;/|]+/).map((part) => part.trim()).filter((part) => part !== '')
29
+ // 去重但保留顺序
30
+ const seen = new Set()
31
+ const out = []
32
+ for (const part of parts) {
33
+ const key = part.toLowerCase()
34
+ if (seen.has(key)) continue
35
+ seen.add(key)
36
+ out.push(part)
37
+ }
38
+ return out
39
+ }
40
+
41
+ /** 标签比较不区分大小写:主题词统计那边已经归并 `RAG`/`rag`,查询这边不能反而更严。 */
42
+ function matchesTag(pageTags, wanted) {
43
+ const lower = String(wanted).toLowerCase()
44
+ return pageTags.some((tag) => tag.toLowerCase() === lower)
45
+ }
46
+
47
+ function countOccurrences(haystack, needle) {
48
+ if (needle === '' || haystack === '') return 0
49
+ const h = haystack.toLowerCase()
50
+ const n = needle.toLowerCase()
51
+ let count = 0
52
+ let idx = h.indexOf(n)
53
+ while (idx !== -1) {
54
+ count += 1
55
+ idx = h.indexOf(n, idx + n.length)
56
+ if (count > 200) break
57
+ }
58
+ return count
59
+ }
60
+
61
+ /**
62
+ * 单个检索词对单个页面的贡献分。0 表示这个词与这页无关。
63
+ *
64
+ * 权重与 search.py **完全一致**(标题全等 120 / 标题含 60 / 别名含 50 / 标签 25 /
65
+ * 正文 min(命中数,12)×3,各项累加),因为 A/B 的目标是「召回不降」——算法一变,
66
+ * 对比就失去意义。唯一的新增是 index.md 摘要命中 +8:那行摘要人工提炼过,
67
+ * 常含正文里不出现的说法(例如「上下文怎么管」这类口语),不加就搜不到。
68
+ */
69
+ function termScore(page, token) {
70
+ const name = page.name.toLowerCase()
71
+ const term = token.toLowerCase()
72
+ let score = 0
73
+ if (name === term) score += 120
74
+ else if (name.includes(term)) score += 60
75
+
76
+ for (const alias of asList(page.fields['别名'])) {
77
+ if (alias.toLowerCase().includes(term)) {
78
+ score += 50
79
+ break
80
+ }
81
+ }
82
+ for (const tag of asList(page.fields['标签'])) {
83
+ if (tag.toLowerCase().includes(term)) {
84
+ score += 25
85
+ break
86
+ }
87
+ }
88
+ score += Math.min(countOccurrences(page.body, term), 12) * 3
89
+ return score
90
+ }
91
+
92
+ /**
93
+ * index.md 摘要通道:**只在其它通道全零时才给分**。
94
+ *
95
+ * 一开始把 +8 加进总分,立刻把某个 query 的 top5 挤掉三页——摘要里提到过
96
+ * 某个词的资料页会顶掉真正相关的笔记页,召回不降的目标当场就破了。改成「只补漏、
97
+ * 不抢位」之后,它只负责 search.py 搜不到的口语说法,不干扰既有名次。
98
+ */
99
+ const INDEX_ONLY_SCORE = 8
100
+
101
+ /** 类型分层:同分时结构化笔记优先于原始资料摘要 —— 笔记是消化过的结论。 */
102
+ const TYPE_TIER = { 综合: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
103
+
104
+ function typeTier(page) {
105
+ return TYPE_TIER[String(page.fields['类型'] ?? '')] ?? 2
106
+ }
107
+
108
+ /**
109
+ * 排序:先「命中全部检索词」的页,再按分数。
110
+ *
111
+ * 多词查询里总有几页像「某课程·资料摘要」这种大而全的资料页,每个词都沾一点、分数最高,
112
+ * 但不是答案。把只命中一部分词的页压到全命中页后面,等于保留 search.py 的 AND 语义;
113
+ * 全部页都只命中一部分时(库里的确没写这个词),次序退回纯分数,并标 degraded。
114
+ */
115
+ function compareHits(a, b) {
116
+ if (a.allTerms !== b.allTerms) return a.allTerms ? -1 : 1
117
+ if (b.score !== a.score) return b.score - a.score
118
+ const tierDiff = typeTier(b.page) - typeTier(a.page)
119
+ if (tierDiff !== 0) return tierDiff
120
+ const updatedA = String(a.page.fields['更新'] ?? '')
121
+ const updatedB = String(b.page.fields['更新'] ?? '')
122
+ if (updatedA !== updatedB) return updatedB.localeCompare(updatedA)
123
+ // 码点序(不是拼音序):与文件系统里的名字顺序一致,同分次序可复现。
124
+ // 用 localeCompare('zh') 会按拼音重排,A/B 对比时同一组 3 分页会漂移。
125
+ return a.page.name < b.page.name ? -1 : a.page.name > b.page.name ? 1 : 0
126
+ }
127
+
128
+ /** 页面性质:原始资料压缩稿 / 资料页 / 结构化笔记。渲染时给模型一个判断依据。 */
129
+ function pageKind(page) {
130
+ const type = String(page.fields['类型'] ?? '')
131
+ if (type === '资料') {
132
+ return page.name.endsWith('·资料摘要') ? 'raw-summary' : 'source'
133
+ }
134
+ return 'note'
135
+ }
136
+
137
+ /** 正文开头那句 `> 一句话总结:…` / `> 定义:…`,一两百字就能判断该不该读整页。 */
138
+ function extractGist(body) {
139
+ const match = String(body ?? '').match(/^>\s*(?:一句话总结|定义|一句话|摘要)[::]\s*(.+)$/m)
140
+ return match === null ? '' : clip(match[1].trim(), 140)
141
+ }
142
+
143
+ /**
144
+ * 不该抢头名的小节:前一组只是清单,后一组谈的是「这一页自己」而不是它讲的主题。
145
+ * 命中了也不是答案,先排掉,实在没有别的小节才回退。
146
+ */
147
+ const BOILERPLATE_TITLES = [
148
+ '元信息', '原始文件', '文件清单', '更新日志', '变更记录', '修订记录', '来源', '参考', '附录',
149
+ '悬而未决', '值得追问', '它改变了什么', '相关', '待办', '遗留',
150
+ ]
151
+
152
+ function isBoilerplate(title) {
153
+ return BOILERPLATE_TITLES.some((word) => title.includes(word))
154
+ }
155
+
156
+ /**
157
+ * 挑命中最密的一节交给模型。
158
+ *
159
+ * 先按「命中了几种检索词」排(覆盖广度比出现次数更能说明这一节在讲什么),再按次数。
160
+ * 清单类小节先排除:`§元信息` 里列着 `03-第一讲-要点.md` 这种文件名,词频很高但
161
+ * 一个字都没回答「立意怎么写」,早先版本就是被它抢了头名。
162
+ */
163
+ function pickSection(page, tokens) {
164
+ const sections = page.sections
165
+ if (sections.length === 0) return { title: '', text: page.body }
166
+ const candidates = sections.filter((section) => section.title !== '' && !isBoilerplate(section.title))
167
+ const pool = candidates.length > 0 ? candidates : sections.filter((section) => section.title !== '')
168
+ const realPool = pool.length > 0 ? pool : sections
169
+ let best = null
170
+ let bestScore = 0
171
+ for (const [index, section] of realPool.entries()) {
172
+ let covered = 0
173
+ let hits = 0
174
+ for (const token of tokens) {
175
+ const inTitle = countOccurrences(section.title, token)
176
+ const inText = countOccurrences(section.text, token)
177
+ if (inTitle + inText > 0) covered += 1
178
+ hits += inTitle * 3 + inText
179
+ }
180
+ if (covered === 0) continue
181
+ // 靠前的小节更像「这页在讲什么」:越往后越可能是补充、反例、边角。给一点微弱的顺位分,
182
+ // 只在命中密度接近时起作用。
183
+ const positionBonus = (realPool.length - index) / realPool.length * 6
184
+ const score = covered * 10 + Math.min(hits, 30) + positionBonus
185
+ if (score > bestScore) {
186
+ bestScore = score
187
+ best = section
188
+ }
189
+ }
190
+ return best ?? realPool[0]
191
+ }
192
+
193
+ function clip(text, limit) {
194
+ const value = String(text ?? '')
195
+ if (limit <= 0 || value.length <= limit) return value
196
+ return `${value.slice(0, limit)}…`
197
+ }
198
+
199
+ function buildIndexMap(corpus) {
200
+ const map = new Map()
201
+ for (const line of corpus.indexLines) {
202
+ if (!map.has(line.name)) map.set(line.name, line)
203
+ }
204
+ return map
205
+ }
206
+
207
+ /**
208
+ * 超大页没有正文可比(只记了元数据),所以「相关性」只能看页名与 index 摘要。
209
+ * 这是「有没有可能相关」的线索,不是正文检索 —— 标题和摘要没命中,
210
+ * 不能反推正文没命中;这也是 no_match 只能表示「当前可检索范围未命中」的原因。
211
+ */
212
+ function oversizedRelevance(corpus, tokens, indexMap) {
213
+ let total = 0
214
+ let byTitle = 0
215
+ let bySummary = 0
216
+ for (const page of corpus.pages) {
217
+ if (page.oversized !== true) continue
218
+ const title = page.name.toLowerCase()
219
+ const summary = String(indexMap.get(page.name)?.summary ?? '').toLowerCase()
220
+ const titleHit = tokens.some((token) => title.includes(token.toLowerCase()))
221
+ const summaryHit = tokens.some((token) => summary.includes(token.toLowerCase()))
222
+ if (!titleHit && !summaryHit) continue
223
+ total += 1
224
+ if (titleHit) byTitle += 1
225
+ if (summaryHit) bySummary += 1
226
+ }
227
+ const via = byTitle > 0 && bySummary > 0 ? '标题与摘要' : byTitle > 0 ? '标题' : bySummary > 0 ? '摘要' : ''
228
+ return { total, via }
229
+ }
230
+
231
+ /**
232
+ * mode 2:search
233
+ * 返回 hits(按分数降序),每项带索引摘要、命中小节正文、citation、断链。
234
+ */
235
+ export function search(corpus, query, options = {}) {
236
+ const tokens = tokenize(query)
237
+ if (tokens.length === 0) {
238
+ return { mode: 'search', query, total: 0, tokens: [], hits: [], note: '空查询' }
239
+ }
240
+ const indexMap = buildIndexMap(corpus)
241
+ const limit = intOption(options, 'limit', 5, 1, 12)
242
+ const sectionChars = intOption(options, 'sectionChars', DEFAULT_SECTION_CHARS, 120, 3000)
243
+ const typeFilter = typeof options.type === 'string' && options.type.trim() !== '' ? options.type.trim() : null
244
+ const tagFilter = asList(options.tags)
245
+
246
+ const scored = []
247
+ // 分母要分开记:扫描了多少页、过滤后真正参与打分的多少页、命中的多少页、最后返回多少条。
248
+ // 只报一个「扫描 90 页,12 命中」,读起来像 90 页都比过了。
249
+ let considered = 0
250
+ for (const page of corpus.pages) {
251
+ if (page.oversized === true) continue
252
+ if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
253
+ if (tagFilter.length > 0) {
254
+ const pageTags = asList(page.fields['标签'])
255
+ if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
256
+ }
257
+ considered += 1
258
+ const indexLine = indexMap.get(page.name) ?? null
259
+ let total = 0
260
+ let matched = 0
261
+ for (const token of tokens) {
262
+ let score = termScore(page, token)
263
+ if (score === 0 && indexLine !== null && indexLine.summary.toLowerCase().includes(token.toLowerCase())) {
264
+ score = INDEX_ONLY_SCORE
265
+ }
266
+ total += score
267
+ if (score > 0) matched += 1
268
+ }
269
+ if (matched === 0) continue
270
+ scored.push({ page, indexLine, score: total, matched, allTerms: matched === tokens.length })
271
+ }
272
+
273
+ // AND 优先;一条 AND 都没有时降级为 OR,并在结果里说明,别让模型以为「库里没有」。
274
+ // 注意:OR 也一条没有时不算「降级」——那是真的没命中,标 degraded 反而误导。
275
+ let degraded = false
276
+ let list = scored.filter((item) => item.allTerms)
277
+ if (list.length === 0) {
278
+ degraded = scored.length > 0
279
+ list = scored
280
+ }
281
+
282
+ list.sort(compareHits)
283
+
284
+ const hits = list.slice(0, limit).map((item) => {
285
+ const section = pickSection(item.page, tokens)
286
+ const broken = section.text !== ''
287
+ ? [...new Set((section.text.match(/\[\[([^\]|#]+)/g) ?? []).map((raw) => raw.slice(2).trim()))]
288
+ .filter((link) => !corpus.byName.has(link) && !corpus.byAlias.has(link.toLowerCase()))
289
+ : []
290
+ return {
291
+ name: item.page.name,
292
+ kind: pageKind(item.page),
293
+ type: String(item.page.fields['类型'] ?? ''),
294
+ status: String(item.page.fields['状态'] ?? ''),
295
+ sources: typeof item.page.fields['来源数量'] === 'number' ? item.page.fields['来源数量'] : null,
296
+ updated: String(item.page.fields['更新'] ?? ''),
297
+ tags: asList(item.page.fields['标签']),
298
+ aliases: asList(item.page.fields['别名']),
299
+ score: item.score,
300
+ allTerms: item.allTerms,
301
+ gist: extractGist(item.page.body),
302
+ summary: item.indexLine?.summary ?? '',
303
+ section: { title: section.title, text: clip(section.text, sectionChars) },
304
+ citation: `← [[${item.page.name}]]${section.title === '' ? '' : ` §${section.title}`} → ${item.page.file}`,
305
+ brokenLinks: broken,
306
+ file: item.page.file,
307
+ }
308
+ })
309
+
310
+ const oversized = oversizedRelevance(corpus, tokens, indexMap)
311
+
312
+ return {
313
+ mode: 'search',
314
+ query,
315
+ tokens,
316
+ total: list.length,
317
+ degraded,
318
+ // 调用级统计:分母各是各的,别合成一个数字
319
+ considered,
320
+ matched: scored.length,
321
+ allTerms: scored.filter((item) => item.allTerms).length,
322
+ returned: hits.length,
323
+ // 超大页里「标题或 index 摘要」沾到查询词的数量:决定这次要不要提醒覆盖缺口,
324
+ // 不参与命中与排序 —— 它只是元数据线索,不是正文检索结果
325
+ oversizedRelevant: oversized.total,
326
+ oversizedRelevantVia: oversized.via,
327
+ hits,
328
+ note: degraded ? '没有同时命中全部检索词,已降级为「命中任一」,命中面变宽、精度下降' : '',
329
+ }
330
+ }
331
+
332
+ /** mode 2:page —— 按页名/别名/模糊取整页。取不到就给最像的 5 个候选。 */
333
+ export function page(corpus, name, options = {}) {
334
+ const wanted = String(name ?? '').trim()
335
+ const limit = intOption(options, 'pageChars', DEFAULT_PAGE_CHARS, 500, 20000)
336
+ if (wanted === '') return { mode: 'page', found: null, candidates: [] }
337
+
338
+ const indexMap = buildIndexMap(corpus)
339
+ const exact = corpus.byName.get(wanted) ?? corpus.byName.get(wanted.replace(/\.md$/i, ''))
340
+ if (exact !== undefined) return { mode: 'page', found: renderPage(corpus, exact, indexMap, limit), candidates: [] }
341
+
342
+ const aliasHits = corpus.byAlias.get(wanted.toLowerCase()) ?? []
343
+ if (aliasHits.length > 0) {
344
+ const first = aliasHits[0]
345
+ return { mode: 'page', found: renderPage(corpus, first, indexMap, limit), candidates: [] }
346
+ }
347
+
348
+ // 模糊:包含关系 → 相似度
349
+ const scored = corpus.pages
350
+ .filter((p) => p.oversized !== true)
351
+ .map((p) => {
352
+ const lower = p.name.toLowerCase()
353
+ const target = wanted.toLowerCase()
354
+ let score = 0
355
+ if (lower.includes(target) || target.includes(lower)) score += 60
356
+ score += bigramSimilarity(lower, target) * 100
357
+ return { page: p, score }
358
+ })
359
+ .filter((item) => item.score > 20)
360
+ .sort((a, b) => b.score - a.score)
361
+ .slice(0, 5)
362
+
363
+ return {
364
+ mode: 'page',
365
+ found: null,
366
+ wanted,
367
+ candidates: scored.map((item) => ({
368
+ name: item.page.name,
369
+ type: String(item.page.fields['类型'] ?? ''),
370
+ updated: String(item.page.fields['更新'] ?? ''),
371
+ summary: indexMap.get(item.page.name)?.summary ?? '',
372
+ score: Math.round(item.score),
373
+ })),
374
+ note: scored.length === 0 ? '没有任何页与这个名称相近' : '页名没精确命中,下面是候选;确认后把候选名当 name 再查一次',
375
+ }
376
+ }
377
+
378
+ function renderPage(corpus, page, indexMap, limit) {
379
+ const body = clip(page.body, limit)
380
+ return {
381
+ name: page.name,
382
+ type: String(page.fields['类型'] ?? ''),
383
+ status: String(page.fields['状态'] ?? ''),
384
+ sources: typeof page.fields['来源数量'] === 'number' ? page.fields['来源数量'] : null,
385
+ created: String(page.fields['创建'] ?? ''),
386
+ updated: String(page.fields['更新'] ?? ''),
387
+ tags: asList(page.fields['标签']),
388
+ aliases: asList(page.fields['别名']),
389
+ summary: indexMap.get(page.name)?.summary ?? '',
390
+ sections: page.sections.map((section) => section.title).filter((title) => title !== ''),
391
+ body,
392
+ truncated: body.length < page.body.length,
393
+ citation: `← [[${page.name}]] → ${page.file}`,
394
+ file: page.file,
395
+ }
396
+ }
397
+
398
+ /** mode 3:list —— 按类型/标签/状态列目录,替代「每次读 1.5k token 的 index.md」。 */
399
+ export function list(corpus, options = {}) {
400
+ const typeFilter = typeof options.type === 'string' && options.type.trim() !== '' ? options.type.trim() : null
401
+ const statusFilter = typeof options.status === 'string' && options.status.trim() !== '' ? options.status.trim() : null
402
+ const tagFilter = asList(options.tags)
403
+ const indexMap = buildIndexMap(corpus)
404
+
405
+ const rows = corpus.pages
406
+ .filter((p) => p.oversized !== true)
407
+ .filter((p) => typeFilter === null || String(p.fields['类型'] ?? '') === typeFilter)
408
+ .filter((p) => statusFilter === null || String(p.fields['状态'] ?? '') === statusFilter)
409
+ .filter((p) => tagFilter.length === 0 || tagFilter.some((tag) => matchesTag(asList(p.fields['标签']), tag)))
410
+ .map((p) => ({
411
+ name: p.name,
412
+ type: String(p.fields['类型'] ?? ''),
413
+ status: String(p.fields['状态'] ?? ''),
414
+ sources: typeof p.fields['来源数量'] === 'number' ? p.fields['来源数量'] : null,
415
+ updated: String(p.fields['更新'] ?? ''),
416
+ summary: indexMap.get(p.name)?.summary ?? '',
417
+ file: p.file,
418
+ }))
419
+ .sort((a, b) => (b.sources ?? -1) - (a.sources ?? -1) || a.name.localeCompare(b.name, 'zh'))
420
+
421
+ const byType = {}
422
+ for (const row of rows) byType[row.type || '(无类型)'] = (byType[row.type || '(无类型)'] ?? 0) + 1
423
+
424
+ // 上限 200:目录是给人扫一眼的,再多也不该一口气塞进上下文。
425
+ const limit = intOption(options, 'limit', 40, 1, 200)
426
+ const shown = rows.slice(0, limit)
427
+
428
+ return {
429
+ mode: 'list',
430
+ total: rows.length,
431
+ shown: shown.length,
432
+ truncated: shown.length < rows.length,
433
+ byType,
434
+ scale: corpus.scaleLine,
435
+ rows: shown,
436
+ }
437
+ }
438
+
439
+ /** mode 4:overview —— 全库当前状态:总览正文 + 规模行 + 最近日志 + 健康计数。 */
440
+ export function overview(corpus, options = {}) {
441
+ const indexMap = buildIndexMap(corpus)
442
+ const overviewPage = corpus.byName.get('总览-overview') ?? corpus.byName.get('总览')
443
+ const logLimit = intOption(options, 'logLimit', 5, 1, 20)
444
+ const recentLog = corpus.log.slice(-logLimit).map((entry) => ({
445
+ date: entry.date, type: entry.type, title: entry.title,
446
+ }))
447
+
448
+ // index.md 与磁盘的一致性:index 登记了但磁盘上没有的页(红链的另一种来源),
449
+ // 以及磁盘上有却没登记的页(新写的东西忘了进目录)。这两项是免费的库健康信号。
450
+ const diskNames = new Set(corpus.pages.map((page) => page.name))
451
+ const indexNames = new Set(corpus.indexLines.map((line) => line.name))
452
+ const indexOnly = corpus.indexLines.map((line) => line.name).filter((name) => !diskNames.has(name))
453
+ // 总览页是 overview 模式的数据源,本来就不该出现在「按主题分组的目录」里 —— 别报成漏登记
454
+ const overviewName = overviewPage?.name ?? ''
455
+ const diskOnly = corpus.pages
456
+ .map((page) => page.name)
457
+ .filter((name) => !indexNames.has(name) && name !== overviewName)
458
+
459
+ return {
460
+ mode: 'overview',
461
+ scale: corpus.scaleLine,
462
+ stats: {
463
+ pages: corpus.stats.pages,
464
+ resources: corpus.stats.resources,
465
+ brokenPages: corpus.stats.brokenPages,
466
+ brokenTotal: corpus.stats.brokenTotal,
467
+ // 库级缺陷在总览里如实报,但不拿它去污染单次检索的状态
468
+ oversized: corpus.stats.oversized ?? 0,
469
+ scannedMs: corpus.stats.scannedMs,
470
+ duplicateNames: corpus.stats.duplicateNames ?? [],
471
+ },
472
+ consistency: {
473
+ indexOnly: [...new Set(indexOnly)].slice(0, 10),
474
+ indexOnlyTotal: new Set(indexOnly).size,
475
+ diskOnly: [...new Set(diskOnly)].slice(0, 10),
476
+ diskOnlyTotal: new Set(diskOnly).size,
477
+ },
478
+ overview: overviewPage === undefined ? null : {
479
+ name: overviewPage.name,
480
+ body: clip(overviewPage.body, intOption(options, 'pageChars', 4000, 1000, 20000)),
481
+ citation: `← [[${overviewPage.name}]] → ${overviewPage.file}`,
482
+ sections: overviewPage.sections.map((section) => section.title).filter((title) => title !== ''),
483
+ summary: indexMap.get(overviewPage.name)?.summary ?? '',
484
+ },
485
+ recentLog,
486
+ broken: corpus.brokenLinks.slice(0, 10),
487
+ }
488
+ }
489
+
490
+ /** 每个页面至少该有的 frontmatter 字段(缺了会让排序、证据强度判断失真)。 */
491
+ const REQUIRED_FIELDS = ['类型', '状态', '标签', '更新']
492
+
493
+ /** 没推断出目录时的兜底顺序:与 karpathy 原文的 wiki 分层一致(概念/实体/对比/综合/资料)。 */
494
+ const DEFAULT_TYPE_DIRS = {
495
+ 概念: '概念-concepts',
496
+ 实体: '实体-entities',
497
+ 对比: '对比-comparisons',
498
+ 综合: '综合-syntheses',
499
+ 资料: '资料-sources',
500
+ }
501
+
502
+ /** 从现有页面的真实路径反推「类型 → 目录」,别把目录名写死。 */
503
+ function inferTypeDirs(corpus) {
504
+ const votes = new Map()
505
+ for (const page of corpus.pages) {
506
+ const type = typeof page.fields['类型'] === 'string' ? page.fields['类型'] : ''
507
+ const parts = String(page.file ?? '').split(/[\\/]/)
508
+ if (type === '' || parts.length < 2) continue
509
+ const dir = parts[parts.length - 2]
510
+ if (dir === '' || dir === '.') continue
511
+ const counter = votes.get(type) ?? new Map()
512
+ counter.set(dir, (counter.get(dir) ?? 0) + 1)
513
+ votes.set(type, counter)
514
+ }
515
+ const result = new Map()
516
+ for (const [type, counter] of votes) {
517
+ const best = [...counter.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0]
518
+ if (best !== undefined) result.set(type, best[0])
519
+ }
520
+ return result
521
+ }
522
+
523
+ /** 本地日期 YYYY-MM-DD。不能用 toISOString —— 那是 UTC,本机凌晨 0–8 点会差一天。 */
524
+ export function getLocalDate(date = new Date()) {
525
+ const year = date.getFullYear()
526
+ const month = String(date.getMonth() + 1).padStart(2, '0')
527
+ const day = String(date.getDate()).padStart(2, '0')
528
+ return `${year}-${month}-${day}`
529
+ }
530
+
531
+ /**
532
+ * 日志事件类型:不强制枚举(query / ingest / 拍板 / 结构补齐…本来该由调用方表达),
533
+ * 只挡住会破坏 `## [日期] 类型 | 标题` 这一行结构的东西。
534
+ */
535
+ function normalizeLogType(value) {
536
+ const text = String(value ?? '').trim()
537
+ if (text === '' || text.length > 24) return 'query'
538
+ if (/[\r\n|]/.test(text)) return 'query' // 换行或竖线会把 log 的第二个分隔符顶掉
539
+ return text
540
+ }
541
+
542
+ /**
543
+ * mode 6:draft —— 给「把这次的好答案回写成新页」生成落盘骨架(仍然只读,不写任何文件)。
544
+ *
545
+ * 对应 karpathy「LLM Wiki」原文 Query 一节:good answers can be filed back into the wiki
546
+ * as new pages,否则一次探索就消失在聊天记录里。回写真正的难点不是写正文,而是
547
+ * frontmatter 七个字段、该放哪个目录、index.md 那一行的格式、log.md 那条的格式 ——
548
+ * 这些都由本函数按库里现有约定现推,模型照着填就行。
549
+ */
550
+ export function draft(corpus, options = {}) {
551
+ const title = String(options.title ?? options.name ?? options.query ?? '').trim()
552
+ if (title === '') return { error: 'mode=draft 需要一个 title(新页的名字)' }
553
+
554
+ const typeDirs = inferTypeDirs(corpus)
555
+ const type = String(options.type ?? '').trim() || '概念'
556
+ const dir = typeDirs.get(type) ?? DEFAULT_TYPE_DIRS[type] ?? DEFAULT_TYPE_DIRS['概念']
557
+ // 日期只算一次,四处复用(frontmatter 创建/更新、indexLine、logLine)。
558
+ // 分别取四次的话,迟早出现「创建 03 号、log 02 号」这种自相矛盾的骨架。
559
+ const date = getLocalDate(Number.isFinite(Number(options.now)) ? new Date(Number(options.now)) : new Date())
560
+ // draft 是操作模式,logType 是日志事件类型(query / ingest / 拍板…),两件事不能混
561
+ const logType = normalizeLogType(options.logType)
562
+
563
+ const tags = asList(options.tags)
564
+ const aliases = asList(options.alias ?? options.aliases)
565
+ const sources = Number.isFinite(Number(options.sources)) ? Number(options.sources) : 0
566
+ const summary = String(options.summary ?? '').trim()
567
+ const file = `${dir}/${title}.md`
568
+
569
+ // 同名页已经存在时,回写会覆盖旧内容 —— 必须先在结果里警告,而不是让人写完才发现
570
+ const existing = corpus.byName.get(title) ?? corpus.byAlias.get(title) ?? null
571
+
572
+ const frontmatter = [
573
+ '---',
574
+ `类型: ${type}`,
575
+ '状态: 草稿',
576
+ `标签: [${tags.join(', ')}]`,
577
+ `别名: [${aliases.join(', ')}]`,
578
+ `来源数量: ${sources}`,
579
+ `创建: ${date}`,
580
+ `更新: ${date}`,
581
+ '---',
582
+ ].join('\n')
583
+
584
+ const body = [
585
+ `# ${title}`,
586
+ '',
587
+ `> 一句话总结:${summary === '' ? '(一句话说清这页讲什么)' : summary}`,
588
+ '',
589
+ '## 结论',
590
+ '',
591
+ '(先说结论。)',
592
+ '',
593
+ '## 依据',
594
+ '',
595
+ '(正文里用 [[双链]] 指向已有页;缺少的页会在 lint 里报成红链。)',
596
+ ].join('\n')
597
+
598
+ return {
599
+ mode: 'draft',
600
+ title,
601
+ type,
602
+ dir,
603
+ file,
604
+ exists: existing === null ? null : { name: existing.name, file: existing.file },
605
+ frontmatter,
606
+ body,
607
+ date,
608
+ logType,
609
+ indexLine: `- [[${title}]] — ${summary === '' ? '(一句话摘要)' : summary}(${sources} 份资料,更新于 ${date})`,
610
+ logLine: `## [${date}] ${logType} | ${title}`,
611
+ }
612
+ }
613
+
614
+ /** 总览页天然没有入链来源,不算孤儿。 */
615
+ const OVERVIEW_NAMES = new Set(['总览-overview', '总览'])
616
+
617
+ /**
618
+ * mode 5:lint —— 库健康检查,纯只读。
619
+ *
620
+ * 对应 karpathy「LLM Wiki」原文里的第三个操作 Lint:查孤儿页、断链、缺字段、
621
+ * 别名冲突、久未更新、单页无出链。原文还提到「页面间矛盾」「被新资料推翻的旧结论」
622
+ * 和「被提到但没有独立页的概念」——前两项要读懂内容才能判断,不是本函数能做到的,
623
+ * 这里只报可机械判定的部分(红链本身就是「被提到但没成页」的硬信号)。
624
+ */
625
+ export function lint(corpus, options = {}) {
626
+ const limit = intOption(options, 'limit', 8, 1, 40)
627
+ const staleDays = intOption(options, 'staleDays', 120, 1, 3650)
628
+ const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now()
629
+
630
+ // 超大文件只记了元数据(没读正文),拿它去比对「缺字段 / 无出链 / 孤儿」全是噪音:
631
+ // 单独列一项「未读入的大文件」,其余检查一律只看真正读进来的页。
632
+ const readable = corpus.pages.filter((page) => page.oversized !== true)
633
+ const oversized = corpus.pages.filter((page) => page.oversized === true).map((page) => page.name)
634
+
635
+ // 入链:别人正文里 [[X]] 指向它。X 可能是页名,也可能是别名 ——
636
+ // 别名命中时必须记在「拥有这个别名的那一页」名下,否则被别名引用的页会被误报成孤儿。
637
+ const inbound = new Map()
638
+ for (const page of corpus.pages) {
639
+ for (const link of page.links) {
640
+ if (link === page.name) continue
641
+ const owners = corpus.byAlias.get(link.toLowerCase()) ?? []
642
+ const target = corpus.byName.has(link) ? link : owners[0]?.name
643
+ if (target === undefined || target === page.name) continue
644
+ inbound.set(target, (inbound.get(target) ?? 0) + 1)
645
+ }
646
+ }
647
+ const orphans = readable
648
+ .filter((page) => !OVERVIEW_NAMES.has(page.name))
649
+ .filter((page) => (inbound.get(page.name) ?? 0) === 0)
650
+ .map((page) => page.name)
651
+
652
+ // 红链按「没人接的名字」聚合:同一个缺口被引用得越多,越该补页
653
+ const brokenCount = new Map()
654
+ for (const entry of corpus.brokenLinks) {
655
+ for (const name of entry.missing) brokenCount.set(name, (brokenCount.get(name) ?? 0) + 1)
656
+ }
657
+ const brokenTargets = [...brokenCount.entries()]
658
+ .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
659
+ .map(([name, pages]) => ({ name, pages }))
660
+
661
+ const missingFields = readable
662
+ .map((page) => ({
663
+ name: page.name,
664
+ missing: REQUIRED_FIELDS.filter((field) => page.fields[field] === undefined || page.fields[field] === ''),
665
+ }))
666
+ .filter((row) => row.missing.length > 0)
667
+
668
+ // 一个别名指向多个页时,检索排序会随文件顺序漂移,必须报出来
669
+ const aliasGroups = new Map()
670
+ for (const page of readable) {
671
+ for (const alias of asList(page.fields['别名'])) {
672
+ const owners = aliasGroups.get(alias) ?? []
673
+ owners.push(page.name)
674
+ aliasGroups.set(alias, owners)
675
+ }
676
+ }
677
+ const aliasConflicts = [...aliasGroups.entries()]
678
+ .map(([alias, owners]) => ({ alias, pages: [...new Set(owners)] }))
679
+ .filter((row) => row.pages.length > 1)
680
+
681
+ const stale = []
682
+ for (const page of readable) {
683
+ const raw = page.fields['更新']
684
+ if (typeof raw !== 'string' || raw.length < 10) continue
685
+ const time = Date.parse(`${raw.slice(0, 10)}T00:00:00Z`)
686
+ if (!Number.isFinite(time)) continue
687
+ const days = Math.floor((now - time) / 86400000)
688
+ if (days > staleDays) stale.push({ name: page.name, updated: raw.slice(0, 10), days })
689
+ }
690
+ stale.sort((a, b) => b.days - a.days)
691
+
692
+ const noLinks = readable.filter((page) => page.links.length === 0).map((page) => page.name)
693
+ const drafts = readable.filter((page) => page.fields['状态'] === '草稿').map((page) => page.name)
694
+
695
+ // index.md 与磁盘的两侧差异(与 overview 保持一致的口径)
696
+ const diskNames = new Set(corpus.pages.map((page) => page.name))
697
+ const indexNames = new Set(corpus.indexLines.map((line) => line.name))
698
+ const indexOnly = [...new Set(corpus.indexLines.map((line) => line.name).filter((name) => !diskNames.has(name)))]
699
+ const diskOnly = readable
700
+ .map((page) => page.name)
701
+ .filter((name) => !indexNames.has(name) && !OVERVIEW_NAMES.has(name))
702
+
703
+ return {
704
+ mode: 'lint',
705
+ staleDays,
706
+ stats: {
707
+ pages: corpus.stats.pages,
708
+ resources: corpus.stats.resources,
709
+ scannedMs: corpus.stats.scannedMs,
710
+ brokenPages: corpus.stats.brokenPages,
711
+ brokenTotal: corpus.stats.brokenTotal,
712
+ },
713
+ counts: {
714
+ orphans: orphans.length,
715
+ broken: brokenTargets.length,
716
+ missingFields: missingFields.length,
717
+ aliasConflicts: aliasConflicts.length,
718
+ stale: stale.length,
719
+ noLinks: noLinks.length,
720
+ drafts: drafts.length,
721
+ indexOnly: indexOnly.length,
722
+ diskOnly: diskOnly.length,
723
+ oversized: oversized.length,
724
+ },
725
+ orphans: orphans.slice(0, limit),
726
+ brokenTargets: brokenTargets.slice(0, limit),
727
+ missingFields: missingFields.slice(0, limit),
728
+ aliasConflicts: aliasConflicts.slice(0, limit),
729
+ stale: stale.slice(0, limit),
730
+ noLinks: noLinks.slice(0, limit),
731
+ drafts: drafts.slice(0, limit),
732
+ oversized: oversized.slice(0, limit),
733
+ consistency: { indexOnly: indexOnly.slice(0, limit), diskOnly: diskOnly.slice(0, limit) },
734
+ }
735
+ }
736
+
737
+ function bigramSimilarity(a, b) {
738
+ if (a === b) return 1
739
+ const grams = (text) => {
740
+ const set = new Set()
741
+ for (let i = 0; i < text.length - 1; i += 1) set.add(text.slice(i, i + 2))
742
+ return set
743
+ }
744
+ const ga = grams(a)
745
+ const gb = grams(b)
746
+ if (ga.size === 0 || gb.size === 0) return 0
747
+ let shared = 0
748
+ for (const gram of ga) if (gb.has(gram)) shared += 1
749
+ return (2 * shared) / (ga.size + gb.size)
750
+ }
751
+
752
+ /* ----------------------- 调用级:参数校验、状态与警告 ----------------------- */
753
+
754
+ export const MODES = ['search', 'page', 'list', 'overview', 'lint', 'draft']
755
+
756
+ /**
757
+ * 参数校验:必须在碰语料之前跑完。
758
+ * 空查询不该触发一次完整扫描,也不该被顺手归因成「库读不出来」或「库里没有」。
759
+ * 返回 null 表示参数没问题,否则返回一句给模型看的话。
760
+ */
761
+ export function validateArgs(mode, args = {}) {
762
+ if (!MODES.includes(mode)) return `未知 mode: ${mode}(可用 ${MODES.join(' / ')})`
763
+ if (mode === 'search' && tokenize(args.query ?? '').length === 0) {
764
+ return 'query 为空:请传 1–4 个关键词'
765
+ }
766
+ if (mode === 'page' && String(args.name ?? args.query ?? '').trim() === '') {
767
+ return 'name 为空:请传要查的页名'
768
+ }
769
+ if (mode === 'draft' && String(args.title ?? args.name ?? args.query ?? '').trim() === '') {
770
+ return 'title 为空:请传新页的名字'
771
+ }
772
+ return null
773
+ }
774
+
775
+ const toCount = (value, fallback = 0) => (Number.isFinite(value) ? value : fallback)
776
+
777
+ /**
778
+ * 状态判定:纯函数。只读 corpus.stats 与 result,绝不改 result、不动排序。
779
+ *
780
+ * 优先级不是按发生顺序排的,是按「错误结论的代价」排的:
781
+ * 「没搜全」被读成「没有」,比「没命中」被标成「不完整」贵得多 —— 所以覆盖类永远压过查询类。
782
+ * status 编码「模型该做什么」,warnings 编码「为什么」,两者都不承担修改结果的责任。
783
+ */
784
+ export function decideStatus(corpus, mode, args = {}, result = {}) {
785
+ const stats = (corpus && corpus.stats) || {}
786
+ const pages = toCount(stats.pages)
787
+ const discovered = toCount(stats.discovered, pages)
788
+ const unreadable = toCount(stats.unreadable)
789
+ const walkFailures = toCount(stats.walkFailures)
790
+ const statFailures = toCount(stats.statFailures)
791
+ const oversized = toCount(stats.oversized)
792
+ const failures = Array.isArray(stats.failures) ? stats.failures : []
793
+
794
+ // 覆盖类:先说「你看到的不是全部」。顺序固定(读失败 → 目录 → 属性 → 超大),
795
+ // 模型扫一眼就知道该先信哪条、该向用户交代什么。
796
+ const warnings = []
797
+ if (unreadable > 0) {
798
+ const names = failures
799
+ .filter((item) => item.stage === 'read' || item.stage === 'parse')
800
+ .slice(0, 3)
801
+ .map((item) => item.path)
802
+ const more = unreadable > names.length ? '…' : ''
803
+ warnings.push(`${unreadable} 页读取失败${names.length > 0 ? `(${names.join('、')}${more})` : ''}:共 ${discovered} 页中 ${pages} 页可用`)
804
+ }
805
+ if (walkFailures > 0) warnings.push(`${walkFailures} 个目录无法列出,其中的页面没有计入`)
806
+ if (statFailures > 0) warnings.push(`${statFailures} 个文件读不到属性,已跳过`)
807
+
808
+ // 超大页:只有「和这次调用真的相关」才升级状态。
809
+ // search —— 标题或 index 摘要沾到查询词的超大页数(oversizedRelevant);
810
+ // page —— 目标页本身超大;
811
+ // list —— 目录天然漏掉了它们;
812
+ // overview / lint —— 自己就会把这件事报出来,不必靠状态再喊一遍。
813
+ // 判据是相关性,不是「库里有几页太大」这个与本次查询无关的事实:后者会让每次调用都挂 partial,
814
+ // 这个信号很快就会变成模型学会忽略的背景噪音。
815
+ const wanted = mode === 'page' ? String(args.name ?? args.query ?? '').trim() : ''
816
+ const targetOversized = wanted !== '' && corpus.byName?.get?.(wanted)?.oversized === true
817
+ const relevantOversized = mode === 'search' ? toCount(result.oversizedRelevant) : 0
818
+ const oversizedHit = (mode === 'search' && relevantOversized > 0)
819
+ || (mode === 'page' && targetOversized)
820
+ || (mode === 'list' && oversized > 0)
821
+ const oversizedWarning = mode === 'page'
822
+ ? '目标页正文超过 512KB 未载入,这次只有标题与元数据'
823
+ : mode === 'list'
824
+ ? `${oversized} 页正文超过 512KB,没有进目录`
825
+ : `${relevantOversized} 个超大页正文没有参与检索,但${viaText(result.oversizedRelevantVia)} —— 可能还有相关内容没看到`
826
+
827
+ const coverageLost = unreadable > 0 || walkFailures > 0 || statFailures > 0
828
+
829
+ // 空结果按 mode 各取各的字段,不为「统一」虚构字段
830
+ const empty =
831
+ mode === 'search' ? (result.hits ?? []).length === 0
832
+ : mode === 'page' ? result.found === null || result.found === undefined
833
+ : mode === 'list' ? toCount(result.total) === 0
834
+ : false
835
+
836
+ if (pages === 0) {
837
+ // 这条必须排在最前:找到了文件却一页都读不出来,是权限/损坏,不是路径指错。
838
+ // 判成 unavailable 会把用户引去改路径,而真正该看的是文件本身。
839
+ if (unreadable > 0) {
840
+ warnings.push('0 页可用:库不是空的,是这次一页都没读出来')
841
+ return { status: 'partial', warnings }
842
+ }
843
+ const rootGone = failures.some((item) => item.stage === 'walk' && (item.code === 'ENOENT' || item.code === 'ENOTDIR'))
844
+ if (discovered === 0 && walkFailures > 0 && !rootGone) {
845
+ warnings.push('0 页可用:目录列不出来')
846
+ return { status: 'partial', warnings }
847
+ }
848
+ warnings.push(discovered === 0
849
+ ? '没有扫描到任何 .md 文件:路径可能指错了层'
850
+ : `扫描到 ${discovered} 个文件,但没有一个算作页面(只有 index/log,或被规则跳过)`)
851
+ return { status: 'unavailable', warnings }
852
+ }
853
+ if (coverageLost) return { status: 'partial', warnings }
854
+ if (mode === 'search' && result.degraded === true) {
855
+ // 降级与「超大页可能相关」可以同时成立:状态按约定取 degraded,但两条事实都要输出 ——
856
+ // 别让一个状态值把覆盖缺口吞掉。
857
+ if (oversizedHit) warnings.push(oversizedWarning)
858
+ warnings.push('只命中部分检索词,已降级为 OR:命中面变宽,精度下降')
859
+ return { status: 'degraded', warnings }
860
+ }
861
+ if (oversizedHit) {
862
+ warnings.push(oversizedWarning)
863
+ return { status: 'partial', warnings }
864
+ }
865
+ if (empty) return { status: 'no_match', warnings: [] }
866
+ return { status: 'ok', warnings: [] }
867
+ }
868
+
869
+ /** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */
870
+ function viaText(via) {
871
+ if (via === '标题') return '标题命中查询词'
872
+ if (via === '摘要') return 'index 摘要命中查询词'
873
+ return '标题或 index 摘要命中查询词'
874
+ }
875
+
876
+ /** 统一入口:工具只暴露一个函数,六个 mode 分派到这里。 */
877
+ export function run(corpus, args = {}) {
878
+ const mode = typeof args.mode === 'string' && args.mode.trim() !== '' ? args.mode.trim() : 'search'
879
+
880
+ // 校验先于语料:参数错不该产生一次完整扫描,也不该被归因成扫描失败
881
+ const invalid = validateArgs(mode, args)
882
+ if (invalid !== null) {
883
+ return {
884
+ mode: MODES.includes(mode) ? mode : 'error',
885
+ status: 'invalid_input',
886
+ warnings: [invalid],
887
+ // 第二步会把 render 改成按 status 分支;在那之前靠 error 挡住「库里没有命中」这句,
888
+ // 否则模型会把「参数写错了」读成「库里没这条」。
889
+ error: invalid,
890
+ ...(mode === 'search' ? { query: args.query ?? '', tokens: [], total: 0, hits: [] } : {}),
891
+ }
892
+ }
893
+
894
+ let result
895
+ switch (mode) {
896
+ case 'search':
897
+ result = search(corpus, args.query ?? '', args)
898
+ break
899
+ case 'page':
900
+ result = page(corpus, args.name ?? args.query ?? '', args)
901
+ break
902
+ case 'list':
903
+ result = list(corpus, args)
904
+ break
905
+ case 'overview':
906
+ result = overview(corpus, args)
907
+ break
908
+ case 'lint':
909
+ result = lint(corpus, args)
910
+ break
911
+ case 'draft':
912
+ result = draft(corpus, args)
913
+ break
914
+ }
915
+
916
+ const verdict = decideStatus(corpus, mode, args, result)
917
+ // status 永远有;warnings 只在非 ok 时出现 —— 正常路径零额外 token
918
+ return verdict.warnings.length > 0
919
+ ? { ...result, status: verdict.status, warnings: verdict.warnings }
920
+ : { ...result, status: verdict.status }
921
+ }