@mdfriday/foundry 26.4.19 → 26.5.1

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

@@ -0,0 +1,49 @@
+/**
+ * Wiki Page Repository Interface
+ *
+ * 定义 Wiki 页面持久化的抽象接口
+ */
+export interface IWikiPageRepository {
+    /**
+     * 写入单个页面
+     * @param relativePath 相对于 wiki 根目录的路径（如 'entities/typescript.md'）
+     * @param content 页面内容
+     */
+    writePage(relativePath: string, content: string): Promise<void>;
+    /**
+     * 删除页面
+     * @param relativePath 相对路径
+     */
+    deletePage(relativePath: string): Promise<void>;
+    /**
+     * 批量写入页面
+     * @param pages Map<相对路径, 内容>
+     */
+    writePages(pages: Map<string, string>): Promise<void>;
+    /**
+     * 列出目录下的所有页面
+     * @param directory 相对目录路径（如 'entities/'）
+     * @returns 页面路径列表
+     */
+    listPages(directory: string): Promise<string[]>;
+    /**
+     * 追加日志条目
+     * @param entry 日志内容
+     */
+    appendToLog(entry: string): Promise<void>;
+    /**
+     * 更新索引页面
+     * @param content 索引内容
+     */
+    updateIndex(content: string): Promise<void>;
+    /**
+     * 更新词汇表
+     * @param content 词汇表内容
+     */
+    updateGlossary(content: string): Promise<void>;
+    /**
+     * 检查页面是否存在
+     * @param relativePath 相对路径
+     */
+    exists(relativePath: string): Promise<boolean>;
+}

package/dist/types/internal/domain/wiki/value-object/connection-type.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ConnectionType Value Object
+ *
+ * 关系类型枚举
+ */
+export type ConnectionTypeValue = 'influences' | 'uses' | 'critiques' | 'extends' | 'part-of' | 'created-by' | 'related-to' | 'applies-to' | 'contrasts-with';
+export declare class ConnectionType {
+    private static readonly VALID_TYPES;
+    private readonly _value;
+    private constructor();
+    get value(): ConnectionTypeValue;
+    static fromString(type: string): ConnectionType;
+    equals(other: ConnectionType): boolean;
+    toString(): string;
+    static readonly INFLUENCES: ConnectionType;
+    static readonly USES: ConnectionType;
+    static readonly CRITIQUES: ConnectionType;
+    static readonly EXTENDS: ConnectionType;
+    static readonly PART_OF: ConnectionType;
+    static readonly CREATED_BY: ConnectionType;
+    static readonly RELATED_TO: ConnectionType;
+    static readonly APPLIES_TO: ConnectionType;
+    static readonly CONTRASTS_WITH: ConnectionType;
+}

package/dist/types/internal/domain/wiki/value-object/content-annotator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Content Annotator
+ *
+ * 负责在原文中标记提取出的 entities 和 concepts，将其转换为 wikilink
+ *
+ * Phase 1: 基础实现 - 简单文本替换，全词匹配
+ * Phase 2: 优化匹配 - 处理别名，按长度排序，处理中英文差异
+ * Phase 3: 高级功能 - 只标记首次出现，上下文感知，不同类型使用不同标记
+ */
+import { Entity, Concept } from '../entity/knowledge-base';
+interface AnnotationOptions {
+    markFirstOccurrenceOnly?: boolean;
+    contextAware?: boolean;
+    differentMarkers?: boolean;
+}
+export declare class ContentAnnotator {
+    private options;
+    constructor(options?: AnnotationOptions);
+    /**
+     * 标记内容中的 entities 和 concepts
+     *
+     * @param content 原文内容
+     * @param entities 提取的实体列表
+     * @param concepts 提取的概念列表
+     * @returns 标记后的内容
+     */
+    annotate(content: string, entities: Entity[], concepts: Concept[]): string;
+    /**
+     * Phase 1: 收集所有待标记的词条（包含别名）
+     */
+    private collectTerms;
+    /**
+     * Phase 2 & 3: 在内容中标记词条
+     */
+    private markTerms;
+    /**
+     * Phase 3: 提取需要跳过的内容范围（标题、代码块、已有链接等）
+     */
+    private extractSkipRanges;
+    /**
+     * Phase 3: 检查位置是否在跳过范围内
+     */
+    private isInSkipRange;
+    /**
+     * Phase 2: 标记单个词条（支持别名）
+     * Phase 3: 支持首次标记、上下文感知、不同标记
+     *
+     * @param content 内容
+     * @param termText 要标记的词条文本（可能是主名称或别名）
+     * @param linkTarget 链接到的目标（主名称）
+     * @param termType 词条类型
+     * @param skipRanges 需要跳过的范围
+     * @param firstOccurrenceMarked 已标记首次出现的词条集合
+     */
+    private markSingleTerm;
+    /**
+     * 转义正则表达式特殊字符
+     */
+    private escapeRegex;
+}
+export {};

package/dist/types/internal/domain/wiki/value-object/entity-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * EntityId Value Object
+ *
+ * 负责将名称标准化为唯一 ID
+ * 例如: "Alan Watts" -> "alan-watts"
+ */
+export declare class EntityId {
+    private readonly _value;
+    private constructor();
+    get value(): string;
+    /**
+     * 从名称创建标准化 ID
+     */
+    static create(name: string): EntityId;
+    equals(other: EntityId): boolean;
+    toString(): string;
+}

package/dist/types/internal/domain/wiki/value-object/entity-type.d.ts

@@ -0,0 +1,24 @@
+/**
+ * EntityType Value Object
+ *
+ * 实体类型枚举
+ */
+export type EntityTypeValue = 'person' | 'org' | 'tool' | 'project' | 'book' | 'article' | 'place' | 'event' | 'other';
+export declare class EntityType {
+    private static readonly VALID_TYPES;
+    private readonly _value;
+    private constructor();
+    get value(): EntityTypeValue;
+    static fromString(type: string): EntityType;
+    equals(other: EntityType): boolean;
+    toString(): string;
+    static readonly PERSON: EntityType;
+    static readonly ORG: EntityType;
+    static readonly TOOL: EntityType;
+    static readonly PROJECT: EntityType;
+    static readonly BOOK: EntityType;
+    static readonly ARTICLE: EntityType;
+    static readonly PLACE: EntityType;
+    static readonly EVENT: EntityType;
+    static readonly OTHER: EntityType;
+}

package/dist/types/internal/domain/wiki/value-object/extraction-parser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Robust JSON Parser for LLM Extraction Results
+ *
+ * 处理各种 LLM 输出格式的边界情况
+ */
+import { ExtractionResult } from './extraction-result';
+export interface ParseOptions {
+    verbose?: boolean;
+}
+/**
+ * 健壮的 JSON 解析器
+ *
+ * 处理：
+ * 1. Markdown 代码块 (```json ... ```)
+ * 2. Reasoning 前缀
+ * 3. 不完整的 JSON
+ * 4. 多余的文本
+ */
+export declare function parseExtractionResult(raw: string, options?: ParseOptions): ExtractionResult | null;
+/**
+ * 尝试修复不完整的 JSON
+ *
+ * 常见问题：
+ * - 缺少结尾的 ]}
+ * - 截断的字符串
+ */
+export declare function tryFixIncompleteJSON(jsonStr: string): string | null;

package/dist/types/internal/domain/wiki/value-object/extraction-result.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ExtractionResult Value Object
+ *
+ * 封装 LLM 提取的结果
+ */
+export interface ExtractedEntity {
+    name: string;
+    type: string;
+    aliases?: string[];
+    facts?: string[];
+}
+export interface ExtractedConcept {
+    name: string;
+    definition?: string;
+    related?: string[];
+    aliases?: string[];
+}
+export interface ExtractedConnection {
+    from: string;
+    to: string;
+    type: string;
+    description?: string;
+}
+export declare class ExtractionResult {
+    readonly sourceSummary: string;
+    readonly entities: ExtractedEntity[];
+    readonly concepts: ExtractedConcept[];
+    readonly connections: ExtractedConnection[];
+    constructor(sourceSummary: string, entities: ExtractedEntity[], concepts: ExtractedConcept[], connections: ExtractedConnection[]);
+    static fromJSON(data: any): ExtractionResult;
+    toJSON(): any;
+}

package/dist/types/internal/domain/wiki/value-object/retrieval.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Retrieval Value Object
+ *
+ * 封装所有检索相关的算法和方法
+ * - 查询词提取
+ * - 关键词排序
+ * - 路径排序
+ * - Embedding 排序
+ * - RRF 融合
+ * - 质量加权
+ * - 余弦相似度
+ */
+import type { KnowledgeBase } from '../entity/knowledge-base';
+import type { EmbeddingIndex } from '../entity/embedding-index';
+import type { Entity } from '../entity/entity';
+import type { Concept } from '../entity/concept';
+import type { Connection } from '../entity/connection';
+import type { SourceRecord } from './source-record';
+import type { IEmbeddingProvider } from '../../../infrastructure/embedding';
+/**
+ * Embedding 缓存项
+ */
+export interface EmbeddingCacheEntry {
+    sourceText: string;
+    vector: number[];
+}
+/**
+ * Embedding 缓存
+ */
+export interface EmbeddingCache {
+    entries: Record<string, EmbeddingCacheEntry>;
+}
+/**
+ * 索引构建进度
+ */
+export interface EmbeddingIndexProgress {
+    current: number;
+    total: number;
+    phase: 'entities' | 'concepts';
+}
+/**
+ * 索引构建参数
+ */
+export interface BuildEmbeddingIndexArgs {
+    kb: KnowledgeBase;
+    provider: IEmbeddingProvider;
+    model: string;
+    cache: EmbeddingCache;
+    signal?: AbortSignal;
+    onProgress?: (progress: EmbeddingIndexProgress) => void;
+}
+/**
+ * 排序项
+ */
+export interface RankedItem {
+    id: string;
+    score: number;
+}
+/**
+ * 查询类型
+ */
+export type QueryType = 'entity_lookup' | 'list_category' | 'relational' | 'conceptual';
+/**
+ * 检索结果包
+ */
+export interface RetrievedBundle {
+    question: string;
+    queryType: QueryType;
+    entities: Entity[];
+    concepts: Concept[];
+    connections: Connection[];
+    sources: SourceRecord[];
+}
+/**
+ * 检索选项
+ */
+export interface RetrieveOptions {
+    maxEntities?: number;
+    maxConcepts?: number;
+    folders?: string[];
+    embeddingIndex?: ReadonlyMap<string, number[]>;
+    queryEmbedding?: number[] | null;
+}
+/**
+ * Retrieval Value Object
+ *
+ * 提供所有检索相关的功能
+ */
+export declare class Retrieval {
+    /**
+     * 提取查询词
+     *
+     * 简单的分词逻辑:
+     * - 转小写
+     * - 按空格分割
+     * - 过滤长度 < 3 的词
+     *
+     * 未来改进:
+     * - 停用词过滤
+     * - 词干提取
+     * - 中文分词
+     */
+    static extractQueryTerms(question: string): string[];
+    /**
+     * 关键词排序
+     *
+     * 规则:
+     * - 名称匹配: +3 分
+     * - 别名匹配: +3 分
+     * - 事实匹配: +1 分
+     * - 双词组合: +6 分 (如果查询中的连续两个词同时出现在名称中)
+     *
+     * 打破平局: 按 richness (facts + sources 数量) 排序
+     */
+    static rankByKeyword(kb: KnowledgeBase, terms: string[]): RankedItem[];
+    /**
+     * 路径排序
+     *
+     * 规则:
+     * - 如果 entity/concept 的 source 路径包含查询词，+1 分
+     *
+     * 用途:
+     * - 当用户查询包含文件夹或文件名时，优先返回该路径的内容
+     * - 例如: "tools in backend/" → 优先返回 backend 文件夹中的内容
+     */
+    static rankByPath(kb: KnowledgeBase, terms: string[]): RankedItem[];
+    /**
+     * 语义向量排序
+     *
+     * 规则:
+     * - 计算查询向量与每个 entity/concept 向量的余弦相似度
+     * - 排序并返回 Top-N
+     *
+     * @param embeddingIndex 向量索引
+     * @param queryEmbedding 查询向量
+     * @returns 排序后的结果 (Top 50)
+     */
+    static rankByEmbedding(embeddingIndex: ReadonlyMap<string, number[]> | EmbeddingIndex, queryEmbedding: readonly number[]): RankedItem[];
+    /**
+     * RRF 融合多个排序列表
+     *
+     * @param ranked 排序列表数组
+     * @param weights 每个列表的权重
+     * @param k RRF 常数 (默认 60)
+     * @returns 融合后的排序列表
+     *
+     * RRF 公式: score = Σ(weight[i] / (k + rank[i] + 1))
+     *
+     * 优势:
+     * - 不依赖原始 score 的绝对值
+     * - 只看排名位置，更鲁棒
+     * - 自动处理不同尺度的 scores
+     */
+    static rrfFuse(ranked: Array<Array<{
+        id: string;
+        score: number;
+    }>>, weights: number[], k?: number): Array<{
+        id: string;
+        score: number;
+    }>;
+    /**
+     * 质量加权倍数
+     *
+     * 规则:
+     * - Entity: 1 + (facts.length + sources.length) * 0.1
+     * - Concept: 1 + (related.length + sources.length) * 0.1
+     *
+     * 范围: [1.0, ~3.0]
+     */
+    static qualityMultiplier(id: string, kb: KnowledgeBase): number;
+    /**
+     * 余弦相似度
+     *
+     * 公式: cos(θ) = (A · B) / (||A|| * ||B||)
+     *
+     * 其中:
+     * - A · B 是点积
+     * - ||A|| 和 ||B|| 是向量的模(长度)
+     *
+     * 返回值范围: [-1, 1]
+     * - 1: 完全相同
+     * - 0: 正交(无关)
+     * - -1: 完全相反
+     */
+    static cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+    /**
+     * 为 Entity 生成上下文文本
+     *
+     * 格式: "Entity [type]: name. [aliases]. [facts]."
+     *
+     * 示例: "Entity [tool]: TypeScript. Also known as: TS. TypeScript is a typed superset of JavaScript."
+     */
+    static contextualTextForEntity(e: Entity): string;
+    /**
+     * 为 Concept 生成上下文文本
+     *
+     * 格式: "Concept: name. [definition]. [related]."
+     *
+     * 示例: "Concept: Domain-Driven Design. A software design approach... Related to: Aggregate, Entity."
+     */
+    static contextualTextForConcept(c: Concept): string;
+    /**
+     * 构建 Embedding 索引
+     *
+     * 流程:
+     * 1. 遍历所有 Entities
+     * 2. 为每个 Entity 生成 contextual text
+     * 3. 检查缓存 (基于 sourceText)
+     * 4. 如果缓存命中，使用缓存；否则调用 provider
+     * 5. 更新缓存
+     * 6. 对 Concepts 重复 1-5
+     *
+     * @returns Map<id, vector> - Entity id 或 "concept:{id}"
+     */
+    static buildEmbeddingIndex(args: BuildEmbeddingIndexArgs): Promise<Map<string, number[]>>;
+    /**
+     * 创建空缓存
+     */
+    static createEmbeddingCache(): EmbeddingCache;
+    /**
+     * 加载缓存 (从 JSON)
+     */
+    static loadEmbeddingCache(json: string): EmbeddingCache;
+    /**
+     * 保存缓存 (到 JSON)
+     */
+    static saveEmbeddingCache(cache: EmbeddingCache): string;
+}

package/dist/types/internal/domain/wiki/value-object/source-record.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SourceRecord Value Object
+ *
+ * 源文件记录
+ */
+export type SourceOrigin = 'user-note' | 'daily';
+export declare class SourceRecord {
+    readonly path: string;
+    readonly summary: string;
+    readonly date: Date;
+    readonly mtime: number;
+    readonly origin: SourceOrigin;
+    readonly contentHash: string;
+    constructor(path: string, summary: string, date: Date, mtime: number, origin: SourceOrigin, contentHash: string);
+    toJSON(): any;
+    static fromJSON(data: any): SourceRecord;
+}

package/dist/types/internal/domain/wiki/value-object/wiki-config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Wiki 配置
+ *
+ * 集中管理所有 wiki 相关的路径和设置
+ *
+ * 设计原则：
+ * - kbPath / embeddingsPath：项目数据文件名（相对），由 Project 实体解析为绝对路径
+ * - wikiDir：Wiki 页面输出目录（绝对路径，由外部传入，不从环境变量读取）
+ * - 其余子目录均从 wikiDir 派生
+ */
+export interface WikiConfig {
+    kbPath: string;
+    embeddingsPath: string;
+    wikiDir: string;
+    entitiesDir: string;
+    conceptsDir: string;
+    sourcesDir: string;
+    conversationsDir: string;
+    indexFile: string;
+    glossaryFile: string;
+    logFile: string;
+}
+/**
+ * 默认文件名常量（只描述文件结构，不包含路径）
+ */
+export declare const WIKI_KB_FILENAME = "kb.json";
+export declare const WIKI_EMBEDDINGS_FILENAME = "embeddings.json";
+export declare const WIKI_SUBDIR = "wiki";
+/**
+ * 根据 wikiDir 创建完整 WikiConfig
+ *
+ * wikiDir 必须由调用方显式传入（如 project 的 outputDir 配置）
+ * kbPath / embeddingsPath 为文件名，由 Project 实体解析为绝对路径
+ */
+export declare function createWikiConfig(wikiDir: string): WikiConfig;
+/**
+ * 默认 WikiConfig（用于测试或默认场景）
+ * wikiDir 使用占位符，实际使用时应调用 createWikiConfig
+ */
+export declare const DEFAULT_WIKI_CONFIG: WikiConfig;

package/dist/types/internal/domain/wiki/value-object/wiki-index-generator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Wiki Index Generator
+ *
+ * 负责生成索引页和词汇表
+ */
+import { KnowledgeBase } from '../entity/knowledge-base';
+export declare class WikiIndexGenerator {
+    private kb;
+    constructor(kb: KnowledgeBase);
+    /**
+     * 生成主索引页面
+     */
+    generateIndex(): string;
+    /**
+     * 生成词汇表
+     */
+    generateGlossary(): string;
+    /**
+     * 获取 Source 文件名（使用父目录-文件名格式）
+     */
+    private getSourceFilename;
+    /**
+     * 截断文本
+     */
+    private truncate;
+    /**
+     * 文件名清理（保留用于可能的其他用途）
+     * 使用中划线替换特殊字符，保持全局风格统一
+     */
+    private sanitizeFilename;
+}

package/dist/types/internal/domain/wiki/value-object/wiki-page-renderer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Wiki Page Renderer
+ *
+ * 负责将领域实体渲染为 Markdown 页面
+ */
+import { KnowledgeBase, Entity, Concept, SourceRecord } from '../entity/knowledge-base';
+export declare class WikiPageRenderer {
+    private kb;
+    private annotator;
+    constructor(kb: KnowledgeBase);
+    /**
+     * 渲染实体页面
+     */
+    renderEntityPage(entity: Entity): string;
+    /**
+     * 渲染概念页面
+     */
+    renderConceptPage(concept: Concept): string;
+    /**
+     * 渲染来源页面
+     *
+     * @param source 源记录
+     * @param originalContent 可选的原文内容（如果提供，将生成带标注的版本）
+     */
+    renderSourcePage(source: SourceRecord, originalContent?: string): string;
+    /**
+     * 获取 Source 文件名（使用父目录-文件名格式）
+     */
+    private getSourceFilename;
+    /**
+     * 查找与实体相关的概念
+     */
+    private findRelatedConcepts;
+    /**
+     * 查找与概念相关的实体
+     */
+    private findRelatedEntities;
+    /**
+     * URL 转义
+     */
+    private escapeUrl;
+}

package/dist/types/internal/domain/workspace/entity/authentication.d.ts

@@ -1,11 +1,40 @@
+/**
+ * Authentication Entity
+ *
+ * 管理 workspace 中的认证文件（token 等）
+ * 专注于文件系统层面的操作，不包含登录等业务逻辑
+ *
+ * 职责：
+ * - 管理认证文件的存储路径
+ * - 提供文件读写接口
+ * - 维护文件生命周期
+ */
 export declare class Authentication {
     private workspacePath;
     private hasAuthFile;
     constructor(workspacePath: string, hasAuthFile?: boolean);
+    /**
+     * Get workspace path
+     */
     getWorkspacePath(): string;
+    /**
+     * Check if auth file exists
+     */
     hasAuth(): boolean;
+    /**
+     * Mark auth file as existing
+     */
     markAuthExists(): void;
+    /**
+     * Mark auth file as deleted
+     */
     markAuthDeleted(): void;
+    /**
+     * Get auth file path (relative to workspace)
+     */
     getAuthFilePath(): string;
+    /**
+     * Get server config file path (relative to workspace)
+     */
     getServerConfigPath(): string;
 }