@dsh-libing/knowledge-base 0.1.3 → 0.1.4

package/lib/document/zip.js

@@ -12,17 +12,24 @@ export function unpackDocx(buffer, config) {
     }
     if (end < 0)
         throw new Error('无效 DOCX ZIP 文件');
-    const count = buffer.readUInt16LE(end + 10), size = buffer.readUInt32LE(end + 12), start = buffer.readUInt32LE(end + 16);
+    const count = buffer.readUInt16LE(end + 10);
+    const size = buffer.readUInt32LE(end + 12);
+    const start = buffer.readUInt32LE(end + 16);
     if (count === 65535 || count > config.maxArchiveEntries || start + size > end || buffer.readUInt16LE(end + 4) !== 0)
         throw new Error('不支持的分卷/ZIP64 或过多 ZIP 条目');
-    let pos = start, total = 0;
+    let pos = start;
+    let total = 0;
     const entries = new Map();
     for (let n = 0; n < count; n++) {
         if (pos + 46 > end || buffer.readUInt32LE(pos) !== 0x02014b50)
             throw new Error('损坏的 ZIP 目录');
-        const flags = buffer.readUInt16LE(pos + 8), method = buffer.readUInt16LE(pos + 10);
-        const compressed = buffer.readUInt32LE(pos + 20), uncompressed = buffer.readUInt32LE(pos + 24);
-        const nameLength = buffer.readUInt16LE(pos + 28), extraLength = buffer.readUInt16LE(pos + 30), commentLength = buffer.readUInt16LE(pos + 32);
+        const flags = buffer.readUInt16LE(pos + 8);
+        const method = buffer.readUInt16LE(pos + 10);
+        const compressed = buffer.readUInt32LE(pos + 20);
+        const uncompressed = buffer.readUInt32LE(pos + 24);
+        const nameLength = buffer.readUInt16LE(pos + 28);
+        const extraLength = buffer.readUInt16LE(pos + 30);
+        const commentLength = buffer.readUInt16LE(pos + 32);
         const next = pos + 46 + nameLength + extraLength + commentLength;
         if (next > end || uncompressed === 0xffffffff || compressed === 0xffffffff)
             throw new Error('损坏或不支持的 ZIP 条目');
@@ -34,7 +41,8 @@ export function unpackDocx(buffer, config) {
         const local = buffer.readUInt32LE(pos + 42);
         if (local + 30 > start || buffer.readUInt32LE(local) !== 0x04034b50)
             throw new Error('损坏的 ZIP 本地条目');
-        const localNameLength = buffer.readUInt16LE(local + 26), localExtra = buffer.readUInt16LE(local + 28);
+        const localNameLength = buffer.readUInt16LE(local + 26);
+        const localExtra = buffer.readUInt16LE(local + 28);
         if (buffer.subarray(local + 30, local + 30 + localNameLength).toString('utf8') !== name || local + 30 + localNameLength + localExtra + compressed > start)
             throw new Error('ZIP 条目不一致');
         total += uncompressed;

package/lib/figures/image-client.js

@@ -7,12 +7,17 @@ import { imageMessageSchema, imageOptionsSchema } from "./image-protocol.js";
 export async function runImageWorker(file, config, save, signal) {
     const options = imageOptionsSchema.parse({ visionMaxEdge: config.visionMaxEdge, visionTileSize: config.visionTileSize, visionMaxTiles: config.visionMaxTiles });
     const release = await imageGate.acquire(signal);
-    let worker, saving;
-    const result = deferred(), abort = () => result.reject(signal?.reason ?? new Error('图片预处理已取消'));
-    let timer, complete = false, next = 1;
+    let worker;
+    let saving;
+    const result = deferred();
+    const abort = () => result.reject(signal?.reason ?? new Error('图片预处理已取消'));
+    let timer;
+    let complete = false;
+    let next = 1;
     try {
         checkAbort(signal);
-        const js = new URL('./image-worker.js', import.meta.url), source = !existsSync(fileURLToPath(js));
+        const js = new URL('./image-worker.js', import.meta.url);
+        const source = !existsSync(fileURLToPath(js));
         worker = new Worker(source ? new URL('./image-worker.ts', import.meta.url) : js, { workerData: { file, options }, execArgv: source ? ['--import', 'tsx/esm'] : [], resourceLimits: { maxOldGenerationSizeMb: 512 } });
         const current = worker;
         timer = setTimeout(() => result.reject(new Error('图片预处理超时')), Math.min(config.imageTimeoutMs, 120000));

package/lib/figures/image-worker.js

@@ -10,16 +10,21 @@ async function run() {
     const { file, options } = z.object({ file: z.string(), options: imageOptionsSchema }).parse(workerData);
     if ((await stat(file)).size > 32 * 1024 * 1024)
         throw new Error('单张图片超过 32 MiB，请提供较小的位图');
-    const data = await readFile(file), dimensions = imageSize(data);
+    const data = await readFile(file);
+    const dimensions = imageSize(data);
     if (data.length > 32 * 1024 * 1024)
         throw new Error('单张图片超过 32 MiB，请提供较小的位图');
     if (!dimensions.width || !dimensions.height || dimensions.width * dimensions.height > 50000000)
         throw new Error('图片像素过大，请提供分辨率较低的版本');
-    const image = await Jimp.read(data), { width, height } = image.bitmap;
+    const image = await Jimp.read(data);
+    const { width, height } = image.bitmap;
     if (width * height > 50000000)
         throw new Error('图片像素过大，请提供分辨率较低的版本');
-    const tile = options.visionTileSize, step = Math.max(1, Math.floor(tile * .85)), tiled = Math.max(width, height) > options.visionMaxEdge;
-    const columns = Math.max(1, Math.ceil((width - tile) / step) + 1), rows = Math.max(1, Math.ceil((height - tile) / step) + 1);
+    const tile = options.visionTileSize;
+    const step = Math.max(1, Math.floor(tile * .85));
+    const tiled = Math.max(width, height) > options.visionMaxEdge;
+    const columns = Math.max(1, Math.ceil((width - tile) / step) + 1);
+    const rows = Math.max(1, Math.ceil((height - tile) / step) + 1);
     if (tiled && columns * rows > options.visionMaxTiles)
         throw new Error(`大图需要 ${columns * rows} 个裁片，超过 visionMaxTiles；请拆分图片或提高上限`);
     let id = 0;
@@ -27,7 +32,8 @@ async function run() {
         const bytes = await bitmap.getBuffer('image/png');
         if (bytes.length > 8 * 1024 * 1024)
             throw new Error('图像转换后超过单张 8 MiB，请降低 visionTileSize');
-        const packet = new Uint8Array(bytes), current = ++id;
+        const packet = new Uint8Array(bytes);
+        const current = ++id;
         const acknowledged = new Promise((resolve, reject) => port.once('message', raw => {
             const ack = z.object({ ack: z.literal(current) }).safeParse(raw);
             if (ack.success)
@@ -48,7 +54,10 @@ async function run() {
     if (tiled)
         for (let row = 0; row < rows; row++)
             for (let col = 0; col < columns; col++) {
-                const x = Math.min(col * step, Math.max(0, width - tile)), y = Math.min(row * step, Math.max(0, height - tile)), w = Math.min(tile, width), h = Math.min(tile, height);
+                const x = Math.min(col * step, Math.max(0, width - tile));
+                const y = Math.min(row * step, Math.max(0, height - tile));
+                const w = Math.min(tile, width);
+                const h = Math.min(tile, height);
                 // Copy only the requested region; never clone the full source for a tile.
                 const bitmap = new Jimp({ width: w, height: h });
                 for (let line = 0; line < h; line++)

package/lib/figures/process.js

@@ -45,8 +45,10 @@ export async function processFigures(document, sourceDir, job, models, signal, o
             checkAbort(signal);
             job.progress.inflightFigures = [...(job.progress.inflightFigures || []), { occurrenceId: block.occurrenceId, caption: block.caption || block.occurrenceId }];
             await job.checkpoint();
-            const asset = document.assets.find(x => x.assetId === block.assetId), resultPath = join(sourceDir, 'figures', block.occurrenceId + '.json');
-            const overlayKey = hash({ assetId: block.assetId, context }), overlay = overlays[overlayKey];
+            const asset = document.assets.find(x => x.assetId === block.assetId);
+            const resultPath = join(sourceDir, 'figures', block.occurrenceId + '.json');
+            const overlayKey = hash({ assetId: block.assetId, context });
+            const overlay = overlays[overlayKey];
             const cacheKey = hash({ assetId: block.assetId, context, route: job.routes.vision, prompt: PROMPT_VERSION, params: { maxEdge: job.config.visionMaxEdge, tile: job.config.visionTileSize, maxChars: job.config.figureMaxChars } });
             let result = await readJson(resultPath, figureSchema, null);
             const overlayHash = hash(overlay || null);
@@ -60,7 +62,15 @@ export async function processFigures(document, sourceDir, job, models, signal, o
                     if (!asset)
                         throw new Error('未提取原图');
                     if (overlay)
-                        result = figureSchema.parse({ ...overlay, cacheKey, overlayKey, overlayHash, assetId: block.assetId, occurrenceId: block.occurrenceId, caption: block.caption, status: overlay.ignore ? 'ignored' : overlay.skip ? 'decoration' : 'reviewed', humanReviewed: true });
+                        result = figureSchema.parse({ ...overlay, cacheKey, overlayKey, overlayHash, assetId: block.assetId, occurrenceId: block.occurrenceId, caption: block.caption, status: (() => {
+                                if (overlay.ignore) {
+                                    return 'ignored';
+                                }
+                                if (overlay.skip) {
+                                    return 'decoration';
+                                }
+                                return 'reviewed';
+                            })(), humanReviewed: true });
                     else if (job.config.skipImages)
                         result = figureSchema.parse({ status: 'skipped', cacheKey, overlayKey, overlayHash, assetId: block.assetId, occurrenceId: block.occurrenceId, caption: block.caption, description: '本次明确跳过图片理解', needsReview: true, uncertainties: ['未分析图片'] });
                     else {

package/lib/index.js

@@ -3,6 +3,7 @@ import { createRuntime } from "./runtime.js";
 import { routes } from "./routes.js";
 import { tools } from "./tools.js";
 import { skillProvider } from "./skills.js";
+import { registerKnowledgeCatalog } from "./agent-access.js";
 export { Config } from "./config.js";
 export { createRuntime } from "./runtime.js";
 export const name = 'libing-knowledge-base';
@@ -10,7 +11,8 @@ export const inject = ['connection', 'tools', 'skills', 'llm', 'attachments'];
 const lifetimes = new Map();
 /** Context owns all registrations and drains durable work before releasing the data root. */
 export async function apply(ctx, config = {}) {
-    const resolved = resolveConfig(config), previous = lifetimes.get(resolved.dataRoot);
+    const resolved = resolveConfig(config);
+    const previous = lifetimes.get(resolved.dataRoot);
     const scope = { disposed: false };
     // Own cancellation before awaiting a previous generation; disposal during that wait must not leak a newly created runtime.
     ctx.effect(() => () => {
@@ -28,13 +30,15 @@ export async function apply(ctx, config = {}) {
         await previous.closing;
     if (scope.disposed)
         return;
-    const runtime = createRuntime(ctx, resolved), lifetime = { runtime };
+    const runtime = createRuntime(ctx, resolved);
+    const lifetime = { runtime };
     scope.owned = lifetime;
     if (!lifetimes.has(resolved.dataRoot))
         lifetimes.set(resolved.dataRoot, lifetime);
     await runtime.ready;
     if (scope.disposed)
         return;
+    registerKnowledgeCatalog(ctx, runtime);
     for (const definition of tools(runtime))
         ctx.tools.register(definition);
     ctx.effect(() => ctx.skills.registerProvider(() => skillProvider()), 'libing-knowledge-base: bundled skills');

package/lib/indexes.js

@@ -12,7 +12,8 @@ export async function summarizeChunks(chunks, job, models, signal) {
     for (const chunk of chunks) {
         job.progress.currentChunk = { title: chunk.title, headingPath: chunk.headingPath, chunkId: chunk.chunkId };
         await job.checkpoint();
-        let summary, fallback = false;
+        let summary;
+        let fallback = false;
         if (job.routes.summary) {
             try {
                 const key = hash({ content: chunk.contentHash, route: job.routes.summary, max: job.config.summaryMaxChars, schema: job.schemaHash, prompt: 1 });
@@ -43,11 +44,13 @@ export async function summarizeChunks(chunks, job, models, signal) {
 }
 /** Every node is a bounded navigation page; overflow is split into linked pages. */
 export async function writeIndexes(dir, documents, config, revision) {
-    const catalogs = {}, entities = {};
+    const catalogs = {};
+    const entities = {};
     const writeCatalog = async (catalogId, path, title, entries) => {
         const intro = `# ${mdText(title)}\n\n版本：${revision}\n\n`;
         const pageEntries = [];
-        let group = [], length = chars(intro);
+        let group = [];
+        let length = chars(intro);
         for (const entry of entries) {
             const line = entry.line || `- [${mdText(entry.title)}](${posix.relative(posix.dirname(path), required(entry.path))}) — ${mdText(entry.summary)}；docId=${entry.docId}${entry.nodeId ? '; nodeId=' + entry.nodeId : ''}${entry.chunkId ? '; chunkId=' + entry.chunkId : ''}；${entry.fullChars || 0} 字符；${mdText((entry.keywords || []).slice(0, 12).join('、'))}；${entry.reviewStatus || ''}${entry.pdfScope ? '；' + mdText(entry.pdfScope) : ''}${entry.pageRange ? '；PDF第' + entry.pageRange.join('–') + '页' : ''}\n`;
             if (group.length && length + chars(line) > config.catalogMaxChars - 300) {
@@ -61,7 +64,8 @@ export async function writeIndexes(dir, documents, config, revision) {
         pageEntries.push(group);
         catalogs[catalogId] = { catalogId, path, title, pages: [] };
         for (let i = 0; i < pageEntries.length; i++) {
-            const pagePath = i === 0 ? path : path.replace(/\.md$/, `-${i + 1}.md`), next = i + 1 < pageEntries.length ? path.replace(/\.md$/, `-${i + 2}.md`) : null;
+            const pagePath = i === 0 ? path : path.replace(/\.md$/, `-${i + 1}.md`);
+            const next = i + 1 < pageEntries.length ? path.replace(/\.md$/, `-${i + 2}.md`) : null;
             const content = intro + required(pageEntries[i]).map(x => x.line).join('') + (next ? `\n[下一页索引](${posix.basename(next)})\n` : '');
             if (chars(content) > config.catalogMaxChars)
                 throw new Error('单个索引条目超过导航预算，请提高 catalogMaxChars 或缩短标题');

package/lib/job-storage.js

@@ -32,7 +32,8 @@ export async function loadJob(directory) {
     if (record.jobId !== basename(directory))
         throw new Error('任务目录与身份不一致');
     if (['queued', 'preflight', 'converting', 'describing', 'splitting', 'indexing', 'validating', 'publishing'].includes(record.state)) {
-        let total = 0, reported = 0;
+        let total = 0;
+        let reported = 0;
         for (let number = 1; number <= record.usage.calls; number++) {
             const receipt = await readJson(await safePath(directory, join('calls', `${String(number).padStart(6, '0')}.json`), false), receiptSchema, null);
             if (receipt?.usage) {
@@ -96,7 +97,8 @@ export async function readReport(job) {
 export async function usagePage(job, offset, limit, signal) {
     if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 50)
         throw new Error('用量分页参数无效');
-    const total = job.legacyUsageCount + Math.max(0, job.usage.calls - job.legacyCallCount), records = [];
+    const total = job.legacyUsageCount + Math.max(0, job.usage.calls - job.legacyCallCount);
+    const records = [];
     const end = Math.min(total, offset + limit);
     let legacy;
     if (offset < job.legacyUsageCount)
@@ -108,7 +110,8 @@ export async function usagePage(job, offset, limit, signal) {
             continue;
         }
         const number = job.legacyCallCount + index - job.legacyUsageCount + 1;
-        const file = await safePath(job.directory, join('calls', `${String(number).padStart(6, '0')}.json`), false), receipt = await readJson(file, receiptSchema, null);
+        const file = await safePath(job.directory, join('calls', `${String(number).padStart(6, '0')}.json`), false);
+        const receipt = await readJson(file, receiptSchema, null);
         records.push(z.json().parse(JSON.parse(JSON.stringify({ call: number, state: receipt?.state ?? 'reserved', usage: receipt?.usage ?? null }))));
     }
     return { records, offset, total, next: end < total ? end : null };

package/lib/jobs.js

@@ -94,7 +94,7 @@ export class Jobs {
         });
         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), { report: _report, ...value } = this.public(job); return { ...value, ...includeReport ? { report: await readReport(job) } : {} }; }
+    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'));
@@ -111,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;
@@ -154,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;
@@ -173,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);
@@ -222,7 +226,8 @@ export class Jobs {
         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);
@@ -358,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);
@@ -367,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('仅已忽略的图片可以恢复导入');
@@ -384,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);

package/lib/models.js

@@ -31,10 +31,15 @@ export class Models {
         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(), timeout = setTimeout(() => controller.abort(new Error('模型调用超时')), job.config.modelTimeoutMs);
+        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;

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 });
@@ -103,13 +126,16 @@ export class Retrieval {
     }
     async search(args) {
         const { kb, snapshot } = await this.store.open(args.kbId, args.revision);
-        const terms = queryTerms(args.query, args.keywords), scored = [];
+        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, lower: body } = await this.store.chunkView(snapshot, chunk);
-                const hits = terms.filter(t => body.includes(t)), title = chunk.headingPath.join('/').toLowerCase(), keys = (chunk.keywords || []).map(k => k.toLowerCase());
+                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);
@@ -151,7 +177,8 @@ export class Retrieval {
         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);
     }

package/lib/routes.js

@@ -6,10 +6,15 @@ import { figureDataSchema, overlaySchema } from "./data.js";
 import { inspectPdf } from "./document/pdf-session.js";
 import { hash, safePath, message, required, fileBytes, checkAbort } from "./util.js";
 const HOST_VERSION = z.object({ version: z.string() }).parse(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))).version;
-const id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,95}$/u), name = z.string().trim().min(1).max(120), digest = z.string().regex(/^[a-f0-9]{64}$/u);
-const libraryArgs = z.strictObject({ kbId: id }), managementArgs = libraryArgs.extend({ confirmName: name });
+const id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,95}$/u);
+const name = z.string().trim().min(1).max(120);
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const libraryArgs = z.strictObject({ kbId: id });
+const managementArgs = libraryArgs.extend({ confirmName: name });
 const reviewSchema = z.strictObject({ kbId: id, revision: id, docId: id, occurrenceId: id, expectedHash: digest, action: z.enum(['reidentify', 'restore']).optional(), figure: z.union([figureDataSchema.strict(), z.strictObject({ ignore: z.literal(true) }), z.strictObject({ skip: z.literal(true) })]).optional(), visionProvider: z.string().optional(), visionModel: z.string().optional() }).refine(value => Boolean(value.action) !== Boolean(value.figure), '指定一个复核操作或内容');
-const draftQuery = z.strictObject({ jobId: id }), sourceQuery = revisionQuerySchema.extend({ docId: id }), draftAssetQuery = draftQuery.extend({ docId: id, assetId: id });
+const draftQuery = z.strictObject({ jobId: id });
+const sourceQuery = revisionQuerySchema.extend({ docId: id });
+const draftAssetQuery = draftQuery.extend({ docId: id, assetId: id });
 const draftReadQuery = draftQuery.extend(readQuerySchema.omit({ kbId: true, revision: true }).shape);
 const headers = { 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer' };
 function query(request) {
@@ -93,32 +98,52 @@ export function routes(runtime, ctx) {
         return store.upload(await bytes(request, config.maxInputBytes), args.filename);
     });
     add('inspect-document', 'POST', async (request) => {
-        const { receiptId } = await body(request, z.strictObject({ receiptId: id })), uploaded = await store.uploaded(receiptId);
+        const { receiptId } = await body(request, z.strictObject({ receiptId: id }));
+        const uploaded = await store.uploaded(receiptId);
         if (!/\.pdf$/iu.test(uploaded.filename))
             throw new Error('文档预检只支持 PDF');
         return inspectPdf(await safePath(store.root, join('uploads', receiptId + '.bin')), config, request.signal);
     });
-    add('source', 'GET', async (request) => { const args = sourceQuery.parse(query(request)), kb = await store.kb(args.kbId); return original({ ...await store.revision(kb.kbId, args.revision), kbId: kb.kbId }, args.docId); });
+    add('source', 'GET', async (request) => { const args = sourceQuery.parse(query(request)); const kb = await store.kb(args.kbId); return original({ ...await store.revision(kb.kbId, args.revision), kbId: kb.kbId }, args.docId); });
     add('draft-source', 'GET', async (request) => { const args = draftQuery.extend({ docId: id }).parse(query(request)); return original(await jobs.preview(args.jobId), args.docId); });
     add('build', 'POST', async (request) => jobs.submit(await body(request, browserBuildSchema)));
     add('job', 'POST', async (request) => { const args = await body(request, jobActionSchema); return jobs.action(args.jobId, args.action, args); });
     add('draft', 'GET', async (request) => { const snapshot = await jobs.preview(draftQuery.parse(query(request)).jobId); return { ...tree(snapshot, snapshot.kbId), previewJobId: snapshot.jobId, coverageIncomplete: true }; });
     add('draft-read', 'GET', async (request) => {
-        const { jobId, ...args } = draftReadQuery.parse(query(request)), snapshot = await jobs.preview(jobId), chunk = required(snapshot.manifest.documents.flatMap(d => d.chunks).find(c => c.chunkId === args.chunkId), '草稿片段');
+        const { jobId, ...args } = draftReadQuery.parse(query(request));
+        const snapshot = await jobs.preview(jobId);
+        const chunk = required(snapshot.manifest.documents.flatMap(d => d.chunks).find(c => c.chunkId === args.chunkId), '草稿片段');
         const value = retrieval.readSnapshot(snapshot.kbId, { ...snapshot, chunk, content: await store.chunkContent(snapshot, chunk) }, { ...args, kbId: snapshot.kbId });
         return { ...value, previewJobId: jobId, warnings: ['待发布预览：未向 Agent 检索开放', ...value.warnings] };
     });
-    add('draft-asset', 'GET', async (request) => { const args = draftAssetQuery.parse(query(request)), snapshot = await jobs.preview(args.jobId), doc = required(snapshot.manifest.documents.find(d => d.docId === args.docId), '草稿文档'), asset = required(doc.assets.find(a => a.assetId === args.assetId), '草稿图片'); return image(asset, await safePath(snapshot.root, join('sources', doc.docId, asset.path))); });
+    add('draft-asset', 'GET', async (request) => { const args = draftAssetQuery.parse(query(request)); const snapshot = await jobs.preview(args.jobId); const doc = required(snapshot.manifest.documents.find(d => d.docId === args.docId), '草稿文档'); const asset = required(doc.assets.find(a => a.assetId === args.assetId), '草稿图片'); return image(asset, await safePath(snapshot.root, join('sources', doc.docId, asset.path))); });
     add('catalog', 'GET', async (request) => retrieval.catalog(catalogQuerySchema.parse(query(request))));
-    add('tree', 'GET', async (request) => { const args = revisionQuerySchema.parse(query(request)), { kb, snapshot } = await store.open(args.kbId, args.revision), overlays = await store.overlays(kb.kbId), value = tree(snapshot, kb.kbId); return { ...value, location: await store.snapshotLocation(kb.kbId, snapshot), documents: value.documents.map(doc => ({ ...doc, figures: doc.figures.map(figure => ({ ...figure, expectedHash: hash(overlays[figure.overlayKey] || null) })) })) }; });
+    add('tree', 'GET', async (request) => { const args = revisionQuerySchema.parse(query(request)); const { kb, snapshot } = await store.open(args.kbId, args.revision); const overlays = await store.overlays(kb.kbId); const value = tree(snapshot, kb.kbId); return { ...value, location: await store.snapshotLocation(kb.kbId, snapshot), documents: value.documents.map(doc => ({ ...doc, figures: doc.figures.map(figure => ({ ...figure, expectedHash: hash(overlays[figure.overlayKey] || null) })) })) }; });
     add('read', 'GET', async (request) => retrieval.read(readQuerySchema.parse(query(request))));
     add('search', 'POST', async (request) => retrieval.search(await body(request, searchSchema)));
-    add('asset', 'GET', async (request) => { const args = assetQuerySchema.parse(query(request)), kb = await store.kb(args.kbId), asset = await store.asset(kb.kbId, args.revision, args.docId, args.assetId); return image(asset.asset, asset.file, asset.data); });
-    add('schema', 'GET', async (request) => { const kb = await store.kb(libraryArgs.parse(query(request)).kbId), content = await store.schema(kb.kbId); return { content, hash: hash(content) }; });
-    add('schema', 'POST', async (request) => { const args = await body(request, libraryArgs.extend({ content: z.string().max(20000), expectedHash: digest })), kb = await store.kb(args.kbId); return store.setSchema(kb.kbId, args.content, args.expectedHash); });
+    add('asset', 'GET', async (request) => { const args = assetQuerySchema.parse(query(request)); const kb = await store.kb(args.kbId); const asset = await store.asset(kb.kbId, args.revision, args.docId, args.assetId); return image(asset.asset, asset.file, asset.data); });
+    add('schema', 'GET', async (request) => { const kb = await store.kb(libraryArgs.parse(query(request)).kbId); const content = await store.schema(kb.kbId); return { content, hash: hash(content) }; });
+    add('schema', 'POST', async (request) => { const args = await body(request, libraryArgs.extend({ content: z.string().max(20000), expectedHash: digest })); const kb = await store.kb(args.kbId); return store.setSchema(kb.kbId, args.content, args.expectedHash); });
     add('review', 'POST', async (request) => {
-        const args = await body(request, reviewSchema), kb = await store.kb(args.kbId);
-        const figure = args.action ? null : args.figure && 'ignore' in args.figure ? { ignore: true } : args.figure && 'skip' in args.figure ? { skip: true, types: ['decoration'], description: '人工确认装饰图', visibleLabels: [], relations: [], uncertainties: [], needsReview: false } : args.figure;
+        const args = await body(request, reviewSchema);
+        const kb = await store.kb(args.kbId);
+        let figure;
+        if (args.action) {
+            figure = null;
+        }
+        else {
+            if (args.figure && 'ignore' in args.figure) {
+                figure = { ignore: true };
+            }
+            else {
+                if (args.figure && 'skip' in args.figure) {
+                    figure = { skip: true, types: ['decoration'], description: '人工确认装饰图', visibleLabels: [], relations: [], uncertainties: [], needsReview: false };
+                }
+                else {
+                    figure = args.figure;
+                }
+            }
+        }
         if (figure && JSON.stringify(figure).length > config.figureMaxChars * 3)
             throw new Error('图片复核内容超过预算');
         return jobs.review(kb.kbId, args.revision, args.docId, args.occurrenceId, figure === null ? null : overlaySchema.parse(figure), args.expectedHash, { restore: args.action === 'restore', visionProvider: args.visionProvider, visionModel: args.visionModel });
@@ -142,11 +167,29 @@ export function routes(runtime, ctx) {
                 try {
                     await runtime.ready;
                     checkAbort(request.signal);
-                    const handler = required(methods.get(z.enum(['GET', 'POST', 'HEAD']).parse(request.method)), '请求方法'), value = await runtime.run(signal => handler(new Request(request, { signal })), request.signal);
+                    const handler = required(methods.get(z.enum(['GET', 'POST', 'HEAD']).parse(request.method)), '请求方法');
+                    const value = await runtime.run(signal => handler(new Request(request, { signal })), request.signal);
                     return value instanceof Response ? value : json(value);
                 }
                 catch (error) {
-                    const detail = message(error), status = error instanceof z.ZodError || error instanceof SyntaxError ? 400 : /变化|冲突|已存在|未退出|正在关闭/u.test(detail) ? 409 : /无效|必须|不支持|不能|只能|不在回收站|超过|过大|缺少|缺失|尚无|不存在|提供|请选择|待复核|重复/u.test(detail) ? 400 : 500;
+                    const detail = message(error);
+                    let status;
+                    if (error instanceof z.ZodError || error instanceof SyntaxError) {
+                        status = 400;
+                    }
+                    else {
+                        if (/变化|冲突|已存在|未退出|正在关闭/u.test(detail)) {
+                            status = 409;
+                        }
+                        else {
+                            if (/无效|必须|不支持|不能|只能|不在回收站|超过|过大|缺少|缺失|尚无|不存在|提供|请选择|待复核|重复/u.test(detail)) {
+                                status = 400;
+                            }
+                            else {
+                                status = 500;
+                            }
+                        }
+                    }
                     if (status === 500)
                         ctx.logger.warn(`knowledge-base: ${detail}`);
                     return json({ error: detail }, status);

package/lib/runtime.js

@@ -7,10 +7,16 @@ import { Jobs } from "./jobs.js";
 import { Retrieval } from "./retrieval.js";
 /** One root owner; admitted tasks are durable and the close promise drains them once. */
 export function createRuntime(ctx, raw = {}) {
-    const config = resolveConfig(raw), store = new Store(config), models = new Models(ctx, config), jobs = new Jobs(store, models, config), retrieval = new Retrieval(store, config);
+    const config = resolveConfig(raw);
+    const store = new Store(config);
+    const models = new Models(ctx, config);
+    const jobs = new Jobs(store, models, config);
+    const retrieval = new Retrieval(store, config);
     const ready = mkdir(store.root, { recursive: true }).then(() => jobs.init());
-    let closing, stopped = false;
-    const controller = new AbortController(), pending = new Set();
+    let closing;
+    let stopped = false;
+    const controller = new AbortController();
+    const pending = new Set();
     const run = (operation, signal) => {
         if (stopped)
             return Promise.reject(new Error('任务服务正在关闭'));

package/lib/skills.js

@@ -3,10 +3,13 @@ import { fileURLToPath } from 'node:url';
 import { checkAbort, required } from "./util.js";
 /** Packaged, invocation-neutral skills; no copies in the operator's user directory. */
 export function skillProvider() {
-    const provider = 'libing-knowledge-base', names = ['libing-knowledge-base', 'libing-kb-build', 'libing-kb-search'];
+    const provider = 'libing-knowledge-base';
+    const names = ['libing-knowledge-base', 'libing-kb-build', 'libing-kb-search'];
     const candidates = names.map(name => {
-        const directory = fileURLToPath(new URL(`../skills/${name}/`, import.meta.url)), path = fileURLToPath(new URL(`../skills/${name}/SKILL.md`, import.meta.url));
-        const raw = readFileSync(path, 'utf8'), header = required(/^---\n([\s\S]*?)\n---\n/u.exec(raw), `skill frontmatter: ${name}`);
+        const directory = fileURLToPath(new URL(`../skills/${name}/`, import.meta.url));
+        const path = fileURLToPath(new URL(`../skills/${name}/SKILL.md`, import.meta.url));
+        const raw = readFileSync(path, 'utf8');
+        const header = required(/^---\n([\s\S]*?)\n---\n/u.exec(raw), `skill frontmatter: ${name}`);
         const description = required(/^description:\s*(.+)$/mu.exec(required(header[1]))?.[1], `skill description: ${name}`);
         return { name, description, source: 'bundled', provider, rank: 600, path, resourceBase: { kind: 'directory', path: directory }, invocation: { modelInvocable: true, userInvocable: true }, locator: path };
     });