dsh-wiki-notes 1.5.0 → 1.6.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/CHANGELOG.md +142 -0
- package/README.md +33 -8
- package/lib/bridge.js +43 -3
- package/lib/calls.js +23 -5
- package/lib/client.js +62 -12
- package/lib/config.js +72 -10
- package/lib/corpus.js +99 -14
- package/lib/engine.js +401 -28
- package/lib/index.js +107 -49
- package/lib/jsonl-store.js +61 -7
- package/lib/text.js +20 -0
- package/package.json +4 -3
package/lib/engine.js
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
*/
|
|
9
9
|
|
|
10
10
|
import { asList } from './corpus.js'
|
|
11
|
+
import { clipChars } from './text.js'
|
|
11
12
|
|
|
12
13
|
const DEFAULT_SECTION_CHARS = 900
|
|
13
14
|
const DEFAULT_PAGE_CHARS = 6000
|
|
@@ -21,11 +22,75 @@ function intOption(options, key, fallback, lo, hi) {
|
|
|
21
22
|
return Math.max(lo, Math.min(value, hi))
|
|
22
23
|
}
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
// 中文疑问词。它们出现在查询里几乎从不出现在页面正文里,留着就会变成「必须同时命中」的
|
|
26
|
+
// 硬条件:`Agent Harness 是什么` 里那个「是什么」会把真正该命中的页筛掉。
|
|
27
|
+
// 只剥疑问词,不碰「的 / 了 / 和」—— 那些字在「目的」「和平」里是真词,剥了会切坏词。
|
|
28
|
+
const QUESTION_WORDS = ['是什么样的', '是什么', '什么样', '怎么样', '怎么办', '咋办', '咋整', '做什么', '怎么', '怎样', '如何', '为什么', '为何', '哪些', '哪个', '哪种', '是否', '有没有', '能不能', '要不要', '多少', '吗', '呢', '吧']
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* 剥掉查询两端的疑问词。
|
|
32
|
+
*
|
|
33
|
+
* 只剥**贴在两端**的,不从中间切:中文没有词边界,一从中间切就造伪词。
|
|
34
|
+
* 反例(真跑出来的):「甲方案的实施顺序应该怎么安排」按旧的「全局 split」切出来是
|
|
35
|
+
* 「甲方案的实施顺序应该」+「安排」——两个都不是词,AND 全落空,覆盖率兜底也没机会,
|
|
36
|
+
* 于是最该命中的那页总览反而进不了前五。
|
|
37
|
+
*
|
|
38
|
+
* 三种情形:
|
|
39
|
+
* part 整个就是一个疑问词 → 丢掉(它不含内容,留着只会当硬条件)
|
|
40
|
+
* 疑问词在头或在尾,剥完还剩 ≥2 字 → 剥
|
|
41
|
+
* 其余(含剥完不足 2 字) → 原样保留,宁可搜不到,也不把查询悄悄缩窄
|
|
42
|
+
*/
|
|
43
|
+
function stripQuestionWords(part) {
|
|
44
|
+
for (const word of QUESTION_WORDS) {
|
|
45
|
+
if (part === word) return []
|
|
46
|
+
if (part.endsWith(word)) {
|
|
47
|
+
const head = part.slice(0, part.length - word.length).trim()
|
|
48
|
+
if (head.length >= 2) return [head]
|
|
49
|
+
return [part]
|
|
50
|
+
}
|
|
51
|
+
if (part.startsWith(word)) {
|
|
52
|
+
const tail = part.slice(word.length).trim()
|
|
53
|
+
if (tail.length >= 2) return [tail]
|
|
54
|
+
return [part]
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return [part]
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* 输入卫生:去掉两端包着的标点,丢掉既没有文字也没有数字的片段。
|
|
62
|
+
*
|
|
63
|
+
* 两件真事逼出来的:`???` 经 NFKC 变成 `???` 会当成一个检索词(结果页显示「没有命中」,
|
|
64
|
+
* 但实际上查询本身就没内容,该报空查询);`"引号"` 带着引号去匹配,永远只能落在覆盖率兜底。
|
|
65
|
+
* 只去引号/括号/句读,不动 `+ # . _ -`:`C#`、`F#`、`node.js` 里的符号是词的一部分。
|
|
66
|
+
*/
|
|
67
|
+
const EDGE_PUNCT = /^["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+|["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+$/g
|
|
68
|
+
const HAS_WORD_CHAR = /[\p{L}\p{N}]/u
|
|
69
|
+
|
|
70
|
+
function cleanPart(part) {
|
|
71
|
+
return part.replace(EDGE_PUNCT, '').trim()
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。
|
|
76
|
+
*
|
|
77
|
+
* 两处归一化,都是被评测集逼出来的(queries.json 的「全角」「中英混写」两组):
|
|
78
|
+
* NFKC —— 全角「RAG」要能命中半角「RAG」。search.py 第一步就是这一步,之前这边漏了。
|
|
79
|
+
* 疑问词剥离 —— 见 QUESTION_WORDS,不让「是什么」当硬条件。
|
|
80
|
+
*/
|
|
25
81
|
export function tokenize(query) {
|
|
26
|
-
|
|
82
|
+
// 200 字上限放在这里,而不是只放在工具层:CLI、设置页 /search、Python 桥都走这条路,
|
|
83
|
+
// 上一层拦住的长度到这里不该又变回一个 300 字的「词元」——它会拖慢每个页面的比对,
|
|
84
|
+
// 还会被原样回显进 note(`"<整段查询>" 被当成一个词元`)。
|
|
85
|
+
const trimmed = clipChars(String(query ?? '').normalize('NFKC').trim(), MAX_QUERY_CHARS)
|
|
27
86
|
if (trimmed === '') return []
|
|
28
|
-
const
|
|
87
|
+
const rawParts = trimmed
|
|
88
|
+
.split(/[\s,,、。;;/|]+/)
|
|
89
|
+
.map((part) => cleanPart(part))
|
|
90
|
+
.filter((part) => part !== '' && HAS_WORD_CHAR.test(part))
|
|
91
|
+
// 整条查询就是一个疑问词(「多少」「怎么样」)时退回原样:宁可搜不到,也不把查询悄悄变成空
|
|
92
|
+
const stripped = rawParts.flatMap(stripQuestionWords)
|
|
93
|
+
const parts = stripped.length > 0 ? stripped : rawParts
|
|
29
94
|
// 去重但保留顺序
|
|
30
95
|
const seen = new Set()
|
|
31
96
|
const out = []
|
|
@@ -145,8 +210,15 @@ function explainTerms(page, indexLine, tokens) {
|
|
|
145
210
|
*/
|
|
146
211
|
const INDEX_ONLY_SCORE = 8
|
|
147
212
|
|
|
148
|
-
/**
|
|
149
|
-
|
|
213
|
+
/**
|
|
214
|
+
* 类型分层:同分时结构化笔记优先于原始资料摘要 —— 笔记是消化过的结论。
|
|
215
|
+
*
|
|
216
|
+
* 总览放在最高一档而不是默认档:它是全库唯一的入口页,一个跨模块的词(「复盘」「数据」
|
|
217
|
+
* 这类)在总览里出现的意义,和它在某个模块综合页里出现的意义不是一回事。2026-11-08 用
|
|
218
|
+
* tests/local/ab_export.py 重导基线后暴露:某一查询里总览与某个模块综合页同分 15,
|
|
219
|
+
* 按旧表(总览落到默认档 2)被挤到第 6 位,与 search.py 的前 5 不一致。
|
|
220
|
+
*/
|
|
221
|
+
const TYPE_TIER = { 综合: 3, 总览: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
|
|
150
222
|
|
|
151
223
|
function typeTier(page) {
|
|
152
224
|
return TYPE_TIER[String(page.fields['类型'] ?? '')] ?? 2
|
|
@@ -258,7 +330,7 @@ function pickSection(page, tokens) {
|
|
|
258
330
|
function clip(text, limit) {
|
|
259
331
|
const value = String(text ?? '')
|
|
260
332
|
if (limit <= 0 || value.length <= limit) return value
|
|
261
|
-
return `${value
|
|
333
|
+
return `${clipChars(value, limit)}…`
|
|
262
334
|
}
|
|
263
335
|
|
|
264
336
|
function buildIndexMap(corpus) {
|
|
@@ -293,6 +365,89 @@ function oversizedRelevance(corpus, tokens, indexMap) {
|
|
|
293
365
|
return { total, via }
|
|
294
366
|
}
|
|
295
367
|
|
|
368
|
+
// 字面覆盖率兜底的阈值,与 search.py 的 COVERAGE_MIN 取同一个数。
|
|
369
|
+
// 低于这条线不是「相关性弱」,是「根本不像在说同一件事」,放进结果里只会骗人。
|
|
370
|
+
const COVERAGE_MIN = 0.45
|
|
371
|
+
// 查询长度上限,与工具层 schema 的意思对齐(那边拦的是模型,这里拦的是 CLI / /search / 桥)。
|
|
372
|
+
const MAX_QUERY_CHARS = 200
|
|
373
|
+
const CJK_RE = /[\u3400-\u9fff]/
|
|
374
|
+
|
|
375
|
+
/**
|
|
376
|
+
* 把查询切成「字面原子」:中文按二字组、拉丁按整词。
|
|
377
|
+
*
|
|
378
|
+
* 为什么需要这一步:中文没有空格,一句「甲方案的实施顺序应该怎么安排」在 tokenize 眼里
|
|
379
|
+
* 就是**一个词元**,而库里不可能逐字出现这句话,于是 AND、OR 双双落空。用户看到的是
|
|
380
|
+
* 「库里没有」,可库里明明有一页在讲这件事。search.py 的降级层就是干这个的,
|
|
381
|
+
* 这里补上同一层,只在前面全落空时才启用。
|
|
382
|
+
*/
|
|
383
|
+
function coverageAtomsOf(text) {
|
|
384
|
+
const atoms = []
|
|
385
|
+
const seen = new Map()
|
|
386
|
+
const push = (atom, weight) => {
|
|
387
|
+
const previous = seen.get(atom) ?? 0
|
|
388
|
+
if (previous >= weight) return
|
|
389
|
+
if (previous === 0) atoms.push(atom)
|
|
390
|
+
seen.set(atom, weight)
|
|
391
|
+
}
|
|
392
|
+
for (const chunk of String(text).match(/[\u3400-\u9fff]+|[A-Za-z0-9][A-Za-z0-9._+#-]*/g) ?? []) {
|
|
393
|
+
if (CJK_RE.test(chunk)) {
|
|
394
|
+
if (chunk.length === 1) push(chunk, 1)
|
|
395
|
+
else for (let i = 0; i < chunk.length - 1; i += 1) push(chunk.slice(i, i + 2), 1)
|
|
396
|
+
} else {
|
|
397
|
+
// 一个拉丁词比一个二字组信息量大:权重 3,与 search.py 的整段权重对齐
|
|
398
|
+
push(chunk.toLowerCase(), 3)
|
|
399
|
+
}
|
|
400
|
+
}
|
|
401
|
+
return atoms.map((atom) => ({ atom, weight: seen.get(atom) ?? 1 }))
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
/**
|
|
405
|
+
* 覆盖率通道:不要求整句出现,只要求「查询里的字面片段在这页出现了多少」。
|
|
406
|
+
* 分数刻意做成覆盖率 × 100 + 结构加分,量级远低于正常命中(页名全等 120),
|
|
407
|
+
* 所以它永远排在真命中后面 —— 这一层只负责「别报空」。
|
|
408
|
+
*/
|
|
409
|
+
function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
|
|
410
|
+
const atoms = coverageAtomsOf(tokens.join(' '))
|
|
411
|
+
const totalWeight = atoms.reduce((sum, item) => sum + item.weight, 0)
|
|
412
|
+
if (atoms.length === 0 || totalWeight === 0) return []
|
|
413
|
+
const indexMap = buildIndexMap(corpus)
|
|
414
|
+
const out = []
|
|
415
|
+
for (const page of corpus.pages) {
|
|
416
|
+
if (page.oversized === true) continue
|
|
417
|
+
if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
|
|
418
|
+
if (tagFilter.length > 0) {
|
|
419
|
+
const pageTags = asList(page.fields['标签'])
|
|
420
|
+
if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
|
|
421
|
+
}
|
|
422
|
+
const body = page.body.toLowerCase()
|
|
423
|
+
const title = page.name.toLowerCase()
|
|
424
|
+
const aliasText = asList(page.fields['别名']).join(' ').toLowerCase()
|
|
425
|
+
const tagText = asList(page.fields['标签']).join(' ').toLowerCase()
|
|
426
|
+
let hitWeight = 0
|
|
427
|
+
const hitAtoms = []
|
|
428
|
+
for (const { atom, weight } of atoms) {
|
|
429
|
+
if (!body.includes(atom)) continue
|
|
430
|
+
hitWeight += weight
|
|
431
|
+
hitAtoms.push(atom)
|
|
432
|
+
}
|
|
433
|
+
const coverage = hitWeight / totalWeight
|
|
434
|
+
if (coverage < COVERAGE_MIN) continue
|
|
435
|
+
let bonus = 0
|
|
436
|
+
if (hitAtoms.some((atom) => title.includes(atom))) bonus += 20
|
|
437
|
+
if (hitAtoms.some((atom) => aliasText.includes(atom))) bonus += 10
|
|
438
|
+
if (hitAtoms.some((atom) => tagText.includes(atom))) bonus += 5
|
|
439
|
+
out.push({
|
|
440
|
+
page,
|
|
441
|
+
indexLine: indexMap.get(page.name) ?? null,
|
|
442
|
+
score: Math.round(coverage * 100) + bonus,
|
|
443
|
+
matched: hitAtoms.length,
|
|
444
|
+
allTerms: false,
|
|
445
|
+
atoms: hitAtoms,
|
|
446
|
+
})
|
|
447
|
+
}
|
|
448
|
+
return out
|
|
449
|
+
}
|
|
450
|
+
|
|
296
451
|
/**
|
|
297
452
|
* mode 2:search
|
|
298
453
|
* 返回 hits(按分数降序),每项带索引摘要、命中小节正文、citation、断链。
|
|
@@ -353,14 +508,32 @@ export function search(corpus, query, options = {}) {
|
|
|
353
508
|
list = scored
|
|
354
509
|
}
|
|
355
510
|
|
|
511
|
+
// 最后一道兜底:AND 和 OR 都一条没有,但查询本身是「一句话」时,用字面覆盖率再找一遍。
|
|
512
|
+
// 只在结果为 0 时启用 —— 有任何一条真命中就不碰,所以它不可能把好结果挤掉。
|
|
513
|
+
let coverageFallback = false
|
|
514
|
+
if (list.length === 0) {
|
|
515
|
+
const covered = coveragePass(corpus, tokens, { typeFilter, tagFilter })
|
|
516
|
+
if (covered.length > 0) {
|
|
517
|
+
coverageFallback = true
|
|
518
|
+
degraded = true
|
|
519
|
+
list = covered
|
|
520
|
+
}
|
|
521
|
+
}
|
|
522
|
+
|
|
356
523
|
list.sort(compareHits)
|
|
357
524
|
|
|
525
|
+
// 覆盖率通道下,整句作为一个词元在正文里必然找不到,选节会退化成「取第一段」。
|
|
526
|
+
// 改用命中的字面片段去选节:pickSection 本身没动,只是换了喂进去的词。
|
|
527
|
+
const sectionTokensOf = (item) => (coverageFallback ? item.atoms ?? tokens : tokens)
|
|
528
|
+
|
|
358
529
|
const hits = list.slice(0, limit).map((item) => {
|
|
359
|
-
const section = pickSection(item.page,
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
530
|
+
const section = pickSection(item.page, sectionTokensOf(item))
|
|
531
|
+
// 断链按整页算,不按命中小节算:选节会把页面截成一段,断链常落在文末的「相关」里,
|
|
532
|
+
// 只报小节内的会让模型把「这一页没有断链」当成结论 —— README 给它的语义是页级硬信号。
|
|
533
|
+
// 复用 corpus 已经解析好的 page.links,而不是在这里再扫一遍正文:
|
|
534
|
+
// 那边会跳过行内代码里的 `[[示例]]`(那是举例,不是链接),这边自己扫就会把示例当红链。
|
|
535
|
+
const broken = [...new Set(item.page.links ?? [])]
|
|
536
|
+
.filter((link) => !corpus.byName.has(link) && !corpus.byAlias.has(link.toLowerCase()))
|
|
364
537
|
return {
|
|
365
538
|
name: item.page.name,
|
|
366
539
|
kind: pageKind(item.page),
|
|
@@ -374,7 +547,14 @@ export function search(corpus, query, options = {}) {
|
|
|
374
547
|
allTerms: item.allTerms,
|
|
375
548
|
gist: extractGist(item.page.body),
|
|
376
549
|
summary: item.indexLine?.summary ?? '',
|
|
377
|
-
section: {
|
|
550
|
+
section: {
|
|
551
|
+
title: section.title,
|
|
552
|
+
text: clip(section.text, sectionChars),
|
|
553
|
+
// 截断与否要明说:clip 只在真截断时补「…」,但原文自己也可能以省略号结尾,
|
|
554
|
+
// 模型光看 text 分不出「这段完整」和「这段被砍了一半」——截断的表格后半截最容易被当完整引用。
|
|
555
|
+
chars: String(section.text ?? '').length,
|
|
556
|
+
truncated: String(section.text ?? '').length > sectionChars,
|
|
557
|
+
},
|
|
378
558
|
citation: `← [[${item.page.name}]]${section.title === '' ? '' : ` §${section.title}`} → ${item.page.file}`,
|
|
379
559
|
brokenLinks: broken,
|
|
380
560
|
file: item.page.file,
|
|
@@ -384,6 +564,23 @@ export function search(corpus, query, options = {}) {
|
|
|
384
564
|
|
|
385
565
|
const oversized = oversizedRelevance(corpus, tokens, indexMap)
|
|
386
566
|
|
|
567
|
+
// 单字查询命中过半页时,排序确实没有区分度(「的」「a」会命中几乎整库)。
|
|
568
|
+
// 不改结果——改了就是动排序,那是 §13.1 的地界;但必须让模型知道这批结果别当真。
|
|
569
|
+
const trivialQuery = tokens.length === 1 && tokens[0].length <= 1 && considered > 20 && scored.length >= considered * 0.5
|
|
570
|
+
|
|
571
|
+
// 过滤器把候选清空时,「这次没命中」和「库里根本没这种页」是两件事。
|
|
572
|
+
// 不说清楚,模型会把「库里没有资料类型的页」读成「库里没有这个主题」。
|
|
573
|
+
// 还有第三种:过了滤、也有页参与,但整句一页都没命中 —— 那时同样得说话,
|
|
574
|
+
// 否则「词不对」和「命中页被 type 过滤掉了」在模型看来长得一模一样(真库实测过)。
|
|
575
|
+
const filterApplied = typeFilter !== null || tagFilter.length > 0
|
|
576
|
+
const filterNote = !filterApplied
|
|
577
|
+
? ''
|
|
578
|
+
: considered === 0
|
|
579
|
+
? filterEmptyNote(corpus, typeFilter, tagFilter)
|
|
580
|
+
: (scored.length === 0 && list.length === 0
|
|
581
|
+
? `过滤后仍有 ${considered} 页参与检索,但整句没有命中任何一页(字面覆盖率兜底 ${Math.round(COVERAGE_MIN * 100)}% 也没过)。这可能是词不对,也可能命中的页被 type/tags 过滤掉了——去掉过滤再搜一次就能分开。`
|
|
582
|
+
: '')
|
|
583
|
+
|
|
387
584
|
return {
|
|
388
585
|
mode: 'search',
|
|
389
586
|
query,
|
|
@@ -392,14 +589,20 @@ export function search(corpus, query, options = {}) {
|
|
|
392
589
|
// 这三件事决定「结果为空」该怪词、怪库,还是怪匹配模式。
|
|
393
590
|
// missedTerms / matchMode 常驻(模型看到「这个词没用上」才可能换词重查,成本两个短字段);
|
|
394
591
|
// 每个词在多少页上得分的明细只有 explain 时才给,那是面板的事。
|
|
395
|
-
|
|
592
|
+
// 覆盖率兜底下调时不能报「这些词一页都没命中」——命中正是靠这些词的字面片段捞到的,
|
|
593
|
+
// 两句话放在一起自相矛盾,note 里已经交代清楚。
|
|
594
|
+
missedTerms: coverageFallback ? [] : tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
|
|
396
595
|
matchMode: degraded ? 'or' : 'and',
|
|
596
|
+
// 覆盖率兜底是 or 的下一层(仍标 matchMode/or 以保持面板与既有断言的两值语义),
|
|
597
|
+
// 但必须单独标出来:这时候「命中」只是字面沾边,精度比 OR 更低,模型叙述时要收着写。
|
|
598
|
+
coverageFallback,
|
|
599
|
+
trivialQuery,
|
|
397
600
|
...(explain ? { termPages: tokens.map((token) => ({ term: token, pages: termPages.get(token) ?? 0 })) } : {}),
|
|
398
601
|
total: list.length,
|
|
399
602
|
degraded,
|
|
400
603
|
// 调用级统计:分母各是各的,别合成一个数字
|
|
401
604
|
considered,
|
|
402
|
-
matched: scored.length,
|
|
605
|
+
matched: coverageFallback ? list.length : scored.length,
|
|
403
606
|
allTerms: scored.filter((item) => item.allTerms).length,
|
|
404
607
|
returned: hits.length,
|
|
405
608
|
// 超大页里「标题或 index 摘要」沾到查询词的数量:决定这次要不要提醒覆盖缺口,
|
|
@@ -407,8 +610,40 @@ export function search(corpus, query, options = {}) {
|
|
|
407
610
|
oversizedRelevant: oversized.total,
|
|
408
611
|
oversizedRelevantVia: oversized.via,
|
|
409
612
|
hits,
|
|
410
|
-
note:
|
|
613
|
+
note: filterNote
|
|
614
|
+
|| (coverageFallback
|
|
615
|
+
? `整句没有命中任何页(中文不分词,"${query}" 被当成一个词元),已降级为字面覆盖率匹配(≥${Math.round(COVERAGE_MIN * 100)}%)。结果只作线索:命中是字面沾边,不是这页回答了你。`
|
|
616
|
+
: degraded
|
|
617
|
+
? '没有同时命中全部检索词,已降级为 OR(命中任一):命中面变宽、精度下降'
|
|
618
|
+
: trivialQuery
|
|
619
|
+
? `查询只有一个字("${tokens[0]}"),它在这 ${considered} 页里出现了 ${scored.length} 页——这个字到处都有,排序没有区分度。换个更具体的词再搜。`
|
|
620
|
+
: ''),
|
|
621
|
+
}
|
|
622
|
+
}
|
|
623
|
+
|
|
624
|
+
/** 过滤器把候选清空时,说清楚是「库里没这种页」而不是「库里没这个主题」。 */
|
|
625
|
+
function filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter = null) {
|
|
626
|
+
const dist = new Map()
|
|
627
|
+
const statuses = new Map()
|
|
628
|
+
for (const page of corpus.pages) {
|
|
629
|
+
if (page.oversized === true) continue
|
|
630
|
+
const type = String(page.fields['类型'] ?? '') || '(无类型)'
|
|
631
|
+
dist.set(type, (dist.get(type) ?? 0) + 1)
|
|
632
|
+
const status = String(page.fields['状态'] ?? '') || '(无状态)'
|
|
633
|
+
statuses.set(status, (statuses.get(status) ?? 0) + 1)
|
|
411
634
|
}
|
|
635
|
+
const tally = (map) => [...map.entries()]
|
|
636
|
+
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0], 'zh'))
|
|
637
|
+
.map(([key, count]) => `${key} ${count}`)
|
|
638
|
+
.join(' / ')
|
|
639
|
+
const asked = [
|
|
640
|
+
typeFilter === null ? '' : `type=${typeFilter}`,
|
|
641
|
+
statusFilter === null ? '' : `status=${statusFilter}`,
|
|
642
|
+
tagFilter.length === 0 ? '' : `tags=${tagFilter.join('/')}`,
|
|
643
|
+
].filter((part) => part !== '').join(' ')
|
|
644
|
+
const typeShown = tally(dist)
|
|
645
|
+
const statusShown = tally(statuses)
|
|
646
|
+
return `库里没有符合 ${asked} 的页(现有类型:${typeShown === '' ? '无' : typeShown}${statusFilter === null ? '' : `;现有状态:${statusShown === '' ? '无' : statusShown}`})。这是过滤条件的问题,不是主题不存在——去掉过滤再搜。`
|
|
412
647
|
}
|
|
413
648
|
|
|
414
649
|
/** mode 2:page —— 按页名/别名/模糊取整页。取不到就给最像的 5 个候选。 */
|
|
@@ -419,12 +654,24 @@ export function page(corpus, name, options = {}) {
|
|
|
419
654
|
|
|
420
655
|
const indexMap = buildIndexMap(corpus)
|
|
421
656
|
const exact = corpus.byName.get(wanted) ?? corpus.byName.get(wanted.replace(/\.md$/i, ''))
|
|
422
|
-
if (exact !== undefined)
|
|
657
|
+
if (exact !== undefined) {
|
|
658
|
+
const found = renderPage(corpus, exact, indexMap, limit)
|
|
659
|
+
const note = pageBodyNote(found, exact.oversized === true)
|
|
660
|
+
return { mode: 'page', found, candidates: [], ...(note === '' ? {} : { note }) }
|
|
661
|
+
}
|
|
423
662
|
|
|
424
663
|
const aliasHits = corpus.byAlias.get(wanted.toLowerCase()) ?? []
|
|
425
664
|
if (aliasHits.length > 0) {
|
|
426
665
|
const first = aliasHits[0]
|
|
427
|
-
return {
|
|
666
|
+
return {
|
|
667
|
+
mode: 'page',
|
|
668
|
+
found: renderPage(corpus, first, indexMap, limit),
|
|
669
|
+
candidates: [],
|
|
670
|
+
// 别名是检索入口,被两页共用时「按名字取页」就是抛硬币 —— 必须点名,别让引用悄悄指错。
|
|
671
|
+
...(aliasHits.length > 1
|
|
672
|
+
? { note: aliasCollisionNote(aliasHits, first, wanted), aliasConflict: true }
|
|
673
|
+
: {}),
|
|
674
|
+
}
|
|
428
675
|
}
|
|
429
676
|
|
|
430
677
|
// 模糊:包含关系 → 相似度
|
|
@@ -457,6 +704,21 @@ export function page(corpus, name, options = {}) {
|
|
|
457
704
|
}
|
|
458
705
|
}
|
|
459
706
|
|
|
707
|
+
/** 命中的页没有正文时会话里最容易出的错:模型引用一个空页当依据。 */
|
|
708
|
+
function pageBodyNote(found, oversized = false) {
|
|
709
|
+
// 超大页的 body 也是空字符串,但原因不是「文件是空的」——那句说明由 decideStatus 给,
|
|
710
|
+
// 这里再说一遍就成了两条互相矛盾的提示(一条说文件空,一条说超过 512KB)。
|
|
711
|
+
if (oversized === true) return ''
|
|
712
|
+
const body = typeof found?.body === 'string' ? found.body.trim() : ''
|
|
713
|
+
return body === '' ? '这页没有正文(只有 frontmatter 或文件是空的):别把它当依据,回到原始资料或换一页' : ''
|
|
714
|
+
}
|
|
715
|
+
|
|
716
|
+
/** 别名被多页共用:按别名取页等于抛硬币,点名让人改。 */
|
|
717
|
+
function aliasCollisionNote(aliasHits, chosen, wanted) {
|
|
718
|
+
const names = aliasHits.map((item) => `${item.name}(${item.file})`).join('、')
|
|
719
|
+
return `别名「${wanted}」被 ${aliasHits.length} 页共用:${names};这次给的是 ${chosen.name}。引用前先确认是哪一篇,或把别名改成唯一。`
|
|
720
|
+
}
|
|
721
|
+
|
|
460
722
|
function renderPage(corpus, page, indexMap, limit) {
|
|
461
723
|
const body = clip(page.body, limit)
|
|
462
724
|
return {
|
|
@@ -507,6 +769,13 @@ export function list(corpus, options = {}) {
|
|
|
507
769
|
const limit = intOption(options, 'limit', 40, 1, 200)
|
|
508
770
|
const shown = rows.slice(0, limit)
|
|
509
771
|
|
|
772
|
+
// 空目录同样要区分「库里没这种页」与「库里没这个东西」:list 的调用方拿到的是一张空表,
|
|
773
|
+
// 不给一句话它只能猜。与 search 的 filterEmptyNote() 同一套说法,维度多一个 status。
|
|
774
|
+
const filtered = typeFilter !== null || statusFilter !== null || tagFilter.length > 0
|
|
775
|
+
const note = rows.length === 0 && filtered
|
|
776
|
+
? filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter)
|
|
777
|
+
: ''
|
|
778
|
+
|
|
510
779
|
return {
|
|
511
780
|
mode: 'list',
|
|
512
781
|
total: rows.length,
|
|
@@ -515,6 +784,7 @@ export function list(corpus, options = {}) {
|
|
|
515
784
|
byType,
|
|
516
785
|
scale: corpus.scaleLine,
|
|
517
786
|
rows: shown,
|
|
787
|
+
...(note === '' ? {} : { note }),
|
|
518
788
|
}
|
|
519
789
|
}
|
|
520
790
|
|
|
@@ -550,6 +820,9 @@ export function overview(corpus, options = {}) {
|
|
|
550
820
|
oversized: corpus.stats.oversized ?? 0,
|
|
551
821
|
scannedMs: corpus.stats.scannedMs,
|
|
552
822
|
duplicateNames: corpus.stats.duplicateNames ?? [],
|
|
823
|
+
// 没跟的 junction / symlink:不报的话,「链接里的页」会被读成「库里的页」本来就没有
|
|
824
|
+
linksSkipped: corpus.stats.linksSkipped ?? 0,
|
|
825
|
+
linkSkips: corpus.stats.linkSkips ?? [],
|
|
553
826
|
},
|
|
554
827
|
consistency: {
|
|
555
828
|
indexOnly: [...new Set(indexOnly)].slice(0, 10),
|
|
@@ -565,7 +838,20 @@ export function overview(corpus, options = {}) {
|
|
|
565
838
|
summary: indexMap.get(overviewPage.name)?.summary ?? '',
|
|
566
839
|
},
|
|
567
840
|
recentLog,
|
|
841
|
+
// 「最近日志」为空有两种原因:根本没有 log.md,或者 log.md 在、但一条也对不上
|
|
842
|
+
// 「## [日期] 类型 | 标题」。后者必须说出来,否则报表被读成「最近没有改动」。
|
|
843
|
+
logPresent: corpus.stats.logPresent === true,
|
|
844
|
+
logEntries: toCount(corpus.stats.logEntries),
|
|
568
845
|
broken: corpus.brokenLinks.slice(0, 10),
|
|
846
|
+
// 总览页是 overview 的正体;缺了它,模式还能跑(规模、index 一致性、日志都在),
|
|
847
|
+
// 但只交出这些而不说一声,等于把「这库没有总览」翻成「这库总览是空的」。
|
|
848
|
+
...(overviewPage === undefined
|
|
849
|
+
? {
|
|
850
|
+
note: '库里没有「总览-overview」页:下面只有规模、index 一致性与最近日志,没有总览正文。'
|
|
851
|
+
+ '按本库的结构约定该有一页总览(它决定「现在在回答什么、已有什么、分歧在哪、缺什么」);'
|
|
852
|
+
+ '换别人的库、没有总览页是正常的,规模与一致性照样能看。',
|
|
853
|
+
}
|
|
854
|
+
: {}),
|
|
569
855
|
}
|
|
570
856
|
}
|
|
571
857
|
|
|
@@ -658,6 +944,9 @@ export function draft(corpus, options = {}) {
|
|
|
658
944
|
|
|
659
945
|
const typeDirs = inferTypeDirs(corpus)
|
|
660
946
|
const type = String(options.type ?? '').trim() || '概念'
|
|
947
|
+
// 类型没有对应目录时,兜底放「概念」会让 frontmatter 的「类型」和目录自相矛盾 ——
|
|
948
|
+
// 而按库的改动—同步契约,这种页在提交时会被拦下。骨架阶段就该说,而不是等 lint。
|
|
949
|
+
const knownType = typeDirs.has(type) || Object.prototype.hasOwnProperty.call(DEFAULT_TYPE_DIRS, type)
|
|
661
950
|
const dir = typeDirs.get(type) ?? DEFAULT_TYPE_DIRS[type] ?? DEFAULT_TYPE_DIRS['概念']
|
|
662
951
|
// 日期只算一次,四处复用(frontmatter 创建/更新、indexLine、logLine)。
|
|
663
952
|
// 分别取四次的话,迟早出现「创建 03 号、log 02 号」这种自相矛盾的骨架。
|
|
@@ -667,13 +956,21 @@ export function draft(corpus, options = {}) {
|
|
|
667
956
|
|
|
668
957
|
const tags = asList(options.tags)
|
|
669
958
|
const aliases = asList(options.alias ?? options.aliases)
|
|
670
|
-
|
|
959
|
+
// 「来源数量」是要写进 frontmatter 的计数:负数、小数都不该原样落盘(2.7 份资料说不通)
|
|
960
|
+
const sourcesInput = Number(options.sources)
|
|
961
|
+
const sources = Number.isFinite(sourcesInput) ? Math.max(0, Math.trunc(sourcesInput)) : 0
|
|
671
962
|
const summary = String(options.summary ?? '').trim()
|
|
672
|
-
const file = `${dir}/${title}.md`
|
|
673
963
|
|
|
674
964
|
// 同名页已经存在时,回写会覆盖旧内容 —— 必须先在结果里警告,而不是让人写完才发现
|
|
675
965
|
const existing = corpus.byName.get(title) ?? corpus.byAlias.get(title) ?? null
|
|
676
966
|
|
|
967
|
+
// 文件名安全:AGENTS.md 的命名规则禁 `\ / : * ? " < > |`,但 draft 是「照着填就行」的骨架。
|
|
968
|
+
// 带冒号的标题在 Windows 上建不出来;带斜杠的更糟 —— `../../x` 会把路径带出库外,
|
|
969
|
+
// 而骨架里那行路径是给人照着建的。所以路径用替代名生成,原标题原样留在正文标题里。
|
|
970
|
+
const badName = /[\\/:*?"<>|]/.test(title)
|
|
971
|
+
const safeTitle = title.replace(/[\\/:*?"<>|]/g, '-').replace(/-{2,}/g, '-').replace(/^-+|-+$/g, '') || '未命名'
|
|
972
|
+
const file = `${dir}/${badName ? safeTitle : title}.md`
|
|
973
|
+
|
|
677
974
|
const frontmatter = [
|
|
678
975
|
'---',
|
|
679
976
|
`类型: ${type}`,
|
|
@@ -713,6 +1010,19 @@ export function draft(corpus, options = {}) {
|
|
|
713
1010
|
logType,
|
|
714
1011
|
indexLine: `- [[${title}]] — ${summary === '' ? '(一句话摘要)' : summary}(${sources} 份资料,更新于 ${date})`,
|
|
715
1012
|
logLine: `## [${date}] ${logType} | ${title}`,
|
|
1013
|
+
...(badName
|
|
1014
|
+
? {
|
|
1015
|
+
nameWarning: `标题里的 \\ / : * ? " < > | 是文件名禁用字符(斜杠还会把路径带出知识层)。`
|
|
1016
|
+
+ `回写骨架里的路径已按「${safeTitle}」生成,标题照旧写在正文第一行。`,
|
|
1017
|
+
safeTitle,
|
|
1018
|
+
}
|
|
1019
|
+
: {}),
|
|
1020
|
+
...(knownType
|
|
1021
|
+
? {}
|
|
1022
|
+
: {
|
|
1023
|
+
typeWarning: `类型「${type}」在本库里没有对应目录(现有类型:${[...new Set([...typeDirs.keys(), ...Object.keys(DEFAULT_TYPE_DIRS)])].join('、')}),`
|
|
1024
|
+
+ `骨架暂放在「${dir}/」。要么换成已有类型,要么先建目录 —— 按改动—同步契约,新目录还要同步 lint 的目录表与 SKILL.md 白名单。`,
|
|
1025
|
+
}),
|
|
716
1026
|
}
|
|
717
1027
|
}
|
|
718
1028
|
|
|
@@ -784,11 +1094,17 @@ export function lint(corpus, options = {}) {
|
|
|
784
1094
|
.filter((row) => row.pages.length > 1)
|
|
785
1095
|
|
|
786
1096
|
const stale = []
|
|
1097
|
+
// 「更新」写成 `2026/11/01`、`2026-11`、`2026 年 11 月` 时,久未更新判定只能跳过这一页 ——
|
|
1098
|
+
// 跳过的结果是「0 页久未更新」,而真相是「没算」。两者不能都显示成 0,所以单独收起来。
|
|
1099
|
+
const staleUnknown = []
|
|
787
1100
|
for (const page of readable) {
|
|
788
1101
|
const raw = page.fields['更新']
|
|
789
|
-
if (typeof raw !== 'string' || raw.
|
|
790
|
-
const time = Date.parse(`${raw.slice(0, 10)}T00:00:00Z`)
|
|
791
|
-
if (!Number.isFinite(time))
|
|
1102
|
+
if (typeof raw !== 'string' || raw.trim() === '') continue // 缺字段归 frontmatter 合规那一项
|
|
1103
|
+
const time = raw.length < 10 ? Number.NaN : Date.parse(`${raw.slice(0, 10)}T00:00:00Z`)
|
|
1104
|
+
if (!Number.isFinite(time)) {
|
|
1105
|
+
staleUnknown.push({ name: page.name, updated: raw })
|
|
1106
|
+
continue
|
|
1107
|
+
}
|
|
792
1108
|
const days = Math.floor((now - time) / 86400000)
|
|
793
1109
|
if (days > staleDays) stale.push({ name: page.name, updated: raw.slice(0, 10), days })
|
|
794
1110
|
}
|
|
@@ -821,6 +1137,7 @@ export function lint(corpus, options = {}) {
|
|
|
821
1137
|
missingFields: missingFields.length,
|
|
822
1138
|
aliasConflicts: aliasConflicts.length,
|
|
823
1139
|
stale: stale.length,
|
|
1140
|
+
staleUnknown: staleUnknown.length,
|
|
824
1141
|
noLinks: noLinks.length,
|
|
825
1142
|
drafts: drafts.length,
|
|
826
1143
|
indexOnly: indexOnly.length,
|
|
@@ -832,6 +1149,7 @@ export function lint(corpus, options = {}) {
|
|
|
832
1149
|
missingFields: missingFields.slice(0, limit),
|
|
833
1150
|
aliasConflicts: aliasConflicts.slice(0, limit),
|
|
834
1151
|
stale: stale.slice(0, limit),
|
|
1152
|
+
staleUnknown: staleUnknown.slice(0, limit),
|
|
835
1153
|
noLinks: noLinks.slice(0, limit),
|
|
836
1154
|
drafts: drafts.slice(0, limit),
|
|
837
1155
|
oversized: oversized.slice(0, limit),
|
|
@@ -936,8 +1254,14 @@ export const MODES = ['search', 'page', 'list', 'overview', 'lint', 'draft', 'he
|
|
|
936
1254
|
*/
|
|
937
1255
|
export function validateArgs(mode, args = {}) {
|
|
938
1256
|
if (!MODES.includes(mode)) return `未知 mode: ${mode}(可用 ${MODES.join(' / ')})`
|
|
939
|
-
if (mode === 'search'
|
|
940
|
-
|
|
1257
|
+
if (mode === 'search') {
|
|
1258
|
+
const rawQuery = String(args.query ?? '').trim()
|
|
1259
|
+
if (rawQuery === '') return 'query 为空:请传 1–4 个关键词'
|
|
1260
|
+
// 传了东西但全是标点/空白(???!!!、()、……)时别回「query 为空」——
|
|
1261
|
+
// 那会让人以为自己漏了参数,其实参数在,只是切不出可检索的字。
|
|
1262
|
+
if (tokenize(rawQuery).length === 0) {
|
|
1263
|
+
return `query 切不出可检索的字:${clipChars(rawQuery, 20)} 全是标点或空白,换个具体的词(1–4 个关键词)`
|
|
1264
|
+
}
|
|
941
1265
|
}
|
|
942
1266
|
if (mode === 'page' && String(args.name ?? args.query ?? '').trim() === '') {
|
|
943
1267
|
return 'name 为空:请传要查的页名'
|
|
@@ -1041,23 +1365,72 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
|
|
|
1041
1365
|
warnings.push(dupWarning)
|
|
1042
1366
|
return { status: 'partial', warnings }
|
|
1043
1367
|
}
|
|
1368
|
+
// 别名被多页共用与同名页是同一类风险(引错版本),只是入口不同:一个按页名,一个按别名。
|
|
1369
|
+
if (mode === 'page' && result.aliasConflict === true) {
|
|
1370
|
+
warnings.push(engineNote(result) || '这个别名被多页共用,这次给的不一定是你要的那篇')
|
|
1371
|
+
return { status: 'partial', warnings }
|
|
1372
|
+
}
|
|
1044
1373
|
if (mode === 'search' && result.degraded === true) {
|
|
1045
1374
|
// 降级与「超大页可能相关」可以同时成立:状态按约定取 degraded,但两条事实都要输出 ——
|
|
1046
1375
|
// 别让一个状态值把覆盖缺口吞掉。
|
|
1047
1376
|
if (oversizedHit) warnings.push(oversizedWarning)
|
|
1048
|
-
|
|
1377
|
+
// 引擎自己知道这次是「命中任一词」还是「整句只沾字面」(覆盖率兜底),
|
|
1378
|
+
// 让它的说法优先:模型要做的动作不一样 —— 前者该收窄词,后者该换更短的词或直接查页面。
|
|
1379
|
+
// 固定文案只当兜底(老调用方不带 note 时)。
|
|
1380
|
+
warnings.push(engineNote(result)
|
|
1381
|
+
|| '只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
|
|
1049
1382
|
return { status: 'degraded', warnings }
|
|
1050
1383
|
}
|
|
1051
1384
|
if (oversizedHit) {
|
|
1385
|
+
// 目录/检索为空而库里恰好有超大页时,两件事都得说:先说「为什么是空的」(可能是过滤条件写错),
|
|
1386
|
+
// 再说「还漏了超大页」。只报后者的话,模型会以为过滤是对的、只是内容太大。
|
|
1387
|
+
const why = engineNote(result)
|
|
1388
|
+
if (why !== '') warnings.push(why)
|
|
1052
1389
|
warnings.push(oversizedWarning)
|
|
1053
1390
|
return { status: 'partial', warnings }
|
|
1054
1391
|
}
|
|
1055
|
-
|
|
1392
|
+
// 零命中也要带上「为什么零命中」:过滤器清空与主题不存在是两件事,
|
|
1393
|
+
// 引擎写在 note 里的那句话如果在这里丢掉,模型只能自己猜。
|
|
1394
|
+
if (empty) {
|
|
1395
|
+
const why = engineNote(result)
|
|
1396
|
+
return { status: 'no_match', warnings: why === '' ? [] : [why] }
|
|
1397
|
+
}
|
|
1398
|
+
// overview 的两个「看起来是空」可以同时成立:缺总览页 + log 格式不对。
|
|
1399
|
+
// 以前两条各写各的 `if … return`,第二条永远被第一条吞掉 —— 状态同样是 partial,
|
|
1400
|
+
// 却只给一句话,模型会以为只有一件事要交代。改成累积,几条事实都输出。
|
|
1401
|
+
if (mode === 'overview') {
|
|
1402
|
+
// 总览缺页:模式还能给出规模与一致性,但那是「没有总览」而不是「总览是空的」。
|
|
1403
|
+
if (result.overview === null) {
|
|
1404
|
+
warnings.push(engineNote(result) || '库里没有总览页,这次只给了规模与一致性信息')
|
|
1405
|
+
}
|
|
1406
|
+
// log.md 在、但一条记录也解析不出来:格式和「## [日期] 类型 | 标题」对不上。
|
|
1407
|
+
// 不报的话「最近日志 0 条」会被读成「库里最近没改动」—— 这是最容易被当真的那种空。
|
|
1408
|
+
if (result.logPresent === true && toCount(result.logEntries) === 0) {
|
|
1409
|
+
warnings.push('log.md 存在,但没有一条符合「## [日期] 类型 | 标题」的记录:'
|
|
1410
|
+
+ '所以「最近日志」是空的 —— 这是格式没对上,不代表库里最近没有改动')
|
|
1411
|
+
}
|
|
1412
|
+
if (warnings.length > 0) return { status: 'partial', warnings }
|
|
1413
|
+
}
|
|
1414
|
+
// lint 的「久未更新」只算得出能解析日期的页。日期写坏(`2026/11/01`、`2026-11`)的页会被跳过,
|
|
1415
|
+
// 不能让「0 页久未更新」冒充「全库都新」—— 这是两件不同的事。
|
|
1416
|
+
if (mode === 'lint') {
|
|
1417
|
+
const unknown = Array.isArray(result.staleUnknown) ? result.staleUnknown : []
|
|
1418
|
+
if (unknown.length > 0) {
|
|
1419
|
+
const sample = unknown[0]
|
|
1420
|
+
warnings.push(`${unknown.length} 页的「更新」不是 YYYY-MM-DD(如 [[${sample.name}]] 写的是「${sample.updated}」),`
|
|
1421
|
+
+ '久未更新检查跳过了这些页:别把「0 页久未更新」当成全库都新')
|
|
1422
|
+
return { status: 'partial', warnings }
|
|
1423
|
+
}
|
|
1424
|
+
}
|
|
1056
1425
|
return { status: 'ok', warnings: [] }
|
|
1057
1426
|
}
|
|
1058
1427
|
|
|
1059
|
-
/**
|
|
1060
|
-
function
|
|
1428
|
+
/** 引擎写好的那句话(降级原因 / 单字无区分度),没有就返回空串。 */
|
|
1429
|
+
function engineNote(result) {
|
|
1430
|
+
return typeof result?.note === 'string' ? result.note.trim() : ''
|
|
1431
|
+
}
|
|
1432
|
+
|
|
1433
|
+
/** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */function viaText(via) {
|
|
1061
1434
|
if (via === '标题') return '标题命中查询词'
|
|
1062
1435
|
if (via === '摘要') return 'index 摘要命中查询词'
|
|
1063
1436
|
return '标题或 index 摘要命中查询词'
|