dsh-knit 0.21.0 → 0.22.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/src/host/index.js CHANGED
@@ -15,20 +15,26 @@
15
15
  */
16
16
  import { readFile, readdir, stat } from 'node:fs/promises'
17
17
  import { createReadStream, realpathSync, statSync } from 'node:fs'
18
- import { join, relative, resolve, sep } from 'node:path'
18
+ import { dirname, join, relative, resolve, sep } from 'node:path'
19
19
  import { homedir } from 'node:os'
20
20
  import { extractKeywords, rankByRelevance, topicLabel } from './relevance.js'
21
21
  import { registerKnitDocsTool } from './tool.js'
22
22
  // v0.12:引用关系。`links.js` **不反过来 import 本文件**(依赖由这里注入),所以没有环。
23
- import { buildLinkGraph, linksOf } from './links.js'
24
- // v0.21:关系事实表(谁提到谁)。**同步、零 I/O** —— 只吃记录上现成的 `head`。
25
- import { buildRelationFacts } from './relations.js'
23
+ // v0.22 修法 ①:这里多用了一个 `extractRefsWithLines` —— 它把「抽取引用」这件事
24
+ // 从「每次装配上下文的消费者各抽一遍」提前到「读盘那一次抽一遍,结果进索引」。
25
+ import { buildLinkGraph, extractRefsWithLines, linksOf } from './links.js'
26
+ // v0.21:关系事实表(谁提到谁)。**同步、零 I/O** —— 只吃记录上现成的 `refs` / `head`。
27
+ // v0.22 修法 ①:`importsOf` 同样提前到读盘时执行,结果进索引的 `refs.imports`。
28
+ import { buildRelationFacts, importsOf } from './relations.js'
26
29
  // v0.21:上下文控制层(固定 / 排除)。**纯逻辑 + 可选持久化**:本文件负责把
27
30
  // `ctx.storage`(拿得到才有)递给它,它自己不 import 任何官方包。
28
31
  import {
29
32
  createControlRegistry, applyPinOverride, excludedSet, sharedControlRegistry,
30
33
  CONTROL_ACTIONS,
31
34
  } from './control.js'
35
+ // v0.22:增量上下文索引的持久层。**不参与排序、不缓存正文** —— 它只回答
36
+ // 「这个文件的头部指纹和上次一样吗」。存储拿不到时它自己降级成空 Map。
37
+ import { sharedIndexStore, headHashOf, refsShapeOk } from './index-store.js'
32
38
  // v0.14:上下文装配。同样由这里注入依赖(`list` / `read`),保持纯函数可单测。
33
39
  // ⚠️ 这里**只 import `buildContext`**:Context Pack 的文本渲染只在 `tool.js` 的
34
40
  // `renderToolText()` 里发生(模型看到的是那段文本,不是结构化 JSON)。曾经多导出一个
@@ -212,6 +218,63 @@ const cache = new Map()
212
218
  /** 缓存里正文的总字节数(配合 `MAX_CACHE_BYTES` 淘汰)。 */
213
219
  let cacheBodyBytes = 0
214
220
 
221
+ /* ── v0.22 增量索引 ────────────────────────────────────────────────
222
+ *
223
+ * 审计结论(`Knit-v0.22-Phase0-审计.md` §2):上面的 `cache` 已经兑现了「未变化文件不
224
+ * 重读、不重解析」和「改一个文件只重处理该文件」—— 暖扫 `readFile = 0`。它**缺**的是
225
+ * 跨进程:进程一没,缓存即空,重启后第一次扫描要把 700 个文件全部重读重解析。
226
+ *
227
+ * 所以这一版**不动检索算法**,只在 `cache` 外围加两件事:
228
+ * 1. 持久层 `indexStore`(`index-store.js`):把每个文件的内容指纹与派生的标题/摘要
229
+ * 存进 DSH 自己的存储,让**重启后**能跳过读盘与解析;
230
+ * 2. 目录级 memo `dirMemo`:目录 mtime 未变就跳过 `readdir`(实测暖扫耗时**全部**是
231
+ * `readdir + stat`,而 `collectDocs` 占扫描总耗时 104%–122%)。
232
+ *
233
+ * ⚠️ 三条不许破的边界:
234
+ * · `mtimeMs + size` **不是**唯一证据 —— 必须再核 `headHash`(提示词 §4)。
235
+ * · 树绝不因为「维护缓存」而遍历两遍 —— 目录 memo 只省 `readdir`,不改遍历顺序,
236
+ * `MAX_DIRS` / `MAX_DEPTH` / `SCAN_BUDGET_MS` 的作用范围一字不动。
237
+ * · 索引里**没有正文**(裁决 A)⇒ 正文永远来自当次读取,不可能陈旧。
238
+ */
239
+
240
+ /** 进程内的增量索引 store(`apply()` 拿到 `ctx.storage` 时换成持久化的那份)。 */
241
+ let indexRegistry = null
242
+
243
+ /**
244
+ * 一轮扫描里「核过指纹的」记录数上限。
245
+ *
246
+ * 提示词 §5⑤ 要求「reconciliation 只读取变化项,必要时**分批**执行避免阻塞主交互」。
247
+ * 这个数字就是「分批」的粒度:坏掉的第一条会被立刻重读,其余未变化条目每轮抽查这么多,
248
+ * 于是整个工作区在一段窗口内被核完,而单轮扫描的额外读盘有界。
249
+ */
250
+ const INDEX_VERIFY_PER_PASS = 8
251
+
252
+ /**
253
+ * 本轮生效的抽验预算(默认 `INDEX_VERIFY_PER_PASS`)。
254
+ *
255
+ * 它可调,只为一件事:**证伪**。把预算设成 0,对账一次都不跑 ⇒ 「靠索引复用之后
256
+ * 没人核指纹」这件事必须能被测试抓出来(提示词 §18:新增守卫必须能够证伪)。
257
+ * 生产路径没有任何地方改它。
258
+ */
259
+ let indexVerifyBudget = INDEX_VERIFY_PER_PASS
260
+
261
+ /** 目录 → `{mtimeMs, md, code, media, dead, stats}`;目录 mtime 未变则跳过 `readdir`。 */
262
+ const dirMemo = new Map()
263
+
264
+ /** 已装载持久索引的工作区根 → `Map<rel, 记录>`(值只在扫描时读,不长期留存)。 */
265
+ const indexRels = new Map()
266
+
267
+ /** 已核过指纹的记录(`${hostRoot}\u0000${rel}`)—— 抽验是「没核过的优先」。 */
268
+ const indexVerified = new Set()
269
+
270
+ /** 抽验游标(每个 hostRoot 一个)—— 保证「分批」是轮转的,不是每次盯前几条。 */
271
+ const indexVerifyCursor = new Map()
272
+
273
+ /** 每个 hostRoot 最近一轮扫描被解析过的记录数(基准脚本用它断言「只重处理变化的文件」)。 */
274
+ const indexStats = new Map()
275
+
276
+ /* ── /v0.22 ──────────────────────────────────────────────────────── */
277
+
215
278
  /**
216
279
  * 写缓存并做容量淘汰(v0.20)。
217
280
  *
@@ -318,22 +381,87 @@ export function parseMarkdown(head, fileName) {
318
381
  }
319
382
 
320
383
  /**
321
- * 读一个 Markdown 文件的元信息,命中缓存则跳过读盘。
322
- * @param {string} absPath - 绝对路径
323
- * @returns {Promise<object|null>} 解析结果(含小写 haystack 与原文首部 head),读失败返回 null
384
+ * 从**已在内存里的首部**抽出索引要存的引用/导入列表(v0.22 修法 ①)。
385
+ *
386
+ * 为什么提前到这里做:引用图(`buildLinkGraph()`)与关系投影(`buildRelationFacts()`)
387
+ * 各自都要「原首部 → 候选引用」,而它们**互相不知道对方也抽过一遍**。把这一遍放进
388
+ * 读盘那一刻,结果同时进内存条目与索引记录,于是:进程内两个消费者各取所需、
389
+ * 重启后从索引直接取 —— 抽取次数从「每个消费者每轮一次」降到「每个文件每次读盘一次」。
390
+ *
391
+ * ⚠️ 两套 Markdown 口径都算、都存(见 `index-store.js` 模块头第 1 条):
392
+ * `md` = `extractRefs()` 的默认口径(只认 `.md` 目标,引用图用),
393
+ * `any` = `anyExt: true`(还认 md→代码,关系投影用)。**不能只存一套再过滤** ——
394
+ * 两者各有自己的 `MAX_REFS_PER_DOC = 500` 截断点,近似会在引用极多的文件上改变目标集合。
395
+ *
396
+ * @param {string} head - 文件首部(已在内存里)
397
+ * @param {boolean} isCode - 代码走 `importsOf()`,Markdown 走引用抽取
398
+ * @returns {{md?: Array<object>, any?: Array<object>, imports?: Array<object>}} 抽取结果
324
399
  */
325
- async function readDoc(absPath) {
326
- let st
327
- try {
328
- st = await stat(absPath)
329
- } catch {
330
- return null
400
+ function refsForHead(head, isCode) {
401
+ const text = typeof head === 'string' ? head : ''
402
+ if (isCode) return { imports: importsOf(text) }
403
+ return {
404
+ md: extractRefsWithLines(text),
405
+ any: extractRefsWithLines(text, { anyExt: true }),
331
406
  }
332
- if (!st.isFile()) return null
407
+ }
333
408
 
334
- const hit = cache.get(absPath)
335
- if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit
409
+ /**
410
+ * v0.22:一份**完整的**索引记录 → `readDoc()` 形状的缓存条目。
411
+ *
412
+ * 「索引里存了什么」与「条目里能还原什么」是同一件事,这里就把它写死:
413
+ *
414
+ * · `title` / `summary` / `refs` → 索引里各存一份(`refs` = 抽取后的引用/导入列表,见修法 ①)。
415
+ * · `body`(整篇正文)→ **索引里没有,也永远不会有**。调用方(`readDoc`)因此
416
+ * 只在「这一轮不需要正文」时用这份还原结果(时间序扫描),相关检索仍然读盘。
417
+ * 这条分工就是裁决 A 的落实:正文不可能陈旧。
418
+ *
419
+ * ⚠️ 字段必须与 `readDoc()` 里的条目**逐字对齐**。少一个 `hayBody`,相关检索就会
420
+ * 在「条目看起来命中缓存」与「打分读到 undefined」之间产生静默的空结果。
421
+ *
422
+ * @param {object} record - 索引记录
423
+ * @returns {object} 缓存条目形状(`body` 为空串)
424
+ */
425
+ function restoreFromIndex(record) {
426
+ return {
427
+ mtimeMs: record.mtimeMs,
428
+ size: record.size,
429
+ headHash: record.headHash,
430
+ title: record.title,
431
+ summary: record.summary,
432
+ // v0.22 修法 ①:索引里**没有原文首部**,只有抽取结果。所以还原出来的条目
433
+ // `head` 是空串、`refs` 带着关系投影与引用图需要的一切。谁要是还从 `head`
434
+ // 读内容,重启后就会**静默**拿到空串 —— 两个消费者因此都优先读 `refs`。
435
+ head: '',
436
+ refs: record.refs,
437
+ body: '',
438
+ bodyBytes: 0,
439
+ bodyTruncated: false,
440
+ // v0.22:还原出来的条目**没有正文**。`hydrateBodies()` 靠这一位决定补不补,
441
+ // 相关检索因此不会拿到一份「看着像命中、其实是空串」的正文去打分。
442
+ bodyReady: false,
443
+ hayTitle: String(record.title).toLowerCase(),
444
+ haySummary: String(record.summary).toLowerCase(),
445
+ hayBody: '',
446
+ }
447
+ }
336
448
 
449
+ /**
450
+ * `readDoc()` 的读盘那一半(v0.22 从原函数里原样拆出,逻辑一字未改)。
451
+ *
452
+ * ⚠️ v0.22 起这就是**唯一**的文档读取路径:原来那个「先查缓存再决定读不读」的包装
453
+ * 已经并进 `collectDocs()` 的逐条判定里(缓存 / 索引 / 重读三选一,见那里的注释)。
454
+ * 留两份判定只会漂移 —— 所以包装函数被删掉了,这里只负责「读 + 解析」。
455
+ *
456
+ * @param {string} absPath - 绝对路径
457
+ * @param {object} st - 已取得的 stat 结果
458
+ * @returns {Promise<object|null>} 解析结果,读失败返回 null
459
+ */
460
+ async function readDocFromDisk(absPath, st, options = {}) {
461
+ // v0.22 修法 ①:抽取结果可以不要。`hydrateBodies()` 补正文时条目上已经有
462
+ // 索引带来的 `refs`(同一份内容算出来的同一个结果),再抽一遍纯属白烧 CPU ——
463
+ // 实测在 16KB 首部的语料上是每文件两次正则扫描。
464
+ const wantRefs = options.refs !== false
337
465
  let head = ''
338
466
  let body = ''
339
467
  let bodyBytes = 0
@@ -358,8 +486,18 @@ async function readDoc(absPath) {
358
486
  size: st.size,
359
487
  title,
360
488
  summary,
489
+ // v0.22:内容指纹(对上面那段**已在内存里**的头部算,不额外读盘)。
490
+ // 它是「mtime+size 之外的第二道证据」—— 见 `Knit-决策记录.md` 裁决 A。
491
+ headHash: headHashOf(head),
492
+ // v0.22:正文已在手上(这条路径刚刚整读过)。
493
+ bodyReady: true,
494
+ // v0.22 修法 ①:抽取结果随读盘一起算出来 —— 进索引的就是它(原文首部不进索引)。
495
+ // `wantRefs: false` 是给「条目上已经有一份同一个内容算出来的 refs」的调用方用的
496
+ // (`hydrateBodies()` 补正文时就是这种情况),省掉每文件两次正则扫描。
497
+ ...(wantRefs ? { refs: refsForHead(head, false) } : {}),
361
498
  // ⚠️ 原文首部**留在缓存里**(v0.14):上下文装配要用它抽引用关系。
362
499
  // 它已经在内存里了 —— 再读一遍盘才是浪费。`publicDoc()` 不会把它发出去。
500
+ // 修法 ① 之后 `refs` 是首选、`head` 只是**同进程内的**兜底。
363
501
  head,
364
502
  // v0.20:正文(截到上限)也留在缓存里 —— 片段切分与全文打分的输入。
365
503
  // 语义上 `head` 是「首部」(引用关系用,16KB),`body` 是「全文」,
@@ -378,11 +516,11 @@ async function readDoc(absPath) {
378
516
  }
379
517
 
380
518
  /**
381
- * 读一个**代码文件**参与检索所需的头部(v0.19),命中缓存则跳过读盘。
519
+ * 读一个**代码文件**参与检索所需的头部(v0.19)。
382
520
  *
383
- * 与 `readDoc` 共用同一张 `cache`(键是绝对路径,一个路径只可能是文档或代码之一),
384
- * 并复用同一套 `haystack` 形状 —— 这正是「不给代码建第二套检索」在数据层面的落实:
385
- * `relevance.js` 一个字节都不用改,它看到的仍是它一直在看的 `{title, summary, body}`。
521
+ * 与 `readDocFromDisk()` 共用同一套 `haystack` 形状 —— 这正是「不给代码建第二套检索」
522
+ * 在数据层面的落实:`relevance.js` 一个字节都不用改,它看到的仍是它一直在看的
523
+ * `{title, summary, body}`。
386
524
  *
387
525
  * haystack 的字段语义在这里被**重新指派**(需求 §13:代码不复用 Markdown 的语义):
388
526
  *
@@ -393,22 +531,16 @@ async function readDoc(absPath) {
393
531
  * 于是 `FIELD_WEIGHTS` 现成的 4 / 2 / 1 恰好等于
394
532
  * 「filename × 4 / path × 2 / content × 1」,排序器零改动。
395
533
  *
534
+ * ⚠️ v0.22:这就是**唯一**的代码读取路径(原因同 `readDocFromDisk()`)。
535
+ * 它**必须**知道 `rel` —— haystack 的 `summary` 槽放的正是相对路径的目录部分。
536
+ *
396
537
  * @param {string} absPath - 绝对路径
397
538
  * @param {string} root - 工作区根
539
+ * @param {object} st - 已取得的 stat 结果
398
540
  * @returns {Promise<object|null>} 解析结果,读失败返回 null
399
541
  */
400
- async function readCode(absPath, root) {
401
- let st
402
- try {
403
- st = await stat(absPath)
404
- } catch {
405
- return null
406
- }
407
- if (!st.isFile()) return null
408
-
409
- const hit = cache.get(absPath)
410
- if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit
411
-
542
+ async function readCodeFromDisk(absPath, root, st, options = {}) {
543
+ const wantRefs = options.refs !== false
412
544
  let head = ''
413
545
  let body = ''
414
546
  let bodyBytes = 0
@@ -434,6 +566,11 @@ async function readCode(absPath, root) {
434
566
  const entry = {
435
567
  mtimeMs: st.mtimeMs,
436
568
  size: st.size,
569
+ // v0.22:内容指纹 + 「正文已在手上」,口径与 `readDocFromDisk` 一致。
570
+ headHash: headHashOf(head),
571
+ bodyReady: true,
572
+ // v0.22 修法 ①:代码侧抽的是 import 语句(`importsOf()` 的 `{spec, line}`)。
573
+ ...(wantRefs ? { refs: refsForHead(head, true) } : {}),
437
574
  head,
438
575
  body,
439
576
  bodyBytes,
@@ -453,7 +590,24 @@ async function readCode(absPath, root) {
453
590
  }
454
591
 
455
592
  /**
456
- * 广度优先扫出工作区里的文档、代码与媒体文件(v0.19)。
593
+ * `stat` 的「拿不到就是没有」版本(v0.22)。
594
+ *
595
+ * 目录 memo 的判据是目录 mtime,而 `stat` 失败(权限、刚被删)不是一个可以让扫描
596
+ * 崩掉的理由 —— 失败一律当 `null`,调用方据此走原路径重新 `readdir`。
597
+ *
598
+ * @param {string} path - 绝对路径
599
+ * @returns {Promise<object|null>} stat 结果或 null
600
+ */
601
+ async function statOrNull(path) {
602
+ try {
603
+ return await stat(path)
604
+ } catch {
605
+ return null
606
+ }
607
+ }
608
+
609
+ /**
610
+ * 广度优先扫出工作区里的文档、代码与媒体文件(v0.19;v0.22 加目录级 memo)。
457
611
  *
458
612
  * 一次遍历同时收三类,目录预算与时间预算共享;三类各自有数量上限,
459
613
  * 截图再多也不会把文档名额挤光,代码再多也不会(见 `MAX_CODE`)。
@@ -461,6 +615,10 @@ async function readCode(absPath, root) {
461
615
  * **扫描只做「目录元数据 → 分类 → 准入」**:这里不读任何文件内容,
462
616
  * 正文读取留给 `collectDocs`(bounded,见 `readCode`)。
463
617
  *
618
+ * v0.22:目录自己的 mtime 与上一轮逐字相同 ⇒ 跳过这一层的 `readdir`,改用缓存的
619
+ * 分类结果。**它省的是 syscall,不是正确性** —— 缓存的是「这一层有什么、各自算哪类」,
620
+ * 重新入队、计数、配额三条规则一字未改(见审计文档 §3 结论 4 与 §5 R3)。
621
+ *
464
622
  * @param {string} root - 工作区根(会话 cwd)
465
623
  * @returns {Promise<{md: string[], code: string[], media: Array<{abs:string, kind:string}>,
466
624
  * mdTruncated: boolean, codeTruncated: boolean, mediaTruncated: boolean,
@@ -474,6 +632,16 @@ async function collectEntries(root) {
474
632
  const code = []
475
633
  /** @type {Array<{abs:string, kind:string}>} */
476
634
  const media = []
635
+ /**
636
+ * 同一轮扫描内的去重集合(v0.22)。
637
+ *
638
+ * 目录 memo 让**同一层**可能被两条路径各命中一次(父目录缓存里已经有子目录清单,
639
+ * 子目录自己也命中 memo),不去重的话列表长度会随目录层级虚增。集合是本轮内幂等的
640
+ * 唯一保证 —— 它的作用域**只有这一轮**,不进任何持久结构。
641
+ */
642
+ const mdSeen = new Set()
643
+ const codeSeen = new Set()
644
+ const mediaSeen = new Set()
477
645
  const deadline = startedAt + SCAN_BUDGET_MS
478
646
  /** @type {Array<{dir:string,depth:number}>} */
479
647
  const queue = [{ dir: root, depth: 0 }]
@@ -497,6 +665,60 @@ async function collectEntries(root) {
497
665
  const { dir, depth } = queue.shift()
498
666
  visited += 1
499
667
 
668
+ // ── v0.22:目录没变就不重新 `readdir` ──────────────────────────────
669
+ //
670
+ // 判据只有一条 —— 目录自身的 mtime 与上一轮**逐字相同**。APFS 实测(审计文档 §3
671
+ // 结论 4):新增 / 删除文件只更新**直接父目录**的 mtime,且**不向上传播** ⇒ 这个
672
+ // 判据不会漏掉「某个子目录里多了个文件」,因为那一层自己的 mtime 变了。
673
+ //
674
+ // ⚠️ 它只决定「要不要重新 `readdir`」,**不改变遍历顺序**:命中的目录照样把缓存的
675
+ // 子目录重新入队,于是 `MAX_DIRS` / `MAX_DEPTH` / `SCAN_BUDGET_MS` 的作用范围一字不动。
676
+ // (旧实测否掉的是 cap-aware **剪枝** —— 提前 break 不遍历,那会让语料变小,见 §5 R3。)
677
+ const snapshot = await statOrNull(dir)
678
+ if (snapshot) {
679
+ const memo = dirMemo.get(dir)
680
+ if (memo && memo.mtimeMs === snapshot.mtimeMs) {
681
+ // 计数照旧累加:缓存省的是 `readdir`,不是「这个工作区里有什么」。
682
+ for (const key of Object.keys(stats)) stats[key] += memo.stats[key] || 0
683
+ // 两份列表都受**当前**配额约束,且必须**去重**:同一轮扫描里 A 命中了目录 memo、
684
+ // B 也命中了,它们缓存的是各自那一层,`B` 的子目录在 `A` 的记录里也会出现一次。
685
+ // 去重集合是「同一轮内幂等」的保证 —— 少了它,列表长度会随目录层级虚增。
686
+ for (const abs of memo.md) {
687
+ if (md.length >= MAX_DOCS) break
688
+ if (mdSeen.has(abs)) continue
689
+ mdSeen.add(abs)
690
+ md.push(abs)
691
+ }
692
+ for (const abs of memo.allCode) {
693
+ if (code.length >= MAX_CODE) break
694
+ if (codeSeen.has(abs)) continue
695
+ codeSeen.add(abs)
696
+ code.push(abs)
697
+ }
698
+ for (const item of memo.allMedia) {
699
+ if (media.length >= MAX_MEDIA) break
700
+ if (mediaSeen.has(item.abs)) continue
701
+ mediaSeen.add(item.abs)
702
+ media.push({ abs: item.abs, kind: item.kind })
703
+ }
704
+ if (depth < MAX_DEPTH) {
705
+ for (const sub of memo.dirs) queue.push({ dir: sub, depth: depth + 1 })
706
+ }
707
+ continue
708
+ }
709
+ }
710
+ const mtimeMs = snapshot ? snapshot.mtimeMs : null
711
+ /** 本目录**自己**发现的子目录与文件(不含更深层)—— 缓存的就是这一小份。 */
712
+ const local = {
713
+ dirs: [], md: [], allCode: [], allMedia: [],
714
+ stats: {
715
+ mdSeen: 0, mdAdmitted: 0,
716
+ codeSeen: 0, codeAdmitted: 0, codeExcluded: 0,
717
+ mediaSeen: 0, mediaAdmitted: 0,
718
+ generated: 0, ignored: 0,
719
+ },
720
+ }
721
+
500
722
  let entries
501
723
  try {
502
724
  entries = await readdir(dir, { withFileTypes: true })
@@ -510,6 +732,7 @@ async function collectEntries(root) {
510
732
  if (depth >= MAX_DEPTH) continue
511
733
  if (SKIP_DIRS.has(entry.name)) continue
512
734
  if (entry.name.startsWith('.')) continue
735
+ if (mtimeMs !== null) local.dirs.push(abs)
513
736
  queue.push({ dir: abs, depth: depth + 1 })
514
737
  } else if (entry.isFile()) {
515
738
  const info = classifyFile(entry.name)
@@ -519,22 +742,63 @@ async function collectEntries(root) {
519
742
  if (isContextKind(info.kind)) {
520
743
  if (info.kind === KIND_DOC) {
521
744
  stats.mdSeen += 1
522
- if (md.length < MAX_DOCS) { md.push(abs); stats.mdAdmitted += 1 }
745
+ local.stats.mdSeen += 1
746
+ if (mtimeMs !== null) local.md.push(abs)
747
+ if (md.length < MAX_DOCS && !mdSeen.has(abs)) {
748
+ mdSeen.add(abs)
749
+ md.push(abs)
750
+ stats.mdAdmitted += 1
751
+ local.stats.mdAdmitted += 1
752
+ }
523
753
  } else {
524
754
  stats.codeSeen += 1
525
- if (code.length < MAX_CODE) { code.push(abs); stats.codeAdmitted += 1 } else stats.codeExcluded += 1
755
+ local.stats.codeSeen += 1
756
+ if (mtimeMs !== null) local.allCode.push(abs)
757
+ if (code.length < MAX_CODE && !codeSeen.has(abs)) {
758
+ codeSeen.add(abs)
759
+ code.push(abs)
760
+ stats.codeAdmitted += 1
761
+ local.stats.codeAdmitted += 1
762
+ } else {
763
+ stats.codeExcluded += 1
764
+ local.stats.codeExcluded += 1
765
+ }
526
766
  }
527
767
  } else if (info.kind === KIND_IMAGE || info.kind === KIND_VIDEO) {
528
768
  stats.mediaSeen += 1
529
- if (media.length < MAX_MEDIA) { media.push({ abs, kind: info.kind }); stats.mediaAdmitted += 1 }
769
+ local.stats.mediaSeen += 1
770
+ if (mtimeMs !== null) local.allMedia.push({ abs, kind: info.kind })
771
+ if (media.length < MAX_MEDIA && !mediaSeen.has(abs)) {
772
+ mediaSeen.add(abs)
773
+ media.push({ abs, kind: info.kind })
774
+ stats.mediaAdmitted += 1
775
+ local.stats.mediaAdmitted += 1
776
+ }
530
777
  } else if (info.kind === KIND_GENERATED) {
531
778
  // 生成/噪声产物:**数一下,但一个都不准入**(需求 §6 §7)。
532
779
  stats.generated += 1
780
+ local.stats.generated += 1
533
781
  } else {
534
782
  stats.ignored += 1
783
+ local.stats.ignored += 1
535
784
  }
536
785
  }
537
786
  }
787
+
788
+ // 只有拿到 mtime 的目录才入 memo:`mtimeMs === null` 意味着这次 `stat` 失败,
789
+ // 而「失败」绝不能变成一条「以后都不用再看」的记录。上限与解析缓存同量级,
790
+ // 超出按插入序淘汰最早的(与 `cacheSet` 同一条 FIFO 纪律)。
791
+ if (mtimeMs !== null) {
792
+ dirMemo.set(dir, {
793
+ mtimeMs, dirs: local.dirs, md: local.md,
794
+ allCode: local.allCode, allMedia: local.allMedia, stats: local.stats,
795
+ })
796
+ while (dirMemo.size > MAX_CACHE_ENTRIES) {
797
+ const oldest = dirMemo.keys().next()
798
+ if (oldest.done) break
799
+ dirMemo.delete(oldest.value)
800
+ }
801
+ }
538
802
  }
539
803
 
540
804
  return {
@@ -580,42 +844,370 @@ async function readMediaMeta(root, { abs, kind }) {
580
844
  }
581
845
  }
582
846
 
847
+ /**
848
+ * 清掉**全部**进程内派生状态(v0.22;与 `relations.js` 的 `resetRelationCache()` 同定位)。
849
+ *
850
+ * 仅供测试:用例之间必须能拿到一个「刚重启」的插件,而模块级状态在同一个进程里是共享的。
851
+ * 生产路径一次都不会调用它。
852
+ *
853
+ * @returns {void}
854
+ */
855
+ export function resetIndexMemory() {
856
+ cache.clear()
857
+ cacheBodyBytes = 0
858
+ dirMemo.clear()
859
+ indexRels.clear()
860
+ indexVerified.clear()
861
+ indexVerifyCursor.clear()
862
+ indexStats.clear()
863
+ indexRegistry = null
864
+ indexVerifyBudget = INDEX_VERIFY_PER_PASS
865
+ }
866
+
867
+ /**
868
+ * 装一次插件存储(`apply()` 拿到 `ctx.storage` 时换掉内存版;测试也走它)。
869
+ * @param {{createIndexStore?: Function}} store - 索引存储实例;传 `null` 退回「没有存储」
870
+ * @returns {void}
871
+ */
872
+ export function setIndexRegistry(store) {
873
+ indexRegistry = store || null
874
+ }
875
+
876
+ /**
877
+ * 最近一轮扫描的索引计数(v0.22)。
878
+ *
879
+ * 验收要求「不能只说更快」,所以这些**计数**要和墙钟一起报出来:
880
+ * 这一轮真正读盘的候选数、靠索引复用的条数、写回的差量条数。
881
+ * 它只有计数,没有文件名、没有正文、没有用户数据 —— 因此可以安全地进基准报告。
882
+ *
883
+ * @param {string} root - canonical 工作区根
884
+ * @returns {{readFiles:number, reused:number, put:number, del:number,
885
+ * persisted:boolean, reason:string}|null} 计数或 null
886
+ */
887
+ export function indexStatsFor(rawRoot) {
888
+ const held = indexStats.get(hostPathOf(rawRoot))
889
+ return held ? { ...held } : null
890
+ }
891
+
892
+ /**
893
+ * 索引存储当前是否**已被证明**可用(`persisted` 只在读或写成功之后才是 true)。
894
+ * @returns {{persisted:boolean, reason:string}} 状态
895
+ */
896
+ export function indexStorageStatus() {
897
+ return indexRegistry
898
+ ? { persisted: indexRegistry.persisted, reason: indexRegistry.reason }
899
+ : { persisted: false, reason: 'no-storage' }
900
+ }
901
+
902
+ /**
903
+ * 调本轮抽验预算(v0.22)。**只为证伪**:设成 0 时对账一次都不跑,测试据此证明
904
+ * 「指纹核对」这道守卫真的在起作用;生产代码不调用它。
905
+ *
906
+ * @param {number} budget - 非负整数;非法值退回默认 `INDEX_VERIFY_PER_PASS`
907
+ * @returns {number} 生效之后的预算
908
+ */
909
+ export function setIndexVerifyBudget(budget) {
910
+ const n = Number(budget)
911
+ indexVerifyBudget = Number.isFinite(n) && n >= 0 ? Math.trunc(n) : INDEX_VERIFY_PER_PASS
912
+ return indexVerifyBudget
913
+ }
914
+
915
+ /** 抽验标记的键(`hostRoot` 与 `rel` 之间用 NUL,避免路径里出现这个组合)。 */
916
+ const verifyKey = (root, rel) => `${root}\u0000${rel}`
917
+
918
+ /**
919
+ * 把一个工作区的索引读进内存(每个 root 只读一次)。
920
+ *
921
+ * 读一次就够:这一轮扫描内的所有判定都以这份快照为准,写回走差量。
922
+ * 存储不可用时 `read()` 自己返回空 Map —— 这条路径与「索引为空」完全同形,
923
+ * 检索因此**不需要**知道存储坏没坏(提示词 §5③ 的降级要求)。
924
+ *
925
+ * @param {string} root - canonical 工作区根
926
+ * @returns {Promise<Map<string, object>>} rel → 记录
927
+ */
928
+ async function ensureIndexRels(root) {
929
+ const held = indexRels.get(root)
930
+ if (held) return held
931
+ const map = indexRegistry ? await indexRegistry.read(root) : new Map()
932
+ indexRels.set(root, map)
933
+ return map
934
+ }
935
+
936
+ /**
937
+ * 从「靠索引复用」的记录里挑出本轮要**核指纹**的那几条(v0.22)。
938
+ *
939
+ * 两条纪律:
940
+ * · **有界** —— 最多 `INDEX_VERIFY_PER_PASS` 条,与语料规模无关,于是单轮扫描的
941
+ * 额外读盘是常数级的,不会把一次用户可见的检索拖慢。
942
+ * · **公平** —— 优先挑「这个进程里还没核过」的,游标轮转推进;全核过一遍之后
943
+ * 从头再核,于是对账是**持续**的,不是启动时一次性走过场。
944
+ *
945
+ * @param {string} root - canonical 工作区根
946
+ * @param {Array<{abs:string, rel:string, isCode:boolean, record:object}>} reused - 复用清单
947
+ * @returns {Array<{abs:string, rel:string, isCode:boolean, record:object}>} 本轮要核的
948
+ */
949
+ function sampleForVerify(root, reused) {
950
+ if (reused.length === 0) return []
951
+ const take = Math.min(indexVerifyBudget, reused.length)
952
+ const cursorKey = `verify\u0000${root}`
953
+ const cursor = (indexVerifyCursor.get(cursorKey) || 0) % reused.length
954
+ const out = []
955
+ for (let i = 0; i < reused.length && out.length < take; i += 1) {
956
+ const item = reused[(cursor + i) % reused.length]
957
+ if (indexVerified.has(verifyKey(root, item.rel))) continue
958
+ out.push(item)
959
+ }
960
+ // 全部核过了(进程活得够久)⇒ 从游标处再核一遍,保持持续对账。
961
+ if (out.length === 0) {
962
+ for (let i = 0; i < take; i += 1) out.push(reused[(cursor + i) % reused.length])
963
+ }
964
+ indexVerifyCursor.set(cursorKey, (cursor + take) % reused.length)
965
+ return out
966
+ }
967
+
968
+ /**
969
+ * 一条已解析记录 → 可持久化的索引记录。
970
+ *
971
+ * 存的是**抽取后的 `refs`**,不是原文首部(v0.22 修法 ①,见 `index-store.js` 模块头):
972
+ * `buildRelationFacts()` / `buildLinkGraph()` 要的只是「这份文件提到了哪些路径」,
973
+ * 存 16KB 原文会让索引体积 ≈ 源码体积,而 `KvUnit` 只有 `loadAll()` ⇒ 每次用索引
974
+ * 都要为加载一份和源码一样大的 JSON 付钱(实测让默认的相关检索重启后慢 1.31×)。
975
+ *
976
+ * @param {object} entry - `readDoc()` / `readCode()` 的条目
977
+ * @param {string} rel - 工作区相对路径
978
+ * @returns {object} 索引记录
979
+ */
980
+ function recordFor(entry, rel) {
981
+ return {
982
+ rel,
983
+ mtimeMs: entry.mtimeMs,
984
+ size: entry.size,
985
+ headHash: entry.headHash,
986
+ title: entry.title,
987
+ summary: entry.summary,
988
+ refs: entry.refs,
989
+ }
990
+ }
991
+
992
+ /**
993
+ * 算一份 rel → 记录的快照,并与装载进来的旧索引比对出差量。
994
+ *
995
+ * 三种变化各有各的动作,**都在这里**:
996
+ * · 新增 / 更新 → `put`(只写这一条)
997
+ * · 少了的(被删 / 被移出准入范围 / 被 Git 切分支切没了)→ `del`(只删这一条)
998
+ * · 没变的 → 两边都不出现,一个字节都不写
999
+ *
1000
+ * 删除必须有界:一轮扫描只抽验 `INDEX_VERIFY_PER_PASS` 条**没在本轮语料里出现**的旧记录
1001
+ * (游标轮转,见 `sweepStale`)—— 否则「1000 个文件全删掉」会把删除量变成一次 O(N) 的写风暴。
1002
+ *
1003
+ * @param {string} root - canonical 工作区根
1004
+ * @param {Map<string, object>} next - 本轮算出的 rel → 记录
1005
+ * @param {Map<string, object>} before - 装载进来的旧索引
1006
+ * @returns {{put: Array<object>, del: string[]}} 差量
1007
+ */
1008
+ function indexDiff(root, next, before) {
1009
+ const put = []
1010
+ const del = []
1011
+ for (const [rel, record] of next) {
1012
+ const old = before.get(rel)
1013
+ if (old && old.headHash === record.headHash
1014
+ && old.mtimeMs === record.mtimeMs && old.size === record.size) continue
1015
+ put.push(record)
1016
+ }
1017
+ // 本轮语料里根本没有的旧记录:抽验删除(游标轮转,保证「分批」是公平的)。
1018
+ const stale = []
1019
+ for (const rel of before.keys()) {
1020
+ if (!next.has(rel)) stale.push(rel)
1021
+ }
1022
+ if (stale.length > 0) {
1023
+ let cursor = indexVerifyCursor.get(root) || 0
1024
+ if (cursor >= stale.length) cursor = 0
1025
+ const take = Math.min(INDEX_VERIFY_PER_PASS, stale.length)
1026
+ for (let i = 0; i < take; i += 1) {
1027
+ del.push(stale[(cursor + i) % stale.length])
1028
+ }
1029
+ indexVerifyCursor.set(root, (cursor + take) % stale.length)
1030
+ }
1031
+ return { put, del }
1032
+ }
1033
+
1034
+ /**
1035
+ * 把一批记录里缺少正文的那些**按需**补齐(v0.22)。
1036
+ *
1037
+ * 为什么必须有这一步:索引里**没有正文**(裁决 A),而从索引还原出来的条目
1038
+ * `body` 是空串。时间序列表不需要正文(`publicDoc()` 本来就不下发它),但
1039
+ * **相关检索需要** —— 文件级 BM25 打分的输入是整篇小写正文。
1040
+ *
1041
+ * 所以相关路径照旧读正文,「跳过读盘」这一版只在时间序路径上成立,这是**如实记下的代价**,
1042
+ * 不是遗漏。补齐仍然是有界的:只补真的会参与打分的那批(`pool` 已按 kind 切好)。
1043
+ *
1044
+ * @param {Array<object>} list - 条目(原地升级)
1045
+ * @param {string} root - 工作区根
1046
+ * @returns {Promise<number>} 真正补了几条
1047
+ */
1048
+ async function hydrateBodies(list, root) {
1049
+ let hydrated = 0
1050
+ for (const doc of list) {
1051
+ if (doc.bodyReady) continue
1052
+ // 条目上已经有 `refs`(索引复用来的)时明说不要重算 —— 省掉两次正则扫描,
1053
+ // 而结果本来就一模一样。没有 `refs` 时才让它顺带算出来。
1054
+ const wantRefs = !(doc.refs && typeof doc.refs === 'object')
1055
+ const meta = doc.kind === KIND_CODE
1056
+ ? await readCodeFromDisk(doc.path, root, { mtimeMs: doc.mtimeMs, size: doc.size }, { refs: wantRefs })
1057
+ : await readDocFromDisk(doc.path, { mtimeMs: doc.mtimeMs, size: doc.size }, { refs: wantRefs })
1058
+ if (!meta) continue
1059
+ doc.head = meta.head
1060
+ // v0.22 修法 ①:整读时顺带算出的抽取结果也要跟着升级 —— 否则「索引复用来的
1061
+ // `refs`」与「刚读出来的 `head`」会在同一个条目上不一致(关系用旧的、引用图用新的)。
1062
+ if (meta.refs) doc.refs = meta.refs
1063
+ doc.body = meta.body
1064
+ doc.bodyBytes = meta.bodyBytes
1065
+ doc.bodyTruncated = meta.bodyTruncated
1066
+ doc.haystack = { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody }
1067
+ doc.bodyReady = true
1068
+ cacheSet(doc.path, meta)
1069
+ hydrated += 1
1070
+ }
1071
+ return hydrated
1072
+ }
1073
+
583
1074
  /**
584
1075
  * 扫出工作区里全部文档、代码与媒体的元信息(各自按 mtime 倒序)。
585
1076
  *
586
1077
  * 三类共用一次目录遍历(`collectEntries`),但**只有文档与代码会读正文头部**
587
1078
  * ——媒体永远只 stat(视频可能上百 MB)。
588
1079
  *
1080
+ * v0.22:每条候选先过一遍「有没有资格不读盘」——顺序是
1081
+ * ① 进程内缓存命中(mtime+size)→ 直接复用,一次盘都不读;
1082
+ * ② 持久索引里有记录且 mtime+size 一致 → **只读头部核指纹**(≤16KB),核过就还原;
1083
+ * ③ 其余 → 老老实实整读 + 重解析。
1084
+ * 第 ② 步是这一版唯一新增的一致性问题:「同 mtime、同 size、内容变了」必须在核过指纹后
1085
+ * 才敢复用,而提示词 §4 明确禁止把 mtime/size 当作唯一证据。
1086
+ *
589
1087
  * @param {string} root - 工作区根
590
1088
  * @returns {Promise<{docs: Array<object>, code: Array<object>, media: Array<object>,
591
1089
  * truncated: boolean, codeTruncated: boolean, mediaTruncated: boolean,
592
1090
  * stats: object, scanMs: number}>}
593
1091
  */
594
- export async function collectDocs(root) {
1092
+ export async function collectDocs(rawRoot, options = {}) {
1093
+ // v0.22:**索引一律按 canonical 工作区根记账**。
1094
+ //
1095
+ // 为什么必须在这里归一,而不是只靠调用方:`scan()` 自己有 `hostPathOf()`(展开符号
1096
+ // 链接),但 `collectDocs()` 是导出函数,工具与测试会**直接用工作区原路径**调它。
1097
+ // 两边都用原路径分别记账的话,同一个工作区会留下两份内存状态,而**存储里
1098
+ // 同一个键会被两个不同的 `root` 值轮流覆盖** —— 于是「跨工作区隔离」的过滤条件
1099
+ // 会随最后一次写入摇摆,索引时灵时不灵,且完全不报错。
1100
+ // `hostPathOf()` 在路径不存在时兜底返回原值,所以这里不会把「打不开」升级成异常。
1101
+ const root = hostPathOf(rawRoot)
1102
+ // v0.22 修法 ②(2026-10-10):**要正文的扫描不查索引**。
1103
+ //
1104
+ // 索引省下的是「读盘 + 解析正文」,而相关检索(BM25)无论如何都要拿到全部正文
1105
+ // —— `rankByRelevance()` 的 `avgdl` / `df` 都是正文的函数(裁决 A)。于是那条路上
1106
+ // 复用来的记录会被 `hydrateBodies()` 立刻整读补回正文,净效果是**多付一次索引装载**:
1107
+ // 每条记录一个文件 open + read + `JSON.parse`,实测 600 条约 60–75 ms,而且这个成本
1108
+ // 与记录里的载荷大小**几乎无关**(见 `Knit-v0.22-实现与基准报告.md` §4.5)。
1109
+ // 判据因此不是「有没有索引」,而是**这一轮到底用不用得着正文** —— 只有调用方知道,
1110
+ // 于是由它显式传 `{ index: false }`;不传仍然查索引(低层 API 不替调用方做这个决定)。
1111
+ const useIndex = options.index !== false
595
1112
  const found = await collectEntries(root)
596
1113
  const docs = []
597
1114
  // v0.20:被 `MAX_BODY_BYTES` 截掉尾巴的文件数。**只是计数**,用来在规模报告里
598
1115
  // 诚实说出「有多大比例的文件没有全量参与打分」,不参与任何排序。
599
1116
  let bodyTruncated = 0
600
1117
 
1118
+ // v0.22:装载索引 + 逐条「读盘 / 还原」判定。整段就是上面的 ①②③。
1119
+ // `useIndex === false` 时给一张空表:下面的 `resolve()` 因此逐条走 ③(整读 + 重解析),
1120
+ // 而**不装载、不对账、不写回** —— 正是修法 ② 要的那条口径。
1121
+ const index = useIndex ? await ensureIndexRels(root) : new Map()
1122
+ const nextIndex = new Map()
1123
+ let readFiles = 0
1124
+
1125
+ /**
1126
+ * 一条候选的取数判定(文档与代码共用;`isCode` 只决定读盘时走哪个解析器)。
1127
+ * @param {string} abs - 绝对路径
1128
+ * @param {string} rel - 工作区相对路径
1129
+ * @param {object} st - 已取得的 stat
1130
+ * @param {boolean} isCode - 是否代码
1131
+ * @returns {Promise<object|null>} 条目
1132
+ */
1133
+ /** 本轮靠**进程内 `cache`** 复用的条数(v0.20 就有的能力,与索引复用分开报)。 */
1134
+ let cached = 0
1135
+
1136
+ const resolve = async (abs, rel, st, isCode) => {
1137
+ const key = verifyKey(root, rel)
1138
+ const hit = cache.get(abs)
1139
+ if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
1140
+ // ① 进程内已解析过,且 mtime+size 未变 —— 一次盘都不读。
1141
+ // ⚠️ 它与 `reused`(靠索引还原)**分开计数**:v0.20/v0.21 就已经做到了
1142
+ // 「同一进程内不重读」,而 v0.22 的收益在**跨进程重启**。混在一起报,
1143
+ // 就会把旧能力算进这一版的成绩里。
1144
+ indexVerified.add(key)
1145
+ cached += 1
1146
+ return hit
1147
+ }
1148
+ const stored = index.get(rel)
1149
+ const plausible = !!stored
1150
+ && typeof stored.headHash === 'string' && stored.headHash.length > 0
1151
+ // v0.22 修法 ①:`refs` 必须真的在里面。v2 记录(存的是 `head`)与 v1 记录
1152
+ // 都过不了这一关 ⇒ 当「没有可用记录」处理 ⇒ 本轮回退读盘并重建,
1153
+ // 迁移不需要任何专用代码。少这一条,重启后关系投影会**静默少掉**。
1154
+ && refsShapeOk(stored.refs)
1155
+ && stored.mtimeMs === st.mtimeMs && stored.size === st.size
1156
+ if (plausible) {
1157
+ // ② 元信息一致 ⇒ **正文与头部都不读**,直接用索引还原。
1158
+ //
1159
+ // 这里就是这一版的立论:`mtime + size` 当**快速筛子**用(提示词 §4 允许),
1160
+ // 而「筛过之后凭什么信」由两件事回答 ——
1161
+ // a) 每条记录都带 `headHash`,内容一旦变化,下一次抽验必然发现;
1162
+ // b) 每轮扫描抽验 `INDEX_VERIFY_PER_PASS` 条(`verifySampled()`),
1163
+ // 把「同 mtime 同 size 的编辑」这类伪造在一个有界窗口内抓出来。
1164
+ // 两者合起来才是「mtime/size 不是唯一证据」的落实 —— 不是让每次扫描都重读一遍
1165
+ // 头部(那等于没省),而是**读到的那一份永远能被指纹复核**。
1166
+ indexVerified.add(key)
1167
+ reused.push({ abs, rel, isCode, record: stored })
1168
+ return restoreFromIndex(stored)
1169
+ }
1170
+ // ③ 没有可用记录(或元信息就变了)—— 整读 + 重解析,并重算指纹。
1171
+ indexVerified.add(key)
1172
+ const meta = isCode
1173
+ ? await readCodeFromDisk(abs, root, st)
1174
+ : await readDocFromDisk(abs, st)
1175
+ if (!meta) return null
1176
+ readFiles += 1
1177
+ return meta
1178
+ }
1179
+
1180
+ /** 本轮「靠索引复用」的候选 —— 抽验的对象。 */
1181
+ const reused = []
1182
+
601
1183
  for (const abs of found.md) {
602
- const meta = await readDoc(abs)
1184
+ const st = await statOrNull(abs)
1185
+ if (!st || !st.isFile()) continue
1186
+ const rel = relative(root, abs).split(sep).join('/')
1187
+ const meta = await resolve(abs, rel, st, false)
603
1188
  if (!meta) continue
604
1189
  if (meta.bodyTruncated) bodyTruncated += 1
605
1190
  docs.push({
606
1191
  kind: KIND_DOC,
607
1192
  path: abs,
608
- rel: relative(root, abs).split(sep).join('/'),
1193
+ rel,
609
1194
  name: abs.split(sep).pop(),
610
1195
  title: meta.title,
611
1196
  summary: meta.summary,
612
1197
  size: meta.size,
613
1198
  mtimeMs: meta.mtimeMs,
1199
+ headHash: meta.headHash,
1200
+ // v0.22 修法 ①:抽取后的引用列表(索引里存的就是它)。内部字段,不下发。
1201
+ refs: meta.refs,
614
1202
  // 原文首部:`buildContextFor()` 抽引用关系用(v0.14)。内部字段,不下发。
1203
+ // 索引复用来的条目这里是空串 —— 消费方必须优先读 `refs`。
615
1204
  head: meta.head,
616
1205
  // v0.20:整篇正文随记录走 —— 片段切分与 `matches` 的输入。
617
1206
  // 它是**内部字段**:`publicDoc()` 不转发正文,只转发派生出的行号与摘要。
618
1207
  body: meta.body,
1208
+ bodyReady: !!meta.bodyReady,
1209
+ bodyBytes: meta.bodyBytes,
1210
+ bodyTruncated: meta.bodyTruncated,
619
1211
  haystack: { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody },
620
1212
  })
621
1213
  }
@@ -626,25 +1218,87 @@ export async function collectDocs(root) {
626
1218
  // 这不是「第二套数据模型」,就是同一套模型里多了一类 kind。
627
1219
  const code = []
628
1220
  for (const abs of found.code) {
629
- const meta = await readCode(abs, root)
1221
+ const st = await statOrNull(abs)
1222
+ if (!st || !st.isFile()) continue
1223
+ const rel = relative(root, abs).split(sep).join('/')
1224
+ const meta = await resolve(abs, rel, st, true)
630
1225
  if (!meta) continue
631
1226
  if (meta.bodyTruncated) bodyTruncated += 1
632
1227
  code.push({
633
1228
  kind: KIND_CODE,
634
1229
  path: abs,
635
- rel: relative(root, abs).split(sep).join('/'),
1230
+ rel,
636
1231
  name: abs.split(sep).pop(),
637
1232
  title: meta.title,
638
1233
  summary: meta.summary,
639
1234
  size: meta.size,
640
1235
  mtimeMs: meta.mtimeMs,
1236
+ headHash: meta.headHash,
1237
+ refs: meta.refs,
641
1238
  head: meta.head,
642
1239
  body: meta.body,
1240
+ bodyReady: !!meta.bodyReady,
1241
+ bodyBytes: meta.bodyBytes,
1242
+ bodyTruncated: meta.bodyTruncated,
643
1243
  haystack: { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody },
644
1244
  })
645
1245
  }
646
1246
  code.sort((a, b) => b.mtimeMs - a.mtimeMs)
647
1247
 
1248
+ // v0.22:**有界对账**。抽验「靠索引复用」的那些记录 —— 读头部、比指纹;对不上就
1249
+ // 重读重解析并**就地改正刚刚交出去的那条记录**。每轮只抽 `INDEX_VERIFY_PER_PASS` 条,
1250
+ // 游标轮转,于是整个工作区在一段有界的窗口内被核完,而单轮扫描的额外读盘是常数级的
1251
+ // (提示词 §5⑤「必要时分批执行避免阻塞主交互」)。
1252
+ const byRel = new Map()
1253
+ for (const doc of docs) byRel.set(doc.rel, doc)
1254
+ for (const doc of code) byRel.set(doc.rel, doc)
1255
+ const sampled = sampleForVerify(root, reused)
1256
+ let verified = 0
1257
+ let repaired = 0
1258
+ for (const item of sampled) {
1259
+ if (!item) continue
1260
+ let head = null
1261
+ try {
1262
+ const buf = await readFile(item.abs)
1263
+ // ⚠️ 代码的头部口径是 `CODE_HEAD_BYTES`(8KB),文档是 `HEAD_BYTES`(16KB)。
1264
+ // 用错长度算出来的指纹**永远对不上**(会让索引对代码彻底失效且不报错),
1265
+ // 所以这一行必须与 `readDocFromDisk` / `readCodeFromDisk` 里那行逐字一致。
1266
+ head = buf.subarray(0, item.isCode ? CODE_HEAD_BYTES : HEAD_BYTES).toString('utf8')
1267
+ } catch {
1268
+ continue
1269
+ }
1270
+ readFiles += 1
1271
+ verified += 1
1272
+ if (headHashOf(head) === item.record.headHash) continue
1273
+ // 指纹不符 —— 元信息骗了我们。重读重解析,并改正这条记录。
1274
+ const fresh = await statOrNull(item.abs)
1275
+ if (!fresh || !fresh.isFile()) continue
1276
+ const meta = item.isCode
1277
+ ? await readCodeFromDisk(item.abs, root, fresh)
1278
+ : await readDocFromDisk(item.abs, fresh)
1279
+ if (!meta) continue
1280
+ readFiles += 1
1281
+ repaired += 1
1282
+ const doc = byRel.get(item.rel)
1283
+ if (!doc) continue
1284
+ doc.head = meta.head
1285
+ doc.refs = meta.refs
1286
+ doc.title = meta.title
1287
+ doc.summary = meta.summary
1288
+ doc.size = meta.size
1289
+ doc.mtimeMs = meta.mtimeMs
1290
+ doc.headHash = meta.headHash
1291
+ // ⚠️ 内容变了,抽取结果必然跟着变 —— 漏了这一个字段,修好的记录会把**旧引用**
1292
+ // 写回索引,重启后关系与引用图就静默少了东西(而且看不出错)。
1293
+ if (meta.refs) doc.refs = meta.refs
1294
+ doc.body = meta.body
1295
+ doc.bodyReady = true
1296
+ doc.bodyBytes = meta.bodyBytes
1297
+ doc.bodyTruncated = meta.bodyTruncated
1298
+ doc.haystack = { title: meta.hayTitle, summary: meta.haySummary, body: meta.hayBody }
1299
+ cacheSet(item.abs, meta)
1300
+ }
1301
+
648
1302
  const media = []
649
1303
  for (const item of found.media) {
650
1304
  const meta = await readMediaMeta(root, item)
@@ -652,6 +1306,49 @@ export async function collectDocs(root) {
652
1306
  }
653
1307
  media.sort((a, b) => b.mtimeMs - a.mtimeMs)
654
1308
 
1309
+ // 这一轮算出的索引:**从刚刚交出去的记录本身**生成,所以抽验修好的那几条自动是正确值。
1310
+ for (const doc of docs) nextIndex.set(doc.rel, recordFor(doc, doc.rel))
1311
+ for (const doc of code) nextIndex.set(doc.rel, recordFor(doc, doc.rel))
1312
+
1313
+ // v0.22:把这一轮算出来的索引写回存储。**只写差量**(新增/更新那几条 + 抽验出的删除),
1314
+ // fire-and-forget:写失败只影响「下次重启」,不影响本次结果,所以不 await
1315
+ // —— 不为维护缓存去阻塞一次用户可见的检索(提示词 §4 最后一条)。
1316
+ if (useIndex && indexRegistry) {
1317
+ const diff = indexDiff(root, nextIndex, index)
1318
+ indexRels.set(root, nextIndex)
1319
+ indexStats.set(root, {
1320
+ candidates: nextIndex.size,
1321
+ readFiles,
1322
+ cached,
1323
+ reused: reused.length,
1324
+ verified,
1325
+ repaired,
1326
+ put: diff.put.length,
1327
+ del: diff.del.length,
1328
+ skipped: false,
1329
+ persisted: indexRegistry.persisted,
1330
+ reason: indexRegistry.reason,
1331
+ })
1332
+ if (diff.put.length > 0 || diff.del.length > 0) {
1333
+ indexRegistry.write(root, diff)
1334
+ }
1335
+ } else {
1336
+ indexStats.set(root, {
1337
+ candidates: nextIndex.size,
1338
+ readFiles,
1339
+ cached,
1340
+ reused: reused.length,
1341
+ verified,
1342
+ repaired,
1343
+ put: 0,
1344
+ del: 0,
1345
+ // 「这一轮没查索引」与「这个进程没有存储」是两件事,读数不能混成同一个 0。
1346
+ skipped: !useIndex,
1347
+ persisted: false,
1348
+ reason: useIndex ? 'no-storage' : 'index-skipped',
1349
+ })
1350
+ }
1351
+
655
1352
  return {
656
1353
  docs,
657
1354
  code,
@@ -866,7 +1563,41 @@ export async function scan(root, limit, options = {}) {
866
1563
  // ⚠️ `rel` 用同一个 base 算,所以相对路径一字不变;对外的 `root` 仍是会话
867
1564
  // 原本那条(界面显示用),canonical 的那份单独放在 `hostRoot`。
868
1565
  const hostRoot = hostPathOf(root)
869
- const collected = await collectDocs(hostRoot)
1566
+
1567
+ // v0.22 修法 ②:**先算出这一轮要不要正文,再决定查不查索引**(2026-10-10)。
1568
+ //
1569
+ // 判据只有一条:`mode === 'relevance'` —— 排序改成「相关」**并且**真的抽到了关键词。
1570
+ // 那时 `rankByRelevance()` 必须拿到全部正文,索引复用在那种情形下是净开销(见
1571
+ // `collectDocs()` 里的长注释)。时间序(含「按相关排序但一个关键词都没抽到」)
1572
+ // 完全吃索引里的 `title` / `summary` / 有界正文派生字段 —— 那才是索引的收益点。
1573
+ // 这一段原来在 `collectDocs()` 之后;挪上来只为把 `mode` 先算出来,判定规则一字未动。
1574
+ const wantRelevance = options.sort === 'relevance'
1575
+ const sessionId = options.sessionId || ''
1576
+ let keywords = NO_KEYWORDS
1577
+ let mode = 'time'
1578
+ let matched = []
1579
+ // 当前任务的**原文引用**(SDD §12)。只在「对话驱动」这条路上有值:
1580
+ // 显式 query 路径下模型自己知道在问什么,把 query 当「任务」是编的。
1581
+ let task = ''
1582
+
1583
+ if (wantRelevance) {
1584
+ // 调用方给了明确的 query(v0.7 的 agent 工具走这条路):把它当成**一条最新的消息**,
1585
+ // 于是走的是完全相同的抽取与门槛规则,不引入第二条抽取路径。
1586
+ // 不进 convCache —— 那个缓存按 session seq 键控,塞 query 进去会互相污染。
1587
+ const explicitQuery = typeof options.query === 'string' ? options.query.trim() : ''
1588
+ if (explicitQuery) {
1589
+ keywords = extractKeywords([explicitQuery], 30)
1590
+ } else {
1591
+ const conv = conversationFor(options.session, sessionId)
1592
+ keywords = conv.keywords
1593
+ task = conv.task
1594
+ }
1595
+ // 没有对话可依据时老实退回时间序,而不是假装排了个序
1596
+ mode = keywords.length > 0 ? 'relevance' : 'time'
1597
+ }
1598
+
1599
+
1600
+ const collected = await collectDocs(hostRoot, { index: mode !== 'relevance' })
870
1601
 
871
1602
  // 默认 doc:旧版客户端 / 悬停浮层不带 kind,行为与「只列 Markdown」时完全一致。
872
1603
  //
@@ -925,34 +1656,16 @@ export async function scan(root, limit, options = {}) {
925
1656
  }
926
1657
  }
927
1658
 
928
- const wantRelevance = options.sort === 'relevance'
929
- const sessionId = options.sessionId || ''
930
- let keywords = NO_KEYWORDS
931
- let mode = 'time'
932
- let matched = []
933
- // 当前任务的**原文引用**(SDD §12)。只在「对话驱动」这条路上有值:
934
- // 显式 query 路径下模型自己知道在问什么,把 query 当「任务」是编的。
935
- let task = ''
936
-
937
- if (wantRelevance) {
938
- // 调用方给了明确的 query(v0.7 的 agent 工具走这条路):把它当成**一条最新的消息**,
939
- // 于是走的是完全相同的抽取与门槛规则,不引入第二条抽取路径。
940
- // 不进 convCache —— 那个缓存按 session seq 键控,塞 query 进去会互相污染。
941
- const explicitQuery = typeof options.query === 'string' ? options.query.trim() : ''
942
- if (explicitQuery) {
943
- keywords = extractKeywords([explicitQuery], 30)
944
- } else {
945
- const conv = conversationFor(options.session, sessionId)
946
- keywords = conv.keywords
947
- task = conv.task
948
- }
949
- // 没有对话可依据时老实退回时间序,而不是假装排了个序
950
- mode = keywords.length > 0 ? 'relevance' : 'time'
951
- }
952
-
953
1659
  let ordered
954
1660
  let topic = ''
955
1661
  if (mode === 'relevance') {
1662
+ // v0.22:相关检索必须拿到**正文**(打分、片段、逐词字频都读它)。从索引还原出来的
1663
+ // 条目没有正文(裁决 A),这里按需补齐 —— 只补真的会参与打分的那批,而且是整读。
1664
+ //
1665
+ // ⚠️ 放在 `rankByRelevance()` **之前**,不是之后:没有正文的条目会让 BM25 的
1666
+ // `avgdl` 与 `df` 一起偏小,名次与「索引开/关」两份结果就对不上了。顺序在这里是
1667
+ // 正确性问题,不是性能问题。
1668
+ await hydrateBodies(pool, hostRoot)
956
1669
  // 一个 `now` 贯到底(打分与片段用同一个时间基准)—— 同一批输入两次跑出的
957
1670
  // 结果因此逐字相同(§20 的确定性要求)。
958
1671
  const now = Date.now()
@@ -1074,7 +1787,12 @@ async function linkGraphFor(root, withLinks, byRel) {
1074
1787
  }),
1075
1788
  read: async (_root, rel) => {
1076
1789
  const entry = byRel.get(rel)
1077
- if (!entry || typeof entry.head !== 'string') return { ok: false }
1790
+ if (!entry) return { ok: false }
1791
+ // v0.22 修法 ①:索引复用来的条目没有原文首部(`head` 是空串),所以
1792
+ // **正常不会走到这里** —— `links.js` 优先吃条目上的 `refs.md`(抽取结果),
1793
+ // 只有那条路没有时才回来要文本。保留这条分支是给「列表方与读取方不是同一份数据」
1794
+ // 的调用方用的(单测的假条目就是这种)。
1795
+ if (typeof entry.head !== 'string') return { ok: false }
1078
1796
  return { ok: true, text: entry.head }
1079
1797
  },
1080
1798
  })
@@ -2074,6 +2792,16 @@ export function apply(ctx) {
2074
2792
  const shared = sharedControlRegistry(backend)
2075
2793
  if (shared) controlRegistry = shared
2076
2794
  console.log(`[${name}] control storage: ${shared ? 'json backend attached' : 'memory-only'}`)
2795
+
2796
+ // ── v0.22:增量索引的持久化 ─────────────────────────────────────
2797
+ //
2798
+ // 与上面共用**一个** `ctx.storage` 后端,但**各开各的 kv 单元**(`knit_index`):
2799
+ // 索引的写量与形状和控制状态完全不同(`per-record` + 每条一个文件),混在一个单元里
2800
+ // 会让「改一个文件」变成重写整份控制状态。同一条 `sharedIndexStore()` 理由,
2801
+ // 见 `index-store.js`。
2802
+ const store = sharedIndexStore(backend)
2803
+ if (store) setIndexRegistry(store)
2804
+ console.log(`[${name}] index storage: ${store ? 'attached' : 'memory-only'}`)
2077
2805
  })
2078
2806
 
2079
2807
  // ── v0.7:把同一个排序结果也交给模型 ──────────────────────────────