@mdfriday/foundry 26.4.20 → 26.5.1

package/dist/types/internal/domain/wiki/entity/knowledge-base.d.ts

@@ -0,0 +1,292 @@
+/**
+ * KnowledgeBase Aggregate Root
+ *
+ * 聚合根负责:
+ * - 持有所有子实体 (Entity, Concept, Connection, SourceRecord, OperationLog)
+ * - 提供所有业务方法 (ingestFromSource, query, generateWikiPages, lint)
+ * - 确保业务一致性
+ */
+import { Entity } from './entity';
+import { Concept } from './concept';
+import { Connection } from './connection';
+import { OperationLog } from './operation-log';
+import { EmbeddingIndex } from './embedding-index';
+import { SourceRecord } from '../value-object/source-record';
+import { EntityId } from '../value-object/entity-id';
+import { ExtractionResult } from '../value-object/extraction-result';
+import { ILLMProvider, IEmbeddingProvider, IFileSystem, IPathService, ICryptoService, IWikiPageRepository } from '../repository';
+export { Entity, Concept, Connection, SourceRecord, OperationLog };
+export declare class KnowledgeBase {
+    private _entities;
+    private _concepts;
+    private _connections;
+    private _sources;
+    private _operationLog;
+    private _embeddingIndex;
+    private _version;
+    private _createdAt;
+    private _updatedAt;
+    constructor();
+    /**
+     * 添加或合并实体
+     */
+    addOrMergeEntity(name: string, type: string, aliases: string[], facts: string[], sourcePath: string): Entity;
+    /**
+     * 添加或合并概念
+     */
+    addOrMergeConcept(name: string, definition: string, related: string[], aliases: string[], sourcePath: string): Concept;
+    /**
+     * 添加连接（去重）
+     */
+    addConnection(from: string, to: string, type: string, description: string, sourcePath: string): Connection;
+    /**
+     * 标记源文件已处理
+     */
+    markSource(record: SourceRecord): void;
+    /**
+     * 获取 OperationLog
+     */
+    getOperationLog(): OperationLog;
+    /**
+     * 获取统计信息 (包含 OperationLog)
+     */
+    getStats(): {
+        entities: number;
+        concepts: number;
+        connections: number;
+        sources: number;
+        operations: number;
+    };
+    /**
+     * 检查文件是否需要提取（基于哈希去重）
+     */
+    needsExtraction(path: string, mtime: number, contentHash: string): boolean;
+    /**
+     * 检查文件路径是否是全新来源（从未被 ingest 过）
+     *
+     * 用于增量构建场景：区分"全新文件"与"已处理文件"。
+     * 与 needsExtraction 不同：此方法仅判断路径是否存在，不考虑内容变化。
+     */
+    isNewSource(path: string): boolean;
+    /**
+     * 返回当前已知的所有 source 路径集合（用于增量过滤）
+     */
+    getIngestedPaths(): ReadonlySet<string>;
+    /**
+     * 回填 content hash（用于已存在但缺少哈希的文件）
+     */
+    backfillContentHash(path: string, contentHash: string, mtime: number): void;
+    get entities(): IterableIterator<Entity>;
+    get concepts(): IterableIterator<Concept>;
+    get connections(): ReadonlyArray<Connection>;
+    get sources(): IterableIterator<SourceRecord>;
+    getEntity(id: string): Entity | undefined;
+    getConcept(id: string): Concept | undefined;
+    getSource(id: string): SourceRecord | undefined;
+    /**
+     * 获取所有实体列表
+     */
+    getAllEntities(): Entity[];
+    /**
+     * 获取所有概念列表
+     */
+    getAllConcepts(): Concept[];
+    /**
+     * 获取所有来源列表
+     */
+    getAllSources(): SourceRecord[];
+    /**
+     * 获取与指定实体相关的连接
+     */
+    getConnectionsByEntity(entityId: EntityId): Connection[];
+    /**
+     * 获取来自指定来源的实体
+     */
+    getEntitiesBySource(sourceId: string): Entity[];
+    /**
+     * 获取来自指定来源的概念
+     */
+    getConceptsBySource(sourceId: string): Concept[];
+    /**
+     * 导出词汇表（供 LLM 提取时参考）
+     */
+    exportVocabulary(): string;
+    toJSON(): any;
+    static fromJSON(data: any): KnowledgeBase;
+    /**
+     * Merge extraction result into knowledge base
+     *
+     * 将提取结果合并到知识库中
+     * 这是原 KBMerger.merge() 的逻辑，移入聚合根
+     */
+    mergeExtraction(result: ExtractionResult, sourcePath: string, mtime: number, contentHash: string, origin: 'user-note' | 'daily' | string): void;
+    /**
+     * Ingest knowledge from source file (核心业务方法)
+     *
+     * 从源文件提取知识并合并到聚合根
+     * 依赖通过参数传入，不在聚合根内部持有
+     *
+     * @param sourcePath 源文件路径
+     * @param content 文件内容
+     * @param dependencies 外部依赖
+     * @returns 提取结果
+     */
+    ingestFromSource(sourcePath: string, content: string, dependencies: {
+        llmProvider: ILLMProvider;
+        model: string;
+        temperature?: number;
+        maxTokens?: number;
+        outputLanguage?: string;
+        fileSystem: IFileSystem;
+        crypto: ICryptoService;
+    }): Promise<{
+        success: boolean;
+        extractedEntities: number;
+        extractedConcepts: number;
+        extractedConnections: number;
+        timeMs: number;
+        error?: string;
+    }>;
+    /**
+     * Build extraction prompt (辅助方法)
+     */
+    private buildExtractionPrompt;
+    /**
+     * Retrieve entities and concepts based on query
+     *
+     * 多层混合检索 (关键词 + 路径 + [可选]语义向量)
+     * 使用 RRF 融合多路检索结果
+     * 这是原 WikiRetriever.retrieve() 的逻辑，移入聚合根
+     */
+    retrieve(question: string, options?: {
+        maxEntities?: number;
+        maxConcepts?: number;
+        embeddingIndex?: ReadonlyMap<string, number[]>;
+        queryEmbedding?: readonly number[];
+    }): {
+        question: string;
+        queryType: string;
+        entities: Entity[];
+        concepts: Concept[];
+        connections: Connection[];
+        sources: SourceRecord[];
+    };
+    /**
+     * Lint the knowledge base for issues
+     *
+     * 执行健康检查，发现知识库中的问题
+     * 这是原 WikiLinter.lint() 的逻辑，移入聚合根
+     */
+    lint(): Array<{
+        severity: 'error' | 'warning' | 'info';
+        type: string;
+        message: string;
+        location?: string;
+        suggestion?: string;
+    }>;
+    /**
+     * Query knowledge base (核心业务方法)
+     *
+     * 查询知识库，使用 LLM 生成答案
+     * 结合检索到的上下文
+     *
+     * @param question 用户问题
+     * @param dependencies 外部依赖
+     * @returns 查询结果
+     */
+    query(question: string, dependencies: {
+        llmProvider: ILLMProvider;
+        embeddingProvider?: IEmbeddingProvider;
+        model: string;
+        embeddingModel?: string;
+        temperature?: number;
+        maxResults?: number;
+    }): Promise<{
+        entities: Array<{
+            id: string;
+            name: string;
+            type: string;
+            relevance: number;
+        }>;
+        concepts: Array<{
+            name: string;
+            definition: string;
+            relevance: number;
+        }>;
+        connections: Array<{
+            from: string;
+            to: string;
+            type: string;
+            description: string;
+        }>;
+    }>;
+    /**
+     * Generate all wiki pages (核心业务方法)
+     *
+     * 生成所有 Wiki 页面（entities, concepts, sources, index, glossary, log）
+     *
+     * @param dependencies 外部依赖
+     */
+    generateWikiPages(dependencies: {
+        wikiPageRepo: IWikiPageRepository;
+        pathService: IPathService;
+        fileSystem: IFileSystem;
+    }): Promise<void>;
+    private renderEntityPage;
+    private renderConceptPage;
+    private renderSourcePage;
+    private generateIndex;
+    private generateGlossary;
+    private sanitizeFilename;
+    private getSourceFilename;
+    /**
+     * 初始化或增量更新 Embedding Index
+     *
+     * 首次调用时全量构建；后续调用时仅为尚未编入索引的实体/概念补充 embedding，
+     * 已存在的条目不重新生成，避免浪费 LLM 调用。
+     * 有新增条目时 isDirty=true，saveKB 会自动持久化。
+     */
+    buildEmbeddingIndex(dependencies: {
+        embeddingProvider: IEmbeddingProvider;
+        model: string;
+        cachePath: string;
+        fileSystem: IFileSystem;
+    }): Promise<void>;
+    /**
+     * 保存 Embedding Index 缓存
+     */
+    saveEmbeddingIndex(fileSystem: IFileSystem, pathService: IPathService): Promise<void>;
+    /**
+     * 获取 Embedding Index（如果存在）
+     */
+    getEmbeddingIndex(): EmbeddingIndex | null;
+    /**
+     * 检查是否有 Embedding Index
+     */
+    hasEmbeddingIndex(): boolean;
+    /**
+     * 构建查询上下文
+     *
+     * Domain 职责：决定如何组织知识上下文
+     */
+    private buildQueryContext;
+    /**
+     * 构建查询 Prompt
+     *
+     * Domain 职责：决定如何提示 LLM
+     */
+    private buildQueryPrompt;
+    /**
+     * Query Stream - 流式返回
+     *
+     * Domain 方法：使用内部 EmbeddingIndex
+     */
+    queryStream(question: string, dependencies: {
+        llmProvider: ILLMProvider;
+        embeddingProvider?: IEmbeddingProvider;
+        model: string;
+        embeddingModel?: string;
+        temperature?: number;
+        maxResults?: number;
+    }): AsyncGenerator<string, void, unknown>;
+}

package/dist/types/internal/domain/wiki/entity/operation-log.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OperationLog: 操作日志实体
+ *
+ * 设计理念：
+ * - 记录 Ingest, Query, Lint 等操作
+ * - 追加到 log.md 文件
+ * - 格式：## [YYYY-MM-DD HH:MM] operation | details
+ */
+export interface LogEntry {
+    timestamp: Date;
+    operation: 'ingest' | 'query' | 'lint' | 'generate' | 'save-answer';
+    details: string;
+    metadata?: Record<string, any>;
+}
+export interface IngestStats {
+    entities: number;
+    concepts: number;
+    connections: number;
+    sourcePath: string;
+}
+export interface QueryStats {
+    query: string;
+    resultCount: number;
+    answerSaved?: boolean;
+}
+export interface LintStats {
+    issuesCount: number;
+    categories: Record<string, number>;
+}
+export declare class OperationLog {
+    private entries;
+    /**
+     * 添加 Ingest 操作记录
+     */
+    addIngest(stats: IngestStats): void;
+    /**
+     * 添加 Query 操作记录
+     */
+    addQuery(stats: QueryStats): void;
+    /**
+     * 添加 Lint 操作记录
+     */
+    addLint(stats: LintStats): void;
+    /**
+     * 添加 Generate 操作记录
+     */
+    addGenerate(pageCount: number): void;
+    /**
+     * 添加 Save Answer 操作记录
+     */
+    addSaveAnswer(query: string, filepath: string): void;
+    /**
+     * 转换为 Markdown 格式
+     * 格式：## [YYYY-MM-DD HH:MM] operation | details
+     */
+    toMarkdown(): string;
+    /**
+     * 追加到现有的 log.md 内容
+     */
+    appendToExisting(existingContent: string): string;
+    /**
+     * 获取条目数量
+     */
+    get count(): number;
+    /**
+     * 清空日志
+     */
+    clear(): void;
+    /**
+     * 从 JSON 加载
+     */
+    static fromJSON(data: any): OperationLog;
+    /**
+     * 转换为 JSON
+     */
+    toJSON(): any;
+    private formatTimestamp;
+    private formatOperation;
+    private getFilename;
+    private truncate;
+    private formatCategories;
+}

package/dist/types/internal/domain/wiki/factory/wiki-factory.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Wiki Factory
+ *
+ * 负责 KnowledgeBase 聚合根的生命周期管理
+ * - 创建新的 KnowledgeBase
+ * - 从 Repository 加载 KnowledgeBase
+ * - 保存 KnowledgeBase 到 Repository
+ */
+import { KnowledgeBase } from '../entity/knowledge-base';
+import { IKBRepository, IWikiPageRepository } from '../repository';
+/**
+ * Wiki Factory Options
+ */
+export interface WikiFactoryOptions {
+    kbRepo: IKBRepository;
+    wikiPageRepo: IWikiPageRepository;
+}
+/**
+ * Wiki Factory
+ */
+export declare class WikiFactory {
+    private kbRepo;
+    private wikiPageRepo;
+    constructor(options: WikiFactoryOptions);
+    /**
+     * Create a new empty KnowledgeBase
+     */
+    create(): KnowledgeBase;
+    /**
+     * Load KnowledgeBase from repository
+     */
+    load(): Promise<KnowledgeBase | null>;
+    /**
+     * Save KnowledgeBase to repository
+     */
+    save(kb: KnowledgeBase): Promise<void>;
+    /**
+     * Get WikiPageRepository (供 Application 层使用)
+     */
+    getWikiPageRepository(): IWikiPageRepository;
+}

package/dist/types/internal/domain/wiki/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Wiki Domain Exports
+ */
+export * from './value-object/entity-id';
+export * from './value-object/entity-type';
+export * from './value-object/connection-type';
+export * from './value-object/source-record';
+export * from './value-object/extraction-result';
+export * from './value-object/extraction-parser';
+export * from './value-object/wiki-config';
+export * from './value-object/retrieval';
+export * from './value-object/content-annotator';
+export * from './value-object/wiki-page-renderer';
+export * from './value-object/wiki-index-generator';
+export * from './entity/entity';
+export * from './entity/concept';
+export * from './entity/connection';
+export * from './entity/knowledge-base';
+export * from './entity/conversation';
+export * from './entity/embedding-index';
+export { WikiFactory, WikiFactoryOptions } from './factory/wiki-factory';
+export * from './repository';

package/dist/types/internal/domain/wiki/repository/conversation-repository.interface.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Conversation Repository Interface
+ *
+ * Domain 层定义的对话存储接口
+ * Infrastructure 层提供具体实现
+ */
+import { Conversation } from '../entity/conversation';
+export interface SaveConversationOptions {
+    overwrite?: boolean;
+}
+export interface IConversationRepository {
+    /**
+     * 保存对话
+     * @returns 保存的文件路径
+     */
+    save(conversation: Conversation, options?: SaveConversationOptions): Promise<string>;
+    /**
+     * 获取所有对话
+     */
+    list(): Promise<Conversation[]>;
+    /**
+     * 检查对话是否存在
+     */
+    exists(conversationId: string): Promise<boolean>;
+    /**
+     * 获取对话文件路径
+     */
+    getFilePath(conversationId: string): string;
+}

package/dist/types/internal/domain/wiki/repository/crypto-service.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Crypto Service Interface
+ *
+ * Domain 层定义的加密/哈希服务接口
+ * Infrastructure 层提供具体实现（Node.js crypto）
+ */
+export interface ICryptoService {
+    /**
+     * Generate hash of content
+     */
+    hash(content: string, algorithm: 'sha256' | 'md5'): string;
+    /**
+     * Generate random UUID
+     */
+    randomUUID(): string;
+}

package/dist/types/internal/domain/wiki/repository/embedding-provider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Embedding Provider Interface
+ *
+ * Domain 层定义的 Embedding 服务接口
+ * Infrastructure 层提供具体实现
+ */
+export interface IEmbeddingProvider {
+    /**
+     * Generate embedding vector for text
+     */
+    generateEmbedding(text: string, model: string): Promise<number[]>;
+}

package/dist/types/internal/domain/wiki/repository/file-system.d.ts

@@ -0,0 +1,43 @@
+/**
+ * File System Interface
+ *
+ * Domain 层定义的文件系统接口
+ * Infrastructure 层提供具体实现（Node.js fs / Obsidian API）
+ */
+export interface FileStats {
+    mtimeMs: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+}
+export interface IFileSystem {
+    /**
+     * Read file content
+     */
+    readFile(path: string, encoding: string): Promise<string>;
+    /**
+     * Write file content
+     */
+    writeFile(path: string, content: string, encoding: string): Promise<void>;
+    /**
+     * Get file stats
+     */
+    stat(path: string): Promise<FileStats>;
+    /**
+     * Check if file/directory exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Create directory
+     */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Read directory
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Delete file
+     */
+    unlink(path: string): Promise<void>;
+}

package/dist/types/internal/domain/wiki/repository/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wiki Domain Repository Interfaces
+ *
+ * 统一导出所有 Repository 接口
+ */
+export * from './kb-repository.interface';
+export * from './wiki-page-repository.interface';
+export * from './conversation-repository.interface';
+export * from './llm-provider';
+export * from './llm-http-client';
+export * from './embedding-provider';
+export * from './file-system';
+export * from './path-service';
+export * from './crypto-service';

package/dist/types/internal/domain/wiki/repository/kb-repository.interface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Knowledge Base Repository Interface
+ *
+ * 定义 KB 持久化的抽象接口
+ */
+import { KnowledgeBase } from '../entity/knowledge-base';
+export interface IKBRepository {
+    /**
+     * 加载知识库
+     * @returns KnowledgeBase 或 null（如果不存在）
+     */
+    load(): Promise<KnowledgeBase | null>;
+    /**
+     * 检查知识库是否存在
+     */
+    exists(): Promise<boolean>;
+    /**
+     * 保存知识库
+     * @param kb 要保存的知识库
+     */
+    save(kb: KnowledgeBase): Promise<void>;
+    /**
+     * 获取最后修改时间
+     */
+    getLastModified(): Promise<number>;
+    /**
+     * 获取文件大小（字节）
+     */
+    getSize(): Promise<number>;
+}

package/dist/types/internal/domain/wiki/repository/llm-http-client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LLM HTTP Client Interface
+ *
+ * Domain 层定义的 HTTP 客户端接口，用于 LLM Provider
+ * 由 Infrastructure 层或外部环境（如 Obsidian Plugin）提供具体实现
+ *
+ * 设计目的：
+ * - 依赖倒置：Domain 定义接口，Infrastructure 提供实现
+ * - 解决 CORS：允许 Obsidian 使用 Electron net 模块绕过浏览器限制
+ * - 灵活扩展：支持不同环境的 HTTP 实现
+ */
+export interface LLMHttpRequest {
+    url: string;
+    method: 'GET' | 'POST';
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export interface LLMHttpResponse {
+    status: number;
+    statusText: string;
+    ok: boolean;
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+    json(): Promise<any>;
+}
+/**
+ * LLM HTTP Client 接口
+ *
+ * 提供 HTTP 请求能力，用于与 LLM 服务通信
+ */
+export interface LLMHttpClient {
+    /**
+     * 发送 HTTP 请求
+     *
+     * @param request - 请求配置
+     * @returns HTTP 响应（支持流式响应）
+     */
+    fetch(request: LLMHttpRequest): Promise<LLMHttpResponse>;
+}

package/dist/types/internal/domain/wiki/repository/llm-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * LLM Provider Interface
+ *
+ * Domain 层定义的 LLM 服务接口
+ * Infrastructure 层提供具体实现
+ */
+export interface LLMOptions {
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    systemMessage?: string;
+}
+export interface LLMStreamChunk {
+    text: string;
+    done: boolean;
+}
+export interface ILLMProvider {
+    /**
+     * Stream completion (yields chunks as they arrive)
+     */
+    complete(prompt: string, options: LLMOptions, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
+    /**
+     * Synchronous completion (wait for full response)
+     */
+    completeSync(prompt: string, options: LLMOptions, signal?: AbortSignal): Promise<string>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Provider name
+     */
+    readonly name: string;
+}

package/dist/types/internal/domain/wiki/repository/path-service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Path Service Interface
+ *
+ * Domain 层定义的路径操作接口
+ * Infrastructure 层提供具体实现（Node.js path）
+ */
+export interface IPathService {
+    /**
+     * Join path segments
+     */
+    join(...paths: string[]): string;
+    /**
+     * Get basename of path
+     */
+    basename(path: string, ext?: string): string;
+    /**
+     * Get directory name
+     */
+    dirname(path: string): string;
+    /**
+     * Get relative path
+     */
+    relative(from: string, to: string): string;
+    /**
+     * Resolve path to absolute
+     */
+    resolve(...paths: string[]): string;
+    /**
+     * Get file extension
+     */
+    extname(path: string): string;
+}