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/CHANGELOG.md +124 -0
- package/README.md +3 -2
- package/package.json +2 -2
- package/src/host/index-store.js +479 -0
- package/src/host/index.js +796 -68
- package/src/host/links.js +23 -10
- package/src/host/relations.js +12 -2
- package/test/fixture.mjs +50 -0
- package/test/index-incremental.test.mjs +504 -0
- package/test/index-store.test.mjs +340 -0
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
|
-
|
|
24
|
-
//
|
|
25
|
-
import {
|
|
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
|
-
*
|
|
322
|
-
*
|
|
323
|
-
*
|
|
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
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
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
|
-
|
|
407
|
+
}
|
|
333
408
|
|
|
334
|
-
|
|
335
|
-
|
|
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
|
-
* 与 `
|
|
384
|
-
*
|
|
385
|
-
* `
|
|
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
|
|
401
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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:把同一个排序结果也交给模型 ──────────────────────────────
|