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/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
- /** 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。 */
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
- const trimmed = String(query ?? '').trim()
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 parts = trimmed.split(/[\s,,、。;;/|]+/).map((part) => part.trim()).filter((part) => part !== '')
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
- const TYPE_TIER = { 综合: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
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.slice(0, limit)}…`
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, 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
- : []
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: { title: section.title, text: clip(section.text, sectionChars) },
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
- missedTerms: tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
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: degraded ? '没有同时命中全部检索词,已降级为「命中任一」,命中面变宽、精度下降' : '',
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) return { mode: 'page', found: renderPage(corpus, exact, indexMap, limit), candidates: [] }
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 { mode: 'page', found: renderPage(corpus, first, indexMap, limit), candidates: [] }
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
- const sources = Number.isFinite(Number(options.sources)) ? Number(options.sources) : 0
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.length < 10) continue
790
- const time = Date.parse(`${raw.slice(0, 10)}T00:00:00Z`)
791
- if (!Number.isFinite(time)) continue
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' && tokenize(args.query ?? '').length === 0) {
940
- return 'query 为空:请传 1–4 个关键词'
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
- warnings.push('只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
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
- if (empty) return { status: 'no_match', warnings: [] }
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
- /** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */
1060
- function viaText(via) {
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 摘要命中查询词'