@mdfriday/foundry 26.4.20 → 26.5.2

package/dist/types/internal/application/wiki-service.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Wiki Service - Application Layer
+ *
+ * 重构后的应用服务，遵循 DDD 架构：
+ * - 持有 WikiFactory 和统一配置
+ * - 通过 Factory 创建和加载 KB
+ * - 调用 KB 聚合根的业务方法
+ * - 协调依赖，不包含业务逻辑
+ * - 配置在创建时一次性传入，避免重复
+ */
+import { KnowledgeBase, WikiFactory, ConversationMetadata, TokenUsage, CostBreakdown, MODEL_PRICING, ModelPricing } from '../domain/wiki';
+import { WikiServiceConfig } from './wiki-service-config';
+/**
+ * Ingest 可选配置（用于覆盖默认值）
+ */
+export interface IngestOptions {
+    temperature?: number;
+    /** LLM token 使用量回调：实体/概念提取完成后触发精确值（isEstimate: false） */
+    onIngestTokenUsage?: (usage: TokenUsage) => void;
+    /**
+     * 实时流式进度回调：每个 LLM chunk 到达时触发，携带累计 completionTokens 估算值。
+     * 提供此回调时，ingest 改用流式模式，实现逐 chunk 实时上报（isEstimate: true）。
+     */
+    onIngestProgress?: (estimatedCompletionTokens: number) => void;
+    /** Embedding token 使用量回调：每次 embedding 调用完成后触发（构建索引时） */
+    onEmbeddingUsage?: (usage: TokenUsage) => void;
+}
+/**
+ * Query 可选配置（用于覆盖默认值）
+ */
+export interface QueryOptions {
+    temperature?: number;
+    maxResults?: number;
+    /** LLM token 使用量回调：在 LLM stream 完成时调用 */
+    onTokenUsage?: (usage: TokenUsage) => void;
+    /** Embedding token 使用量回调：query embedding 完成后调用 */
+    onEmbeddingUsage?: (usage: TokenUsage) => void;
+}
+export type { TokenUsage, CostBreakdown, ModelPricing };
+export { MODEL_PRICING };
+/**
+ * Ingest 结果
+ */
+export interface IngestResult {
+    success: boolean;
+    sourcePath: string;
+    extractedEntities: number;
+    extractedConcepts: number;
+    extractedConnections: number;
+    timeMs: number;
+    error?: string;
+}
+/**
+ * Query 结果
+ */
+export interface QueryResult {
+    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;
+    }>;
+}
+/**
+ * Lint 问题
+ */
+export interface LintIssue {
+    severity: 'error' | 'warning' | 'info';
+    type: string;
+    message: string;
+    location?: string;
+    suggestion?: string;
+}
+/**
+ * WikiService - 应用服务（协调层）
+ *
+ * 职责:
+ * - 持有 Factory 和统一配置
+ * - 协调聚合根操作
+ * - 管理辅助操作（保存对话、构建索引等）
+ * - 不包含业务逻辑
+ */
+export declare class WikiService {
+    private factory;
+    private kb;
+    private readonly config;
+    constructor(factory: WikiFactory, config: WikiServiceConfig);
+    private get llmProvider();
+    private get embeddingProvider();
+    private get fileSystem();
+    private get pathService();
+    private get cryptoService();
+    private get conversationRepo();
+    /**
+     * 加载 KB
+     *
+     * 如果配置了 embedding，自动构建索引
+     */
+    loadKB(): Promise<boolean>;
+    /**
+     * 保存 KB
+     *
+     * 同时保存 embedding index
+     */
+    saveKB(): Promise<void>;
+    /**
+     * 获取当前 KB 的统计信息
+     */
+    getStats(): {
+        entities: number;
+        concepts: number;
+        connections: number;
+        sources: number;
+        operations: number;
+    };
+    /**
+     * 获取 KnowledgeBase 实例（供高级用法）
+     */
+    getKnowledgeBase(): KnowledgeBase;
+    /**
+     * Ingest 文件
+     *
+     * 协调聚合根的 ingestFromSource 方法
+     * 使用配置的默认值，允许可选覆盖
+     * Ingest 后自动更新 embedding
+     */
+    ingestFile(filePath: string, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * 增量 Ingest 文件列表（业务逻辑在此封装）
+     *
+     * 规则：
+     *   - 对每个文件调用 kb.isNewSource(path) 进行判断
+     *   - 只对"全新文件"触发 ingestFile；已知文件直接跳过
+     *   - 返回新增/跳过文件数量，供上层进度汇报
+     *
+     * @param files      待检查的文件路径列表（绝对路径）
+     * @param options    ingest 选项（temperature 等）
+     * @param onFileProgress 每处理一个文件的回调（fileIndex, total, filePath, isNew）
+     */
+    ingestFolderIncremental(files: string[], options?: IngestOptions, onFileProgress?: (fileIndex: number, total: number, filePath: string, isNew: boolean) => void | Promise<void>): Promise<{
+        newFiles: string[];
+        skippedFiles: string[];
+        extractedEntities: number;
+        extractedConcepts: number;
+        extractedConnections: number;
+        timeMs: number;
+    }>;
+    /**
+     * Query (同步)
+     *
+     * 协调聚合根的 query 方法
+     * 使用配置的默认值，允许可选覆盖
+     * KB 会自动使用内部的 Embedding Index
+     */
+    query(question: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Query (流式)
+     *
+     * 使用 LLM 流式生成答案
+     * 使用配置的默认值，允许可选覆盖
+     * 委托给 KB 的 queryStream 方法
+     * 通过 options.onTokenUsage 回调上报 token 使用量
+     */
+    queryStream(question: string, options?: QueryOptions): AsyncGenerator<string, void, unknown>;
+    /**
+     * 生成所有 Wiki 页面
+     *
+     * 协调聚合根的 generateWikiPages 方法
+     */
+    generateAllPages(): Promise<void>;
+    /**
+     * Lint 检查
+     *
+     * 调用聚合根的 lint 方法
+     */
+    lint(): Promise<LintIssue[]>;
+    /**
+     * 估算 token 费用
+     *
+     * 无状态纯函数，不需要加载 KB。
+     * 根据 provider + model 在内置定价表中查找单价，计算输入/输出 token 的总成本。
+     *
+     * @param provider     LLM 或 embedding 提供商名称（如 "openai", "deepseek", "ollama"）
+     * @param model        模型名称（如 "gpt-4o"）
+     * @param inputTokens  输入 token 数（promptTokens）
+     * @param outputTokens 输出 token 数（completionTokens）
+     * @returns            费用明细，或 undefined（找不到该 provider 的任何定价）
+     */
+    calculateCost(provider: string, model: string, inputTokens: number, outputTokens: number): CostBreakdown | undefined;
+    /**
+     * 返回所有已知的模型定价数据（供 UI 展示定价表）
+     */
+    getPricingTable(): ModelPricing[];
+    /**
+     * 查找单个模型的定价数据
+     */
+    findModelPricing(provider: string, model: string): ModelPricing | undefined;
+    /**
+     * 为当前 KB 构建 Embedding Index
+     *
+     * 私有方法，由 loadKB 和 ingestFile 自动调用
+     */
+    private buildEmbeddingIndexForKB;
+    /**
+     * 手动触发 Embedding Index 构建
+     *
+     * 供外部调用（如测试）
+     */
+    buildEmbeddingIndex(): Promise<void>;
+    /**
+     * 保存对话结果为新的源文件
+     */
+    saveConversation(question: string, answer: string, metadata?: {
+        sources?: string[];
+        retrieval?: {
+            entityCount: number;
+            conceptCount: number;
+            totalResults: number;
+        };
+    }): Promise<string>;
+    /**
+     * 列出所有保存的对话
+     */
+    listConversations(): Promise<ConversationMetadata[]>;
+}

package/dist/types/internal/application/worker/pool-manager.d.ts

@@ -1,24 +1,67 @@
 import { WorkerTask, WorkerResponse } from './worker-main';
+/**
+ * Worker 池配置
+ */
 export interface WorkerPoolConfig {
     workerCount?: number;
     maxQueueSize?: number;
 }
+/**
+ * Worker 环境类型
+ */
 export type WorkerEnvironment = 'node' | 'browser';
+/**
+ * Worker 池管理器
+ * 负责创建和管理 Worker 池，支持 Node.js 和浏览器环境
+ */
 export declare class WorkerPoolManager {
     private pool;
     private environment;
     private workerCount;
     constructor(config?: WorkerPoolConfig);
+    /**
+     * 检测当前运行环境
+     *
+     * 优先检测 Worker 支持能力，而不仅仅依赖 process 对象的存在
+     * 这样可以正确识别 Electron/Obsidian 环境（有 Node.js API 但只支持 Web Workers）
+     */
     private detectEnvironment;
+    /**
+     * 计算最佳 Worker 数量
+     */
     private calculateOptimalWorkerCount;
+    /**
+     * 初始化 Worker 池
+     *
+     * 包含回退机制：如果 Node.js Worker Threads 初始化失败，
+     * 自动回退到 Web Workers（用于 Electron/Obsidian 等环境）
+     */
     initialize(): Promise<void>;
+    /**
+     * 初始化 Node.js Worker 池
+     */
     private initializeNodePool;
+    /**
+     * 初始化浏览器 Worker 池
+     *
+     * 在浏览器环境中，我们不使用文件，而是直接传递函数给 workerpool
+     * workerpool 会自动将函数序列化并在 Worker 中执行
+     */
     private initializeBrowserPool;
+    /**
+     * 执行 Worker 任务
+     */
     exec(task: WorkerTask): Promise<WorkerResponse>;
+    /**
+     * 获取池统计信息
+     */
     getStats(): {
         environment: WorkerEnvironment;
         workerCount: number;
         poolStats: any;
     } | null;
+    /**
+     * 清理 Worker 池
+     */
     terminate(): Promise<void>;
 }

package/dist/types/internal/application/worker/worker-browser.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 浏览器 Web Worker 入口（特殊版本）
+ *
+ * 这个 Worker 运行在 Blob URL 中，通过 postMessage 与主线程通信
+ * 主包的代码通过消息传递或共享内存访问
+ */
 declare const self: {
     addEventListener: (type: string, listener: (event: any) => void) => void;
     postMessage: (message: any) => void;

package/dist/types/internal/application/worker/worker-main.d.ts

@@ -1,14 +1,26 @@
 import { PageTask } from '@pkg/page-filter';
+/**
+ * Worker 任务类型
+ */
 export type WorkerTaskType = 'init' | 'process-batch' | 'stats' | 'cleanup';
+/**
+ * Worker 任务
+ */
 export interface WorkerTask {
     type: WorkerTaskType;
     projDir?: string;
     moduleDir?: string;
     pageTasks?: PageTask[];
 }
+/**
+ * Worker 响应
+ */
 export interface WorkerResponse {
     success: boolean;
     data?: any;
     error?: string | undefined;
 }
+/**
+ * 处理 Worker 任务的主函数
+ */
 export declare function handleWorkerTask(task: WorkerTask): Promise<WorkerResponse>;

package/dist/types/internal/application/worker/worker-state.d.ts

@@ -1,4 +1,7 @@
 import { PageTask } from '@pkg/page-filter';
+/**
+ * 批量渲染结果
+ */
 export interface BatchRenderResult {
     success: boolean;
     processedCount: number;
@@ -6,14 +9,34 @@ export interface BatchRenderResult {
     duration: number;
     errors: string[];
 }
+/**
+ * Worker 状态管理器
+ * 负责初始化和维护 Worker 的 SSG 环境
+ * 每个 Worker 初始化一次，然后复用来处理多个批次
+ */
 export declare class WorkerState {
     private projDir;
     private moduleDir;
     private initialized;
     constructor(projDir: string, moduleDir: string);
+    /**
+     * 初始化 Worker 环境（只执行一次）
+     */
     initialize(): Promise<void>;
+    /**
+     * 处理一个批次的页面任务
+     * 运行完整的 SSG 流程，但通过过滤器只处理指定任务
+     *
+     * @param pageTasks - 包含语言和路径信息的任务列表
+     */
     processBatch(pageTasks: PageTask[]): Promise<BatchRenderResult>;
+    /**
+     * 清理资源
+     */
     cleanup(): Promise<void>;
+    /**
+     * 获取统计信息
+     */
     getStats(): {
         initialized: boolean;
         projDir: string;

package/dist/types/internal/application/workspace.d.ts

@@ -1,38 +1,136 @@
+/**
+ * Application Layer: Workspace Management Service
+ *
+ * 职责：
+ * - 协调多个 domain 之间的交互
+ * - 提供应用级服务（如 Identity 需要 Workspace 存储）
+ * - 不包含业务逻辑（业务逻辑在 Domain 层）
+ */
 import { WorkspaceFactory, Workspace, Project } from '@internal/domain/workspace';
+/**
+ * Application Service Options
+ */
 export interface WorkspaceAppServiceOptions {
     workspaceFactory: WorkspaceFactory;
 }
+/**
+ * Workspace Application Service
+ *
+ * 提供应用层的 Workspace 服务
+ */
 export declare class WorkspaceAppService {
     private workspaceFactory;
     constructor(options: WorkspaceAppServiceOptions);
+    /**
+     * Load workspace from path
+     */
     loadWorkspace(path?: string): Promise<Workspace>;
+    /**
+     * Create new workspace
+     */
     createWorkspace(path: string, options?: Parameters<WorkspaceFactory['create']>[1]): Promise<Workspace>;
+    /**
+     * Save workspace
+     */
     saveWorkspace(workspace: Workspace): Promise<void>;
+    /**
+     * Find workspace root
+     */
     findWorkspaceRoot(startPath?: string): Promise<string | null>;
+    /**
+     * Create project in workspace
+     */
     createProject(workspace: Workspace, name: string, options?: Parameters<WorkspaceFactory['createProject']>[2]): Promise<Project>;
+    /**
+     * Create project from existing folder
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 创建项目并链接到源文件夹
+     */
     createProjectFromFolder(workspace: Workspace, name: string, sourceFolderPath: string, options?: Parameters<WorkspaceFactory['createProjectFromFolder']>[3]): Promise<Project>;
     createProjectFromFile(workspace: Workspace, name: string, sourceFilePath: string, options?: Parameters<WorkspaceFactory['createProjectFromFile']>[3]): Promise<Project>;
+    /**
+     * Delete project from workspace
+     */
     deleteProject(workspace: Workspace, projectIdOrName: string, options?: Parameters<WorkspaceFactory['deleteProject']>[2]): Promise<void>;
+    /**
+     * Load workspace and find project by name or path
+     * Common pattern used by many CLI commands
+     *
+     * 统一行为：
+     * 1. 如果传入 projectNameOrPath，先按项目名查找
+     * 2. 如果按名字找不到，尝试按路径查找（可能是绝对路径）
+     * 3. 如果没传入参数，使用当前目录查找
+     */
     loadWorkspaceAndProject(projectNameOrPath?: string, workspacePath?: string): Promise<{
         workspace: Workspace;
         project: Project;
     }>;
+    /**
+     * Create snapshot for project
+     */
     createSnapshot(project: Project, snapshotName?: string): Promise<import("@internal/domain/workspace").SnapshotMetadata>;
+    /**
+     * List snapshots for project
+     */
     listSnapshots(project: Project): Promise<import("@internal/domain/workspace").SnapshotMetadata[]>;
+    /**
+     * Restore snapshot
+     */
     restoreSnapshot(project: Project, snapshotId: string, outputDir?: string): Promise<void>;
+    /**
+     * Delete snapshot
+     */
     deleteSnapshot(project: Project, snapshotId: string): Promise<void>;
+    /**
+     * Get snapshot metadata
+     */
     getSnapshot(project: Project, snapshotId: string): Promise<import("@internal/domain/workspace").SnapshotMetadata>;
+    /**
+     * Load a single project by path
+     */
     loadProject(projectPath: string): Promise<Project>;
+    /**
+     * Save a single project
+     */
     saveProject(project: Project): Promise<void>;
+    /**
+     * Find project root from current directory
+     */
     findProjectRoot(startPath: string): Promise<string | null>;
+    /**
+     * Scan folder structure
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 用于在创建项目前预览文件夹结构
+     */
     scanFolderStructure(folderPath: string): Promise<import("@internal/domain/workspace").FolderStructure>;
+    /**
+     * Create IdentityStorageProvider for a workspace
+     *
+     * 跨域协调：
+     * - Identity Domain 定义需要什么存储能力 (IdentityStorageProvider)
+     * - Workspace Domain 提供实现
+     * - Application Layer 负责组装
+     */
     createIdentityStorage(workspace: Workspace): import("../domain/identity").IdentityStorageProvider;
+    /**
+     * 设置项目的 baseURL 路径结构
+     * 在 public/ 目录下创建对应的 symlink 结构
+     */
     setupProjectBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;
         symlinkCreated: boolean;
     }>;
+    /**
+     * 清理项目的 baseURL 路径结构
+     */
     cleanProjectBaseURLStructure(project: Project): Promise<void>;
+    /**
+     * 确保项目的 baseURL 路径结构正确
+     * 检查 baseURL 是否变化，如需要则重新创建
+     */
     ensureProjectBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;

package/dist/types/internal/domain/config/entity/config.d.ts

@@ -8,6 +8,10 @@ import { Language } from './language';
 import { Taxonomy } from './taxonomy';
 import { Dir } from "./dir";
 import { Markdown } from './markdown';
+/**
+ * Config entity that aggregates all configuration components
+ * Matches the golang version structure
+ */
 export declare class Config {
     private configSourceFs;
     private provider;
@@ -24,16 +28,52 @@ export declare class Config {
     getProvider(): Provider;
     theme(): string;
     getDir(): Dir;
+    /**
+     * Get Root entity
+     */
     getRoot(): Root;
+    /**
+     * Get Module entity
+     */
     getModule(): Module;
+    /**
+     * Get Service entity
+     */
     getService(): Service;
+    /**
+     * Get Social entity
+     */
     getSocial(): Social;
+    /**
+     * Get Language entity (optional)
+     */
     getLanguage(): Language;
+    /**
+     * Get Taxonomy entity (optional)
+     */
     getTaxonomy(): Taxonomy;
+    /**
+     * Get Markdown entity
+     */
     getMarkdown(): Markdown;
+    /**
+     * Set Language entity
+     */
     setLanguage(language: Language): void;
+    /**
+     * Set Taxonomy entity
+     */
     setTaxonomy(taxonomy: Taxonomy): void;
+    /**
+     * Set Markdown entity
+     */
     setMarkdown(markdown: Markdown): void;
+    /**
+     * Validate the configuration
+     */
     validate(): boolean;
 }
+/**
+ * Creates a new Config instance
+ */
 export declare function newConfig(configSourceFs: Fs, provider: Provider, root: Root, dir: Dir, module: Module, service: Service, social: Social, language: Language, taxonomy: Taxonomy, markdown: Markdown): Config;

package/dist/types/internal/domain/config/entity/language.d.ts

@@ -1,23 +1,74 @@
 import { LanguageConfig } from '../type';
+/**
+ * Language entity holds language configuration
+ */
 export declare class Language {
     private defaultLang;
     private configs;
     private indices;
     constructor(configs: Record<string, LanguageConfig>);
+    /**
+     * Calculate default language based on weight (smallest weight wins)
+     */
     private calculateDefaultLanguage;
+    /**
+     * Get all language configurations
+     */
     languages(): LanguageConfig[];
+    /**
+     * Get default language
+     */
     defaultLanguage(): string;
+    /**
+     * Check if a language is valid
+     */
     isLanguageValid(lang: string): boolean;
+    /**
+     * Get other language keys (excluding default)
+     */
     otherLanguageKeys(): string[];
+    /**
+     * Get relative directory for a language
+     */
     getRelDir(name: string, langKey: string): string;
+    /**
+     * Validate language configuration
+     */
     validate(): boolean;
+    /**
+     * Set language indices (ordered list)
+     */
     private setIndices;
+    /**
+     * Get language keys in order
+     */
     languageKeys(): string[];
+    /**
+     * Get language indexes
+     */
     languageIndexes(): number[];
+    /**
+     * Get language index by language code
+     */
     getLanguageIndex(lang: string): number;
+    /**
+     * Get language by index
+     */
     getLanguageByIndex(idx: number): string;
+    /**
+     * Get language name by language code
+     */
     getLanguageName(lang: string): string;
+    /**
+     * Get language configuration by language code
+     */
     getLanguageConfig(lang: string): LanguageConfig | undefined;
+    /**
+     * Get all language configurations
+     */
     getConfigs(): Record<string, LanguageConfig>;
 }
+/**
+ * Create a new Language instance from provider data
+ */
 export declare function newLanguage(data: any): Language;