@dsh-libing/knowledge-base 0.1.0 → 0.1.4

package/lib/jobs.js

@@ -14,6 +14,7 @@ import { convertPdf } from "./document/pdf.js";
 import { PdfSession, pageRange } from "./document/pdf-session.js";
 import { PDF_PARSER_VERSION } from "./document/pdf-layout.js";
 import { BudgetError } from "./models.js";
+import { loadJob, saveCheckpoint, saveReport, readReport, recoverUsage, summarizeReport, usagePage } from "./job-storage.js";
 const RESUMABLE = new Set(['failed', 'needs-review', 'paused-budget', 'cancelled']);
 export class Jobs {
     store;
@@ -50,33 +51,51 @@ export class Jobs {
         }
         const visible = new Set((await this.store.list()).map(k => k.kbId));
         for (const dir of await this.store.jobDirectories()) {
-            const record = await readJson(join(dir, 'job.json'), jobSchema, null);
+            const record = await loadJob(dir);
             if (!record || !visible.has(record.kbId))
                 continue;
+            if (record.jobId !== basename(dir))
+                throw new Error('任务目录与身份不一致');
             const job = this.attach(record, dir);
             this.jobs.set(job.jobId, job);
+            if (job.pendingCalls.length)
+                await recoverUsage(job);
             if (ACTIVE.has(job.state)) {
                 job.state = 'queued';
                 job.recoveredAt = now();
                 await job.checkpoint();
             }
         }
+        await this.store.cleanUploads();
         this.pump();
     }
     attach(record, directory) {
         let tail = Promise.resolve();
-        return { ...record, directory, cacheDir: join(this.store.root, 'cache'), checkpoint: async () => {
-                const snapshot = jobSchema.parse(JSON.parse(JSON.stringify(this.jobs.get(record.jobId) || record)));
-                const pending = tail.then(() => atomicWrite(join(directory, 'job.json'), snapshot));
+        const job = { ...record, directory, cacheDir: join(this.store.root, 'cache'), checkpoint: async () => {
+                const { report: _report, usage, ...value } = job;
+                const snapshot = jobSchema.parse({ ...value, usage: { ...usage, records: [] } });
+                const pending = tail.then(() => saveCheckpoint(directory, snapshot));
                 tail = pending.catch(() => { });
                 await pending;
             } };
+        return job;
     }
     public(job) {
-        const { checkpoint: _checkpoint, directory: _directory, cacheDir: _cacheDir, schema: _schema, overlays: _overlays, ...value } = job;
+        const { checkpoint: _checkpoint, directory: _directory, cacheDir: _cacheDir, schema: _schema, overlays: _overlays, report: _report, ...value } = job;
         return { ...value, outputPath: value.outputPath || null };
     }
-    list(kbId) { return [...this.jobs.values()].filter(j => !kbId || j.kbId === kbId).sort((a, b) => b.createdAt.localeCompare(a.createdAt)).map(j => this.public(j)); }
+    list(kbId, offset = 0, limit = 20) {
+        if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new Error('任务分页参数无效');
+        const all = [...this.jobs.values()].filter(j => !kbId || j.kbId === kbId).sort((a, b) => Number(ACTIVE.has(b.state)) - Number(ACTIVE.has(a.state)) || b.createdAt.localeCompare(a.createdAt) || b.jobId.localeCompare(a.jobId));
+        const page = all.slice(offset, offset + limit).map(job => {
+            const { report: _report, events: _events, failures: _failures, ...value } = this.public(job);
+            return { ...value, events: [], failures: [], usage: { ...value.usage, records: [] } };
+        });
+        return { jobs: page, jobTotal: all.length, jobOffset: offset, activeJobs: [...this.jobs.values()].filter(j => ACTIVE.has(j.state)).length };
+    }
+    async details(jobId, includeReport = true) { const job = this.get(jobId); const { report: _report, ...value } = this.public(job); return { ...value, ...includeReport ? { report: await readReport(job) } : {} }; }
+    async usage(jobId, offset, limit, signal) { return usagePage(this.get(jobId), offset, limit, signal); }
     get(jobId) {
         const job = this.jobs.get(id(jobId, 'jobId'));
         if (!job)
@@ -92,7 +111,8 @@ export class Jobs {
         const kb = await this.store.kb(text(args.kbId, 'kbId', 120));
         if (Boolean(args.sourcePath) === Boolean(args.receiptId))
             throw new Error('sourcePath / receiptId 必须提供其中一个');
-        let source, filename;
+        let source;
+        let filename;
         if (args.receiptId) {
             const uploaded = await this.store.uploaded(args.receiptId);
             source = uploaded.data;
@@ -135,12 +155,14 @@ export class Jobs {
                 await session.close();
                 await rm(temp, { force: true });
             }
-            const current = await this.store.current(kb.kbId), old = current ? (await this.store.revision(kb.kbId, current.revision)).manifest.documents.find(d => d.docId === docId) : null;
+            const current = await this.store.current(kb.kbId);
+            const old = current ? (await this.store.revision(kb.kbId, current.revision)).manifest.documents.find(d => d.docId === docId) : null;
             const previous = old?.selectedPages;
             if (previous && (previous.partial || selectedPages.partial) && (previous.start !== selectedPages.start || previous.end !== selectedPages.end) && args.confirmRangeChange !== true)
                 throw new Error('PDF 导入范围已变化，本次发布会替换该文档当前内容；请明确确认范围变化，历史版本保留');
         }
-        const schema = await this.store.schema(kb.kbId), schemaHash = hash(schema);
+        const schema = await this.store.schema(kb.kbId);
+        const schemaHash = hash(schema);
         const routes = { vision: config.visionProvider ? { provider: config.visionProvider, model: config.visionModel } : null, summary: config.summaryProvider ? { provider: config.summaryProvider, model: config.summaryModel } : null };
         if (!routes.summary) {
             const defaultRoute = this.models.ctx.get('agentDefaultModel')?.currentSelection() || execution.route;
@@ -154,7 +176,8 @@ export class Jobs {
         const existing = [...this.jobs.values()].find(j => j.kbId === kb.kbId && j.buildKey === optionsKey && (ACTIVE.has(j.state) || j.state === 'ready' && current?.revision === j.revision));
         if (existing)
             return { ...this.public(existing), reused: true };
-        const jobId = `job-${randomUUID()}`, directory = join(this.store.root, 'jobs', jobId);
+        const jobId = `job-${randomUUID()}`;
+        const directory = join(this.store.root, 'jobs', jobId);
         await mkdir(directory, { recursive: true });
         await atomicWrite(join(directory, 'input' + extname(filename).toLowerCase()), source);
         const job = this.attach(jobSchema.parse({ jobId, kbId: kb.kbId, docId, title: text(args.title || filename.replace(/\.(?:docx?|pdf)$/i, ''), '文档标题', 300), sourceVersion: args.sourceVersion ? text(args.sourceVersion, '文档版本', 120) : '', filename, sourceFormat, ...selectedPages ? { pageStart: selectedPages.start, pageEnd: selectedPages.end, pdf: { pageCount: selectedPages.total, selectedPages } } : {}, sourceOriginalHash, buildKey: optionsKey, config, routes, schema, schemaHash, overlays, sessionId: execution.sessionId || null, state: 'queued', createdAt: now(), progress: {}, usage: { calls: 0, tokens: 0, reportedCalls: 0, records: [] }, failures: [] }), directory);
@@ -198,12 +221,13 @@ export class Jobs {
             const { nodes, chunks } = createChunks(document, info, job.config);
             for (const chunk of chunks)
                 chunk.summary = clip(chunk.segments.filter(s => ['paragraph', 'list', 'note'].includes(s.type)).map(s => s.text).join(' ').replace(/\s+/g, ' ') || chunk.title, job.config.summaryMaxChars);
-            manifest = { formatVersion: 1, revision: required(job.revision, '草稿版本'), buildKey: job.buildKey, createdAt: job.createdAt, config: { chunkTargetChars: job.config.chunkTargetChars }, catalogs: {}, entities: {}, report: job.report ?? { revision: required(job.revision), sourceHash: required(job.sourceHash), issues: document.warnings, documents: 1, blocks: document.blocks.length, figures: document.assets.length, ignoredFigures: 0, unreviewedFigures: document.assets.length, chunks: chunks.length, withinTarget: chunks.filter(c => c.fullChars <= job.config.chunkTargetChars).length, oversized: [], usage: job.usage, targetChars: job.config.chunkTargetChars }, coverageIncomplete: true, documents: [{ ...info, nodes, chunks, assets: document.assets, figures: document.blocks.filter(b => b.type === 'figure').map(b => required(b.figure)) }] };
+            manifest = { formatVersion: 1, revision: required(job.revision, '草稿版本'), buildKey: job.buildKey, createdAt: job.createdAt, config: { chunkTargetChars: job.config.chunkTargetChars }, catalogs: {}, entities: {}, report: await readReport(job) ?? { revision: required(job.revision), sourceHash: required(job.sourceHash), issues: document.warnings, documents: 1, blocks: document.blocks.length, figures: document.assets.length, ignoredFigures: 0, unreviewedFigures: document.assets.length, chunks: chunks.length, withinTarget: chunks.filter(c => c.fullChars <= job.config.chunkTargetChars).length, oversized: [], usage: job.usage, targetChars: job.config.chunkTargetChars }, coverageIncomplete: true, documents: [{ ...info, nodes, chunks, assets: document.assets, figures: document.blocks.filter(b => b.type === 'figure').map(b => required(b.figure)) }] };
         }
         return { root, manifest, revision: required(job.revision), kbId: job.kbId, jobId };
     }
     async run(job, signal) {
-        const stage = join(job.directory, 'stage'), sourceDir = join(stage, 'sources', job.docId);
+        const stage = join(job.directory, 'stage');
+        const sourceDir = join(stage, 'sources', job.docId);
         try {
             await this.phase(job, 'preflight');
             checkAbort(signal);
@@ -249,20 +273,25 @@ export class Jobs {
             const { catalogs, entities } = await writeIndexes(stage, docs, job.config, job.revision);
             await this.phase(job, 'validating');
             checkAbort(signal);
-            for (const doc of docs)
+            const indexedChunks = new Set(Object.values(catalogs).flatMap(c => c.pages.flatMap(p => p.entries.flatMap(e => e.chunkId ? [e.chunkId] : []))));
+            for (const doc of docs) {
+                const assetIds = new Set(doc.assets.map(a => a.assetId));
                 for (const chunk of doc.chunks) {
                     if (hash(await readFile(await safePath(stage, chunk.path), 'utf8')) !== chunk.contentHash)
                         throw new Error('生成片段哈希不一致');
-                    if (!Object.values(catalogs).some(c => c.pages.some(p => p.entries.some(e => e.chunkId === chunk.chunkId))))
+                    if (!indexedChunks.has(chunk.chunkId))
                         throw new Error('索引遗漏片段');
                     for (const assetId of chunk.assetRefs)
-                        if (!doc.assets.some(a => a.assetId === assetId))
+                        if (!assetIds.has(assetId))
                             throw new Error('片段引用不存在的图片');
                 }
+            }
             const report = { revision: job.revision, sourceHash: required(job.sourceHash, '原件哈希'), issues, documents: docs.length, blocks: document.blocks.length, figures: figureResults.length, ignoredFigures: figureResults.filter(f => f.status === 'ignored').length, unreviewedFigures: figureResults.filter(f => !f.humanReviewed && f.status !== 'decoration').length, chunks: chunks.length, withinTarget: chunks.filter(c => c.fullChars <= job.config.chunkTargetChars).length, oversized: chunks.filter(c => c.oversizedReason).map(c => ({ chunkId: c.chunkId, chars: c.fullChars, reason: required(c.oversizedReason) })), usage: job.usage, targetChars: job.config.chunkTargetChars, ...document.sourceFormat === 'pdf' ? { pdf: { pageCount: required(document.pageCount), selectedPages: required(document.selectedPages), outlineCount: document.audit.outlineCount, matchedBookmarks: document.audit.matchedBookmarks, ocrPages: document.audit.pages.filter(p => p.ocr).length, pages: document.audit.pages } } : {} };
             await atomicWrite(join(stage, 'reports/quality.json'), report);
             await atomicWrite(join(stage, 'reports/quality.md'), `# 构建质量报告\n\n文档 ${report.documents}；本次片段 ${report.chunks}；目标内 ${report.withinTarget}；图片 ${report.figures}；已忽略 ${report.ignoredFigures}；未人工核验 ${report.unreviewedFigures}。\n\n` + issues.map(i => `- ${i.blocking ? '需要处理' : '提示'}：${i.message}`).join('\n') + '\n');
-            job.report = report;
+            await saveReport(job.directory, report);
+            delete job.report;
+            job.reportSummary = summarizeReport(report);
             await job.checkpoint();
             const documents = docs.map(d => ({ ...d, chunks: d.chunks.map(({ content: _content, body: _body, ...chunk }) => chunk) }));
             const manifest = { formatVersion: 1, revision: job.revision, buildKey: job.buildKey, createdAt: now(), documents, catalogs, entities, coverageIncomplete: docs.some(d => d.coverageIncomplete), config: { chunkTargetChars: job.config.chunkTargetChars }, report };
@@ -292,7 +321,7 @@ export class Jobs {
     async actionUnlocked(jobId, action, options = {}) {
         const job = this.get(jobId);
         if (action === 'status')
-            return this.public(job);
+            return this.details(jobId);
         if (action === 'cancel') {
             if (job.state === 'ready')
                 throw new Error('已发布任务不能取消');
@@ -307,18 +336,18 @@ export class Jobs {
         else if (action === 'retry') {
             if (!RESUMABLE.has(job.state) || this.controllers.has(jobId))
                 throw new Error('任务尚未退出或不能重试');
+            if (options.maxModelCalls !== undefined && (!Number.isSafeInteger(options.maxModelCalls) || options.maxModelCalls < 1 || options.maxModelCalls > this.config.maxModelCallsLimit))
+                throw new Error('模型调用预算超过宿主上限或无效');
+            if (options.maxModelTokens !== undefined && (!Number.isSafeInteger(options.maxModelTokens) || options.maxModelTokens < 1 || options.maxModelTokens > this.config.maxModelTokensLimit))
+                throw new Error('模型 token 预算超过宿主上限或无效');
+            job.config.maxModelCallsLimit = this.config.maxModelCallsLimit;
+            job.config.maxModelTokensLimit = this.config.maxModelTokensLimit;
             if (options.acceptPartial === true)
                 job.config.acceptPartial = true;
-            if (options.maxModelCalls !== undefined) {
-                if (!Number.isSafeInteger(options.maxModelCalls) || options.maxModelCalls < 1)
-                    throw new Error('模型调用预算无效');
+            if (options.maxModelCalls !== undefined)
                 job.config.maxModelCalls = options.maxModelCalls;
-            }
-            if (options.maxModelTokens !== undefined) {
-                if (!Number.isSafeInteger(options.maxModelTokens) || options.maxModelTokens < 1)
-                    throw new Error('模型 token 预算无效');
+            if (options.maxModelTokens !== undefined)
                 job.config.maxModelTokens = options.maxModelTokens;
-            }
             job.cancelRequested = false;
             job.error = null;
             await this.phase(job, 'queued');
@@ -334,7 +363,9 @@ export class Jobs {
     async reviewUnlocked(kbId, revision, docId, occurrenceId, value, expectedHash, options = {}) {
         if (Boolean(options.visionProvider) !== Boolean(options.visionModel))
             throw new Error('visionProvider / visionModel 必须成对配置');
-        const snapshot = await this.store.revision(kbId, revision), doc = snapshot.manifest.documents.find(d => d.docId === docId), figure = doc?.figures.find(f => f.occurrenceId === occurrenceId);
+        const snapshot = await this.store.revision(kbId, revision);
+        const doc = snapshot.manifest.documents.find(d => d.docId === docId);
+        const figure = doc?.figures.find(f => f.occurrenceId === occurrenceId);
         if (!figure)
             throw new Error('图片不存在');
         const current = await this.store.current(kbId);
@@ -343,7 +374,8 @@ export class Jobs {
         const original = await this.store.rawSource(kbId, required(doc));
         const previous = [...this.jobs.values()].find(j => j.revision === revision && j.docId === docId);
         const vision = options.visionProvider && options.visionModel ? { provider: options.visionProvider, model: options.visionModel } : previous?.routes.vision || required(doc).figures.find(f => f.model)?.model || (this.config.visionProvider ? { provider: this.config.visionProvider, model: this.config.visionModel } : null);
-        const overlays = await this.store.overlays(kbId), previousOverlay = overlays[figure.overlayKey] || null;
+        const overlays = await this.store.overlays(kbId);
+        const previousOverlay = overlays[figure.overlayKey] || null;
         if (options.restore) {
             if (!previousOverlay?.ignore)
                 throw new Error('仅已忽略的图片可以恢复导入');
@@ -360,7 +392,8 @@ export class Jobs {
     }
     async trash(kbId, expectedName) {
         return this.mutate(async () => {
-            const kb = await this.store.kb(kbId), related = [...this.jobs.values()].filter(j => j.kbId === kb.kbId);
+            const kb = await this.store.kb(kbId);
+            const related = [...this.jobs.values()].filter(j => j.kbId === kb.kbId);
             if (this.work.has(kb.kbId) || related.some(j => ACTIVE.has(j.state) || this.controllers.has(j.jobId)))
                 throw new Error('知识库仍有构建任务未退出，请先取消或等待完成后删除');
             const removed = await this.store.trash(kb.kbId, expectedName);
@@ -373,7 +406,7 @@ export class Jobs {
         return this.mutate(async () => {
             const kb = await this.store.restore(kbId);
             for (const dir of await this.store.jobDirectories()) {
-                const record = await readJson(join(dir, 'job.json'), jobSchema, null);
+                const record = await loadJob(dir);
                 if (record?.kbId === kb.kbId)
                     this.jobs.set(record.jobId, this.attach(record, dir));
             }
@@ -395,7 +428,7 @@ export class Jobs {
             const jobIds = related.map(j => j.jobId);
             if (!kb.purge)
                 for (const dir of await this.store.jobDirectories()) {
-                    const record = await readJson(await safePath(dir, 'job.json', false), jobSchema, null);
+                    const record = await loadJob(dir);
                     if (record?.kbId !== kb.kbId)
                         continue;
                     const key = id(basename(dir), 'jobId');
@@ -417,7 +450,7 @@ export class Jobs {
             else
                 await new Promise(r => setTimeout(r, 0));
         }
-        return this.public(this.get(jobId));
+        return this.details(jobId);
     }
     stop() {
         this.stopped = true;

package/lib/models.d.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
-import { z } from 'zod';
+import type { z } from 'zod';
 import type { Settings } from './config.ts';
 import type { Job, ModelRoute } from './data.ts';
 export type PreparedImage = {

package/lib/models.js

@@ -1,5 +1,4 @@
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { z } from 'zod';
 import { atomicWrite, checkAbort, chars, message, now, readJson, tokensUsed } from "./util.js";
 import { join } from 'node:path';
 export class BudgetError extends Error {
@@ -27,13 +26,20 @@ export class Models {
         const route = job.routes[kind];
         if (!route)
             throw new Error(`${kind} 模型不可用`);
-        if (job.usage.calls >= job.config.maxModelCalls || job.usage.tokens >= job.config.maxModelTokens)
+        if (job.usage.calls >= Math.min(job.config.maxModelCalls, this.config.maxModelCallsLimit) || job.usage.tokens >= Math.min(job.config.maxModelTokens, this.config.maxModelTokensLimit))
             throw new BudgetError('已达到本次构建模型调用/实际 token 预算；调整预算后重试可继续');
-        const number = ++job.usage.calls, file = join(job.directory, 'calls', `${String(number).padStart(6, '0')}.json`);
-        const controller = new AbortController(), timeout = setTimeout(() => controller.abort(new Error('模型调用超时')), job.config.modelTimeoutMs);
+        const number = ++job.usage.calls;
+        job.pendingCalls.push(number);
+        const file = join(job.directory, 'calls', `${String(number).padStart(6, '0')}.json`);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('模型调用超时')), job.config.modelTimeoutMs);
         const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
         const request = { kind, route, prompt, system, images, startedAt: now(), maxTokens: job.config.modelMaxOutputTokens };
-        let response = '', complete = '', usage, finish, accounted = false;
+        let response = '';
+        let complete = '';
+        let usage;
+        let finish;
+        let accounted = false;
         const account = () => {
             if (accounted)
                 return;
@@ -41,8 +47,8 @@ export class Models {
             job.usage.tokens += tokensUsed(usage);
             if (usage) {
                 job.usage.reportedCalls++;
-                job.usage.records.push(z.json().parse(JSON.parse(JSON.stringify(usage))));
             }
+            job.pendingCalls = job.pendingCalls.filter(n => n !== number);
         };
         try {
             await job.checkpoint();
@@ -68,14 +74,14 @@ export class Models {
                 throw new Error(finish && 'failure' in finish ? finish.failure.message : `模型未正常完成：${finish?.kind ?? '缺少结束事件'}`);
             if (!response.trim())
                 throw new Error('模型返回空内容');
-            account();
             await atomicWrite(file, { request, state: 'done', response, usage, finishedAt: now() });
+            account();
             await job.checkpoint();
             return response;
         }
         catch (error) {
-            account();
             await atomicWrite(file, { request, state: 'failed', response, usage, error: message(error), finishedAt: now() });
+            account();
             await job.checkpoint();
             throw error;
         }
@@ -101,7 +107,7 @@ export class Models {
         if (job.config.skipImages)
             return;
         const info = await this.resolve(job.routes.vision, 'vision', signal);
-        const { Jimp } = await import('jimp'), data = await new Jimp({ width: 32, height: 32, color: 0xffffffff }).getBuffer('image/png');
+        const data = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAQ0lEQVR4AcXBAQEAAAiAIPP/5+qFMPsISUxiEpOYxCQmMYlJTGISk5jEJCYxiUlMYhKTmMQkJjGJSUxiEpOYxCQmsQNNiAQ8n/3A9AAAAABJRU5ErkJggg==', 'base64');
         const attachment = await this.ctx.attachments.saveImage({ data, mediaType: 'image/png', name: 'kb-vision-preflight.png' });
         const response = await this.call(job, 'vision', '这是图片接口连通性检查。能读取图像时只返回 READY。', [{ attachment, coordinates: { kind: 'preflight' } }], signal, '检查是否实际收到图片，简短回答。');
         if (response.trim() !== 'READY')

package/lib/retrieval.js

@@ -37,10 +37,12 @@ function windows(chunk, content, terms, config, options = {}) {
     }
     const ordered = [...indices].sort((a, b) => a - b);
     const read = [];
-    let body = '', continuation = null;
+    let body = '';
+    let continuation = null;
     const max = Math.max(128, Math.min(config.evidenceMaxChars - 2000, options.windowBudget || config.evidenceMaxChars - 2000));
     for (const i of ordered) {
-        const s = required(chunk.segments[i], '语义块'), heading = s.startLine === undefined || s.endLine === undefined ? `[${s.type} · segment ${i}]\n` : `[L${s.startLine}–L${s.endLine} · ${s.type}]\n`;
+        const s = required(chunk.segments[i], '语义块');
+        const heading = s.startLine === undefined || s.endLine === undefined ? `[${s.type} · segment ${i}]\n` : `[L${s.startLine}–L${s.endLine} · ${s.type}]\n`;
         let value = s.text;
         const start = options.segmentIndex === i ? options.offset || 0 : 0;
         if (start > chars(value))
@@ -51,11 +53,31 @@ function windows(chunk, content, terms, config, options = {}) {
                 continuation = { segmentIndex: i, offset: 0 };
                 break;
             }
-            const characters = Array.from(s.text), hit = terms.map(t => value.toLowerCase().indexOf(t)).filter(x => x >= 0).sort((a, b) => a - b)[0];
-            const offset = options.segmentIndex !== undefined ? start : (hit === undefined ? 0 : Math.max(0, chars(value.slice(0, hit)) - 250));
+            const characters = Array.from(s.text);
+            const hit = terms.map(t => value.toLowerCase().indexOf(t)).filter(x => x >= 0).sort((a, b) => a - b)[0];
+            let offset;
+            if (options.segmentIndex !== undefined) {
+                offset = start;
+            }
+            else {
+                if (hit === undefined) {
+                    offset = 0;
+                }
+                else {
+                    offset = Math.max(0, chars(value.slice(0, hit)) - 250);
+                }
+            }
             const available = max - chars(heading) - 50;
             value = clip(characters.slice(offset).join(''), available);
-            continuation = offset + chars(value) < characters.length ? { segmentIndex: i, offset: offset + chars(value) } : i + 1 < chunk.segments.length ? { segmentIndex: i + 1, offset: 0 } : null;
+            continuation = (() => {
+                if (offset + chars(value) < characters.length) {
+                    return { segmentIndex: i, offset: offset + chars(value) };
+                }
+                if (i + 1 < chunk.segments.length) {
+                    return { segmentIndex: i + 1, offset: 0 };
+                }
+                return null;
+            })();
             read.push({ segmentIndex: i, startLine: s.startLine, endLine: s.endLine, charOffset: offset, partial: true });
             body += heading + value + '\n[此语义块仅返回部分，请按 continuation 续读]\n';
             break;
@@ -76,7 +98,8 @@ export class Retrieval {
     }
     async catalog(args = {}) {
         if (!args.kbId) {
-            const kbs = await this.store.list(), entries = [];
+            const kbs = await this.store.list();
+            const entries = [];
             for (const kb of kbs) {
                 const current = await this.store.current(kb.kbId);
                 entries.push({ ...kb, revision: current?.revision || null, coverageIncomplete: current?.coverageIncomplete || false });
@@ -88,7 +111,7 @@ export class Retrieval {
             }
             return bounded(value, this.config.catalogMaxChars);
         }
-        const kb = await this.store.kb(args.kbId), snapshot = await this.store.revision(kb.kbId, args.revision);
+        const { kb, snapshot } = await this.store.open(args.kbId, args.revision);
         const catalogId = args.docId ? `${id(args.docId)}-${args.nodeId ? id(args.nodeId) : 'root'}` : 'root';
         const catalog = snapshot.manifest.catalogs[catalogId];
         if (!catalog)
@@ -102,14 +125,17 @@ export class Retrieval {
         return bounded(value, this.config.catalogMaxChars + 1000);
     }
     async search(args) {
-        const kb = await this.store.kb(args.kbId), snapshot = await this.store.revision(kb.kbId, args.revision);
-        const terms = queryTerms(args.query, args.keywords), scored = [];
+        const { kb, snapshot } = await this.store.open(args.kbId, args.revision);
+        const terms = queryTerms(args.query, args.keywords);
+        const scored = [];
         for (const doc of snapshot.manifest.documents) {
             if (args.docId && doc.docId !== args.docId)
                 continue;
             for (const chunk of doc.chunks) {
-                const content = await this.store.chunkContent(snapshot, chunk), body = content.toLowerCase();
-                const hits = terms.filter(t => body.includes(t)), title = chunk.headingPath.join('/').toLowerCase(), keys = (chunk.keywords || []).map(k => k.toLowerCase());
+                const { content, lower: body } = await this.store.chunkView(snapshot, chunk);
+                const hits = terms.filter(t => body.includes(t));
+                const title = chunk.headingPath.join('/').toLowerCase();
+                const keys = (chunk.keywords || []).map(k => k.toLowerCase());
                 if (!hits.length)
                     continue;
                 const score = hits.reduce((n, t) => n + (keys.includes(t) ? 12 : 0) + (title.includes(t) ? 6 : 0) + Math.min(5, body.split(t).length - 1), 0);
@@ -122,7 +148,9 @@ export class Retrieval {
             throw new Error('limit 必须为 1–30');
         const value = { kbId: kb.kbId, revision: snapshot.revision, query: args.query, terms, candidates: [], evidence: [], warnings: [], truncated: scored.length > limit, totalCandidates: scored.length, continuation: [] };
         const top = scored.slice(0, limit);
-        for (const { doc, chunk, score, hits, content } of top) {
+        for (const { doc, chunk, score, hits } of top) {
+            // Cached scoring is navigation only; returned evidence is always reread and hash-verified.
+            const content = await this.store.chunkContent(snapshot, chunk);
             const candidate = { chunkId: chunk.chunkId, score, matchedTerms: hits, title: chunk.title, summary: chunk.summary, fullChars: chunk.fullChars, reviewStatus: chunk.reviewStatus, source: source(required(doc), chunk, snapshot.revision) };
             value.candidates.push(candidate);
             const remaining = this.config.evidenceMaxChars - chars(JSON.stringify(value)) - 800;
@@ -145,10 +173,13 @@ export class Retrieval {
                 break;
             }
         }
+        await this.store.kb(kb.kbId); // Recheck visibility after potentially long scoring/evidence reads.
         return bounded(value, this.config.evidenceMaxChars);
     }
     async read(args) {
-        const kb = await this.store.kb(args.kbId), snapshot = await this.store.readChunk(kb.kbId, args.revision, args.chunkId);
+        const kb = await this.store.kb(args.kbId);
+        const snapshot = await this.store.readChunk(kb.kbId, args.revision, args.chunkId);
+        await this.store.kb(kb.kbId);
         return this.readSnapshot(kb.kbId, snapshot, args);
     }
     readSnapshot(kbId, snapshot, args) {

package/lib/revision-cache.d.ts

@@ -0,0 +1,24 @@
+import type { Manifest } from './data.ts';
+/** Bounded hot revision payloads. Every lookup checks file identity; evidence reads bypass reuse. */
+export declare class RevisionCache {
+    readonly maxBytes: number;
+    readonly maxEntries: number;
+    private entries;
+    bytes: number;
+    reads: number;
+    hits: number;
+    parses: number;
+    get size(): number;
+    constructor(maxBytes?: number, maxEntries?: number);
+    clear(): void;
+    private drop;
+    private put;
+    private stamp;
+    private lookup;
+    private read;
+    manifest(file: string): Promise<Manifest>;
+    chunk(file: string, digest: string, fresh?: boolean): Promise<{
+        content: string;
+        lower: string;
+    }>;
+}

package/lib/revision-cache.js

@@ -0,0 +1,100 @@
+import { stat, readFile } from 'node:fs/promises';
+import { manifestSchema } from "./data.js";
+import { hash } from "./util.js";
+function freeze(value) { if (value && typeof value === 'object') {
+    for (const child of Object.values(value))
+        freeze(child);
+    Object.freeze(value);
+} return value; }
+/** Bounded hot revision payloads. Every lookup checks file identity; evidence reads bypass reuse. */
+export class RevisionCache {
+    maxBytes;
+    maxEntries;
+    entries = new Map();
+    bytes = 0;
+    reads = 0;
+    hits = 0;
+    parses = 0;
+    get size() { return this.entries.size; }
+    constructor(maxBytes = 32 * 1024 * 1024, maxEntries = 256) {
+        this.maxBytes = maxBytes;
+        this.maxEntries = maxEntries;
+    }
+    clear() { this.entries.clear(); this.bytes = 0; }
+    drop(file) { const old = this.entries.get(file); if (old)
+        this.bytes -= old.cost; this.entries.delete(file); }
+    put(file, entry) {
+        this.drop(file);
+        if (entry.cost > this.maxBytes || this.maxEntries < 1)
+            return;
+        while (this.entries.size >= this.maxEntries || this.bytes + entry.cost > this.maxBytes) {
+            const first = this.entries.keys().next().value;
+            if (first === undefined)
+                break;
+            this.drop(first);
+        }
+        this.entries.set(file, entry);
+        this.bytes += entry.cost;
+    }
+    async stamp(file) {
+        const info = await stat(file, { bigint: true });
+        if (!info.isFile())
+            throw new Error('版本文件必须是普通文件');
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+    }
+    async lookup(file) {
+        let stamp;
+        try {
+            stamp = await this.stamp(file);
+        }
+        catch (error) {
+            this.drop(file);
+            throw error;
+        }
+        const entry = this.entries.get(file);
+        if (entry?.stamp === stamp) {
+            this.drop(file);
+            this.entries.set(file, entry);
+            this.bytes += entry.cost;
+            return { stamp, entry };
+        }
+        this.drop(file);
+        return { stamp, entry: undefined };
+    }
+    async read(file, stamp) {
+        this.reads++;
+        const content = await readFile(file, 'utf8');
+        if (await this.stamp(file) !== stamp) {
+            this.drop(file);
+            throw new Error('版本文件读取期间变化，请重试');
+        }
+        return content;
+    }
+    async manifest(file) {
+        const { stamp, entry } = await this.lookup(file);
+        if (entry?.kind === 'manifest') {
+            this.hits++;
+            return entry.value;
+        }
+        const raw = await this.read(file, stamp);
+        this.parses++;
+        const value = freeze(manifestSchema.parse(JSON.parse(raw)));
+        this.put(file, { kind: 'manifest', stamp, value, cost: raw.length * 8 + 512 });
+        return value;
+    }
+    async chunk(file, digest, fresh = false) {
+        const { stamp, entry } = await this.lookup(file);
+        if (!fresh && entry?.kind === 'chunk' && entry.digest === digest) {
+            this.hits++;
+            return { content: entry.value, lower: entry.lower };
+        }
+        const content = await this.read(file, stamp);
+        if (hash(content) !== digest) {
+            this.drop(file);
+            throw new Error('片段内容与清单不一致，请重建');
+        }
+        const lower = content.toLowerCase();
+        this.put(file, { kind: 'chunk', stamp, value: content, lower, digest, cost: (content.length + lower.length) * 2 + 512 });
+        return { content, lower };
+    }
+}