dsh-knowledge-library 0.1.0 → 0.2.0

package/dist/core/library.js

@@ -2,8 +2,10 @@ 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';
 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 +23,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 +66,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 {
@@ -95,6 +104,7 @@ export class Library {
         this.db.prepare('INSERT INTO material_fts (id,title,content) VALUES (?,?,?)').run(meta.id, meta.title, content);
     }
     rebuild() {
+        this.recoverNoteUpdate();
         this.warnings.length = 0;
         const entries = [];
         const visit = (directory, depth) => {
@@ -154,9 +164,11 @@ export class Library {
         return row;
     }
     get(id) {
+        this.recoverNoteUpdate();
         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 };
     }
+    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 +178,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 +243,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 +266,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 +287,10 @@ export class Library {
     }
     update(id, fields) {
         const item = this.get(id);
+        if (item.deletedAt)
+            throw new Error('请先从回收站恢复资料后再编辑');
         const { content, segments: _segments, path: oldPath, ...meta } = item;
+        const previous = structuredClone(meta);
         if (fields.title !== undefined) {
             if (!cleanString(fields.title))
                 throw new Error('标题不能为空');
@@ -291,23 +307,148 @@ 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 { content, segments: _segments, path, ...previous } = item;
+        const meta = { ...previous, updatedAt: now() };
+        if (deleted) {
+            meta.deletedAt = now();
+            meta.deletionId = randomUUID();
+        }
+        else {
+            delete meta.deletedAt;
+            delete meta.deletionId;
         }
-        atomicJson(join(path, 'metadata.json'), meta);
+        // 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,9 +458,116 @@ 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));
@@ -333,6 +581,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)
@@ -359,8 +609,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 +621,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 +634,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/purge.d.ts

@@ -0,0 +1,20 @@
+export interface PurgeTicket {
+    id: string;
+    source: string;
+    staged: string;
+    manifest: string;
+}
+/** Durable, confirmed cleanup work. Only owned material directories are removable. */
+export declare class PurgeStore {
+    private root;
+    readonly directory: string;
+    constructor(root: string);
+    private contained;
+    private tree;
+    private ticket;
+    validate(id: string, source: string): void;
+    list(): PurgeTicket[];
+    stage(id: string, source: string): PurgeTicket;
+    rollback(ticket: PurgeTicket): void;
+    finish(ticket: PurgeTicket): void;
+}

package/dist/core/purge.js

@@ -0,0 +1,106 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const validId = (id) => typeof id === 'string' && /^r_[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id);
+/** Durable, confirmed cleanup work. Only owned material directories are removable. */
+export class PurgeStore {
+    root;
+    directory;
+    constructor(root) {
+        this.root = root;
+        this.directory = join(root, '.system', 'purge');
+    }
+    contained(path) {
+        const rel = relative(this.root, resolve(path));
+        if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            throw new Error('清理路径超出资料库');
+        let current = this.root;
+        if (lstatSync(current).isSymbolicLink())
+            throw new Error('清理不支持符号链接');
+        for (const part of rel.split(sep)) {
+            current = join(current, part);
+            try {
+                if (lstatSync(current).isSymbolicLink())
+                    throw new Error('清理不支持符号链接');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    tree(path) {
+        this.contained(path);
+        const info = lstatSync(path);
+        if (info.isSymbolicLink())
+            throw new Error('清理不支持符号链接');
+        if (info.isDirectory())
+            for (const entry of readdirSync(path))
+                this.tree(join(path, entry));
+    }
+    ticket(id, source) {
+        if (!validId(id))
+            throw new Error('清理资料 ID 无效');
+        source = resolve(source);
+        const rel = relative(join(this.root, 'materials'), source);
+        if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) || basename(source) !== id)
+            throw new Error('清理目标不是资料目录');
+        const ticket = { id, source, staged: join(this.directory, id), manifest: join(this.directory, `${id}.json`) };
+        for (const path of [ticket.source, ticket.staged, ticket.manifest])
+            this.contained(path);
+        return ticket;
+    }
+    validate(id, source) { this.tree(this.ticket(id, source).source); }
+    list() {
+        this.contained(this.directory);
+        if (!existsSync(this.directory))
+            return [];
+        return readdirSync(this.directory).filter(name => name.endsWith('.json')).sort().map(name => {
+            const manifest = join(this.directory, name);
+            this.contained(manifest);
+            const data = JSON.parse(readFileSync(manifest, 'utf8'));
+            if (data.schemaVersion !== 1 || !validId(data.id) || name !== `${data.id}.json` || typeof data.source !== 'string' || isAbsolute(data.source))
+                throw new Error('待清理记录损坏');
+            return this.ticket(data.id, resolve(this.root, data.source));
+        });
+    }
+    stage(id, source) {
+        const ticket = this.ticket(id, source);
+        this.tree(ticket.source);
+        if (existsSync(ticket.staged))
+            throw new Error('该资料仍有待完成的文件清理');
+        mkdirSync(this.directory, { recursive: true });
+        writeFileSync(ticket.manifest, JSON.stringify({ schemaVersion: 1, id, source: relative(this.root, source) }), { flag: 'wx' });
+        try {
+            renameSync(ticket.source, ticket.staged);
+        }
+        catch (error) {
+            unlinkSync(ticket.manifest);
+            throw error;
+        }
+        return ticket;
+    }
+    rollback(ticket) {
+        const checked = this.ticket(ticket.id, ticket.source);
+        if (existsSync(checked.source))
+            throw new Error('原目录已有内容，无法回退文件清理');
+        this.tree(checked.staged);
+        renameSync(checked.staged, checked.source);
+        unlinkSync(checked.manifest);
+    }
+    finish(ticket) {
+        const checked = this.ticket(ticket.id, ticket.source);
+        if (existsSync(checked.source)) {
+            if (existsSync(checked.staged))
+                throw new Error('清理目录与原目录冲突，文件已保留');
+            // The process stopped before the move; no original file may be deleted.
+            unlinkSync(checked.manifest);
+            return;
+        }
+        if (existsSync(checked.staged)) {
+            this.tree(checked.staged);
+            // Both the absolute boundary and every descendant were checked above.
+            rmSync(checked.staged, { recursive: true, maxRetries: 2, retryDelay: 50 });
+        }
+        unlinkSync(checked.manifest);
+    }
+}

package/dist/directory-settings.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { DirectoryListing } from '@deepseek-ai/dsh-host-directory-picker';
+import { Library } from './core/library.js';
+import type { FetchPolicy } from './core/fetch.js';
+export type { DirectoryListing };
+export interface DirectorySettings {
+    status(): {
+        canChange: boolean;
+        canChangeNetwork: boolean;
+        picker: 'native' | 'browse' | null;
+        allowProxyFakeIp: boolean;
+    };
+    pick(signal: AbortSignal): Promise<string | null>;
+    list(path: string | undefined, signal: AbortSignal): Promise<DirectoryListing>;
+    change(root: string, expectedRoot: string): Promise<string>;
+    setProxyMode(enabled: boolean, expected: boolean, expectedRoot: string): Promise<boolean>;
+}
+export declare function createDirectorySettings(ctx: Context, library: Library, policy?: FetchPolicy): DirectorySettings;