dsh-wiki-notes 1.1.2 → 1.3.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/corpus.js CHANGED
@@ -68,9 +68,32 @@ export function splitFrontmatter(text) {
68
68
  }
69
69
  const match = text.match(FM_RE)
70
70
  if (match === null) return { fields: {}, body: text }
71
+ // 缺收尾 `---` 时,非贪婪正则会一路吃到正文里下一条分隔线,把标题与首段整段吞掉,
72
+ // 而且不报警 —— 模型看到的就是一篇没有开头的小节。
73
+ // 内容不像元数据就当没有:宁可少解析一次,也不能让正文凭空不见。
74
+ if (!looksLikeFields(match[1])) return { fields: {}, body: text }
71
75
  return { fields: parseFields(match[1]), body: text.slice(match[0].length) }
72
76
  }
73
77
 
78
+ /**
79
+ * 一段「像元数据」的文本:每行要么空行、注释、块序列项,要么是 `键: 值`。
80
+ * 用来分辨 `---` 之间那一段到底是 frontmatter,还是正文里碰巧出现的两条分隔线。
81
+ */
82
+ function looksLikeFields(raw) {
83
+ let sawField = false
84
+ for (const line of raw.split(/\r?\n/)) {
85
+ const trimmed = line.trim()
86
+ if (trimmed === '' || trimmed.startsWith('#')) continue
87
+ if (trimmed.startsWith('- ') || trimmed === '-') continue
88
+ if (/^[^\s:#][^:]*:/.test(trimmed)) {
89
+ sawField = true
90
+ continue
91
+ }
92
+ return false
93
+ }
94
+ return sawField
95
+ }
96
+
74
97
  /**
75
98
  * 解析 key: value 行。
76
99
  * 真实库里只有七种值形态:纯文本、数字、`[]`、`[a, b]`、`[{{占位}}]`、日期、带引号。
@@ -163,12 +186,21 @@ function finish(section) {
163
186
  return { title: section.title, text: section.lines.join('\n').trim() }
164
187
  }
165
188
 
166
- /** 正文里的双链:`[[页名]]` 与 `[[页名|显示名]]`,去掉 `#锚点`。 */
189
+ /**
190
+ * 正文里的双链:`[[页名]]` 与 `[[页名|显示名]]`,去掉 `#锚点`。
191
+ *
192
+ * 两处细节都是实测踩出来的:
193
+ * - 表格里写双链要用 `\|` 转义,`[[甲\|别名]]` 早先会把页名读成 `甲\`(多一个反斜杠),
194
+ * 于是每张表格里的链接都变成红链。
195
+ * - 代码块和行内代码里的 `[[...]]` 是示例不是链接,不该进图谱。splitSections 早就剥了围栏,
196
+ * 这里原来没剥,同一条正文两种口径。
197
+ */
167
198
  export function extractLinks(text) {
168
199
  const names = []
169
- const re = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g
200
+ const plain = String(text ?? '').replace(/```[\s\S]*?```/g, '').replace(/`[^`\n]*`/g, '')
201
+ const re = /\[\[([^\]|#\\]+)(?:#[^\]|]*)?(?:\\?\|[^\]]*)?\]\]/g
170
202
  let match
171
- while ((match = re.exec(text)) !== null) {
203
+ while ((match = re.exec(plain)) !== null) {
172
204
  const name = match[1].trim()
173
205
  if (name !== '') names.push(name)
174
206
  }
@@ -179,6 +211,19 @@ export function extractLinks(text) {
179
211
  * 扫描整个 wiki 层。
180
212
  * 返回 { wikiDir, pages, byName, byAlias, indexLines, scaleLine, log, brokenLinks, stats }
181
213
  */
214
+ /** 页面的最后修改时间里最新 / 最旧的那一个,给覆盖诊断用(空库返回空串,不造 1970)。 */
215
+ function newestIso(pages) {
216
+ const values = pages.map((page) => page.mtime).filter((value) => typeof value === 'number' && value > 0)
217
+ if (values.length === 0) return ''
218
+ return new Date(Math.max(...values)).toISOString()
219
+ }
220
+
221
+ function oldestIso(pages) {
222
+ const values = pages.map((page) => page.mtime).filter((value) => typeof value === 'number' && value > 0)
223
+ if (values.length === 0) return ''
224
+ return new Date(Math.min(...values)).toISOString()
225
+ }
226
+
182
227
  export async function loadCorpus(wikiDir) {
183
228
  const startedAt = Date.now()
184
229
  const walked = await walkMarkdown(wikiDir)
@@ -299,6 +344,13 @@ export async function loadCorpus(wikiDir) {
299
344
  failuresTotal: failures.length + walked.statFailures,
300
345
  failures: failures.slice(0, MAX_FAILURE_DETAILS),
301
346
  scannedMs: Date.now() - startedAt,
347
+ // 「这次到底读到了什么、什么时候读的」—— 覆盖诊断要的不只是页数。
348
+ // 小节数决定「能定位到多细」,字节数决定「扫的是一手正文还是空壳」。
349
+ sections: pages.reduce((sum, page) => sum + (Array.isArray(page.sections) ? page.sections.length : 0), 0),
350
+ bytes: pages.reduce((sum, page) => sum + (typeof page.bytes === 'number' ? page.bytes : 0), 0),
351
+ newestMtime: newestIso(pages),
352
+ oldestMtime: oldestIso(pages),
353
+ scannedAt: new Date().toISOString(),
302
354
  wikiDir,
303
355
  }
304
356
 
package/lib/engine.js CHANGED
@@ -67,26 +67,73 @@ function countOccurrences(haystack, needle) {
67
67
  * 常含正文里不出现的说法(例如「上下文怎么管」这类口语),不加就搜不到。
68
68
  */
69
69
  function termScore(page, token) {
70
+ return termBreakdown(page, token).score
71
+ }
72
+
73
+ /**
74
+ * 单个检索词对单个页面的贡献**明细**:每条通道各给了多少分。
75
+ *
76
+ * termScore 就是把它求和 —— 只有一个实现,所以「面板上显示的理由」与
77
+ * 「排序用的分数」不可能对不上。explain 只是把已经在算的数摊开,不是第二条路径。
78
+ */
79
+ function termBreakdown(page, token) {
70
80
  const name = page.name.toLowerCase()
71
81
  const term = token.toLowerCase()
82
+ const parts = []
72
83
  let score = 0
73
- if (name === term) score += 120
74
- else if (name.includes(term)) score += 60
84
+
85
+ if (name === term) {
86
+ parts.push({ via: 'name', score: 120 })
87
+ score += 120
88
+ } else if (name.includes(term)) {
89
+ parts.push({ via: 'name', score: 60 })
90
+ score += 60
91
+ }
75
92
 
76
93
  for (const alias of asList(page.fields['别名'])) {
77
94
  if (alias.toLowerCase().includes(term)) {
95
+ parts.push({ via: 'alias', score: 50 })
78
96
  score += 50
79
97
  break
80
98
  }
81
99
  }
82
100
  for (const tag of asList(page.fields['标签'])) {
83
101
  if (tag.toLowerCase().includes(term)) {
102
+ parts.push({ via: 'tag', score: 25 })
84
103
  score += 25
85
104
  break
86
105
  }
87
106
  }
88
- score += Math.min(countOccurrences(page.body, term), 12) * 3
89
- return score
107
+
108
+ const count = countOccurrences(page.body, term)
109
+ const bodyScore = Math.min(count, 12) * 3
110
+ if (bodyScore > 0) {
111
+ parts.push({ via: 'body', score: bodyScore, count })
112
+ score += bodyScore
113
+ }
114
+ return { score, parts, count }
115
+ }
116
+
117
+ /**
118
+ * explain 用:每个检索词在这页上「凭什么得分」,没得分也留一条,好让面板看出是哪个词掉了。
119
+ * index 通道同样按「只补漏」的规则在这里补记 —— 与 search() 里的判定条件一字不差。
120
+ */
121
+ function explainTerms(page, indexLine, tokens) {
122
+ return tokens.map((token) => {
123
+ const breakdown = termBreakdown(page, token)
124
+ if (breakdown.score > 0) {
125
+ return {
126
+ term: token,
127
+ score: breakdown.score,
128
+ count: breakdown.count,
129
+ parts: breakdown.parts,
130
+ }
131
+ }
132
+ if (indexLine !== null && indexLine.summary.toLowerCase().includes(token.toLowerCase())) {
133
+ return { term: token, score: INDEX_ONLY_SCORE, count: 0, parts: [{ via: 'index', score: INDEX_ONLY_SCORE }] }
134
+ }
135
+ return { term: token, score: 0, count: 0, parts: [] }
136
+ })
90
137
  }
91
138
 
92
139
  /**
@@ -260,8 +307,14 @@ export function search(corpus, query, options = {}) {
260
307
  const sectionChars = intOption(options, 'sectionChars', DEFAULT_SECTION_CHARS, 120, 3000)
261
308
  const typeFilter = typeof options.type === 'string' && options.type.trim() !== '' ? options.type.trim() : null
262
309
  const tagFilter = asList(options.tags)
310
+ // explain 只多带「这分怎么来的」,不参与打分与排序;工具 schema 里没有这个开关,
311
+ // 它只给设置页/侧栏那份只读 API 用,模型看不到也多不出 token。
312
+ const explain = options.explain === true
263
313
 
264
314
  const scored = []
315
+ // 每个词在多少页上真正拿到分 —— 用来回答「这个词到底有没有用上」,
316
+ // 以及「没命中的是词太少,还是库没写到」。
317
+ const termPages = new Map(tokens.map((token) => [token, 0]))
265
318
  // 分母要分开记:扫描了多少页、过滤后真正参与打分的多少页、命中的多少页、最后返回多少条。
266
319
  // 只报一个「扫描 90 页,12 命中」,读起来像 90 页都比过了。
267
320
  let considered = 0
@@ -282,7 +335,10 @@ export function search(corpus, query, options = {}) {
282
335
  score = INDEX_ONLY_SCORE
283
336
  }
284
337
  total += score
285
- if (score > 0) matched += 1
338
+ if (score > 0) {
339
+ matched += 1
340
+ termPages.set(token, termPages.get(token) + 1)
341
+ }
286
342
  }
287
343
  if (matched === 0) continue
288
344
  scored.push({ page, indexLine, score: total, matched, allTerms: matched === tokens.length })
@@ -322,6 +378,7 @@ export function search(corpus, query, options = {}) {
322
378
  citation: `← [[${item.page.name}]]${section.title === '' ? '' : ` §${section.title}`} → ${item.page.file}`,
323
379
  brokenLinks: broken,
324
380
  file: item.page.file,
381
+ ...(explain ? { termHits: explainTerms(item.page, item.indexLine, tokens) } : {}),
325
382
  }
326
383
  })
327
384
 
@@ -331,6 +388,13 @@ export function search(corpus, query, options = {}) {
331
388
  mode: 'search',
332
389
  query,
333
390
  tokens,
391
+ // 查询诊断:引擎实际拿哪几个词去找的、哪几个词一页都没沾到、用的是 AND 还是 OR。
392
+ // 这三件事决定「结果为空」该怪词、怪库,还是怪匹配模式。
393
+ // missedTerms / matchMode 常驻(模型看到「这个词没用上」才可能换词重查,成本两个短字段);
394
+ // 每个词在多少页上得分的明细只有 explain 时才给,那是面板的事。
395
+ missedTerms: tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
396
+ matchMode: degraded ? 'or' : 'and',
397
+ ...(explain ? { termPages: tokens.map((token) => ({ term: token, pages: termPages.get(token) ?? 0 })) } : {}),
334
398
  total: list.length,
335
399
  degraded,
336
400
  // 调用级统计:分母各是各的,别合成一个数字
@@ -546,6 +610,29 @@ export function getLocalDate(date = new Date()) {
546
610
  return `${year}-${month}-${day}`
547
611
  }
548
612
 
613
+ /**
614
+ * 「更新」字段 → 模型能用的判断。
615
+ *
616
+ * 只写一个 2025-03-14,模型没法判断该不该信:三年前的结论和上周的结论长得一样。
617
+ * 所以补上距今天数,超过半年直接说「可能已过时」。
618
+ * 这个信息 compareHits 一直在用(排序第五级就是 updated),但从来没渲染出去 ——
619
+ * 排了序、却不告诉模型为什么这么排。
620
+ */
621
+ export function freshnessOf(updated, now = Date.now()) {
622
+ const text = String(updated ?? '').trim()
623
+ const match = text.match(/^(\d{4})-(\d{1,2})-(\d{1,2})/)
624
+ if (!match) return text
625
+ const stamp = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3])).getTime()
626
+ if (!Number.isFinite(stamp)) return text
627
+ const days = Math.floor((now - stamp) / 86400000)
628
+ if (!Number.isFinite(days) || days < 0) return text // 未来日期不解释,原样输出
629
+ if (days === 0) return `${text}(今天更新)`
630
+ if (days === 1) return `${text}(昨天更新)`
631
+ if (days < 31) return `${text}(${days} 天前)`
632
+ if (days <= 180) return `${text}(${Math.floor(days / 30)} 个月前)`
633
+ return `${text}(${Math.floor(days / 30)} 个月前,可能已过时)`
634
+ }
635
+
549
636
  /**
550
637
  * 日志事件类型:不强制枚举(query / ingest / 拍板 / 结构补齐…本来该由调用方表达),
551
638
  * 只挡住会破坏 `## [日期] 类型 | 标题` 这一行结构的东西。
@@ -769,7 +856,78 @@ function bigramSimilarity(a, b) {
769
856
 
770
857
  /* ----------------------- 调用级:参数校验、状态与警告 ----------------------- */
771
858
 
772
- export const MODES = ['search', 'page', 'list', 'overview', 'lint', 'draft']
859
+ /**
860
+ * help:把「这个工具怎么用」做成可查的内容。
861
+ *
862
+ * 工具描述是每回合都要付的固定成本,机制文档只在模型真的要问时付一次。
863
+ * 而且描述写不全、写多了都一样有害:写不全模型猜错模式,写太满挤占别的东西。
864
+ * 这里的内容只讲「怎么用」,不讲这个库有什么 —— 后者是 overview 的事。
865
+ */
866
+ export function help() {
867
+ return {
868
+ mode: 'help',
869
+ sections: [
870
+ {
871
+ title: '它是什么',
872
+ lines: [
873
+ '一个只读的本地知识库检索器:给关键词,返回库里最相关的几页,附命中小节正文与出处。',
874
+ '不改文件、不联网、不生成内容。要写新页先用 mode:"draft" 拿骨架,再自己落盘。',
875
+ ],
876
+ },
877
+ {
878
+ title: '七个 mode',
879
+ lines: [
880
+ 'help:就是这份说明。不确定用哪个 mode、或看不懂某个 status 时先查它 —— 它不读库,不会失败。',
881
+ 'search(默认):1-4 个核心名词,空格分隔做 AND。返回元数据 + index 摘要 + 命中小节正文 + 出处,通常一次就够作答。',
882
+ 'page:传页名取整页;没精确命中会给 5 个候选。',
883
+ 'list:按 type / tags / status 列目录,比读 index.md 省 token。',
884
+ 'overview:总览正文 + 规模 + 最近日志 + 断链统计。',
885
+ 'lint:全库健康检查 —— 孤儿页、断链、缺字段、别名冲突、久未更新、草稿、index 与磁盘不一致。',
886
+ 'draft:给一份落盘骨架(目录、frontmatter、index 那行、log 那条),只返回文本。',
887
+ ],
888
+ },
889
+ {
890
+ title: 'status 怎么读',
891
+ lines: [
892
+ 'ok:正常,内容可信。',
893
+ 'degraded:只有部分检索词命中,已降级成 OR —— 命中面变宽、精度下降,答案要点可能偏。',
894
+ 'partial:看到的不全(有页读不出来 / 目录列不出 / 超大页没参与 / 有同名页)。warnings 说漏了什么。',
895
+ 'no_match:参与比对的页里没有命中。**不能反推全库没有**,换词组或 list 看命名习惯。',
896
+ 'unavailable:库一页都没扫到,通常是路径指错层 —— 该去查配置,不是换关键词。',
897
+ 'invalid_input:参数写错了(空 query、缺 name)。按提示补参数重试,别当成「库里没有」。',
898
+ ],
899
+ },
900
+ {
901
+ title: '输出里的字段',
902
+ lines: [
903
+ 'kind=note 是消化过的笔记(最可信);raw-summary 是原始资料压缩稿;source 是资料页。',
904
+ 'sources 是来源数量,判断证据强度用:1 份和 12 份不是一回事。',
905
+ '更新 后面括号是距今天数;标「可能已过时」的页,引用时要说明时间。',
906
+ '断链 / brokenLinks 非空 = 那处引用了库里不存在的页,说明该判断缺少页级支撑。',
907
+ '§小节 是命中的具体小节,引用时可以指到这个粒度。',
908
+ ],
909
+ },
910
+ {
911
+ title: '参数',
912
+ lines: [
913
+ 'limit:search 返回几页,默认 5、最多 12;lint 时是每组列几条,默认 8。',
914
+ 'sectionChars:search 每页正文上限,默认 900;需要完整段落时调到 1500-2000。',
915
+ 'pageChars:page 正文上限,默认 6000;overview 引用总览时默认 4000。',
916
+ 'staleDays:lint 判「久未更新」的天数,默认 120。',
917
+ ],
918
+ },
919
+ {
920
+ title: '不该用它的时候',
921
+ lines: [
922
+ '纯通用常识、且能从库索引线索确认没有对应内容 —— 查了只会拿到不相干的页。',
923
+ '但你「没看到线索」不等于库里没有:不确定就查一次,一次检索比一个错的结论便宜。',
924
+ ],
925
+ },
926
+ ],
927
+ }
928
+ }
929
+
930
+ export const MODES = ['search', 'page', 'list', 'overview', 'lint', 'draft', 'help']
773
931
 
774
932
  /**
775
933
  * 参数校验:必须在碰语料之前跑完。
@@ -800,6 +958,8 @@ const toCount = (value, fallback = 0) => (Number.isFinite(value) ? value : fallb
800
958
  * status 编码「模型该做什么」,warnings 编码「为什么」,两者都不承担修改结果的责任。
801
959
  */
802
960
  export function decideStatus(corpus, mode, args = {}, result = {}) {
961
+ // help 不碰语料:不该因为「库读不出来」被降级成 partial —— 说明文档和库的状态无关
962
+ if (mode === 'help') return { status: 'ok', warnings: [] }
803
963
  const stats = (corpus && corpus.stats) || {}
804
964
  const pages = toCount(stats.pages)
805
965
  const discovered = toCount(stats.discovered, pages)
@@ -844,6 +1004,10 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
844
1004
 
845
1005
  const coverageLost = unreadable > 0 || walkFailures > 0 || statFailures > 0
846
1006
 
1007
+ // 同名页:byName 是 Map,后扫到的覆盖先扫到的,page 会静默返回其中一篇。
1008
+ // 这是最难自查的一类错 —— 状态是 ok、正文有内容、引用也写得出来,只是可能引错了版本。
1009
+ const dupWarning = duplicatePageWarning(stats, mode, result)
1010
+
847
1011
  // 空结果按 mode 各取各的字段,不为「统一」虚构字段
848
1012
  const empty =
849
1013
  mode === 'search' ? (result.hits ?? []).length === 0
@@ -868,12 +1032,20 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
868
1032
  : `扫描到 ${discovered} 个文件,但没有一个算作页面(只有 index/log,或被规则跳过)`)
869
1033
  return { status: 'unavailable', warnings }
870
1034
  }
871
- if (coverageLost) return { status: 'partial', warnings }
1035
+ if (coverageLost) {
1036
+ if (dupWarning) warnings.push(dupWarning)
1037
+ return { status: 'partial', warnings }
1038
+ }
1039
+ if (dupWarning) {
1040
+ // 覆盖没丢,但「拿到的是不是那一篇」不确定:失败模式是引错版本,同样配 partial。
1041
+ warnings.push(dupWarning)
1042
+ return { status: 'partial', warnings }
1043
+ }
872
1044
  if (mode === 'search' && result.degraded === true) {
873
1045
  // 降级与「超大页可能相关」可以同时成立:状态按约定取 degraded,但两条事实都要输出 ——
874
1046
  // 别让一个状态值把覆盖缺口吞掉。
875
1047
  if (oversizedHit) warnings.push(oversizedWarning)
876
- warnings.push('只命中部分检索词,已降级为 OR:命中面变宽,精度下降')
1048
+ warnings.push('只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
877
1049
  return { status: 'degraded', warnings }
878
1050
  }
879
1051
  if (oversizedHit) {
@@ -891,6 +1063,22 @@ function viaText(via) {
891
1063
  return '标题或 index 摘要命中查询词'
892
1064
  }
893
1065
 
1066
+ /**
1067
+ * 同名页提示:byName 只留最后一个,page 命中的可能不是模型以为的那一页。
1068
+ * 返回空串表示这次没有这个风险(别的 mode、没取到页、名字唯一)。
1069
+ */
1070
+ function duplicatePageWarning(stats, mode, result) {
1071
+ if (mode !== 'page') return ''
1072
+ const found = result && result.found
1073
+ if (!found || !found.name) return ''
1074
+ const dups = Array.isArray(stats.duplicateNames) ? stats.duplicateNames : []
1075
+ const same = dups.filter((item) => item.name === found.name)
1076
+ if (same.length < 2) return ''
1077
+ const others = same.map((item) => item.file).filter((file) => file && file !== found.file)
1078
+ const rest = others.length > 0 ? `;另外还有 ${others.join('、')}` : ''
1079
+ return `库里有 ${same.length} 篇同名页「${found.name}」,这次返回的是 ${found.file}${rest} —— 引用前请确认是哪一篇,或先把同名页改名`
1080
+ }
1081
+
894
1082
  /** 统一入口:工具只暴露一个函数,六个 mode 分派到这里。 */
895
1083
  export function run(corpus, args = {}) {
896
1084
  const mode = typeof args.mode === 'string' && args.mode.trim() !== '' ? args.mode.trim() : 'search'
@@ -929,6 +1117,9 @@ export function run(corpus, args = {}) {
929
1117
  case 'draft':
930
1118
  result = draft(corpus, args)
931
1119
  break
1120
+ case 'help':
1121
+ result = help()
1122
+ break
932
1123
  }
933
1124
 
934
1125
  const verdict = decideStatus(corpus, mode, args, result)