dsh-wiki-notes 1.6.1 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +195 -0
- package/README.md +112 -20
- package/bin/cli.mjs +2 -2
- package/docs/preview-overview.png +0 -0
- package/docs/preview.png +0 -0
- package/docs//345/272/223/347/273/223/346/236/204.md +1 -1
- package/examples/sample-wiki//350/265/204/346/226/231-sources//346/237/220/350/257/276/347/250/213/347/254/254/344/270/211/350/256/262/302/267/350/265/204/346/226/231/346/221/230/350/246/201.md +1 -1
- package/icon.svg +4 -0
- package/lib/calls.js +24 -4
- package/lib/client.js +1409 -17
- package/lib/corpus.js +3 -1
- package/lib/engine.js +116 -15
- package/lib/index.js +425 -7
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +10 -5
package/lib/corpus.js
CHANGED
|
@@ -392,7 +392,9 @@ export async function loadCorpus(wikiDir) {
|
|
|
392
392
|
// 只看条数会把它读成「最近没有改动」。
|
|
393
393
|
logPresent: logInfo.present,
|
|
394
394
|
logEntries: log.length,
|
|
395
|
-
|
|
395
|
+
// failures 已含 walk/stat/read/parse 四类失败;再加一次 statFailures 会把
|
|
396
|
+
// 同一批文件算两遍,覆盖诊断的「目录/stat 失败」就会凭空翻倍。
|
|
397
|
+
failuresTotal: failures.length,
|
|
396
398
|
failures: failures.slice(0, MAX_FAILURE_DETAILS),
|
|
397
399
|
scannedMs: Date.now() - startedAt,
|
|
398
400
|
// 「这次到底读到了什么、什么时候读的」—— 覆盖诊断要的不只是页数。
|
package/lib/engine.js
CHANGED
|
@@ -406,7 +406,7 @@ function coverageAtomsOf(text) {
|
|
|
406
406
|
* 分数刻意做成覆盖率 × 100 + 结构加分,量级远低于正常命中(页名全等 120),
|
|
407
407
|
* 所以它永远排在真命中后面 —— 这一层只负责「别报空」。
|
|
408
408
|
*/
|
|
409
|
-
function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
|
|
409
|
+
function coveragePass(corpus, tokens, { typeFilter, tagFilter, statusFilter = null }) {
|
|
410
410
|
const atoms = coverageAtomsOf(tokens.join(' '))
|
|
411
411
|
const totalWeight = atoms.reduce((sum, item) => sum + item.weight, 0)
|
|
412
412
|
if (atoms.length === 0 || totalWeight === 0) return []
|
|
@@ -415,6 +415,7 @@ function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
|
|
|
415
415
|
for (const page of corpus.pages) {
|
|
416
416
|
if (page.oversized === true) continue
|
|
417
417
|
if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
|
|
418
|
+
if (statusFilter !== null && String(page.fields['状态'] ?? '') !== statusFilter) continue
|
|
418
419
|
if (tagFilter.length > 0) {
|
|
419
420
|
const pageTags = asList(page.fields['标签'])
|
|
420
421
|
if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
|
|
@@ -448,6 +449,58 @@ function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
|
|
|
448
449
|
return out
|
|
449
450
|
}
|
|
450
451
|
|
|
452
|
+
/** 零命中时最多列几页沾边候选。三页够指方向,再多就变成「另一个结果列表」。 */
|
|
453
|
+
const NEAR_MISS_LIMIT = 3
|
|
454
|
+
|
|
455
|
+
/**
|
|
456
|
+
* 零命中时的「最接近的几页」。
|
|
457
|
+
*
|
|
458
|
+
* 命中为空不等于库里没有:词对不上、中文没分词、过滤条件太窄,三种都会让分数归零,
|
|
459
|
+
* 而它们该采取的动作完全不同(换词 / 拆词 / 放开过滤)。只回一句「没命中」,
|
|
460
|
+
* 模型只能瞎猜;给出沾边候选,它才知道该往哪边走。
|
|
461
|
+
*
|
|
462
|
+
* 两条纪律:
|
|
463
|
+
* 1. 这一栏从不参与 hits 的生成 —— 它只在 hits 为空时才算,不可能挤掉任何真结果。
|
|
464
|
+
* 2. 被过滤掉的候选要标出来(filtered):「我筛掉了它」和「库里没有它」是两件事。
|
|
465
|
+
*/
|
|
466
|
+
export function nearMissOf(corpus, tokens, { typeFilter = null, tagFilter = [], statusFilter = null, limit = NEAR_MISS_LIMIT } = {}) {
|
|
467
|
+
const atoms = coverageAtomsOf(tokens.join(' '))
|
|
468
|
+
const totalWeight = atoms.reduce((sum, item) => sum + item.weight, 0)
|
|
469
|
+
if (atoms.length === 0 || totalWeight === 0) return []
|
|
470
|
+
const tags = Array.isArray(tagFilter) ? tagFilter : []
|
|
471
|
+
const out = []
|
|
472
|
+
for (const page of corpus.pages) {
|
|
473
|
+
if (page.oversized === true) continue
|
|
474
|
+
const body = String(page.body ?? '').toLowerCase()
|
|
475
|
+
const title = String(page.name ?? '').toLowerCase()
|
|
476
|
+
let hitWeight = 0
|
|
477
|
+
const hitAtoms = []
|
|
478
|
+
for (const { atom, weight } of atoms) {
|
|
479
|
+
if (!body.includes(atom) && !title.includes(atom)) continue
|
|
480
|
+
hitWeight += weight
|
|
481
|
+
hitAtoms.push(atom)
|
|
482
|
+
}
|
|
483
|
+
if (hitWeight === 0) continue
|
|
484
|
+
const type = String(page.fields['类型'] ?? '')
|
|
485
|
+
const status = String(page.fields['状态'] ?? '')
|
|
486
|
+
const pageTags = asList(page.fields['标签'])
|
|
487
|
+
out.push({
|
|
488
|
+
name: page.name,
|
|
489
|
+
type,
|
|
490
|
+
file: page.file,
|
|
491
|
+
// 覆盖率按同一套权重算,和覆盖兜底同量级 —— 85% 还没过 45% 线是不可能的,
|
|
492
|
+
// 所以这里出现的一定是「差一点」而不是「本该命中」。
|
|
493
|
+
coverage: Math.round((hitWeight / totalWeight) * 100),
|
|
494
|
+
words: hitAtoms.slice(0, 4),
|
|
495
|
+
filtered: (typeFilter !== null && type !== typeFilter)
|
|
496
|
+
|| (statusFilter !== null && status !== statusFilter)
|
|
497
|
+
|| (tags.length > 0 && !tags.some((tag) => matchesTag(pageTags, tag))),
|
|
498
|
+
})
|
|
499
|
+
}
|
|
500
|
+
out.sort((a, b) => b.coverage - a.coverage || a.name.localeCompare(b.name, 'zh'))
|
|
501
|
+
return out.slice(0, limit)
|
|
502
|
+
}
|
|
503
|
+
|
|
451
504
|
/**
|
|
452
505
|
* mode 2:search
|
|
453
506
|
* 返回 hits(按分数降序),每项带索引摘要、命中小节正文、citation、断链。
|
|
@@ -462,6 +515,9 @@ export function search(corpus, query, options = {}) {
|
|
|
462
515
|
const sectionChars = intOption(options, 'sectionChars', DEFAULT_SECTION_CHARS, 120, 3000)
|
|
463
516
|
const typeFilter = typeof options.type === 'string' && options.type.trim() !== '' ? options.type.trim() : null
|
|
464
517
|
const tagFilter = asList(options.tags)
|
|
518
|
+
// status 与 list() 同一口径:schema 里声明了,search 就得真的筛。
|
|
519
|
+
// 否则模型传了 status 却拿到没筛过的结果,会以为库里没有这种状态的页。
|
|
520
|
+
const statusFilter = typeof options.status === 'string' && options.status.trim() !== '' ? options.status.trim() : null
|
|
465
521
|
// explain 只多带「这分怎么来的」,不参与打分与排序;工具 schema 里没有这个开关,
|
|
466
522
|
// 它只给设置页/侧栏那份只读 API 用,模型看不到也多不出 token。
|
|
467
523
|
const explain = options.explain === true
|
|
@@ -476,6 +532,7 @@ export function search(corpus, query, options = {}) {
|
|
|
476
532
|
for (const page of corpus.pages) {
|
|
477
533
|
if (page.oversized === true) continue
|
|
478
534
|
if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
|
|
535
|
+
if (statusFilter !== null && String(page.fields['状态'] ?? '') !== statusFilter) continue
|
|
479
536
|
if (tagFilter.length > 0) {
|
|
480
537
|
const pageTags = asList(page.fields['标签'])
|
|
481
538
|
if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
|
|
@@ -512,7 +569,7 @@ export function search(corpus, query, options = {}) {
|
|
|
512
569
|
// 只在结果为 0 时启用 —— 有任何一条真命中就不碰,所以它不可能把好结果挤掉。
|
|
513
570
|
let coverageFallback = false
|
|
514
571
|
if (list.length === 0) {
|
|
515
|
-
const covered = coveragePass(corpus, tokens, { typeFilter, tagFilter })
|
|
572
|
+
const covered = coveragePass(corpus, tokens, { typeFilter, tagFilter, statusFilter })
|
|
516
573
|
if (covered.length > 0) {
|
|
517
574
|
coverageFallback = true
|
|
518
575
|
degraded = true
|
|
@@ -571,14 +628,14 @@ export function search(corpus, query, options = {}) {
|
|
|
571
628
|
// 过滤器把候选清空时,「这次没命中」和「库里根本没这种页」是两件事。
|
|
572
629
|
// 不说清楚,模型会把「库里没有资料类型的页」读成「库里没有这个主题」。
|
|
573
630
|
// 还有第三种:过了滤、也有页参与,但整句一页都没命中 —— 那时同样得说话,
|
|
574
|
-
// 否则「词不对」和「命中页被 type 过滤掉了」在模型看来长得一模一样(真库实测过)。
|
|
575
|
-
const filterApplied = typeFilter !== null || tagFilter.length > 0
|
|
631
|
+
// 否则「词不对」和「命中页被 type/tags/status 过滤掉了」在模型看来长得一模一样(真库实测过)。
|
|
632
|
+
const filterApplied = typeFilter !== null || tagFilter.length > 0 || statusFilter !== null
|
|
576
633
|
const filterNote = !filterApplied
|
|
577
634
|
? ''
|
|
578
635
|
: considered === 0
|
|
579
|
-
? filterEmptyNote(corpus, typeFilter, tagFilter)
|
|
636
|
+
? filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter)
|
|
580
637
|
: (scored.length === 0 && list.length === 0
|
|
581
|
-
? `过滤后仍有 ${considered} 页参与检索,但整句没有命中任何一页(字面覆盖率兜底 ${Math.round(COVERAGE_MIN * 100)}% 也没过)。这可能是词不对,也可能命中的页被 type/tags 过滤掉了——去掉过滤再搜一次就能分开。`
|
|
638
|
+
? `过滤后仍有 ${considered} 页参与检索,但整句没有命中任何一页(字面覆盖率兜底 ${Math.round(COVERAGE_MIN * 100)}% 也没过)。这可能是词不对,也可能命中的页被 type/tags/status 过滤掉了——去掉过滤再搜一次就能分开。`
|
|
582
639
|
: '')
|
|
583
640
|
|
|
584
641
|
return {
|
|
@@ -609,6 +666,10 @@ export function search(corpus, query, options = {}) {
|
|
|
609
666
|
// 不参与命中与排序 —— 它只是元数据线索,不是正文检索结果
|
|
610
667
|
oversizedRelevant: oversized.total,
|
|
611
668
|
oversizedRelevantVia: oversized.via,
|
|
669
|
+
// 零命中才有这一栏:库可能在,只是这次的说法对不上。
|
|
670
|
+
nearMiss: hits.length === 0
|
|
671
|
+
? nearMissOf(corpus, tokens, { typeFilter, tagFilter, statusFilter })
|
|
672
|
+
: [],
|
|
612
673
|
hits,
|
|
613
674
|
note: filterNote
|
|
614
675
|
|| (coverageFallback
|
|
@@ -650,12 +711,17 @@ function filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter = null) {
|
|
|
650
711
|
export function page(corpus, name, options = {}) {
|
|
651
712
|
const wanted = String(name ?? '').trim()
|
|
652
713
|
const limit = intOption(options, 'pageChars', DEFAULT_PAGE_CHARS, 500, 20000)
|
|
714
|
+
const sectionSelector = typeof options.section === 'string' || typeof options.section === 'number'
|
|
715
|
+
? String(options.section).trim()
|
|
716
|
+
: ''
|
|
653
717
|
if (wanted === '') return { mode: 'page', found: null, candidates: [] }
|
|
654
718
|
|
|
655
719
|
const indexMap = buildIndexMap(corpus)
|
|
656
720
|
const exact = corpus.byName.get(wanted) ?? corpus.byName.get(wanted.replace(/\.md$/i, ''))
|
|
657
721
|
if (exact !== undefined) {
|
|
658
|
-
const found = renderPage(corpus, exact, indexMap, limit)
|
|
722
|
+
const found = renderPage(corpus, exact, indexMap, limit, sectionSelector)
|
|
723
|
+
// 小节没找到的说明已经放在 found.sectionNote 里(渲染器会在正文前印一行 ⚠️);
|
|
724
|
+
// 这里再拼进 note 就会把同一句话说两遍。note 只保留整页级别的提示。
|
|
659
725
|
const note = pageBodyNote(found, exact.oversized === true)
|
|
660
726
|
return { mode: 'page', found, candidates: [], ...(note === '' ? {} : { note }) }
|
|
661
727
|
}
|
|
@@ -665,7 +731,7 @@ export function page(corpus, name, options = {}) {
|
|
|
665
731
|
const first = aliasHits[0]
|
|
666
732
|
return {
|
|
667
733
|
mode: 'page',
|
|
668
|
-
found: renderPage(corpus, first, indexMap, limit),
|
|
734
|
+
found: renderPage(corpus, first, indexMap, limit, sectionSelector),
|
|
669
735
|
candidates: [],
|
|
670
736
|
// 别名是检索入口,被两页共用时「按名字取页」就是抛硬币 —— 必须点名,别让引用悄悄指错。
|
|
671
737
|
...(aliasHits.length > 1
|
|
@@ -709,6 +775,11 @@ function pageBodyNote(found, oversized = false) {
|
|
|
709
775
|
// 超大页的 body 也是空字符串,但原因不是「文件是空的」——那句说明由 decideStatus 给,
|
|
710
776
|
// 这里再说一遍就成了两条互相矛盾的提示(一条说文件空,一条说超过 512KB)。
|
|
711
777
|
if (oversized === true) return ''
|
|
778
|
+
// 指定了小节但没找到:body 为空是「没取到那一节」,不是整页没正文 ——
|
|
779
|
+
// 这句「整页没正文」会和「没有这一节」互相打架,得让后者单独说。
|
|
780
|
+
if (typeof found?.sectionNote === 'string' && found.sectionNote !== '') return ''
|
|
781
|
+
// 取单节时 body 只是那一节,节为空不等于整页没正文。
|
|
782
|
+
if (typeof found?.sectionTitle === 'string' && found.sectionTitle !== '') return ''
|
|
712
783
|
const body = typeof found?.body === 'string' ? found.body.trim() : ''
|
|
713
784
|
return body === '' ? '这页没有正文(只有 frontmatter 或文件是空的):别把它当依据,回到原始资料或换一页' : ''
|
|
714
785
|
}
|
|
@@ -719,8 +790,26 @@ function aliasCollisionNote(aliasHits, chosen, wanted) {
|
|
|
719
790
|
return `别名「${wanted}」被 ${aliasHits.length} 页共用:${names};这次给的是 ${chosen.name}。引用前先确认是哪一篇,或把别名改成唯一。`
|
|
720
791
|
}
|
|
721
792
|
|
|
722
|
-
function renderPage(corpus, page, indexMap, limit) {
|
|
723
|
-
const
|
|
793
|
+
function renderPage(corpus, page, indexMap, limit, sectionSelector = '') {
|
|
794
|
+
const titled = page.sections.filter((section) => section.title !== '')
|
|
795
|
+
const titles = titled.map((section) => section.title)
|
|
796
|
+
// search 的截断提示会指向「page 带 section 再取一次」。这里必须真的能取到那一节:
|
|
797
|
+
// 标题精确优先,其次按 1-based 序号;序号按界面列出的「小节」算,
|
|
798
|
+
// 不能把 H1 前言(无标题的那段)算进去,否则「1」会取错一节。
|
|
799
|
+
let picked = null
|
|
800
|
+
let sectionNote = ''
|
|
801
|
+
if (sectionSelector !== '') {
|
|
802
|
+
const byTitle = titled.find((section) => section.title === sectionSelector)
|
|
803
|
+
const asIndex = /^\d+$/.test(sectionSelector) ? Number(sectionSelector) : 0
|
|
804
|
+
picked = byTitle ?? (asIndex >= 1 && asIndex <= titled.length ? titled[asIndex - 1] : null)
|
|
805
|
+
if (picked === null) {
|
|
806
|
+
sectionNote = `没有这一节:${sectionSelector}。这页的小节是 ${titles.length > 0 ? titles.join(' / ') : '(无)'};可用小节标题或 1-based 序号再查一次。`
|
|
807
|
+
}
|
|
808
|
+
}
|
|
809
|
+
// 指定过小节却没找到时不给整页正文:模型要的是那一节,拿回整页会把「没找到」
|
|
810
|
+
// 和「找到了但很长」混成一件事,还白花一份 pageChars 的 token。
|
|
811
|
+
const source = sectionSelector === '' ? page.body : (picked?.text ?? '')
|
|
812
|
+
const body = clip(source, limit)
|
|
724
813
|
return {
|
|
725
814
|
name: page.name,
|
|
726
815
|
type: String(page.fields['类型'] ?? ''),
|
|
@@ -731,10 +820,14 @@ function renderPage(corpus, page, indexMap, limit) {
|
|
|
731
820
|
tags: asList(page.fields['标签']),
|
|
732
821
|
aliases: asList(page.fields['别名']),
|
|
733
822
|
summary: indexMap.get(page.name)?.summary ?? '',
|
|
734
|
-
sections:
|
|
823
|
+
sections: titles,
|
|
824
|
+
sectionTitle: picked?.title ?? '',
|
|
825
|
+
sectionNote,
|
|
735
826
|
body,
|
|
736
|
-
truncated: body.length <
|
|
737
|
-
citation:
|
|
827
|
+
truncated: body.length < source.length,
|
|
828
|
+
citation: picked === null
|
|
829
|
+
? `← [[${page.name}]] → ${page.file}`
|
|
830
|
+
: `← [[${page.name}]] §${picked.title} → ${page.file}`,
|
|
738
831
|
file: page.file,
|
|
739
832
|
}
|
|
740
833
|
}
|
|
@@ -1197,8 +1290,8 @@ export function help() {
|
|
|
1197
1290
|
lines: [
|
|
1198
1291
|
'help:就是这份说明。不确定用哪个 mode、或看不懂某个 status 时先查它 —— 它不读库,不会失败。',
|
|
1199
1292
|
'search(默认):1-4 个核心名词,空格分隔做 AND。返回元数据 + index 摘要 + 命中小节正文 + 出处,通常一次就够作答。',
|
|
1200
|
-
'page
|
|
1201
|
-
'list:按 type / tags / status 列目录,比读 index.md 省 token。',
|
|
1293
|
+
'page:传页名取整页;带 section(小节标题或 1-based 序号)就只取那一节,截断片段可以一次补齐;没精确命中会给 5 个候选。',
|
|
1294
|
+
'list:按 type / tags / status 列目录,比读 index.md 省 token。status 取值:草稿 / 演进中 / 稳定 / 存疑 / 已归档。',
|
|
1202
1295
|
'overview:总览正文 + 规模 + 最近日志 + 断链统计。',
|
|
1203
1296
|
'lint:全库健康检查 —— 孤儿页、断链、缺字段、别名冲突、久未更新、草稿、index 与磁盘不一致。',
|
|
1204
1297
|
'draft:给一份落盘骨架(目录、frontmatter、index 那行、log 那条),只返回文本。',
|
|
@@ -1231,6 +1324,8 @@ export function help() {
|
|
|
1231
1324
|
'limit:search 返回几页,默认 5、最多 12;lint 时是每组列几条,默认 8。',
|
|
1232
1325
|
'sectionChars:search 每页正文上限,默认 900;需要完整段落时调到 1500-2000。',
|
|
1233
1326
|
'pageChars:page 正文上限,默认 6000;overview 引用总览时默认 4000。',
|
|
1327
|
+
'section:mode=page 时只取某一节,填小节标题或 1-based 序号;search 正文被截断时照提示带上它再取一次。',
|
|
1328
|
+
'status:search / list 按 frontmatter「状态」筛;五档是草稿 / 演进中 / 稳定 / 存疑 / 已归档。',
|
|
1234
1329
|
'staleDays:lint 判「久未更新」的天数,默认 120。',
|
|
1235
1330
|
],
|
|
1236
1331
|
},
|
|
@@ -1391,6 +1486,12 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
|
|
|
1391
1486
|
}
|
|
1392
1487
|
// 零命中也要带上「为什么零命中」:过滤器清空与主题不存在是两件事,
|
|
1393
1488
|
// 引擎写在 note 里的那句话如果在这里丢掉,模型只能自己猜。
|
|
1489
|
+
// page 指定了小节却没找到:found 还在、但 body 是空的,不能报 ok。
|
|
1490
|
+
// 原因写在正文的 ⚠️ 行(found.sectionNote),warnings 留空,免得同一句被
|
|
1491
|
+
// renderValue 的「本次结果有缺口」再印一遍。
|
|
1492
|
+
if (mode === 'page' && typeof result?.found?.sectionNote === 'string' && result.found.sectionNote !== '') {
|
|
1493
|
+
return { status: 'no_match', warnings: [] }
|
|
1494
|
+
}
|
|
1394
1495
|
if (empty) {
|
|
1395
1496
|
const why = engineNote(result)
|
|
1396
1497
|
return { status: 'no_match', warnings: why === '' ? [] : [why] }
|