@dsh-libing/knowledge-base 0.1.0

package/lib/retrieval.d.ts

@@ -0,0 +1,209 @@
+import type { Settings } from './config.ts';
+import type { Store } from './store.ts';
+import type { PublishedDocument, DocInfo, Chunk, Snapshot } from './data.ts';
+import type { CatalogArgs, SearchArgs, ReadArgs } from './shared.ts';
+export type WindowOptions = {
+    segmentIndex?: number | undefined;
+    offset?: number | undefined;
+    windowBudget?: number | undefined;
+};
+export interface ReadWindow {
+    segmentIndex: number;
+    startLine: number | undefined;
+    endLine: number | undefined;
+    charOffset?: number;
+    partial?: boolean;
+}
+export interface WindowRead {
+    text: string;
+    startLine?: number;
+    endLine?: number;
+    complete: boolean;
+    continuation: {
+        segmentIndex: number;
+        offset: number;
+    } | null;
+    windows?: ReadWindow[];
+    truncated?: boolean;
+    totalSegments?: number;
+}
+export declare function queryTerms(query: string, keywords?: string[]): string[];
+export declare function pdfScope(doc: Pick<DocInfo, 'sourceFormat' | 'selectedPages' | 'pageCount'>): string;
+declare function source(doc: PublishedDocument, chunk: Chunk, revision: string, read?: WindowRead): {
+    docId: string;
+    title: string;
+    sourceVersion: string;
+    sourceHash: string;
+    revision: string;
+    headingPath: string[];
+    path: string;
+    contentHash: string;
+    locations?: import("./data.ts").Source[];
+    locationsTruncated?: boolean;
+    sourceFormat?: string;
+    pageCount?: number | undefined;
+    selectedPages?: {
+        start: number;
+        end: number;
+        count: number;
+        total: number;
+        partial: boolean;
+    } | undefined;
+    scope?: string;
+    pageRange?: number[] | undefined;
+};
+export declare class Retrieval {
+    readonly store: Store;
+    readonly config: Settings;
+    constructor(store: Store, config: Settings);
+    catalog(args?: CatalogArgs): Promise<{
+        knowledgeBases: ({
+            kbId: string;
+            name: string;
+            createdAt: string;
+            deletedAt?: string | undefined;
+            purge?: {
+                startedAt: string;
+                jobIds: string[];
+                error?: string | undefined;
+            } | undefined;
+        } & {
+            revision: string | null;
+            coverageIncomplete: boolean;
+        })[];
+        truncated: boolean;
+    } | {
+        kbId: string;
+        revision: string;
+        catalogId: string;
+        page: number;
+        path: string;
+        content: string;
+        nextPage: number | null;
+    }>;
+    search(args: SearchArgs): Promise<{
+        kbId: string;
+        revision: string;
+        query: string;
+        terms: string[];
+        candidates: Candidate[];
+        evidence: Evidence[];
+        warnings: SearchWarning[];
+        truncated: boolean;
+        totalCandidates: number;
+        continuation: {
+            chunkId: string;
+        }[];
+    }>;
+    read(args: ReadArgs): Promise<{
+        assetRefs: string[];
+        relatedChunks: string[];
+        warnings: string[];
+        text: string;
+        startLine?: number;
+        endLine?: number;
+        complete: boolean;
+        continuation: {
+            segmentIndex: number;
+            offset: number;
+        } | null;
+        windows?: ReadWindow[];
+        truncated?: boolean;
+        totalSegments?: number;
+        kbId: string;
+        chunkId: string;
+        revision: string;
+        source: {
+            docId: string;
+            title: string;
+            sourceVersion: string;
+            sourceHash: string;
+            revision: string;
+            headingPath: string[];
+            path: string;
+            contentHash: string;
+            locations?: import("./data.ts").Source[];
+            locationsTruncated?: boolean;
+            sourceFormat?: string;
+            pageCount?: number | undefined;
+            selectedPages?: {
+                start: number;
+                end: number;
+                count: number;
+                total: number;
+                partial: boolean;
+            } | undefined;
+            scope?: string;
+            pageRange?: number[] | undefined;
+        };
+    }>;
+    readSnapshot(kbId: string, snapshot: Snapshot & {
+        chunk: Chunk;
+        content: string;
+    }, args: ReadArgs): {
+        assetRefs: string[];
+        relatedChunks: string[];
+        warnings: string[];
+        text: string;
+        startLine?: number;
+        endLine?: number;
+        complete: boolean;
+        continuation: {
+            segmentIndex: number;
+            offset: number;
+        } | null;
+        windows?: ReadWindow[];
+        truncated?: boolean;
+        totalSegments?: number;
+        kbId: string;
+        chunkId: string;
+        revision: string;
+        source: {
+            docId: string;
+            title: string;
+            sourceVersion: string;
+            sourceHash: string;
+            revision: string;
+            headingPath: string[];
+            path: string;
+            contentHash: string;
+            locations?: import("./data.ts").Source[];
+            locationsTruncated?: boolean;
+            sourceFormat?: string;
+            pageCount?: number | undefined;
+            selectedPages?: {
+                start: number;
+                end: number;
+                count: number;
+                total: number;
+                partial: boolean;
+            } | undefined;
+            scope?: string;
+            pageRange?: number[] | undefined;
+        };
+    };
+}
+export type EvidenceSource = ReturnType<typeof source>;
+export interface Candidate {
+    chunkId: string;
+    score: number;
+    matchedTerms: string[];
+    title: string;
+    summary: string;
+    fullChars: number;
+    reviewStatus: Chunk['reviewStatus'];
+    source: EvidenceSource;
+}
+export interface Evidence extends WindowRead {
+    chunkId: string;
+    source: EvidenceSource;
+    assetRefs: string[];
+    relatedChunks: string[];
+}
+export interface SearchWarning {
+    docId?: string;
+    chunkId?: string;
+    kind?: string;
+    message: string;
+}
+export {};

package/lib/retrieval.js

@@ -0,0 +1,173 @@
+import { required } from "./util.js";
+import { chars, clip, id, text } from "./util.js";
+export function queryTerms(query, keywords = []) {
+    query = text(query, '检索问题', 2000);
+    if (!Array.isArray(keywords) || keywords.length > 32 || keywords.some(x => typeof x !== 'string' || chars(x) > 100))
+        throw new Error('keywords 必须是最多 32 个短文本');
+    const tokens = query.match(/[A-Za-z][A-Za-z0-9_.+#/-]+|[\p{Script=Han}]+/gu) || [];
+    return [...new Set([...keywords, ...tokens, ...tokens.filter(t => /\p{Script=Han}/u.test(t) && t.length > 4).flatMap(t => Array.from({ length: t.length - 1 }, (_, i) => t.slice(i, i + 2)))]
+            .map(t => t.trim().toLowerCase()).filter(t => t.length >= 2))].slice(0, 64);
+}
+function bounded(value, max) {
+    if (chars(JSON.stringify(value)) > max)
+        throw new Error('输出预算不足，请缩小检索范围或提高 evidenceMaxChars');
+    return value;
+}
+export function pdfScope(doc) { return doc.sourceFormat === 'pdf' ? `PDF 实际页序 ${doc.selectedPages?.start || 1}–${doc.selectedPages?.end || doc.pageCount} / ${doc.pageCount}${required(doc).selectedPages?.partial ? '；仅覆盖所选页范围' : ''}` : ''; }
+function source(doc, chunk, revision, read) {
+    const locations = read?.windows ? read.windows.flatMap(w => chunk.segments[w.segmentIndex]?.sourceLocations || []) : chunk.sourceLocations || [];
+    const unique = [...new Map(locations.map(l => [JSON.stringify(l), l])).values()];
+    const pages = unique.map(l => l.page);
+    return { ...doc.sourceFormat === 'pdf' ? { sourceFormat: 'pdf', pageCount: doc.pageCount, selectedPages: doc.selectedPages, scope: pdfScope(doc), pageRange: pages.length ? [Math.min(...pages), Math.max(...pages)] : chunk.pageRange, ...read ? { locations: unique.slice(0, 32), locationsTruncated: unique.length > 32 } : {} } : {}, docId: doc.docId, title: doc.title, sourceVersion: doc.sourceVersion, sourceHash: doc.sourceHash, revision, headingPath: chunk.headingPath, path: chunk.path, contentHash: chunk.contentHash };
+}
+function windows(chunk, content, terms, config, options = {}) {
+    if (chars(content) <= Math.min(config.chunkTargetChars, config.evidenceMaxChars - 3000, options.windowBudget ?? Infinity) && options.segmentIndex === undefined)
+        return { text: content, startLine: 1, endLine: content.split('\n').length, complete: true, continuation: null };
+    let selected = chunk.segments.map((s, i) => ({ ...s, index: i })).filter(s => terms.some(t => s.text.toLowerCase().includes(t)));
+    if (options.segmentIndex !== undefined)
+        selected = chunk.segments[options.segmentIndex] ? [{ ...required(chunk.segments[options.segmentIndex]), index: options.segmentIndex }] : [];
+    if (!selected.length)
+        selected = chunk.segments.length ? [{ ...required(chunk.segments[0]), index: 0 }] : [];
+    if (!selected.length)
+        return { text: '', complete: true, continuation: null };
+    const indices = new Set();
+    for (const s of selected) {
+        for (let i = options.segmentIndex === undefined ? Math.max(0, s.index - 1) : s.index; i <= Math.min(chunk.segments.length - 1, s.index + 1); i++)
+            indices.add(i);
+    }
+    const ordered = [...indices].sort((a, b) => a - b);
+    const read = [];
+    let body = '', 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`;
+        let value = s.text;
+        const start = options.segmentIndex === i ? options.offset || 0 : 0;
+        if (start > chars(value))
+            throw new Error('续读字符偏移超过语义块');
+        value = Array.from(value).slice(start).join('');
+        if (chars(body + heading + value) > max) {
+            if (read.length) {
+                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 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;
+            read.push({ segmentIndex: i, startLine: s.startLine, endLine: s.endLine, charOffset: offset, partial: true });
+            body += heading + value + '\n[此语义块仅返回部分，请按 continuation 续读]\n';
+            break;
+        }
+        body += heading + value + '\n\n';
+        read.push({ segmentIndex: i, startLine: s.startLine, endLine: s.endLine, ...start ? { charOffset: start, partial: true } : {} });
+    }
+    const unread = chunk.segments.length - read.length;
+    const next = (read.at(-1)?.segmentIndex ?? -1) + 1;
+    return { text: body, windows: read, complete: unread === 0 && !read.some(r => r.partial), truncated: unread > 0 || read.some(r => r.partial), continuation: continuation || (next < chunk.segments.length ? { segmentIndex: next, offset: 0 } : null), totalSegments: chunk.segments.length };
+}
+export class Retrieval {
+    store;
+    config;
+    constructor(store, config) {
+        this.store = store;
+        this.config = config;
+    }
+    async catalog(args = {}) {
+        if (!args.kbId) {
+            const kbs = await this.store.list(), 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 });
+            }
+            const value = { knowledgeBases: entries, truncated: false };
+            while (chars(JSON.stringify(value)) > this.config.catalogMaxChars && value.knowledgeBases.length) {
+                value.knowledgeBases.pop();
+                value.truncated = true;
+            }
+            return bounded(value, this.config.catalogMaxChars);
+        }
+        const kb = await this.store.kb(args.kbId), snapshot = await this.store.revision(kb.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)
+            throw new Error('目录节点不存在');
+        const page = args.page === undefined ? 0 : args.page;
+        if (!Number.isSafeInteger(page) || page < 0 || !catalog.pages[page])
+            throw new Error('索引页不存在');
+        const actual = required(catalog.pages[page]);
+        // Markdown is the model-facing index; do not duplicate its entries in the same result.
+        const value = { kbId: kb.kbId, revision: snapshot.revision, catalogId, page, path: actual.path, content: actual.content, nextPage: page + 1 < catalog.pages.length ? page + 1 : null };
+        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 = [];
+        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());
+                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);
+                scored.push({ doc, chunk, content, score, hits });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score || a.chunk.path.localeCompare(b.chunk.path));
+        const limit = args.limit === undefined ? this.config.candidateLimit : args.limit;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 30)
+            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) {
+            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;
+            const read = windows(chunk, content, terms, this.config, { windowBudget: Math.max(128, Math.min(remaining, 6000)) });
+            const evidence = { chunkId: chunk.chunkId, ...read, source: source(required(doc), chunk, snapshot.revision, read), assetRefs: chunk.assetRefs, relatedChunks: chunk.relatedChunks };
+            if (required(doc).selectedPages?.partial && !value.warnings.some(w => w.docId === doc.docId && w.kind === 'scope'))
+                value.warnings.push({ docId: doc.docId, kind: 'scope', message: pdfScope(doc) });
+            if (required(doc).coverageIncomplete && !value.warnings.some(w => w.docId === doc.docId))
+                value.warnings.push({ docId: doc.docId, message: '此文档存在已接受的覆盖缺口，请结合质量报告核对' });
+            if (chunk.reviewStatus === 'needs-review')
+                value.warnings.push({ chunkId: chunk.chunkId, message: '涉及未解决的图片描述或待复核信息' });
+            value.evidence.push(evidence);
+            if (chars(JSON.stringify(value)) > this.config.evidenceMaxChars) {
+                value.evidence.pop();
+                value.continuation.push({ chunkId: chunk.chunkId });
+                value.truncated = true;
+            }
+            if (chars(JSON.stringify(value)) > this.config.evidenceMaxChars) {
+                value.candidates.pop();
+                break;
+            }
+        }
+        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);
+        return this.readSnapshot(kb.kbId, snapshot, args);
+    }
+    readSnapshot(kbId, snapshot, args) {
+        const doc = snapshot.manifest.documents.find(d => d.docId === snapshot.chunk.docId);
+        const terms = args.query ? queryTerms(args.query, args.keywords) : [];
+        for (const key of ['segmentIndex', 'offset'])
+            if (args[key] !== undefined && (!Number.isSafeInteger(args[key]) || args[key] < 0))
+                throw new Error(`${key} 必须为非负整数`);
+        if (args.offset !== undefined && args.segmentIndex === undefined)
+            throw new Error('offset 必须与 segmentIndex 一起提供');
+        if (args.segmentIndex !== undefined && args.segmentIndex >= snapshot.chunk.segments.length)
+            throw new Error('续读语义块不存在');
+        let budget = this.config.evidenceMaxChars - 2000;
+        for (;;) {
+            const read = windows(snapshot.chunk, snapshot.content, terms, this.config, { ...args, windowBudget: budget });
+            const result = { kbId, chunkId: snapshot.chunk.chunkId, revision: snapshot.revision, source: source(required(doc), snapshot.chunk, snapshot.revision, read), ...read, assetRefs: snapshot.chunk.assetRefs, relatedChunks: snapshot.chunk.relatedChunks, warnings: [...required(doc).coverageIncomplete ? ['当前文档存在覆盖缺口'] : [], ...required(doc).selectedPages?.partial ? [pdfScope(required(doc))] : []] };
+            if (chars(JSON.stringify(result)) <= this.config.evidenceMaxChars || budget <= 128)
+                return bounded(result, this.config.evidenceMaxChars);
+            budget = Math.max(128, Math.floor(budget * .6));
+        }
+    }
+}

package/lib/routes.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Runtime } from './runtime.ts';
+export declare function routes(runtime: Runtime, ctx: Context): void;

package/lib/routes.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { API, browserBuildSchema, jobActionSchema, catalogQuerySchema, readQuerySchema, searchSchema, assetQuerySchema, revisionQuerySchema } from "./shared.js";
+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 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 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) {
+    const result = {};
+    for (const [key, value] of new URL(request.url).searchParams) {
+        if (Object.hasOwn(result, key))
+            throw new Error('重复查询参数');
+        result[key] = value;
+    }
+    return result;
+}
+async function bytes(request, max) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        return Buffer.alloc(0);
+    const parts = [];
+    let size = 0;
+    try {
+        for (;;) {
+            checkAbort(request.signal);
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > max)
+                throw new Error('请求内容超过大小上限');
+            parts.push(Buffer.from(value));
+        }
+        return Buffer.concat(parts, size);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+async function body(request, schema) {
+    if (request.headers.get('content-type')?.split(';')[0]?.trim() !== 'application/json')
+        throw new Error('请求必须使用 application/json');
+    return schema.parse(JSON.parse((await bytes(request, 128 * 1024)).toString('utf8')));
+}
+export function routes(runtime, ctx) {
+    const { store, jobs, retrieval, config } = runtime;
+    const table = new Map();
+    const add = (path, method, handler) => {
+        let methods = table.get(path);
+        if (!methods) {
+            methods = new Map();
+            table.set(path, methods);
+        }
+        methods.set(method, handler);
+    };
+    const json = (value, status = 200) => Response.json(value, { status, headers });
+    const binary = (data, mime) => new Response(new Uint8Array(data), { headers: { ...headers, 'content-type': mime, 'content-security-policy': "default-src 'none'; sandbox" } });
+    const original = async (snapshot, docId) => {
+        const doc = snapshot.manifest.documents.find(d => d.docId === docId);
+        if (!doc || doc.sourceFormat !== 'pdf')
+            throw new Error('PDF 原件不存在于所选版本中');
+        return binary((await store.rawSource(snapshot.kbId, doc)).data, 'application/pdf');
+    };
+    const image = async (asset, file) => {
+        if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/bmp', 'image/tiff'].includes(asset.mime))
+            throw new Error('不支持浏览此图片格式，请提供 PNG/JPEG 预览');
+        const data = await fileBytes(file, config.maxUncompressedBytes);
+        if (`a-${hash(data).slice(0, 20)}` !== asset.assetId)
+            throw new Error('图片内容与清单不一致');
+        return binary(data, asset.mime);
+    };
+    const tree = (snapshot, kbId) => ({ kbId, revision: snapshot.revision, coverageIncomplete: snapshot.manifest.coverageIncomplete, report: snapshot.manifest.report, documents: snapshot.manifest.documents.map(doc => ({ ...doc, chunks: doc.chunks.map(({ segments: _segments, anchors: _anchors, ...chunk }) => chunk) })) });
+    add('list', 'GET', async (request) => { z.strictObject({}).parse(query(request)); return ({ hostVersion: HOST_VERSION, kbs: await Promise.all((await store.list()).map(async (kb) => ({ ...kb, ...await store.inspect(kb.kbId) }))), deletedKbs: await store.deleted(), activities: await store.activities(), jobs: jobs.list(), dataRoot: store.root, config: { chunkTargetChars: config.chunkTargetChars, visionProvider: config.visionProvider, visionModel: config.visionModel, maxInputBytes: config.maxInputBytes } }); });
+    add('create', 'POST', async (request) => store.create((await body(request, z.strictObject({ name }))).name));
+    add('delete', 'POST', async (request) => { const args = await body(request, managementArgs); return jobs.trash(args.kbId, args.confirmName); });
+    add('restore', 'POST', async (request) => jobs.restore((await body(request, libraryArgs)).kbId));
+    add('purge', 'POST', async (request) => { const args = await body(request, managementArgs.extend({ confirmIrreversible: z.literal(true) })); return jobs.purge(args.kbId, args.confirmName, args.confirmIrreversible); });
+    add('upload', 'POST', async (request) => {
+        if (request.headers.get('content-type')?.split(';')[0]?.trim() !== 'application/octet-stream')
+            throw new Error('上传必须使用 application/octet-stream');
+        const args = z.strictObject({ filename: z.string().min(1).max(200) }).parse(query(request));
+        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);
+        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('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 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('catalog', 'GET', async (request) => retrieval.catalog(catalogQuerySchema.parse(query(request))));
+    add('tree', 'GET', async (request) => { const args = revisionQuerySchema.parse(query(request)), kb = await store.kb(args.kbId), snapshot = await store.revision(kb.kbId, args.revision), overlays = await store.overlays(kb.kbId), value = tree(snapshot, kb.kbId); return { ...value, location: await store.location(kb.kbId, snapshot.revision), 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); });
+    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('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;
+        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 });
+    });
+    add('models', 'GET', async (request) => {
+        z.strictObject({}).parse(query(request));
+        checkAbort(request.signal);
+        const providers = [];
+        for (const provider of ctx.llm.listProviders()) {
+            try {
+                providers.push({ id: provider.id, name: provider.name || provider.id, models: (await ctx.llm.listModels(provider.id)).map(model => ({ id: model.id, name: model.name || model.id, inputModalities: model.inputModalities })) });
+            }
+            catch (error) {
+                providers.push({ id: provider.id, name: provider.name || provider.id, models: [], error: message(error) });
+            }
+        }
+        return { providers };
+    });
+    for (const [path, methods] of table)
+        ctx.effect(() => ctx.connection.fetch.register({ path: `${API}/${path}`, methods: [...methods.keys()], requestBody: path === 'upload' ? 'streaming' : 'buffered', fetch: async (request) => {
+                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);
+                    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;
+                    if (status === 500)
+                        ctx.logger.warn(`knowledge-base: ${detail}`);
+                    return json({ error: detail }, status);
+                }
+            } }), `libing-knowledge-base: ${path}`);
+}

package/lib/runtime.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.ts';
+import { Store } from './store.ts';
+import { Models } from './models.ts';
+import { Jobs } from './jobs.ts';
+import { Retrieval } from './retrieval.ts';
+/** One root owner; admitted tasks are durable and the close promise drains them once. */
+export declare function createRuntime(ctx: Context, raw?: Config): {
+    config: {
+        dataRoot: string;
+        chunkTargetChars: number;
+        evidenceMaxChars: number;
+        catalogMaxChars: number;
+        candidateLimit: number;
+        maxInputBytes: number;
+        maxUncompressedBytes: number;
+        maxArchiveEntries: number;
+        modelTimeoutMs: number;
+        modelAttempts: number;
+        visionConcurrency: number;
+        maxModelCalls: number;
+        maxModelTokens: number;
+        visionMaxEdge: number;
+        visionTileSize: number;
+        visionMaxTiles: number;
+        modelMaxOutputTokens: number;
+        summaryMaxChars: number;
+        figureMaxChars: number;
+        pdfMaxPages: number;
+        pdfMaxPagePixels: number;
+        pdfPageTimeoutMs: number;
+        libreOfficePath: string;
+        visionProvider: string;
+        visionModel: string;
+        summaryProvider: string;
+        summaryModel: string;
+        skipImages: boolean;
+        acceptPartial: boolean;
+    };
+    store: Store;
+    models: Models;
+    jobs: Jobs;
+    retrieval: Retrieval;
+    ready: Promise<void>;
+    run: <T>(operation: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal) => Promise<T>;
+    close: () => Promise<void>;
+};
+export type Runtime = ReturnType<typeof createRuntime>;

package/lib/runtime.js

@@ -0,0 +1,41 @@
+import { checkAbort } from "./util.js";
+import { mkdir } from 'node:fs/promises';
+import { resolveConfig } from "./config.js";
+import { Store } from "./store.js";
+import { Models } from "./models.js";
+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 ready = mkdir(store.root, { recursive: true }).then(() => jobs.init());
+    let closing, stopped = false;
+    const controller = new AbortController(), pending = new Set();
+    const run = (operation, signal) => {
+        if (stopped)
+            return Promise.reject(new Error('任务服务正在关闭'));
+        const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        const value = Promise.resolve().then(() => { checkAbort(combined); return operation(combined); });
+        pending.add(value);
+        void value.finally(() => pending.delete(value)).catch(() => { });
+        return value;
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        stopped = true;
+        controller.abort(new Error('任务服务正在关闭'));
+        jobs.stop();
+        closing = (async () => {
+            try {
+                await ready;
+            }
+            finally {
+                await Promise.allSettled(pending);
+                await jobs.close();
+            }
+        })();
+        return closing;
+    };
+    return { config, store, models, jobs, retrieval, ready, run, close };
+}