@dsh-libing/knowledge-base 0.1.0

package/lib/store.js

@@ -0,0 +1,328 @@
+import { z } from 'zod';
+import { registrySchema, currentSchema, manifestSchema, uploadSchema, overlaySchema } from "./data.js";
+import { code, message, required } from "./util.js";
+import { mkdir, readFile, readdir, rename, cp, rm, stat, lstat } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, fileBytes, hash, id, now, readJson, safePath, text } from "./util.js";
+export const DEFAULT_SCHEMA = `# 知识库治理约定\n\n保留原文中的型号、管脚、单位、数值、极性和适用条件。图片描述与原文分别标注；不确定的信息保留待复核。摘要用于导航，回答依据原文和可核验图像。引用包含文档版本、章节、片段和图表编号。\n`;
+export class Store {
+    config;
+    root;
+    registryTail;
+    constructor(config) { this.config = config; this.root = config.dataRoot; this.registryTail = Promise.resolve(); }
+    async init() {
+        for (const dir of ['kbs', 'jobs', 'uploads', 'cache'])
+            await mkdir(join(this.root, dir), { recursive: true });
+        if (!await readJson(join(this.root, 'registry.json'), registrySchema, null))
+            await atomicWrite(join(this.root, 'registry.json'), { formatVersion: 1, kbs: [] });
+    }
+    async serialized(fn) {
+        const next = this.registryTail.then(fn);
+        this.registryTail = next.catch(() => { });
+        return next;
+    }
+    async list(includeDeleted = false) { return (await readJson(join(this.root, 'registry.json'), registrySchema)).kbs.filter(k => includeDeleted || !k.deletedAt); }
+    async deleted() { return (await this.list(true)).filter(k => k.deletedAt); }
+    async activities() { return (await readJson(join(this.root, 'registry.json'), registrySchema)).activities || []; }
+    record(registry, action, kb) {
+        registry.activities = [...(registry.activities || []), { eventId: randomUUID(), at: now(), action, kbId: kb.kbId, name: kb.name }].slice(-100);
+    }
+    async trash(kbId, expectedName) {
+        return this.serialized(async () => {
+            const registry = await readJson(join(this.root, 'registry.json'), registrySchema), kb = registry.kbs.find(k => k.kbId === id(kbId) && !k.deletedAt);
+            if (!kb)
+                throw new Error('知识库不存在，请刷新');
+            if (kb.name !== expectedName)
+                throw new Error('知识库名称已变化，请刷新后确认删除');
+            kb.deletedAt = now();
+            this.record(registry, 'trash', kb);
+            await atomicWrite(join(this.root, 'registry.json'), registry);
+            return kb;
+        });
+    }
+    async restore(kbId) {
+        return this.serialized(async () => {
+            const registry = await readJson(join(this.root, 'registry.json'), registrySchema), kb = registry.kbs.find(k => k.kbId === id(kbId) && k.deletedAt);
+            if (!kb)
+                throw new Error('知识库不在回收站，请刷新');
+            if (kb.purge)
+                throw new Error('知识库已开始彻底删除，不能恢复；请继续彻底删除');
+            if (registry.kbs.some(k => !k.deletedAt && k.name === kb.name))
+                throw new Error('同名知识库已存在，不能恢复；请先删除同名库');
+            delete kb.deletedAt;
+            this.record(registry, 'restore', kb);
+            await atomicWrite(join(this.root, 'registry.json'), registry);
+            return kb;
+        });
+    }
+    async purgeTarget(group, key) {
+        const parent = await safePath(this.root, group);
+        if ((await lstat(parent)).isSymbolicLink())
+            throw new Error('不能通过符号链接删除知识库数据');
+        const path = await safePath(parent, id(key), false);
+        const info = await lstat(path).catch(error => {
+            if (code(error) === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (info && (!info.isDirectory() || info.isSymbolicLink()))
+            throw new Error('不能删除非目录或符号链接对象');
+        return path;
+    }
+    async removePurgeTree(path) { await rm(path, { recursive: true, force: true, maxRetries: 2, retryDelay: 100 }); }
+    async purge(kbId, expectedName, confirmed, jobIds = []) {
+        if (confirmed !== true)
+            throw new Error('必须明确确认彻底删除不可恢复');
+        return this.serialized(async () => {
+            const registry = await readJson(join(this.root, 'registry.json'), registrySchema), kb = registry.kbs.find(k => k.kbId === id(kbId) && k.deletedAt);
+            if (!kb)
+                throw new Error('只能彻底删除回收站中的知识库');
+            if (kb.name !== expectedName)
+                throw new Error('知识库名称已变化，请重新确认彻底删除');
+            const targets = [...new Set([...(kb.purge?.jobIds || []), ...jobIds])];
+            const kbPath = await this.purgeTarget('kbs', kb.kbId), jobPaths = await Promise.all(targets.map(key => this.purgeTarget('jobs', key)));
+            // Persist intent before removing files: a crash or partial failure must not allow restoration.
+            kb.purge = { startedAt: kb.purge?.startedAt || now(), jobIds: targets };
+            await atomicWrite(join(this.root, 'registry.json'), registry);
+            try {
+                for (const path of jobPaths)
+                    await this.removePurgeTree(path);
+                await this.removePurgeTree(kbPath);
+                registry.kbs = registry.kbs.filter(k => k.kbId !== kb.kbId);
+                this.record(registry, 'purge', kb);
+                await atomicWrite(join(this.root, 'registry.json'), registry);
+                return { kbId: kb.kbId, name: kb.name, purged: true };
+            }
+            catch (error) {
+                // Keep the pending entry so cleanup is retryable and the UI cannot restore incomplete data.
+                registry.kbs = registry.kbs.filter(k => k.kbId !== kb.kbId).concat(kb);
+                registry.activities = (registry.activities || []).filter(e => !(e.kbId === kb.kbId && e.action === 'purge' && e.at >= required(kb.purge).startedAt));
+                required(kb.purge).error = `彻底删除未完成，请继续删除：${message(error)}`;
+                await atomicWrite(join(this.root, 'registry.json'), registry);
+                throw new Error(required(kb.purge).error);
+            }
+        });
+    }
+    async kb(selector) {
+        const kbs = await this.list(), matches = kbs.filter(k => k.kbId === selector || k.name === selector);
+        if (matches.length !== 1)
+            throw new Error(matches.length ? '知识库名称重复，请使用 kbId' : '知识库不存在，请先创建或选择');
+        await safePath(this.root, join('kbs', id(required(matches[0]).kbId)), true);
+        return required(matches[0]);
+    }
+    async create(name) {
+        name = text(name, '知识库名', 120);
+        return this.serialized(async () => {
+            const registry = await readJson(join(this.root, 'registry.json'), registrySchema);
+            if (registry.kbs.some(k => !k.deletedAt && k.name === name))
+                throw new Error('同名知识库已存在');
+            const kb = { kbId: `kb-${randomUUID().slice(0, 12)}`, name, createdAt: now() };
+            const root = join(this.root, 'kbs', kb.kbId);
+            await mkdir(root, { recursive: true });
+            await atomicWrite(join(root, 'schema.md'), DEFAULT_SCHEMA);
+            await atomicWrite(join(root, 'log.md'), '# 构建与复核流水\n\n');
+            registry.kbs.push(kb);
+            this.record(registry, 'create', kb);
+            await atomicWrite(join(this.root, 'registry.json'), registry);
+            return kb;
+        });
+    }
+    kbRoot(kbId) { return join(this.root, 'kbs', id(kbId, 'kbId')); }
+    async inspect(kbId, revision) {
+        const kb = await this.kb(kbId), kbPath = await safePath(this.root, join('kbs', kb.kbId));
+        const current = await this.current(kb.kbId);
+        if (!revision && !current)
+            return { location: { kbPath, revision: null, wikiPath: null, indexPath: null }, summary: { revision: null, documentCount: 0, chunkCount: 0, coverageIncomplete: false } };
+        const snapshot = await this.revision(kb.kbId, revision || required(current).revision);
+        return { location: { kbPath, revision: snapshot.revision, wikiPath: await safePath(snapshot.root, 'wiki'), indexPath: await safePath(snapshot.root, 'index.md') }, summary: { revision: snapshot.revision, documentCount: snapshot.manifest.documents.length, chunkCount: snapshot.manifest.documents.reduce((sum, d) => sum + d.chunks.length, 0), coverageIncomplete: Boolean(snapshot.manifest.coverageIncomplete) } };
+    }
+    async location(kbId, revision) { return (await this.inspect(kbId, revision)).location; }
+    async schema(kbId) { return readFile(await safePath(this.kbRoot(kbId), 'schema.md'), 'utf8'); }
+    async setSchema(kbId, content, expectedHash) {
+        if (typeof content !== 'string' || content.length > 20000)
+            throw new Error('库约定不能超过 20000 字符');
+        return this.serialized(async () => {
+            const old = await this.schema(kbId);
+            if (hash(old) !== expectedHash)
+                throw new Error('库约定已变化，请刷新后再保存');
+            await atomicWrite(join(this.kbRoot(kbId), 'schema.md'), content);
+            return { content, hash: hash(content) };
+        });
+    }
+    async upload(data, filename) {
+        filename = text(basename(filename), '文件名', 200);
+        if (!/\.(?:docx?|pdf)$/i.test(filename) || data.length > this.config.maxInputBytes)
+            throw new Error('只支持大小限制内的 .docx / .doc / .pdf 文件');
+        const receiptId = `u-${randomUUID()}`, file = join(this.root, 'uploads', receiptId + '.bin');
+        await atomicWrite(file, data);
+        await atomicWrite(join(this.root, 'uploads', receiptId + '.json'), { receiptId, filename, createdAt: now(), bytes: data.length, hash: hash(data) });
+        return { receiptId, filename, bytes: data.length };
+    }
+    async uploaded(receiptId) {
+        id(receiptId, '上传收据');
+        const receipt = await readJson(await safePath(this.root, join('uploads', receiptId + '.json')), uploadSchema);
+        const data = await fileBytes(await safePath(this.root, join('uploads', receiptId + '.bin')), this.config.maxInputBytes);
+        if (data.length !== receipt.bytes || hash(data) !== receipt.hash)
+            throw new Error('上传内容已变化');
+        return { ...receipt, data };
+    }
+    async current(kbId) { return readJson(join(this.kbRoot(kbId), 'current.json'), currentSchema, null); }
+    async revision(kbId, requested) {
+        await this.kb(kbId);
+        const current = await this.current(kbId), revision = requested || current?.revision;
+        if (!revision)
+            throw new Error('知识库尚无已发布版本');
+        id(revision, 'revision');
+        const root = await safePath(this.kbRoot(kbId), join('revisions', revision));
+        const manifest = await readJson(join(root, 'manifest.json'), manifestSchema);
+        if (manifest.revision !== revision)
+            throw new Error('版本清单不一致');
+        return { root, manifest, revision };
+    }
+    async readChunk(kbId, revision, chunkId) {
+        const snapshot = await this.revision(kbId, revision);
+        const chunk = snapshot.manifest.documents.flatMap(d => d.chunks).find(c => c.chunkId === chunkId);
+        if (!chunk)
+            throw new Error('片段不在所选知识库版本中');
+        const content = await this.chunkContent(snapshot, chunk);
+        return { ...snapshot, chunk, content };
+    }
+    async chunkContent(snapshot, chunk) {
+        const content = await readFile(await safePath(snapshot.root, chunk.path), 'utf8');
+        if (hash(content) !== chunk.contentHash)
+            throw new Error('片段内容与清单不一致，请重建');
+        return content;
+    }
+    async asset(kbId, revision, docId, assetId) {
+        const snapshot = await this.revision(kbId, revision), doc = snapshot.manifest.documents.find(d => d.docId === docId);
+        const asset = doc?.assets.find(a => a.assetId === assetId);
+        if (!asset)
+            throw new Error('图片不在所选文档版本中');
+        const file = await safePath(snapshot.root, join('sources', id(docId), asset.path));
+        if (`a-${hash(await fileBytes(file, this.config.maxUncompressedBytes)).slice(0, 20)}` !== asset.assetId)
+            throw new Error('图片内容与清单不一致');
+        return { ...snapshot, asset, file, doc: required(doc) };
+    }
+    async rawSnapshot(kbId, docId, sourceHash, data, info) {
+        const root = join(this.kbRoot(kbId), 'raw', id(docId), id(sourceHash));
+        await mkdir(root, { recursive: true });
+        const file = await safePath(root, info.sourceFormat === 'pdf' ? 'source.pdf' : 'source.docx', false);
+        const previous = await readJson(join(root, 'source.json'), z.record(z.string(), z.json()), null);
+        if (previous) {
+            if (hash(await readFile(file)) !== sourceHash)
+                throw new Error('原件快照与哈希不一致');
+        }
+        else {
+            await atomicWrite(file, data);
+            await atomicWrite(join(root, 'source.json'), info);
+        }
+        return { root, file };
+    }
+    async rawSource(kbId, doc) {
+        const root = await safePath(this.kbRoot(kbId), join('raw', id(doc.docId), id(doc.sourceHash)));
+        const file = await safePath(root, doc.sourceFormat === 'pdf' ? 'source.pdf' : 'source.docx');
+        const data = await fileBytes(file, this.config.maxInputBytes);
+        if (hash(data) !== doc.sourceHash)
+            throw new Error('原件快照与版本哈希不一致');
+        return { file, data };
+    }
+    async carryPrevious(kbId, destination, replaceDocId) {
+        const current = await this.current(kbId);
+        if (!current)
+            return [];
+        const { root, manifest } = await this.revision(kbId, current.revision);
+        const docs = [];
+        for (const document of manifest.documents.filter(d => d.docId !== replaceDocId)) {
+            const chunks = [];
+            for (const chunk of document.chunks) {
+                const content = await this.chunkContent({ root, manifest, revision: manifest.revision }, chunk);
+                chunks.push({ ...chunk, content, body: content.split("\n---\n\n").slice(1).join("\n---\n\n") });
+            }
+            docs.push({ ...document, chunks });
+        }
+        for (const doc of docs) {
+            await mkdir(join(destination, 'sources'), { recursive: true });
+            await cp(await safePath(root, join('sources', doc.docId)), join(destination, 'sources', doc.docId), { recursive: true, errorOnExist: false });
+            for (const chunk of doc.chunks) {
+                const content = await readFile(await safePath(root, chunk.path), 'utf8');
+                if (hash(content) !== chunk.contentHash)
+                    throw new Error('旧版本片段已变化，请先修复');
+                chunk.content = content;
+            }
+        }
+        return docs;
+    }
+    async publish(kbId, revision, stage, manifest, operation) {
+        const kbRoot = this.kbRoot(kbId), target = join(kbRoot, 'revisions', id(revision));
+        await atomicWrite(join(stage, 'manifest.json'), manifest);
+        await mkdir(join(kbRoot, 'revisions'), { recursive: true });
+        try {
+            await rename(stage, target);
+        }
+        catch (error) {
+            if (!['EEXIST', 'ENOTEMPTY'].includes(String(code(error))))
+                throw error;
+            const existing = await readJson(join(target, 'manifest.json'), manifestSchema);
+            if (existing.buildKey !== manifest.buildKey)
+                throw new Error('版本发布冲突');
+        }
+        // The pointer owns visibility. Replaying the same job after a crash is idempotent.
+        await atomicWrite(join(kbRoot, 'current.json'), { revision, publishedAt: now(), buildKey: manifest.buildKey, coverageIncomplete: manifest.coverageIncomplete });
+        await this.serialized(async () => {
+            const logFile = join(kbRoot, 'log.md'), old = await readFile(logFile, 'utf8'), line = `- ${operation.jobId} ${now()} ${operation.kind} ${revision} ← ${operation.docId}\n`;
+            if (!old.includes(`- ${operation.jobId} `))
+                await atomicWrite(logFile, old + line);
+        });
+        return target;
+    }
+    async overlays(kbId) { return readJson(join(this.kbRoot(kbId), 'overlays.json'), z.record(z.string(), overlaySchema), {}); }
+    async setOverlay(kbId, key, value, expectedHash) {
+        return this.serialized(async () => {
+            const overlays = await this.overlays(kbId);
+            if (expectedHash && hash(overlays[key] || null) !== expectedHash)
+                throw new Error('图片复核已变化，请刷新');
+            if (value === null)
+                delete overlays[key];
+            else
+                overlays[key] = { ...value, updatedAt: now() };
+            await atomicWrite(join(this.kbRoot(kbId), 'overlays.json'), overlays);
+            return overlays[key];
+        });
+    }
+    async jobDirectories() { return (await readdir(join(this.root, 'jobs'), { withFileTypes: true })).filter(d => d.isDirectory()).map(d => join(this.root, 'jobs', d.name)); }
+    async acquireOwner() {
+        const dir = join(this.root, '.owner.lock'), nonce = randomUUID();
+        try {
+            await mkdir(dir);
+        }
+        catch (error) {
+            if (code(error) !== 'EEXIST')
+                throw error;
+            const owner = await readJson(join(dir, 'owner.json'), z.object({ pid: z.number().int().positive(), startedAt: z.string(), nonce: z.string().optional() }), null);
+            if (!owner) {
+                const info = await stat(dir);
+                if (Date.now() - info.mtimeMs < 60000)
+                    throw new Error('知识库任务服务正在初始化');
+            }
+            if (owner?.pid) {
+                try {
+                    process.kill(owner.pid, 0);
+                    throw new Error('另一个知识库任务服务正在使用此数据根目录');
+                }
+                catch (e) {
+                    if (code(e) !== 'ESRCH')
+                        throw e;
+                }
+            }
+            await rm(dir, { recursive: true, force: true });
+            await mkdir(dir);
+        }
+        await atomicWrite(join(dir, 'owner.json'), { pid: process.pid, startedAt: now(), nonce });
+        return async () => {
+            const owner = await readJson(join(dir, 'owner.json'), z.object({ nonce: z.string().optional() }), null);
+            if (owner?.nonce === nonce)
+                await rm(dir, { recursive: true, force: true });
+        };
+    }
+}

package/lib/tools.d.ts

@@ -0,0 +1,3 @@
+import type { Runtime } from './runtime.ts';
+/** Registry validates declared parameters, then strict domain schemas reject unknown identities and options. */
+export declare function tools(runtime: Runtime): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,72 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { AttachmentId } from '@deepseek-ai/dsh-attachment';
+import { z } from 'zod';
+import { prepareImage } from "./figures/process.js";
+import { buildSchema, jobActionSchema, catalogQuerySchema, readQuerySchema, searchSchema, assetQuerySchema } from "./shared.js";
+import { checkAbort, message } from "./util.js";
+const str = (description) => ({ type: 'string', description });
+const bool = (description) => ({ type: 'boolean', description });
+const int = (description) => ({ type: 'integer', description });
+const selector = str('已登记知识库 ID 或唯一库名'), revision = str('固定的知识库版本；首次检索可省略');
+const canonical = (value) => z.json().parse(JSON.parse(JSON.stringify(value)));
+function jobView(job) {
+    const { jobId, kbId, docId, revision, state, error, outputPath, progress, routes, usage, report, failures } = job;
+    return { jobId, kbId, docId, revision, state, error, outputPath, progress, models: routes, usage: { calls: usage.calls, tokens: usage.tokens, reportedCalls: usage.reportedCalls }, report: report ? { chunks: report.chunks, figures: report.figures, withinTarget: report.withinTarget, targetChars: report.targetChars, issueCount: report.issues.length, issues: report.issues.slice(0, 12), ...report.pdf ? { pdf: { pageCount: report.pdf.pageCount, selectedPages: report.pdf.selectedPages, ocrPages: report.pdf.ocrPages, matchedBookmarks: report.pdf.matchedBookmarks, needsReviewPages: report.pdf.pages.filter(p => p.status === 'needs-review' || p.status === 'failed').map(p => p.page).slice(0, 30) } } : {} } : null, failures: failures.slice(-3) };
+}
+const attachmentSchema = z.object({ attachmentId: z.string().transform(AttachmentId), mediaType: z.enum(['image/png', 'image/jpeg', 'image/webp', 'image/gif']), bytes: z.number(), width: z.number(), height: z.number(), name: z.string().optional(), originalDimensions: z.object({ width: z.number(), height: z.number() }).optional() }).transform(({ name, originalDimensions, ...value }) => ({ ...value, ...name === undefined ? {} : { name }, ...originalDimensions === undefined ? {} : { originalDimensions } }));
+/** Registry validates declared parameters, then strict domain schemas reject unknown identities and options. */
+export function tools(runtime) {
+    const { jobs, store, retrieval, ready, config } = runtime;
+    const define = (name, title, description, parameters, execute, render) => defineTool({
+        name: `libing_${name}`, description, parameters, output: { schema: { type: 'json' }, render: render ?? ((_args, value) => [{ type: 'text', text: JSON.stringify(value) }]) },
+        presentCall: args => ({ card: 'generic', title, kind: 'other', rawInput: args }),
+        execute: async (args, exec) => { await ready; checkAbort(exec.signal); return runtime.run(async (signal) => canonical(await execute(args, { ...exec, signal })), exec.signal); },
+    });
+    return [
+        define('kb_build', '构建知识库', '将指定 Word / PDF 构建为知识库；返回后台 jobId。仅明确允许时建库、跳过图片或接受缺口。', {
+            kbId: { ...selector, required: true }, createKb: bool('明确创建新库'), sourcePath: str('宿主本地 .docx/.doc/.pdf 路径，与 receiptId 二选一'), receiptId: str('页面上传收据'), title: str('文档标题'), sourceVersion: str('原文版本标签'), docId: str('更新时用原 docId'), chunkTargetChars: int('目标字符数 256–60000，默认6000'), pageStart: int('PDF 实际起始页，1起'), pageEnd: int('PDF 实际结束页，包含该页'), confirmRangeChange: bool('明确同意替换已有PDF范围'), visionProvider: str('宿主图片模型供应商'), visionModel: str('图片模型ID'), summaryProvider: str('宿主摘要供应商'), summaryModel: str('摘要模型ID'), skipImages: bool('明确跳过图片'), acceptPartial: bool('明确接受覆盖缺口'),
+        }, async (raw, exec) => {
+            let args = buildSchema.parse(raw);
+            if (args.createKb) {
+                try {
+                    await store.kb(args.kbId);
+                }
+                catch (error) {
+                    if (!message(error).startsWith('知识库不存在'))
+                        throw error;
+                    args = { ...args, kbId: (await store.create(args.kbId)).kbId };
+                }
+            }
+            const route = exec.agent?.session.requestHeader()?.config ?? exec.agent?.options;
+            return jobView(await jobs.submit(args, { sessionId: exec.agent?.session.id, ...route?.provider && route.model ? { route: { provider: route.provider, model: route.model } } : {} }));
+        }),
+        define('kb_job', '知识库任务', '查看、重试或取消任务。needs-review尚未发布，接受缺口及提高预算都需明确授权。', {
+            jobId: { ...str('构建任务ID'), required: true }, action: { type: 'string', enum: ['status', 'retry', 'cancel'] }, acceptPartial: bool('明确接受覆盖缺口'), maxModelCalls: int('新累计调用上限'), maxModelTokens: int('新累计实际token上限'),
+        }, async (raw) => { const args = jobActionSchema.parse(raw); return jobView(await jobs.action(args.jobId, args.action, args)); }),
+        define('kb_catalog', '知识库目录', '读取库清单或分页章节摘要。先选库，再按docId/nodeId导航。', {
+            kbId: selector, revision, docId: str('文档ID'), nodeId: str('章节节点ID'), page: int('索引页，从0起'),
+        }, async (raw) => retrieval.catalog(catalogQuerySchema.parse(raw))),
+        define('kb_search', '检索知识库', '用原始型号/信号检索正文；返回固定版本、来源位置、证据窗口和续读入口。', {
+            kbId: { ...selector, required: true }, revision, query: { ...str('问题或关键词'), required: true }, keywords: { type: 'array', items: { type: 'string' }, description: '原始标识或明确别名，最多32个' }, docId: str('可选文档范围'), limit: int('候选数1–30，默认6'),
+        }, async (raw) => retrieval.search(searchSchema.parse(raw))),
+        define('kb_read', '读取知识库原文', '短片段全文读取，长片段按匹配语义块与continuation续读；引用固定版本。', {
+            kbId: { ...selector, required: true }, revision, chunkId: { ...str('候选片段ID'), required: true }, query: str('长片段定位关键词'), keywords: { type: 'array', items: { type: 'string' } }, segmentIndex: int('continuation语义块编号'), offset: int('Unicode字符偏移'),
+        }, async (raw) => retrieval.read(readQuerySchema.parse(raw))),
+        define('kb_read_image', '核对知识库原图', '读取所选文档版本原图及裁片。当前模型须声明图片输入能力；忽略的图片不可作为证据。', {
+            kbId: { ...selector, required: true }, revision, docId: { ...str('文档ID'), required: true }, assetId: { ...str('图片ID'), required: true },
+        }, async (raw, exec) => {
+            const args = assetQuerySchema.parse(raw), kb = await store.kb(args.kbId), asset = await store.asset(kb.kbId, args.revision, args.docId, args.assetId);
+            const figures = asset.doc.figures.filter(f => f.assetId === args.assetId && f.status !== 'ignored'), region = asset.asset.source && asset.doc.sourceFormat === 'pdf';
+            if (!figures.length && (!region || asset.doc.figures.some(f => f.assetId === args.assetId && f.status === 'ignored')))
+                throw new Error('此版本的图片已忽略，请在图片复核恢复导入');
+            const route = exec.agent?.session.requestHeader()?.config ?? exec.agent?.options;
+            if (!route?.provider || !route.model)
+                throw new Error('当前会话模型路由不可用');
+            const info = await runtime.models.ctx.llm.resolveModelInfo(route.provider, route.model, exec.signal);
+            if (!info.inputModalities?.includes('image'))
+                throw new Error('当前模型未声明图片输入能力，请切换图像模型');
+            const prepared = await prepareImage(runtime.models.ctx, asset.file, config, exec.signal);
+            return { info: { kbId: kb.kbId, revision: asset.revision, docId: args.docId, assetId: args.assetId, ...region ? { source: asset.asset.source, selectedPages: asset.doc.selectedPages } : {}, figures: figures.map(f => ({ occurrenceId: f.occurrenceId, caption: f.caption, status: f.status, source: f.source })) }, images: prepared.images };
+        }, (_args, value) => { const result = z.object({ info: z.json(), images: z.array(z.object({ attachment: attachmentSchema })) }).parse(value); return [{ type: 'text', text: JSON.stringify(result.info) }, ...result.images.map(image => ({ type: 'image', attachment: image.attachment }))]; }),
+    ];
+}

package/lib/util.d.ts

@@ -0,0 +1,25 @@
+import type { z } from 'zod';
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+export declare const hash: (value: unknown) => string;
+export declare const chars: (value: unknown) => number;
+export declare const clip: (value: unknown, length: number) => string;
+export declare const escapeHtml: (value: unknown) => string;
+export declare const mdText: (value: unknown) => string;
+export declare const now: () => string;
+export declare const message: (error: unknown) => string;
+export declare const code: (error: unknown) => unknown;
+export declare function id(value: unknown, label?: string): string;
+export declare function text(value: unknown, label: string, max?: number): string;
+export declare function required<T>(value: T | null | undefined, label?: string): T;
+export declare function readJson<T>(file: string, schema: z.ZodType<T>): Promise<T>;
+export declare function readJson<T, F>(file: string, schema: z.ZodType<T>, fallback: F): Promise<T | F>;
+export declare function atomicWrite(file: string, value: unknown): Promise<void>;
+export declare function safePath(root: string, rel?: string, existing?: boolean): Promise<string>;
+export declare function fileBytes(file: string, max: number): Promise<Buffer>;
+export declare function checkAbort(signal: AbortSignal | undefined): void;
+export declare function tokensUsed(usage: TokenUsage | undefined): number;
+export declare function deferred<T>(): {
+    resolve: (value: T) => void;
+    reject: (error: unknown) => void;
+    promise: Promise<T>;
+};

package/lib/util.js

@@ -0,0 +1,89 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, realpath, stat, rm } from 'node:fs/promises';
+import { dirname, resolve, relative, isAbsolute, sep } from 'node:path';
+export const hash = (value) => createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex');
+export const chars = (value) => Array.from(String(value)).length;
+export const clip = (value, length) => Array.from(String(value)).slice(0, Math.max(0, length)).join('');
+export const escapeHtml = (value) => String(value).replace(/[&<>"']/gu, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch] ?? ch));
+export const mdText = (value) => String(value).replace(/[\r\n]/gu, ' ').replace(/[\\[\]<>*`|]/gu, ch => `\\${ch}`);
+export const now = () => new Date().toISOString();
+export const message = (error) => error instanceof Error ? error.message : String(error);
+export const code = (error) => typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+export function id(value, label = 'ID') {
+    if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9-]{0,95}$/u.test(value))
+        throw new Error(`${label} 无效`);
+    return value;
+}
+export function text(value, label, max = 2000) {
+    if (typeof value !== 'string' || !value.trim() || chars(value) > max)
+        throw new Error(`${label} 必须是 1–${max} 字符的文本`);
+    return value.trim();
+}
+export function required(value, label = '数据') {
+    if (value === null || value === undefined)
+        throw new Error(`${label} 缺失`);
+    return value;
+}
+export async function readJson(file, schema, fallback) {
+    try {
+        return schema.parse(JSON.parse(await readFile(file, 'utf8')));
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT' && fallback !== undefined)
+            return fallback;
+        throw error;
+    }
+}
+export async function atomicWrite(file, value) {
+    await mkdir(dirname(file), { recursive: true });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+        await rename(temp, file);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+export async function safePath(root, rel = '.', existing = true) {
+    if (typeof rel !== 'string' || rel.includes('\0') || isAbsolute(rel))
+        throw new Error('无效相对路径');
+    const base = await realpath(root), target = resolve(base, rel);
+    const inside = (value) => { const r = relative(base, value); return r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r); };
+    if (!inside(target))
+        throw new Error('路径越界');
+    let ancestor = target;
+    for (;;) {
+        try {
+            if (!inside(await realpath(ancestor)))
+                throw new Error('符号链接越界');
+            break;
+        }
+        catch (error) {
+            if (code(error) !== 'ENOENT' || existing)
+                throw error;
+            ancestor = dirname(ancestor);
+        }
+    }
+    return target;
+}
+export async function fileBytes(file, max) {
+    const info = await stat(file);
+    if (!info.isFile() || info.size > max)
+        throw new Error(`文件必须是普通文件且不超过 ${max} 字节`);
+    const value = await readFile(file);
+    if (value.length > max)
+        throw new Error('文件读取期间超过大小限制');
+    return value;
+}
+export function checkAbort(signal) { signal?.throwIfAborted(); }
+export function tokensUsed(usage) {
+    if (!usage)
+        return 0;
+    return [usage.inputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens].reduce((n, k) => n + (Number.isFinite(k) ? Math.max(0, k ?? 0) : 0), 0);
+}
+export function deferred() {
+    let result;
+    const promise = new Promise((resolve, reject) => { result = { resolve, reject }; });
+    return { promise, ...required(result) };
+}

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@dsh-libing/knowledge-base",
+  "version": "0.1.0",
+  "description": "知识治理：Word/PDF 导入、图表复核、可恢复任务与固定版本证据检索",
+  "type": "module",
+  "icon": "icon.svg",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client-types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "icon.svg",
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitcode.com/LiBing-DSH/dsh-libing.git",
+    "directory": "plugins/knowledge-base"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.4",
+    "zod": "4.4.3",
+    "@napi-rs/canvas": "1.0.9",
+    "fast-xml-parser": "5.11.1",
+    "fflate": "0.8.3",
+    "image-size": "2.0.4",
+    "jimp": "1.6.1",
+    "mammoth": "1.13.0",
+    "parse5": "8.0.1",
+    "pdfjs-dist": "6.3.289"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    },
+    "market": {
+      "displayName": {
+        "zh": "知识治理",
+        "en": "Knowledge Base"
+      },
+      "category": "utilities",
+      "icon": "icon.svg",
+      "maintainers": [
+        "@lujinxing"
+      ],
+      "compatibility": {
+        "dsh": "0.2.0-rc.2"
+      },
+      "allowedBuilds": []
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.client.build.json && node --import tsx/esm ../../scripts/build-client.ts knowledge-base",
+    "typecheck:client": "tsc -p tsconfig.client.json --noEmit"
+  }
+}