dsh-data-domain-knowledge 0.1.0-alpha.11 → 0.1.0-alpha.13

package/lib/types/environment/service.js

@@ -0,0 +1,253 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readdirSync, statSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { embeddingFingerprint } from '../compiler/embedding-identity.js';
+import { installRequiredEnvironment, requirementsFile } from './install.js';
+import { modelOptionsView, parseModelSelection } from './model-catalog.js';
+import { ENVIRONMENT_PROBE_VERSION } from './manifest.js';
+import { runProcess } from './process.js';
+import { readModelSelection, writeModelSelection } from './selection.js';
+const labels = { embedding: '向量模型', rerank: '重排模型' };
+function blankReport() {
+    return { state: 'unchecked', required: true, items: ['embedding', 'rerank'].map(id => ({ id, label: labels[id], state: 'unchecked', message: '首次使用前必须完成模型推理自检' })) };
+}
+function stamp(path) { try {
+    const value = statSync(path);
+    return [value.size, value.mtimeMs];
+}
+catch {
+    return null;
+} }
+function sitePackagesPath(pythonPath) {
+    const environmentRoot = dirname(dirname(pythonPath));
+    const windows = join(environmentRoot, 'Lib', 'site-packages');
+    try {
+        if (statSync(windows).isDirectory())
+            return windows;
+    }
+    catch { /* use the platform-neutral lib layout */ }
+    const libraryRoot = join(environmentRoot, 'lib');
+    try {
+        const versionDirectory = readdirSync(libraryRoot).find(name => /^python\d+\.\d+$/.test(name));
+        if (versionDirectory)
+            return join(libraryRoot, versionDirectory, 'site-packages');
+    }
+    catch { /* no venv/site-packages directory */ }
+    return join(libraryRoot, 'site-packages');
+}
+export function modelFilesProblem(path) {
+    if (!isAbsolute(path))
+        return '尚未准备本地模型，请安装默认资源或填写已下载模型的完整路径';
+    try {
+        const files = readdirSync(path);
+        if (!files.includes('config.json'))
+            return '模型缺少 config.json';
+        const weights = files.filter(name => /\.(safetensors|bin)$/.test(name));
+        if (!weights.length || weights.some(name => statSync(join(path, name)).size < 1024))
+            return '模型权重缺失或下载不完整';
+        const tokenizer = ['tokenizer.json', 'sentencepiece.bpe.model', 'vocab.txt'].some(name => files.includes(name) && statSync(join(path, name)).size >= 1024);
+        if (!tokenizer)
+            return '模型缺少完整分词器词表';
+    }
+    catch {
+        return '模型目录不存在或无法读取';
+    }
+    return undefined;
+}
+/** Preparation and readiness are shared by all bases in one deployment. */
+export class KnowledgeEnvironment {
+    options;
+    report = blankReport();
+    job;
+    checkPending;
+    work;
+    controller;
+    checkController;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    fingerprint() {
+        const { config, paths } = this.options.snapshot();
+        const env = dirname(dirname(paths.python));
+        return createHash('sha256').update(JSON.stringify({
+            probe: ENVIRONMENT_PROBE_VERSION, paths,
+            provider: config.embeddingProvider, rerank: config.rerankProvider, device: config.embeddingDevice, dimension: config.embeddingDimension, endpoint: config.embeddingBaseUrl,
+            embedding: embeddingFingerprint(paths.embeddingModel, this.options.resourceRoot), rerankModel: embeddingFingerprint(paths.rerankModel, this.options.resourceRoot),
+            python: stamp(paths.python), venv: stamp(join(env, 'pyvenv.cfg')), dependencies: stamp(sitePackagesPath(paths.python)), requirements: stamp(requirementsFile),
+        })).digest('hex');
+    }
+    view() {
+        if (!this.checkPending && this.report.state === 'ready' && this.report.fingerprint !== this.fingerprint())
+            this.report = blankReport();
+        const selection = readModelSelection(this.options.resourceRoot);
+        return structuredClone({ report: this.report, selection, models: modelOptionsView(), ...(this.job ? { job: this.job } : {}) });
+    }
+    invalidate() { if (!this.checkPending)
+        this.report = blankReport(); }
+    async requireReady() {
+        if (this.disposed)
+            throw new Error('环境服务已关闭');
+        if (this.job?.state === 'running')
+            throw new Error('环境正在准备或自检，请等待完成后再编译和召回');
+        const view = this.view();
+        const recent = view.report.checkedAt && Date.now() - Date.parse(view.report.checkedAt) < 5 * 60_000;
+        const report = view.report.state === 'ready' && recent ? view.report : await this.check(true);
+        if (report.state !== 'ready')
+            throw new Error(`环境未就绪：${report.items.filter(item => item.state !== 'ready').map(item => `${item.label}：${item.message}`).join('；')}。请在 Tita 设置中完成环境准备`);
+    }
+    check(deep = true) {
+        if (this.checkPending)
+            return this.checkPending;
+        const pending = this.performCheck(deep);
+        this.checkPending = pending;
+        void pending.finally(() => { if (this.checkPending === pending)
+            this.checkPending = undefined; }).catch(() => undefined);
+        return pending;
+    }
+    item(id, patch) {
+        this.report.items = this.report.items.map(item => item.id === id ? { ...item, ...patch } : item);
+    }
+    async performCheck(deep) {
+        const checkController = new AbortController();
+        this.checkController = checkController;
+        const signal = this.controller ? AbortSignal.any([this.controller.signal, checkController.signal]) : checkController.signal;
+        const fingerprint = this.fingerprint();
+        const { config, paths } = this.options.snapshot();
+        this.report = blankReport();
+        this.report.state = 'checking';
+        for (const id of ['embedding', 'rerank']) {
+            if (signal.aborted || this.disposed)
+                break;
+            const path = id === 'embedding' ? paths.embeddingModel : paths.rerankModel;
+            this.item(id, { path });
+            const disabled = id === 'embedding' ? config.embeddingProvider === 'none' : config.rerankProvider === 'none';
+            const problem = disabled ? '此能力是必需项，请启用模型'
+                : id === 'embedding' && config.embeddingProvider === 'ollama' ? undefined : modelFilesProblem(path);
+            if (problem) {
+                this.item(id, { state: 'missing', message: problem });
+                continue;
+            }
+            if (!deep) {
+                this.item(id, { state: 'unchecked', message: '资源已找到，尚未完成实际推理自检' });
+                continue;
+            }
+            this.item(id, { state: 'checking', message: '加载模型并运行推理自检，首次加载可能较慢' });
+            try {
+                const result = await this.options.probe(id);
+                this.item(id, { state: result.ok ? 'ready' : 'failed', message: result.message });
+            }
+            catch (cause) {
+                this.item(id, { state: 'failed', message: cause instanceof Error ? cause.message : String(cause) });
+            }
+        }
+        const changed = fingerprint !== this.fingerprint();
+        if (changed)
+            this.report.items = this.report.items.map(item => item.state === 'ready'
+                ? { ...item, state: 'unchecked', message: '自检期间配置或资源发生变化，请重新自检' }
+                : item);
+        if (signal.aborted || this.disposed)
+            this.report.items = this.report.items.map(item => item.state === 'checking'
+                ? { ...item, state: 'unchecked', message: '自检已停止，请重新运行' }
+                : item);
+        this.report.state = this.report.items.every(item => item.state === 'ready') ? 'ready' : 'blocked';
+        this.report.checkedAt = new Date().toISOString();
+        this.report.fingerprint = fingerprint;
+        if (this.checkController === checkController)
+            this.checkController = undefined;
+        return structuredClone(this.report);
+    }
+    start(action, requestedSelection) {
+        if (this.disposed)
+            throw new Error('环境服务已关闭');
+        if (this.job?.state === 'running')
+            return this.view();
+        const previousSelection = readModelSelection(this.options.resourceRoot);
+        const selection = action === 'install'
+            ? parseModelSelection(requestedSelection, previousSelection)
+            : previousSelection;
+        this.checkController?.abort();
+        this.controller = new AbortController();
+        const controller = this.controller;
+        this.job = { id: randomUUID(), state: 'running', stage: action === 'install' ? '准备安装' : '环境自检', startedAt: new Date().toISOString(), logs: [] };
+        const job = this.job;
+        const log = (line) => { job.logs = [...job.logs, line.slice(-1500)].slice(-12); };
+        const work = async () => {
+            try {
+                // A first-use guard can already be checking. Do not install into that probe.
+                if (this.checkPending)
+                    await this.checkPending;
+                if (controller.signal.aborted)
+                    throw new Error('ENVIRONMENT_CANCELLED');
+                if (action === 'install') {
+                    this.report = blankReport();
+                    this.report.state = 'checking';
+                    await (this.options.install ?? installRequiredEnvironment)(this.options.resourceRoot, controller.signal, label => {
+                        job.stage = label;
+                        for (const item of this.report.items)
+                            if (item.state === 'checking')
+                                this.item(item.id, { state: 'unchecked', message: '准备步骤已完成，等待实际自检' });
+                        const id = label.includes('向量') ? 'embedding' : label.includes('重排') ? 'rerank' : undefined;
+                        if (id)
+                            this.item(id, { state: 'checking', message: label });
+                    }, log, this.options.run ?? runProcess, selection);
+                    this.options.reload();
+                }
+                else
+                    this.options.reload();
+                job.stage = '运行实际推理自检';
+                const report = await this.check(true);
+                if (controller.signal.aborted)
+                    throw new Error('ENVIRONMENT_CANCELLED');
+                if (report.state !== 'ready')
+                    throw new Error(report.items.filter(item => item.state !== 'ready').map(item => `${item.label}：${item.message}`).join('；'));
+                await mkdir(this.options.resourceRoot, { recursive: true });
+                await writeFile(join(this.options.resourceRoot, 'environment-last-check.json'), JSON.stringify(report, null, 2));
+                job.state = 'succeeded';
+                job.stage = '环境已就绪';
+            }
+            catch (cause) {
+                if (action === 'install') {
+                    const activeSelection = readModelSelection(this.options.resourceRoot);
+                    if (activeSelection.embedding !== previousSelection.embedding || activeSelection.rerank !== previousSelection.rerank) {
+                        try {
+                            await writeModelSelection(this.options.resourceRoot, previousSelection);
+                            this.options.reload();
+                            this.report = blankReport();
+                            log('所选模型未通过自检，已恢复此前启用的模型');
+                        }
+                        catch (rollbackCause) {
+                            log(`恢复此前模型选择失败：${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`);
+                        }
+                    }
+                }
+                job.state = controller.signal.aborted ? 'cancelled' : 'failed';
+                job.error = controller.signal.aborted ? '已停止，已下载的资源可在下次重试时复用' : cause instanceof Error ? cause.message : String(cause);
+                job.stage = controller.signal.aborted ? '已停止' : '准备未完成';
+                if (this.report.state !== 'ready') {
+                    this.report.state = 'blocked';
+                    for (const item of this.report.items)
+                        if (item.state === 'checking')
+                            this.item(item.id, { state: controller.signal.aborted ? 'unchecked' : 'failed', message: job.error });
+                }
+            }
+            finally {
+                job.finishedAt = new Date().toISOString();
+                if (this.controller === controller)
+                    this.controller = undefined;
+            }
+        };
+        this.work = Promise.resolve().then(work);
+        return this.view();
+    }
+    async wait() { await this.work; }
+    cancel() {
+        this.controller?.abort();
+        this.checkController?.abort();
+        if (this.job?.state === 'running')
+            this.job.stage = '正在停止，请等待当前步骤结束';
+    }
+    close() { this.disposed = true; this.cancel(); }
+}
+//# sourceMappingURL=service.js.map

package/lib/types/environment/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/environment/service.ts"],"names":[],"mappings":"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"}

package/lib/types/environment/types.d.ts

@@ -0,0 +1,37 @@
+/** Installation state is deployment-wide; it is not knowledge or a build artifact. */
+import type { ModelOptionView, ModelSelection } from './model-catalog.js';
+export type EnvironmentItemId = 'embedding' | 'rerank';
+export type EnvironmentItemState = 'unchecked' | 'checking' | 'ready' | 'missing' | 'failed';
+export interface EnvironmentItem {
+    id: EnvironmentItemId;
+    label: string;
+    state: EnvironmentItemState;
+    message: string;
+    path?: string;
+}
+export interface EnvironmentReport {
+    state: 'unchecked' | 'checking' | 'blocked' | 'ready';
+    required: true;
+    checkedAt?: string;
+    fingerprint?: string;
+    items: EnvironmentItem[];
+}
+export interface EnvironmentJob {
+    id: string;
+    state: 'running' | 'succeeded' | 'failed' | 'cancelled';
+    stage: string;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+    logs: string[];
+}
+export interface EnvironmentView {
+    report: EnvironmentReport;
+    job?: EnvironmentJob;
+    selection: ModelSelection;
+    models: {
+        embedding: ModelOptionView[];
+        rerank: ModelOptionView[];
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/environment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/environment/types.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEzE,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,QAAQ,CAAA;AACtD,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAA;AAC5F,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,iBAAiB,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,oBAAoB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAA;IACrD,QAAQ,EAAE,IAAI,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AACD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AACD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,iBAAiB,CAAA;IACzB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,SAAS,EAAE,cAAc,CAAA;IACzB,MAAM,EAAE;QAAE,SAAS,EAAE,eAAe,EAAE,CAAC;QAAC,MAAM,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;CACpE"}

package/lib/types/environment/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types/environment/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/environment/types.ts"],"names":[],"mappings":""}

package/lib/types/events.d.ts

@@ -57,4 +57,14 @@ export interface EventEntity {
     createdAt: string;
     updatedAt: string;
 }
+export declare function compositeEventIdentity(occurredAt: string | null, coordinate: CardCoordinate, symptom: string | null): string;
+/** Recompute the aggregate after records are appended, pruned or redirected. */
+export declare function eventEntityFromRecords(input: {
+    id: string;
+    identityKey: string;
+    identityType: EventEntity['identityType'];
+    records: EventSourceRecord[];
+    createdAt: string;
+    updatedAt?: string;
+}): EventEntity;
 //# sourceMappingURL=events.d.ts.map

package/lib/types/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEpE,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEtE,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAClF,aAAa,EAAE,cAAc,CAAA;IAC7B,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,CAAA;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,eAAe,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAA;IAC9C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,iBAAiB,CAAA;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAClF,aAAa,EAAE,cAAc,CAAA;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5F,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,OAAO,EAAE,iBAAiB,EAAE,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"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"}

package/lib/types/events.js

@@ -1,2 +1,39 @@
-export {};
+import { createHash } from 'node:crypto';
+import { normalizeKnowledge } from './knowledge.js';
+export function compositeEventIdentity(occurredAt, coordinate, symptom) {
+    const payload = [occurredAt, coordinate.objectId, coordinate.actionId, coordinate.sceneId, normalizeKnowledge(symptom ?? '')];
+    return 'composite:' + createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, 24);
+}
+/** Recompute the aggregate after records are appended, pruned or redirected. */
+export function eventEntityFromRecords(input) {
+    const { id, identityKey, identityType, records } = input;
+    const first = records[0];
+    const firstCoordinate = records.find(record => record.coordinateIds.objectId || record.coordinateIds.actionId || record.coordinateIds.sceneId);
+    const sources = new Map();
+    for (const record of records) {
+        for (const source of record.sources)
+            sources.set(`${source.documentId}\u0001${source.quote}`, source);
+    }
+    return {
+        id, identityKey, identityType,
+        externalId: records.find(record => record.externalId)?.externalId ?? null,
+        title: first?.title ?? id,
+        summary: records.find(record => record.summary.trim())?.summary ?? first?.title ?? id,
+        coordinate: {
+            object: records.find(record => record.coordinate.object)?.coordinate.object ?? null,
+            action: records.find(record => record.coordinate.action)?.coordinate.action ?? null,
+            scene: records.find(record => record.coordinate.scene)?.coordinate.scene ?? null,
+        },
+        coordinateIds: firstCoordinate?.coordinateIds ?? { objectId: '', actionId: '', sceneId: '' },
+        occurredAt: records.find(record => record.occurredAt)?.occurredAt ?? null,
+        symptom: records.find(record => record.symptom)?.symptom ?? null,
+        timeline: records.flatMap(record => record.timeline.map(step => ({ ...step, sourceId: record.sourceId }))),
+        rootCauses: records.flatMap(record => record.rootCause ? [{ text: record.rootCause, status: record.rootCauseStatus, sourceId: record.sourceId }] : []),
+        outcomes: records.flatMap(record => record.outcome ? [{ text: record.outcome, sourceId: record.sourceId }] : []),
+        missing: [...new Set(records.flatMap(record => record.missing))],
+        sources: [...sources.values()], records,
+        createdAt: input.createdAt,
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+    };
+}
 //# sourceMappingURL=events.js.map

package/lib/types/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":""}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AA+CnD,MAAM,UAAU,sBAAsB,CAAC,UAAyB,EAAE,UAA0B,EAAE,OAAsB;IAClH,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,kBAAkB,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;IAC7H,OAAO,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACvG,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,sBAAsB,CAAC,KAOtC;IACC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,KAAK,CAAA;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACxB,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IAC9I,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,SAAS,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAA;IACvG,CAAC;IACD,OAAO;QACL,EAAE,EAAE,WAAW,EAAE,YAAY;QAC7B,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,UAAU,IAAI,IAAI;QACzE,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;QACzB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE;QACrF,UAAU,EAAE;YACV,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,IAAI,IAAI;YACnF,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,IAAI,IAAI;YACnF,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,IAAI,IAAI;SACjF;QACD,aAAa,EAAE,eAAe,EAAE,aAAa,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QAC5F,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,UAAU,IAAI,IAAI;QACzE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI,IAAI;QAChE,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC1G,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtJ,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChH,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAChE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO;QACvC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACvD,CAAA;AACH,CAAC"}

package/lib/types/images.d.ts

@@ -0,0 +1,26 @@
+/** Maximum decoded image size accepted by `images.publish`. */
+export declare const MAX_PUBLISHED_IMAGE_BYTES: number;
+export declare class ImagePublishError extends Error {
+    readonly code: string;
+    readonly suggestion?: string | undefined;
+    constructor(code: string, message: string, suggestion?: string | undefined);
+}
+export interface PublishKnowledgeImageInput {
+    filePath?: unknown;
+    contentBase64?: unknown;
+    filename?: unknown;
+    mimeType?: unknown;
+}
+export interface PublishedKnowledgeImage {
+    kb: string;
+    filename: string;
+    path: string;
+    url: string;
+    markdown: string;
+    mimeType: string;
+    bytes: number;
+    sha256: string;
+}
+/** Store one validated image using the knowledge assets content-hash bucket layout. */
+export declare function publishKnowledgeImage(rootDir: string, kb: string, input: PublishKnowledgeImageInput): Promise<PublishedKnowledgeImage>;
+//# sourceMappingURL=images.d.ts.map

package/lib/types/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../src/images.ts"],"names":[],"mappings":"AAMA,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,QAAmB,CAAA;AAYzD,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAmB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;gBAA3D,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAW,UAAU,CAAC,EAAE,MAAM,YAAA;CAIjF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAuED,uFAAuF;AACvF,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAoFlC"}

package/lib/types/images.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { ASSETS_DIR, PUBLISHED_IMAGE_MARKER } from './layout.js';
+import { writeBufferAtomic, writeTextAtomic } from './fs-atomic.js';
+/** Maximum decoded image size accepted by `images.publish`. */
+export const MAX_PUBLISHED_IMAGE_BYTES = 20 * 1024 * 1024;
+const IMAGE_FORMATS = [
+    { mimeType: 'image/png', extension: '.png' },
+    { mimeType: 'image/jpeg', extension: '.jpg' },
+    { mimeType: 'image/gif', extension: '.gif' },
+    { mimeType: 'image/webp', extension: '.webp' },
+    { mimeType: 'image/avif', extension: '.avif' },
+    { mimeType: 'image/bmp', extension: '.bmp' },
+    { mimeType: 'image/svg+xml', extension: '.svg' },
+];
+export class ImagePublishError extends Error {
+    code;
+    suggestion;
+    constructor(code, message, suggestion) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.name = 'ImagePublishError';
+    }
+}
+function invalid(message, suggestion) {
+    throw new ImagePublishError('IMAGE_INVALID', message, suggestion);
+}
+function normalizeMimeType(value) {
+    const mimeType = value.split(';', 1)[0].trim().toLowerCase();
+    return mimeType === 'image/jpg' ? 'image/jpeg' : mimeType;
+}
+function detectImageMimeType(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return 'image/png';
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    if (bytes.length >= 6 && (bytes.toString('ascii', 0, 6) === 'GIF87a' || bytes.toString('ascii', 0, 6) === 'GIF89a'))
+        return 'image/gif';
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 2) === 'BM')
+        return 'image/bmp';
+    if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+        const brands = bytes.toString('ascii', 8, Math.min(bytes.length, 32));
+        if (/(?:avif|avis)/.test(brands))
+            return 'image/avif';
+    }
+    // SVG is text, so recognize its root element after an optional XML declaration.
+    const text = bytes.toString('utf8', 0, Math.min(bytes.length, 4096)).replace(/^\uFEFF/, '').trimStart();
+    if (/^(?:<\?xml\b[^>]*>\s*)?<svg(?:\s|>)/i.test(text))
+        return 'image/svg+xml';
+    return undefined;
+}
+function decodeBase64(value) {
+    let encoded = value.trim();
+    let declaredMimeType;
+    if (encoded.startsWith('data:')) {
+        const match = /^data:([^;,]+);base64,([\s\S]*)$/i.exec(encoded);
+        if (!match)
+            invalid('content_base64 的 Data URI 格式无效。', '传标准 Base64，或传 data:image/png;base64,... 形式。');
+        declaredMimeType = normalizeMimeType(match[1]);
+        encoded = match[2];
+    }
+    encoded = encoded.replace(/\s+/g, '');
+    if (encoded.length > Math.ceil(MAX_PUBLISHED_IMAGE_BYTES * 4 / 3) + 8) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    if (encoded.length % 4 === 1 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}={0,2}|[A-Za-z0-9+/]{3}=?)?$/.test(encoded)) {
+        invalid('content_base64 不是有效的 Base64。');
+    }
+    const bytes = Buffer.from(encoded, 'base64');
+    if (bytes.length === 0)
+        invalid('图片内容不能为空。');
+    if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    if (bytes.toString('base64').replace(/=+$/, '') !== encoded.replace(/=+$/, ''))
+        invalid('content_base64 不是有效的 Base64。');
+    return { bytes, ...(declaredMimeType ? { declaredMimeType } : {}) };
+}
+function safeFilename(value, fallback, extension) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    const leaf = (raw.replace(/\\/g, '/').split('/').pop() ?? '').replace(/[\u0000-\u001f\u007f]/g, '');
+    const suppliedExtension = extname(leaf);
+    const stem = (suppliedExtension ? leaf.slice(0, -suppliedExtension.length) : leaf)
+        .replace(/[^\p{L}\p{N}._ -]/gu, '_')
+        .replace(/\s+/g, '-')
+        .replace(/^\.+$/, '')
+        .slice(0, 120);
+    return `${stem || fallback}${extension}`;
+}
+async function readExisting(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (cause) {
+        if (cause?.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    }
+}
+/** Store one validated image using the knowledge assets content-hash bucket layout. */
+export async function publishKnowledgeImage(rootDir, kb, input) {
+    const filePath = typeof input.filePath === 'string' ? input.filePath.trim() : '';
+    const base64 = typeof input.contentBase64 === 'string' ? input.contentBase64 : '';
+    if (Boolean(filePath) === Boolean(base64)) {
+        invalid('file_path 和 content_base64 必须且只能提供一个。');
+    }
+    let bytes;
+    let sourceName = '';
+    let dataUriMimeType;
+    if (filePath) {
+        let details;
+        try {
+            details = await stat(filePath);
+        }
+        catch (cause) {
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!details.isFile())
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FILE', 'file_path 必须指向一个文件。');
+        if (details.size > MAX_PUBLISHED_IMAGE_BYTES) {
+            throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+        }
+        try {
+            bytes = await readFile(filePath);
+        }
+        catch (cause) {
+            throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        sourceName = basename(filePath);
+    }
+    else {
+        const decoded = decodeBase64(base64);
+        bytes = decoded.bytes;
+        dataUriMimeType = decoded.declaredMimeType;
+    }
+    if (bytes.length === 0)
+        invalid('图片内容不能为空。');
+    if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+        throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`);
+    }
+    const mimeType = detectImageMimeType(bytes);
+    if (!mimeType)
+        invalid('文件内容不是支持的图片格式（PNG、JPEG、GIF、WebP、AVIF、BMP、SVG）。');
+    const declaredMimeType = typeof input.mimeType === 'string' && input.mimeType.trim()
+        ? normalizeMimeType(input.mimeType)
+        : dataUriMimeType;
+    if (declaredMimeType && declaredMimeType !== mimeType) {
+        invalid(`声明的 MIME 类型 ${declaredMimeType} 与图片内容 ${mimeType} 不一致。`);
+    }
+    const format = IMAGE_FORMATS.find(item => item.mimeType === mimeType);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    const bucket = sha256.slice(0, 12);
+    const filename = safeFilename(input.filename ?? sourceName, `image-${bucket}`, format.extension);
+    const assetDir = join(rootDir, ASSETS_DIR, bucket);
+    const assetPath = join(assetDir, filename);
+    let existing = await readExisting(assetPath);
+    let storedFilename = filename;
+    // The established bucket uses only the first 12 hash characters. If that prefix and the
+    // supplied filename both collide with different bytes, add more hash characters instead of
+    // replacing the existing asset.
+    if (existing && !existing.equals(bytes)) {
+        const extension = format.extension;
+        const stem = filename.slice(0, -extension.length);
+        storedFilename = `${stem}-${sha256.slice(12, 20)}${extension}`;
+        existing = await readExisting(join(assetDir, storedFilename));
+        if (existing && !existing.equals(bytes)) {
+            storedFilename = `image-${sha256}${extension}`;
+            existing = await readExisting(join(assetDir, storedFilename));
+        }
+    }
+    if (existing && !existing.equals(bytes)) {
+        throw new ImagePublishError('ASSET_NAME_COLLISION', '目标文件名已被不同内容占用，未覆盖现有图片。');
+    }
+    if (!existing?.equals(bytes))
+        await writeBufferAtomic(join(assetDir, storedFilename), bytes);
+    // Standalone hosted images have no SourceRaw or card by design. Keep that intent beside the
+    // asset so the orphan sweep does not mistake it for a disposable extraction artifact.
+    await writeTextAtomic(join(assetDir, PUBLISHED_IMAGE_MARKER), 'images.publish\n');
+    const relativePath = `${ASSETS_DIR}/${bucket}/${storedFilename}`;
+    const url = `/knowledge/assets/${encodeURIComponent(kb)}/${relativePath.split('/').map(encodeURIComponent).join('/')}`;
+    return {
+        kb,
+        filename: storedFilename,
+        path: relativePath,
+        url,
+        markdown: `![${storedFilename}](${url})`,
+        mimeType,
+        bytes: bytes.length,
+        sha256,
+    };
+}
+//# sourceMappingURL=images.js.map