dsh-wiki-notes 1.4.3 → 1.6.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/lib/engine.js CHANGED
@@ -21,11 +21,75 @@ function intOption(options, key, fallback, lo, hi) {
21
21
  return Math.max(lo, Math.min(value, hi))
22
22
  }
23
23
 
24
- /** 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。 */
24
+ // 中文疑问词。它们出现在查询里几乎从不出现在页面正文里,留着就会变成「必须同时命中」的
25
+ // 硬条件:`Agent Harness 是什么` 里那个「是什么」会把真正该命中的页筛掉。
26
+ // 只剥疑问词,不碰「的 / 了 / 和」—— 那些字在「目的」「和平」里是真词,剥了会切坏词。
27
+ const QUESTION_WORDS = ['是什么样的', '是什么', '什么样', '怎么样', '怎么办', '咋办', '咋整', '做什么', '怎么', '怎样', '如何', '为什么', '为何', '哪些', '哪个', '哪种', '是否', '有没有', '能不能', '要不要', '多少', '吗', '呢', '吧']
28
+
29
+ /**
30
+ * 剥掉查询两端的疑问词。
31
+ *
32
+ * 只剥**贴在两端**的,不从中间切:中文没有词边界,一从中间切就造伪词。
33
+ * 反例(真跑出来的):「甲方案的实施顺序应该怎么安排」按旧的「全局 split」切出来是
34
+ * 「甲方案的实施顺序应该」+「安排」——两个都不是词,AND 全落空,覆盖率兜底也没机会,
35
+ * 于是最该命中的那页总览反而进不了前五。
36
+ *
37
+ * 三种情形:
38
+ * part 整个就是一个疑问词 → 丢掉(它不含内容,留着只会当硬条件)
39
+ * 疑问词在头或在尾,剥完还剩 ≥2 字 → 剥
40
+ * 其余(含剥完不足 2 字) → 原样保留,宁可搜不到,也不把查询悄悄缩窄
41
+ */
42
+ function stripQuestionWords(part) {
43
+ for (const word of QUESTION_WORDS) {
44
+ if (part === word) return []
45
+ if (part.endsWith(word)) {
46
+ const head = part.slice(0, part.length - word.length).trim()
47
+ if (head.length >= 2) return [head]
48
+ return [part]
49
+ }
50
+ if (part.startsWith(word)) {
51
+ const tail = part.slice(word.length).trim()
52
+ if (tail.length >= 2) return [tail]
53
+ return [part]
54
+ }
55
+ }
56
+ return [part]
57
+ }
58
+
59
+ /**
60
+ * 输入卫生:去掉两端包着的标点,丢掉既没有文字也没有数字的片段。
61
+ *
62
+ * 两件真事逼出来的:`???` 经 NFKC 变成 `???` 会当成一个检索词(结果页显示「没有命中」,
63
+ * 但实际上查询本身就没内容,该报空查询);`"引号"` 带着引号去匹配,永远只能落在覆盖率兜底。
64
+ * 只去引号/括号/句读,不动 `+ # . _ -`:`C#`、`F#`、`node.js` 里的符号是词的一部分。
65
+ */
66
+ const EDGE_PUNCT = /^["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+|["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+$/g
67
+ const HAS_WORD_CHAR = /[\p{L}\p{N}]/u
68
+
69
+ function cleanPart(part) {
70
+ return part.replace(EDGE_PUNCT, '').trim()
71
+ }
72
+
73
+ /**
74
+ * 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。
75
+ *
76
+ * 两处归一化,都是被评测集逼出来的(queries.json 的「全角」「中英混写」两组):
77
+ * NFKC —— 全角「RAG」要能命中半角「RAG」。search.py 第一步就是这一步,之前这边漏了。
78
+ * 疑问词剥离 —— 见 QUESTION_WORDS,不让「是什么」当硬条件。
79
+ */
25
80
  export function tokenize(query) {
26
- const trimmed = String(query ?? '').trim()
81
+ // 200 字上限放在这里,而不是只放在工具层:CLI、设置页 /search、Python 桥都走这条路,
82
+ // 上一层拦住的长度到这里不该又变回一个 300 字的「词元」——它会拖慢每个页面的比对,
83
+ // 还会被原样回显进 note(`"<整段查询>" 被当成一个词元`)。
84
+ const trimmed = String(query ?? '').normalize('NFKC').trim().slice(0, MAX_QUERY_CHARS)
27
85
  if (trimmed === '') return []
28
- const parts = trimmed.split(/[\s,,、。;;/|]+/).map((part) => part.trim()).filter((part) => part !== '')
86
+ const rawParts = trimmed
87
+ .split(/[\s,,、。;;/|]+/)
88
+ .map((part) => cleanPart(part))
89
+ .filter((part) => part !== '' && HAS_WORD_CHAR.test(part))
90
+ // 整条查询就是一个疑问词(「多少」「怎么样」)时退回原样:宁可搜不到,也不把查询悄悄变成空
91
+ const stripped = rawParts.flatMap(stripQuestionWords)
92
+ const parts = stripped.length > 0 ? stripped : rawParts
29
93
  // 去重但保留顺序
30
94
  const seen = new Set()
31
95
  const out = []
@@ -145,8 +209,15 @@ function explainTerms(page, indexLine, tokens) {
145
209
  */
146
210
  const INDEX_ONLY_SCORE = 8
147
211
 
148
- /** 类型分层:同分时结构化笔记优先于原始资料摘要 —— 笔记是消化过的结论。 */
149
- const TYPE_TIER = { 综合: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
212
+ /**
213
+ * 类型分层:同分时结构化笔记优先于原始资料摘要 —— 笔记是消化过的结论。
214
+ *
215
+ * 总览放在最高一档而不是默认档:它是全库唯一的入口页,一个跨模块的词(「复盘」「数据」
216
+ * 这类)在总览里出现的意义,和它在某个模块综合页里出现的意义不是一回事。2026-11-08 用
217
+ * tests/local/ab_export.py 重导基线后暴露:某一查询里总览与某个模块综合页同分 15,
218
+ * 按旧表(总览落到默认档 2)被挤到第 6 位,与 search.py 的前 5 不一致。
219
+ */
220
+ const TYPE_TIER = { 综合: 3, 总览: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
150
221
 
151
222
  function typeTier(page) {
152
223
  return TYPE_TIER[String(page.fields['类型'] ?? '')] ?? 2
@@ -293,6 +364,89 @@ function oversizedRelevance(corpus, tokens, indexMap) {
293
364
  return { total, via }
294
365
  }
295
366
 
367
+ // 字面覆盖率兜底的阈值,与 search.py 的 COVERAGE_MIN 取同一个数。
368
+ // 低于这条线不是「相关性弱」,是「根本不像在说同一件事」,放进结果里只会骗人。
369
+ const COVERAGE_MIN = 0.45
370
+ // 查询长度上限,与工具层 schema 的意思对齐(那边拦的是模型,这里拦的是 CLI / /search / 桥)。
371
+ const MAX_QUERY_CHARS = 200
372
+ const CJK_RE = /[\u3400-\u9fff]/
373
+
374
+ /**
375
+ * 把查询切成「字面原子」:中文按二字组、拉丁按整词。
376
+ *
377
+ * 为什么需要这一步:中文没有空格,一句「甲方案的实施顺序应该怎么安排」在 tokenize 眼里
378
+ * 就是**一个词元**,而库里不可能逐字出现这句话,于是 AND、OR 双双落空。用户看到的是
379
+ * 「库里没有」,可库里明明有一页在讲这件事。search.py 的降级层就是干这个的,
380
+ * 这里补上同一层,只在前面全落空时才启用。
381
+ */
382
+ function coverageAtomsOf(text) {
383
+ const atoms = []
384
+ const seen = new Map()
385
+ const push = (atom, weight) => {
386
+ const previous = seen.get(atom) ?? 0
387
+ if (previous >= weight) return
388
+ if (previous === 0) atoms.push(atom)
389
+ seen.set(atom, weight)
390
+ }
391
+ for (const chunk of String(text).match(/[\u3400-\u9fff]+|[A-Za-z0-9][A-Za-z0-9._+#-]*/g) ?? []) {
392
+ if (CJK_RE.test(chunk)) {
393
+ if (chunk.length === 1) push(chunk, 1)
394
+ else for (let i = 0; i < chunk.length - 1; i += 1) push(chunk.slice(i, i + 2), 1)
395
+ } else {
396
+ // 一个拉丁词比一个二字组信息量大:权重 3,与 search.py 的整段权重对齐
397
+ push(chunk.toLowerCase(), 3)
398
+ }
399
+ }
400
+ return atoms.map((atom) => ({ atom, weight: seen.get(atom) ?? 1 }))
401
+ }
402
+
403
+ /**
404
+ * 覆盖率通道:不要求整句出现,只要求「查询里的字面片段在这页出现了多少」。
405
+ * 分数刻意做成覆盖率 × 100 + 结构加分,量级远低于正常命中(页名全等 120),
406
+ * 所以它永远排在真命中后面 —— 这一层只负责「别报空」。
407
+ */
408
+ function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
409
+ const atoms = coverageAtomsOf(tokens.join(' '))
410
+ const totalWeight = atoms.reduce((sum, item) => sum + item.weight, 0)
411
+ if (atoms.length === 0 || totalWeight === 0) return []
412
+ const indexMap = buildIndexMap(corpus)
413
+ const out = []
414
+ for (const page of corpus.pages) {
415
+ if (page.oversized === true) continue
416
+ if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
417
+ if (tagFilter.length > 0) {
418
+ const pageTags = asList(page.fields['标签'])
419
+ if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
420
+ }
421
+ const body = page.body.toLowerCase()
422
+ const title = page.name.toLowerCase()
423
+ const aliasText = asList(page.fields['别名']).join(' ').toLowerCase()
424
+ const tagText = asList(page.fields['标签']).join(' ').toLowerCase()
425
+ let hitWeight = 0
426
+ const hitAtoms = []
427
+ for (const { atom, weight } of atoms) {
428
+ if (!body.includes(atom)) continue
429
+ hitWeight += weight
430
+ hitAtoms.push(atom)
431
+ }
432
+ const coverage = hitWeight / totalWeight
433
+ if (coverage < COVERAGE_MIN) continue
434
+ let bonus = 0
435
+ if (hitAtoms.some((atom) => title.includes(atom))) bonus += 20
436
+ if (hitAtoms.some((atom) => aliasText.includes(atom))) bonus += 10
437
+ if (hitAtoms.some((atom) => tagText.includes(atom))) bonus += 5
438
+ out.push({
439
+ page,
440
+ indexLine: indexMap.get(page.name) ?? null,
441
+ score: Math.round(coverage * 100) + bonus,
442
+ matched: hitAtoms.length,
443
+ allTerms: false,
444
+ atoms: hitAtoms,
445
+ })
446
+ }
447
+ return out
448
+ }
449
+
296
450
  /**
297
451
  * mode 2:search
298
452
  * 返回 hits(按分数降序),每项带索引摘要、命中小节正文、citation、断链。
@@ -353,14 +507,32 @@ export function search(corpus, query, options = {}) {
353
507
  list = scored
354
508
  }
355
509
 
510
+ // 最后一道兜底:AND 和 OR 都一条没有,但查询本身是「一句话」时,用字面覆盖率再找一遍。
511
+ // 只在结果为 0 时启用 —— 有任何一条真命中就不碰,所以它不可能把好结果挤掉。
512
+ let coverageFallback = false
513
+ if (list.length === 0) {
514
+ const covered = coveragePass(corpus, tokens, { typeFilter, tagFilter })
515
+ if (covered.length > 0) {
516
+ coverageFallback = true
517
+ degraded = true
518
+ list = covered
519
+ }
520
+ }
521
+
356
522
  list.sort(compareHits)
357
523
 
524
+ // 覆盖率通道下,整句作为一个词元在正文里必然找不到,选节会退化成「取第一段」。
525
+ // 改用命中的字面片段去选节:pickSection 本身没动,只是换了喂进去的词。
526
+ const sectionTokensOf = (item) => (coverageFallback ? item.atoms ?? tokens : tokens)
527
+
358
528
  const hits = list.slice(0, limit).map((item) => {
359
- const section = pickSection(item.page, tokens)
360
- const broken = section.text !== ''
361
- ? [...new Set((section.text.match(/\[\[([^\]|#]+)/g) ?? []).map((raw) => raw.slice(2).trim()))]
362
- .filter((link) => !corpus.byName.has(link) && !corpus.byAlias.has(link.toLowerCase()))
363
- : []
529
+ const section = pickSection(item.page, sectionTokensOf(item))
530
+ // 断链按整页算,不按命中小节算:选节会把页面截成一段,断链常落在文末的「相关」里,
531
+ // 只报小节内的会让模型把「这一页没有断链」当成结论 —— README 给它的语义是页级硬信号。
532
+ // 复用 corpus 已经解析好的 page.links,而不是在这里再扫一遍正文:
533
+ // 那边会跳过行内代码里的 `[[示例]]`(那是举例,不是链接),这边自己扫就会把示例当红链。
534
+ const broken = [...new Set(item.page.links ?? [])]
535
+ .filter((link) => !corpus.byName.has(link) && !corpus.byAlias.has(link.toLowerCase()))
364
536
  return {
365
537
  name: item.page.name,
366
538
  kind: pageKind(item.page),
@@ -384,6 +556,23 @@ export function search(corpus, query, options = {}) {
384
556
 
385
557
  const oversized = oversizedRelevance(corpus, tokens, indexMap)
386
558
 
559
+ // 单字查询命中过半页时,排序确实没有区分度(「的」「a」会命中几乎整库)。
560
+ // 不改结果——改了就是动排序,那是 §13.1 的地界;但必须让模型知道这批结果别当真。
561
+ const trivialQuery = tokens.length === 1 && tokens[0].length <= 1 && considered > 20 && scored.length >= considered * 0.5
562
+
563
+ // 过滤器把候选清空时,「这次没命中」和「库里根本没这种页」是两件事。
564
+ // 不说清楚,模型会把「库里没有资料类型的页」读成「库里没有这个主题」。
565
+ // 还有第三种:过了滤、也有页参与,但整句一页都没命中 —— 那时同样得说话,
566
+ // 否则「词不对」和「命中页被 type 过滤掉了」在模型看来长得一模一样(真库实测过)。
567
+ const filterApplied = typeFilter !== null || tagFilter.length > 0
568
+ const filterNote = !filterApplied
569
+ ? ''
570
+ : considered === 0
571
+ ? filterEmptyNote(corpus, typeFilter, tagFilter)
572
+ : (scored.length === 0 && list.length === 0
573
+ ? `过滤后仍有 ${considered} 页参与检索,但整句没有命中任何一页(字面覆盖率兜底 ${Math.round(COVERAGE_MIN * 100)}% 也没过)。这可能是词不对,也可能命中的页被 type/tags 过滤掉了——去掉过滤再搜一次就能分开。`
574
+ : '')
575
+
387
576
  return {
388
577
  mode: 'search',
389
578
  query,
@@ -392,14 +581,20 @@ export function search(corpus, query, options = {}) {
392
581
  // 这三件事决定「结果为空」该怪词、怪库,还是怪匹配模式。
393
582
  // missedTerms / matchMode 常驻(模型看到「这个词没用上」才可能换词重查,成本两个短字段);
394
583
  // 每个词在多少页上得分的明细只有 explain 时才给,那是面板的事。
395
- missedTerms: tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
584
+ // 覆盖率兜底下调时不能报「这些词一页都没命中」——命中正是靠这些词的字面片段捞到的,
585
+ // 两句话放在一起自相矛盾,note 里已经交代清楚。
586
+ missedTerms: coverageFallback ? [] : tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
396
587
  matchMode: degraded ? 'or' : 'and',
588
+ // 覆盖率兜底是 or 的下一层(仍标 matchMode/or 以保持面板与既有断言的两值语义),
589
+ // 但必须单独标出来:这时候「命中」只是字面沾边,精度比 OR 更低,模型叙述时要收着写。
590
+ coverageFallback,
591
+ trivialQuery,
397
592
  ...(explain ? { termPages: tokens.map((token) => ({ term: token, pages: termPages.get(token) ?? 0 })) } : {}),
398
593
  total: list.length,
399
594
  degraded,
400
595
  // 调用级统计:分母各是各的,别合成一个数字
401
596
  considered,
402
- matched: scored.length,
597
+ matched: coverageFallback ? list.length : scored.length,
403
598
  allTerms: scored.filter((item) => item.allTerms).length,
404
599
  returned: hits.length,
405
600
  // 超大页里「标题或 index 摘要」沾到查询词的数量:决定这次要不要提醒覆盖缺口,
@@ -407,10 +602,42 @@ export function search(corpus, query, options = {}) {
407
602
  oversizedRelevant: oversized.total,
408
603
  oversizedRelevantVia: oversized.via,
409
604
  hits,
410
- note: degraded ? '没有同时命中全部检索词,已降级为「命中任一」,命中面变宽、精度下降' : '',
605
+ note: filterNote
606
+ || (coverageFallback
607
+ ? `整句没有命中任何页(中文不分词,"${query}" 被当成一个词元),已降级为字面覆盖率匹配(≥${Math.round(COVERAGE_MIN * 100)}%)。结果只作线索:命中是字面沾边,不是这页回答了你。`
608
+ : degraded
609
+ ? '没有同时命中全部检索词,已降级为 OR(命中任一):命中面变宽、精度下降'
610
+ : trivialQuery
611
+ ? `查询只有一个字("${tokens[0]}"),它在这 ${considered} 页里出现了 ${scored.length} 页——这个字到处都有,排序没有区分度。换个更具体的词再搜。`
612
+ : ''),
411
613
  }
412
614
  }
413
615
 
616
+ /** 过滤器把候选清空时,说清楚是「库里没这种页」而不是「库里没这个主题」。 */
617
+ function filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter = null) {
618
+ const dist = new Map()
619
+ const statuses = new Map()
620
+ for (const page of corpus.pages) {
621
+ if (page.oversized === true) continue
622
+ const type = String(page.fields['类型'] ?? '') || '(无类型)'
623
+ dist.set(type, (dist.get(type) ?? 0) + 1)
624
+ const status = String(page.fields['状态'] ?? '') || '(无状态)'
625
+ statuses.set(status, (statuses.get(status) ?? 0) + 1)
626
+ }
627
+ const tally = (map) => [...map.entries()]
628
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0], 'zh'))
629
+ .map(([key, count]) => `${key} ${count}`)
630
+ .join(' / ')
631
+ const asked = [
632
+ typeFilter === null ? '' : `type=${typeFilter}`,
633
+ statusFilter === null ? '' : `status=${statusFilter}`,
634
+ tagFilter.length === 0 ? '' : `tags=${tagFilter.join('/')}`,
635
+ ].filter((part) => part !== '').join(' ')
636
+ const typeShown = tally(dist)
637
+ const statusShown = tally(statuses)
638
+ return `库里没有符合 ${asked} 的页(现有类型:${typeShown === '' ? '无' : typeShown}${statusFilter === null ? '' : `;现有状态:${statusShown === '' ? '无' : statusShown}`})。这是过滤条件的问题,不是主题不存在——去掉过滤再搜。`
639
+ }
640
+
414
641
  /** mode 2:page —— 按页名/别名/模糊取整页。取不到就给最像的 5 个候选。 */
415
642
  export function page(corpus, name, options = {}) {
416
643
  const wanted = String(name ?? '').trim()
@@ -419,12 +646,24 @@ export function page(corpus, name, options = {}) {
419
646
 
420
647
  const indexMap = buildIndexMap(corpus)
421
648
  const exact = corpus.byName.get(wanted) ?? corpus.byName.get(wanted.replace(/\.md$/i, ''))
422
- if (exact !== undefined) return { mode: 'page', found: renderPage(corpus, exact, indexMap, limit), candidates: [] }
649
+ if (exact !== undefined) {
650
+ const found = renderPage(corpus, exact, indexMap, limit)
651
+ const note = pageBodyNote(found)
652
+ return { mode: 'page', found, candidates: [], ...(note === '' ? {} : { note }) }
653
+ }
423
654
 
424
655
  const aliasHits = corpus.byAlias.get(wanted.toLowerCase()) ?? []
425
656
  if (aliasHits.length > 0) {
426
657
  const first = aliasHits[0]
427
- return { mode: 'page', found: renderPage(corpus, first, indexMap, limit), candidates: [] }
658
+ return {
659
+ mode: 'page',
660
+ found: renderPage(corpus, first, indexMap, limit),
661
+ candidates: [],
662
+ // 别名是检索入口,被两页共用时「按名字取页」就是抛硬币 —— 必须点名,别让引用悄悄指错。
663
+ ...(aliasHits.length > 1
664
+ ? { note: aliasCollisionNote(aliasHits, first, wanted), aliasConflict: true }
665
+ : {}),
666
+ }
428
667
  }
429
668
 
430
669
  // 模糊:包含关系 → 相似度
@@ -457,6 +696,18 @@ export function page(corpus, name, options = {}) {
457
696
  }
458
697
  }
459
698
 
699
+ /** 命中的页没有正文时会话里最容易出的错:模型引用一个空页当依据。 */
700
+ function pageBodyNote(found) {
701
+ const body = typeof found?.body === 'string' ? found.body.trim() : ''
702
+ return body === '' ? '这页没有正文(只有 frontmatter 或文件是空的):别把它当依据,回到原始资料或换一页' : ''
703
+ }
704
+
705
+ /** 别名被多页共用:按别名取页等于抛硬币,点名让人改。 */
706
+ function aliasCollisionNote(aliasHits, chosen, wanted) {
707
+ const names = aliasHits.map((item) => `${item.name}(${item.file})`).join('、')
708
+ return `别名「${wanted}」被 ${aliasHits.length} 页共用:${names};这次给的是 ${chosen.name}。引用前先确认是哪一篇,或把别名改成唯一。`
709
+ }
710
+
460
711
  function renderPage(corpus, page, indexMap, limit) {
461
712
  const body = clip(page.body, limit)
462
713
  return {
@@ -507,6 +758,13 @@ export function list(corpus, options = {}) {
507
758
  const limit = intOption(options, 'limit', 40, 1, 200)
508
759
  const shown = rows.slice(0, limit)
509
760
 
761
+ // 空目录同样要区分「库里没这种页」与「库里没这个东西」:list 的调用方拿到的是一张空表,
762
+ // 不给一句话它只能猜。与 search 的 filterEmptyNote() 同一套说法,维度多一个 status。
763
+ const filtered = typeFilter !== null || statusFilter !== null || tagFilter.length > 0
764
+ const note = rows.length === 0 && filtered
765
+ ? filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter)
766
+ : ''
767
+
510
768
  return {
511
769
  mode: 'list',
512
770
  total: rows.length,
@@ -515,6 +773,7 @@ export function list(corpus, options = {}) {
515
773
  byType,
516
774
  scale: corpus.scaleLine,
517
775
  rows: shown,
776
+ ...(note === '' ? {} : { note }),
518
777
  }
519
778
  }
520
779
 
@@ -1041,23 +1300,45 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
1041
1300
  warnings.push(dupWarning)
1042
1301
  return { status: 'partial', warnings }
1043
1302
  }
1303
+ // 别名被多页共用与同名页是同一类风险(引错版本),只是入口不同:一个按页名,一个按别名。
1304
+ if (mode === 'page' && result.aliasConflict === true) {
1305
+ warnings.push(engineNote(result) || '这个别名被多页共用,这次给的不一定是你要的那篇')
1306
+ return { status: 'partial', warnings }
1307
+ }
1044
1308
  if (mode === 'search' && result.degraded === true) {
1045
1309
  // 降级与「超大页可能相关」可以同时成立:状态按约定取 degraded,但两条事实都要输出 ——
1046
1310
  // 别让一个状态值把覆盖缺口吞掉。
1047
1311
  if (oversizedHit) warnings.push(oversizedWarning)
1048
- warnings.push('只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
1312
+ // 引擎自己知道这次是「命中任一词」还是「整句只沾字面」(覆盖率兜底),
1313
+ // 让它的说法优先:模型要做的动作不一样 —— 前者该收窄词,后者该换更短的词或直接查页面。
1314
+ // 固定文案只当兜底(老调用方不带 note 时)。
1315
+ warnings.push(engineNote(result)
1316
+ || '只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
1049
1317
  return { status: 'degraded', warnings }
1050
1318
  }
1051
1319
  if (oversizedHit) {
1320
+ // 目录/检索为空而库里恰好有超大页时,两件事都得说:先说「为什么是空的」(可能是过滤条件写错),
1321
+ // 再说「还漏了超大页」。只报后者的话,模型会以为过滤是对的、只是内容太大。
1322
+ const why = engineNote(result)
1323
+ if (why !== '') warnings.push(why)
1052
1324
  warnings.push(oversizedWarning)
1053
1325
  return { status: 'partial', warnings }
1054
1326
  }
1055
- if (empty) return { status: 'no_match', warnings: [] }
1327
+ // 零命中也要带上「为什么零命中」:过滤器清空与主题不存在是两件事,
1328
+ // 引擎写在 note 里的那句话如果在这里丢掉,模型只能自己猜。
1329
+ if (empty) {
1330
+ const why = engineNote(result)
1331
+ return { status: 'no_match', warnings: why === '' ? [] : [why] }
1332
+ }
1056
1333
  return { status: 'ok', warnings: [] }
1057
1334
  }
1058
1335
 
1059
- /** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */
1060
- function viaText(via) {
1336
+ /** 引擎写好的那句话(降级原因 / 单字无区分度),没有就返回空串。 */
1337
+ function engineNote(result) {
1338
+ return typeof result?.note === 'string' ? result.note.trim() : ''
1339
+ }
1340
+
1341
+ /** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */function viaText(via) {
1061
1342
  if (via === '标题') return '标题命中查询词'
1062
1343
  if (via === '摘要') return 'index 摘要命中查询词'
1063
1344
  return '标题或 index 摘要命中查询词'