@mdfriday/foundry 26.4.19 → 26.5.1

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

@@ -1,36 +1,142 @@
+/**
+ * Application Layer: Identity Management Service
+ *
+ * 职责：
+ * - 协调 Identity Domain 和其他 Domain 的交互
+ * - 提供应用级的 Identity 服务
+ * - 不包含业务逻辑（业务逻辑在 Domain 层）
+ */
 import { UserFactory } from '@internal/domain/identity/factory/user-factory';
 import { User, UserStatus } from '@internal/domain/identity/entity/user';
 import { ServerConfig } from '@internal/domain/identity/value-object/server-config';
 import { License } from '@internal/domain/identity/value-object/license';
 import { Device } from '@internal/domain/identity/value-object/device';
+/**
+ * IdentityAppService Options
+ */
 export interface IdentityAppServiceOptions {
     userFactory: UserFactory;
 }
+/**
+ * Identity Application Service
+ *
+ * 提供应用层的 Identity 服务
+ */
 export declare class IdentityAppService {
     private userFactory;
     private currentUser;
     private cachedServerConfig;
     constructor(options: IdentityAppServiceOptions);
+    /**
+     * 初始化服务（加载已保存的用户和服务器配置）
+     */
     initialize(): Promise<void>;
+    /**
+     * 用户登录
+     */
     login(email: string, password: string): Promise<User>;
+    /**
+     * 用户注册
+     */
     register(email: string, password: string): Promise<User>;
+    /**
+     * 用户登出
+     */
     logout(): Promise<void>;
+    /**
+     * 获取当前用户
+     */
     getCurrentUser(): User | null;
+    /**
+     * 检查是否已认证
+     */
     isAuthenticated(): boolean;
+    /**
+     * 获取认证令牌字符串
+     */
     getToken(): string | null;
+    /**
+     * 获取认证状态
+     */
+    /**
+     * 获取用户状态
+     *
+     * @returns 用户状态信息，包括认证、License 和 Sync 配置
+     */
     getStatus(): UserStatus;
+    /**
+     * 获取服务器配置
+     *
+     * 优先级：当前用户配置 > 缓存配置 > 默认配置
+     */
     getServerConfig(): ServerConfig;
+    /**
+     * 更新服务器配置
+     */
     updateServerConfig(updates: {
         apiUrl?: string;
         websiteUrl?: string;
     }): Promise<void>;
+    /**
+     * 申请试用 License（只申请，不激活）
+     *
+     * @param email - 用户邮箱
+     * @returns 试用 License 信息和凭证
+     */
     requestTrial(email: string): Promise<import("@internal/domain/identity/factory/user-factory").TrialLicenseResponse>;
+    /**
+     * 使用 License Key 登录
+     *
+     * License Key 会自动生成 email 和 password
+     *
+     * @param licenseKey - License Key (MDF-XXXX-XXXX-XXXX)
+     * @returns 登录成功的用户
+     */
     loginWithLicense(licenseKey: string): Promise<User>;
+    /**
+     * 激活 License
+     *
+     * @param licenseKey - License Key
+     * @param device - 设备信息（可选）
+     * @returns 激活后的用户
+     */
     activateLicense(licenseKey: string, device?: Device): Promise<User>;
+    /**
+     * 完整的试用流程：申请 → 登录 → 激活
+     *
+     * 简化操作：只需提供邮箱即可
+     *
+     * @param email - 用户邮箱
+     * @returns 已激活试用 License 的用户
+     */
+    /**
+     * 申请试用 License 并自动激活
+     *
+     * 流程：
+     * 1. 申请试用 License
+     * 2. 使用 License Key 登录
+     * 3. 激活 License
+     *
+     * @param email - 用户邮箱
+     * @returns 登录并激活后的 User
+     */
     requestAndActivateTrial(email: string): Promise<User>;
+    /**
+     * 获取当前用户的 License
+     */
     getLicense(): License | null;
+    /**
+     * 检查用户是否有有效的 License
+     */
     hasValidLicense(): boolean;
+    /**
+     * 检查是否是试用账户
+     */
     isTrialAccount(): boolean;
+    /**
+     * 获取 License 信息（用于显示）
+     * 从当前用户的 License 对象获取，不调用 API
+     */
     getLicenseDisplay(): {
         key: string;
         plan: string;
@@ -41,28 +147,95 @@ export declare class IdentityAppService {
         isTrial: boolean;
         features: import("@internal/domain/identity/value-object/license").LicenseFeatures;
     } | null;
+    /**
+     * 自动刷新当前用户的 Token（如果需要）
+     *
+     * 当用户使用 License 登录后，token 会在 30 天后过期
+     * 此方法检查 token 是否过期，如果是则自动使用 license 重新登录
+     *
+     * @returns 是否执行了刷新操作
+     */
     refreshTokenIfNeeded(): Promise<boolean>;
+    /**
+     * 执行需要认证的请求，自动处理 token 刷新
+     *
+     * 当请求返回 401 时，自动刷新 token 并重试
+     * 这是对 UserFactory.requestWithAutoRefresh 的应用层封装
+     *
+     * @param requestFn - 执行实际请求的函数，接收 token 字符串作为参数
+     * @returns 请求结果
+     *
+     * @example
+     * ```typescript
+     * const result = await identityService.requestWithAutoRefresh(async (token) => {
+     *   return httpClient.post('/api/some-endpoint', { data }, {
+     *     headers: { Authorization: `Bearer ${token}` }
+     *   });
+     * });
+     * ```
+     */
     requestWithAutoRefresh<T>(requestFn: (tokenValue: string) => Promise<T>): Promise<T>;
+    /**
+     * 获取 License 使用量信息
+     *
+     * @returns License 使用量信息
+     */
     getLicenseUsage(): Promise<import("@internal/domain/identity/factory/user-factory").LicenseUsageResponse | null>;
+    /**
+     * 获取 License 详细信息
+     *
+     * @param licenseKey - 可选的 License Key，如果不提供则从当前用户的 license 中获取
+     */
     getLicenseInfo(licenseKey?: string): Promise<any>;
+    /**
+     * 重置 License 使用量
+     */
     resetUsage(): Promise<{
         success: boolean;
         message?: string;
     }>;
+    /**
+     * 获取域名信息（包括子域名和自定义域名）
+     */
     getDomains(): Promise<import("@internal/domain/identity/factory/user-factory").DomainInfo | null>;
+    /**
+     * 检查子域名可用性
+     *
+     * @param subdomain - 要检查的子域名
+     */
     checkSubdomainAvailability(subdomain: string): Promise<import("@internal/domain/identity/factory/user-factory").SubdomainCheckResponse | null>;
+    /**
+     * 更新子域名
+     *
+     * @param newSubdomain - 新的子域名
+     */
     updateSubdomain(newSubdomain: string): Promise<import("@internal/domain/identity/factory/user-factory").SubdomainUpdateResponse | null>;
+    /**
+     * 检查自定义域名 DNS 配置
+     *
+     * @param domain - 要检查的域名
+     */
     checkCustomDomain(domain: string): Promise<{
         dns_valid: boolean;
         ready: boolean;
         message: string;
         resolved_ips?: string[];
     } | null>;
+    /**
+     * 添加自定义域名
+     *
+     * @param domain - 要添加的域名
+     */
     addCustomDomain(domain: string): Promise<{
         domain: string;
         status: string;
         message: string;
     } | null>;
+    /**
+     * 检查自定义域名 HTTPS 证书状态
+     *
+     * @param domain - 要检查的域名
+     */
     checkCustomDomainHttpsStatus(domain: string): Promise<{
         status: string;
         tls_ready: boolean;

package/dist/types/internal/application/incremental-build-coordinator.d.ts

@@ -29,19 +29,47 @@ export declare class IncrementalBuildCoordinator {
     private initialized;
     private domainInstances?;
     constructor(config: IncrementalBuildConfig);
+    /**
+     * 初始化：执行首次完整构建并保存 domain 实例
+     */
     initialize(): Promise<void>;
+    /**
+     * 执行完整构建并缓存 domain 实例
+     */
     private performFullBuildAndCacheDomains;
     startWatching(): Promise<void>;
     stopWatching(): Promise<void>;
+    /**
+     * 处理文件变更事件，触发增量构建
+     * 阶段3-5：完整的增量构建流程
+     */
     private handleFileChanges;
     needFullRebuild(events: FileChangeEvent[]): boolean;
+    /**
+     * 执行增量构建（阶段3-5的核心实现）
+     */
     private performIncrementalBuild;
     getEventsFilePaths(events: FileChangeEvent[]): string[];
+    /**
+     * 第2阶段的临时实现：执行完整重建并通知 Live Reload
+     */
     private performFullRebuild;
+    /**
+     * 获取当前是否已初始化
+     */
     isInitialized(): boolean;
+    /**
+     * 获取是否正在构建
+     */
     isBuildInProgress(): boolean;
+    /**
+     * 获取配置信息
+     */
     getConfig(): IncrementalBuildConfig;
     getServerUrl(): string;
+    /**
+     * 获取 Live Reload 服务器状态
+     */
     getLiveReloadStatus(): {
         running: boolean;
         url?: string;

package/dist/types/internal/application/incremental-ssg.d.ts

@@ -1,3 +1,7 @@
 import { IncrementalBuildCoordinator, IncrementalBuildConfig } from './incremental-build-coordinator';
 export { IncrementalBuildConfig, IncrementalBuildCoordinator };
+/**
+ * 增量构建的主入口函数
+ * 第1阶段：实现基础的初始化和完整构建
+ */
 export declare function startIncrementalBuild(config: IncrementalBuildConfig): Promise<IncrementalBuildCoordinator>;

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

@@ -1,4 +1,5 @@
-export { WorkspaceAppService } from './workspace';
-export { PublishAppService } from './publish';
-export { IdentityAppService } from './identity';
-export { createWorkspaceFactory, createWorkspaceAppService, createIdentityService, createPublishAppService, } from './container';
+/**
+ * Application Layer Exports
+ */
+export * from './wiki-service';
+export * from './wiki-service-config';

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

@@ -10,18 +10,55 @@ export type PublishProgressCallback = (progress: {
     filesTotal?: number;
     bytesTransferred?: number;
 }) => void;
+/**
+ * Publish Application Service
+ *
+ * 协调发布操作，通过 PublisherFactory 创建聚合根
+ *
+ * 注意：配置的查找和合并由 Interface 层（CLI/Obsidian）负责
+ *      Application 层只负责编排业务逻辑
+ */
 export declare class PublishAppService {
     private publisherFactory;
     private workspaceService;
     constructor(publisherFactory: PublisherFactory, workspaceService: WorkspaceAppService);
+    /**
+     * Publish project to specified platform
+     *
+     * @param project - 项目实例
+     * @param config - 已合并的发布配置（由调用方准备）
+     * @param options - 发布选项
+     * @param onProgress - 进度回调
+     */
     publish(project: Project, config: AnyPublishConfig, options?: {
         force?: boolean;
         incremental?: boolean;
     }, onProgress?: PublishProgressCallback): Promise<any>;
+    /**
+     * Test connection
+     *
+     * @param project - 项目实例
+     * @param config - 已合并的发布配置（由调用方准备）
+     */
     testConnection(project: Project, config: AnyPublishConfig): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * 准备最终的发布配置
+     *
+     * 配置查找优先级（两级）：
+     * 1. 项目配置 (project.config.publish)
+     * 2. 全局配置 (workspace global config)
+     *
+     * @param workspace - Workspace 实例
+     * @param project - Project 实例
+     * @param method - 发布方法
+     * @returns 最终的发布配置
+     */
     prepareFinalConfig(workspace: Workspace, project: Project, method: 'ftp' | 'netlify' | 'mdfriday'): Promise<AnyPublishConfig>;
+    /**
+     * Get method-specific config from WorkspacePublishConfig
+     */
     private getMethodConfig;
 }

package/dist/types/internal/application/ssg-parallel.d.ts

@@ -1,6 +1,9 @@
 import { SSGProgressCallback } from './ssg';
 import { MarkdownRenderer } from "@internal/domain/markdown";
 import { HttpClient } from "@internal/domain/module";
+/**
+ * 并行 SSG 统计信息
+ */
 export interface ParallelSSGStats {
     totalPages: number;
     totalBatches: number;
@@ -10,4 +13,7 @@ export interface ParallelSSGStats {
     parallelSpeedup: number;
     pagesPerSecond: number;
 }
+/**
+ * 并行处理 SSG（主入口）
+ */
 export declare function processSSGParallel(projDir: string, modulesDir: string, markdown?: MarkdownRenderer, onProgress?: SSGProgressCallback, httpClient?: HttpClient): Promise<ParallelSSGStats>;

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

@@ -6,6 +6,9 @@ import { Site } from "@internal/domain/site/entity/site";
 import { Resources } from "@internal/domain/resources/entity/resources";
 import { MarkdownRenderer } from "@internal/domain/markdown";
 import { PageTask } from "@pkg/page-filter";
+/**
+ * Domain 实例集合，用于增量构建时复用
+ */
 export interface DomainInstances {
     site: Site;
     content: Content;
@@ -14,8 +17,14 @@ export interface DomainInstances {
     modules: Modules;
     resources: Resources;
 }
+/**
+ * Generate static site
+ */
 export declare function generateStaticSite(projDir: string, modulesDir: string, markdown?: MarkdownRenderer): Promise<void>;
 export declare function processSSG(projDir: string, modulesDir: string, markdown?: MarkdownRenderer): Promise<void>;
+/**
+ * Progress callback interface for SSG processing
+ */
 export interface SSGProgressCallback {
     (progress: {
         stage: 'config' | 'modules' | 'filesystem' | 'content' | 'site' | 'template' | 'pages' | 'build' | 'completion';
@@ -31,7 +40,13 @@ export interface SSGProgressCallback {
         };
     }): void;
 }
+/**
+ * Generate static site with progress callbacks
+ */
 export declare function generateStaticSiteWithProgress(projDir: string, modulesDir: string, markdown?: MarkdownRenderer, onProgress?: SSGProgressCallback, httpClient?: HttpClient): Promise<DomainInstances>;
+/**
+ * Process SSG with progress callbacks
+ */
 export declare function processSSGWithProgress(projDir: string, modulesDir: string, markdown?: MarkdownRenderer, onProgress?: SSGProgressCallback, httpClient?: HttpClient): Promise<void>;
 export declare function serveSSG(projDir: string, modulesDir: string, markdown?: MarkdownRenderer, onProgress?: SSGProgressCallback, httpClient?: HttpClient): Promise<DomainInstances>;
 export declare function collectAllPageTasks(projDir: string, modulesDir: string, markdown?: MarkdownRenderer, onProgress?: SSGProgressCallback, httpClient?: HttpClient): Promise<PageTask[]>;

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

@@ -0,0 +1,65 @@
+/**
+ * WikiService 配置
+ *
+ * 用户在创建 WikiService 时一次性传入所有配置
+ * 避免在每次方法调用时重复传入相同参数
+ */
+import { ILLMProvider, IEmbeddingProvider, IFileSystem, IPathService, ICryptoService, IConversationRepository } from '../domain/wiki/repository';
+/**
+ * LLM 配置
+ */
+export interface WikiServiceLLMConfig {
+    provider: ILLMProvider;
+    defaultModel: string;
+    defaultTemperature?: number;
+    defaultMaxTokens?: number;
+}
+/**
+ * Embedding 配置（可选）
+ */
+export interface WikiServiceEmbeddingConfig {
+    provider: IEmbeddingProvider;
+    defaultModel: string;
+    cacheEnabled?: boolean;
+}
+/**
+ * Wiki Domain 行为配置
+ */
+export interface WikiServiceDomainConfig {
+    outputLanguage?: string;
+    ingestTemperature?: number;
+    queryTemperature?: number;
+    maxQueryResults?: number;
+}
+/**
+ * 基础设施配置
+ */
+export interface WikiServiceInfrastructureConfig {
+    fileSystem: IFileSystem;
+    pathService: IPathService;
+    cryptoService: ICryptoService;
+    conversationRepo: IConversationRepository;
+}
+/**
+ * 路径配置
+ */
+export interface WikiServicePathsConfig {
+    kbPath: string;
+    embeddingsPath: string;
+    wikiDir: string;
+    conversationsDir: string;
+}
+/**
+ * WikiService 完整配置
+ */
+export interface WikiServiceConfig {
+    llm: WikiServiceLLMConfig;
+    embedding?: WikiServiceEmbeddingConfig;
+    wiki?: WikiServiceDomainConfig;
+    infrastructure: WikiServiceInfrastructureConfig;
+    paths: WikiServicePathsConfig;
+}
+/**
+ * 默认配置值
+ */
+export declare const DEFAULT_WIKI_SERVICE_CONFIG: Partial<WikiServiceDomainConfig>;

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

@@ -0,0 +1,199 @@
+/**
+ * Wiki Service - Application Layer
+ *
+ * 重构后的应用服务，遵循 DDD 架构：
+ * - 持有 WikiFactory 和统一配置
+ * - 通过 Factory 创建和加载 KB
+ * - 调用 KB 聚合根的业务方法
+ * - 协调依赖，不包含业务逻辑
+ * - 配置在创建时一次性传入，避免重复
+ */
+import { KnowledgeBase, WikiFactory, ConversationMetadata } from '../domain/wiki';
+import { WikiServiceConfig } from './wiki-service-config';
+/**
+ * Ingest 可选配置（用于覆盖默认值）
+ */
+export interface IngestOptions {
+    temperature?: number;
+}
+/**
+ * Query 可选配置（用于覆盖默认值）
+ */
+export interface QueryOptions {
+    temperature?: number;
+    maxResults?: number;
+}
+/**
+ * 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 方法
+     */
+    queryStream(question: string, options?: QueryOptions): AsyncGenerator<string, void, unknown>;
+    /**
+     * 生成所有 Wiki 页面
+     *
+     * 协调聚合根的 generateWikiPages 方法
+     */
+    generateAllPages(): Promise<void>;
+    /**
+     * Lint 检查
+     *
+     * 调用聚合根的 lint 方法
+     */
+    lint(): Promise<LintIssue[]>;
+    /**
+     * 为当前 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[]>;
+}