@lemoncat7/dsh-knowledge 1.2.0 → 2.0.0

package/lib/local-provider.js

@@ -1,6 +1,7 @@
 import { dirname, join } from 'node:path';
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { DatabaseSync } from 'node:sqlite';
 import { contentHash, DEFAULT_KNOWLEDGE_BASE_ID, newId, normalizeDraft, normalizeKnowledgeBaseDraft, normalizeKnowledgeMountDraft, normalizeKnowledgeSettings, nowIso, } from './domain.js';
 import { renderKnowledgeMarkdown } from './documents/markdown.js';
@@ -8,6 +9,7 @@ import { knowledgeDocumentPath } from './documents/path.js';
 import { KnowledgeDocumentStore } from './documents/store.js';
 import { enqueueDocumentProjection } from './documents/projection-queue.js';
 import { mergeKnowledgeBodies } from './knowledge-merge.js';
+import { NoteStore } from './notes/store.js';
 const ENTRY_COLUMNS = `
   id, knowledge_base_id, title, body, type, tags_json, scope_kind, scope_id, confidence,
   status, document_state, finalized_at, finalization_note, version, source_json, created_at, updated_at
@@ -22,6 +24,7 @@ const JOINED_ENTRY_COLUMNS = `
 const EXTRACTION_LEASE_MS = 15 * 60 * 1000;
 export class LocalKnowledgeProvider {
     mode = 'local';
+    notes;
     db;
     documentStore;
     documentsReady;
@@ -29,6 +32,10 @@ export class LocalKnowledgeProvider {
     constructor(path) {
         if (path !== ':memory:')
             mkdirSync(dirname(path), { recursive: true });
+        const inMemory = path === ':memory:';
+        this.notes = new NoteStore(inMemory
+            ? join(tmpdir(), `dsh-knowledge-notes-${randomUUID()}`)
+            : join(dirname(path), 'notes'), inMemory);
         this.documentStore = new KnowledgeDocumentStore(join(dirname(path), 'documents'));
         this.db = new DatabaseSync(path);
         this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
@@ -37,7 +44,7 @@ export class LocalKnowledgeProvider {
     }
     migrate() {
         let version = Number(this.db.prepare('PRAGMA user_version').get().user_version ?? 0);
-        if (version > 9)
+        if (version > 10)
             throw new Error(`knowledge database schema ${version} is newer than this plugin supports`);
         if (version === 0)
             this.db.exec(`
@@ -246,11 +253,52 @@ export class LocalKnowledgeProvider {
       PRAGMA user_version = 9;
       COMMIT;
     `);
+        if (version <= 8)
+            version = 9;
+        if (version === 9) {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.db.exec(`
+          CREATE TABLE knowledge_note_references (
+            knowledge_id TEXT NOT NULL REFERENCES knowledge_entries(id) ON DELETE CASCADE,
+            note_id TEXT NOT NULL,
+            source TEXT NOT NULL CHECK(source IN ('user','agent','legacy')),
+            source_session_id TEXT,
+            created_at TEXT NOT NULL,
+            PRIMARY KEY(knowledge_id, note_id)
+          );
+          CREATE INDEX knowledge_note_references_note ON knowledge_note_references(note_id, created_at DESC);
+        `);
+                this.backfillLegacyNoteReferences();
+                this.db.exec('PRAGMA user_version = 10; COMMIT');
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        }
         // Alpha v2 used a migration note as the default base's routing description.
         // Clear only that exact placeholder so existing user-authored descriptions stay untouched.
         this.db.prepare("UPDATE knowledge_bases SET description='' WHERE id=? AND description=?")
             .run(DEFAULT_KNOWLEDGE_BASE_ID, '由 0.2 版本迁移的知识。');
     }
+    backfillLegacyNoteReferences() {
+        const insert = this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_note_references(knowledge_id,note_id,source,source_session_id,created_at)
+      VALUES(?,?,'legacy',NULL,?)
+    `);
+        const timestamp = nowIso();
+        const rows = this.db.prepare("SELECT id,body FROM knowledge_entries WHERE body LIKE '%note://note_%'").all();
+        for (const row of rows) {
+            const noteIds = String(row.body).match(/note:\/\/(note_[a-f0-9]{32})/giu) ?? [];
+            for (const reference of new Set(noteIds)) {
+                const noteId = reference.slice('note://'.length).toLocaleLowerCase();
+                const note = this.notes.get(noteId);
+                if (note !== undefined && note.kind !== 'folder')
+                    insert.run(String(row.id), note.id, timestamp);
+            }
+        }
+    }
     assertOpen() {
         if (this.closed)
             throw new Error('knowledge provider is closed');
@@ -429,6 +477,68 @@ export class LocalKnowledgeProvider {
         const sql = `SELECT * FROM knowledge_documents${where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`} ORDER BY knowledge_base_id, CASE WHEN rel_path='README.md' THEN 0 ELSE 1 END, rel_path`;
         return this.db.prepare(sql).all(...args).map(rowToDocument);
     }
+    async listDocumentIndex(request) {
+        this.assertOpen();
+        await this.documentsReady;
+        const limit = Math.max(1, Math.min(request.limit, 100));
+        const where = [];
+        const args = [];
+        const knowledgeBaseIds = request.knowledgeBaseIds === undefined
+            ? undefined
+            : [...new Set(request.knowledgeBaseIds.map(id => id.trim()).filter(Boolean))];
+        if (knowledgeBaseIds !== undefined && knowledgeBaseIds.length === 0)
+            return { items: [], total: 0 };
+        if (knowledgeBaseIds !== undefined) {
+            where.push(`knowledge_base_id IN (${knowledgeBaseIds.map(() => '?').join(',')})`);
+            args.push(...knowledgeBaseIds);
+        }
+        if (request.activeKnowledgeBasesOnly) {
+            where.push("knowledge_base_id IN (SELECT id FROM knowledge_bases WHERE status='active')");
+        }
+        const query = request.query?.trim();
+        if (query) {
+            const like = `%${escapeSqlLike(query)}%`;
+            where.push(`(title LIKE ? ESCAPE '\\' OR rel_path LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\')`);
+            args.push(like, like, like);
+        }
+        const sourceWhere = where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`;
+        const cursorWhere = [];
+        const cursorArgs = [];
+        if (request.cursor !== undefined) {
+            const cursor = decodeDocumentCursor(request.cursor);
+            cursorWhere.push(`(
+        knowledge_base_id > ? OR
+        (knowledge_base_id = ? AND sort_rank > ?) OR
+        (knowledge_base_id = ? AND sort_rank = ? AND rel_path > ?) OR
+        (knowledge_base_id = ? AND sort_rank = ? AND rel_path = ? AND id > ?)
+      )`);
+            cursorArgs.push(cursor.knowledgeBaseId, cursor.knowledgeBaseId, cursor.sortRank, cursor.knowledgeBaseId, cursor.sortRank, cursor.relPath, cursor.knowledgeBaseId, cursor.sortRank, cursor.relPath, cursor.id);
+        }
+        const rows = this.db.prepare(`
+      WITH document_index AS (
+        SELECT
+          id, knowledge_base_id, rel_path, title, entry_count, content_hash,
+          document_state, finalized_at, finalization_note, created_at, updated_at,
+          CASE WHEN rel_path='README.md' THEN 0 ELSE 1 END AS sort_rank
+        FROM knowledge_documents${sourceWhere}
+      )
+      SELECT * FROM document_index
+      ${cursorWhere.length === 0 ? '' : `WHERE ${cursorWhere.join(' AND ')}`}
+      ORDER BY knowledge_base_id, sort_rank, rel_path, id
+      LIMIT ?
+    `).all(...args, ...cursorArgs, limit + 1);
+        const pageRows = rows.slice(0, limit);
+        const items = pageRows.map(rowToDocumentSummary);
+        const last = pageRows.at(-1);
+        const total = Number(this.db.prepare(`SELECT COUNT(*) AS total FROM knowledge_documents${sourceWhere}`).get(...args).total ?? 0);
+        return {
+            items,
+            total,
+            ...rows.length <= limit || last === undefined ? {} : {
+                nextCursor: encodeDocumentCursor(String(last.knowledge_base_id), Number(last.sort_rank), String(last.rel_path), String(last.id)),
+            },
+        };
+    }
     async getDocument(id) {
         this.assertOpen();
         await this.documentsReady;
@@ -871,6 +981,152 @@ export class LocalKnowledgeProvider {
         if (current !== undefined)
             await this.syncKnowledgeDocumentsQueued(current.knowledgeBaseId);
     }
+    async listNotes(request = {}) {
+        this.assertOpen();
+        return this.notes.list(request);
+    }
+    async getNote(id) {
+        this.assertOpen();
+        return this.notes.get(id);
+    }
+    async readNote(id) {
+        this.assertOpen();
+        return this.notes.read(id);
+    }
+    async createNoteFolder(name, parentId = null) {
+        this.assertOpen();
+        return this.notes.createFolder(name, parentId);
+    }
+    async createNoteDocument(name, parentId = null, content = '') {
+        this.assertOpen();
+        return this.notes.createDocument(name, parentId, content);
+    }
+    async updateNoteContent(id, content) {
+        this.assertOpen();
+        return this.notes.updateContent(id, content);
+    }
+    async renameNote(id, name) {
+        this.assertOpen();
+        return this.notes.rename(id, name);
+    }
+    async moveNote(id, parentId) {
+        this.assertOpen();
+        return this.notes.move(id, parentId);
+    }
+    async deleteNote(id) {
+        this.assertOpen();
+        const noteIds = this.notes.subtree(id).filter(node => node.kind !== 'folder').map(node => node.id);
+        const references = this.noteReferencesForNotes(noteIds);
+        if (references.length > 0)
+            throw conflict(`note content is referenced by ${references.length} knowledge document(s)`);
+        await this.notes.delete(id);
+        this.deleteNoteReferences(noteIds);
+    }
+    async searchNotes(query, limit) {
+        this.assertOpen();
+        const value = query.trim();
+        if (value.length === 0)
+            return [];
+        const boundedLimit = Math.max(1, Math.min(Math.trunc(limit), 100));
+        return this.notes.list({ query: value, limit: Math.min(500, boundedLimit * 3) })
+            .filter(node => node.kind !== 'folder')
+            .slice(0, boundedLimit);
+    }
+    async listKnowledgeNoteReferences(knowledgeId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        const rows = this.db.prepare(`
+      SELECT knowledge_id,note_id,source,source_session_id,created_at
+      FROM knowledge_note_references
+      WHERE knowledge_id=?
+      ORDER BY created_at,note_id
+    `).all(knowledgeId);
+        return rows.flatMap(row => {
+            const note = this.notes.get(String(row.note_id));
+            if (note === undefined || note.kind === 'folder')
+                return [];
+            return [{
+                    knowledgeId: entry.id,
+                    knowledgeBaseId: entry.knowledgeBaseId,
+                    documentTitle: entry.title,
+                    note,
+                    source: String(row.source),
+                    ...row.source_session_id == null ? {} : { sourceSessionId: String(row.source_session_id) },
+                    createdAt: String(row.created_at),
+                }];
+        });
+    }
+    async addKnowledgeNoteReference(knowledgeId, noteId, source, sourceSessionId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        if (entry.status !== 'active')
+            throw conflict('archived knowledge documents cannot change note references');
+        if (entry.documentState !== 'open')
+            throw finalizedConflict(entry);
+        const note = this.notes.get(noteId);
+        if (note === undefined)
+            throw notFound('note node', noteId);
+        if (note.kind === 'folder')
+            throw inputError('knowledge documents can reference note documents or files, not folders');
+        if (source !== 'user' && source !== 'agent' && source !== 'legacy')
+            throw inputError('invalid knowledge note reference source');
+        const sessionId = sourceSessionId?.trim() || undefined;
+        if (sessionId !== undefined && sessionId.length > 200)
+            throw inputError('reference source session id is too long');
+        const createdAt = nowIso();
+        this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_note_references(knowledge_id,note_id,source,source_session_id,created_at)
+      VALUES(?,?,?,?,?)
+    `).run(entry.id, note.id, source, sessionId ?? null, createdAt);
+        const reference = (await this.listKnowledgeNoteReferences(entry.id)).find(item => item.note.id === note.id);
+        if (reference === undefined)
+            throw new Error('knowledge note reference was not persisted');
+        return reference;
+    }
+    async deleteKnowledgeNoteReference(knowledgeId, noteId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        if (entry.status !== 'active')
+            throw conflict('archived knowledge documents cannot change note references');
+        if (entry.documentState !== 'open')
+            throw finalizedConflict(entry);
+        const result = this.db.prepare('DELETE FROM knowledge_note_references WHERE knowledge_id=? AND note_id=?').run(knowledgeId, noteId);
+        if (result.changes === 0)
+            throw notFound('knowledge note reference', `${knowledgeId}/${noteId}`);
+    }
+    noteReferencesForNotes(noteIds) {
+        this.assertOpen();
+        const ids = [...new Set(noteIds)];
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(',');
+        return this.db.prepare(`
+      SELECT r.note_id,e.knowledge_base_id,e.id AS document_id,e.title AS document_title
+      FROM knowledge_note_references r
+      JOIN knowledge_entries e ON e.id=r.knowledge_id
+      WHERE r.note_id IN (${placeholders})
+      ORDER BY e.updated_at DESC,e.id
+    `).all(...ids).map(row => ({
+            noteId: String(row.note_id),
+            knowledgeBaseId: String(row.knowledge_base_id),
+            documentId: String(row.document_id),
+            documentTitle: String(row.document_title),
+        }));
+    }
+    deleteNoteReferences(noteIds) {
+        this.assertOpen();
+        const ids = [...new Set(noteIds)];
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(',');
+        this.db.prepare(`DELETE FROM knowledge_note_references WHERE note_id IN (${placeholders})`).run(...ids);
+    }
     async propose(input, sourceKey) {
         this.assertOpen();
         const proposal = normalizeProposal(input);
@@ -1200,6 +1456,7 @@ export class LocalKnowledgeProvider {
         await this.documentsReady;
         this.closed = true;
         this.db.close();
+        await this.notes.close();
     }
     writeVersion(entry, changeKind) {
         const snapshot = {
@@ -1353,6 +1610,21 @@ function rowToDocument(row) {
         updatedAt: String(row.updated_at),
     };
 }
+function rowToDocumentSummary(row) {
+    return {
+        id: String(row.id),
+        knowledgeBaseId: String(row.knowledge_base_id),
+        relPath: String(row.rel_path),
+        title: String(row.title),
+        entryCount: Number(row.entry_count),
+        contentHash: String(row.content_hash),
+        documentState: row.document_state == null ? 'open' : String(row.document_state),
+        ...row.finalized_at == null ? {} : { finalizedAt: String(row.finalized_at) },
+        ...row.finalization_note == null ? {} : { finalizationNote: String(row.finalization_note) },
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
 function rowToVersion(row) {
     const snapshot = JSON.parse(String(row.snapshot_json));
     if (snapshot.knowledgeBaseId === undefined)
@@ -1613,12 +1885,40 @@ function decodeCursor(cursor) {
         throw Object.assign(new Error('invalid pagination cursor'), { code: 'BAD_REQUEST' });
     }
 }
+function encodeDocumentCursor(knowledgeBaseId, sortRank, relPath, id) {
+    return Buffer.from(JSON.stringify({ knowledgeBaseId, sortRank, relPath, id })).toString('base64url');
+}
+function decodeDocumentCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (typeof value.knowledgeBaseId !== 'string'
+            || (value.sortRank !== 0 && value.sortRank !== 1)
+            || typeof value.relPath !== 'string'
+            || typeof value.id !== 'string')
+            throw new Error();
+        return {
+            knowledgeBaseId: value.knowledgeBaseId,
+            sortRank: value.sortRank,
+            relPath: value.relPath,
+            id: value.id,
+        };
+    }
+    catch {
+        throw Object.assign(new Error('invalid document pagination cursor'), { code: 'BAD_REQUEST', status: 400 });
+    }
+}
+function escapeSqlLike(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+}
 function notFound(kind, id) {
     return Object.assign(new Error(`${kind} "${id}" was not found`), { code: 'NOT_FOUND' });
 }
 function conflict(message) {
     return Object.assign(new Error(message), { code: 'CONFLICT' });
 }
+function inputError(message) {
+    return Object.assign(new Error(message), { code: 'BAD_REQUEST', status: 400 });
+}
 function finalizedConflict(entry) {
     const label = entry.documentState === 'resolved' ? 'resolved' : 'collection complete';
     return conflict(`knowledge document "${entry.title}" (${entry.id}) is finalized as ${label}; reopen it before making changes`);