dsh-knowledge-library 0.1.1 → 0.3.0

package/dist/core/library.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import type { CaptureFields, CaptureResult, Citation, MaterialDetail, SearchOptions, SearchResult } from '../types.js';
+import type { CaptureFields, CaptureResult, Citation, EmptyTrashResult, MaterialDetail, PageImageManifest, SearchOptions, SearchResult, TrashSnapshot } from '../types.js';
 export declare const MAX_FILE_BYTES: number;
 export declare const MAX_TEXT_CHARS = 2000000;
 export declare function categoryName(value: unknown): string;
@@ -20,6 +20,23 @@ export declare class Library {
     };
     private row;
     get(id: string): MaterialDetail;
+    private readImageDataAt;
+    pageImages(id: string): PageImageManifest | undefined;
+    savePageImages(id: string, data: PageImageManifest): void;
+    savePageImageFile(id: string, imageId: string, bytes: Buffer): {
+        fileName: string;
+        checksum: string;
+        mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+        width: number;
+        height: number;
+        bytes: number;
+    };
+    pageImageFile(id: string, imageId: string): {
+        bytes: NonSharedBuffer;
+        mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+        name: string;
+    };
+    has(id: string): boolean;
     original(id: string): {
         bytes: Buffer;
         name: string;
@@ -32,13 +49,30 @@ export declare class Library {
     importBytes(name: string, bytes: Buffer, fields?: CaptureFields): CaptureResult;
     private decode;
     update(id: string, fields: CaptureFields): MaterialDetail;
-    saveNote(content: string, citations: Citation[], fields: CaptureFields): CaptureResult;
+    validateCategoryMove(id: string, category: string): void;
+    trash(id: string): MaterialDetail;
+    restore(id: string): MaterialDetail;
+    private setDeleted;
+    private trashPlan;
+    trashSnapshot(): TrashSnapshot;
+    private cleanupPendingPurge;
+    emptyTrash(expectedToken: string): EmptyTrashResult;
+    saveNote(content: string, citations: Citation[], fields: CaptureFields, knowledgeJobId?: string): CaptureResult;
+    private writeNoteSnapshot;
+    private archiveNoteUpdate;
+    private recoverNoteUpdate;
+    /** Append only after explicit confirmation. Existing paragraph IDs and text never change. */
+    appendNote(id: string, expectedFingerprint: string, addition: string, citations: Citation[], tags: string[], jobId: string): CaptureResult;
+    generatedNote(jobId: string): MaterialDetail | undefined;
     search(options?: SearchOptions): {
         items: SearchResult[];
         total: number;
     };
     stats(): {
         total: number;
+        trashed: number;
+        canEmptyTrash: boolean;
+        purgePending: number;
         ready: number;
         notes: number;
         inbox: number;

package/dist/core/library.js

@@ -2,8 +2,11 @@ import { DatabaseSync } from 'node:sqlite';
 import { randomUUID, createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, lstatSync, unlinkSync, openSync, closeSync } from 'node:fs';
 import { resolve, join, dirname, basename, extname, relative, isAbsolute } from 'node:path';
+import { PurgeStore } from './purge.js';
 import { extractArticle, formatTime, parseSubtitles, splitSegments } from './extract.js';
 import { validateUrl } from './fetch.js';
+import { noteFingerprint } from './incremental.js';
+import { imageHash, imageSupplement, inspectImage, validateImageManifest } from './page-images.js';
 export const MAX_FILE_BYTES = 64 * 1024 * 1024;
 export const MAX_TEXT_CHARS = 2_000_000;
 const hash = (data) => createHash('sha256').update(data).digest('hex');
@@ -21,6 +24,11 @@ export function atomicJson(path, value) {
     writeFileSync(tmp, JSON.stringify(value, null, 2), { encoding: 'utf8', flag: 'wx' });
     renameSync(tmp, path);
 }
+function atomicText(path, value) {
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, value, { encoding: 'utf8', flag: 'wx' });
+    renameSync(tmp, path);
+}
 export class Library {
     root;
     db;
@@ -59,7 +67,9 @@ export class Library {
             this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
         CREATE TABLE IF NOT EXISTS materials (id TEXT PRIMARY KEY, path TEXT NOT NULL, meta TEXT NOT NULL, content TEXT NOT NULL, content_hash TEXT NOT NULL, updated_at TEXT NOT NULL);
         CREATE VIRTUAL TABLE IF NOT EXISTS material_fts USING fts5(id UNINDEXED, title, content, tokenize='trigram');`);
+            this.recoverNoteUpdate();
             this.rebuild();
+            this.warnings.push(...this.cleanupPendingPurge().map(error => `待清理文件：${error}`));
         }
         catch (error) {
             try {
@@ -92,9 +102,11 @@ export class Library {
     index(meta, path, content) {
         this.db.prepare('INSERT OR REPLACE INTO materials VALUES (?,?,?,?,?,?)').run(meta.id, path, JSON.stringify(meta), content, meta.contentHash, meta.updatedAt);
         this.db.prepare('DELETE FROM material_fts WHERE id=?').run(meta.id);
-        this.db.prepare('INSERT INTO material_fts (id,title,content) VALUES (?,?,?)').run(meta.id, meta.title, content);
+        const supplement = meta.kind === 'web' ? imageSupplement(this.readImageDataAt(path)).text : '';
+        this.db.prepare('INSERT INTO material_fts (id,title,content) VALUES (?,?,?)').run(meta.id, meta.title, content + '\n\n' + supplement);
     }
     rebuild() {
+        this.recoverNoteUpdate();
         this.warnings.length = 0;
         const entries = [];
         const visit = (directory, depth) => {
@@ -125,6 +137,8 @@ export class Library {
                     }
                     // The physical category remains recoverable after an interrupted move.
                     meta.category = relative(join(this.root, 'materials'), dirname(path)).split('\\').join('/');
+                    if (meta.kind === 'web')
+                        this.readImageDataAt(path);
                     entries.push({ meta, path, content });
                 }
                 catch (error) {
@@ -154,9 +168,89 @@ export class Library {
         return row;
     }
     get(id) {
+        this.recoverNoteUpdate();
+        const row = this.row(id);
+        const meta = JSON.parse(row.meta);
+        const images = meta.kind === 'web' ? this.readImageDataAt(row.path) : undefined;
+        const supplement = imageSupplement(images);
+        return { ...meta, content: row.content + (supplement.text ? '\n\n' + supplement.text : ''), segments: [...JSON.parse(readFileSync(join(row.path, 'segments.json'), 'utf8')), ...supplement.segments], path: row.path,
+            ...(images ? { images: images.records.map(record => { const { text: _text, description: _description, fileName, checksum: _checksum, ...view } = record; return { ...view, model: images.model, originalAvailable: !!fileName && existsSync(join(row.path, 'images', fileName)), ...(record.status === 'completed' ? { segmentId: `v_${record.id.slice(4).replaceAll('-', '')}_1` } : {}) }; }) } : {}) };
+    }
+    readImageDataAt(path) {
+        const file = join(path, '.page-images.json');
+        this.assertContained(file);
+        if (!existsSync(file))
+            return;
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || imageHash(JSON.stringify(value.data)) !== value.checksum)
+            throw new Error('网页图片补充记录校验失败，请恢复 .page-images.json');
+        return validateImageManifest(value.data);
+    }
+    pageImages(id) { return structuredClone(this.readImageDataAt(this.row(id).path)); }
+    savePageImages(id, data) {
+        validateImageManifest(data);
+        const row = this.row(id);
+        const meta = JSON.parse(row.meta);
+        if (meta.kind !== 'web')
+            throw new Error('仅网页资料支持图片补充');
+        const previous = this.readImageDataAt(row.path);
+        if (previous && (previous.model !== data.model || previous.limit !== data.limit || previous.excluded !== data.excluded || JSON.stringify(previous.records.map(record => [record.id, record.url, record.alt])) !== JSON.stringify(data.records.map(record => [record.id, record.url, record.alt]))))
+            throw new Error('图片计划与模型已固定，不能静默更换');
+        for (const old of previous?.records.filter(image => image.status === 'completed') || [])
+            if (JSON.stringify(data.records.find(image => image.id === old.id)) !== JSON.stringify(old))
+                throw new Error('已保存的图片文字和段落不可改写');
+        const file = join(row.path, '.page-images.json');
+        this.assertContained(file);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            atomicJson(file, { data, checksum: imageHash(JSON.stringify(data)) });
+            this.index(meta, row.path, row.content);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            if (previous)
+                atomicJson(file, { data: previous, checksum: imageHash(JSON.stringify(previous)) });
+            else if (existsSync(file))
+                unlinkSync(file);
+            throw error;
+        }
+    }
+    savePageImageFile(id, imageId, bytes) {
+        if (!/^img_[a-f0-9-]{36}$/.test(imageId))
+            throw new Error('图片ID无效');
+        const row = this.row(id);
+        const meta = JSON.parse(row.meta);
+        if (meta.kind !== 'web' || meta.deletedAt)
+            throw new Error('网页已删除，停止保存图片');
+        const info = inspectImage(bytes);
+        const fileName = `${imageId}.${info.extension}`;
+        const directory = join(row.path, 'images');
+        const file = join(directory, fileName);
+        this.assertContained(file);
+        mkdirSync(directory, { recursive: true });
+        const checksum = imageHash(bytes);
+        if (existsSync(file)) {
+            if (imageHash(readFileSync(file)) !== checksum)
+                throw new Error('原图缓存校验失败，拒绝覆盖');
+        }
+        else
+            writeFileSync(file, bytes, { flag: 'wx' });
+        return { fileName, checksum, mediaType: info.mediaType, width: info.width, height: info.height, bytes: bytes.length };
+    }
+    pageImageFile(id, imageId) {
         const row = this.row(id);
-        return { ...JSON.parse(row.meta), content: row.content, segments: JSON.parse(readFileSync(join(row.path, 'segments.json'), 'utf8')), path: row.path };
+        const image = this.readImageDataAt(row.path)?.records.find(record => record.id === imageId);
+        if (!image?.fileName)
+            throw new Error('图片尚未保存');
+        const file = join(row.path, 'images', image.fileName);
+        this.assertContained(file);
+        const bytes = readFileSync(file);
+        if (imageHash(bytes) !== image.checksum)
+            throw new Error('原图校验失败，请检查图片文件');
+        return { bytes, mediaType: image.mediaType, name: image.fileName };
     }
+    has(id) { return Boolean(this.db.prepare('SELECT id FROM materials WHERE id=?').get(id)); }
     original(id) {
         const item = this.get(id);
         if (!item.originalFile || basename(item.originalFile) !== item.originalFile)
@@ -166,12 +260,13 @@ export class Library {
         return { bytes: readFileSync(path), name: item.originalName || item.originalFile };
     }
     save(content, fields, extra, original, suppliedSegments) {
+        this.recoverNoteUpdate();
         if (content.length > MAX_TEXT_CHARS)
             throw new Error('正文超过 200 万字符，请拆分后导入');
-        const digest = hash(`${extra.kind}\0${original ? hash(original.bytes) : content}\0${fields.sourceUrl ?? ''}\0${JSON.stringify(extra.citations ?? [])}`);
+        const digest = hash(`${extra.kind}\0${original ? hash(original.bytes) : content}\0${fields.sourceUrl ?? ''}\0${JSON.stringify(extra.citations ?? [])}${extra.knowledgeJobId ? `\0${extra.knowledgeJobId}` : ''}`);
         const duplicate = this.db.prepare('SELECT id FROM materials WHERE content_hash=? LIMIT 1').get(digest);
         if (duplicate)
-            return { material: this.get(duplicate.id), duplicate: true };
+            return { material: this.get(duplicate.id).deletedAt ? this.restore(duplicate.id) : this.get(duplicate.id), duplicate: true };
         const category = categoryName(fields.category);
         const id = `r_${randomUUID()}`;
         const timestamp = now();
@@ -230,7 +325,7 @@ export class Library {
         const source = validateUrl(url).href;
         const article = extractArticle(html, source);
         return this.save(article.content, { ...fields, title: fields.title || article.title, sourceUrl: source }, {
-            kind: 'web', author: article.author, extraction: 'Readability 正文提取；图片保留远程引用，未离线下载',
+            kind: 'web', author: article.author, extraction: `${article.extraction}；图片保留远程引用，未离线下载`,
         }, { name: 'page.html', bytes: Buffer.from(html) });
     }
     importFile(path, fields = {}) {
@@ -253,7 +348,7 @@ export class Library {
         }
         if (['.html', '.htm'].includes(extension)) {
             const article = extractArticle(this.decode(bytes), fields.sourceUrl || 'https://import.invalid/');
-            return this.save(article.content, { ...data, title: fields.title || article.title }, { kind: 'file', extraction: '本地 HTML 正文提取', author: article.author }, original);
+            return this.save(article.content, { ...data, title: fields.title || article.title }, { kind: 'file', extraction: `本地 HTML：${article.extraction}；图片保留远程引用，未离线下载`, author: article.author }, original);
         }
         if (['.txt', '.md', '.markdown', '.csv', '.json', '.log'].includes(extension)) {
             return this.save(this.decode(bytes), data, { kind: 'file', extraction: 'UTF-8 文本导入' }, original);
@@ -274,7 +369,12 @@ export class Library {
     }
     update(id, fields) {
         const item = this.get(id);
-        const { content, segments: _segments, path: oldPath, ...meta } = item;
+        if (item.deletedAt)
+            throw new Error('请先从回收站恢复资料后再编辑');
+        const row = this.row(id);
+        const { content, path: oldPath } = row;
+        const meta = JSON.parse(row.meta);
+        const previous = structuredClone(meta);
         if (fields.title !== undefined) {
             if (!cleanString(fields.title))
                 throw new Error('标题不能为空');
@@ -291,23 +391,150 @@ export class Library {
         meta.updatedAt = now();
         const path = join(this.root, 'materials', ...meta.category.split('/'), id);
         this.assertContained(path);
-        if (path !== oldPath) {
-            mkdirSync(dirname(path), { recursive: true });
-            renameSync(oldPath, path);
+        let moved = false;
+        let written = false;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            if (path !== oldPath) {
+                mkdirSync(dirname(path), { recursive: true });
+                renameSync(oldPath, path);
+                moved = true;
+            }
+            atomicJson(join(path, 'metadata.json'), meta);
+            written = true;
+            this.index(meta, path, content);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            if (written)
+                atomicJson(join(path, 'metadata.json'), previous);
+            if (moved)
+                renameSync(path, oldPath);
+            throw error;
+        }
+        return this.get(id);
+    }
+    validateCategoryMove(id, category) {
+        const source = this.get(id);
+        const target = join(this.root, 'materials', ...categoryName(category).split('/'), id);
+        this.assertContained(target);
+        if (resolve(target) !== resolve(source.path) && existsSync(target))
+            throw new Error('目标分类已有同ID目录，请检查后重试');
+    }
+    trash(id) { return this.setDeleted(id, true); }
+    restore(id) { return this.setDeleted(id, false); }
+    setDeleted(id, deleted) {
+        const item = this.get(id);
+        if (Boolean(item.deletedAt) === deleted)
+            return item;
+        const row = this.row(id);
+        const { content, path } = row;
+        const previous = JSON.parse(row.meta);
+        const meta = { ...previous, updatedAt: now() };
+        if (deleted) {
+            meta.deletedAt = now();
+            meta.deletionId = randomUUID();
         }
-        atomicJson(join(path, 'metadata.json'), meta);
+        else {
+            delete meta.deletedAt;
+            delete meta.deletionId;
+        }
+        // Keep the canonical files and stable IDs in place so existing citations
+        // remain readable. The flag also survives rebuilding a lost SQLite index.
         this.db.exec('BEGIN IMMEDIATE');
+        let written = false;
         try {
+            atomicJson(join(path, 'metadata.json'), meta);
+            written = true;
             this.index(meta, path, content);
             this.db.exec('COMMIT');
         }
         catch (error) {
             this.db.exec('ROLLBACK');
+            if (written)
+                atomicJson(join(path, 'metadata.json'), previous);
             throw error;
         }
         return this.get(id);
     }
-    saveNote(content, citations, fields) {
+    trashPlan() {
+        const rows = this.db.prepare('SELECT id,path,meta FROM materials ORDER BY id').all();
+        const items = rows.map(row => ({ ...row, metadata: JSON.parse(row.meta) })).filter(row => row.metadata.deletedAt);
+        const pending = new PurgeStore(this.root).list();
+        const token = hash(JSON.stringify({ items: items.map(row => [row.id, row.metadata.deletedAt, row.metadata.deletionId]), pending: pending.map(row => row.id) }));
+        return { items, pending, token };
+    }
+    trashSnapshot() {
+        const plan = this.trashPlan();
+        return { count: plan.items.length, pending: plan.pending.length, token: plan.token };
+    }
+    cleanupPendingPurge() {
+        const store = new PurgeStore(this.root);
+        const errors = [];
+        try {
+            for (const ticket of store.list()) {
+                try {
+                    store.finish(ticket);
+                }
+                catch (error) {
+                    errors.push(`${ticket.id}：${error.message}`);
+                }
+            }
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+        return errors;
+    }
+    emptyTrash(expectedToken) {
+        this.recoverNoteUpdate();
+        const plan = this.trashPlan();
+        if (typeof expectedToken !== 'string' || expectedToken !== plan.token)
+            throw new Error('回收站内容已改变，请重新打开清空确认窗口');
+        const store = new PurgeStore(this.root);
+        // Preflight the entire confirmed scope before moving or removing anything.
+        for (const item of plan.items) {
+            const expected = join(this.root, 'materials', ...categoryName(item.metadata.category).split('/'), item.id);
+            if (resolve(item.path) !== resolve(expected))
+                throw new Error('清理目标与资料目录不一致');
+            store.validate(item.id, item.path);
+        }
+        const errors = this.cleanupPendingPurge();
+        let deleted = 0;
+        for (const item of plan.items) {
+            try {
+                const ticket = store.stage(item.id, item.path);
+                let transaction = false;
+                try {
+                    this.db.exec('BEGIN IMMEDIATE');
+                    transaction = true;
+                    this.db.prepare('DELETE FROM material_fts WHERE id=?').run(item.id);
+                    this.db.prepare('DELETE FROM materials WHERE id=?').run(item.id);
+                    this.db.exec('COMMIT');
+                    transaction = false;
+                }
+                catch (error) {
+                    if (transaction)
+                        this.db.exec('ROLLBACK');
+                    store.rollback(ticket);
+                    throw error;
+                }
+                deleted++;
+                try {
+                    store.finish(ticket);
+                }
+                catch (error) {
+                    errors.push(`${item.id}：文件清理未完成，${error.message}`);
+                }
+            }
+            catch (error) {
+                errors.push(`${item.id}：${error.message}`);
+            }
+        }
+        return { deleted, pending: store.list().length, errors };
+    }
+    saveNote(content, citations, fields, knowledgeJobId) {
         if (!content?.trim())
             throw new Error('笔记内容不能为空');
         if (!Array.isArray(citations) || citations.length > 200)
@@ -317,14 +544,121 @@ export class Library {
             if (citation.segmentId && !source.segments.some(s => s.id === citation.segmentId))
                 throw new Error(`引用段落不存在：${citation.segmentId}`);
         }
-        return this.save(content.trim(), fields, { kind: 'note', citations, extraction: '知识笔记；内容由用户或 Agent 提供，请结合引用核验' });
+        return this.save(content.trim(), fields, { kind: 'note', citations, ...(knowledgeJobId ? { knowledgeJobId } : {}), extraction: '知识笔记；内容由用户或 Agent 提供，请结合引用核验' });
+    }
+    writeNoteSnapshot(snapshot) {
+        const path = join(this.root, 'materials', ...categoryName(snapshot.meta.category).split('/'), snapshot.meta.id);
+        for (const file of ['content.md', 'segments.json', 'metadata.json'])
+            this.assertContained(join(path, file));
+        atomicText(join(path, 'content.md'), snapshot.content);
+        atomicJson(join(path, 'segments.json'), snapshot.segments);
+        atomicJson(join(path, 'metadata.json'), snapshot.meta);
+        return path;
+    }
+    archiveNoteUpdate(update) {
+        const history = join(this.root, 'materials', ...categoryName(update.before.meta.category).split('/'), update.before.meta.id, '.history');
+        this.assertContained(history);
+        mkdirSync(history, { recursive: true });
+        const target = join(history, `${update.jobId}.json`);
+        this.assertContained(target);
+        renameSync(join(this.root, '.system', 'note-update.json'), target);
+    }
+    recoverNoteUpdate() {
+        const file = join(this.root, '.system', 'note-update.json');
+        this.assertContained(file);
+        if (!existsSync(file))
+            return;
+        const update = JSON.parse(readFileSync(file, 'utf8'));
+        if (!update || !/^knowledge_[a-f0-9-]+$/.test(update.jobId) || !['prepared', 'committed'].includes(update.phase))
+            throw new Error('笔记更新日志损坏，请检查 .system/note-update.json');
+        for (const snapshot of [update.before, update.after]) {
+            if (!snapshot || snapshot.meta?.kind !== 'note' || !/^r_[a-f0-9-]+$/.test(snapshot.meta.id) || typeof snapshot.content !== 'string' || !Array.isArray(snapshot.segments) || hash(snapshot.content) !== snapshot.meta.textChecksum || hash(JSON.stringify(snapshot.segments, null, 2)) !== snapshot.meta.segmentsChecksum)
+                throw new Error('笔记更新快照损坏，请检查更新日志');
+        }
+        if (update.before.meta.id !== update.after.meta.id || update.before.meta.category !== update.after.meta.category || update.after.meta.revision !== update.before.meta.revision + 1)
+            throw new Error('笔记更新版本无效');
+        const snapshot = update.phase === 'committed' ? update.after : update.before;
+        const path = this.writeNoteSnapshot(snapshot);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.index(snapshot.meta, path, snapshot.content);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+        if (update.phase === 'committed')
+            this.archiveNoteUpdate(update);
+        else
+            unlinkSync(file);
+    }
+    /** Append only after explicit confirmation. Existing paragraph IDs and text never change. */
+    appendNote(id, expectedFingerprint, addition, citations, tags, jobId) {
+        this.recoverNoteUpdate();
+        const previous = this.generatedNote(jobId);
+        if (previous)
+            return { material: previous, duplicate: true };
+        const item = this.get(id);
+        if (item.kind !== 'note' || item.deletedAt)
+            throw new Error('目标知识笔记已删除或不可用，请改为新建或重新整理');
+        if (noteFingerprint(item) !== expectedFingerprint)
+            throw new Error('已有笔记已改变，请改为新建，或重新整理后核对');
+        if (!/^knowledge_[a-f0-9-]+$/.test(jobId) || typeof addition !== 'string' || addition.length > 50_000)
+            throw new Error('笔记补充参数无效');
+        for (const citation of citations) {
+            const source = this.get(citation.materialId);
+            if (source.deletedAt || source.kind === 'note' || !citation.segmentId || !source.segments.some(s => s.id === citation.segmentId))
+                throw new Error('新增来源已删除或引用无效');
+        }
+        const merged = [...new Map([...item.citations, ...citations].map(c => [JSON.stringify([c.materialId, c.segmentId]), c])).values()];
+        if (merged.length > 200)
+            throw new Error('合并后来源超过200条，请改为新建笔记');
+        const mergedTags = [...new Set([...item.tags, ...this.tags(tags)])];
+        if (mergedTags.length > 30)
+            throw new Error('合并后标签超过30个，请减少标签或新建笔记');
+        const suffix = addition.trim() ? `## 知识补充 · ${now().slice(0, 10)}\n\n${addition.trim()}` : '';
+        const content = item.content + (suffix ? `\n\n${suffix}` : '');
+        if (content.length > MAX_TEXT_CHARS)
+            throw new Error('笔记超过正文上限，请改为新建');
+        const segments = [...item.segments, ...splitSegments(suffix).map(s => ({ ...s, id: `u_${randomUUID().replaceAll('-', '')}` }))];
+        const { content: oldContent, segments: oldSegments, path: _path, ...meta } = item;
+        const before = { meta, content: oldContent, segments: oldSegments };
+        const after = { content, segments, meta: { ...meta, revision: meta.revision + 1, updatedAt: now(), tags: mergedTags, citations: merged, knowledgeUpdateJobIds: [...(meta.knowledgeUpdateJobIds || []), jobId], contentHash: hash(`note-update\0${content}\0${jobId}`), textChecksum: hash(content), segmentsChecksum: hash(JSON.stringify(segments, null, 2)) } };
+        const update = { jobId, phase: 'prepared', before, after };
+        const journal = join(this.root, '.system', 'note-update.json');
+        this.assertContained(journal);
+        atomicJson(journal, update);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const path = this.writeNoteSnapshot(after);
+            this.index(after.meta, path, content);
+            update.phase = 'committed';
+            atomicJson(journal, update);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            update.phase = 'prepared';
+            atomicJson(journal, update);
+            this.writeNoteSnapshot(before);
+            unlinkSync(journal);
+            throw error;
+        }
+        this.archiveNoteUpdate(update);
+        return { material: this.get(id), duplicate: false };
+    }
+    generatedNote(jobId) {
+        const row = this.db.prepare("SELECT id FROM materials WHERE json_extract(meta, '$.knowledgeJobId')=? OR EXISTS (SELECT 1 FROM json_each(materials.meta, '$.knowledgeUpdateJobIds') WHERE value=?) LIMIT 1").get(jobId, jobId);
+        return row ? this.get(row.id) : undefined;
     }
     search(options = {}) {
+        this.recoverNoteUpdate();
         const query = cleanString(options.query, 500);
         const limit = Math.max(1, Math.min(100, Number(options.limit) || 40));
         const offset = Math.max(0, Math.floor(Number(options.offset) || 0));
         const terms = query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
-        const rows = this.db.prepare('SELECT id,meta,content FROM materials ORDER BY updated_at DESC').all();
+        const rows = this.db.prepare('SELECT id,path,meta,content FROM materials ORDER BY updated_at DESC').all();
         // Literal substring matching guarantees one- and two-character Chinese searches.
         // FTS narrows body/title candidates for longer terms; metadata is always searched too.
         let indexed;
@@ -333,6 +667,8 @@ export class Library {
         }
         const matched = rows.filter(row => {
             const meta = JSON.parse(row.meta);
+            if (Boolean(meta.deletedAt) !== (options.trashed === true))
+                return false;
             if (options.category && meta.category !== options.category && !meta.category.startsWith(`${options.category}/`))
                 return false;
             if (options.kind && meta.kind !== options.kind)
@@ -344,7 +680,8 @@ export class Library {
             const metadataText = `${meta.title}\n${meta.category}\n${meta.tags.join(' ')}\n${meta.collection}\n${meta.sourceNote}`.toLocaleLowerCase();
             if (!terms.length)
                 return true;
-            const haystack = metadataText + '\n' + row.content.toLocaleLowerCase();
+            const supplement = meta.kind === 'web' ? imageSupplement(this.readImageDataAt(row.path)).text : '';
+            const haystack = metadataText + '\n' + row.content.toLocaleLowerCase() + '\n' + supplement.toLocaleLowerCase();
             // FTS is an optimization hint only; punctuation and Unicode never change correctness.
             return indexed?.has(row.id) || terms.every(term => haystack.includes(term));
         });
@@ -359,8 +696,10 @@ export class Library {
         };
     }
     stats() {
+        this.recoverNoteUpdate();
         const rows = this.db.prepare('SELECT meta FROM materials').all();
-        const materials = rows.map(row => JSON.parse(row.meta));
+        const all = rows.map(row => JSON.parse(row.meta));
+        const materials = all.filter(item => !item.deletedAt);
         const count = (select) => {
             const map = new Map();
             for (const m of materials)
@@ -369,7 +708,12 @@ export class Library {
                         map.set(key, (map.get(key) || 0) + 1);
             return [...map].sort((a, b) => a[0].localeCompare(b[0], 'zh')).map(([name, count]) => ({ name, count }));
         };
-        return { total: materials.length, ready: materials.filter(m => m.status === 'ready').length, notes: materials.filter(m => m.kind === 'note').length,
+        let purgePending = 0;
+        try {
+            purgePending = new PurgeStore(this.root).list().length;
+        }
+        catch { /* Clearing reports invalid cleanup records without breaking normal reading. */ }
+        return { total: materials.length, trashed: all.length - materials.length, canEmptyTrash: true, purgePending, ready: materials.filter(m => m.status === 'ready').length, notes: materials.filter(m => m.kind === 'note').length,
             inbox: materials.filter(m => m.category === '收件箱').length, categories: count(m => [m.category]),
             tags: count(m => m.tags), collections: count(m => [m.collection]), root: this.root, warnings: [...this.warnings] };
     }
@@ -377,6 +721,8 @@ export class Library {
         const item = this.get(id);
         const header = JSON.stringify({ id: item.id, title: item.title, category: item.category, tags: item.tags, collection: item.collection, sourceUrl: item.sourceUrl, createdAt: item.createdAt, revision: item.revision }, null, 2);
         const references = item.citations.map(c => {
+            if (!this.has(c.materialId))
+                return `- 来源已永久删除 — library://${c.materialId}${c.segmentId ? `/${c.segmentId}` : ''}`;
             const source = this.get(c.materialId);
             const segment = c.segmentId ? source.segments.find(p => p.id === c.segmentId) : undefined;
             return `- ${source.title} — library://${source.id}${c.segmentId ? `/${c.segmentId}` : ''}${segment?.startSeconds !== undefined ? ` (${formatTime(segment.startSeconds)})` : ''}${source.sourceUrl ? ` — ${source.sourceUrl}` : ''}`;

package/dist/core/page-access.d.ts

@@ -0,0 +1,6 @@
+export declare class PageAccessError extends Error {
+    readonly code = "PAGE_REQUIRES_BROWSER";
+    constructor(site: string);
+}
+/** Match explicit challenge structure, not keywords occurring in an ordinary article. */
+export declare function assertArticleAccess(document: Document, source: string): void;

package/dist/core/page-access.js

@@ -0,0 +1,38 @@
+export class PageAccessError extends Error {
+    code = 'PAGE_REQUIRES_BROWSER';
+    constructor(site) {
+        super(`${site}返回了验证页面，尚未获取文章正文。请在浏览器打开原网页，完成验证后粘贴正文，或导入保存的 HTML。后台采集不共享浏览器的验证状态。`);
+        this.name = 'PageAccessError';
+    }
+}
+/** Match explicit challenge structure, not keywords occurring in an ordinary article. */
+export function assertArticleAccess(document, source) {
+    const url = new URL(source);
+    const host = url.hostname.toLowerCase().replace(/\.$/, '');
+    const text = (document.body?.textContent || '').replace(/\s+/g, ' ').trim();
+    const title = document.title?.trim() || '';
+    const heading = document.querySelector('h1,h2,.weui-msg__title')?.textContent?.trim() || '';
+    const verificationLink = document.querySelector('a[href*="/mp/wappoc_appmsgcaptcha"]');
+    let importedWechatChallenge = false;
+    if (host === 'import.invalid' && verificationLink) {
+        try {
+            importedWechatChallenge = new URL(verificationLink.getAttribute('href') || '', source).hostname === 'mp.weixin.qq.com';
+        }
+        catch { /* Not a recognizable verification link. */ }
+    }
+    if (host === 'mp.weixin.qq.com' || importedWechatChallenge) {
+        if (/^\/mp\/wappoc_appmsgcaptcha(?:\/|$)/i.test(url.pathname))
+            throw new PageAccessError('微信');
+        const content = document.querySelector('#js_content')?.textContent?.trim() || '';
+        const articleText = document.querySelector('article')?.textContent?.trim() || '';
+        if (content.length >= 40 || articleText.length >= 300)
+            return;
+        const environmentNotice = /当前环境异常/.test(text) && /完成验证|去验证/.test(text);
+        if (text.length < 2000 && environmentNotice && (verificationLink || title === '环境异常' || heading === '环境异常'))
+            throw new PageAccessError('微信');
+    }
+    const challengeTitle = /^(?:just a moment[.!…]*|attention required!?\s*\|\s*cloudflare)$/i.test(title);
+    const challengeForm = document.querySelector('#challenge-form,#challenge-running,form[action*="/cdn-cgi/challenge-platform/"]');
+    if (text.length < 3000 && challengeTitle && challengeForm)
+        throw new PageAccessError('网站');
+}

package/dist/core/page-images.d.ts

@@ -0,0 +1,15 @@
+import type { PageImageManifest, Segment } from '../types.js';
+export declare const imageHash: (value: string | Uint8Array) => string;
+export declare const imageFilePattern: RegExp;
+export declare function validateImageManifest(value: unknown): PageImageManifest;
+export declare function imageSupplement(data?: PageImageManifest): {
+    text: string;
+    segments: Segment[];
+};
+/** Sniff raster bytes and dimensions without decoding scripts or unbounded compressed content. */
+export declare function inspectImage(bytes: Buffer): {
+    extension: "png" | "jpg" | "gif" | "webp";
+    mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    width: number;
+    height: number;
+};