@mdfriday/foundry 26.5.1 → 26.5.2

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

@@ -8,13 +8,22 @@
  * - 协调依赖，不包含业务逻辑
  * - 配置在创建时一次性传入，避免重复
  */
-import { KnowledgeBase, WikiFactory, ConversationMetadata } from '../domain/wiki';
+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 可选配置（用于覆盖默认值）
@@ -22,7 +31,13 @@ export interface IngestOptions {
 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 结果
  */
@@ -155,6 +170,7 @@ export declare class WikiService {
      * 使用 LLM 流式生成答案
      * 使用配置的默认值，允许可选覆盖
      * 委托给 KB 的 queryStream 方法
+     * 通过 options.onTokenUsage 回调上报 token 使用量
      */
     queryStream(question: string, options?: QueryOptions): AsyncGenerator<string, void, unknown>;
     /**
@@ -169,6 +185,27 @@ export declare class WikiService {
      * 调用聚合根的 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
      *

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

@@ -15,6 +15,7 @@ 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';
+import type { TokenUsage } from '../value-object/token-usage';
 export { Entity, Concept, Connection, SourceRecord, OperationLog };
 export declare class KnowledgeBase {
     private _entities;
@@ -139,6 +140,14 @@ export declare class KnowledgeBase {
         outputLanguage?: string;
         fileSystem: IFileSystem;
         crypto: ICryptoService;
+        /** LLM token 使用量回调：提取完成后触发精确值（isEstimate: false） */
+        onIngestTokenUsage?: (usage: TokenUsage) => void;
+        /**
+         * 实时流式进度回调：每个 chunk 到达时触发，携带累计 completionTokens 估算值。
+         * 提供此回调时，ingestFromSource 改用流式 complete()，实现逐 chunk 实时上报。
+         * 估算方法与 queryStream 一致（约 3 字符 / token）。
+         */
+        onIngestProgress?: (estimatedCompletionTokens: number) => void;
     }): Promise<{
         success: boolean;
         extractedEntities: number;
@@ -201,6 +210,8 @@ export declare class KnowledgeBase {
         embeddingModel?: string;
         temperature?: number;
         maxResults?: number;
+        /** Embedding token 使用量回调：query embedding 完成后调用 */
+        onEmbeddingUsage?: (usage: TokenUsage) => void;
     }): Promise<{
         entities: Array<{
             id: string;
@@ -251,6 +262,8 @@ export declare class KnowledgeBase {
         model: string;
         cachePath: string;
         fileSystem: IFileSystem;
+        /** 每次 embedding 调用完成后的 token 使用量回调（累计上报） */
+        onEmbeddingUsage?: (usage: TokenUsage) => void;
     }): Promise<void>;
     /**
      * 保存 Embedding Index 缓存
@@ -280,6 +293,7 @@ export declare class KnowledgeBase {
      * Query Stream - 流式返回
      *
      * Domain 方法：使用内部 EmbeddingIndex
+     * 通过 onTokenUsage 回调实时上报 token 使用量（属于 wiki domain 业务概念）
      */
     queryStream(question: string, dependencies: {
         llmProvider: ILLMProvider;
@@ -288,5 +302,9 @@ export declare class KnowledgeBase {
         embeddingModel?: string;
         temperature?: number;
         maxResults?: number;
+        /** LLM token 使用量回调：在 LLM stream 完成时调用 */
+        onTokenUsage?: (usage: TokenUsage) => void;
+        /** Embedding token 使用量回调：query embedding 完成后调用 */
+        onEmbeddingUsage?: (usage: TokenUsage) => void;
     }): AsyncGenerator<string, void, unknown>;
 }

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

@@ -12,6 +12,8 @@ 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 './value-object/token-usage';
+export * from './value-object/pricing';
 export * from './entity/entity';
 export * from './entity/concept';
 export * from './entity/connection';

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

@@ -4,9 +4,17 @@
  * Domain 层定义的 Embedding 服务接口
  * Infrastructure 层提供具体实现
  */
+import type { TokenUsage } from '../value-object/token-usage';
+export type { TokenUsage };
 export interface IEmbeddingProvider {
     /**
      * Generate embedding vector for text
+     *
+     * @param text    输入文本
+     * @param model   模型名称
+     * @param onUsage 可选回调：embedding 完成后携带 token 使用量
+     *                （promptTokens = 输入 token 数，completionTokens = 0，
+     *                  totalTokens = promptTokens，由 infrastructure 层填充）
      */
-    generateEmbedding(text: string, model: string): Promise<number[]>;
+    generateEmbedding(text: string, model: string, onUsage?: (usage: TokenUsage) => void): Promise<number[]>;
 }

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

@@ -4,6 +4,8 @@
  * Domain 层定义的 LLM 服务接口
  * Infrastructure 层提供具体实现
  */
+import type { TokenUsage } from '../value-object/token-usage';
+export type { TokenUsage };
 export interface LLMOptions {
     model: string;
     temperature?: number;
@@ -13,6 +15,8 @@ export interface LLMOptions {
 export interface LLMStreamChunk {
     text: string;
     done: boolean;
+    /** Token 使用量统计，由 provider 在最终 chunk 中填充（若 API 支持） */
+    usage?: TokenUsage;
 }
 export interface ILLMProvider {
     /**
@@ -21,8 +25,10 @@ export interface ILLMProvider {
     complete(prompt: string, options: LLMOptions, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
     /**
      * Synchronous completion (wait for full response)
+     *
+     * @param onUsage 可选：LLM 响应完成后，携带本次调用的 token 使用量（由 infrastructure 填充）
      */
-    completeSync(prompt: string, options: LLMOptions, signal?: AbortSignal): Promise<string>;
+    completeSync(prompt: string, options: LLMOptions, signal?: AbortSignal, onUsage?: (usage: TokenUsage) => void): Promise<string>;
     /**
      * Health check
      */

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

@@ -0,0 +1,64 @@
+/**
+ * Wiki Pricing Value Objects & Service
+ *
+ * Domain 层定义的模型定价数据和费用计算逻辑。
+ * 属于 wiki domain 的业务概念：用户通过消耗的 token 数量估算实际成本。
+ *
+ * 价格来源：各厂商官网公布的按量计费价格（2024-2025）。
+ * 本地模型（ollama / lmstudio）费用为 0。
+ */
+export interface ModelPricing {
+    provider: string;
+    model: string;
+    /** 每 1M 输入 token 的价格（USD） */
+    inputPer1M: number;
+    /** 每 1M 输出 token 的价格（USD） */
+    outputPer1M: number;
+    /** 每 1M 缓存读取 token 的价格（USD），可选 */
+    cacheReadPer1M?: number;
+    /** 每 1M 缓存写入 token 的价格（USD），可选 */
+    cacheWritePer1M?: number;
+    currency: 'USD';
+    /** 本地运行模型，费用为 0 */
+    isLocal?: boolean;
+}
+export interface CostBreakdown {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** 输入部分费用（USD） */
+    inputCost: number;
+    /** 输出部分费用（USD） */
+    outputCost: number;
+    /** 总费用（USD） */
+    totalCost: number;
+    currency: 'USD';
+    isLocal: boolean;
+    /**
+     * 是否使用了精确定价数据。
+     * false = 使用了通配符或没有找到精确匹配，费用为估算值。
+     */
+    isExact: boolean;
+}
+export declare const MODEL_PRICING: ModelPricing[];
+/**
+ * 根据 provider + model 查找定价数据。
+ *
+ * 匹配优先级：
+ * 1. 精确匹配 provider + model（忽略大小写）
+ * 2. provider 匹配 + model 通配符 "*"
+ * 3. 未找到返回 undefined
+ */
+export declare function findPricing(provider: string, model: string): ModelPricing | undefined;
+/**
+ * 根据定价数据计算 token 费用。
+ */
+export declare function calculateCost(pricing: ModelPricing, inputTokens: number, outputTokens: number): number;
+/**
+ * 根据 provider + model 名称和 token 数量，返回完整的费用明细。
+ *
+ * 当找不到精确定价时，isExact = false；
+ * 当完全找不到该 provider（含通配符），返回 undefined。
+ */
+export declare function estimateCost(provider: string, model: string, inputTokens: number, outputTokens: number): CostBreakdown | undefined;

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

@@ -0,0 +1,26 @@
+/**
+ * TokenUsage Value Object
+ *
+ * Domain 层定义的 Token 使用量值对象。
+ * 代表一次 LLM 调用中的 token 消耗统计，属于 wiki domain 的业务概念。
+ * 由 LLM infrastructure 层负责从 API 响应中提取并填充，
+ * 通过 onProgress 回调实时传递给上层（如 obsidian interface）。
+ */
+export interface TokenUsage {
+    /** 输入 token 数（prompt + 上下文） */
+    promptTokens: number;
+    /** 输出 token 数（模型生成的内容） */
+    completionTokens: number;
+    /** 总 token 数 = promptTokens + completionTokens */
+    totalTokens: number;
+    /** 当次调用使用的模型名称（可选，由 provider 填充） */
+    model?: string;
+}
+/**
+ * 将两次 TokenUsage 累加合并（多次 LLM 调用的 session 汇总）
+ */
+export declare function mergeTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * 创建空的 TokenUsage（初始状态）
+ */
+export declare function emptyTokenUsage(): TokenUsage;

package/dist/types/internal/infrastructure/embedding/ollama-embedding-provider.d.ts

@@ -14,11 +14,23 @@ export declare class OllamaEmbeddingProvider implements IEmbeddingProvider {
     private config;
     constructor(config: OllamaEmbeddingConfig);
     /**
-     * Domain IEmbeddingProvider interface: generateEmbedding(text, model)
+     * Domain IEmbeddingProvider interface: generateEmbedding(text, model, onUsage?)
      * Bridges the domain contract to the infrastructure embed() method.
      */
-    generateEmbedding(text: string, model: string): Promise<number[]>;
-    embed(request: EmbedRequest): Promise<number[]>;
+    generateEmbedding(text: string, model: string, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<number[]>;
+    embed(request: EmbedRequest & {
+        onUsage?: (usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+            model?: string;
+        }) => void;
+    }): Promise<number[]>;
     embedBatch(texts: string[]): Promise<number[][]>;
     healthCheck(): Promise<boolean>;
 }

package/dist/types/internal/infrastructure/llm/lmstudio-provider.d.ts

@@ -36,16 +36,32 @@ export declare class OpenAICompatibleEmbeddingProvider implements ILLMProvider,
     /** Build Authorization header when an API key is configured. */
     private buildHeaders;
     complete(prompt: string, config: LLMConfig, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
-    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal): Promise<string>;
+    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<string>;
     /**
-     * Domain IEmbeddingProvider contract: generateEmbedding(text, model).
+     * Domain IEmbeddingProvider contract: generateEmbedding(text, model, onUsage?).
      * Bridges to the infrastructure embed() method.
      */
-    generateEmbedding(text: string, model: string): Promise<number[]>;
+    generateEmbedding(text: string, model: string, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<number[]>;
     embed(request: {
         text: string;
         model?: string;
         signal?: AbortSignal;
+        onUsage?: (usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+            model?: string;
+        }) => void;
     }): Promise<number[]>;
     embedBatch(texts: string[]): Promise<number[][]>;
     healthCheck(): Promise<boolean>;

package/dist/types/internal/infrastructure/llm/ollama-provider.d.ts

@@ -12,6 +12,11 @@ export declare class OllamaProvider implements ILLMProvider {
     complete(prompt: string, config: LLMConfig, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
     private completeWithChat;
     private completeWithGenerate;
-    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal): Promise<string>;
+    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<string>;
     healthCheck(): Promise<boolean>;
 }

package/dist/types/internal/infrastructure/llm/openai-compatible-provider.d.ts

@@ -57,7 +57,12 @@ export declare class OpenAICompatibleProvider implements ILLMProvider {
     private httpClient;
     constructor(config: OpenAICompatibleConfig);
     complete(prompt: string, config: LLMConfig, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
-    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal): Promise<string>;
+    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<string>;
     healthCheck(): Promise<boolean>;
 }
 /**

package/dist/types/internal/infrastructure/llm/provider.d.ts

@@ -9,6 +9,13 @@
 export interface LLMStreamChunk {
     text: string;
     done: boolean;
+    /** Token 使用量统计，由 provider 在最终 chunk 中填充（若 API 支持） */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    };
 }
 /**
  * LLM 配置
@@ -34,11 +41,17 @@ export interface ILLMProvider {
     complete(prompt: string, config: LLMConfig, signal?: AbortSignal): AsyncIterable<LLMStreamChunk>;
     /**
      * 非流式完成（等待完整响应）
-     * @param prompt 提示词
-     * @param config LLM 配置
-     * @param signal 取消信号
+     * @param prompt   提示词
+     * @param config   LLM 配置
+     * @param signal   取消信号
+     * @param onUsage  可选：响应完成后携带 token 使用量（由 infrastructure 填充）
      */
-    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal): Promise<string>;
+    completeSync(prompt: string, config: LLMConfig, signal?: AbortSignal, onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        model?: string;
+    }) => void): Promise<string>;
     /**
      * 健康检查
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdfriday/foundry",
-  "version": "26.5.1",
+  "version": "26.5.2",
   "description": "The core engine of MDFriday. Convert Markdown and shortcodes into fully themed static sites – Hugo-style, powered by TypeScript.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",