dsh-wiki-notes 1.1.3 → 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
@@ -211,6 +211,19 @@ export function extractLinks(text) {
211
211
  * 扫描整个 wiki 层。
212
212
  * 返回 { wikiDir, pages, byName, byAlias, indexLines, scaleLine, log, brokenLinks, stats }
213
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
+
214
227
  export async function loadCorpus(wikiDir) {
215
228
  const startedAt = Date.now()
216
229
  const walked = await walkMarkdown(wikiDir)
@@ -331,6 +344,13 @@ export async function loadCorpus(wikiDir) {
331
344
  failuresTotal: failures.length + walked.statFailures,
332
345
  failures: failures.slice(0, MAX_FAILURE_DETAILS),
333
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(),
334
354
  wikiDir,
335
355
  }
336
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
  // 调用级统计:分母各是各的,别合成一个数字
package/lib/index.js CHANGED
@@ -8,8 +8,10 @@
8
8
  * 沙箱策略拦一道;这里只需要「读一个用户明确授权的目录」,用 node:fs 更直接,
9
9
  * 而且这一步只在扫描时发生,不涉及任何写操作。
10
10
  *
11
- * 只读承诺:除了插件目录旁那一个 wiki-notes.config.json(设置页保存库路径用),
12
- * 这里不写任何文件,更不写知识库本体。
11
+ * 只读承诺:知识库本体一个字节都不写。会写盘的只有插件目录旁这两个文件——
12
+ * wiki-notes.config.json(设置页保存库路径与提示词配置)、lint-history.json
13
+ * (lint 的上一轮问题键,只用来算「新增 / 已修」)。而且只在用户点了保存、
14
+ * 或模型真的跑了 lint 时才写,检索路径全程不落盘。
13
15
  */
14
16
 
15
17
  import path from 'node:path'
@@ -32,6 +34,16 @@ const CACHE_TTL_MS = 30_000
32
34
  /** 设置页的同源 API 前缀(浏览器半侧 lib/client.js 里写的是同一个值)。 */
33
35
  const API_PREFIX = '/api/wiki-notes'
34
36
 
37
+ /** 面板里一次输入的查询长度上限:超过这个长度不是检索,是粘贴事故。 */
38
+ const MAX_QUERY_CHARS = 200
39
+
40
+ /** 面板显示几条:引擎自己封顶 12(那是给模型的 token 预算),面板取更小的默认值。 */
41
+ function clampLimit(raw) {
42
+ const value = Number.parseInt(String(raw ?? ''), 10)
43
+ if (!Number.isFinite(value)) return 5
44
+ return Math.min(Math.max(value, 1), 12)
45
+ }
46
+
35
47
  /**
36
48
  * 工具泛词:它们能出现在任何一页上,对「这个库在研究什么」没有信息量。
37
49
  * 命中就跳过,不进主题词候选(打标签不受影响,检索打分照旧用它们)。
@@ -438,10 +450,13 @@ export function apply(ctx, config = {}) {
438
450
  }
439
451
 
440
452
  // 启动时探一次库:路径写错的话,日志里会立刻出现,而不是等模型调用时才失败。
453
+ // 顺带把「重启后第一次扫描」提前到没人等的时候做 —— 实测冷盘要 5s 上下(一次真实重启后
454
+ // 5,217ms,第二次 29ms),这段延迟不该落在用户的第一句提问上。
455
+ const warmStarted = Date.now()
441
456
  getCorpus()
442
457
  .then((corpus) => {
443
458
  ctx.logger?.info?.(
444
- `LLM-Wiki 检索就绪:${corpus.stats.pages} 页 / ${corpus.stats.resources} 份资料 / ${corpus.stats.brokenPages} 页存在红链(${root})`,
459
+ `LLM-Wiki 检索就绪:${corpus.stats.pages} 页 / ${corpus.stats.resources} 份资料 / ${corpus.stats.brokenPages} 页存在红链(${root},首次扫描 ${Date.now() - warmStarted} ms)`,
445
460
  )
446
461
  })
447
462
  .catch((error) => {
@@ -459,6 +474,19 @@ export function apply(ctx, config = {}) {
459
474
  brokenPages: stats.brokenPages ?? 0,
460
475
  brokenTotal: stats.brokenTotal ?? 0,
461
476
  scannedMs: stats.scannedMs ?? 0,
477
+ // 覆盖诊断:分母各是各的,别让人对着「95 页」猜漏了什么。
478
+ // discovered = pages + unreadable + skipped(文件级恒等式);walkFailures 是目录数,另算。
479
+ discovered: stats.discovered ?? 0,
480
+ skipped: stats.skipped ?? 0,
481
+ unreadable: stats.unreadable ?? 0,
482
+ oversized: stats.oversized ?? 0,
483
+ walkFailures: stats.walkFailures ?? 0,
484
+ statFailures: stats.statFailures ?? 0,
485
+ sections: stats.sections ?? 0,
486
+ bytes: stats.bytes ?? 0,
487
+ newestMtime: stats.newestMtime ?? '',
488
+ oldestMtime: stats.oldestMtime ?? '',
489
+ scannedAt: stats.scannedAt ?? '',
462
490
  }
463
491
  }
464
492
 
@@ -534,6 +562,30 @@ export function apply(ctx, config = {}) {
534
562
  if (route === '/state' && req.method === 'GET') {
535
563
  return sendJson(res, 200, await buildState())
536
564
  }
565
+ // 面板专用只读查询:和模型调 wiki_recall 走同一个 run(),所以「人看到的」
566
+ // 就是「模型拿到的」——这正是这个面板存在的理由,另写一套轻量检索就白做了。
567
+ // explain 只在服务端打开;工具 schema 里没有这个参数,模型触发不到。
568
+ if (route === '/search' && req.method === 'GET') {
569
+ const parsed = new URL(req.url ?? '/', 'http://127.0.0.1')
570
+ const query = (parsed.searchParams.get('q') ?? '').trim().slice(0, MAX_QUERY_CHARS)
571
+ // 空查询不当作错误让面板弹红字:面板要显示的是「库现在什么样」,那是 /state 的事。
572
+ if (query === '') return sendJson(res, 400, { error: '缺少 q 参数(要查什么)' })
573
+ const started = Date.now()
574
+ const corpus = await getCorpus()
575
+ const result = run(corpus, {
576
+ mode: 'search',
577
+ query,
578
+ limit: clampLimit(parsed.searchParams.get('limit')),
579
+ explain: true,
580
+ })
581
+ return sendJson(res, 200, {
582
+ ...result,
583
+ // 面板要的分母:扫了多少页、扫描本身花了多久、这次查询花了多久
584
+ scanned: corpus.stats?.pages ?? 0,
585
+ scannedMs: corpus.stats?.scannedMs ?? 0,
586
+ elapsedMs: Date.now() - started,
587
+ })
588
+ }
537
589
  if (route === '/check' && req.method === 'POST') {
538
590
  const body = await readBody(req)
539
591
  return sendJson(res, 200, await probeRoot(body?.root))
@@ -907,6 +959,11 @@ function renderSearch(value) {
907
959
  `${Number.isFinite(value.allTerms) ? `(全词 ${value.allTerms})` : ''}· 返回 ${value.returned ?? 0}`
908
960
  : `扫描 ${scanned} 页,${value.total} 命中`
909
961
  out.push(`【检索】${tokens} ${numbers}`)
962
+ // 「没沾到」是给模型看的换词依据:面板上能点出来,模型看不到就等于白算。
963
+ // 它和 degraded 说的不是一件事:degraded 是「一条全词命中都没有」,
964
+ // 这里是「这个具体的词在库里一页都没沾到」—— 后者才指着该换哪个词。
965
+ const missed = Array.isArray(value.missedTerms) ? value.missedTerms : []
966
+ if (missed.length > 0) out.push(`没沾到:${missed.join('、')}(这些词在库里一页都没命中,换同义词或干脆去掉)`)
910
967
  // 降级说明已由 warnings 承载(degraded 时必有一条);只有老调用方(结果里没有 status 字段)
911
968
  // 才需要这里的 note —— 否则同一句话模型会读两遍。
912
969
  if (value.note && value.status === undefined) out.push(`⚠️ ${value.note}`)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-wiki-notes",
3
- "version": "1.1.3",
3
+ "version": "1.3.0",
4
4
  "type": "module",
5
5
  "description": "Read-only Markdown knowledge-base retrieval for DeepSeek Harness: one wiki_recall tool (search/page/list/overview/lint/draft) returning the matching section's full text with page-level citations. 中文:本地 Markdown 笔记库检索插件,一次调用返回命中小节正文与出处,另带健康检查与回写骨架。",
6
6
  "keywords": [
@@ -37,7 +37,7 @@
37
37
  "node": ">=20.13.0"
38
38
  },
39
39
  "scripts": {
40
- "test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/watch.mjs && node tests/client.mjs",
40
+ "test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/watch.mjs && node tests/client.mjs",
41
41
  "cli": "node bin/cli.mjs",
42
42
  "probe": "node tools/probe.mjs"
43
43
  },