@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/template/vo/registry.d.ts

@@ -1,50 +1,210 @@
+/**
+ * Template functions registry
+ * Centralized management of template functions following DDD principles
+ * TypeScript equivalent of Go's valueobject/nsreg.go
+ */
 import { CustomizedFunctions, TemplateFuncMap } from '../type';
 import { TemplateEngine } from '../entity/template';
+/**
+ * Template functions registry interface
+ * Domain service for managing template function registration
+ */
 export interface TemplateRegistry {
     registerCoreFunctions(funcMap: TemplateFuncMap): void;
     registerExtendedFunctions(funcMap: TemplateFuncMap, services: CustomizedFunctions): void;
     registerAllFunctions(funcMap: TemplateFuncMap, services?: CustomizedFunctions): void;
 }
+/**
+ * Template functions registry implementation
+ * Following DDD principles - encapsulates template function management logic
+ */
 export declare class DefaultTemplateRegistry implements TemplateRegistry {
+    /**
+     * Register core template functions that don't require external services
+     * Equivalent to Go's RegisterNamespaces()
+     */
     registerCoreFunctions(funcMap: TemplateFuncMap): void;
+    /**
+     * Register cryptographic hash functions
+     * Equivalent to Go's crypto packages
+     */
     private registerCryptoFunctions;
+    /**
+     * Register extended template functions that require external services
+     * Equivalent to Go's RegisterExtendedNamespaces()
+     */
     registerExtendedFunctions(funcMap: TemplateFuncMap, services: CustomizedFunctions): void;
+    /**
+     * Register all available functions with services
+     * This is the main entry point for function registration
+     */
     registerAllFunctions(funcMap: TemplateFuncMap, services?: CustomizedFunctions): void;
+    /**
+     * Register functions that depend on TemplateEngine
+     * These functions are registered with placeholder implementations initially
+     */
     private registerEngineDependentFunctions;
+    /**
+     * Register URL template functions using URLService
+     * Equivalent to Go's registerUrls()
+     */
     private registerURLFunctions;
+    /**
+     * Register site template functions using SiteService
+     * Equivalent to Go's registerSite()
+     */
     private registerSiteFunctions;
     private registerResourcesFunctions;
+    /**
+     * Register Hugo template functions using HugoInfoService
+     * Equivalent to Go's registerHugo()
+     */
     private registerHugoFunctions;
+    /**
+     * Register language template functions using LanguageService
+     * Equivalent to Go's registerLang()
+     */
     private registerLanguageFunctions;
+    /**
+     * Register string manipulation functions
+     * Equivalent to Go's registerStrings()
+     */
     private registerStringFunctions;
+    /**
+     * HTML escape utility function
+     */
     private escapeHTML;
+    /**
+     * Truncate plain text, breaking at word boundaries when possible
+     */
     private truncateText;
+    /**
+     * Truncate HTML text while preserving tag structure
+     */
     private truncateHTML;
+    /**
+     * Register math functions
+     * Equivalent to Go's registerMath()
+     */
     private registerMathFunctions;
+    /**
+     * Register time/date functions
+     * Equivalent to Go's registerTime()
+     */
     private registerTimeFunctions;
+    /**
+     * Register collection functions
+     * Equivalent to Go's registerCollections()
+     */
     private registerCollectionFunctions;
+    /**
+     * Core indexing implementation following Go's doIndex logic
+     * Supports nested indexing of arrays, objects, and maps
+     */
     private doIndex;
+    /**
+     * Index into an array or slice
+     */
     private indexArray;
+    /**
+     * Index into a string (treating it like a character array)
+     */
     private indexString;
+    /**
+     * Index into an object/map (including TaxonomyList)
+     */
     private indexObject;
+    /**
+     * Convert value to integer, similar to Go's index conversion
+     */
     private toInteger;
+    /**
+     * Check condition between two values using the specified operator
+     * Following golang's checkCondition logic
+     */
     private checkCondition;
+    /**
+     * Normalize values for comparison
+     */
     private normalizeForComparison;
+    /**
+     * Register safe functions
+     * Equivalent to Go's registerSafe()
+     */
     private registerSafeFunctions;
+    /**
+     * Register format functions (fmt namespace)
+     * Equivalent to Go's registerFmt()
+     */
     private registerFmtFunctions;
+    /**
+     * Register reflect functions
+     * Equivalent to Go's registerReflect()
+     */
     private registerReflectFunctions;
+    /**
+     * Register path manipulation functions
+     * Equivalent to Go's path package functions
+     */
     private registerPathFunctions;
+    /**
+     * Register transform functions (unmarshal, etc.)
+     * Equivalent to Go's transform package functions
+     */
     private registerTransformFunctions;
+    /**
+     * Strip HTML tags from a string
+     * Equivalent to Go's helpers.StripHTML function
+     * Preserves line breaks from block elements and normalizes whitespace
+     */
     private stripHTML;
+    /**
+     * Unmarshal content from string based on format
+     * Supports JSON, YAML, TOML, CSV formats
+     */
     private unmarshalContent;
+    /**
+     * Detect format from content
+     */
     private detectFormat;
+    /**
+     * Parse YAML content (basic implementation)
+     * For a full implementation, you'd want to use a proper YAML library
+     */
     private parseYAML;
+    /**
+     * Parse TOML content (basic implementation)
+     * For a full implementation, you'd want to use a proper TOML library
+     */
     private parseTOML;
+    /**
+     * Parse CSV content (basic implementation)
+     */
     private parseCSV;
+    /**
+     * Parse a single CSV line, handling quoted values
+     */
     private parseCSVLine;
+    /**
+     * Get nested value from object using dot notation path
+     * Following golang's path resolution logic
+     */
     private getNestedValue;
 }
+/**
+ * Create default template registry
+ */
 export declare function newTemplateRegistry(): TemplateRegistry;
+/**
+ * Convenience function to create and register core functions only
+ */
 export declare function createCoreFuncMap(): TemplateFuncMap;
+/**
+ * Convenience function to create and register all functions with services
+ */
 export declare function createStandardFuncMap(services: CustomizedFunctions): TemplateFuncMap;
+/**
+ * Update all engine-dependent functions with the template engine instance
+ * This should be called after the template engine is created
+ */
 export declare function updateEngineDependentFunctions(engine: TemplateEngine): void;

package/dist/types/internal/domain/wiki/entity/concept.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Concept Entity
+ *
+ * 代表知识库中的一个概念
+ */
+import { EntityId } from '../value-object/entity-id';
+export declare class Concept {
+    private readonly _id;
+    private _name;
+    private _definition;
+    private _related;
+    private _sources;
+    private _aliases;
+    constructor(id: EntityId, name: string, definition: string, related?: string[], sources?: string[], aliases?: string[]);
+    get id(): EntityId;
+    get name(): string;
+    get definition(): string;
+    get related(): ReadonlyArray<string>;
+    get sources(): ReadonlyArray<string>;
+    get aliases(): ReadonlySet<string>;
+    /**
+     * 合并新的定义、关联和别名（去重）
+     */
+    merge(newDefinition: string, newRelated: string[], newAliases: string[], source: string): void;
+    /**
+     * 质量评分（用于检索排序）
+     */
+    qualityScore(): number;
+    toJSON(): any;
+    static fromJSON(data: any): Concept;
+}

package/dist/types/internal/domain/wiki/entity/connection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Connection Entity
+ *
+ * 代表知识库中两个实体/概念之间的关系
+ */
+import { ConnectionType } from '../value-object/connection-type';
+export declare class Connection {
+    private _from;
+    private _to;
+    private _type;
+    private _description;
+    private _sources;
+    constructor(from: string, to: string, type: ConnectionType, description?: string, sources?: string[]);
+    get from(): string;
+    get to(): string;
+    get type(): ConnectionType;
+    get description(): string;
+    get sources(): ReadonlyArray<string>;
+    /**
+     * 添加来源
+     */
+    addSource(source: string): void;
+    /**
+     * 更新描述（如果新描述更长）
+     */
+    updateDescription(newDescription: string): void;
+    toJSON(): any;
+    static fromJSON(data: any): Connection;
+}

package/dist/types/internal/domain/wiki/entity/conversation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Conversation Entity
+ *
+ * 代表一次对话记录，包含查询、答案和元数据
+ * 职责：
+ * - 持有对话数据
+ * - 提供格式化方法（Markdown）
+ * - 生成文件名
+ * - 不依赖任何 I/O 操作
+ */
+export interface ConversationMetadata {
+    query: string;
+    timestamp: Date;
+    sources: string[];
+    retrieval: {
+        entityCount: number;
+        conceptCount: number;
+        totalResults: number;
+    };
+}
+export declare class Conversation {
+    private readonly id;
+    private readonly query;
+    private readonly answer;
+    private readonly metadata;
+    constructor(id: string, query: string, answer: string, metadata: ConversationMetadata);
+    /**
+     * 创建新对话
+     */
+    static create(query: string, answer: string, metadata: Omit<ConversationMetadata, 'query' | 'timestamp'>): Conversation;
+    /**
+     * 生成对话 ID（作为文件名）
+     * 格式: YYYY-MM-DD-query-slug
+     */
+    private static generateId;
+    /**
+     * 格式化为 Markdown 文档
+     *
+     * 结构：
+     * - YAML frontmatter（元数据）
+     * - 主体：查询 + 答案
+     * - 引用：源文档列表
+     */
+    formatAsMarkdown(): string;
+    /**
+     * 获取文件名
+     * 格式: YYYY-MM-DD-query-slug.md
+     */
+    getFilename(): string;
+    getId(): string;
+    getQuery(): string;
+    getAnswer(): string;
+    getMetadata(): ConversationMetadata;
+    getTimestamp(): Date;
+    getSources(): string[];
+    private buildFrontmatter;
+    private buildBody;
+    private buildFooter;
+    private static formatDate;
+    private formatDateTime;
+    private static slugify;
+    private escapeYaml;
+    toJSON(): any;
+    static fromJSON(json: any): Conversation;
+}

package/dist/types/internal/domain/wiki/entity/embedding-index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * EmbeddingIndex Entity
+ *
+ * 领域实体：管理 Embedding 向量索引的生命周期
+ *
+ * 职责：
+ * - 存储实体和概念的向量表示
+ * - 提供向量检索能力
+ * - 管理自己的持久化（缓存）
+ */
+export declare class EmbeddingIndex {
+    private index;
+    private readonly cachePath;
+    private isDirty;
+    constructor(cachePath: string, initialData?: Map<string, number[]>);
+    /**
+     * 添加向量
+     */
+    set(key: string, embedding: number[]): void;
+    /**
+     * 获取向量
+     */
+    get(key: string): number[] | undefined;
+    /**
+     * 检索最相似的项
+     */
+    findSimilar(queryEmbedding: number[], topK: number): Array<{
+        key: string;
+        similarity: number;
+    }>;
+    /**
+     * 获取只读索引（用于传递给查询）
+     */
+    getReadOnlyIndex(): ReadonlyMap<string, number[]>;
+    /**
+     * 获取所有键
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * 检查是否包含某个键
+     */
+    has(key: string): boolean;
+    /**
+     * 序列化
+     */
+    toJSON(): Record<string, number[]>;
+    /**
+     * 从 JSON 反序列化
+     */
+    static fromJSON(cachePath: string, data: Record<string, number[]>): EmbeddingIndex;
+    /**
+     * 余弦相似度计算
+     */
+    private cosineSimilarity;
+    getCachePath(): string;
+    isDirtyState(): boolean;
+    markClean(): void;
+    size(): number;
+    clear(): void;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Entity Aggregate Root
+ *
+ * 代表知识库中的一个实体（人、组织、工具、书籍等）
+ */
+import { EntityId } from '../value-object/entity-id';
+import { EntityType } from '../value-object/entity-type';
+export declare class Entity {
+    private readonly _id;
+    private _name;
+    private _type;
+    private _aliases;
+    private _facts;
+    private _sources;
+    constructor(id: EntityId, name: string, type: EntityType, aliases?: string[], facts?: string[], sources?: string[]);
+    get id(): EntityId;
+    get name(): string;
+    get type(): EntityType;
+    get aliases(): ReadonlyArray<string>;
+    get facts(): ReadonlyArray<string>;
+    get sources(): ReadonlyArray<string>;
+    /**
+     * 合并新的事实和别名（去重）
+     */
+    merge(newAliases: string[], newFacts: string[], source: string): void;
+    /**
+     * 质量评分（用于检索排序）
+     */
+    qualityScore(): number;
+    toJSON(): any;
+    static fromJSON(data: any): Entity;
+}